Implement Rule

new_category: Correctness    # → Category module: correctness, style, performance, portability, security
new_code: C001               # → Rule code used in registry
shellcheck_code: SC2034       # → ShellCheck mapping for suppression
description: ...              # → What the rule detects
examples:                     # → Test cases to base the fixture on

declare_rules! {
    ("C001", Category::Correctness, Severity::Warning, UnusedAssignment),
    // Add new rule here in code-sorted order
    ("C003", Category::Correctness, Severity::Warning, NewRuleName),
    ...
}

"SH-NNN" => Some(Rule::NewRuleName),

(NNNN, Rule::NewRuleName),  // SCNNNN

crates/shuck-linter/src/rules/{category}/
├── mod.rs

pub mod correctness;
pub mod style;  // new category

#[cfg(test)]
mod tests {
    use std::path::Path;

    use test_case::test_case;

    use crate::{LinterSettings, Rule, assert_diagnostics};
    use crate::test::test_path;

    #[test_case(Rule::NewRuleName, Path::new("C003.sh"))]
    fn rules(rule: Rule, path: &Path) -> anyhow::Result<()> {
        let snapshot = format!("{}_{}", rule.code(), path.display());
        let (diagnostics, source) = test_path(
            Path::new("{category}").join(path).as_path(),
            &LinterSettings::for_rule(rule),
        )?;
        assert_diagnostics!(snapshot, diagnostics, &source);
        Ok(())
    }
}

use crate::{Checker, Rule, Violation};

pub struct RuleName {
    // Fields that provide context for the diagnostic message.
    // Common: `name: String` for variable names.
    // Use no fields if the message is always the same (preferred).
}

impl Violation for RuleName {
    fn rule() -> Rule {
        Rule::RuleName
    }

    fn message(&self) -> String {
        // Concise, lowercase message describing the violation.
        "description of what's wrong".to_owned()
    }
}

pub mod rule_name;

pub fn read_without_raw(checker: &mut Checker) {
    let spans = checker
        .facts()
        .structural_commands()                              // iterator over CommandFact
        .filter(|fact| fact.effective_name_is("read"))      // normalized name (unwraps env/command/sudo)
        .filter(|fact| {
            fact.options()
                .read()                                     // pre-parsed ReadCommandFacts
                .is_some_and(|read| !read.uses_raw_input)
        })
        .filter_map(|fact| fact.body_name_word().map(|word| word.span))
        .collect::<Vec<_>>();

    checker.report_all(spans, || ReadWithoutRaw);
}

pub fn find_output_to_xargs(checker: &mut Checker) {
    let spans = checker
        .facts()
        .pipelines()                                        // &[PipelineFact]
        .iter()
        .flat_map(|pipeline| unsafe_find_to_xargs_spans(checker, pipeline))
        .collect::<Vec<_>>();

    checker.report_all_dedup(spans, || FindOutputToXargs);
}

fn unsafe_find_to_xargs_spans(checker: &Checker<'_>, pipeline: &PipelineFact<'_>) -> Vec<Span> {
    pipeline.segments().windows(2).filter_map(|pair| {
        let left = checker.facts().command_for_stmt(pair[0].stmt())?;   // cross-reference
        let right = checker.facts().command_for_stmt(pair[1].stmt())?;

        if !pair[0].effective_name_is("find") || !pair[1].effective_name_is("xargs") {
            return None;
        }
        if left.options().find().is_some_and(|f| f.has_print0)
            && right.options().xargs().is_some_and(|x| x.uses_null_input) {
            return None;  // null-delimited pair is safe
        }
        Some(left.body_span())
    }).collect()
}

pub fn find_output_loop(checker: &mut Checker) {
    let spans = checker
        .facts()
        .for_headers()                                      // &[ForHeaderFact]
        .iter()
        .flat_map(|header| header.words().iter())
        .filter(|word| word.contains_find_substitution())   // pre-computed
        .map(|word| word.span())
        .collect::<Vec<_>>();

    checker.report_all(spans, || FindOutputLoop);
}

pub fn constant_comparison_test(checker: &mut Checker) {
    let spans = checker
        .facts()
        .commands()
        .iter()
        .filter(|fact| {
            fact.simple_test().is_some_and(simple_test_is_constant)     // SimpleTestFact
                || fact.conditional().is_some_and(conditional_is_constant) // ConditionalFact
        })
        .map(|fact| fact.span())
        .collect::<Vec<_>>();

    checker.report_all(spans, || ConstantComparisonTest);
}

pub fn sudo_redirection_order(checker: &mut Checker) {
    let spans = checker
        .facts()
        .commands()
        .iter()
        .filter(|fact| fact.has_wrapper(WrapperKind::SudoFamily))
        .flat_map(|fact| {
            fact.redirect_facts().iter().filter_map(|redirect| {
                (redirects_output(redirect.redirect().kind)
                    && !redirect.analysis()
                        .is_some_and(|a| a.is_definitely_dev_null()))
                .then(|| redirect.target_span()).flatten()
            })
        })
        .collect::<Vec<_>>();

    checker.report_all_dedup(spans, || SudoRedirectionOrder);
}

// Access via checker.facts().backtick_fragments(), .single_quoted_fragments(), etc.

// Access via checker.facts().word_facts(), .expansion_word_facts(context), .case_subject_facts()

pub fn unused_assignment(checker: &mut Checker) {
    for &binding_id in checker.semantic().unused_assignments() {
        let binding = checker.semantic().binding(binding_id);

        if !is_reportable(binding.kind, binding.attributes) { continue; }
        if binding.attributes.contains(BindingAttributes::EXPORTED) { continue; }
        if matches!(binding.kind, BindingKind::Nameref) { continue; }

        checker.report(
            UnusedAssignment { name: binding.name.to_string() },
            binding.span,
        );
    }
}