oxc-project
linter: .oxlintrc.json configuration file improvements
An issue for dumping various ideas on improvements to the .oxlinrc.json configuration_schema.json. These sections can be split into individual issues based on whether the maintainers think they're worthwhile improvements.
Basically, I think it's a much better developer experience if their editor (VS Code, Cursor, IntelliJ, etc) can provide useful information/links about the configuration options and do some basic validation. This is already implemented in many regards, but it's imperfect right now.
Add markdownDescription for everything that has description
VS Code (and thus Cursor and friends) support this for JSON Schemas
Unfortunately there's no current way to do this in the schemars crate as far as I know. But schematic has code already that hacks this into schemars, and they also use schemars v0.8, so it can potentially be reused by oxc?: https://github.com/moonrepo/schematic/blob/d3a9422cead2802b940c96f8ab8b188c86ab281f/crates/schematic/src/schema/renderers/json_schema.rs#L85
The difference in quality of hover info is pretty obvious, before and after using markdownDescription with VS Code:
We still want to keep the description field on all schema elements that have it for editors/other tools which won't recognize markdownDescription. The markdownDescription will always have the same value as the description field, at least for now. In the future we could maybe strip markdown somehow, but not worth the trouble for now.
Generate the configuration schema with embedded documentation for each rule
This may be difficult, but it seems possible? Basically, when I hover over a rule, it should be able to display the docs defined from the declare_oxc_lint! macro. Or at the very least, it should link to the documentation page for each rule. This would only support the built-in rules, no js plugin rules obviously.
Right now it just displays this for every rule:
Improved validation/enforcement of valid values
I think this was better in previous versions, but there have been regressions in the validation with the emitted json schema See this comment for an example: https://github.com/oxc-project/oxc/pull/12117#issuecomment-3483329249
Basically, we should be able to have validation in-editor like this:
Add tests for the configuration_schema.json to ensure regressions do not occur
Moved this section to its own issue in #15468
To ensure the validations don't break in the future, we may want to consider a simple CI script to validate example JSON files that should fail to validate? e.g. an .oxlintrc.json file with an invalid plugins value or invalid categories value. Not everything can be validated, such as the jsPlugins array, but some parts can be, and we should ensure we keep it working for end-users via some basic tests. We could potentially run these tests via JavaScript with ajv? Although there is presumably an equivalent for Rust we could use.
Is there a way to have env work like plugins and categories? I'm not entirely sure where the env values come from right now, but the JSON Schema doesn't provide any possible values for it, so you don't get any editor help at all.
Also because we share the AllowWarnDeny type for both rules and categories, this happens, which looks goofy:
It feels messy to duplicate the whole class/schema just to fix the weird description here, but I'm not sure of a better way to do it.
Also, this is technically allowed and works fine, but the schema says it won't work:
@camc314 before I explore it further, do you have any concerns with the markdownDescription change idea here?