Support command-specific preprocessor execution (lint vs bundle vs docs)

[vscaiceanu-1a]

Is your feature request related to a problem? Please describe.

As a user developing custom preprocessors for Redocly CLI, I need the ability to run preprocessors only for specific commands (e.g., only during lint, but not during bundle, preview-docs, or build-docs).

Currently, preprocessors defined in redocly.yaml run for all commands that support them. The only way to skip a preprocessor is using the --skip-preprocessor CLI flag, which requires:

• Remembering to add the flag to every command where you don't want the preprocessor
• Maintaining this across multiple npm scripts and CI/CD pipelines
• An opt-out approach instead of opt-in

Use case

I've created a custom preprocessor that filters/modifies schemas from specific paths (e.g., auto-generated files, external vendor schemas, legacy code). This preprocessing is useful only during linting because:

• During bundle: I want the original schemas preserved in the bundled output
• During preview-docs/build-docs: I want the full documentation generated, not filtered content
• During lint: I want to skip validation for specific paths

Current workaround

# Must add --skip-preprocessor to every non-lint command
redocly lint                                                    # preprocessor runs
redocly bundle --skip-preprocessor=my-plugin/my-preprocessor
redocly preview-docs --skip-preprocessor=my-plugin/my-preprocessor
redocly build-docs --skip-preprocessor=my-plugin/my-preprocessor

This is error-prone and requires coordination across teams and CI/CD pipelines.

Describe the solution you'd like

I'd like to understand what options are available to solve this problem:

1. Is the current command already available in the preprocessor context? If so, documentation on how to access it would solve this issue.

2. If not available, could command context be added? For example:

   export const myPreprocessor: Oas3Preprocessor = (options) => {
     return {
       Schema: {
         leave: (schema, ctx) => {
           // Check which command is running
           if (ctx.command !== 'lint') {
             return; // Skip for non-lint commands
           }
           // ... preprocessor logic
         }
       }
     };
   };

3. Alternatively, could command-specific preprocessor configuration be added to redocly.yaml? For example:

   preprocessors:
     my-plugin/my-preprocessor:
       pathPatterns: ['**/generated/**']
       commands: ['lint']  # Only run for lint command

Describe alternatives you've considered

1. CLI flags with npm scripts - Current workaround, but requires maintenance and is error-prone
2. Separate config file for linting - Creates duplication and maintenance overhead

Thank you.

[tatomyr]

@vscaiceanu-1a interesting request!
We don't have the command in the context available AFAIK. Possibly we can add it, but first I'd like you to explore other options.

First, you can leverage the apis section of redocly.yaml to create different setups for specific files, like so:

apis: 
   preprocessed-api:
      root: ./openapiyaml
      preprocessors:
         # your preprocessors go here
...

Then, if you run redocly lint preprocessed-api, it will pick the corresponding preprocessors and apply them to openapi.yaml. However, when running redocly bundle ./openapi.yaml, it will only apply the common configuration.

This approach has a limitation--it allows you to create configuration per-file only (because it is designed to allow granular customisation). So if you want to be able to reuse the same configuration for multiple files, it might be a better option to maintain several config files. To avoid duplication and maintenance overhead (as you rightfully noticed), you can use $refs (like you'd do in an API file) or simply extend one config file from another, i.e.:

config-with-preprocessors.yaml

extends:
- ./redocly.yaml # here's your file with the general configuration
preprocessors:
   # your preprocessors go here

Then, use this one when linting: redocly lint openapi.yaml --config=config-with-preprocessors.yaml to apply preprocessors.

Hope this helps.

[vscaiceanu-1a]

Thank you @tatomyr for the suggestions!

I explored the second option (using extends with separate config files) since we use the apis section extensively in our main configuration, and option 1 would require duplicating configs for each API.

However, I'm running into a schema validation issue when trying to extend a config file that contains the apis section.

Main config (redocly.yaml):

apis:
  petstore:
    root: specs/petstore.yaml
  users:
    root: specs/users.yaml

Extended config (redocly-preprocessed.yaml):

extends:
  - ./redocly.yaml

preprocessors:
  my-plugin/my-preprocessor:
    # preprocessor options

Error when running redocly lint --config redocly-preprocessed.yaml:

[1] redocly.yaml:1:1 at #/apis

Property `apis` is not expected here.

1 | apis:
2 |   petstore:
3 |     root: specs/petstore.yaml

referenced from redocly-preprocessed.yaml:2:5 at #/extends/0 

Warning was generated by the configuration struct rule.

Is there a way to extend a config file that contains apis?

[tatomyr]

@vscaiceanu-1a interesting. First of all, those are warnings by default (unless you configured config linting severity). And the fact that you're getting that errors means you've found a bug (most likely--we'll investigate this). Just to be clear, the apis section is not intended to be inherited.

To bypass this, you have a couple of options again.

1. Extract the 'core' configuration you want to extend from to a separate config file (this includes rules, decorators, preprocessors, and the extends itself if it's there; this is actually what could be actually extended). Then reuse it twice.
2. Use $ref references instead of extends to essentially point to the exact fields you want to reuse.
3. Ignore the config linting warnings for until we fix the linter.

Please let me know if that helps.

@JLekawa We probably have to clarify the config inheritance strategies in our docs.