add-lint-rule

name	add-lint-rule
description	Add a new built-in lint rule to the fatou linter—implement it against the single-walk dispatch, register it in the one source of truth, add TDD behavior tests (plus autofix coverage when the rule ships a fix), and wire up the snapshot-pinned generated rule reference.

Use this skill when asked to add a new built-in lint rule (correctness, suspicious, ...), whether or not it ships an auto-fix. The roadmap of planned rules lives in TODO.md under "Linter" → "Rules"—when the request names a roadmap item, follow its annotation and check the item off when done. A roadmap item that names blocking infrastructure needs that infrastructure first; don't fake it with a heuristic unless the entry explicitly sanctions one (e.g. index-from-length's name-based match).

Tenets that constrain a rule (from AGENTS.md)

• The linter is purely semantic. Pure layout (spacing, indentation, line breaks, operator spelling) is the formatter's job—any check format --check could perform is out of scope for the linter (see the module doc of src/linter/rules.rs).
• Parsing is the parser's job. Do not paper over parser mistakes in a rule. If the CST does not expose what you need, extend the typed AST wrappers in crates/fatou-parser/src/ast/ (see "Parser and typed AST" in AGENTS.md: ast_node!/ ast_token! entry, support::* accessors, Has* trait impls, re-export from crates/fatou-parser/src/ast.rs, accessor unit test) rather than re-lexing or kind-matching raw CST inside the rule.
• A lint fix is a textual edit, never a formatter. Applying the fix must leave code that still parses and stays lossless (no misbinding, no dropped comments). Make the edit correct by construction (tight span, whitespace-preserving), or withhold the fix for that shape (still report the finding). A fix does not owe line width or canonical layout—the pipeline is fix-then-format and --fix never runs the formatter.

Cost model (drives which infra you may touch)

Three tiers; prefer the cheapest the rule's correctness actually requires.

• syn — the CST plus typed AST wrappers and literal inspection.
• sem — the SemanticModel (ctx.model: scopes, bindings, occurrences, imports, module paths).
• res — name resolution: what an identifier actually means (Base/stdlib methods, imported symbols). Available through RuleContext: resolver(), resolves_to_base(), read_resolves_to_base(), name_resolves_to_base(), base_export_module(), and trusts_resolution() as the gate for "is a resolution context even present". Each is memoized per file, so asking is cheap however many rules do.

A res-tier rule carries two extra obligations. It is sound only with a project-wide resolution context, so it must (a) report nothing when trusts_resolution() is false, rather than guessing, and (b) be listed in RESOLUTION_RULES (src/linter/rules.rs) and ship default_enabled() -> false. That one list is what the CLI's harvest gate, the language server's member-file rule set, and outdated-suppression all read; adding a resolution rule without it means the CLI never harvests for it and it silently misfires.

Key files

• src/linter/rules.rs—the Rule trait, RuleContext, all_rules(), the single source of truth, and RESOLUTION_RULES. all_rule_ids() derives from all_rules(), so there is no second list to sync. Every new rule is added here exactly once.
• src/linter/rules/<category>.rs—the category module. The vocabulary is correctness/suspicious/performance/readability/meta; all five exist. Holds mod <id>; + pub use <id>::<Name>;.
• src/linter/rules/<category>/<id>.rs—one file per rule: a unit pub struct implementing Rule, with a module doc comment. (File names are snake_case; the public id stays kebab-case.)
• crates/fatou-parser/src/ast/ (nodes.rs, tokens.rs, traits.rs, re-exported from crates/fatou-parser/src/ast.rs)—typed wrappers (CallExpr, IfExpr, Condition, BinaryExpr, the Expr sum, Ident/Operator tokens, Has* traits). Prefer these over raw children()/kind() matching; grow them when a shape is missing.
• src/linter/rules/matchers.rs—shared call-shape matching, one tier above the AST wrappers. plain_call(node, name, arity) is the whole "a call to name with exactly n positional arguments and nothing else" opening most idiom rules need; CallShape::of(&call) is the full split when the rule needs keyword arguments (both sides of the ;, plus the f(; verbose) shorthand) or has to know that a splat left the positional or keyword set open. call_named/call_expr exclude a definition's signature, which is a CALL_EXPR too. Do not re-derive Julia's argument grammar in a rule—grow this module instead. Shape matching is only half the job: follow it with before claiming the callee is Base's.

Workflow

1. Pick the rule id (kebab-case). This is the public id(), the --select/--ignore/[lint.severity] key, and the docs slug—unique and stable; renaming is a breaking change. Match existing tone (unused-binding, assignment-in-condition). The roadmap entry usually fixes the id already.

2. Decide gating and safety before writing code:

   • Category = directory only: correctness (the code cannot do what it says), suspicious (legal Julia, very likely not intended), performance (a rewrite that avoids real work), readability (an idiom rewrite that is behavior-preserving), meta (a finding about a # fatou-ignore directive rather than about the Julia). It appears in no public surface—not the id, not the --select/--ignore/[lint.severity]/# fatou-ignore key, and not the reference, which is one page keyed by id—so it is a free refactor later. Pick the fitting one and move on.
   • Severity—override default_severity() (the default is Warning; Error only for code that cannot run, e.g. duplicate-argument). Never set severity on the Diagnostic—the engine stamps it, honoring the user's [lint.severity] override.
   • default_enabled()—default true; override to false for noisy opt-in rules and for every res-tier rule (see the cost model).
   • Dispatch shape—node-shape rules declare interests() (a slice of SyntaxKind) and implement check(el, ctx, sink), called once per matching element in the one shared descendants_with_tokens() walk (tokens included, so token kinds may be subscribed too). Model-driven rules leave interests() empty and override check_file(ctx, sink) (a once-per-file pass). Never walk the whole CST yourself from a node-shape rule; walking within the dispatched subtree is fine.
   • —ship only when the edit is unambiguous and parse-clean by construction; otherwise (applied only under ), or withhold the fix entirely and still report.

Dos and don'ts

• Do reach for the typed AST wrappers before raw CST walking; grow crates/fatou-parser/src/ast/ when a shape is missing (with its own accessor test).
• Do keep spans tight and fixes parse-clean/lossless by construction, or withhold the fix and still report.
• Do make examples() snippets that genuinely trigger the rule—the docs tests reject a plausible-but-inert example.
• Don't set severity or path on a Diagnostic—the engine stamps both; override default_severity() instead.
• Don't add a second registration list or an if-guard; all_rules() is the only list.
• Don't implement a formatting/layout preference as a lint rule.
• Don't work around a parser/CST gap inside the rule—fix the parser or extend the AST wrappers instead.
• Don't run the formatter inside a fix, or ship a fix that produces broken or lossy code. A fix needn't satisfy line width—that's the formatter's job.
• Don't hand-edit docs/src/reference/rules.md—regenerate via docgen.

Report-back format

When done, report:

1. Rule id, category, default severity, and whether it ships a safe/unsafe fix (or none).
2. Cost tier (syn/sem) and default_enabled.
3. New files (rule module) and updated files (<category>.rs, rules.rs all_rules(), tests/linter_rules.rs, tests/autofix.rs if fixable, the regenerated docs/src/reference/rules.md + accepted snapshot, TODO.md).
4. Targeted test names, including the false-positive guards and (if fixable) the fix_source case.
5. Full-gate results: cargo test --workspace, clippy -D warnings, cargo fmt --check.