fatou 0.12.0

//! Lint rule trait, registry, and per-file dispatch.
//!
//! Rules run over a file in a single shared CST traversal: each rule declares
//! the [`SyntaxKind`]s it cares about via [`Rule::interests`], and
//! [`ResolvedRules::run`] walks the tree once, calling [`Rule::check`] on every
//! element whose kind a rule subscribed to. Rules that work off the whole file rather than node shape
//! (semantic-model queries, comment directives) leave `interests` empty and
//! override [`Rule::check_file`], which runs once per file after the walk.
//! `# fatou-ignore` suppression is filtered inside [`ResolvedRules::run`] too,
//! recording which directives fired for the [`Rule::check_suppressions`]
//! post-pass.
//!
//! The linter is purely *semantic*: any check the formatter's `--check` mode can
//! perform belongs to the formatter, not here (see `AGENTS.md`). Rules consume
//! the [`SemanticModel`] and the CST shape; style is never their concern.
//!
//! A rule's *category* is its directory and nothing else: it appears in no
//! public surface — not the ID, not the `select`/`ignore`/`[lint.severity]`/
//! `# fatou-ignore` key, and not the generated reference, which is one page
//! keyed by ID (see [`crate::linter::docs`]). Recategorizing a rule is
//! therefore a free refactor. The vocabulary is `correctness` (the code cannot
//! do what it says), `suspicious` (legal Julia, very likely not intended),
//! `performance` (a rewrite that avoids real work), and `readability` (a
//! behavior-preserving idiom rewrite); the last two have no rules yet, so
//! their modules are created by the first rule that needs them.
//!
//! New rules:
//! 1. Create a module under `src/linter/rules/<category>/<id>.rs`.
//! 2. Define a unit `pub struct` that implements [`Rule`] — subscribe to node
//!    kinds via `interests` + `check`, or do a whole-file pass via `check_file`.
//!    Build findings with [`Diagnostic::new`]: severity (like the path) is
//!    stamped by the engine — override `default_severity` instead of setting it.
//! 3. Add it to [`all_rules`] below — the single source of truth. The set of
//!    valid rule IDs ([`all_rule_ids`]) is derived from it, so there is no
//!    second list to keep in sync.
//!
//! A rule that asks about a *call's shape* goes through [`matchers`] rather
//! than re-deriving Julia's argument grammar: [`matchers::plain_call`] is the
//! whole "a call to *name* with exactly *n* positional arguments and nothing
//! else" opening, and [`matchers::CallShape`] the full split when a rule needs
//! keywords or has to know which set a splat left open.
//!
//! A rule that asks what a *name* means goes through [`RuleContext`] rather
//! than assembling its own machinery: [`RuleContext::resolver`] for the shared
//! [`Resolver`], [`RuleContext::trusts_resolution`] for the soundness floor,
//! and [`RuleContext::resolves_to_base`] /
//! [`RuleContext::read_resolves_to_base`] for the one question most idiom
//! rules open with — is this callee really the Base/Core function, or a local
//! shadow, a qualified name, or a masked import? Each is computed once per
//! file and memoized, so asking is cheap no matter how many rules do. A rule
//! that asks whether code can *run* goes through
//! [`RuleContext::control_flow`], the same way.

use std::cell::OnceCell;
use std::collections::{BTreeSet, HashMap};
use std::path::Path;
use std::sync::{Arc, LazyLock};

use rowan::{TextRange, TextSize};

use crate::ast::{AstToken, CallExpr, Expr};
use crate::config::{LintConfig, RulesConfig};
use crate::index::PackageIndex;
use crate::julia_version::VersionRange;
use crate::linter::diagnostic::{Diagnostic, Severity};
use crate::linter::include_graph::IncludeProblem;
use crate::linter::suppression::{DirectiveUsage, SuppressionMap};
use crate::resolve::{
    ModulePath, Namespace, PackageSource, Resolution, Resolver, has_unresolvable_using,
};
use crate::semantic::{BindingKind, FileControlFlow, IdentRef, SemanticModel};
use crate::syntax::{SyntaxElement, SyntaxKind, SyntaxNode, SyntaxToken};

pub mod correctness;
mod file_scan;
pub mod matchers;
pub mod readability;
pub mod suspicious;

pub(crate) use file_scan::FileScan;

/// A documented example for a rule: a snippet of Julia that triggers the rule.
///
/// The rule reference is generated by running the real linter on `source`, so
/// the rendered diagnostics stay the single source of truth (see
/// [`crate::linter::docs`]).
pub struct Example {
    /// One-line caption rendered above the snippet (markdown). May be empty.
    pub caption: &'static str,
    /// Julia source that triggers the rule. Should end with a trailing newline.
    pub source: &'static str,
}

/// Every rule the linter knows about — the single source of truth.
pub fn all_rules() -> Vec<Box<dyn Rule>> {
    vec![
        Box::new(correctness::UnusedBinding),
        Box::new(correctness::UnusedImport),
        Box::new(correctness::DuplicateArgument),
        Box::new(correctness::DuplicateKeywordArgument),
        Box::new(correctness::UnusedArgument),
        Box::new(correctness::UndefinedName),
        Box::new(correctness::BreakOutsideLoop),
        Box::new(correctness::ConstLocal),
        Box::new(correctness::GlobalConstInFunction),
        Box::new(correctness::LocalConst),
        Box::new(correctness::NotEqDefinition),
        Box::new(correctness::UnusedTypeParameter),
        Box::new(correctness::MissingIncludeFile),
        Box::new(correctness::IncludeCycle),
        Box::new(correctness::DuplicateInclude),
        Box::new(correctness::DuplicateMethod),
        Box::new(correctness::JuliaVersionCompat),
        Box::new(correctness::CallArity),
        Box::new(correctness::RedefinedConstant),
        Box::new(correctness::TypePiracy),
        Box::new(correctness::UnreachableCode),
        Box::new(suspicious::AssignmentInCondition),
        Box::new(suspicious::NothingComparison),
        Box::new(suspicious::MissingComparison),
        Box::new(suspicious::ConstantCondition),
        Box::new(suspicious::ModuleShadowsParent),
        Box::new(suspicious::LoopVariableShadow),
        Box::new(suspicious::IndexFromLength),
        Box::new(suspicious::DiscouragedFunction),
        Box::new(suspicious::TypeofComparison),
        Box::new(readability::ComparisonNegation),
        Box::new(readability::LengthZero),
        Box::new(readability::RedundantBoolean),
    ]
}

