Separate commands for lint, bundle, decorate

[lornajane]

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

As a user, I know which operations I want to perform, and in what order.

• I want to lint intentionally, not as a side effect of a bundle command
• I want to decorate either before or after linting
• By having the commands as a separate step, I can easily report (for example in CI) which part failed.

Describe the solution you'd like

Additional command redocly decorate and no additional operations (linting, decorating) as side-effects of other operations such as bundle.

We might also need a pre-processor command since that's another step that gets done by bundle.

Describe alternatives you've considered

Multiple config blocks for the same API with different names so that I can run one step and then another for each stage of the process to work around this limitation and try to restrict commands to a single operation at a time.

[lornajane]

@RomanHotsiy @adamaltman @tatomyr opening this for some discussion, would like your thoughts.

[RomanHotsiy]

I want to lint intentionally, not as a side effect of a bundle command

The bundle command doesn't run lint as a side effect. There is a special --lint flag for this. But there is also a separate lint command:

Additional command redocly decorate and no additional operations (linting, decorating) as side-effects of other operations such as bundle.

There is an issue with redocly decorate one.

We don't support decorators on unbundled definition. So decorate right now feels like a natural part of bundle. It will most likely need some efforts to support that. I need to check it.

[lornajane]

Ah, OK. I think it would be great to have it separate if possible. Otherwise how about adding it as an opt-in, like lint? So you can bundle --decorate if you want both operations. Maybe --preprocess fits this as well. (See also: #641 )

[RomanHotsiy]

It may be a bit non-intuitive when using toghether with config, but I'm not sure.

For more context, users can define config like that.

apis:
  api-name@internal:
    root: ./other.yaml
    decorators:
      some-decorator: error

Would it be clear that decorators won't run on bundle unless you add --decorate option?

[lornajane]

I am not sure I'd expect the OpenAPI contents to be altered when running the bundle command, I'd just expect to get everything into a single file. So the decorators, which actually change the contents, are even more of a surprise than the linting. I expect bundle to just bundle. If I wanted to decorate, I'd say so. If we can't do it without bundling as well, I think that's OK, but it should still only happen when specifically requested/expected.

[aviskase]

My team also stumbled upon #1078 after upgrading redocly-cli to the newer version; we expected build-docs to behave like preview-docs (it was like that when we used old redoc-cli bundle command).

As for this feature request, I'd like to add that current combination of commands and available options might be confusing.

Command	Preprocessor?	Lint?	Decorator?
build-docs	NO	NO	NO
bundle	YES, with skips	--lint, by default NO, with skips	YES, with skips
join	--preprocess, by default NO	--lint, by default NO	--decorate, by default NO
lint	YES, with skips	YES, with skips	NO
preview-docs	YES, with skips	NO	YES, with skips

(I might be wrong in some places)

From this table seems like:

• There is no real point in running build-docs with API name from config file. You'd better always target yaml/json file generated by build command. And with that it can use only root theme from config.
• join's default behavior is the same as build-docs, but it can be configured to run all operations
• join doesn't allow skipping unlike all other commands

As for adding decorate and preprocess commands: when you decide whether to use decorator or preprocessor, one of the trade-offs is that content generated by decorator isn't linted. But you can still do "double lint": lint -> bundle -> lint bundled version. Yet, it means you can't use per-api settings from config. Same will happen with the separate preprocess and decorate commands: their outputs will lose "connection" to api from the config, so they won't be truly chain-able.

P.S. for some reason docs for bundling shows that you can use --skip-rule without explicit --lint

[lornajane]

Thanks for this detailed writeup, it's a good summary and I think it's accurate. It's a really good point about the two docs commands as well!

I think there's a lot to be said for a two (or maybe even more) -step process. Bundling with lint, and then applying more linting and/or decorating for another tool's output (such as checking descriptions for docs, or adding metadata for generating SDKs). You could try using multiple configured API aliases - one that points to the original source of truth, and another that points to the bundled output of that, and so on. As you say, there are downsides to this approach, in particular that it can be difficult to map any errors or warnings back to their source.