Implement Fix

Implement a Lint Fix

This skill turns an existing rule into a fixable rule: it attaches a Fix to each diagnostic, sets the right FixAvailability and applicability, adds tests that prove the rewrite is correct, and runs the conformance corpus to make sure the fix doesn't shift parity numbers.

The reference implementation is S074 / AmpersandSemicolon at crates/shuck-linter/src/rules/style/ampersand_semicolon.rs. Read it first if anything below is unclear — it covers every moving part end-to-end.

Before you start

Read these files:

1. docs/rules/{CODE}.yaml — the YAML metadata. It tells you whether the fix is safe and what the edit should do.
2. The current rule file (crates/shuck-linter/src/rules/{category}/{rule_name}.rs).
3. crates/shuck-linter/CLAUDE.md — the layered architecture and the "Authoring fixes" section. The skill summarizes it but the source is canonical.
4. crates/shuck-linter/src/fix.rs — the shared Edit, Fix, Applicability, FixAvailability primitives.
5. crates/shuck-linter/src/rules/style/ampersand_semicolon.rs — the reference implementation, including its tests.

If the rule lacks a fix_description in YAML, stop and ask the user — the metadata is the source of truth and an absent fix description means the design work hasn't been done yet.

Step 1: Read the YAML metadata

new_code: S074
safe_fix: true                        # → Applicability::Safe (use Fix::safe_edit)
fix_description: "Delete the …"       # → describes what the edit must do

Two fields drive everything:

The YAML is authoritative. Do not override safe_fix based on your own judgment — if the metadata says safe, implement safe; if it says unsafe, implement unsafe. If you genuinely think the metadata is wrong, raise it with the user before changing the rule.

Step 2: Find the exact span the edit acts on

Open the rule file. The first question, lifted from crates/shuck-linter/CLAUDE.md:

Do we already have an exact span for the token/text we want to edit?

There are three cases:

1. The rule already collects the span it would edit. Most fix-friendly rules do — they report at the span they want to delete or replace (e.g. S074 reports the ; itself). Skip to Step 4.
2. The rule has the diagnostic span but the edit needs a different span. For example, the diagnostic points at a command but the fix wants to delete a single flag. Check whether the corresponding fact already exposes the edit span (option spans, redirect spans, word spans, etc.). If yes, thread it through. Skip to Step 4.
3. No layer exposes the span. Go to Step 3 and add it to facts first.

Do not rediscover the edit span from raw source inside the rule file. Rule files cannot scan source, walk AST, or rebuild structure — the architecture test in src/rules/mod.rs enforces this.

Step 3: Extend facts (only if Step 2 needs it)

When the existing facts don't expose the edit span:

1. Pick the right fact type in crates/shuck-linter/src/facts.rs (or one of the submodules under src/facts/). Almost always one of: CommandFact, RedirectFact, SubstitutionFact, WordFact, PipelineFact, SimpleTestFact, ConditionalFact, or one of the option-shape facts under CommandOptionFacts.
2. Add the new span/method, populate it inside LinterFacts::build (or the relevant builder), and re-export any rule-facing types from the crate root if needed.
3. Add fact-layer tests for the new field if the existing coverage doesn't already exercise it.
4. Then return to Step 4 and consume the new fact field from the rule.

If you find yourself wanting to add a one-off helper that only this rule will ever use, that's a yellow flag — facts are shared by design, so the data should be useful to other rules too. If it really is one-off, still build it in facts; the architecture test will reject it in the rule file.

Step 4: Update the Violation impl

Three changes:

use crate::{Checker, Edit, Fix, FixAvailability, Rule, Violation};

impl Violation for AmpersandSemicolon {
    const FIX_AVAILABILITY: FixAvailability = FixAvailability::Always;  // or Sometimes

    fn rule() -> Rule { Rule::AmpersandSemicolon }

    fn message(&self) -> String { "...".to_owned() }

    fn fix_title(&self) -> Option<String> {
        Some("remove the stray `;` after `&`".to_owned())
    }
}

Picking FIX_AVAILABILITY:

If you set Always you must actually attach a fix to every diagnostic the rule emits. If any path emits a bare diagnostic, downgrade to Sometimes.

Picking fix_title(): a short imperative phrase describing the edit, in the voice of "what shuck will do for you" (e.g. "remove the stray ; after &"). It should not duplicate the diagnostic message. The YAML fix_description is a useful starting point but tighten it for terminal output.

Step 5: Switch the rule body to attach the fix

Replace the report* call with a report_diagnostic* call that builds a Diagnostic and attaches a Fix:

pub fn ampersand_semicolon(checker: &mut Checker) {
    let spans = checker.facts().background_semicolon_spans().to_vec();
    for span in spans {
        checker.report_diagnostic_dedup(
            crate::Diagnostic::new(AmpersandSemicolon, span)
                .with_fix(Fix::safe_edit(Edit::deletion(span))),
        );
    }
}

Two API points to know:

• Checker::report_diagnostic(diagnostic) and report_diagnostic_dedup(diagnostic) accept a fully built Diagnostic. Use these (not report / report_dedup) whenever you want to attach a fix.
• Diagnostic::new(violation, span).with_fix(fix) is the standard builder. Prefer this over reaching into Diagnostic fields directly.

Edit primitives (from src/fix.rs):

Fix primitives:

A single fix can carry multiple edits — keep them tightly related and non-overlapping. The shared fixer in src/fix.rs handles deconflicting and ordering across diagnostics; you do not.

For FixAvailability::Sometimes: branch in the rule body — attach the fix only on the path where it's safe to apply, and emit a bare Diagnostic::new(...) on the other paths.