/// Every shipped rule's ID, derived from [`all_rules`] so the two never drift.
/// Used to validate `LintConfig::select` / `ignore` / `severity`.
pub fn all_rule_ids() -> Vec<&'static str> {
    all_rules().iter().map(|r| r.id()).collect()
}

/// [`all_rule_ids`] as a set, built once. `is_shipped_rule` is on the hot path
/// of rendering a large run's findings, so it cannot rebuild the registry (and
/// its boxed rules) per diagnostic.
static SHIPPED_RULE_IDS: LazyLock<BTreeSet<&'static str>> =
    LazyLock::new(|| all_rule_ids().into_iter().collect());

/// Whether `id` names a rule in the registry. False for the pseudo-rules that
/// ride the same diagnostic channel without being registry entries — notably
/// `parse-error`, which has no section in the generated rule reference.
pub fn is_shipped_rule(id: &str) -> bool {
    SHIPPED_RULE_IDS.contains(id)
}

/// The rule IDs running in a pass, after `select`/`ignore`. Lets a rule tell
/// "this rule ran and found nothing" from "this rule never ran" — the
/// distinction between a stale suppression and a dormant one.
#[derive(Debug, Clone, Default)]
pub struct EnabledRules(Vec<&'static str>);

impl EnabledRules {
    pub fn contains(&self, id: &str) -> bool {
        self.0.contains(&id)
    }
}

/// What a rule sees when it runs against one file.
pub struct RuleContext<'a> {
    pub path: Option<&'a Path>,
    pub root: &'a SyntaxNode,
    pub model: &'a SemanticModel,
    /// The name-resolution context, when the caller has one: the harvested
    /// library (Base/Core at minimum) plus the enclosing workspace package.
    /// `None` leaves resolution-dependent rules (`undefined-name`) silent.
    pub resolution: Option<ResolutionContext<'a>>,
    /// This file's include-graph problems, precomputed by the lint driver (see
    /// [`crate::linter::include_graph`]). Empty leaves the include-graph rules
    /// (`missing-include-file`, `include-cycle`) silent — the language server
    /// passes no problems and keeps publishing its own graph diagnostics.
    pub includes: &'a [IncludeProblem],
    /// The project's declared Julia support range, when known (from
    /// `[julia] version`, `Project.toml` `[compat]`, or the CLI). `None` leaves
    /// version-gated rules (`julia-version-compat`) silent. Constant per run —
    /// carried on [`ResolvedRules`] and copied here by the driver.
    pub julia_target: Option<VersionRange>,
    /// The per-rule option tables from `[lint.rules.<id>]`. Like
    /// [`julia_target`](Self::julia_target) this is constant per run: it is
    /// resolved once onto [`ResolvedRules`] and borrowed here by the driver. A
    /// configurable rule reads its own field off it
    /// (`ctx.config.discouraged_function`); a rule with no knobs ignores it.
    pub config: &'a RulesConfig,
    /// The file's parsed `# fatou-ignore` directives. Built once per file by
    /// the driver and used by [`ResolvedRules::run`] to drop suppressed
    /// findings; the future `meta/*-suppression` rules read it to lint the
    /// directives themselves.
    pub suppressions: &'a SuppressionMap,
    /// The rule IDs running in this pass, after `select`/`ignore`. A directive
    /// naming a rule that did not run is dormant, not stale — the distinction
    /// `outdated-suppression` needs.
    pub enabled_rules: &'a EnabledRules,
    /// Per-file answers built on first use and shared by every rule in the run
    /// (see [`RuleCache`]). Private: build a context with
    /// [`RuleContext::new`] and the `with_*` chain.
    cache: RuleCache<'a>,
}

/// The default `[lint.rules]` tables, so [`RuleContext::new`] has something to
/// borrow when the caller attaches no config. Not a `const` because the
/// built-in deny-lists are populated maps.
static DEFAULT_RULES_CONFIG: LazyLock<RulesConfig> = LazyLock::new(RulesConfig::default);

/// A directive-less suppression map for [`RuleContext::new`] to borrow when the
/// caller attaches none. Not a `const` because `HashMap::new` is not.
static EMPTY_SUPPRESSIONS: LazyLock<SuppressionMap> = LazyLock::new(SuppressionMap::default);

/// An empty rule set for [`RuleContext::new`] to borrow when the caller
/// attaches none.
static EMPTY_ENABLED_RULES: EnabledRules = EnabledRules(Vec::new());

/// The per-file work more than one rule needs, computed lazily and at most
/// once: the name [`Resolver`], the [`FileScan`], the unresolvable-`using`
/// verdict, and a range index over the model's reads. Every entry is derived
/// purely from the context's own fields, so caching is invisible to rules —
/// they just ask.
///
/// A [`RuleContext`] lives on one thread for one file ([`SyntaxNode`] is
/// `Rc`-based and not `Send`, so the lint driver parallelizes across files
/// only), which is why a plain [`OnceCell`] suffices.
#[derive(Default)]
struct RuleCache<'a> {
    resolver: OnceCell<Option<Resolver<'a, dyn PackageSource + 'a>>>,
    scan: OnceCell<FileScan>,
    cfg: OnceCell<FileControlFlow>,
    unresolvable_using: OnceCell<bool>,
    /// `model.idents()` keyed by range, so a rule holding a token can ask what
    /// the model made of it without a linear scan per token.
    idents_by_range: OnceCell<HashMap<TextRange, usize>>,
    trusts_resolution: OnceCell<bool>,
}

impl<'a> RuleContext<'a> {
    /// A context over `root` with no resolution context, no include problems,
    /// no Julia target, the default per-rule options, no suppression
    /// directives, and no enabled-rule set — the floor every rule sees. Layer
    /// the optional tiers on with
    /// [`with_resolution`](Self::with_resolution),
    /// [`with_includes`](Self::with_includes),
    /// [`with_julia_target`](Self::with_julia_target),
    /// [`with_config`](Self::with_config),
    /// [`with_suppressions`](Self::with_suppressions), and
    /// [`with_enabled_rules`](Self::with_enabled_rules).
    pub fn new(path: Option<&'a Path>, root: &'a SyntaxNode, model: &'a SemanticModel) -> Self {
        Self {
            path,
            root,
            model,
            resolution: None,
            includes: &[],
            julia_target: None,
            config: &DEFAULT_RULES_CONFIG,
            suppressions: &EMPTY_SUPPRESSIONS,
            enabled_rules: &EMPTY_ENABLED_RULES,
            cache: RuleCache::default(),
        }
    }

