Repository navigation
docs(config): custom-rule docs and the 0.19.0 changelog disagree with the real config schema #678
Description
Problem
Configuring a custom deterministic rule on 0.19.0 took several failed attempts because docs/configuration.md ("Custom Rule Engine") and the 0.19.0 changelog describe a schema that the binary rejects or silently ignores. Found while tuning the rules of a real Rust workspace (cora 0.19.0, cora scan --no-llm).
What the docs/changelog say vs. what happens
| Source says | Actual behaviour on 0.19.0 |
|---|---|
Changelog (#645): "custom rules_engine.custom_rules" |
config parse error: rules_engine: unknown field `custom_rules`, expected one of `enabled`, `max_findings`, `custom`, `index_skip_files`, `include_tests` . The key is rules_engine.custom. |
docs/configuration.md "Custom Rule Engine": top-level rules: is a list of objects (- id: no-unwrap / pattern: ...) |
config parse error: rules[0]: invalid type: map, expected a string. rules: is the list of free-text reviewer instructions; the object form only works under rules_engine.custom. |
Same page, 2nd example (no-console-log) omits exclude |
rules_engine.custom[0]: missing field `exclude` . exclude is required (an empty list is fine). |
Examples use languages: ["rust"] / ["typescript", "javascript"] |
languages takes file extensions. ["rust"], ["Rust"], ["*"] and [] are accepted and the rule then never matches anything, with no message. ["rs"] works. |
Reproduction
# .cora.yaml
rules_engine:
custom:
- id: probe
pattern: "fn a"
severity: major
message: probe
languages: ["rust"] # silently matches nothing
exclude: []printf 'fn a() {}\n' > src/a.rs && cora scan --no-llm reports 0 findings. Changing ["rust"] to ["rs"] reports the rule.
Proposal
- Fix
docs/configuration.mdand the changelog entry: key namecustom,excluderequired,languages= extensions, and thatrules:stays a list of strings. - Make the schema forgiving where it is currently silent: either accept language names and map them to extensions, or reject unknown values in
languagesat config load with a hint ("rust" is not an extension; did you mean "rs"?). - Make
excludeoptional (default[]) or document why it is required.
Done when
- A config copied verbatim from the docs loads and the rule fires on a matching file.
- A
languagesvalue that cannot match any extension is an error or at least a warning.
Activity