redocly-cli
redocly-cli copied to clipboard
Linting by filename lints by alias rules instead
Describe the bug
When linting a named file, rules from an alias are applied, which I didn't expect.
To Reproduce Steps to reproduce the behavior:
- Given this
redocly.yaml
file
extends:
- recommended
apis:
surprise:
root: a.yaml
rules:
tags-alphabetical: error
- And any two identifcal OpenAPI files
a.yaml
andb.yaml
that have tags declared NOT in alphabetical order - Run this command with these arguments...
redocly lint a.yaml
- See the error about alphabetical tags.
- Run the command again for the identical spec:
redocly lint b.yaml
- See no error
Expected behavior
Settings described under an alias in the config file are only used when the alias is used. Being explicit about what is being linted and which rules are applied will make it easier to understand and debug, and allow users to use multiple rulesets for a single API description. This could be useful when upgrading governance standards, or preparing APIs for different pipeline outputs (particularly with different decorators on a common root API description).
OpenAPI 3.1 Redocly 1.0.2 Node 18
Additional context
I spent quite some time debugging a problem, only to realise that I'd used the same file as an API alias further down my config file. It was a surprise that the alias was used when I had specifically tried to lint just the file by itself. The aliases are a great feature, but they should be only applied when the user specifies them.
I believe this is an expected behavior.
This approach is used by many users to adjust rules for specific APIs (and they may not use aliases but direct link or glob pattern) so we can't break it really.
I had wondered if that was a common use case, I guess we don't have glob on aliases or ways to group which aliases should be linted. I can see the convenience for single-pass pipelines, but it's an anti-pattern for more complex use cases. Let's think of some more ways to tackle these needs.
This looks like a good idea for CLI v2 though.
To recap, these are the use cases I think we need to support:
- Lint files by filename
- Lint files by glob to match path to file
- Lint files by alias
- Lint files by alias with wildcard matching
- Multiple lint passes for one file, eg next-level compliance test as well as checking active standard (multiple passes might be more relevant for bundle/decorate but we will need to be consistent between all the commands, I'm just sticking with lint examples).
Configuration for linting can be
- from a config file (with a default setting of
redocly.yaml
) - from command line switches
- from an alias in the config file if an alias is specified on the command line
- from an alias in the config file if a filename is specified (we predictably seem to pick the first entry using this file from the configuration)
Open questions: can alias names include separators such as hyphens, colons or slashes? Could we add glob matches on those keys to serve the lint-all-the-things use case but without surprising users who specified a filename?