    /// Attach the name-resolution context (see [`ResolutionContext`]).
    #[must_use]
    pub fn with_resolution(mut self, resolution: Option<ResolutionContext<'a>>) -> Self {
        self.resolution = resolution;
        self
    }

    /// Attach this file's precomputed include-graph problems.
    #[must_use]
    pub fn with_includes(mut self, includes: &'a [IncludeProblem]) -> Self {
        self.includes = includes;
        self
    }

    /// Attach the project's declared Julia support range.
    #[must_use]
    pub fn with_julia_target(mut self, julia_target: Option<VersionRange>) -> Self {
        self.julia_target = julia_target;
        self
    }

    /// Attach the run's per-rule option tables (see
    /// [`ResolvedRules::rules_config`]).
    #[must_use]
    pub fn with_config(mut self, config: &'a RulesConfig) -> Self {
        self.config = config;
        self
    }

    /// Attach this file's parsed `# fatou-ignore` directives (see
    /// [`SuppressionMap::build`]).
    #[must_use]
    pub fn with_suppressions(mut self, suppressions: &'a SuppressionMap) -> Self {
        self.suppressions = suppressions;
        self
    }

    /// Attach the rule IDs running in this pass (see [`ResolvedRules::enabled`]).
    #[must_use]
    pub fn with_enabled_rules(mut self, enabled_rules: &'a EnabledRules) -> Self {
        self.enabled_rules = enabled_rules;
        self
    }

    /// The name resolver for this file: [`Resolver::new`] over the model and
    /// the caller's [`ResolutionContext`], with the workspace tier attached.
    /// `None` when the caller provided no resolution context, which is every
    /// resolution-dependent rule's cue to stay silent.
    ///
    /// Built once per file and shared, so a rule should ask for it rather than
    /// assembling its own.
    pub fn resolver(&self) -> Option<&Resolver<'a, dyn PackageSource + 'a>> {
        self.cache
            .resolver
            .get_or_init(|| {
                let resolution = self.resolution.as_ref()?;
                Some(
                    Resolver::new(self.model, resolution.packages)
                        .with_workspace(resolution.workspace.clone()),
                )
            })
            .as_ref()
    }

    /// Whether any whole-module `using` visible in this file fails to resolve
    /// (see [`has_unresolvable_using`]). Such a `using` may export anything, so
    /// no conclusion about what a free name means is sound for the file.
    /// `false` without a resolution context, where the question does not arise.
    pub fn has_unresolvable_using(&self) -> bool {
        *self.cache.unresolvable_using.get_or_init(|| {
            self.resolution.as_ref().is_some_and(|resolution| {
                has_unresolvable_using(
                    self.model,
                    resolution.packages,
                    resolution.workspace.as_ref(),
                )
            })
        })
    }

    /// The shared per-file soundness scan (see [`FileScan`]).
    pub(crate) fn file_scan(&self) -> &FileScan {
        self.cache.scan.get_or_init(|| FileScan::collect(self.root))
    }

    /// The file's control-flow graph (see [`FileControlFlow`]), for a rule that
    /// reasons about reachability rather than shape.
    ///
    /// Built on first use and shared by the run. The lint entry points take a
    /// tree and a model rather than a database, so this is the linter's own
    /// build; the language server's incremental path memoizes the same value
    /// per file as [`crate::incremental::control_flow`].
    pub fn control_flow(&self) -> &FileControlFlow {
        self.cache
            .cfg
            .get_or_init(|| FileControlFlow::build(self.root))
    }

    /// Whether `call`'s callee is confirmed to be the Base/Core function of
    /// that name: a bare identifier that the shared masking order resolves to
    /// tier 4 ([`Resolution::System`]) and nothing else. A local shadow, a
    /// workspace sibling, an explicit `import`, a `using`'d export of another
    /// module, a qualified callee (`M.length(x)`), and a computed one
    /// (`f()(x)`) all answer `false`, as does anything in a file whose
    /// resolution answers are not trustworthy (see
    /// [`trusts_resolution`](Self::trusts_resolution)).
    ///
    /// This is the namespace-confirmation gate an idiom rule opens with: match
    /// the call shape, then ask this before claiming the call means what its
    /// name suggests. It is deliberately one-sided — `false` means
    /// *unconfirmed*, not *proven foreign* — so a rule that rewrites on `true`
    /// stays conservative when the answer is unknown.
    pub fn resolves_to_base(&self, call: &CallExpr) -> bool {
        let Some(Expr::Name(callee)) = call.callee() else {
            return false;
        };
        let Some(ident) = callee.ident() else {
            return false;
        };
        self.read_resolves_to_base(ident.syntax())
    }

    /// Whether a bare value read — an `IDENT` token used as a value, such as a
    /// function passed as an argument (`map(length, xs)`) — is confirmed to be
    /// the Base/Core name. The value-position counterpart of
    /// [`resolves_to_base`](Self::resolves_to_base), sharing its conservative
    /// stance and its gates.
    ///
    /// Only a token the semantic model recorded as a value read qualifies, so
    /// a field name (`x.length`), a keyword-argument name (`f(length = 1)`), a
    /// definition site, and a macro read all answer `false` without the
    /// resolver being consulted.
    pub fn read_resolves_to_base(&self, token: &SyntaxToken) -> bool {
        if token.kind() != SyntaxKind::IDENT || !self.trusts_resolution() {
            return false;
        }
        let Some(resolver) = self.resolver() else {
            return false;
        };
        let range = token.text_range();
        let Some(ident) = self.ident_at(range) else {
            return false;
        };
        if ident.is_macro || self.file_scan().in_skipped(range) {
            return false;
        }
        matches!(
            resolver.resolve(&ident.name, range.start(), Namespace::Value),
            Resolution::System { .. }
        )
    }

    /// Whether the bare name `name`, were it *written* at `at`, would mean the
    /// Base/Core function of that name. The question a fix asks before
    /// splicing in a name the source does not contain yet: rewriting
    /// `length(x) == 0` to `isempty(x)` is only equivalent if `isempty` is
    /// Base's there, and not a local definition, an import, or another
    /// module's export.
    ///
    /// The counterpart of [`read_resolves_to_base`](Self::read_resolves_to_base)
    /// for a name with no token behind it, sharing its masking order and its
    /// one-sided stance: `false` means *unconfirmed*, so a fix gated on `true`
    /// stays conservative when the answer is unknown.
    pub fn name_resolves_to_base(&self, name: &str, at: TextSize) -> bool {
        if !self.trusts_resolution() {
            return false;
        }
        let Some(resolver) = self.resolver() else {
            return false;
        };
        matches!(
            resolver.resolve(name, at, Namespace::Value),
            Resolution::System { .. }
        )
    }

    /// Whether a bare value read is shadowed by a definition *in this file* — a
    /// local, a parameter, a `for`/`let`/`catch` variable, or a same-name
    /// definition — as opposed to naming something a `using`/`import` brought
    /// in or a name no tier provides.
    ///
    /// The weaker namespace gate, for a rule matching a name the built-in
    /// tables do not know (a project-configured deny-list entry). Such a name
    /// can never satisfy [`resolves_to_base`](Self::resolves_to_base) — it is
    /// by definition not Base's — so demanding that would make the project's
    /// configuration silently inert. Asking "is it shadowed?" instead keeps the
    /// obvious false positive out while still honoring the configuration.
    ///
    /// An [`Import`](crate::semantic::BindingKind::Import) binding deliberately
    /// answers `false`: `import Foo: bar` followed by `bar()` really is the
    /// call the project named, not a shadow of it. A token the model did not
    /// record as a value read (a field name, a keyword-argument name) answers
    /// `false` too, matching [`read_resolves_to_base`](Self::read_resolves_to_base).
    pub fn read_is_shadowed_locally(&self, token: &SyntaxToken) -> bool {
        if token.kind() != SyntaxKind::IDENT {
            return false;
        }
        let Some(resolver) = self.resolver() else {
            return false;
        };
        let range = token.text_range();
        let Some(ident) = self.ident_at(range) else {
            return false;
        };
        if ident.is_macro || self.file_scan().in_skipped(range) {
            return false;
        }
        match resolver.resolve(&ident.name, range.start(), Namespace::Value) {
            Resolution::Binding(id) => self.model.binding(id).kind != BindingKind::Import,
            _ => false,
        }
    }

    /// Whether a "which tier provides this name?" answer can be trusted for
    /// this file at all: there is a resolution context, every whole-module
    /// `using` resolves, and no `eval`/`include` can be splicing in
    /// definitions the model never saw. The same soundness floor
    /// `undefined-name` and `call-arity` bail on, hoisted here because every
    /// caller of [`resolves_to_base`](Self::resolves_to_base) needs it.
    pub fn trusts_resolution(&self) -> bool {
        *self.cache.trusts_resolution.get_or_init(|| {
            let Some(resolution) = &self.resolution else {
                return false;
            };
            if self.has_unresolvable_using() {
                return false;
            }
            let scan = self.file_scan();
            // With a workspace, a literal `include` is followed by the harvest,
            // so what it splices in resolves via the workspace tier; a computed
            // path (or any include without a workspace) brings in unknowable
            // names.
            !scan.calls_eval
                && !scan.dynamic_include
                && (resolution.workspace.is_some() || !scan.literal_include)
        })
    }

    /// The model's record of the identifier occupying exactly `range`, if the
    /// model made one. Absent for a token that is not a read at all: a field
    /// name, a keyword-argument name, an operator.
    fn ident_at(&self, range: TextRange) -> Option<&IdentRef> {
        let index = self.cache.idents_by_range.get_or_init(|| {
            let mut map = HashMap::with_capacity(self.model.idents().len());
            for (i, ident) in self.model.idents().iter().enumerate() {
                map.entry(ident.range).or_insert(i);
            }
            map
        });
        index.get(&range).map(|&i| &self.model.idents()[i])
    }
}

/// What a resolution-dependent rule resolves free reads against: a
/// [`PackageSource`] (the CLI passes the built-in Base/Core export snapshot;
/// the language server its harvested library) and, when the file belongs to a
/// package under development, that package plus the file's host module path —
/// the same tier-2 context every LSP feature threads through
/// [`crate::resolve::Resolver::with_workspace`].
pub struct ResolutionContext<'a> {
    pub packages: &'a dyn PackageSource,
    pub workspace: Option<(Arc<PackageIndex>, ModulePath)>,
}

pub trait Rule: Send + Sync {
    /// The stable rule identifier (e.g. `unused-binding`).
    fn id(&self) -> &'static str;

    fn default_severity(&self) -> Severity {
        Severity::Warning
    }

    fn default_enabled(&self) -> bool {
        true
    }

    /// One-paragraph (markdown) description of what the rule flags and why, used
    /// to generate the rule reference. Empty means "not yet documented".
    fn description(&self) -> &'static str {
        ""
    }

    /// Worked examples for the rule reference. Each `source` is linted live and
    /// rendered with its diagnostics. The default is empty — a rule with no
    /// examples is skipped by the docs generator.
    fn examples(&self) -> &'static [Example] {
        &[]
    }

    /// The Julia target range under which this rule's [`examples`](Self::examples)
    /// are linted for the reference pages. Only version-gated rules
    /// (`julia-version-compat`) need this; the default `None` matches every
    /// version-agnostic rule. All of a rule's examples share this target.
    fn example_julia_target(&self) -> Option<VersionRange> {
        None
    }

    /// The `SyntaxKind`s this rule subscribes to. During [`ResolvedRules::run`]'s single
    /// shared traversal, [`Rule::check`] is invoked once for every element whose
    /// kind appears here. The default (`&[]`) opts out of node dispatch entirely
    /// — appropriate for rules that work off the whole file via
    /// [`Rule::check_file`].
    fn interests(&self) -> &'static [SyntaxKind] {
        &[]
    }

    /// Per-element callback, invoked for each CST element (node *or* token) whose
    /// kind is in [`Rule::interests`]. Node-shape rules unwrap `el.as_node()`;
    /// token rules unwrap `el.as_token()`. Push findings onto `sink`.
    fn check(&self, el: &SyntaxElement, ctx: &RuleContext<'_>, sink: &mut Vec<Diagnostic>) {
        let _ = (el, ctx, sink);
    }

    /// Whole-file pass, run once after the shared traversal. For rules driven by
    /// the semantic model or comment directives rather than node shape. The
    /// default is a no-op.
    fn check_file(&self, ctx: &RuleContext<'_>, sink: &mut Vec<Diagnostic>) {
        let _ = (ctx, sink);
    }

    /// Post-suppression pass, run once after the surviving findings have been
    /// filtered through the file's `# fatou-ignore` directives. `used` records
    /// which directives actually matched a finding.
    ///
    /// Separate from [`Rule::check_file`] because its input is a *driver* fact —
    /// which suppressions fired — that does not exist until filtering has run.
    /// No implementors yet; the future `meta/*-suppression` rules
    /// (`outdated-suppression`) are the consumers. The default is a no-op.
    fn check_suppressions(
        &self,
        ctx: &RuleContext<'_>,
        used: &DirectiveUsage,
        sink: &mut Vec<Diagnostic>,
    ) {
        let _ = (ctx, used, sink);
    }
}

/// One enabled rule plus the severity this run stamps on its findings: the
/// `[lint.severity]` override when present, the rule's default otherwise.
struct ConfiguredRule {
    rule: Box<dyn Rule>,
    severity: Severity,
}

/// The set of rules enabled for a run, after applying `select`/`ignore`,
/// each carrying its resolved severity.
pub struct ResolvedRules {
    rules: Vec<ConfiguredRule>,
    /// Node-dispatch table: kind discriminant -> indices into `rules` of the
    /// subscribed rules. `SyntaxKind` is a contiguous `#[repr(u16)]`, so a
    /// flat Vec indexed by `kind as usize` beats a hash map. Built once here
    /// so [`ResolvedRules::run`]'s per-file path allocates nothing for it.
    by_kind: Vec<Vec<usize>>,
    /// Whether any rule subscribes to node dispatch at all.
    any_node_rules: bool,
    /// The declared Julia support range for this run, constant across files.
    /// Copied into each [`RuleContext`] so version-gated rules can read it.
    julia_target: Option<VersionRange>,
    /// The `[lint.rules.<id>]` option tables for this run, likewise constant
    /// across files and borrowed by each [`RuleContext`]. Held here rather than
    /// threaded through the per-file entry points, which would widen every
    /// caller for the sake of the few rules that take options.
    rules_config: RulesConfig,
    /// The surviving rule IDs, for each [`RuleContext`] to borrow.
    enabled: EnabledRules,
}

impl ResolvedRules {
    /// Build the rule set honoring `config`, alongside any `select`/`ignore`/
    /// `severity` entries that name no shipped rule.
    ///
    /// Resolution order: start with every default-enabled rule (or, when
    /// `select` is set, the listed rules), then subtract anything in `ignore`.
    /// Each surviving rule gets the `[lint.severity]` override for its ID, or
    /// its own default severity.
    ///
    /// The returned `Vec<String>` holds the unrecognized IDs (first-seen order,
    /// deduplicated) so callers can warn on a typo'd `--select`/`--ignore` or
    /// `[lint.severity]` key.
    pub fn resolve(config: &LintConfig) -> (Self, Vec<String>) {
        let all = all_rules();
        let select = config.select.as_deref();

        let mut unknown = Vec::new();
        for id in select
            .into_iter()
            .flatten()
            .chain(&config.ignore)
            .chain(config.severity.keys())
        {
            let recognized = all.iter().any(|rule| rule.id() == id);
            if !recognized && !unknown.contains(id) {
                unknown.push(id.clone());
            }
        }

        let rules: Vec<ConfiguredRule> = all
            .into_iter()
            .filter(|rule| {
                let enabled = match select {
                    Some(selected) => selected.iter().any(|id| id == rule.id()),
                    None => rule.default_enabled(),
                };
                enabled && !config.ignore.iter().any(|id| id == rule.id())
            })
            .map(|rule| {
                let severity = config
                    .severity
                    .get(rule.id())
                    .copied()
                    .unwrap_or(rule.default_severity());
                ConfiguredRule { rule, severity }
            })
            .collect();

        let mut by_kind: Vec<Vec<usize>> = vec![Vec::new(); SyntaxKind::COUNT];
        let mut any_node_rules = false;
        for (i, configured) in rules.iter().enumerate() {
            for kind in configured.rule.interests() {
                by_kind[*kind as usize].push(i);
                any_node_rules = true;
            }
        }

        let enabled = EnabledRules(rules.iter().map(|c| c.rule.id()).collect());

        (
            Self {
                rules,
                by_kind,
                any_node_rules,
                julia_target: None,
                rules_config: config.rules.clone(),
                enabled,
            },
            unknown,
        )
    }

    /// A rule set for tests: the given rules with their default severities and
    /// the default options, dispatch table included.
    #[cfg(test)]
    fn with_rules(rules: Vec<Box<dyn Rule>>) -> Self {
        let rules: Vec<ConfiguredRule> = rules
            .into_iter()
            .map(|rule| {
                let severity = rule.default_severity();
                ConfiguredRule { rule, severity }
            })
            .collect();
        let mut by_kind: Vec<Vec<usize>> = vec![Vec::new(); SyntaxKind::COUNT];
        let mut any_node_rules = false;
        for (i, configured) in rules.iter().enumerate() {
            for kind in configured.rule.interests() {
                by_kind[*kind as usize].push(i);
                any_node_rules = true;
            }
        }
        let enabled = EnabledRules(rules.iter().map(|c| c.rule.id()).collect());
        Self {
            rules,
            by_kind,
            any_node_rules,
            julia_target: None,
            rules_config: RulesConfig::default(),
            enabled,
        }
    }

    /// Set the declared Julia support range these rules check against. Off by
    /// default; the CLI sets it from `[julia] version`/`Project.toml`/the
    /// `--julia-version` flag, and the docs generator sets it per example.
    #[must_use]
    pub fn with_julia_target(mut self, target: Option<VersionRange>) -> Self {
        self.julia_target = target;
        self
    }

    /// The Julia support range these rules check against, if set.
    pub fn julia_target(&self) -> Option<VersionRange> {
        self.julia_target
    }

    /// The per-rule option tables resolved for this run, for the driver to hand
    /// to each file's [`RuleContext`].
    pub fn rules_config(&self) -> &RulesConfig {
        &self.rules_config
    }

    /// The rule IDs running in this pass, for the driver to hand to each
    /// file's [`RuleContext`].
    pub fn enabled(&self) -> &EnabledRules {
        &self.enabled
    }

    /// Run every configured rule against `ctx` in one shared CST traversal,
    /// dropping the findings `ctx.suppressions` covers. Diagnostics carry
    /// `ctx.path` and are stably sorted by `(start, end, rule)`.
    ///
    /// Suppression is filtered *here*, not by the caller, for two reasons: the
    /// directive list has to reach rules on [`RuleContext`], and the
    /// post-suppression pass ([`Rule::check_suppressions`]) needs the *result*
    /// of filtering — which directives fired — a fact that does not exist any
    /// earlier.
    pub fn run(&self, ctx: &RuleContext<'_>) -> Vec<Diagnostic> {
        let mut all = Vec::new();

        // Single shared traversal feeding every node-shape rule, dispatched
        // off the precomputed `by_kind` table. Visits tokens too
        // (`descendants_with_tokens`) so token-level rules can subscribe to
        // e.g. `IDENT` or `COMMENT`.
        //
        // Severity is stamped centrally, right after each rule call, onto
        // whatever that call pushed: rules never choose it (see
        // [`Diagnostic::new`]).
        if self.any_node_rules {
            for el in ctx.root.descendants_with_tokens() {
                for &i in &self.by_kind[el.kind() as usize] {
                    let before = all.len();
                    self.rules[i].rule.check(&el, ctx, &mut all);
                    stamp_severity(&mut all[before..], self.rules[i].severity);
                }
            }
        }

        // Whole-file pass for model-/comment-driven rules.
        for configured in &self.rules {
            let before = all.len();
            configured.rule.check_file(ctx, &mut all);
            stamp_severity(&mut all[before..], configured.severity);
        }

        // Drop the suppressed findings, recording which directives did the
        // work.
        let used = ctx.suppressions.filter(&mut all);

        // Post-suppression pass. Its findings are suppressible too, but
        // against the *frozen* usage record — a directive that only ever
        // silenced a post-pass finding is not thereby "used".
        let mut post = Vec::new();
        for configured in &self.rules {
            let before = post.len();
            configured.rule.check_suppressions(ctx, &used, &mut post);
            stamp_severity(&mut post[before..], configured.severity);
        }
        if !post.is_empty() {
            post.retain(|d| !ctx.suppressions.is_suppressed(d.rule, d.range));
            all.append(&mut post);
        }

        // Stamp the file path onto every finding centrally; rules leave it
        // `None`.
        if let Some(path) = ctx.path {
            for diag in &mut all {
                diag.path = Some(path.to_path_buf());
            }
        }

        all.sort_by_key(|d| (d.range.start(), d.range.end(), d.rule));
        all
    }

    pub fn is_empty(&self) -> bool {
        self.rules.is_empty()
    }
}

/// Stamp `severity` onto the findings a rule just pushed. Severity is an
/// engine concern: the config override when set, the rule's default otherwise
/// (both already folded into [`ConfiguredRule::severity`] by
/// [`ResolvedRules::resolve`]).
fn stamp_severity(diags: &mut [Diagnostic], severity: Severity) {
    for diag in diags {
        diag.severity = severity;
    }
}

#[cfg(test)]
mod base_resolution_tests {
    use super::*;
    use crate::ast::AstNode;
    use crate::index::harvest_tree;
    use crate::index::model::ModuleIndex;
    use crate::semantic::SemanticModel;
    use std::collections::BTreeMap;

    type Library = BTreeMap<String, Arc<PackageIndex>>;

    /// A package named `name` harvested from `src` — its `export`s are the
    /// surface resolution sees.
    fn pkg(name: &str, src: &str) -> Arc<PackageIndex> {
        let parsed = crate::parser::parse(src);
        assert!(parsed.diagnostics.is_empty(), "fixture must parse clean");
        Arc::new(PackageIndex {
            name: name.to_string(),
            root: ModuleIndex {
                name: name.to_string(),
                ..harvest_tree(&parsed.cst)
            },
            members: Vec::new(),
            member_modules: Default::default(),
            diagnostics: Vec::new(),
        })
    }

    /// Base exporting `length`, a bare Core (so the tier-4 walk reaches both),
    /// and any extra packages.
    fn library(extra: &[(&str, &str)]) -> Library {
        let mut lib = Library::from([
            ("Base".to_string(), pkg("Base", "export length\n")),
            ("Core".to_string(), pkg("Core", "")),
        ]);
        for (name, src) in extra {
            lib.insert(name.to_string(), pkg(name, src));
        }
        lib
    }

    /// Run `ask` against a context over `src` resolving against `lib` (and an
    /// optional workspace package whose host module is its root).
    fn ask(
        src: &str,
        lib: Option<&Library>,
        ws: Option<Arc<PackageIndex>>,
        ask: impl Fn(&RuleContext<'_>, &SyntaxNode) -> bool,
    ) -> bool {
        let parsed = crate::parser::parse(src);
        assert!(parsed.diagnostics.is_empty(), "fixture must parse clean");
        let model = SemanticModel::build(&parsed.cst);
        let ctx =
            RuleContext::new(None, &parsed.cst, &model).with_resolution(lib.map(|packages| {
                ResolutionContext {
                    packages,
                    workspace: ws.map(|pkg| (pkg, Vec::new())),
                }
            }));
        ask(&ctx, &parsed.cst)
    }

    /// Whether the *last* call in `src` whose source text starts with `prefix`
    /// is confirmed Base/Core. Last, so a fixture can shadow a name with a
    /// definition and still ask about the use below it.
    fn call_is_base(
        src: &str,
        prefix: &str,
        lib: Option<&Library>,
        ws: Option<Arc<PackageIndex>>,
    ) -> bool {
        ask(src, lib, ws, |ctx, root| {
            let call = root
                .descendants()
                .filter_map(CallExpr::cast)
                .filter(|call| call.syntax().text().to_string().starts_with(prefix))
                .last()
                .expect("fixture must contain the call");
            ctx.resolves_to_base(&call)
        })
    }

    /// Whether the last `IDENT` token spelled `name` is confirmed Base/Core.
    fn read_is_base(src: &str, name: &str, lib: Option<&Library>) -> bool {
        ask(src, lib, None, |ctx, root| {
            let token = root
                .descendants_with_tokens()
                .filter_map(|el| el.into_token())
                .filter(|t| t.kind() == SyntaxKind::IDENT && t.text() == name)
                .last()
                .expect("fixture must contain the read");
            ctx.read_resolves_to_base(&token)
        })
    }

    #[test]
    fn bare_base_call_is_confirmed() {
        assert!(call_is_base(
            "length(x)\n",
            "length",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn local_shadow_is_not_base() {
        // A same-file definition masks Base, so the call below is not Base's.
        assert!(!call_is_base(
            "length(x) = 1\nlength(y)\n",
            "length(y)",
            Some(&library(&[])),
            None
        ));
        // So does a binding in an enclosing local scope.
        assert!(!call_is_base(
            "function f(length, x)\n    length(x)\nend\n",
            "length(x)",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn definition_site_is_not_a_base_call() {
        // The signature of `length(x) = 1` is a `CALL_EXPR` too — a definition,
        // not a call to Base.
        assert!(!call_is_base(
            "length(x) = 1\n",
            "length",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn qualified_callee_is_not_confirmed() {
        // Sound but conservative: `Base.length` *is* Base's, yet it is not the
        // bare-name shape the gate exists to confirm.
        assert!(!call_is_base(
            "Base.length(x)\n",
            "Base.length",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn computed_callee_is_not_confirmed() {
        assert!(!call_is_base("f()(x)\n", "f()(", Some(&library(&[])), None));
    }

    #[test]
    fn using_masked_export_is_not_base() {
        let lib = library(&[("A", "export length\n")]);
        assert!(!call_is_base(
            "using A\nlength(x)\n",
            "length",
            Some(&lib),
            None
        ));
    }

    #[test]
    fn explicit_import_is_not_confirmed() {
        // `import A: length` binds the name in this file, so the call is A's.
        let lib = library(&[("A", "export length\n")]);
        assert!(!call_is_base(
            "import A: length\nlength(x)\n",
            "length(x)",
            Some(&lib),
            None
        ));
    }

    #[test]
    fn workspace_sibling_is_not_base() {
        let ws = pkg("MyPkg", "length(x) = 1\n");
        assert!(!call_is_base(
            "length(x)\n",
            "length",
            Some(&library(&[])),
            Some(ws)
        ));
    }

    #[test]
    fn unresolvable_using_bails_the_file() {
        // The unharvested module may export anything, `length` included.
        assert!(!call_is_base(
            "using Unharvested\nlength(x)\n",
            "length",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn eval_or_unfollowable_include_bails_the_file() {
        assert!(!call_is_base(
            "eval(ex)\nlength(x)\n",
            "length(x)",
            Some(&library(&[])),
            None
        ));
        assert!(!call_is_base(
            "@eval f() = 1\nlength(x)\n",
            "length(x)",
            Some(&library(&[])),
            None
        ));
        // No workspace: nothing harvested what the `include` splices in.
        assert!(!call_is_base(
            "include(\"other.jl\")\nlength(x)\n",
            "length(x)",
            Some(&library(&[])),
            None
        ));
        // With one, a literal include is followed by the harvest.
        assert!(call_is_base(
            "include(\"other.jl\")\nlength(x)\n",
            "length(x)",
            Some(&library(&[])),
            Some(pkg("MyPkg", ""))
        ));
    }

    #[test]
    fn macro_call_and_quoted_code_are_not_confirmed() {
        // A macro receives unevaluated expressions and may rewrite them.
        assert!(!call_is_base(
            "@assert length(x) > 0\n",
            "length",
            Some(&library(&[])),
            None
        ));
        // Quoted code is data, not a call.
        assert!(!call_is_base(
            "ex = :(length(x))\n",
            "length",
            Some(&library(&[])),
            None
        ));
    }

    #[test]
    fn no_resolution_context_is_not_confirmed() {
        assert!(!call_is_base("length(x)\n", "length", None, None));
    }

    #[test]
    fn bare_read_is_confirmed() {
        assert!(read_is_base(
            "map(length, xs)\n",
            "length",
            Some(&library(&[]))
        ));
    }

    #[test]
    fn non_reads_spelled_like_a_base_name_are_not_confirmed() {
        // A field name is not a read of `length`.
        assert!(!read_is_base(
            "f(x.length)\n",
            "length",
            Some(&library(&[]))
        ));
        // Nor is a keyword-argument name.
        assert!(!read_is_base(
            "f(length = 1)\n",
            "length",
            Some(&library(&[]))
        ));
    }

    #[test]
    fn shadowed_read_is_not_confirmed() {
        assert!(!read_is_base(
            "length = 3\nmap(length, xs)\n",
            "length",
            Some(&library(&[]))
        ));
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn ids(v: &[&str]) -> Vec<String> {
        v.iter().map(|s| s.to_string()).collect()
    }

    #[test]
    fn resolve_flags_unknown_select_and_ignore_ids() {
        let config = LintConfig {
            select: Some(ids(&["unused-binding", "made-up-rule"])),
            ignore: ids(&["also-bogus"]),
            ..Default::default()
        };
        let (_rules, unknown) = ResolvedRules::resolve(&config);
        assert_eq!(unknown, ids(&["made-up-rule", "also-bogus"]));
    }

    #[test]
    fn resolve_reports_no_unknowns_for_valid_ids() {
        let config = LintConfig {
            ignore: ids(&["unused-import"]),
            ..Default::default()
        };
        let (_rules, unknown) = ResolvedRules::resolve(&config);
        assert!(unknown.is_empty());
    }

    #[test]
    fn control_flow_is_built_once_and_shared() {
        let src = "function f()\n    return 1\n    dead()\nend\n";
        let parsed = crate::parser::parse(src);
        let model = SemanticModel::build(&parsed.cst);
        let ctx = RuleContext::new(None, &parsed.cst, &model);

        let first = ctx.control_flow();
        assert!(std::ptr::eq(first, ctx.control_flow()), "memoized per file");

        let start = src.find("dead()").unwrap();
        let range = TextRange::new(
            u32::try_from(start).unwrap().into(),
            u32::try_from(start + "dead()".len()).unwrap().into(),
        );
        assert!(first.is_unreachable(range));
    }

    #[test]
    fn resolve_dedupes_repeated_unknown_ids() {
        let config = LintConfig {
            select: Some(ids(&["typo", "typo"])),
            ignore: ids(&["typo"]),
            ..Default::default()
        };
        let (_rules, unknown) = ResolvedRules::resolve(&config);
        assert_eq!(unknown, ids(&["typo"]));
    }

    #[test]
    fn resolve_flags_unknown_severity_keys() {
        let config = LintConfig {
            severity: [("no-such-rule".to_string(), Severity::Error)].into(),
            ..Default::default()
        };
        let (_rules, unknown) = ResolvedRules::resolve(&config);
        assert_eq!(unknown, ids(&["no-such-rule"]));
    }

    #[test]
    fn resolved_severity_is_override_or_rule_default() {
        let config = LintConfig {
            severity: [("unused-binding".to_string(), Severity::Error)].into(),
            ..Default::default()
        };
        let (rules, _) = ResolvedRules::resolve(&config);
        let severity_of = |id: &str| {
            rules
                .rules
                .iter()
                .find(|c| c.rule.id() == id)
                .map(|c| c.severity)
                .unwrap()
        };
        assert_eq!(severity_of("unused-binding"), Severity::Error);
        // No override: the rule's own default wins.
        assert_eq!(severity_of("duplicate-argument"), Severity::Error);
        assert_eq!(severity_of("unused-import"), Severity::Warning);
    }

    #[test]
    fn resolve_carries_the_per_rule_option_tables() {
        let mut config = LintConfig::default();
        config
            .rules
            .discouraged_function
            .extend_functions
            .insert("sleep".to_string(), "use a timer".to_string());
        let (rules, _) = ResolvedRules::resolve(&config);
        assert_eq!(
            rules.rules_config().discouraged_function.lookup("sleep"),
            Some("use a timer")
        );
    }

    #[test]
    fn a_context_with_no_config_sees_the_defaults() {
        let parsed = crate::parser::parse("x = 1\n");
        let model = SemanticModel::build(&parsed.cst);
        let ctx = RuleContext::new(None, &parsed.cst, &model);
        assert!(ctx.config.discouraged_function.lookup("exit").is_some());
    }
}

#[cfg(test)]
mod suppression_dispatch_tests {
    use super::*;
    use crate::semantic::SemanticModel;

    /// A rule that flags every `CALL_EXPR`, so a fixture can trigger a finding
    /// with any call and a directive can suppress it.
    struct FakeError;
    impl Rule for FakeError {
        fn id(&self) -> &'static str {
            "fake-error"
        }
        fn interests(&self) -> &'static [SyntaxKind] {
            &[SyntaxKind::CALL_EXPR]
        }
        fn check(&self, el: &SyntaxElement, _ctx: &RuleContext<'_>, sink: &mut Vec<Diagnostic>) {
            sink.push(Diagnostic::new("fake-error", el.text_range(), "boom"));
        }
    }

    /// A stand-in for `outdated-suppression`: reports every directive the
    /// filter left unused, from the post-suppression pass.
    struct FakePost;
    impl Rule for FakePost {
        fn id(&self) -> &'static str {
            "fake-post"
        }
        fn check_suppressions(
            &self,
            ctx: &RuleContext<'_>,
            used: &DirectiveUsage,
            sink: &mut Vec<Diagnostic>,
        ) {
            for (i, directive) in ctx.suppressions.directives().iter().enumerate() {
                if !used.is_used(i) {
                    sink.push(Diagnostic::new("fake-post", directive.comment, "unused"));
                }
            }
        }
    }

    fn run_on(src: &str, rules: Vec<Box<dyn Rule>>) -> Vec<Diagnostic> {
        let parsed = crate::parser::parse(src);
        assert!(parsed.diagnostics.is_empty(), "fixture must parse clean");
        let model = SemanticModel::build(&parsed.cst);
        let suppressions = crate::linter::suppression::SuppressionMap::build(&parsed.cst);
        let resolved = ResolvedRules::with_rules(rules);
        let ctx = RuleContext::new(None, &parsed.cst, &model)
            .with_suppressions(&suppressions)
            .with_enabled_rules(resolved.enabled());
        resolved.run(&ctx)
    }

    /// Suppression filtering lives in `run`, not in `check.rs` — the rules
    /// need the directive list on `RuleContext`, and the post-suppression pass
    /// needs the *result* of filtering.
    #[test]
    fn run_filters_suppressed_findings() {
        let diags = run_on(
            "# fatou-ignore fake-error: quiet\nf(1)\n",
            vec![Box::new(FakeError)],
        );
        assert!(diags.is_empty(), "expected no findings, got {diags:?}");
    }

    #[test]
    fn post_pass_reports_directives_that_matched_nothing() {
        // The directive names a rule that never fires, so the post-pass rule
        // sees it unused and reports on its comment range.
        let src = "# fatou-ignore fake-error: stale\nx = 1\n";
        let diags = run_on(src, vec![Box::new(FakeError), Box::new(FakePost)]);
        assert_eq!(diags.len(), 1);
        assert_eq!(diags[0].rule, "fake-post");
        assert_eq!(&src[diags[0].range], "# fatou-ignore fake-error: stale");
    }

    /// Post-pass findings are themselves suppressible, but against the frozen
    /// usage record — and a directive never covers a finding inside its own
    /// comment, so the file-wide `fake-post` directive silences the finding
    /// about the stale directive while staying reportable itself.
    #[test]
    fn post_pass_findings_are_refiltered() {
        let src = "# fatou-ignore-file fake-post: hush\n# fatou-ignore fake-error: stale\nx = 1\n";
        let diags = run_on(src, vec![Box::new(FakeError), Box::new(FakePost)]);
        assert_eq!(diags.len(), 1, "got {diags:?}");
        assert_eq!(&src[diags[0].range], "# fatou-ignore-file fake-post: hush");
    }

    /// The rule set reaches rules through the context, so a post-suppression
    /// pass can tell "this rule found nothing" from "this rule never ran".
    #[test]
    fn enabled_rules_reflects_the_resolved_set() {
        let config = LintConfig {
            select: Some(vec!["unused-binding".to_string()]),
            ..LintConfig::default()
        };
        let (resolved, unknown) = ResolvedRules::resolve(&config);
        assert!(unknown.is_empty());
        assert!(resolved.enabled().contains("unused-binding"));
        assert!(!resolved.enabled().contains("discouraged-function"));
    }
}