fallow_cli/

lib.rs

#![expect(
    clippy::print_stdout,
    clippy::print_stderr,
    reason = "CLI binary produces intentional terminal output"
)]
#![cfg_attr(
    test,
    allow(
        clippy::unwrap_used,
        clippy::expect_used,
        reason = "tests use unwrap and expect to keep fixture setup concise"
    )
)]

use std::io::IsTerminal as _;
use std::path::{Path, PathBuf};
use std::process::ExitCode;

use clap::{Parser, Subcommand};

mod api;
#[cfg(test)]
mod architecture_boundaries;
mod audit;
mod audit_brief;
mod audit_cache_prune;
mod audit_decision_surface;
mod audit_focus;
mod audit_walkthrough;
mod base_worktree;
/// Re-exported for integration tests so they hash reusable-cache roots through
/// the exact production path (`dunce` canonicalization + platform path-identity
/// bytes) rather than an approximation that diverges on Windows.
pub use base_worktree::canonical_root_hash;
mod walkthrough_state;
use fallow_engine::baseline;
mod agent_install;
mod cache_notice;
mod check;
mod ci;
mod ci_template;
mod cli_agent;
mod cli_format;
mod cli_hooks;
mod cli_impact;
mod cli_production;
mod cli_report;
mod cli_startup;
pub use fallow_engine::codeowners;
mod combined;
mod config;
mod coverage;
mod doctor;
mod dupes;
mod exit_codes;
pub mod explain;
mod fix;
mod flags;
mod guard;
mod health;
mod impact;
mod init;
mod inspect;
mod json_style;
mod license;
mod list;
mod migrate;
mod onboarding;
#[cfg(test)]
mod output_envelope;
mod output_runtime;
mod path_util;
mod plugin_check;
mod rayon_pool;
mod regression;
pub mod report;
mod rule_pack;
mod runtime_support;
mod schema;
mod security;
mod security_help;
mod selector;
mod setup_hooks;
mod signal;
mod similar_code_cli;
mod similar_code_help;
mod suppressions;
mod task_matrix;
mod telemetry;
mod trace_chain;
mod trace_error;
mod trace_path;
mod type_aware_degrade;
mod update_check;
use fallow_engine::validate;
use fallow_engine::vital_signs;
mod cli_telemetry;
mod viz;
mod watch;

use check::{CheckOptions, IssueFilters, TraceOptions};
/// Structured error output for CLI and JSON formats.
pub(crate) mod error;
use cli_agent::{AgentCli, run_agent_command};
#[cfg(test)]
use cli_format::parse_format_arg;
use cli_format::{Format, FormatConfig};
use cli_hooks::{HooksCli, run_hooks_command};
use cli_impact::{ImpactCli, ImpactCrossRepoOpts, ImpactSortCli, dispatch_impact};
use cli_production::{ProductionModes, resolve_production_modes};
#[cfg(test)]
use cli_startup::build_tracing_filter;
use cli_startup::{
    bare_coverage_subcommand_error_message, cli_has_bare_coverage_input, parse_cli_args,
    run_pre_dispatch_checks, setup_tracing, validate_inputs,
};
#[cfg(test)]
use cli_telemetry::TelemetryRun;
#[cfg(test)]
use cli_telemetry::{fallback_failure_reason_for, telemetry_workflow_for_command};
use cli_telemetry::{record_run_epilogue, start_telemetry_run};
use dupes::{DupesMode, DupesOptions};
use error::emit_error;
use health::{HealthOptions, SortBy};
use list::ListOptions;
pub(crate) use runtime_support::{AnalysisKind, GroupBy};
pub(crate) use runtime_support::{
    ConfigLoadOptions, LoadConfigArgs, build_ownership_resolver, load_config,
    load_config_for_analysis,
};
#[cfg(test)]
use security_help::{SECURITY_UNSUPPORTED_GLOBAL_LONGS, SecurityHelpTarget};
use security_help::{render_security_help, security_help_target};
use similar_code_help::{render_similar_code_help, similar_code_help_target};

const DEFAULT_MIN_INVOCATIONS_HOT: u64 = 100;

const TOP_LEVEL_HELP_TEMPLATE: &str =
    "{about-with-newline}\n{usage-heading} {usage}{after-help}\n\nOptions:\n{options}";

// Macros instead of consts so `concat!` can assemble the short (`-h`) and
// long (`--help`) after-help surfaces from the same source fragments.
macro_rules! top_level_task_cheat_sheet {
    () => {
        "\
When the agent is about to...
  delete an \"unused\" export or file        fallow dead-code --trace <file>:<export>
  prove exact TypeScript symbol consumers  fallow dead-code --type-aware --symbol-impact <file>:<export-or-class.method>
  find how one module reaches another      fallow trace --path <from> <to>
  delete an \"unused\" dependency            fallow dead-code --trace-dependency <name>
  commit or open a PR                      fallow audit --base <ref>
  read a diff before approving it          fallow review --base <ref> --brief
  prioritize refactoring                   fallow health --hotspots --targets
  ask who owns code                        fallow health --ownership
  check untested-but-reachable code        fallow health --coverage-gaps
  consolidate duplication                  fallow dupes --trace dup:<fingerprint>
  find feature flags                       fallow flags
  check architecture rules before editing  fallow guard <files>
  surface security candidates              fallow security
  inspect a target before editing          fallow inspect --file <path>
  understand a finding                     fallow explain <issue-type>
  scope a monorepo                         --workspace <glob> / --changed-workspaces <ref>"
    };
}

macro_rules! top_level_core_command_groups {
    () => {
        "\
Analysis:
  dead-code      Analyze unused code, dependency hygiene, and architecture cycles
  dupes          Find copy-paste and structural code duplication
  health         Analyze complexity, maintainability, hotspots, and coverage gaps
  flags          Detect feature flag usage patterns
  security       Surface local security candidates for agent verification (opt-in)
  similar-code   Find semantic implementation overlap for verification (opt-in, local)
  audit          Review changed files for dead code, complexity, duplication, and styling

Workflow:
  watch          Re-run analysis as files change
  fix            Auto-fix safe unused-code findings"
    };
}

macro_rules! top_level_extended_command_groups {
    () => {
        "\
Project inspection:
  list              List discovered files, entry points, plugins, boundaries, and workspaces
  inspect           Inspect one file or exported symbol as a bundled evidence query
  trace             Trace a symbol's call chain (best-effort, syntactic)
  trace-error       Resolve a runtime stack trace's frames to project definitions
  guard             Show which architecture rules apply to files before editing
  decision-surface  Surface the structural decisions a change embeds (advisory)
  workspaces        Show monorepo workspace discovery diagnostics
  explain           Explain one issue type without running analysis
  suppressions      List active fallow-ignore suppression markers
  impact            Show what fallow has done for you (opt-in, local-only)
  viz               Generate an interactive HTML map of the codebase

Setup and configuration:
  doctor            Diagnose project readiness without changing anything
  init              Create a fallow config, optionally with a Git hook
  agent             Wire fallow into Claude Code, Codex, or Cursor in one pass
  audit-cache       Maintain reusable audit base-snapshot caches
  recommend         Recommend a project-tailored config for an agent to author
  migrate           Migrate knip, jscpd, or stylelint config to fallow
  config            Show the resolved config and loaded config file
  config-schema     Print the fallow config JSON Schema
  plugin-schema     Print the external plugin JSON Schema
  plugin-check      Dry-run external plugins and report what they seed
  rule-pack         Manage declarative rule packs (policy-as-code)
  rule-pack-schema  Print the rule pack JSON Schema
  type-aware        Inspect the optional TypeScript semantic companion

Automation and CI:
  ci             Build PR/MR feedback envelopes
  ci-template    Print or vendor CI integration templates
  report         Re-render saved JSON as GitHub or CodeClimate output
  hooks          Install or remove fallow-managed Git and agent hooks
  setup-hooks    Deprecated: use `agent install` or `hooks install --target agent`

Runtime coverage:
  coverage       Set up or analyze runtime coverage data
  license        Manage the paid-feature license
  telemetry      Manage opt-in product telemetry

Reference:
  schema         Dump the CLI interface as machine-readable JSON
  help           Print this message or the help of a command"
    };
}

const TOP_LEVEL_AFTER_HELP: &str = concat!(
    top_level_task_cheat_sheet!(),
    "\n\n",
    top_level_core_command_groups!(),
    "\n\nRun fallow --help for the complete command list."
);

const TOP_LEVEL_AFTER_LONG_HELP: &str = concat!(
    top_level_task_cheat_sheet!(),
    "\n\n",
    top_level_core_command_groups!(),
    "\n\n",
    top_level_extended_command_groups!(),
    "\n\n",
    "When no command is given, fallow runs dead-code + dupes + health together.\n",
    "Use --only/--skip to select specific analyses."
);

#[derive(Parser)]
#[command(
    name = "fallow",
    about = "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
    version,
    disable_version_flag = true,
    help_template = TOP_LEVEL_HELP_TEMPLATE,
    after_help = TOP_LEVEL_AFTER_HELP,
    after_long_help = TOP_LEVEL_AFTER_LONG_HELP
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Command>,

    /// Print version.
    /// Accepts `-v`, `-V`, and `--version`; TS/JS tooling (node, npm, pnpm,
    /// yarn, bun, tsc) uses `-v`, while `-V` matches knip/oxlint/biome.
    #[arg(
        short = 'v',
        visible_short_alias = 'V',
        long = "version",
        action = clap::ArgAction::Version
    )]
    version: Option<bool>,

    /// Project root directory
    #[arg(short, long, global = true)]
    root: Option<PathBuf>,

    /// Path to config file (.fallowrc.json, .fallowrc.jsonc, fallow.toml, or .fallow.toml)
    #[arg(short, long, global = true)]
    config: Option<PathBuf>,

    /// Allow trusted config files to extend HTTPS URLs
    #[arg(hide_short_help = true, long, global = true)]
    allow_remote_extends: bool,

    /// Output format (alias: --output)
    #[arg(
        short,
        long,
        visible_alias = "output",
        global = true,
        default_value = "human"
    )]
    format: Format,

    /// Indent JSON output for manual inspection. Requires the final output format to be JSON.
    #[arg(hide_short_help = true, long, global = true)]
    pretty: bool,

    /// Suppress progress output
    #[arg(short, long, global = true)]
    quiet: bool,

    /// Disable incremental caching
    #[arg(hide_short_help = true, long, global = true)]
    no_cache: bool,

    /// Number of parser threads
    #[arg(hide_short_help = true, long, global = true)]
    threads: Option<usize>,

    /// Only report issues in files changed since this git ref (e.g., main, HEAD~5)
    #[arg(long, visible_alias = "base", global = true)]
    changed_since: Option<String>,

    /// Unified diff for line-level scoping.
    /// Use `-` to read from stdin. Project-level findings still bypass this
    /// filter. When both this and `--changed-since` are set, the diff filter
    /// wins for finding scope while `--changed-since` still drives file discovery.
    #[arg(
        hide_short_help = true,
        long = "diff-file",
        value_name = "PATH",
        global = true
    )]
    diff_file: Option<PathBuf>,

    /// Read the unified diff from stdin.
    /// Equivalent to `--diff-file -`.
    #[arg(hide_short_help = true, long = "diff-stdin", global = true)]
    diff_stdin: bool,

    /// Import change history from a `fallow-churn/v1` JSON file instead of `git
    /// log`, powering hotspots, ownership, and bus-factor on projects with no
    /// git repository (Yandex Arc, Mercurial, Perforce). A small wrapper
    /// translates your VCS log into the contract. Resolved relative to `--root`.
    /// Affects `health --hotspots` / `--ownership` / `--targets` only; `audit`,
    /// `impact`, and `--changed-since` still require git.
    #[arg(
        hide_short_help = true,
        long = "churn-file",
        value_name = "PATH",
        global = true
    )]
    churn_file: Option<PathBuf>,

    /// Skip source files larger than this many megabytes (default 5) instead of
    /// parsing them, guarding against the out-of-memory blowup a single
    /// multi-MB generated/vendored/bundled file causes on large repos. Use `0`
    /// for no limit. Declaration files (`.d.ts`) are always analyzed. Skipped
    /// files are reported and excluded from every analysis. Also settable via
    /// `FALLOW_MAX_FILE_SIZE`.
    #[arg(
        hide_short_help = true,
        long = "max-file-size",
        value_name = "MB",
        global = true
    )]
    max_file_size: Option<u32>,

    /// Compare against a previously saved baseline file
    #[arg(hide_short_help = true, long, global = true)]
    baseline: Option<PathBuf>,

    /// How `--baseline` matches health findings: per file and category
    /// (`count`, the default) or per function identity (`identity`, strict,
    /// and only against a baseline that was saved with `--baseline-mode
    /// identity`; such a baseline still reads in count mode).
    ///
    /// A finding's identity is its file path plus its function name, so
    /// renaming or moving a function that is still in the baseline reports it
    /// as new. Re-save the baseline after that kind of refactor. Functions
    /// that share a name in one file, and unnamed functions, share one
    /// identity and can mask each other.
    ///
    /// Defaults to `count` when omitted. Saving without the flag refuses to
    /// overwrite a baseline that carries identities; pass `--baseline-mode
    /// count` explicitly to downgrade such a baseline on purpose.
    #[arg(
        hide_short_help = true,
        long = "baseline-mode",
        value_enum,
        global = true
    )]
    baseline_mode: Option<BaselineModeArg>,

    /// Correlate this run with a previous telemetry analysis run.
    ///
    /// Used only for opt-in telemetry follow-up measurement. The value is not
    /// interpreted as a path, repository, package, or user identifier. Hidden
    /// from `--help`; agents receive the correlation token from JSON output.
    #[arg(long, global = true, value_name = "RUN_ID", hide = true)]
    parent_run: Option<String>,

    /// Save the current results as a baseline file
    #[arg(hide_short_help = true, long, global = true)]
    save_baseline: Option<PathBuf>,

    /// Production mode: exclude test/story/dev files, only start/build scripts,
    /// report type-only dependencies
    #[arg(long, global = true)]
    production: bool,

    /// Force production mode OFF for every analysis, overriding a project
    /// config's `production: true` (and `FALLOW_PRODUCTION`). Conflicts with
    /// `--production`.
    #[arg(
        hide_short_help = true,
        long = "no-production",
        global = true,
        conflicts_with = "production"
    )]
    no_production: bool,

    /// Run dead-code analysis in production mode when using bare combined mode.
    #[arg(hide_short_help = true, long = "production-dead-code")]
    production_dead_code: bool,

    /// Run health analysis in production mode when using bare combined mode.
    #[arg(hide_short_help = true, long = "production-health")]
    production_health: bool,

    /// Run duplication analysis in production mode when using bare combined mode.
    #[arg(hide_short_help = true, long = "production-dupes")]
    production_dupes: bool,

    /// Scope output to selected workspaces.
    /// Accepts exact names, glob patterns, and `!`-prefixed negations.
    /// Values can be comma-separated or repeated.
    #[arg(short, long, global = true, value_delimiter = ',')]
    workspace: Option<Vec<String>>,

    /// Scope output to workspaces touched since the given git ref.
    /// Git is required. Mutually exclusive with `--workspace`.
    #[arg(long, global = true, value_name = "REF")]
    changed_workspaces: Option<String>,

    /// Group output by owner or by directory.
    #[arg(hide_short_help = true, long, global = true)]
    group_by: Option<GroupBy>,

    /// Show pipeline performance timing breakdown
    #[arg(hide_short_help = true, long, global = true)]
    performance: bool,

    /// Include metric definitions and rule descriptions in output.
    #[arg(hide_short_help = true, long, global = true)]
    explain: bool,

    /// Show a per-pattern breakdown for default duplicate ignores.
    #[arg(hide_short_help = true, long, global = true)]
    explain_skipped: bool,

    /// Show only category counts without individual items
    #[arg(hide_short_help = true, long, global = true)]
    summary: bool,

    /// CI mode: equivalent to --format sarif --fail-on-issues --quiet
    #[arg(long, global = true)]
    ci: bool,

    /// Exit with code 1 if issues are found
    #[arg(hide_short_help = true, long, global = true)]
    fail_on_issues: bool,

    /// Write SARIF output to a file (in addition to the primary --format output)
    #[arg(hide_short_help = true, long, global = true, value_name = "PATH")]
    sarif_file: Option<PathBuf>,

    /// Write the report to a file instead of stdout, for any --format (no ANSI
    /// codes). Useful on large projects where the terminal scrollback truncates
    /// the top. Progress and the confirmation stay on stderr.
    #[arg(short = 'o', long, global = true, value_name = "PATH")]
    output_file: Option<PathBuf>,

    /// Prefix prepended to every path in the CI-facing formats
    /// (`github-annotations`, `github-summary`, `codeclimate`,
    /// `pr-comment-github`, `pr-comment-gitlab`, `review-github`,
    /// `review-gitlab`). CI platforms address files by
    /// repository-root-relative path, so when the analyzed project lives in a
    /// subdirectory (e.g. `packages/app/`), paths need that offset. fallow
    /// detects the offset via the git toplevel automatically; this flag
    /// overrides the detection. Pass an empty string to disable rebasing and
    /// emit paths relative to `--root`.
    #[arg(
        hide_short_help = true,
        long = "report-path-prefix",
        visible_alias = "annotations-path-prefix",
        global = true,
        value_name = "PREFIX"
    )]
    report_path_prefix: Option<String>,

    /// Fail if issue count increased beyond tolerance compared to a regression baseline.
    #[arg(hide_short_help = true, long, global = true)]
    fail_on_regression: bool,

    /// Allowed issue count increase before a regression is flagged.
    #[arg(
        hide_short_help = true,
        long,
        global = true,
        value_name = "TOLERANCE",
        default_value = "0"
    )]
    tolerance: String,

    /// Path to the regression baseline file.
    #[arg(hide_short_help = true, long, global = true, value_name = "PATH")]
    regression_baseline: Option<PathBuf>,

    /// Save the current issue counts as a regression baseline. Omit PATH to
    /// update regression.baseline in the discovered fallow config, or create
    /// .fallowrc.json when none exists. Provide PATH to write a standalone file.
    #[expect(
        clippy::option_option,
        reason = "clap pattern: None=not passed, Some(None)=flag only (write to config), Some(Some(path))=write to file"
    )]
    #[arg(hide_short_help = true, long, global = true, value_name = "PATH", num_args = 0..=1, default_missing_value = "")]
    save_regression_baseline: Option<Option<String>>,

    /// Run only specific analyses when no subcommand is given.
    #[arg(long, value_delimiter = ',')]
    only: Vec<AnalysisKind>,

    /// Skip specific analyses when no subcommand is given.
    #[arg(long, value_delimiter = ',')]
    skip: Vec<AnalysisKind>,

    /// Override duplication detection mode in combined mode.
    #[arg(hide_short_help = true, long = "dupes-mode", global = true)]
    dupes_mode: Option<DupesMode>,

    /// Enable function-scoped near-miss clone detection in combined mode.
    #[arg(hide_short_help = true, long = "dupes-near", global = true)]
    dupes_near: bool,

    /// Override duplication threshold in combined mode.
    #[arg(hide_short_help = true, long = "dupes-threshold", global = true)]
    dupes_threshold: Option<f64>,

    /// Override the minimum token count for clones in combined mode.
    #[arg(hide_short_help = true, long = "dupes-min-tokens", global = true)]
    dupes_min_tokens: Option<usize>,

    /// Override the minimum line count for clones in combined mode.
    #[arg(hide_short_help = true, long = "dupes-min-lines", global = true)]
    dupes_min_lines: Option<usize>,

    /// Override the minimum clone occurrences in combined mode (must be >= 2).
    #[arg(hide_short_help = true, long = "dupes-min-occurrences", global = true, value_parser = parse_min_occurrences)]
    dupes_min_occurrences: Option<usize>,

    /// Only report cross-directory duplicates in combined mode.
    #[arg(hide_short_help = true, long = "dupes-skip-local", global = true)]
    dupes_skip_local: bool,

    /// Enable cross-language duplicate detection in combined mode.
    #[arg(hide_short_help = true, long = "dupes-cross-language", global = true)]
    dupes_cross_language: bool,

    /// Exclude module wiring from duplicate detection in combined mode
    /// (default). Pass `--dupes-no-ignore-imports` to count it again.
    #[arg(hide_short_help = true, long = "dupes-ignore-imports", global = true)]
    dupes_ignore_imports: bool,

    /// Count module wiring as clone candidates in combined mode (opt out of the
    /// default exclusion).
    #[arg(
        hide_short_help = true,
        long = "dupes-no-ignore-imports",
        global = true,
        conflicts_with = "dupes_ignore_imports"
    )]
    dupes_no_ignore_imports: bool,

    /// Compute health score in combined mode.
    #[arg(hide_short_help = true, long)]
    score: bool,

    /// Compare current health metrics against the most recent saved snapshot.
    #[arg(hide_short_help = true, long)]
    trend: bool,

    /// Save a vital signs snapshot for trend tracking in combined mode.
    /// Provide a path or omit for the default `.fallow/snapshots/` location.
    #[expect(
        clippy::option_option,
        reason = "clap pattern: None=not passed, Some(None)=default path, Some(Some(path))=custom path"
    )]
    #[arg(hide_short_help = true, long, value_name = "PATH", num_args = 0..=1, default_missing_value = "")]
    save_snapshot: Option<Option<String>>,

    /// Path to Istanbul coverage data for exact CRAP scores in combined mode.
    /// Also settable via `FALLOW_COVERAGE` or `health.coverage`.
    #[arg(hide_short_help = true, long, value_name = "PATH")]
    coverage: Option<PathBuf>,

    /// Absolute prefix to strip from Istanbul file paths in combined mode.
    /// Also settable via `FALLOW_COVERAGE_ROOT` or `health.coverageRoot`.
    #[arg(hide_short_help = true, long = "coverage-root", value_name = "PATH")]
    coverage_root: Option<PathBuf>,

    /// Report unused exports in entry files instead of auto-marking them as used.
    #[arg(hide_short_help = true, long, global = true)]
    include_entry_exports: bool,

    /// Opt in to TypeScript semantic analysis for project-wide symbol evidence.
    /// This does not emit compiler diagnostics or typed lint findings.
    #[arg(hide_short_help = true, long, global = true)]
    type_aware: bool,

    /// Disable TypeScript semantic analysis even when `typeAware.enabled` or
    /// `FALLOW_TYPE_AWARE` opts in, keeping this run fully syntactic.
    #[arg(
        hide_short_help = true,
        long,
        global = true,
        conflicts_with = "type_aware"
    )]
    no_type_aware: bool,

    /// TypeScript project config to use for type-aware analysis (repeatable).
    #[arg(hide_short_help = true, long, global = true, value_name = "PATH", action = clap::ArgAction::Append)]
    type_aware_project: Vec<PathBuf>,

    /// Decide whether incomplete type-aware analysis is advisory or gating.
    #[arg(hide_short_help = true, long, global = true, value_enum)]
    type_aware_require: Option<TypeAwareRequireArg>,
}

impl Cli {
    /// Tri-state CLI override for type-aware analysis: `Some(true)` for
    /// `--type-aware`, `Some(false)` for `--no-type-aware`, `None` when
    /// neither flag was passed (environment and config decide).
    const fn type_aware_override(&self) -> Option<bool> {
        if self.no_type_aware {
            Some(false)
        } else if self.type_aware {
            Some(true)
        } else {
            None
        }
    }
}

#[derive(Clone, Copy, Subcommand)]
enum TypeAwareCli {
    /// Report companion availability and version compatibility without analysis.
    Status,
}

#[derive(Subcommand)]
enum Command {
    /// Analyze project for unused code and circular dependencies
    #[command(name = "dead-code", alias = "check")]
    Check {
        /// Only report unused files
        #[arg(long)]
        unused_files: bool,

        /// Only report unused exports
        #[arg(long)]
        unused_exports: bool,

        /// Only report unused dependencies
        #[arg(long)]
        unused_deps: bool,

        /// Only report unused type exports
        #[arg(long)]
        unused_types: bool,

        /// Opt in to private type leak API hygiene findings and only report that issue type
        #[arg(long)]
        private_type_leaks: bool,

        /// Only report unused enum members
        #[arg(long)]
        unused_enum_members: bool,

        /// Only report unused class members
        #[arg(long)]
        unused_class_members: bool,

        /// Only report unused store members
        #[arg(long)]
        unused_store_members: bool,

        /// Only report unprovided injects
        #[arg(long)]
        unprovided_injects: bool,

        /// Only report unrendered components
        #[arg(long)]
        unrendered_components: bool,

        /// Only report unused component props
        #[arg(long)]
        unused_component_props: bool,

        /// Only report unused component emits
        #[arg(long)]
        unused_component_emits: bool,

        /// Only report unused component inputs
        #[arg(long)]
        unused_component_inputs: bool,

        /// Only report unused component outputs
        #[arg(long)]
        unused_component_outputs: bool,

        /// Only report unused Svelte dispatched events
        #[arg(long)]
        unused_svelte_events: bool,

        /// Only report unused server actions
        #[arg(long)]
        unused_server_actions: bool,

        /// Only report unused SvelteKit load() data keys
        #[arg(long)]
        unused_load_data_keys: bool,

        /// Only report unresolved imports
        #[arg(long)]
        unresolved_imports: bool,

        /// Only report unlisted dependencies
        #[arg(long)]
        unlisted_deps: bool,

        /// Only report duplicate exports
        #[arg(long)]
        duplicate_exports: bool,

        /// Only report circular dependencies
        #[arg(long)]
        circular_deps: bool,

        /// Only report re-export cycles
        #[arg(long)]
        re_export_cycles: bool,

        /// Only report boundary violations
        #[arg(long)]
        boundary_violations: bool,

        /// Only report rule-pack policy violations
        #[arg(long)]
        policy_violations: bool,

        /// Only report stale suppressions
        #[arg(long)]
        stale_suppressions: bool,

        /// Only report unused pnpm catalog entries
        #[arg(long)]
        unused_catalog_entries: bool,

        /// Only report empty pnpm catalog groups
        #[arg(long)]
        empty_catalog_groups: bool,

        /// Only report unresolved pnpm catalog references
        #[arg(long)]
        unresolved_catalog_references: bool,

        /// Only report unused package-manager dependency overrides
        #[arg(long)]
        unused_dependency_overrides: bool,

        /// Only report misconfigured package-manager dependency overrides
        #[arg(long)]
        misconfigured_dependency_overrides: bool,

        /// Also run duplication analysis and cross-reference with dead code
        #[arg(long)]
        include_dupes: bool,

        /// Trace why an export is used/unused (format: `FILE:EXPORT_NAME`)
        #[arg(long, value_name = "FILE:EXPORT")]
        trace: Option<String>,

        /// Trace all edges for a file (imports, exports, importers)
        #[arg(long, value_name = "PATH")]
        trace_file: Option<String>,

        /// Trace where a dependency is used
        #[arg(long, value_name = "PACKAGE")]
        trace_dependency: Option<String>,

        /// Compute the impact closure for a file (the transitive
        /// affected-but-not-in-diff set + coordination gap). Walks reverse-deps
        /// and re-export chains; powers the `inspect_target` MCP tool.
        #[arg(long, value_name = "PATH")]
        impact_closure: Option<String>,

        /// Compute exact-symbol consumers, affected files, and targeted tests.
        #[arg(long, value_name = "FILE:EXPORT")]
        symbol_impact: Option<String>,

        /// Show only the top N items per category. Human output only: the JSON,
        /// SARIF, and CodeClimate envelopes drive exit codes and CI baselines,
        /// so they always carry every finding and a consumer slices the arrays
        /// itself.
        #[arg(long)]
        top: Option<usize>,

        /// Only report issues in the specified file(s). Accepts multiple values.
        /// The full project graph is still built, but only issues in matching files
        /// are reported. Useful for lint-staged pre-commit hooks.
        #[arg(long, value_name = "PATH")]
        file: Vec<std::path::PathBuf>,
    },

    /// Watch for changes and re-run analysis
    Watch {
        /// Don't clear the screen between re-analyses
        #[arg(long)]
        no_clear: bool,
    },

    /// Inspect the optional TypeScript semantic companion.
    TypeAware {
        #[command(subcommand)]
        subcommand: TypeAwareCli,
    },

    /// Diagnose project readiness without analysis or mutation.
    ///
    /// Checks the root, config resolution, workspace discovery, external
    /// plugins, and the optional type-aware companion. Uses only local reads;
    /// it performs no cache writes, telemetry, network requests, or third-party
    /// execution. Supports human and JSON output.
    #[command(override_help = doctor::HELP)]
    Doctor,

    /// Find semantically similar functions with a pinned local model (opt-in).
    ///
    /// Results are unverified candidates. The model score is not a probability,
    /// gate, vulnerability verdict, or safe-refactor decision. Model setup is
    /// explicit, and project source remains local and offline during analysis.
    SimilarCode {
        #[command(subcommand)]
        subcommand: Option<similar_code_cli::SimilarCodeSubcommand>,
        /// Minimum cosine similarity retained as an unverified candidate.
        #[arg(long, value_name = "0..1")]
        threshold: Option<f64>,
        /// Minimum source lines per extracted function.
        #[arg(long, value_name = "N")]
        min_lines: Option<usize>,
        /// Cap displayed candidates after bounded full-corpus comparison.
        #[arg(long, value_name = "N")]
        top: Option<usize>,
        /// Report pairs touching one of these project-relative files.
        #[arg(long, value_name = "PATH")]
        file: Vec<PathBuf>,
    },

    /// Inspect one file or exported symbol as a bundled evidence query
    Inspect {
        /// File to inspect.
        #[arg(
            long,
            value_name = "PATH",
            conflicts_with = "symbol",
            required_unless_present = "symbol"
        )]
        file: Option<String>,

        /// Exported symbol to inspect, formatted as FILE:EXPORT.
        #[arg(long, value_name = "FILE:EXPORT", conflicts_with = "file")]
        symbol: Option<String>,

        /// OPT-IN: also attach the best-effort symbol-level call chain
        /// (`fallow trace`) as the `symbol_chain` evidence section. Only
        /// meaningful for a `--symbol` target. Default off (best-effort,
        /// syntactic, OFF the ranked path).
        #[arg(long)]
        symbol_chain: bool,

        /// OPT-IN: attach target-level git churn evidence from the health
        /// hotspot subsystem. Default off to avoid git-history latency.
        #[arg(long)]
        churn: bool,
    },

    /// Trace a symbol's call chain, or the shortest import path between two
    /// modules (best-effort, syntactic; OFF the ranked path)
    ///
    /// Walks callers UP (modules that import the symbol) and callees DOWN
    /// (import-symbol edges + intra-module call sites) via the module graph,
    /// bounded by `--depth`. Symbol-level chains are labeled best-effort per
    /// ADR-001: resolved-vs-unresolved callees are reported honestly, never
    /// silently dropped. The result is its OWN surface, NOT folded into the
    /// ranked brief and NEVER an input to the focus map / ranking.
    ///
    /// `--path <FROM> <TO>` answers a different question: the shortest chain of
    /// imports by which one module reaches another. Type-only hops are reported
    /// rather than skipped, and an unreachable pair reports `reachable: false`
    /// instead of an error.
    Trace {
        /// Target symbol, formatted as FILE:SYMBOL (e.g. src/utils.ts:formatDate).
        /// Omitted when `--path` is used.
        #[arg(value_name = "FILE:SYMBOL", required_unless_present = "path")]
        symbol: Option<String>,

        /// Shortest import path between two modules, as two file paths
        /// (e.g. `--path src/app.ts src/db.ts`). Mutually exclusive with the
        /// symbol target and the call-chain flags.
        #[arg(
            long,
            num_args = 2,
            value_names = ["FROM", "TO"],
            conflicts_with_all = ["symbol", "callers", "callees", "depth"]
        )]
        path: Vec<String>,

        /// Walk UP to callers (modules that import the symbol). When neither
        /// `--callers` nor `--callees` is set, both directions are walked.
        #[arg(long)]
        callers: bool,

        /// Walk DOWN to callees (the symbol's module's import-symbol edges plus
        /// unresolved call sites). When neither flag is set, both are walked.
        #[arg(long)]
        callees: bool,

        /// Chain depth bound for both directions (default 2). Symbol-level is
        /// best-effort, so a shallow bound keeps the trace legible.
        #[arg(long, value_name = "N")]
        depth: Option<u32>,
    },

    /// Resolve a runtime stack trace's frames to the definitions they name
    /// (best-effort, syntactic; OFF the ranked path)
    ///
    /// Reads a V8 / Node or SpiderMonkey / JavaScriptCore stack trace from a
    /// file or from stdin, classifies every frame as in-project,
    /// node-modules, or out-of-corpus, and asks the module graph which
    /// definitions the in-project frames name.
    ///
    /// The result refuses to overclaim. A frame matching several definitions
    /// reports `ambiguous` and lists all of them rather than picking one; a
    /// frame matching nothing reports `not_found` rather than disappearing; a
    /// frame the graph was never asked about reports `not_attempted`. Every
    /// frame read stays in the array in input order and `counts` publishes the
    /// per-outcome totals, so a caller can see what went unanswered.
    ///
    /// No source maps are read. A frame inside generated build output is
    /// reported as such, because a stale map rebinds silently to the wrong
    /// line.
    #[command(name = "trace-error")]
    TraceError {
        /// Stack trace file, or `-` to read stdin. Defaults to stdin. A
        /// relative path is resolved against the project root, matching
        /// `--diff-file`.
        #[arg(value_name = "FILE")]
        trace_file: Option<String>,
    },

    /// Auto-fix issues: remove unused exports, dependencies, and enum
    /// members; add duplicate-export rules to a fallow config file.
    ///
    /// When no fallow config exists outside a monorepo subpackage, a
    /// fresh `.fallowrc.json` is created from the same scaffolding
    /// `fallow init` would emit (framework detection, `$schema`,
    /// `entry`, etc.) and the duplicate-export rules are layered on
    /// top. Inside a monorepo subpackage the create-fallback refuses
    /// and points at the workspace root. Pass `--no-create-config` to
    /// opt out of the create-fallback (recommended for pre-commit
    /// hooks, CI bots, and `fallow watch`).
    ///
    /// Use `--dry-run` to preview source-file edits and config-file
    /// diffs without writing.
    Fix {
        /// Dry run, show what would be changed without modifying files
        #[arg(long)]
        dry_run: bool,

        /// Skip confirmation prompt (required in non-TTY environments like CI or AI agents)
        #[arg(long, alias = "force")]
        yes: bool,

        /// Refuse to create a new fallow config file when none exists.
        /// Use this from pre-commit hooks, CI bots, and `fallow watch`
        /// where silently materialising a new top-level config file would
        /// surprise the user. The duplicate-export config-add path is
        /// skipped with an explanatory message; source-file edits proceed
        /// normally.
        #[arg(long)]
        no_create_config: bool,
    },

    /// Initialize a .fallowrc.json configuration file, AGENTS.md guide, or git
    /// pre-commit hook. Use `.fallowrc.jsonc` for editor-native JSON-with-comments
    /// support; both extensions are auto-discovered.
    ///
    /// `--hooks` scaffolds a shell-level Git pre-commit hook under
    /// `.git/hooks/` that runs fallow on changed files. The clearer hook
    /// namespace is `fallow hooks install --target git`; `init --hooks`
    /// remains as a convenience during project initialization.
    Init {
        /// Generate TOML instead of JSONC
        #[arg(long)]
        toml: bool,

        /// Scaffold a starter AGENTS.md guidance file for coding agents
        #[arg(long, conflicts_with_all = ["toml", "hooks", "branch"])]
        agents: bool,

        /// Scaffold a shell-level pre-commit git hook in `.git/hooks/` that
        /// runs fallow on changed files. Alias for
        /// `fallow hooks install --target git`.
        #[arg(long)]
        hooks: bool,

        /// Fallback base branch/ref for the pre-commit hook when no upstream is set
        #[arg(long, requires = "hooks")]
        branch: Option<String>,

        /// Record that this project deliberately stays unconfigured: persists a
        /// decline so the first-contact setup hint and the `setup` next-step
        /// stop appearing here. Writes no config file; idempotent
        #[arg(long, conflicts_with_all = ["toml", "agents", "hooks", "branch"])]
        decline: bool,
    },

    /// Install or remove fallow-managed Git and agent hooks.
    ///
    /// Use `fallow hooks install --target git` for a shell-level Git
    /// pre-commit hook. Use `fallow hooks install --target agent` for a
    /// Claude Code / Codex gate that blocks agent `git commit` / `git push`
    /// commands until `fallow audit` passes.
    Hooks {
        #[command(subcommand)]
        subcommand: HooksCli,
    },

    /// Wire fallow into the coding-agent harnesses used by this project in
    /// one pass (AGENTS.md task map, skill, MCP server, commit/push gate), or
    /// show and remove what was installed. `fallow init --agents` and
    /// `fallow hooks install --target agent` remain the single-piece
    /// commands underneath.
    Agent {
        #[command(subcommand)]
        subcommand: AgentCli,
    },

    /// CI helpers for PR/MR feedback envelopes.
    Ci {
        #[command(subcommand)]
        subcommand: CiCli,
    },

    /// Print the JSON Schema for fallow configuration files
    ConfigSchema,

    /// Print the JSON Schema for external plugin files
    PluginSchema,

    /// Dry-run external plugins: report what each activated and seeded
    PluginCheck,

    /// Print the JSON Schema for rule pack files
    RulePackSchema,

    /// Manage declarative rule packs (policy-as-code)
    RulePack {
        #[command(subcommand)]
        subcommand: RulePackCli,
    },

    /// Show which architecture rules apply to files before changing them.
    Guard {
        /// Files to report on (root-relative or absolute; may not exist yet)
        #[arg(required = true, num_args = 1..)]
        files: Vec<String>,
    },

    /// Show the resolved config and which config file was loaded
    ///
    /// Walks up from the project root looking for `.fallowrc.json`,
    /// `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`, resolves `extends`, and prints
    /// the final config as JSON. Use `--path` to print only the config
    /// file path (useful in shell scripts). The default view always exits 0:
    /// it prints the loaded config, or, on a zero-config project, the effective
    /// defaults (fully supported). `--path` exits 3 when no config file exists,
    /// since there is no path to report.
    ///
    /// Precedence is first-match-wins per directory, in the order
    /// `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`,
    /// walking up to the workspace root. `.fallowrc.json` accepts JSONC
    /// (comments and trailing commas); `.fallowrc.jsonc` is identical in
    /// behavior, the extension only signals to editors that comments are
    /// expected. If two config files coexist in one directory, fallow loads the
    /// higher-precedence one and warns on stderr naming the file it ignored.
    Config {
        /// Print only the config file path (one line, no JSON)
        #[arg(long)]
        path: bool,
    },

    /// Recommend a project-tailored config for an agent to author.
    ///
    /// Read-only. Inspects the project (frameworks, workspace layout, tooling)
    /// and emits what fallow detected, a safe proposed config, and a list of
    /// decisions split into auto (decided from detection), default (a disclosed
    /// overridable default), and taste (a genuinely subjective choice surfaced
    /// to the user as an open question). Honors `--root` and `--format`.
    Recommend,

    /// List discovered entry points, files, plugins, boundaries, and workspaces.
    List {
        /// Show entry points
        #[arg(long)]
        entry_points: bool,

        /// Show all discovered files
        #[arg(long)]
        files: bool,

        /// Show active plugins
        #[arg(long)]
        plugins: bool,

        /// Show architecture boundary zones, rules, and per-zone file counts
        #[arg(long)]
        boundaries: bool,

        /// Show monorepo workspaces and any workspace-discovery diagnostics
        /// (malformed package.json, unreachable glob matches, missing
        /// tsconfig references).
        #[arg(long)]
        workspaces: bool,
    },

    /// Show monorepo workspaces and any workspace-discovery diagnostics.
    ///
    /// Equivalent to `fallow list --workspaces`. Use this dedicated form
    /// when introspecting only the workspace topology (other `list`
    /// sections stay hidden).
    Workspaces,

    /// Find code duplication / clones across the project
    Dupes {
        /// Detection mode: strict, mild, weak, or semantic
        /// (defaults to the value in `.fallowrc.jsonc`, or `mild` if unset).
        #[arg(long)]
        mode: Option<DupesMode>,

        /// Enable function-scoped near-miss clone detection.
        #[arg(long)]
        near: bool,

        /// Minimum token count for a clone
        /// (defaults to the value in `.fallowrc.jsonc`, or `50` if unset).
        #[arg(long)]
        min_tokens: Option<usize>,

        /// Minimum line count for a clone
        /// (defaults to the value in `.fallowrc.jsonc`, or `5` if unset).
        #[arg(long)]
        min_lines: Option<usize>,

        /// Minimum number of occurrences before a clone group is reported.
        /// Raise to focus on widespread copy-paste worth refactoring and skip
        /// pair-only clones.
        /// (defaults to the value in `.fallowrc.jsonc`, or `2` if unset).
        #[arg(long, value_parser = parse_min_occurrences)]
        min_occurrences: Option<usize>,

        /// Fail if duplication exceeds this percentage (0 = no limit)
        /// (defaults to the value in `.fallowrc.jsonc`, or `0` if unset).
        #[arg(long)]
        threshold: Option<f64>,

        /// Only report cross-directory duplicates
        #[arg(long)]
        skip_local: bool,

        /// Enable cross-language detection (strip TS type annotations for TS↔JS matching)
        #[arg(long)]
        cross_language: bool,

        /// Exclude module wiring from clone detection (default; covers imports,
        /// re-exports, and top-level static require bindings). Pass
        /// `--no-ignore-imports` to count it again.
        #[arg(long)]
        ignore_imports: bool,

        /// Count module wiring as clone candidates (opt out of the default
        /// exclusion).
        #[arg(long, conflicts_with = "ignore_imports")]
        no_ignore_imports: bool,

        /// Show only the N highest-ranked clone groups. Ranking combines clone
        /// size, occurrence count, and capped directory or line spread.
        /// `clone_families[]` is rebuilt from the groups that survive, so it
        /// narrows too. `stats` keeps describing the whole corpus;
        /// `clone_groups_shown` / `clone_groups_omitted` and
        /// `clone_families_shown` / `clone_families_omitted` report the split.
        /// Refused with exit code 2 alongside `--group-by`: grouped output
        /// reports per-bucket stats over every clone group in the bucket, which
        /// a global top-N truncation would silently contradict.
        #[arg(long)]
        top: Option<usize>,

        /// Omit the verbatim source text from each clone instance in
        /// `--format json`. The file and line/column range still address the
        /// same code, and this is most of the payload on a duplicated codebase.
        #[arg(long)]
        no_fragments: bool,

        /// Trace all clones at a specific location (format: `FILE:LINE`)
        #[arg(long, value_name = "FILE:LINE")]
        trace: Option<String>,
    },

    /// Analyze function complexity (cyclomatic + cognitive)
    ///
    /// By default, shows all existing sections: health score, complexity findings,
    /// file scores, hotspots, and refactoring targets. When any section flag is
    /// specified, only those sections are shown.
    Health {
        /// Maximum cyclomatic complexity threshold (overrides config)
        #[arg(long)]
        max_cyclomatic: Option<u16>,

        /// Maximum cognitive complexity threshold (overrides config)
        #[arg(long)]
        max_cognitive: Option<u16>,

        /// Maximum CRAP score threshold (overrides config, default 30.0).
        /// Functions meeting or exceeding this score are reported alongside
        /// complexity findings. Pair with `--coverage` for accurate scoring.
        #[arg(long)]
        max_crap: Option<f64>,

        /// Show only the N most complex functions
        #[arg(long)]
        top: Option<usize>,

        /// Sort by: cyclomatic (default), cognitive, lines, or severity
        #[arg(long, default_value = "cyclomatic")]
        sort: SortBy,

        /// Show only complexity findings (functions exceeding thresholds).
        /// By default all sections are shown; use this to select only complexity.
        #[arg(long)]
        complexity: bool,

        /// Include the per-decision-point complexity breakdown (`contributions[]`)
        /// on each complexity finding in `--format json` output. Each entry names
        /// the construct (if, else-if, loop, boolean operator, ...) and its
        /// cyclomatic/cognitive weight, so a consumer can explain WHY a function
        /// scored high. Used by the VS Code inline editor breakdown. Off by
        /// default to keep CI/default output lean.
        #[arg(long)]
        complexity_breakdown: bool,

        /// Show only per-file health scores (fan-in, fan-out, dead code ratio, maintainability index).
        /// Requires full analysis pipeline (graph + dead code detection).
        /// Sorted by risk-aware triage concern: lower MI and higher CRAP risk first.
        /// --sort and --baseline apply to complexity findings only, not file scores.
        #[arg(long)]
        file_scores: bool,

        /// Show only static test coverage gaps: runtime files and exports with no
        /// dependency path from any discovered test root. Requires full analysis pipeline.
        #[arg(long)]
        coverage_gaps: bool,

        /// Show only hotspots: files that are both complex and frequently changing.
        /// Combines git churn history with complexity data. Requires a git repository.
        #[arg(long)]
        hotspots: bool,

        /// Attach ownership signals to hotspot entries: bus factor, contributor
        /// count, declared CODEOWNERS owner, and ownership drift. Implies
        /// `--hotspots`. Requires a git repository.
        #[arg(long)]
        ownership: bool,

        /// Privacy mode for author emails emitted with `--ownership`.
        /// Defaults to `handle` (local-part only). Use `raw` for OSS repos
        /// where authors are public, or `anonymized` to emit non-reversible
        /// pseudonyms in regulated environments. Implies `--ownership`.
        #[arg(long, value_name = "MODE", value_enum)]
        ownership_emails: Option<EmailModeArg>,

        /// Show only refactoring targets: ranked recommendations based on complexity,
        /// coupling, churn, and dead code signals. Requires full analysis pipeline.
        #[arg(long)]
        targets: bool,

        /// Show advisory project-local public-signature type coupling. Requires
        /// type-aware analysis and does not change the health score.
        #[arg(long)]
        type_coupling: bool,

        /// Add structural CSS analytics: specificity hotspots, !important density,
        /// over-complex selectors, deep nesting, and conservative cleanup
        /// candidates. Standard CSS is parsed structurally; preprocessor sources
        /// are scanned only where fallow can avoid expanding Sass/Less semantics.
        #[arg(long)]
        css: bool,

        /// Filter refactoring targets by effort level (low, medium, high).
        /// Implies --targets.
        #[arg(long, value_enum)]
        effort: Option<EffortFilter>,

        /// Show only the project health score (0–100) with letter grade (A/B/C/D/F).
        /// The score is included by default when no section flags are set.
        #[arg(long)]
        score: bool,

        /// Fail if the health score is below this threshold (0-100).
        /// Implies --score. The authoritative CI quality gate: when set,
        /// complexity findings become informational and the exit code is
        /// driven solely by the score (so --min-score 0 always exits 0).
        /// Composes with --min-severity (fails if either gate trips). Plain
        /// `fallow health` (no gate flag) stays advisory and exits 1 on any
        /// finding; for a gate on newly-introduced complexity use
        /// `fallow audit --gate new-only`.
        #[arg(long, value_name = "N")]
        min_score: Option<f64>,

        /// Only exit with error for findings at or above this severity.
        /// Use --min-severity critical to ignore moderate/high findings in CI.
        /// Composes with --min-score (the run fails if either gate trips).
        #[arg(long, value_name = "LEVEL", value_enum)]
        min_severity: Option<HealthSeverityCli>,

        /// Print the score and findings but never fail CI (always exit 0).
        /// Advisory mode for surfacing health in logs without blocking.
        /// Mutually exclusive with --min-score and --min-severity.
        #[arg(long)]
        report_only: bool,

        /// Git history window for hotspot analysis (default: 6m).
        /// Accepts durations (6m, 90d, 1y, 2w) or ISO dates (2025-06-01).
        #[arg(long, value_name = "DURATION")]
        since: Option<String>,

        /// Minimum number of commits for a file to be included in hotspot ranking (default: 3)
        #[arg(long, value_name = "N")]
        min_commits: Option<u32>,

        /// Save a vital signs snapshot for trend tracking.
        /// Defaults to `.fallow/snapshots/{timestamp}.json` if no path is given.
        /// Forces file-scores, hotspot, and score computation for complete metrics.
        #[expect(
            clippy::option_option,
            reason = "clap pattern: None=not passed, Some(None)=flag only, Some(Some(path))=with value"
        )]
        #[arg(long, value_name = "PATH", num_args = 0..=1, default_missing_value = "")]
        save_snapshot: Option<Option<String>>,

        /// Compare current metrics against the most recent saved snapshot.
        /// Reads from `.fallow/snapshots/` and shows per-metric deltas with
        /// directional indicators. Implies --score.
        #[arg(long)]
        trend: bool,

        /// Path to coverage data (coverage-final.json) for exact per-function
        /// CRAP scores. Generate with `jest --coverage`, `vitest run --coverage
        /// --provider istanbul`, or any Istanbul-compatible tool. Requires
        /// Istanbul format (not v8/c8 native format). Accepts a single
        /// Istanbul coverage map JSON file or a directory containing
        /// coverage-final.json. Use --coverage-root when the file was generated
        /// in a different environment (CI runner, Docker). Affects CRAP scores
        /// only, not --coverage-gaps. Also configurable via FALLOW_COVERAGE env var.
        #[arg(long, value_name = "PATH")]
        coverage: Option<PathBuf>,

        /// Absolute prefix to strip from file paths in coverage data before
        /// prepending the project root. Use when coverage was generated in a
        /// different environment (CI runner, Docker). Example: if coverage paths
        /// start with /home/runner/work/myapp and the project root is ./,
        /// pass --coverage-root /home/runner/work/myapp.
        #[arg(long, value_name = "PATH")]
        coverage_root: Option<PathBuf>,

        /// File or directory containing runtime coverage input. Accepts a
        /// V8 coverage directory, a single V8 JSON file, or a single
        /// Istanbul coverage map JSON file (commonly coverage-final.json).
        #[arg(long, value_name = "PATH")]
        runtime_coverage: Option<PathBuf>,

        /// Threshold for hot-path classification
        #[arg(long, default_value_t = 100)]
        min_invocations_hot: u64,

        /// Minimum total trace volume before the sidecar allows high-confidence
        /// `safe_to_delete` / `review_required` verdicts. Below this the
        /// sidecar caps confidence at `medium` to protect against overconfident
        /// verdicts on new or low-traffic services. Omit to use the sidecar's
        /// spec default (5000).
        #[arg(long, value_name = "N")]
        min_observation_volume: Option<u32>,

        /// Fraction of total trace count below which an invoked function is
        /// classified as `low_traffic` rather than `active`. Expressed as a
        /// decimal (e.g. `0.001` for 0.1%). Omit to use the sidecar's spec
        /// default (0.001).
        #[arg(long, value_name = "RATIO")]
        low_traffic_threshold: Option<f64>,
    },

    /// Detect feature flag patterns in the codebase
    ///
    /// Identifies environment variable flags (process.env.FEATURE_*),
    /// SDK calls from common providers, and config object patterns (opt-in).
    /// Reports flag locations, detection confidence, and cross-reference
    /// with dead code findings.
    Flags {
        /// Show only the top N flags
        #[arg(long)]
        top: Option<usize>,
    },

    /// List active fallow-ignore suppression markers (read-only inventory)
    ///
    /// Shows every `fallow-ignore-next-line` and `fallow-ignore-file` marker
    /// present in analyzed files, grouped per file with line, kind, level,
    /// and reason, plus project totals and a stale cross-reference against
    /// this run's stale-suppression findings. A governance surface, not a
    /// detector: always exits 0. Honors `--root`, `--format {human,json}`,
    /// `--workspace`, `--changed-workspaces`, `--changed-since`, and
    /// `--quiet`.
    Suppressions {
        /// Only list suppressions in the specified files. Accepts multiple values.
        #[arg(long, value_name = "PATH")]
        file: Vec<std::path::PathBuf>,
    },

    /// Explain one fallow issue type without running an analysis.
    ///
    /// Prints the rule rationale, a worked example, fix guidance, and the
    /// relevant docs URL. Accepts values like `unused-export`,
    /// `fallow/unused-export`, `unused exports`, and `code duplication`.
    Explain {
        /// Issue type, issue label, or rule id to explain
        #[arg(required = true, num_args = 1.., value_name = "ISSUE_TYPE")]
        issue_type: Vec<String>,
    },

    /// Audit changed files for dead code, complexity, duplication, and styling.
    ///
    /// Purpose-built for reviewing AI-generated code and PR quality gates.
    /// Combines dead-code + complexity + duplication + styling scoped to
    /// changed files and returns a verdict (pass/warn/fail).
    ///
    /// `fallow audit` answers "will CI block this?": it gates (exit 1 on a
    /// fail verdict). The `review` alias plus `--brief` answer "where do I
    /// look?": the same analysis rendered as a deterministic orientation brief
    /// that ALWAYS exits 0, so a reviewer or agent can read it regardless of
    /// the verdict. `--format` is orthogonal to `--brief`.
    /// When `--changed-since`/`--base` is unset, the base is the git merge-base
    /// against the branch's upstream or the remote default (`origin/HEAD`,
    /// `origin/main`, `origin/master`); set `FALLOW_AUDIT_BASE` to pin it.
    /// By default, only findings introduced by the changeset affect the verdict;
    /// inherited findings are reported with new-vs-inherited attribution and
    /// individual JSON findings include `introduced: true/false`. Use
    /// `--gate all` or `[audit] gate = "all"` to fail on every finding in
    /// changed files without running the extra base-snapshot attribution pass.
    ///
    /// The global --baseline / --save-baseline flags are rejected on audit.
    /// Use --dead-code-baseline, --health-baseline, and --dupes-baseline
    /// (or their config equivalents) because each sub-analysis uses a
    /// different baseline format.
    #[command(visible_alias = "review")]
    Audit {
        /// Run dead-code analysis in production mode for this audit.
        #[arg(long = "production-dead-code")]
        production_dead_code: bool,

        /// Run health analysis in production mode for this audit.
        #[arg(long = "production-health")]
        production_health: bool,

        /// Run duplication analysis in production mode for this audit.
        #[arg(long = "production-dupes")]
        production_dupes: bool,

        /// Compare dead-code issues against a saved baseline
        /// (produced by `fallow dead-code --save-baseline`).
        #[arg(long)]
        dead_code_baseline: Option<PathBuf>,

        /// Compare health findings against a saved baseline
        /// (produced by `fallow health --save-baseline`).
        #[arg(long)]
        health_baseline: Option<PathBuf>,

        /// Compare duplication clone groups against a saved baseline
        /// (produced by `fallow dupes --save-baseline`).
        #[arg(long)]
        dupes_baseline: Option<PathBuf>,

        /// Maximum CRAP score threshold (overrides config, default 30.0).
        /// Functions meeting or exceeding this score cause audit to fail.
        /// Pair with `--coverage` for accurate scoring.
        #[arg(long)]
        max_crap: Option<f64>,

        /// Path to Istanbul-format coverage data (coverage-final.json) for
        /// accurate per-function CRAP scores in the health sub-analysis. Also
        /// configurable via FALLOW_COVERAGE or health.coverage.
        #[arg(long, value_name = "PATH")]
        coverage: Option<PathBuf>,

        /// Absolute prefix to strip from coverage data paths before CRAP matching.
        /// Use when coverage was generated under a different checkout root in CI or Docker.
        /// Also configurable via FALLOW_COVERAGE_ROOT or health.coverageRoot.
        #[arg(long, value_name = "PATH")]
        coverage_root: Option<PathBuf>,

        /// Disable styling analytics in audit.
        #[arg(long = "no-css")]
        no_css: bool,

        /// Enable deep CSS analysis for audit explicitly: project-wide styling
        /// reachability, narrowed back to changed anchors. Deep CSS is on by
        /// default; use this to override `audit.cssDeep = false`.
        #[arg(long)]
        css_deep: bool,

        /// Disable deep CSS analysis while keeping local styling analytics on.
        #[arg(long = "no-css-deep")]
        no_css_deep: bool,

        /// Which findings affect the audit verdict.
        ///
        /// new-only (default): fail only on findings introduced by the current
        /// changeset. all: fail on every finding in changed files and skip
        /// base-snapshot attribution.
        #[arg(long, value_enum)]
        gate: Option<AuditGateArg>,

        /// Paid runtime-coverage sidecar input. Accepts a V8 directory, a
        /// single V8 JSON file, or an Istanbul coverage map JSON. Spawns
        /// the `fallow-cov` sidecar as part of the audit pipeline so the
        /// `hot-path-touched` verdict surfaces alongside dead-code and
        /// complexity findings without requiring a second `fallow health`
        /// invocation in CI. License-gated; the verdict is informational
        /// (no exit code change) until a future `--gate hot-path-touched`
        /// knob lands.
        #[arg(long, value_name = "PATH")]
        runtime_coverage: Option<PathBuf>,

        /// Threshold for hot-path classification, forwarded to the sidecar
        /// when `--runtime-coverage` is set.
        #[arg(long, default_value_t = 100)]
        min_invocations_hot: u64,

        /// Internal marker identifying a gate run (e.g. `pre-commit`), set by
        /// the generated git hook so Fallow Impact can record a containment
        /// event when the gate blocks then clears. Hidden; never changes the
        /// verdict, exit code, or output.
        #[arg(long, value_name = "MARKER", hide = true)]
        gate_marker: Option<String>,

        /// Render the deterministic review brief instead of the gating audit
        /// report. The brief answers "where do I look?" rather than "will CI
        /// block this?", runs the same analysis, and ALWAYS exits 0 (the
        /// verdict is carried informationally). Implied by `fallow review`.
        /// Orthogonal to `--format`.
        #[arg(long)]
        brief: bool,

        /// Cap on the number of consequential structural decisions surfaced in
        /// the review brief's decision surface (the working-memory limit).
        /// Default 4; clamped to the 3-5 band (4 plus or minus 1). Only
        /// consulted on the brief path.
        #[arg(
            long,
            value_name = "N",
            default_value_t = audit_decision_surface::DEFAULT_DECISION_CAP
        )]
        max_decisions: usize,

        /// Emit the agent-contract WALKTHROUGH GUIDE: the current digest
        /// (brief + decision surface), the review direction, the JSON schema the
        /// agent must return, and a deterministic graph-snapshot hash pinned into
        /// the digest. The digest is built from the graph only (PR prose is never
        /// folded in, so it is injection-resistant). Implies the brief; always
        /// exits 0. A thin agent skill calls this to fetch the current guide,
        /// produces judgment JSON, then reopens with `--walkthrough-file`.
        #[arg(long, conflicts_with_all = ["walkthrough_file", "walkthrough"])]
        walkthrough_guide: bool,

        /// Ingest an agent's judgment JSON and POST-VALIDATE it against the
        /// LIVE graph. Rejects any judgment whose `signal_id` fallow did not emit
        /// (anti-hallucination); refuses the whole payload as stale when the
        /// echoed graph-snapshot hash no longer matches (the tree moved); rejects
        /// an `action` outside `block`, `address`, `consider`, `fyi`
        /// (`invalid-action`). The verifier is the graph, not a second model.
        /// Implies the brief; always exits 0. The agent's free-text framing and
        /// action label are fenced as non-deterministic and never gate or
        /// auto-post.
        #[arg(long, value_name = "PATH")]
        walkthrough_file: Option<PathBuf>,

        /// Render the existing walkthrough guide as a staged HUMAN terminal tour
        /// (Stage 1 load-bearing / Stage 2 mechanical), or markdown with
        /// `--format markdown`. Implies the brief; always exits 0.
        /// `--format json --walkthrough` emits the same agent-contract JSON as
        /// `--walkthrough-guide`.
        #[arg(long, conflicts_with_all = ["walkthrough_guide", "walkthrough_file"])]
        walkthrough: bool,

        /// Record one or more changed files as VIEWED in the local walkthrough
        /// viewed-state ledger (`.fallow/walkthrough-state.json`), then render the
        /// tour. Files already viewed (and still current) collapse into the
        /// Cleared panel. Repeatable. Stale marks (the tree moved) are ignored on
        /// render but never deleted. Only consulted on the `--walkthrough` path.
        #[arg(long, value_name = "PATH")]
        mark_viewed: Vec<PathBuf>,

        /// Expand the Cleared panel in the human/markdown walkthrough tour: list
        /// each de-prioritized and already-viewed file instead of the collapsed
        /// one-line summary. Only consulted on the `--walkthrough` path.
        #[arg(long)]
        show_cleared: bool,

        /// Expand the de-prioritized units in the review brief's weighted
        /// focus map ("show me what you de-prioritized"). The `deprioritized`
        /// escape-hatch list is ALWAYS present in `--format json` regardless; this
        /// flag only re-expands the collapse-by-default human focus render. Only
        /// consulted on the brief path.
        #[arg(long)]
        show_deprioritized: bool,
    },

    /// Maintain reusable audit base-snapshot caches.
    AuditCache {
        #[command(subcommand)]
        subcommand: AuditCacheCli,
    },

    /// Surface the consequential structural DECISIONS a change embeds (the apex
    /// of the review brief), each framed as a judgment question with the routed
    /// expert to ask.
    ///
    /// The product's decision surface: a ranked, capped (4 plus or minus 1),
    /// signal_id-anchored set of the SOLID-3 decisions (coupling/boundary,
    /// exports-aware public-API/contract, dependency). Runs the same changed-code
    /// analysis as `fallow review` but emits ONLY the decisions, separable and
    /// cheap. Coupling and public-API decisions are suppressible with
    /// `// fallow-ignore`; a dependency decision anchors on `package.json` and
    /// has no suppress action. Always
    /// exits 0 (advisory, never a gate). Use `--base` / `--changed-since` to pick
    /// the comparison point, exactly like `fallow audit`.
    DecisionSurface {
        /// Cap on the number of surfaced decisions (the working-memory limit).
        /// Default 4; clamped to the 3-5 band (4 plus or minus 1).
        #[arg(
            long,
            value_name = "N",
            default_value_t = audit_decision_surface::DEFAULT_DECISION_CAP
        )]
        max_decisions: usize,
    },

    /// Show what fallow has done for you: how many issues it is surfacing, the
    /// trend since the last recorded run, and how many commits it contained at
    /// the pre-commit gate.
    ///
    /// Local-only and opt-in: enable per project with `fallow impact enable`, or
    /// turn it on everywhere with `fallow impact default on`, then let your
    /// `fallow audit` / pre-commit gate runs build history. History is stored in
    /// your user config dir (never written into the repo) and forced off in CI.
    /// Impact never uploads anything and never affects exit codes.
    Impact {
        #[command(subcommand)]
        subcommand: Option<ImpactCli>,
        /// Aggregate every tracked project into one cross-repo roll-up
        /// ("what has fallow done for me across all my repos"). Reads the
        /// user config dir; ignores `--root`. Cannot combine with a subcommand.
        #[arg(long)]
        all: bool,
        /// Row ordering for `--all` (default: most recently recorded first).
        #[arg(long, value_enum, default_value_t = ImpactSortCli::Recent)]
        sort: ImpactSortCli,
        /// Cap the number of `--all` rows printed (grand totals still reflect
        /// every tracked project).
        #[arg(long)]
        limit: Option<usize>,
    },

    /// Surface local security candidates for downstream agent verification (opt-in).
    ///
    /// Ships three complementary surfaces. (1) The graph-structural
    /// `client-server-leak` rule: a `"use client"` file that transitively imports
    /// a module reading a non-public env secret through `process.env` or
    /// `import.meta.env`. (2) The data-driven
    /// `tainted-sink` catalogue: syntactic sink sites matched against a CWE
    /// catalogue (`security_matchers.toml`) spanning categories such as
    /// dangerous-html, template-escape-bypass, command-injection, code-injection,
    /// dynamic-regex, redos-regex, resource-amplification, dynamic-module-load,
    /// sql-injection, ssrf, path-traversal, header-injection, open-redirect,
    /// cleartext-transport, electron-unsafe-webpreferences,
    /// world-writable-permission, insecure-temp-file,
    /// mysql-multiple-statements, mass-assignment, weak-crypto,
    /// deprecated-cipher, insecure-randomness,
    /// unsafe-buffer-alloc, unsafe-deserialization, prototype-pollution,
    /// zip-slip, nosql-injection, ssti, xxe, xpath-injection, and
    /// webview-injection. (3) `hardcoded-secret`,
    /// an include-required
    /// category for provider-prefix literals and high-entropy literals assigned
    /// to secret-shaped identifiers. It never runs from raw entropy alone. All
    /// findings are CANDIDATES for verification, NOT verified vulnerabilities.
    /// This command is the only
    /// surface for security findings; they never appear under bare `fallow` or
    /// the `audit` gate. Build-config and test files are excluded, and public
    /// env prefixes such as `NEXT_PUBLIC_` and `VITE_` are treated as public.
    /// Honors
    /// `--root`, `--format {human,json,sarif}`, `--changed-since`, `--file`, `--gate`, `--diff-file`,
    /// `--diff-stdin`, `--workspace`, `--changed-workspaces`, `--ci`,
    /// `--fail-on-issues`, `--sarif-file`, `--summary`, `--explain`, and `--surface`.
    Security {
        #[command(subcommand)]
        subcommand: Option<SecuritySubcommand>,
        /// Paid runtime-coverage sidecar input. Accepts a V8 directory, a
        /// single V8 JSON file, or an Istanbul coverage map JSON. When set,
        /// `fallow security` annotates tainted-sink candidates with production
        /// runtime state and uses that state as an additive ranking signal.
        #[arg(long, value_name = "PATH")]
        runtime_coverage: Option<PathBuf>,
        /// Threshold for hot-path classification, forwarded to the sidecar
        /// when `--runtime-coverage` is set.
        #[arg(long, default_value_t = 100)]
        min_invocations_hot: u64,
        /// Only report security candidates in or reachable from the specified files.
        /// The full project graph is still built, but output is scoped to matching
        /// finding anchors or trace hops. Accepts multiple values.
        #[arg(long, value_name = "PATH")]
        file: Vec<std::path::PathBuf>,
        /// Opt-in regression gate: fail (exit 8) only when the change introduces a
        /// NEW security-sink candidate in the changed lines, not on the whole
        /// candidate backlog. Requires a diff source: `--changed-since <ref>`,
        /// `--diff-file <path>`, or `--diff-stdin`. There is deliberately no `all`
        /// mode (gating on the full backlog is the anti-feature this gate avoids).
        #[arg(long, value_name = "MODE")]
        gate: Option<security::SecurityGateArg>,
        /// Include the agent-facing attack-surface inventory in JSON output.
        #[arg(long)]
        surface: bool,
    },

    /// Render a saved `--format json` results file in another format without
    /// re-running analysis (analyze once, then render every CI surface from
    /// the same file). Supports GitHub annotations/summary, CodeClimate,
    /// SARIF, and GitHub/GitLab PR-comment and review formats.
    Report {
        /// Path to a fallow JSON results file produced by `--format json`
        /// (dead-code, dupes, health, audit, security, or bare combined).
        #[arg(long, value_name = "PATH")]
        from: PathBuf,
    },
    /// Dump fallow's capability manifest (CLI commands and flags, issue types, MCP tools, framework plugins, env vars) as machine-readable JSON for agent introspection. Always JSON, regardless of --format
    Schema,

    /// Print or vendor CI integration templates.
    ///
    /// Use `fallow ci-template gitlab` to print the GitLab CI template, or
    /// `fallow ci-template gitlab --vendor` to write the template plus the
    /// bash helper files that enable MR comments without downloading from
    /// raw.githubusercontent.com at pipeline runtime.
    CiTemplate {
        #[command(subcommand)]
        subcommand: CiTemplateCli,
    },

    /// Migrate configuration from knip, jscpd, or stylelint to fallow
    Migrate {
        /// Generate `fallow.toml` instead of JSONC
        #[arg(long, conflicts_with = "jsonc")]
        toml: bool,

        /// Write JSONC content to `.fallowrc.jsonc` instead of `.fallowrc.json`. The
        /// generated content is the same JSONC (with `//` comments) either way; the
        /// `.jsonc` extension lets editors auto-detect JSON-with-comments syntax
        /// highlighting and silences linters that flag comments in `.json`. Without
        /// `--jsonc` or `--toml`, fallow auto-mirrors the source extension: a
        /// `knip.jsonc` migration writes `.fallowrc.jsonc`, a `knip.json` migration
        /// writes `.fallowrc.json`.
        #[arg(long)]
        jsonc: bool,

        /// Only preview the generated config without writing
        #[arg(long)]
        dry_run: bool,

        /// Path to source config file (auto-detect if not specified)
        #[arg(long, value_name = "PATH")]
        from: Option<PathBuf>,
    },

    /// Manage the license for continuous/cloud runtime monitoring.
    ///
    /// Verification is offline against an Ed25519 public key compiled into
    /// the binary. The license file lives at `~/.fallow/license.jwt` (or
    /// `$FALLOW_LICENSE_PATH`); `$FALLOW_LICENSE` env var takes precedence
    /// and is the recommended path for shared CI runners.
    License {
        #[command(subcommand)]
        subcommand: LicenseCli,
    },

    /// Manage opt-in product telemetry.
    ///
    /// Telemetry is off by default. It never collects repository names, paths,
    /// package names, source code, config values, raw errors, or raw agent
    /// detection evidence. Use `fallow telemetry inspect --example` to see the
    /// documented payload shape, or prefix a real command with
    /// `FALLOW_TELEMETRY=inspect` to print the exact payload without sending.
    Telemetry {
        #[command(subcommand)]
        subcommand: TelemetryCli,
    },

    /// Runtime coverage workflow.
    ///
    /// `setup` is the resumable single-entry-point first-run flow: license
    /// check → sidecar install → coverage recipe → analysis. Spec:
    /// `.internal/spec-runtime-coverage-phase-2.md` (private repo).
    Coverage {
        #[command(subcommand)]
        subcommand: CoverageCli,
    },

    /// Install or remove a Claude Code PreToolUse hook that gates
    /// `git commit` / `git push` on `fallow audit`, so the agent cleans
    /// findings before the command runs.
    ///
    /// Deprecated: use `fallow agent install` (one pass for every harness)
    /// or `fallow hooks install --target agent` (the gate alone). This
    /// command keeps working throughout fallow 3 and is removed in the next
    /// major. It writes into `.claude/settings.json` +
    /// `.claude/hooks/fallow-gate.sh` (and optionally an `AGENTS.md` managed
    /// block for Codex). For a shell-level Git pre-commit hook in
    /// `.git/hooks/`, see `fallow hooks install --target git` instead.
    SetupHooks {
        /// Target a specific agent surface (default: auto-detect).
        #[arg(long, value_enum)]
        agent: Option<setup_hooks::HookAgentArg>,

        /// Print what would be written or removed without touching the filesystem.
        #[arg(long)]
        dry_run: bool,

        /// Overwrite a user-edited hook script, invalid settings.json, or
        /// remove a user-edited script during uninstall.
        #[arg(long)]
        force: bool,

        /// Write to the user's home directory instead of the project root.
        #[arg(long)]
        user: bool,

        /// Append `.claude/` to the project's `.gitignore`.
        #[arg(long)]
        gitignore_claude: bool,

        /// Remove the fallow-gate handler, hook script, and AGENTS.md
        /// managed block instead of installing them. Idempotent: reports
        /// "unchanged" when nothing to remove.
        #[arg(long)]
        uninstall: bool,
    },

    /// Generate an interactive HTML map of the codebase
    Viz {
        /// Output file path (default: fallow-viz.html in project root)
        #[arg(long = "out", value_name = "PATH")]
        output: Option<PathBuf>,

        /// Don't open the output file in the browser
        #[arg(long)]
        no_open: bool,

        /// Visualization output format
        #[arg(long = "viz-format", default_value = "html")]
        viz_format: viz::VizFormat,
    },
}

#[derive(Subcommand)]
enum SecuritySubcommand {
    /// Render verifier-retained survivor candidates from fallow output plus verifier verdicts.
    Survivors {
        /// Raw `fallow security --format json` candidate output.
        #[arg(long, value_name = "PATH")]
        candidates: PathBuf,
        /// Verifier verdict JSON file.
        #[arg(long, value_name = "PATH")]
        verdicts: PathBuf,
        /// Fail when any candidate has no matching verdict.
        #[arg(long)]
        require_verdict_for_each_candidate: bool,
    },
    /// Group unresolved security callees into actionable blind-spot output.
    #[command(name = "blind-spots")]
    BlindSpots {
        /// Scope diagnostics to selected files.
        #[arg(long, value_name = "PATH")]
        file: Vec<PathBuf>,
    },
}

#[derive(clap::Subcommand)]
enum AuditCacheCli {
    /// Remove reusable audit caches owned by an explicit project root.
    ///
    /// Deletes this project's cache entries unconditionally, warm or not. To
    /// apply the age-based GC policy across every cache entry instead, use
    /// `fallow audit-cache prune`.
    Remove {
        /// Print what would be removed without touching the filesystem.
        #[arg(long)]
        dry_run: bool,

        /// Confirm removal in non-interactive environments.
        #[arg(long, alias = "force")]
        yes: bool,
    },

    /// Apply the audit cache GC policy now and report every entry.
    ///
    /// Runs the same reclaim policy every `fallow audit` run already applies
    /// silently: orphaned-sidecar cleanup, age-based reclaim under the
    /// resolved threshold, and cross-repo reclaim of abandoned entries whose
    /// recorded owner root no longer exists. Entries owned by other live
    /// projects are never touched. Use `--dry-run` to preview every decision
    /// the policy would take without touching the filesystem. `--root` is
    /// optional and defaults to the current directory. Reported sizes come
    /// from a full recursive walk of each cache entry, which can take a few
    /// seconds on large caches. To delete one project's caches
    /// unconditionally, use `fallow audit-cache remove --root <path> --yes`.
    Prune {
        /// Preview decisions without touching the filesystem.
        #[arg(long)]
        dry_run: bool,

        /// Age threshold in days for this invocation. Overrides
        /// FALLOW_AUDIT_CACHE_MAX_AGE_DAYS and the `audit.cacheMaxAgeDays`
        /// config field (default 30). `0` disables age-based reclaim but
        /// still reclaims orphaned sidecars and entries whose recorded owner
        /// root is gone; unconditional deletion of one project's caches is
        /// `fallow audit-cache remove --root <path> --yes`.
        #[arg(long, value_name = "N")]
        max_age_days: Option<u32>,
    },
}

#[derive(clap::Subcommand)]
enum LicenseCli {
    /// Activate a license JWT.
    ///
    /// JWT input precedence: positional arg > `--from-file` > stdin (`-`).
    /// All paths normalize whitespace before crypto verification.
    Activate {
        /// JWT as a positional argument.
        #[arg(value_name = "JWT")]
        jwt: Option<String>,

        /// Path to a file containing the JWT.
        #[arg(long, value_name = "PATH")]
        from_file: Option<PathBuf>,

        /// Read JWT from stdin.
        #[arg(long, conflicts_with_all = ["jwt", "from_file"])]
        stdin: bool,

        /// Start a 30-day email-gated trial in one step.
        ///
        /// The trial endpoint is rate-limited to 5 requests per hour per IP.
        /// In CI or behind a shared NAT, start the trial from a developer
        /// machine and set FALLOW_LICENSE (or FALLOW_LICENSE_PATH) on the
        /// runner instead of re-running `activate --trial` per job.
        #[arg(long, requires = "email")]
        trial: bool,

        /// Email address for the trial flow.
        #[arg(long, value_name = "ADDR")]
        email: Option<String>,
    },
    /// Show the active license tier, seats, features, and days remaining.
    Status,
    /// Fetch a fresh JWT from `api.fallow.cloud` (network-only).
    ///
    /// The stored license JWT is the primary identity proof. When it is
    /// missing, or the cloud reports it as too stale to exchange, the request
    /// is retried with a full-access API key.
    Refresh {
        /// Fallow cloud API key (bearer token) used when the stored license
        /// JWT cannot be refreshed.
        ///
        /// Precedence: this flag > $FALLOW_API_KEY. Generate at
        /// <https://fallow.cloud/settings#api-keys>.
        ///
        /// Security: prefer $FALLOW_API_KEY on shared CI runners. Passing a
        /// secret on the command line may be visible to other processes via
        /// `ps` and can leak into shell history or process audit logs.
        #[arg(long, value_name = "KEY")]
        api_key: Option<String>,
    },
    /// Remove the local license file.
    Deactivate,
}

#[derive(Clone, Copy, clap::Subcommand)]
enum TelemetryCli {
    /// Show effective telemetry state, precedence, and controls.
    Status,
    /// Enable opt-in telemetry in the user-level fallow config.
    Enable,
    /// Disable telemetry in the user-level fallow config.
    Disable,
    /// Explain inspect mode or print example payloads.
    Inspect {
        /// Print documented example payloads and field purposes.
        #[arg(long)]
        example: bool,
    },
}

#[derive(clap::Subcommand)]
enum CiTemplateCli {
    /// Print or vendor the GitLab CI template and MR integration helpers.
    Gitlab {
        /// Write ci/ and action/ helper files under DIR instead of printing the template.
        ///
        /// Passing --vendor without a DIR writes into the current directory.
        #[arg(long, value_name = "DIR", num_args = 0..=1, default_missing_value = ".")]
        vendor: Option<PathBuf>,

        /// Overwrite existing files that differ from the bundled template.
        #[arg(long)]
        force: bool,
    },
}

#[derive(clap::Subcommand)]
enum CoverageCli {
    /// Resumable first-run setup: license + sidecar + recipe + analysis.
    Setup {
        /// Accept all prompts automatically.
        #[arg(short = 'y', long)]
        yes: bool,

        /// Print instructions instead of prompting.
        #[arg(long)]
        non_interactive: bool,

        /// Emit deterministic setup instructions as JSON. Implies --non-interactive.
        #[arg(long)]
        json: bool,
    },
    /// Analyze runtime coverage from a local artifact or explicit cloud source.
    ///
    /// Cloud mode is opt-in only. `FALLOW_API_KEY` by itself never selects
    /// cloud mode; pass `--cloud` / `--runtime-coverage-cloud`, or set
    /// `FALLOW_RUNTIME_COVERAGE_SOURCE=cloud`.
    Analyze {
        /// File or directory containing local runtime coverage input.
        #[arg(long, value_name = "PATH", conflicts_with = "cloud")]
        runtime_coverage: Option<PathBuf>,

        /// Fetch latest runtime facts from fallow cloud for the selected repo.
        #[arg(long, visible_alias = "runtime-coverage-cloud")]
        cloud: bool,

        /// Fallow cloud API key. Precedence: this flag > $FALLOW_API_KEY.
        #[arg(long, value_name = "KEY")]
        api_key: Option<String>,

        /// Override the fallow cloud base URL.
        #[arg(long, value_name = "URL")]
        api_endpoint: Option<String>,

        /// Repository identifier, for example `owner/repo`.
        ///
        /// Defaults to $FALLOW_REPO, then the parsed origin URL from
        /// `git remote get-url origin`. Slashes are percent-encoded as one
        /// URL segment when calling the cloud runtime-context endpoint.
        #[arg(long, value_name = "OWNER/REPO")]
        repo: Option<String>,

        /// Optional monorepo/project disambiguator.
        #[arg(long, value_name = "ID")]
        project_id: Option<String>,

        /// Runtime observation window to request from cloud (1..=90 days).
        #[arg(long, value_name = "DAYS", default_value_t = 30)]
        coverage_period: u16,

        /// Optional runtime environment filter.
        #[arg(long, value_name = "ENV")]
        environment: Option<String>,

        /// Optional commit SHA filter for cloud runtime facts.
        #[arg(long, value_name = "SHA")]
        commit_sha: Option<String>,

        /// Analyze production code only.
        #[arg(long)]
        production: bool,

        /// Threshold for hot-path classification.
        #[arg(long, default_value_t = 100)]
        min_invocations_hot: u64,

        /// Minimum total trace volume before high-confidence verdicts.
        #[arg(long, value_name = "N")]
        min_observation_volume: Option<u32>,

        /// Fraction of total trace count below which an invoked function is low traffic.
        #[arg(long, value_name = "RATIO")]
        low_traffic_threshold: Option<f64>,

        /// Show only the top N runtime findings and hot paths.
        #[arg(long)]
        top: Option<usize>,

        /// Show the first-class blast-radius section in human output.
        #[arg(long)]
        blast_radius: bool,

        /// Show the first-class importance section in human output.
        #[arg(long)]
        importance: bool,

        /// List cloud runtime functions with no local counterpart on stderr.
        #[arg(long)]
        debug_unmatched: bool,
    },
    /// Upload a static function inventory to fallow cloud (Production
    /// Coverage, paid). Unlocks the `untracked` filter on the dashboard by
    /// pairing runtime coverage data with the AST view of "every function
    /// that exists". See <https://docs.fallow.tools/analysis/runtime-coverage>.
    ///
    /// This command makes network calls to fallow cloud. `fallow dead-code`
    /// stays offline.
    ///
    /// Exit codes: 0 ok · 7 network · 10 validation · 11 payload too large
    /// · 12 auth rejected · 13 server error.
    UploadInventory {
        /// Fallow cloud API key (bearer token).
        ///
        /// Precedence: this flag > $FALLOW_API_KEY. Generate at
        /// <https://fallow.cloud/settings#api-keys>.
        ///
        /// Security: prefer $FALLOW_API_KEY on shared CI runners. Passing a
        /// secret on the command line may be visible to other processes via
        /// `ps` and can leak into shell history or process audit logs.
        #[arg(long, value_name = "KEY")]
        api_key: Option<String>,

        /// Override the fallow cloud base URL.
        ///
        /// Useful for staging and on-premise deployments. Also respects
        /// $FALLOW_API_URL when this flag is not set.
        #[arg(long, value_name = "URL")]
        api_endpoint: Option<String>,

        /// Project identifier, for example `fallow-cloud-api` or `owner/repo`.
        ///
        /// Defaults to $GITHUB_REPOSITORY, then $CI_PROJECT_PATH, then the
        /// parsed origin URL from `git remote get-url origin`.
        #[arg(long, value_name = "PROJECT_ID")]
        project_id: Option<String>,

        /// Explicit git SHA for this inventory.
        ///
        /// Default: `git rev-parse HEAD`. The inventory is keyed on this
        /// value; the cloud back-fills hourly buckets with a matching SHA.
        #[arg(long, value_name = "SHA")]
        git_sha: Option<String>,

        /// Proceed even when the working tree has uncommitted changes.
        ///
        /// Warning: the inventory is generated from the working copy, so it
        /// may not match the uploaded git SHA. Commit or stash first if you
        /// want a SHA-exact upload.
        #[arg(long)]
        allow_dirty: bool,

        /// Additional glob patterns to exclude from the walk.
        ///
        /// Applied after the existing fallow ignore rules. Repeatable.
        #[arg(long, value_name = "GLOB", num_args = 0..)]
        exclude_paths: Vec<String>,

        /// Prefix prepended to every emitted filePath so the static
        /// inventory joins with the runtime beacon for your deployment.
        /// Required for containerized deployments where the deployed
        /// WORKDIR rebases paths at runtime. Default: none (paths emit
        /// repo-relative, matching local runs and non-container CI).
        ///
        /// Common values: `/app` (typical Dockerfile), `/workspace`
        /// (Buildpacks / Cloud Run), `/usr/src/app` (older Node images),
        /// `/var/task` (Lambda), `/home/runner/work/<repo>/<repo>`
        /// (GitHub Actions default checkout).
        ///
        /// Must start with `/` and use POSIX separators.
        #[arg(long, value_name = "PREFIX")]
        path_prefix: Option<String>,

        /// Print what would be uploaded and exit. No network call.
        #[arg(long)]
        dry_run: bool,

        /// Also upload importer edges (which files import each function) so the
        /// cloud can show change-time blast radius. Opt-in: this builds the
        /// import graph by running the full static analysis, whereas the default
        /// upload is a fast per-file walk. The graph is cached, so a CI step that
        /// already ran analysis pays little extra.
        #[arg(long)]
        with_callers: bool,

        /// Treat transient upload failures as warnings instead of errors
        /// (exit 0). Validation and auth errors still fail hard; this only
        /// downgrades transport and server errors.
        #[arg(long)]
        ignore_upload_errors: bool,
    },
    /// Upload JavaScript source maps to fallow cloud for bundled runtime coverage.
    ///
    /// Scans a build output directory for `.map` files and uploads them under
    /// the selected repo + git SHA. The production beacon reports bundled
    /// paths; the cloud resolver uses these maps to remap runtime coverage back
    /// to original source files.
    ///
    /// Each upload also carries the map's path relative to the repo root, so the
    /// source-evidence viewer can resolve a monorepo sub-package map's relative
    /// `sources[]` (e.g. `../../src/X`) to the package-prefixed source path
    /// (e.g. `dashboard/src/X`). Run from the repo root so this prefix is
    /// correct.
    UploadSourceMaps {
        /// Directory to scan recursively for source maps.
        #[arg(long, value_name = "PATH", default_value = "dist")]
        dir: PathBuf,

        /// Glob pattern, relative to --dir, selecting maps to upload.
        #[arg(long, value_name = "GLOB", default_value = "**/*.map")]
        include: String,

        /// Glob pattern, relative to --dir, selecting files to skip.
        ///
        /// Repeatable. Defaults to `**/node_modules/**`.
        #[arg(long, value_name = "GLOB", default_value = "**/node_modules/**")]
        exclude: Vec<String>,

        /// Repo name used in the API path.
        ///
        /// Defaults to package.json repository.url, then `git remote get-url origin`.
        #[arg(long, value_name = "NAME")]
        repo: Option<String>,

        /// Commit SHA to key uploads under.
        ///
        /// Defaults to $GITHUB_SHA, $CI_COMMIT_SHA, $COMMIT_SHA, then
        /// `git rev-parse HEAD`.
        #[arg(long, value_name = "SHA")]
        git_sha: Option<String>,

        /// Override the fallow cloud base URL.
        #[arg(long, value_name = "URL")]
        endpoint: Option<String>,

        /// Send only the basename as fileName by default.
        ///
        /// Use `--strip-path=false` when your runtime coverage reports bundle
        /// paths relative to the build directory, such as `assets/app.js`.
        #[arg(long, value_name = "BOOL", default_value_t = true, action = clap::ArgAction::Set)]
        strip_path: bool,

        /// Print what would be uploaded and exit. No network call.
        #[arg(long)]
        dry_run: bool,

        /// Parallel upload fanout.
        #[arg(long, value_name = "N", default_value_t = 4)]
        concurrency: usize,

        /// Stop on first upload error.
        #[arg(long)]
        fail_fast: bool,
    },
    /// Upload static dead-code findings to fallow cloud for the source-evidence viewer.
    ///
    /// Runs fallow's static analysis and uploads the `unused_export` and
    /// `dead_file` verdicts under the selected repo + git SHA. The cloud
    /// overlays them on the source view alongside the runtime coverage overlay.
    /// Findings are replace-by-SHA: each run sends the complete set for the SHA.
    UploadStaticFindings {
        /// Fallow cloud API key (bearer token).
        ///
        /// Precedence: this flag > $FALLOW_API_KEY. Generate at
        /// <https://fallow.cloud/settings#api-keys>. This must be a live API
        /// key, not a publishable ingest key.
        ///
        /// Security: prefer $FALLOW_API_KEY on shared CI runners. Passing a
        /// secret on the command line may be visible to other processes via
        /// `ps` and can leak into shell history or process audit logs.
        #[arg(long, value_name = "KEY")]
        api_key: Option<String>,

        /// Override the fallow cloud base URL.
        ///
        /// Useful for staging and on-premise deployments. Also respects
        /// $FALLOW_API_URL when this flag is not set.
        #[arg(long, value_name = "URL")]
        api_endpoint: Option<String>,

        /// Project identifier, for example `fallow-cloud-api` or `owner/repo`.
        ///
        /// Defaults to $GITHUB_REPOSITORY, then $CI_PROJECT_PATH, then the
        /// parsed origin URL from `git remote get-url origin`.
        #[arg(long, value_name = "PROJECT_ID")]
        project_id: Option<String>,

        /// Explicit git SHA for these findings.
        ///
        /// Default: `git rev-parse HEAD`. Findings are keyed on this value and
        /// fully replace any prior set uploaded for the same SHA.
        #[arg(long, value_name = "SHA")]
        git_sha: Option<String>,

        /// Proceed even when the working tree has uncommitted changes.
        ///
        /// Warning: findings are generated from the working copy, so they may
        /// not match the uploaded git SHA. Commit or stash first if you want a
        /// SHA-exact upload.
        #[arg(long)]
        allow_dirty: bool,

        /// Print what would be uploaded and exit. No network call.
        #[arg(long)]
        dry_run: bool,

        /// Treat transient upload failures as warnings instead of errors
        /// (exit 0). Validation and auth errors still fail hard; this only
        /// downgrades transport and server errors.
        #[arg(long)]
        ignore_upload_errors: bool,
    },
}

#[derive(Subcommand)]
enum CiCli {
    /// Compute the provider action for a rendered sticky PR summary comment.
    PlanPrComment {
        /// Path to the rendered PR comment Markdown body.
        #[arg(long)]
        body: PathBuf,

        /// Sticky marker id used in the rendered body.
        #[arg(long)]
        marker_id: String,

        /// Treat the rendered body as a clean no-findings result.
        #[arg(long)]
        clean: bool,

        /// Existing provider comment id, when a matching sticky comment exists.
        #[arg(long)]
        existing_comment_id: Option<String>,

        /// Path to the existing provider comment body. Enables unchanged-skip planning.
        #[arg(long)]
        existing_body: Option<PathBuf>,
    },

    /// Post, update, or skip a rendered sticky PR summary comment.
    PostPrComment {
        /// Provider whose PR comment is being posted.
        #[arg(long, value_enum)]
        provider: CiProviderArg,

        /// Pull request number (GitHub).
        #[arg(long)]
        pr: Option<String>,

        /// Merge request IID (GitLab).
        #[arg(long)]
        mr: Option<String>,

        /// Path to the rendered PR comment Markdown body.
        #[arg(long)]
        body: PathBuf,

        /// Path to the typed PR comment envelope JSON, when available.
        #[arg(long)]
        envelope: Option<PathBuf>,

        /// Sticky marker id used in the rendered body.
        #[arg(long)]
        marker_id: String,

        /// Treat the rendered body as a clean no-findings result.
        #[arg(long)]
        clean: bool,

        /// GitHub repository in owner/name form. Defaults to GH_REPO or GITHUB_REPOSITORY.
        #[arg(long)]
        repo: Option<String>,

        /// GitLab project id or path. Defaults to CI_PROJECT_ID.
        #[arg(long = "project-id")]
        project_id: Option<String>,

        /// Provider API base URL. Defaults to github.com.
        #[arg(long = "api-url")]
        api_url: Option<String>,

        /// Compute the post plan without creating or updating the provider comment.
        #[arg(long)]
        dry_run: bool,
    },

    /// Post a rendered review envelope as a provider review or summary comment.
    PostReview {
        /// Provider whose review envelope is being posted.
        #[arg(long, value_enum)]
        provider: CiProviderArg,

        /// Pull request number (GitHub).
        #[arg(long)]
        pr: Option<String>,

        /// Merge request IID (GitLab).
        #[arg(long)]
        mr: Option<String>,

        /// Path to a review-github or review-gitlab JSON envelope.
        #[arg(long)]
        envelope: PathBuf,

        /// GitHub repository in owner/name form. Defaults to GH_REPO or GITHUB_REPOSITORY.
        #[arg(long)]
        repo: Option<String>,

        /// GitLab project id or path. Defaults to CI_PROJECT_ID.
        #[arg(long = "project-id")]
        project_id: Option<String>,

        /// Provider API base URL. Defaults to github.com or CI_API_V4_URL/gitlab.com.
        #[arg(long = "api-url")]
        api_url: Option<String>,

        /// Compute the post plan without creating provider comments.
        #[arg(long)]
        dry_run: bool,
    },

    /// Post a GitHub Check Run from a typed PR decision surface.
    PostCheckRun {
        /// Provider whose check run is being posted. Only GitHub is supported.
        #[arg(long, value_enum)]
        provider: CiProviderArg,

        /// Path to a fallow-pr-decision JSON sidecar.
        #[arg(long)]
        decision: PathBuf,

        /// GitHub repository in owner/name form.
        #[arg(long)]
        repo: String,

        /// Head SHA the check run should attach to.
        #[arg(long = "head-sha")]
        head_sha: String,

        /// Provider API base URL. Defaults to github.com.
        #[arg(long = "api-url")]
        api_url: Option<String>,

        /// Post one check run per decision gate instead of one aggregate check.
        #[arg(long = "split-gates")]
        split_gates: bool,

        /// Print the check run payload without posting it.
        #[arg(long)]
        dry_run: bool,
    },

    /// Validate a rendered review envelope and compute a stable reconcile plan.
    ReconcileReview {
        /// Provider whose review envelope is being reconciled.
        #[arg(long, value_enum)]
        provider: CiProviderArg,

        /// Pull request number (GitHub).
        #[arg(long)]
        pr: Option<String>,

        /// Merge request IID (GitLab).
        #[arg(long)]
        mr: Option<String>,

        /// Path to a review-github or review-gitlab JSON envelope.
        #[arg(long)]
        envelope: PathBuf,

        /// GitHub repository in owner/name form. Defaults to GH_REPO or GITHUB_REPOSITORY.
        #[arg(long)]
        repo: Option<String>,

        /// GitLab project id or path. Defaults to CI_PROJECT_ID.
        #[arg(long = "project-id")]
        project_id: Option<String>,

        /// Provider API base URL. Defaults to github.com or CI_API_V4_URL/gitlab.com.
        #[arg(long = "api-url")]
        api_url: Option<String>,

        /// Compute the reconcile plan without posting resolution notes or resolving threads.
        #[arg(long)]
        dry_run: bool,
    },
}

#[derive(Subcommand)]
enum RulePackCli {
    /// Scaffold a new rule pack file and wire it into the config
    Init {
        /// Pack name (default: the template name, or "team-policy")
        name: Option<String>,

        /// Template: starter, ai-safe-repo, side-effect-free-domain, clean-architecture, next-app-router
        #[arg(long, default_value = "starter")]
        template: String,

        /// Directory for the pack file, relative to the project root
        #[arg(long, default_value = "rule-packs")]
        dir: String,

        /// Only write the pack file; do not modify the config
        #[arg(long)]
        no_config: bool,
    },

    /// List configured rule packs and their rules
    List,

    /// Evaluate a pack (or all configured packs) against this project and print matches
    Test {
        /// Path to a pack file to test in isolation (default: all configured packs)
        pack: Option<PathBuf>,
    },

    /// Print the JSON Schema for rule pack files
    Schema,
}

/// CLI mirror of [`fallow_engine::baseline::HealthBaselineMode`].
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, clap::ValueEnum)]
pub enum BaselineModeArg {
    /// Match a saved health baseline per file and finding category.
    #[default]
    Count,
    /// Match a saved health baseline per function identity and finding
    /// category, so a hotspot that replaces another hotspot is reported.
    Identity,
}

impl From<BaselineModeArg> for fallow_engine::baseline::HealthBaselineMode {
    fn from(value: BaselineModeArg) -> Self {
        match value {
            BaselineModeArg::Count => Self::Count,
            BaselineModeArg::Identity => Self::Identity,
        }
    }
}

#[derive(Clone, Copy, Debug, clap::ValueEnum)]
enum CiProviderArg {
    Github,
    Gitlab,
}

/// CLI mirror of [`fallow_config::TypeAwareRequire`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
enum TypeAwareRequireArg {
    /// Keep conservative findings and report semantic gaps.
    BestEffort,
    /// Fail the quality gate when a requested semantic query is incomplete.
    Complete,
}

impl From<TypeAwareRequireArg> for fallow_config::TypeAwareRequire {
    fn from(value: TypeAwareRequireArg) -> Self {
        match value {
            TypeAwareRequireArg::BestEffort => Self::BestEffort,
            TypeAwareRequireArg::Complete => Self::Complete,
        }
    }
}

/// Filter refactoring targets by effort level.
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum EffortFilter {
    Low,
    Medium,
    High,
}

impl EffortFilter {
    /// Convert to the corresponding `EffortEstimate` for comparison.
    const fn to_estimate(self) -> fallow_output::EffortEstimate {
        match self {
            Self::Low => fallow_output::EffortEstimate::Low,
            Self::Medium => fallow_output::EffortEstimate::Medium,
            Self::High => fallow_output::EffortEstimate::High,
        }
    }
}

/// CLI parser for the health severity gate.
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum HealthSeverityCli {
    Moderate,
    High,
    Critical,
}

impl HealthSeverityCli {
    /// Convert to the typed health output severity.
    const fn to_health_severity(self) -> fallow_output::FindingSeverity {
        match self {
            Self::Moderate => fallow_output::FindingSeverity::Moderate,
            Self::High => fallow_output::FindingSeverity::High,
            Self::Critical => fallow_output::FindingSeverity::Critical,
        }
    }
}

/// Privacy mode for author emails emitted by `--ownership`.
///
/// CLI mirror of [`fallow_config::EmailMode`]. Kept as a separate enum so
/// the help text controls rendering and we don't leak config-internal
/// schema details into clap.
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum EmailModeArg {
    /// Show full email addresses as recorded in git history.
    Raw,
    /// Show local-part only (default). Unwraps GitHub-style noreply prefixes.
    Handle,
    /// Show stable non-cryptographic pseudonyms (`xxh3:<hex>`).
    Anonymized,
    /// Legacy spelling for anonymized output.
    #[value(hide = true)]
    Hash,
}

impl EmailModeArg {
    /// Convert to the equivalent config-level mode.
    const fn to_config(self) -> fallow_config::EmailMode {
        match self {
            Self::Raw => fallow_config::EmailMode::Raw,
            Self::Handle => fallow_config::EmailMode::Handle,
            Self::Anonymized => fallow_config::EmailMode::Anonymized,
            Self::Hash => fallow_config::EmailMode::Hash,
        }
    }
}

/// CLI mirror of [`fallow_config::AuditGate`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum AuditGateArg {
    /// Only findings introduced by the current changeset affect the verdict.
    NewOnly,
    /// All findings in changed files affect the verdict.
    All,
}

impl From<AuditGateArg> for fallow_config::AuditGate {
    fn from(value: AuditGateArg) -> Self {
        match value {
            AuditGateArg::NewOnly => Self::NewOnly,
            AuditGateArg::All => Self::All,
        }
    }
}

/// Parse `--min-occurrences` and reject values below 2. A single occurrence
/// is not a duplicate; silently clamping would diverge from the config-file
/// validator, which also rejects `< 2`.
fn parse_min_occurrences(s: &str) -> Result<usize, String> {
    let value: usize = s
        .parse()
        .map_err(|_| format!("`{s}` is not a non-negative integer"))?;
    if value < 2 {
        return Err(format!(
            "must be at least 2 (got {value}); a single occurrence isn't a duplicate"
        ));
    }
    Ok(value)
}

/// Resolve an audit baseline path using CLI > config precedence.
///
/// Both sources resolve relative paths against the project root. This keeps
/// behavior consistent in CI scripts where `--root $REPO_ROOT` differs from
/// the process CWD.
fn resolve_audit_baseline_path(
    root: &std::path::Path,
    cli: Option<&std::path::Path>,
    config: Option<&str>,
) -> Option<PathBuf> {
    let path = cli.map(std::path::Path::to_path_buf).or_else(|| {
        config.map(|p| {
            let path = PathBuf::from(p);
            if path_util::is_absolute_path_any_platform(&path) {
                path
            } else {
                root.join(path)
            }
        })
    })?;
    if path_util::is_absolute_path_any_platform(&path) {
        Some(path)
    } else {
        Some(root.join(path))
    }
}

fn emit_known_failure(
    message: &str,
    exit_code: u8,
    output: fallow_config::OutputFormat,
    reason: telemetry::FailureReason,
) -> ExitCode {
    telemetry::note_failure_reason(reason);
    emit_error(message, exit_code, output)
}

fn emit_known_failure_with_style(
    message: &str,
    exit_code: u8,
    output: fallow_config::OutputFormat,
    json_style: json_style::JsonStyle,
    reason: telemetry::FailureReason,
) -> ExitCode {
    telemetry::note_failure_reason(reason);
    error::emit_error_with_style(message, exit_code, output, json_style)
}

fn unsupported_security_global(cli: &Cli) -> Option<&'static str> {
    if cli.baseline.is_some() {
        Some("--baseline")
    } else if cli.save_baseline.is_some() {
        Some("--save-baseline")
    } else if cli.production {
        Some("--production")
    } else if cli.no_production {
        Some("--no-production")
    } else if cli.group_by.is_some() {
        Some("--group-by")
    } else if cli.performance {
        Some("--performance")
    } else if cli.explain_skipped {
        Some("--explain-skipped")
    } else if cli.fail_on_regression {
        Some("--fail-on-regression")
    } else if cli.regression_baseline.is_some() {
        Some("--regression-baseline")
    } else if cli.save_regression_baseline.is_some() {
        Some("--save-regression-baseline")
    } else if cli.dupes_mode.is_some() {
        Some("--dupes-mode")
    } else if cli.dupes_threshold.is_some() {
        Some("--dupes-threshold")
    } else if cli.dupes_min_tokens.is_some() {
        Some("--dupes-min-tokens")
    } else if cli.dupes_min_lines.is_some() {
        Some("--dupes-min-lines")
    } else if cli.dupes_min_occurrences.is_some() {
        Some("--dupes-min-occurrences")
    } else if cli.dupes_skip_local {
        Some("--dupes-skip-local")
    } else if cli.dupes_cross_language {
        Some("--dupes-cross-language")
    } else if cli.dupes_ignore_imports {
        Some("--dupes-ignore-imports")
    } else if cli.dupes_no_ignore_imports {
        Some("--dupes-no-ignore-imports")
    } else if cli.include_entry_exports {
        Some("--include-entry-exports")
    } else {
        None
    }
}

struct DispatchContext<'a> {
    cli: &'a Cli,
    root: &'a std::path::Path,
    output: fallow_config::OutputFormat,
    quiet: bool,
    fail_on_issues: bool,
    json_style: json_style::JsonStyle,
    threads: usize,
    tolerance: regression::Tolerance,
    save_regression_file: Option<&'a std::path::PathBuf>,
    save_to_config: bool,
}

impl DispatchContext<'_> {
    fn production_modes(
        &self,
        dead_code: bool,
        health: bool,
        dupes: bool,
    ) -> Result<ProductionModes, ExitCode> {
        resolve_production_modes(self.cli, self.root, self.output, dead_code, health, dupes)
    }

    fn production_for(
        &self,
        analysis: fallow_config::ProductionAnalysis,
    ) -> Result<bool, ExitCode> {
        self.production_modes(false, false, false)
            .map(|modes| modes.for_analysis(analysis))
    }

    fn regression_opts(&self, scoped: bool) -> regression::RegressionOpts<'_> {
        regression::RegressionOpts {
            fail_on_regression: self.cli.fail_on_regression,
            tolerance: self.tolerance,
            regression_baseline_file: self.cli.regression_baseline.as_deref(),
            save_target: if let Some(path) = self.save_regression_file {
                regression::SaveRegressionTarget::File(path)
            } else if self.save_to_config {
                regression::SaveRegressionTarget::Config
            } else {
                regression::SaveRegressionTarget::None
            },
            scoped,
            quiet: self.quiet,
            output: self.output,
        }
    }
}

/// Test-only helper invoked when `FALLOW_TEST_SIGNAL_HELPER=1` is set.
/// Spawns `sleep 30` via the `ScopedChild` registry so the child is
/// tracked by the signal handler, prints the child PID to stdout, then
/// busy-waits so a SIGINT/SIGTERM delivered to the parent fires the
/// signal handler (which kills the child and exits 128+signum).
///
/// When `FALLOW_TEST_SIGNAL_HELPER_GRACEFUL=1` is also set, graceful
/// mode is activated BEFORE spawning the child. In graceful mode the
/// signal handler kills the child (proving drain runs unconditionally)
/// but does NOT call `std::process::exit`, so the helper itself sees
/// `wait_with_output` return and exits 0. This is the path the
/// integration test asserts: graceful drain + clean exit. Lives in
/// `main.rs` (not tests/) because clap is already parsed below and we
/// need to intercept before that.
#[cfg(unix)]
fn signal_test_helper() -> ExitCode {
    use std::io::Write as _;
    use std::process::Command;

    if std::env::var_os("FALLOW_TEST_SIGNAL_HELPER_GRACEFUL").is_some() {
        signal::set_graceful_mode();
    }

    let mut command = Command::new("sleep");
    command.arg("30");
    let child = match signal::ScopedChild::spawn(&mut command) {
        Ok(c) => c,
        Err(err) => {
            let _ = writeln!(std::io::stderr(), "spawn sleep failed: {err}");
            return ExitCode::from(2);
        }
    };
    let pid = child.id();
    let stdout = std::io::stdout();
    let mut lock = stdout.lock();
    let _ = writeln!(lock, "{pid}");
    let _ = lock.flush();
    drop(lock);
    let _ = child.wait_with_output();
    if std::env::var_os("FALLOW_TEST_SIGNAL_HELPER_GRACEFUL").is_some() {
        return ExitCode::SUCCESS;
    }
    std::thread::sleep(std::time::Duration::from_secs(5));
    ExitCode::SUCCESS
}

#[cfg(not(unix))]
fn signal_test_helper() -> ExitCode {
    ExitCode::from(2)
}

fn install_spawn_hooks() {
    fallow_engine::churn::set_spawn_hook(signal::scoped_child::output);
    fallow_engine::changed_files::set_spawn_hook(signal::scoped_child::output);
}

fn install_signal_handlers() {
    if let Err(err) = signal::install_handlers() {
        use std::io::Write as _;
        let stderr = std::io::stderr();
        let mut lock = stderr.lock();
        let _ = writeln!(lock, "fallow: failed to install signal handlers: {err}");
    }
}

/// Open `path` (creating parent dirs, truncating) and redirect report output
/// there via the ambient sink, forcing color off so the file carries no ANSI
/// codes even when attached to a TTY. Returns the error exit code if the file
/// cannot be created. Backs `--output-file`.
fn redirect_report_to_file(
    path: &std::path::Path,
    output: fallow_config::OutputFormat,
) -> Result<(), ExitCode> {
    if let Some(parent) = path.parent()
        && !parent.as_os_str().is_empty()
        && let Err(e) = std::fs::create_dir_all(parent)
    {
        return Err(emit_error(
            &format!(
                "failed to create {} for --output-file: {e}",
                parent.display()
            ),
            2,
            output,
        ));
    }
    match std::fs::File::create(path) {
        Ok(file) => {
            report::sink::set_file_sink(file);
            colored::control::set_override(false);
            Ok(())
        }
        Err(e) => Err(emit_error(
            &format!("failed to open {} for --output-file: {e}", path.display()),
            2,
            output,
        )),
    }
}

/// Flush the report file after rendering and print the stderr confirmation
/// (suppressed by `--quiet`). Returns the error exit code on a write failure.
fn finalize_report_file(
    path: &std::path::Path,
    quiet: bool,
    output: fallow_config::OutputFormat,
) -> Result<(), ExitCode> {
    if let Err(e) = report::sink::flush() {
        return Err(emit_error(
            &format!("failed to write {}: {e}", path.display()),
            2,
            output,
        ));
    }
    // Suppress the confirmation when nothing was rendered to the file (a command
    // that errored before producing output sends its error to stdout, not the
    // file), so we never claim "Report written" over an empty file.
    if !quiet && report::sink::wrote() {
        eprintln!("Report written to {}", path.display());
    }
    Ok(())
}

/// Run the full fallow CLI: parse argv, dispatch the selected command, and
/// return the process exit code. This is the crate's single entry point; the
/// `fallow` binary and the multicall `fallow-multicall` binary both delegate
/// here so there is exactly one clap tree and one dispatch path.
pub fn run() -> ExitCode {
    install_signal_handlers();
    install_spawn_hooks();

    if std::env::var_os("FALLOW_TEST_SIGNAL_HELPER").is_some() {
        return signal_test_helper();
    }

    let (mut cli, fmt) = match parse_cli_args() {
        Ok(parsed) => parsed,
        Err(code) => return code,
    };
    if cli.pretty && !fmt.payload_is_json {
        eprintln!(
            "Error: --pretty requires JSON output. Use --format json --pretty, or remove --pretty."
        );
        return ExitCode::from(2);
    }

    if let Some(code) = run_schema_command_if_requested(&cli, fmt.json_style) {
        return code;
    }

    if let Some(code) = run_telemetry_command_if_requested(&mut cli, fmt.output, fmt.json_style) {
        return code;
    }
    if let Some(code) = run_doctor_command_if_requested(&cli, &fmt) {
        return code;
    }
    if is_impact_statusline(&cli) {
        let (root, _) = match validate_inputs(&cli, fmt.output, fmt.json_style) {
            Ok(validated) => validated,
            Err(code) => return code,
        };
        return cli_impact::render_impact_statusline(&root);
    }
    let telemetry_run = start_telemetry_run(&cli, &fmt);

    let (root, threads) = match validate_inputs(&cli, fmt.output, fmt.json_style) {
        Ok(v) => v,
        Err(code) => {
            return record_run_epilogue(telemetry_run, code, None, cli.parent_run.as_deref());
        }
    };

    let FormatConfig {
        output,
        payload_is_json: _,
        quiet,
        fail_on_issues,
        json_style,
    } = fmt;

    let tolerance =
        match run_pre_dispatch_checks(&cli, &root, output, json_style, quiet, telemetry_run) {
            Ok(tolerance) => tolerance,
            Err(code) => return code,
        };

    let (save_regression_file, save_to_config) = regression_save_targets(&cli);

    let command = cli.command.take();
    let dispatch = DispatchContext {
        cli: &cli,
        root: &root,
        output,
        quiet,
        fail_on_issues,
        json_style,
        threads,
        tolerance,
        save_regression_file: save_regression_file.as_ref(),
        save_to_config,
    };
    let exit_code = match dispatch_and_finalize(&dispatch, command) {
        Ok(code) => code,
        Err(code) => return code,
    };
    record_run_epilogue(telemetry_run, exit_code, None, cli.parent_run.as_deref())
}

/// Benchmark hook for the production fix dry-run pipeline. This is not a
/// supported API. Rendered output is disabled so the benchmark measures
/// analysis and fix planning rather than terminal I/O.
#[doc(hidden)]
pub fn benchmark_fix_dry_run(root: &Path, threads: usize) -> (ExitCode, usize) {
    let config_path = None;
    fix::run_fix_with_count(&fix::FixOptions {
        root,
        config_path: &config_path,
        output: fallow_config::OutputFormat::Json,
        json_style: json_style::JsonStyle::Compact,
        no_cache: true,
        threads,
        quiet: true,
        emit_output: false,
        allow_remote_extends: false,
        dry_run: true,
        yes: false,
        production: false,
        no_create_config: true,
        type_aware: None,
        type_aware_projects: &[],
        type_aware_require: None,
    })
}

/// Owned production-analysis corpus for the stable audit review benchmark.
/// This is not a supported API.
#[doc(hidden)]
pub use audit::AuditReviewBenchmarkCorpus;

/// Build audit analysis and preload external review inputs outside the timed
/// benchmark. This is not a supported API.
#[doc(hidden)]
pub fn create_audit_review_benchmark_corpus(
    root: &Path,
    changed_files: &[PathBuf],
    threads: usize,
) -> Result<AuditReviewBenchmarkCorpus, ExitCode> {
    audit::create_audit_review_benchmark_corpus(root, changed_files, threads)
}

/// Benchmark production audit review assembly and compact tagged JSON without
/// git, cache, worktree, or file I/O. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_audit_review_brief_many_changed_files_json(
    corpus: &mut AuditReviewBenchmarkCorpus,
) -> (ExitCode, usize, usize, usize, usize, usize) {
    match audit::benchmark_audit_review_brief_many_changed_files_json(corpus) {
        Ok(result) => (
            ExitCode::SUCCESS,
            result.introduced_count,
            result.inherited_count,
            result.public_api_added_count,
            result.decision_count,
            result.rendered_bytes,
        ),
        Err(code) => (code, 0, 0, 0, 0, 0),
    }
}

#[doc(hidden)]
pub use inspect::InspectBenchmarkCorpus;

/// Build the child-response corpus outside the timed inspect benchmark. This
/// is not a supported API.
#[doc(hidden)]
pub fn create_inspect_benchmark_corpus(root: &Path, threads: usize) -> InspectBenchmarkCorpus {
    inspect::create_inspect_benchmark_corpus(root, threads)
}

/// Benchmark file inspect orchestration and compact tagged JSON rendering
/// without process startup. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_inspect_file_evidence_bundle_json(
    root: &Path,
    threads: usize,
    corpus: &InspectBenchmarkCorpus,
) -> (ExitCode, usize, usize) {
    match inspect::benchmark_inspect_file_evidence_bundle_json(root, threads, corpus) {
        Ok((child_call_count, rendered_bytes)) => {
            (ExitCode::SUCCESS, child_call_count, rendered_bytes)
        }
        Err(_) => (ExitCode::from(2), 0, 0),
    }
}

/// Benchmark hook for the production dead-code analysis and compact JSON
/// rendering pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_dead_code_json(root: &Path, threads: usize) -> (ExitCode, usize, usize) {
    match check::benchmark_dead_code_json(root, threads) {
        Ok((issue_count, rendered_bytes)) => (ExitCode::SUCCESS, issue_count, rendered_bytes),
        Err(code) => (code, 0, 0),
    }
}

/// Benchmark hook for the production security analysis and JSON rendering
/// pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_security_json(root: &Path, threads: usize) -> (ExitCode, usize, usize) {
    match security::benchmark_security_json(root, threads) {
        Ok((finding_count, rendered_bytes)) => (ExitCode::SUCCESS, finding_count, rendered_bytes),
        Err(code) => (code, 0, 0),
    }
}

#[doc(hidden)]
pub use security::{SecurityBlindSpotsBenchmarkResult, SecuritySurvivorsBenchmarkCorpus};

/// Build the explicit candidate and verifier inputs outside the timed
/// survivors benchmark. This is not a supported API.
#[doc(hidden)]
pub fn create_security_survivors_benchmark_corpus(
    root: &Path,
    threads: usize,
) -> Result<SecuritySurvivorsBenchmarkCorpus, ExitCode> {
    security::create_security_survivors_benchmark_corpus(root, threads)
}

/// Benchmark the production survivors loaders, candidate/verdict join, and
/// compact JSON serializer. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_security_survivors_json(
    corpus: &SecuritySurvivorsBenchmarkCorpus,
) -> (ExitCode, usize, usize, usize, usize, usize) {
    match security::benchmark_security_survivors_json(corpus) {
        Ok((survivors, dismissed, needs_human_review, unverdicted, rendered_bytes)) => (
            ExitCode::SUCCESS,
            survivors,
            dismissed,
            needs_human_review,
            unverdicted,
            rendered_bytes,
        ),
        Err(_) => (ExitCode::from(2), 0, 0, 0, 0, 0),
    }
}

/// Benchmark unresolved-callee normalization, blind-spot grouping, and compact
/// JSON serialization without project I/O. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_security_blind_spots_json(
    root: &Path,
    diagnostics: &[fallow_types::results::SecurityUnresolvedCalleeDiagnostic],
) -> SecurityBlindSpotsBenchmarkResult {
    security::benchmark_security_blind_spots_json(root, diagnostics)
}

/// Benchmark hook for the production list inventory and JSON rendering
/// pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_list_json(root: &Path, threads: usize) -> (ExitCode, usize, usize, usize, usize) {
    match list::benchmark_list_json(root, threads) {
        Ok((file_count, entry_point_count, workspace_count, rendered_bytes)) => (
            ExitCode::SUCCESS,
            file_count,
            entry_point_count,
            workspace_count,
            rendered_bytes,
        ),
        Err(code) => (code, 0, 0, 0, 0),
    }
}

/// Benchmark hook for the production boundaries listing and compact JSON
/// rendering pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_list_boundaries_json(
    root: &Path,
    threads: usize,
) -> (ExitCode, usize, usize, usize, usize) {
    match list::benchmark_list_boundaries_json(root, threads) {
        Ok((zone_count, rule_count, matched_file_count, rendered_bytes)) => (
            ExitCode::SUCCESS,
            zone_count,
            rule_count,
            matched_file_count,
            rendered_bytes,
        ),
        Err(code) => (code, 0, 0, 0, 0),
    }
}

/// Opaque deterministic global matcher for the watch-filter benchmark. This is
/// not a supported API.
#[doc(hidden)]
pub use watch::WatchFilterBenchmarkGlobalGitignore;

/// Build a deterministic global gitignore matcher outside the timed watch
/// benchmark. This is not a supported API.
#[doc(hidden)]
pub fn create_watch_filter_benchmark_global_gitignore() -> WatchFilterBenchmarkGlobalGitignore {
    watch::create_benchmark_global_gitignore()
}

/// Benchmark hook for production watch-filter initialization and project
/// gitignore discovery. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_watch_filter_initialization(
    config: &fallow_config::ResolvedConfig,
    global_gitignore: &WatchFilterBenchmarkGlobalGitignore,
) -> (usize, usize) {
    watch::benchmark_filter_initialization(config, global_gitignore)
}

/// Benchmark hook for the production Viz analysis, payload, and HTML
/// rendering pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_viz_html(root: &Path, threads: usize) -> (ExitCode, usize, usize, usize) {
    match viz::benchmark_viz_html(root, threads) {
        Ok((file_count, edge_count, rendered_bytes)) => {
            (ExitCode::SUCCESS, file_count, edge_count, rendered_bytes)
        }
        Err(code) => (code, 0, 0, 0),
    }
}

/// Benchmark hook for the production rule-pack analysis and JSON rendering
/// pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_rule_pack_test_json(root: &Path, threads: usize) -> (ExitCode, usize, usize) {
    match rule_pack::benchmark_rule_pack_test_json(root, threads) {
        Ok((finding_count, rendered_bytes)) => (ExitCode::SUCCESS, finding_count, rendered_bytes),
        Err(code) => (code, 0, 0),
    }
}

/// Benchmark hook for the production recommendation discovery and compact JSON
/// rendering pipeline. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_recommend_json(root: &Path) -> (ExitCode, usize, usize, bool, usize) {
    match onboarding::benchmark_recommend_json(root) {
        Ok((decision_count, framework_count, heterogeneous, rendered_bytes)) => (
            ExitCode::SUCCESS,
            decision_count,
            framework_count,
            heterogeneous,
            rendered_bytes,
        ),
        Err(_) => (ExitCode::from(2), 0, 0, false, 0),
    }
}

/// Benchmark hook for local runtime coverage analysis and compact JSON
/// rendering with an in-process sidecar response. This is not a supported API.
#[doc(hidden)]
pub fn benchmark_runtime_coverage_analyze_json(
    root: &Path,
    runtime_coverage_path: &Path,
    response_bytes: &[u8],
    threads: usize,
) -> (ExitCode, usize, usize, usize, String) {
    match coverage::benchmark_local_json(root, runtime_coverage_path, response_bytes, threads) {
        Ok((finding_count, hot_path_count, request_bytes, rendered)) => (
            ExitCode::SUCCESS,
            finding_count,
            hot_path_count,
            request_bytes,
            rendered,
        ),
        Err(code) => (code, 0, 0, 0, String::new()),
    }
}

/// Status bars refresh frequently, so their local read path bypasses telemetry,
/// update checks, notices, and every other command epilogue.
fn is_impact_statusline(cli: &Cli) -> bool {
    matches!(
        cli.command.as_ref(),
        Some(Command::Impact {
            subcommand: Some(ImpactCli::Statusline),
            all: false,
            ..
        })
    )
}

/// Redirect the rendered report to `--output-file` (ambient sink), dispatch the
/// command, then flush+close the report file. Returns the dispatch exit code, or
/// `Err` carrying a redirect/finalize failure code for `main` to return directly.
fn dispatch_and_finalize(
    dispatch: &DispatchContext<'_>,
    command: Option<Command>,
) -> Result<ExitCode, ExitCode> {
    let cli = dispatch.cli;
    let output = dispatch.output;
    let quiet = dispatch.quiet;

    // Set up the report-file sink before dispatch so rendering lands in the file;
    // progress and the confirmation stay on stderr.
    if let Some(path) = cli.output_file.as_deref()
        && let Err(code) = redirect_report_to_file(path, output)
    {
        return Err(code);
    }

    let exit_code = if command.is_some() && cli_has_bare_coverage_input(cli) {
        emit_error(bare_coverage_subcommand_error_message(), 2, output)
    } else {
        match command {
            None => dispatch_bare_command(dispatch),
            Some(cmd) => dispatch_subcommand(cmd, dispatch),
        }
    };

    if let Some(path) = cli.output_file.as_deref()
        && let Err(code) = finalize_report_file(path, quiet, output)
    {
        return Err(code);
    }
    Ok(exit_code)
}

fn run_telemetry_command_if_requested(
    cli: &mut Cli,
    output: fallow_config::OutputFormat,
    json_style: json_style::JsonStyle,
) -> Option<ExitCode> {
    if matches!(cli.command, Some(Command::Telemetry { .. }))
        && let Some(Command::Telemetry { subcommand }) = cli.command.take()
    {
        return Some(telemetry::run(
            map_telemetry_subcommand(subcommand),
            output,
            json_style,
        ));
    }
    None
}

/// Doctor deliberately bypasses the normal run epilogue: collecting readiness
/// must not write telemetry, flush a spool, perform an update check, or create
/// caches. Root validation stays inside the typed report so failures still
/// return the complete doctor envelope.
fn run_doctor_command_if_requested(cli: &Cli, format: &FormatConfig) -> Option<ExitCode> {
    if !matches!(cli.command, Some(Command::Doctor)) {
        return None;
    }

    if let Some(flag) = unsupported_doctor_option(cli) {
        let message = if flag == "--output-file" {
            "--output-file is not valid with `fallow doctor`; doctor is read-only and writes its report to stdout".to_string()
        } else {
            format!("{flag} is not valid with `fallow doctor`.")
        };
        return Some(crate::error::emit_error_with_style(
            &message,
            2,
            format.output,
            format.json_style,
        ));
    }
    if let Err(code) = doctor::validate_output(format.output, format.json_style) {
        return Some(code);
    }

    let root = cli.root.clone().unwrap_or_else(|| {
        std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."))
    });
    let config_path = cli.config.as_ref().map(|path| {
        if path_util::is_absolute_path_any_platform(path) {
            path.clone()
        } else {
            root.join(path)
        }
    });
    let report = doctor::collect_report(&root, config_path.as_deref());
    Some(doctor::render_report(
        &report,
        format.output,
        format.json_style,
    ))
}

/// Doctor accepts only project selection and presentation options. Rejecting
/// analysis flags avoids implying that a readiness check ran an analysis or
/// applied a gate that it deliberately bypasses.
fn unsupported_doctor_option(cli: &Cli) -> Option<&'static str> {
    [
        (cli.allow_remote_extends, "--allow-remote-extends"),
        (cli.no_cache, "--no-cache"),
        (cli.threads.is_some(), "--threads"),
        (cli.changed_since.is_some(), "--changed-since"),
        (cli.diff_file.is_some(), "--diff-file"),
        (cli.diff_stdin, "--diff-stdin"),
        (cli.churn_file.is_some(), "--churn-file"),
        (cli.max_file_size.is_some(), "--max-file-size"),
        (cli.baseline.is_some(), "--baseline"),
        (cli.baseline_mode.is_some(), "--baseline-mode"),
        (cli.parent_run.is_some(), "--parent-run"),
        (cli.save_baseline.is_some(), "--save-baseline"),
        (cli.production, "--production"),
        (cli.no_production, "--no-production"),
        (cli.production_dead_code, "--production-dead-code"),
        (cli.production_health, "--production-health"),
        (cli.production_dupes, "--production-dupes"),
        (cli.workspace.is_some(), "--workspace"),
        (cli.changed_workspaces.is_some(), "--changed-workspaces"),
        (cli.group_by.is_some(), "--group-by"),
        (cli.performance, "--performance"),
        (cli.explain, "--explain"),
        (cli.explain_skipped, "--explain-skipped"),
        (cli.summary, "--summary"),
        (cli.ci, "--ci"),
        (cli.fail_on_issues, "--fail-on-issues"),
        (cli.sarif_file.is_some(), "--sarif-file"),
        (cli.output_file.is_some(), "--output-file"),
        (cli.report_path_prefix.is_some(), "--report-path-prefix"),
        (cli.fail_on_regression, "--fail-on-regression"),
        (cli.tolerance != "0", "--tolerance"),
        (cli.regression_baseline.is_some(), "--regression-baseline"),
        (
            cli.save_regression_baseline.is_some(),
            "--save-regression-baseline",
        ),
        (!cli.only.is_empty(), "--only"),
        (!cli.skip.is_empty(), "--skip"),
        (cli.dupes_mode.is_some(), "--dupes-mode"),
        (cli.dupes_near, "--dupes-near"),
        (cli.dupes_threshold.is_some(), "--dupes-threshold"),
        (cli.dupes_min_tokens.is_some(), "--dupes-min-tokens"),
        (cli.dupes_min_lines.is_some(), "--dupes-min-lines"),
        (
            cli.dupes_min_occurrences.is_some(),
            "--dupes-min-occurrences",
        ),
        (cli.dupes_skip_local, "--dupes-skip-local"),
        (cli.dupes_cross_language, "--dupes-cross-language"),
        (cli.dupes_ignore_imports, "--dupes-ignore-imports"),
        (cli.dupes_no_ignore_imports, "--dupes-no-ignore-imports"),
        (cli.score, "--score"),
        (cli.trend, "--trend"),
        (cli.save_snapshot.is_some(), "--save-snapshot"),
        (cli.coverage.is_some(), "--coverage"),
        (cli.coverage_root.is_some(), "--coverage-root"),
        (cli.include_entry_exports, "--include-entry-exports"),
        (cli.type_aware, "--type-aware"),
        (cli.no_type_aware, "--no-type-aware"),
        (!cli.type_aware_project.is_empty(), "--type-aware-project"),
        (cli.type_aware_require.is_some(), "--type-aware-require"),
    ]
    .into_iter()
    .find_map(|(used, flag)| used.then_some(flag))
}

fn run_schema_command_if_requested(
    cli: &Cli,
    json_style: json_style::JsonStyle,
) -> Option<ExitCode> {
    match cli.command {
        Some(Command::Schema) => Some(schema::run_schema(json_style)),
        Some(Command::ConfigSchema) => Some(init::run_config_schema(json_style)),
        Some(Command::PluginSchema) => Some(init::run_plugin_schema(json_style)),
        Some(Command::RulePackSchema) => Some(init::run_rule_pack_schema(json_style)),
        _ => None,
    }
}

fn regression_save_targets(cli: &Cli) -> (Option<std::path::PathBuf>, bool) {
    let save_file = cli.save_regression_baseline.as_ref().and_then(|opt| {
        opt.as_ref()
            .filter(|path| !path.is_empty())
            .map(std::path::PathBuf::from)
    });
    let save_to_config = cli.save_regression_baseline.is_some() && save_file.is_none();
    (save_file, save_to_config)
}

fn dispatch_bare_command(dispatch: &DispatchContext<'_>) -> ExitCode {
    let cli = dispatch.cli;
    let (run_check, run_dupes, run_health) = combined::resolve_analyses(&cli.only, &cli.skip);
    let production = match dispatch.production_modes(
        cli.production_dead_code,
        cli.production_health,
        cli.production_dupes,
    ) {
        Ok(production) => production,
        Err(code) => return code,
    };
    // Coverage only feeds health scoring, and resolving it validates the
    // winning root. A bare run that excludes health (`--only check`,
    // `--skip health`) must neither load config for coverage nor reject a
    // relative `health.coverageRoot` it never reads.
    let coverage_inputs = if run_health {
        match resolve_health_coverage_inputs(
            dispatch,
            cli.coverage.as_deref(),
            cli.coverage_root.as_deref(),
        ) {
            Ok(inputs) => inputs,
            Err(code) => return code,
        }
    } else {
        ResolvedHealthCoverageInputs::default()
    };
    run_bare_combined(
        dispatch,
        production,
        &coverage_inputs,
        BareAnalyses {
            run_check,
            run_dupes,
            run_health,
        },
    )
}

/// Which analyses the bare `fallow` run executes (resolved from `--only`/`--skip`).
#[derive(Clone, Copy)]
struct BareAnalyses {
    run_check: bool,
    run_dupes: bool,
    run_health: bool,
}

/// Build `CombinedOptions` for a bare `fallow` invocation and run the combined
/// pipeline.
fn run_bare_combined(
    dispatch: &DispatchContext<'_>,
    production: ProductionModes,
    coverage_inputs: &ResolvedHealthCoverageInputs,
    analyses: BareAnalyses,
) -> ExitCode {
    let cli = dispatch.cli;
    let (output, quiet, fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    combined::run_combined(&combined::CombinedOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet,
        allow_remote_extends: cli.allow_remote_extends,
        fail_on_issues,
        sarif_file: cli.sarif_file.as_deref(),
        changed_since: cli.changed_since.as_deref(),
        churn_file: cli.churn_file.as_deref(),
        baseline: cli.baseline.as_deref(),
        save_baseline: cli.save_baseline.as_deref(),
        production: cli.production,
        production_dead_code: Some(production.dead_code),
        production_health: Some(production.health),
        production_dupes: Some(production.dupes),
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        group_by: cli.group_by,
        type_aware: cli.type_aware_override(),
        type_aware_projects: &cli.type_aware_project,
        type_aware_require: cli.type_aware_require.map(Into::into),
        explain: cli.explain,
        explain_skipped: cli.explain_skipped,
        performance: cli.performance,
        summary: cli.summary,
        run_check: analyses.run_check,
        run_dupes: analyses.run_dupes,
        run_health: analyses.run_health,
        dupes_mode: cli.dupes_mode,
        dupes_near: cli.dupes_near,
        dupes_threshold: cli.dupes_threshold,
        dupes_min_tokens: cli.dupes_min_tokens,
        dupes_min_lines: cli.dupes_min_lines,
        dupes_min_occurrences: cli.dupes_min_occurrences,
        dupes_skip_local: cli.dupes_skip_local,
        dupes_cross_language: cli.dupes_cross_language,
        dupes_ignore_imports: resolve_ignore_imports(
            cli.dupes_ignore_imports,
            cli.dupes_no_ignore_imports,
        ),
        score: cli.score || cli.trend,
        trend: cli.trend,
        save_snapshot: cli.save_snapshot.as_ref(),
        coverage: coverage_inputs.coverage.as_deref(),
        coverage_root: coverage_inputs.coverage_root.as_deref(),
        include_entry_exports: cli.include_entry_exports,
        regression_opts: dispatch.regression_opts(
            cli.changed_since.is_some()
                || cli.workspace.is_some()
                || cli.changed_workspaces.is_some(),
        ),
    })
}

#[allow(
    clippy::too_many_lines,
    reason = "the command router is intentionally an exhaustive top-level dispatch table"
)]
fn dispatch_subcommand(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let cli = dispatch.cli;
    let root = dispatch.root;
    let output = dispatch.output;
    let quiet = dispatch.quiet;
    match command {
        check @ Command::Check { .. } => dispatch_check_command(check, dispatch),
        Command::Watch { no_clear } => dispatch_watch(dispatch, no_clear),
        Command::TypeAware { subcommand } => dispatch_type_aware_command(dispatch, subcommand),
        Command::Doctor => unreachable!("doctor bypasses the normal dispatch epilogue"),
        Command::SimilarCode {
            subcommand,
            threshold,
            min_lines,
            top,
            file,
        } => similar_code_cli::run(similar_code_cli::SimilarCodeCliInput {
            root,
            config_path: cli.config.as_deref(),
            allow_remote_extends: cli.allow_remote_extends,
            no_cache: cli.no_cache,
            threads: dispatch.threads,
            changed_since: cli.changed_since.as_deref(),
            diff_file: cli.diff_file.as_deref(),
            workspace: cli.workspace.as_deref(),
            changed_workspaces: cli.changed_workspaces.as_deref(),
            explain: cli.explain,
            quiet,
            output,
            json_style: dispatch.json_style,
            threshold,
            min_lines,
            top,
            files: file,
            subcommand,
        }),
        Command::Inspect {
            file,
            symbol,
            symbol_chain,
            churn,
        } => dispatch_inspect_command(dispatch, file, symbol, symbol_chain, churn),
        Command::Trace {
            symbol,
            path,
            callers,
            callees,
            depth,
        } => dispatch_trace_command(dispatch, symbol, &path, callers, callees, depth),
        Command::TraceError { trace_file } => {
            trace_error::run_trace_error(&trace_error::TraceErrorOptions {
                root: dispatch.root,
                config_path: &dispatch.cli.config,
                output: dispatch.output,
                json_style: dispatch.json_style,
                no_cache: dispatch.cli.no_cache,
                threads: dispatch.threads,
                quiet: dispatch.quiet,
                allow_remote_extends: dispatch.cli.allow_remote_extends,
                trace_file: trace_file.as_deref(),
            })
        }
        fix @ Command::Fix { .. } => dispatch_fix_command(&fix, dispatch),
        init @ Command::Init { .. } => dispatch_init_command(init, root, quiet),
        Command::Hooks { subcommand } => {
            run_hooks_command(root, subcommand, output, dispatch.json_style)
        }
        Command::Agent { subcommand } => dispatch_agent_command(dispatch, subcommand),
        Command::Ci { subcommand } => {
            ci::run(map_ci_subcommand(subcommand), output, dispatch.json_style)
        }
        Command::ConfigSchema => init::run_config_schema(dispatch.json_style),
        Command::PluginSchema => init::run_plugin_schema(dispatch.json_style),
        Command::PluginCheck => plugin_check::run_plugin_check(root, output, dispatch.json_style),
        Command::RulePackSchema => init::run_rule_pack_schema(dispatch.json_style),
        Command::RulePack { subcommand } => dispatch_rule_pack_command(dispatch, subcommand),
        Command::Guard { files } => dispatch_guard_command(dispatch, &files),
        Command::CiTemplate { subcommand } => dispatch_ci_template_command(subcommand),
        Command::Config { path } => config::run_config_with_options(config::RunConfigInput {
            root,
            explicit_config: cli.config.as_deref(),
            path_only: path,
            output,
            quiet,
            json_style: dispatch.json_style,
            load_options: fallow_config::ConfigLoadOptions {
                allow_remote_extends: cli.allow_remote_extends,
            },
        }),
        Command::Recommend => onboarding::run_recommend(root, output, dispatch.json_style),
        list @ (Command::Workspaces | Command::List { .. }) => {
            dispatch_list_command(&list, dispatch)
        }
        dupes @ Command::Dupes { .. } => dispatch_dupes_command(dupes, dispatch),
        health @ Command::Health { .. } => dispatch_health_command(health, dispatch),
        Command::Flags { top } => dispatch_flags_command(dispatch, top),
        Command::Suppressions { file } => dispatch_suppressions_command(dispatch, &file),
        Command::Explain { issue_type } => {
            explain::run_explain(&issue_type.join(" "), output, dispatch.json_style)
        }
        audit @ Command::Audit { .. } => dispatch_audit_command(audit, dispatch),
        Command::AuditCache { subcommand } => dispatch_audit_cache_command(dispatch, &subcommand),
        Command::DecisionSurface { max_decisions } => {
            dispatch_decision_surface(dispatch, max_decisions)
        }
        Command::Impact {
            subcommand,
            all,
            sort,
            limit,
        } => dispatch_impact(
            root,
            quiet,
            output,
            dispatch.json_style,
            subcommand,
            ImpactCrossRepoOpts { all, sort, limit },
        ),
        security @ Command::Security { .. } => dispatch_security_command(security, dispatch),
        Command::Viz {
            output: viz_output,
            no_open,
            viz_format,
        } => dispatch_viz(dispatch, viz_output.as_deref(), no_open, viz_format),
        Command::Report { from } => {
            cli_report::run_report(&from, output, root, cli.config.as_deref())
        }
        Command::Schema => unreachable!("handled above"),
        migrate @ Command::Migrate { .. } => dispatch_migrate_command(migrate, root),
        Command::License { subcommand } => {
            dispatch_license_command(subcommand, output, dispatch.json_style)
        }
        Command::Telemetry { .. } => unreachable!("handled before root validation"),
        Command::Coverage { subcommand } => dispatch_coverage_command(dispatch, &subcommand),
        setup_hooks @ Command::SetupHooks { .. } => {
            dispatch_setup_hooks_command(&setup_hooks, dispatch)
        }
    }
}

fn dispatch_type_aware_command(
    dispatch: &DispatchContext<'_>,
    subcommand: TypeAwareCli,
) -> ExitCode {
    match subcommand {
        TypeAwareCli::Status => {
            let status = fallow_api::type_aware_status(dispatch.root);
            match dispatch.output {
                fallow_config::OutputFormat::Json => {
                    let output = type_aware_status_output(dispatch.root, status);
                    match fallow_output::serialize_type_aware_status_json_output(
                        output,
                        crate::output_runtime::current_root_envelope_mode(),
                    ) {
                        Ok(value) => match dispatch.json_style.serialize(&value) {
                            Ok(json) => {
                                crate::report::sink::outln!("{json}");
                                ExitCode::SUCCESS
                            }
                            Err(error) => emit_error(
                                &format!("failed to serialize type-aware status: {error}"),
                                2,
                                dispatch.output,
                            ),
                        },
                        Err(error) => emit_error(
                            &format!("failed to build type-aware status: {error}"),
                            2,
                            dispatch.output,
                        ),
                    }
                }
                fallow_config::OutputFormat::Human => {
                    if status.available {
                        crate::report::sink::outln!(
                            "{}",
                            report::human_status_line(
                                report::HumanStatus::Ok,
                                format_args!(
                                    "Type-aware companion: available ({}, protocol {}, TypeScript {})",
                                    status.package_version.as_deref().unwrap_or("unknown"),
                                    status.protocol_version,
                                    status.backend_version.as_deref().unwrap_or("unknown"),
                                )
                            )
                        );
                    } else {
                        crate::report::sink::outln!(
                            "{}",
                            report::human_status_line(
                                report::HumanStatus::Inactive,
                                "Type-aware companion: unavailable"
                            )
                        );
                        if let Some(remediation) = status.remediation {
                            crate::report::sink::outln!(
                                "{}",
                                report::human_status_line(
                                    report::HumanStatus::Warning,
                                    format_args!("Action: {remediation}")
                                )
                            );
                        }
                    }
                    ExitCode::SUCCESS
                }
                _ => emit_error(
                    "type-aware status supports human and json output",
                    2,
                    dispatch.output,
                ),
            }
        }
    }
}

fn type_aware_status_output(
    root: &Path,
    status: fallow_api::TypeAwareStatus,
) -> fallow_output::TypeAwareStatusOutput {
    let companion_path = status.companion_path.as_deref().map(|path| {
        if let Ok(relative) = path.strip_prefix(root)
            && !relative.as_os_str().is_empty()
        {
            relative.to_string_lossy().replace('\\', "/")
        } else {
            path.file_name()
                .unwrap_or(path.as_os_str())
                .to_string_lossy()
                .into_owned()
        }
    });
    let remediation = status.remediation.map(|message| {
        let without_root = message.replace(root.to_string_lossy().as_ref(), ".");
        status.companion_path.as_deref().map_or_else(
            || without_root.clone(),
            |path| {
                without_root.replace(
                    path.to_string_lossy().as_ref(),
                    companion_path.as_deref().unwrap_or("fallow-type-aware"),
                )
            },
        )
    });
    fallow_output::TypeAwareStatusOutput {
        schema_version: fallow_types::envelope::SchemaVersion(
            fallow_output::TYPE_AWARE_STATUS_SCHEMA_VERSION,
        ),
        version: fallow_types::envelope::ToolVersion(env!("CARGO_PKG_VERSION").to_string()),
        available: status.available,
        discovery_source: status.discovery_source.map(str::to_string),
        companion_path,
        package_version: status.package_version,
        protocol_version: status.protocol_version,
        backend_family: status.backend_family,
        backend_version: status.backend_version,
        remediation,
    }
}

/// Destructure the `Command::Check` arm and forward to `dispatch_check`.
fn dispatch_check_command(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let filters = check_issue_filters(&command);
    let Command::Check {
        include_dupes,
        trace,
        trace_file,
        trace_dependency,
        impact_closure,
        symbol_impact,
        top,
        file,
        ..
    } = command
    else {
        unreachable!("check dispatcher only handles check commands");
    };

    dispatch_check(
        dispatch,
        &CheckDispatchArgs {
            filters,
            trace_opts: TraceOptions {
                trace_export: trace,
                trace_file,
                trace_dependency,
                impact_closure,
                symbol_impact,
                performance: dispatch.cli.performance,
            },
            include_dupes,
            type_aware: dispatch.cli.type_aware_override(),
            type_aware_project: dispatch.cli.type_aware_project.clone(),
            type_aware_require: dispatch.cli.type_aware_require,
            top,
            file,
        },
    )
}

/// Map the `Command::Check` filter flags onto `IssueFilters`. Reads the flags by
/// reference (all `Copy` bools) so the caller can still move the non-filter
/// fields out of the same `Command` value afterwards. Split into two halves to
/// keep each builder within the unit-size limit.
fn check_issue_filters(command: &Command) -> IssueFilters {
    check_issue_filters_framework(command, &check_issue_filters_core(command))
}

/// First half of the `IssueFilters` mapping: core/general filter flags over a
/// `Default` base. The framework/catalog half layers on top via struct update.
fn check_issue_filters_core(command: &Command) -> IssueFilters {
    let Command::Check {
        unused_files,
        unused_exports,
        unused_deps,
        unused_types,
        private_type_leaks,
        unused_enum_members,
        unused_class_members,
        unresolved_imports,
        unlisted_deps,
        duplicate_exports,
        circular_deps,
        re_export_cycles,
        boundary_violations,
        policy_violations,
        stale_suppressions,
        ..
    } = command
    else {
        unreachable!("check filter builder only handles check commands");
    };

    let mut filters = IssueFilters::default();
    for (flag, active) in [
        ("--unused-files", *unused_files),
        ("--unused-exports", *unused_exports),
        ("--unused-deps", *unused_deps),
        ("--unused-types", *unused_types),
        ("--private-type-leaks", *private_type_leaks),
        ("--unused-enum-members", *unused_enum_members),
        ("--unused-class-members", *unused_class_members),
        ("--unresolved-imports", *unresolved_imports),
        ("--unlisted-deps", *unlisted_deps),
        ("--duplicate-exports", *duplicate_exports),
        ("--circular-deps", *circular_deps),
        ("--re-export-cycles", *re_export_cycles),
        ("--boundary-violations", *boundary_violations),
        ("--policy-violations", *policy_violations),
        ("--stale-suppressions", *stale_suppressions),
    ] {
        enable_check_filter(&mut filters, flag, active);
    }
    filters
}

/// Second half of the `IssueFilters` mapping: framework/component, store, svelte,
/// catalog, and dependency-override flags, layered onto the core `base`.
fn check_issue_filters_framework(command: &Command, base: &IssueFilters) -> IssueFilters {
    let Command::Check {
        unused_store_members,
        unprovided_injects,
        unrendered_components,
        unused_component_props,
        unused_component_emits,
        unused_component_inputs,
        unused_component_outputs,
        unused_svelte_events,
        unused_server_actions,
        unused_load_data_keys,
        unused_catalog_entries,
        empty_catalog_groups,
        unresolved_catalog_references,
        unused_dependency_overrides,
        misconfigured_dependency_overrides,
        ..
    } = command
    else {
        unreachable!("check filter builder only handles check commands");
    };

    let mut filters = base.clone();
    for (flag, active) in [
        ("--unused-store-members", *unused_store_members),
        ("--unprovided-injects", *unprovided_injects),
        ("--unrendered-components", *unrendered_components),
        ("--unused-component-props", *unused_component_props),
        ("--unused-component-emits", *unused_component_emits),
        ("--unused-component-inputs", *unused_component_inputs),
        ("--unused-component-outputs", *unused_component_outputs),
        ("--unused-svelte-events", *unused_svelte_events),
        ("--unused-server-actions", *unused_server_actions),
        ("--unused-load-data-keys", *unused_load_data_keys),
        ("--unused-catalog-entries", *unused_catalog_entries),
        ("--empty-catalog-groups", *empty_catalog_groups),
        (
            "--unresolved-catalog-references",
            *unresolved_catalog_references,
        ),
        (
            "--unused-dependency-overrides",
            *unused_dependency_overrides,
        ),
        (
            "--misconfigured-dependency-overrides",
            *misconfigured_dependency_overrides,
        ),
    ] {
        enable_check_filter(&mut filters, flag, active);
    }
    filters
}

fn enable_check_filter(filters: &mut IssueFilters, flag: &str, active: bool) {
    if active {
        assert!(
            filters.enable_cli_filter_flag(flag),
            "check command uses unregistered dead-code filter flag {flag}"
        );
    }
}

fn dispatch_inspect_command(
    dispatch: &DispatchContext<'_>,
    file: Option<String>,
    symbol: Option<String>,
    symbol_chain: bool,
    churn: bool,
) -> ExitCode {
    let target = match (file, symbol) {
        (Some(file), None) => inspect::InspectTarget::File { file },
        (None, Some(symbol)) => match selector::parse_file_symbol_selector(&symbol) {
            Some((file, export_name)) => inspect::InspectTarget::Symbol {
                file: file.to_string(),
                export_name: export_name.to_string(),
            },
            None => {
                return emit_error(
                    "--symbol must be formatted as FILE:EXPORT",
                    2,
                    dispatch.output,
                );
            }
        },
        _ => {
            return emit_error(
                "inspect requires exactly one of --file or --symbol",
                2,
                dispatch.output,
            );
        }
    };

    let churn_config = if churn {
        match load_config_for_analysis(
            dispatch.root,
            &dispatch.cli.config,
            ConfigLoadOptions {
                output: dispatch.output,
                no_cache: dispatch.cli.no_cache,
                threads: dispatch.threads,
                production_override: None,
                quiet: dispatch.quiet,
                allow_remote_extends: dispatch.cli.allow_remote_extends,
            },
            fallow_config::ProductionAnalysis::Health,
        ) {
            Ok(config) => Some(config),
            Err(code) => return code,
        }
    } else {
        None
    };

    inspect::run_inspect(&inspect::InspectOptions {
        root: dispatch.root,
        config_path: dispatch.cli.config.as_ref(),
        output: dispatch.output,
        json_style: dispatch.json_style,
        no_cache: dispatch.cli.no_cache,
        no_production: dispatch.cli.no_production,
        max_file_size: dispatch.cli.max_file_size,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        production: dispatch.cli.production,
        workspace: dispatch.cli.workspace.as_ref(),
        target,
        churn_cache_dir: churn_config
            .as_ref()
            .map(|config| config.cache_dir.as_path()),
        symbol_chain,
        type_aware: dispatch.cli.type_aware_override(),
        type_aware_projects: &dispatch.cli.type_aware_project,
        type_aware_require: dispatch.cli.type_aware_require.map(Into::into),
    })
}

fn dispatch_trace_command(
    dispatch: &DispatchContext<'_>,
    symbol: Option<String>,
    path: &[String],
    callers: bool,
    callees: bool,
    depth: Option<u32>,
) -> ExitCode {
    if let [from, to] = path {
        return trace_path::run_trace_path(&trace_path::TracePathOptions {
            root: dispatch.root,
            config_path: &dispatch.cli.config,
            output: dispatch.output,
            json_style: dispatch.json_style,
            no_cache: dispatch.cli.no_cache,
            threads: dispatch.threads,
            quiet: dispatch.quiet,
            allow_remote_extends: dispatch.cli.allow_remote_extends,
            from,
            to,
        });
    }
    let Some(symbol) = symbol else {
        return emit_error(
            "trace requires a FILE:SYMBOL target or --path <FROM> <TO>",
            2,
            dispatch.output,
        );
    };
    trace_chain::run_trace(&trace_chain::TraceChainOptions {
        root: dispatch.root,
        config_path: &dispatch.cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        no_cache: dispatch.cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        allow_remote_extends: dispatch.cli.allow_remote_extends,
        target: symbol,
        callers,
        callees,
        depth: depth.unwrap_or(fallow_types::trace_chain::DEFAULT_TRACE_DEPTH),
    })
}

fn dispatch_security_command(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::Security {
        subcommand,
        runtime_coverage,
        min_invocations_hot,
        file,
        gate,
        surface,
    } = command
    else {
        unreachable!("security dispatcher only handles security commands");
    };

    let gate = gate.map(security::SecurityGateArg::into_mode);
    let cli = dispatch.cli;
    let (output, _quiet, fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    let derived_flags = SecurityDerivedFlagState {
        output,
        json_style: dispatch.json_style,
        ci: cli.ci,
        fail_on_issues,
        sarif_file: cli.sarif_file.as_deref(),
        summary: cli.summary,
        explain: cli.explain,
        runtime_coverage: runtime_coverage.as_deref(),
        min_invocations_hot,
        file: file.as_slice(),
        gate,
        surface,
    };
    if let Some(code) = try_run_security_survivors(subcommand.as_ref(), &derived_flags) {
        return code;
    }

    let scoped_files = scoped_security_files(&file, subcommand.as_ref());
    run_security_blind_spots_or_default(
        dispatch,
        &SecurityRunInputs {
            scoped_files: &scoped_files,
            subcommand: &subcommand,
            runtime_coverage: runtime_coverage.as_deref(),
            min_invocations_hot,
            gate,
            surface,
        },
        &derived_flags,
    )
}

/// Inputs threaded from the security dispatcher into the run step. Borrows the
/// scoped file list and subcommand so they outlive the `SecurityOptions`.
struct SecurityRunInputs<'a> {
    scoped_files: &'a [PathBuf],
    subcommand: &'a Option<SecuritySubcommand>,
    runtime_coverage: Option<&'a Path>,
    min_invocations_hot: u64,
    gate: Option<security::SecurityGateMode>,
    surface: bool,
}

/// Build `SecurityOptions` and run either the blind-spots or default analysis.
fn run_security_blind_spots_or_default(
    dispatch: &DispatchContext<'_>,
    inputs: &SecurityRunInputs<'_>,
    derived_flags: &SecurityDerivedFlagState<'_>,
) -> ExitCode {
    let cli = dispatch.cli;
    let (output, quiet, fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    let opts = security::SecurityOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet,
        allow_remote_extends: cli.allow_remote_extends,
        fail_on_issues,
        sarif_file: cli.sarif_file.as_deref(),
        summary: cli.summary,
        changed_since: cli.changed_since.as_deref(),
        use_shared_diff_index: true,
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        file: inputs.scoped_files,
        surface: inputs.surface,
        gate: inputs.gate,
        runtime_coverage: inputs.runtime_coverage,
        min_invocations_hot: inputs.min_invocations_hot,
        explain: cli.explain,
    };
    if matches!(
        inputs.subcommand,
        Some(SecuritySubcommand::BlindSpots { .. })
    ) {
        if let Some(code) = validate_security_blind_spots_flags(derived_flags) {
            return code;
        }
        security::run_blind_spots(&opts)
    } else {
        security::run(&opts)
    }
}

/// Handle `fallow security survivors` as an early return. Returns `Some(code)`
/// when the subcommand is `survivors` (validated then run); `None` otherwise.
fn try_run_security_survivors(
    subcommand: Option<&SecuritySubcommand>,
    flags: &SecurityDerivedFlagState<'_>,
) -> Option<ExitCode> {
    let Some(SecuritySubcommand::Survivors {
        candidates,
        verdicts,
        require_verdict_for_each_candidate,
    }) = subcommand
    else {
        return None;
    };
    if let Some(code) = validate_security_survivors_flags(flags) {
        return Some(code);
    }
    Some(security::run_survivors(
        &security::SecuritySurvivorsOptions {
            output: flags.output,
            json_style: flags.json_style,
            candidates,
            verdicts,
            require_verdict_for_each_candidate: *require_verdict_for_each_candidate,
        },
    ))
}

/// Build the scoped file list, folding in `blind-spots` extra `--file` values.
fn scoped_security_files(
    file: &[PathBuf],
    subcommand: Option<&SecuritySubcommand>,
) -> Vec<PathBuf> {
    let mut scoped_files = file.to_vec();
    if let Some(SecuritySubcommand::BlindSpots {
        file: blind_spot_files,
    }) = subcommand
    {
        scoped_files.extend(blind_spot_files.iter().cloned());
    }
    scoped_files
}

struct SecurityDerivedFlagState<'a> {
    output: fallow_config::OutputFormat,
    json_style: json_style::JsonStyle,
    ci: bool,
    fail_on_issues: bool,
    sarif_file: Option<&'a Path>,
    summary: bool,
    explain: bool,
    runtime_coverage: Option<&'a Path>,
    min_invocations_hot: u64,
    file: &'a [PathBuf],
    gate: Option<security::SecurityGateMode>,
    surface: bool,
}

fn validate_security_survivors_flags(flags: &SecurityDerivedFlagState<'_>) -> Option<ExitCode> {
    let flag = if flags.ci {
        Some("--ci")
    } else if flags.fail_on_issues {
        Some("--fail-on-issues")
    } else if flags.sarif_file.is_some() {
        Some("--sarif-file")
    } else if flags.summary {
        Some("--summary")
    } else if flags.explain {
        Some("--explain")
    } else if flags.runtime_coverage.is_some() {
        Some("--runtime-coverage")
    } else if flags.min_invocations_hot != DEFAULT_MIN_INVOCATIONS_HOT {
        Some("--min-invocations-hot")
    } else if !flags.file.is_empty() {
        Some("--file")
    } else if flags.gate.is_some() {
        Some("--gate")
    } else if flags.surface {
        Some("--surface")
    } else {
        None
    }?;
    Some(emit_error(
        &format!("{flag} is not valid with `fallow security survivors`."),
        2,
        flags.output,
    ))
}

fn validate_security_blind_spots_flags(flags: &SecurityDerivedFlagState<'_>) -> Option<ExitCode> {
    let flag = if flags.ci {
        Some("--ci")
    } else if flags.fail_on_issues {
        Some("--fail-on-issues")
    } else if flags.sarif_file.is_some() {
        Some("--sarif-file")
    } else if flags.summary {
        Some("--summary")
    } else if flags.explain {
        Some("--explain")
    } else if flags.runtime_coverage.is_some() {
        Some("--runtime-coverage")
    } else if flags.min_invocations_hot != DEFAULT_MIN_INVOCATIONS_HOT {
        Some("--min-invocations-hot")
    } else if flags.gate.is_some() {
        Some("--gate")
    } else if flags.surface {
        Some("--surface")
    } else {
        None
    }?;
    Some(emit_error(
        &format!("{flag} is not valid with `fallow security blind-spots`."),
        2,
        flags.output,
    ))
}

fn dispatch_dupes_command(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::Dupes {
        mode,
        near,
        min_tokens,
        min_lines,
        min_occurrences,
        threshold,
        skip_local,
        cross_language,
        ignore_imports,
        no_ignore_imports,
        top,
        no_fragments,
        trace,
    } = command
    else {
        unreachable!("dupes dispatcher only handles dupes commands");
    };

    dispatch_dupes(
        dispatch,
        &DupesDispatchArgs {
            mode,
            near,
            min_tokens,
            min_lines,
            min_occurrences,
            threshold,
            skip_local,
            cross_language,
            ignore_imports,
            no_ignore_imports,
            top,
            no_fragments,
            trace,
        },
    )
}

fn dispatch_agent_command(dispatch: &DispatchContext<'_>, subcommand: AgentCli) -> ExitCode {
    run_agent_command(
        dispatch.root,
        dispatch.cli.root.is_some(),
        subcommand,
        dispatch.output,
        dispatch.json_style,
    )
}

fn dispatch_init_command(command: Command, root: &Path, quiet: bool) -> ExitCode {
    let Command::Init {
        toml,
        agents,
        hooks,
        branch,
        decline,
    } = command
    else {
        unreachable!("init dispatcher only handles init commands");
    };

    init::run_init(&init::InitOptions {
        root,
        use_toml: toml,
        agents,
        hooks,
        branch: branch.as_deref(),
        decline,
        quiet,
    })
}

fn dispatch_fix_command(command: &Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::Fix {
        dry_run,
        yes,
        no_create_config,
    } = command
    else {
        unreachable!("fix dispatcher only handles fix commands");
    };

    dispatch_fix(
        dispatch,
        FixDispatchArgs {
            dry_run: *dry_run,
            yes: *yes,
            no_create_config: *no_create_config,
        },
    )
}

fn dispatch_list_command(command: &Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    match command {
        Command::Workspaces => dispatch_list(dispatch, ListDispatchArgs::workspaces()),
        Command::List {
            entry_points,
            files,
            plugins,
            boundaries,
            workspaces,
        } => dispatch_list(
            dispatch,
            ListDispatchArgs {
                entry_points: *entry_points,
                files: *files,
                plugins: *plugins,
                boundaries: *boundaries,
                workspaces: *workspaces,
            },
        ),
        _ => unreachable!("list dispatcher only handles list commands"),
    }
}

fn dispatch_migrate_command(command: Command, root: &Path) -> ExitCode {
    let Command::Migrate {
        toml,
        jsonc,
        dry_run,
        from,
    } = command
    else {
        unreachable!("migrate dispatcher only handles migrate commands");
    };

    migrate::run_migrate(root, toml, jsonc, dry_run, from.as_deref())
}

fn dispatch_license_command(
    subcommand: LicenseCli,
    output: fallow_config::OutputFormat,
    json_style: json_style::JsonStyle,
) -> ExitCode {
    license::run(&map_license_subcommand(subcommand), output, json_style)
}

fn dispatch_ci_template_command(subcommand: CiTemplateCli) -> ExitCode {
    match subcommand {
        CiTemplateCli::Gitlab { vendor, force } => {
            ci_template::run_gitlab_template(&ci_template::GitlabTemplateOptions {
                vendor_dir: vendor,
                force,
            })
        }
    }
}

fn dispatch_coverage_command(dispatch: &DispatchContext<'_>, subcommand: &CoverageCli) -> ExitCode {
    let cli = dispatch.cli;
    coverage::run(
        map_coverage_subcommand(subcommand, cli.explain),
        &coverage::RunContext {
            root: dispatch.root,
            config_path: &cli.config,
            output: dispatch.output,
            json_style: dispatch.json_style,
            quiet: dispatch.quiet,
            no_cache: cli.no_cache,
            threads: dispatch.threads,
            explain: cli.explain,
            allow_remote_extends: cli.allow_remote_extends,
        },
    )
}

fn dispatch_health_command(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::Health {
        max_cyclomatic,
        max_cognitive,
        max_crap,
        top,
        sort,
        complexity,
        complexity_breakdown,
        file_scores,
        coverage_gaps,
        hotspots,
        ownership,
        ownership_emails,
        targets,
        type_coupling,
        css,
        effort,
        score,
        min_score,
        min_severity,
        report_only,
        since,
        min_commits,
        save_snapshot,
        trend,
        coverage,
        coverage_root,
        runtime_coverage,
        min_invocations_hot,
        min_observation_volume,
        low_traffic_threshold,
    } = command
    else {
        unreachable!("health dispatcher only handles health commands");
    };

    let ownership = ownership || ownership_emails.is_some();
    let hotspots = hotspots || ownership;
    let args = HealthDispatchArgs {
        max_cyclomatic,
        max_cognitive,
        max_crap,
        top,
        sort,
        complexity,
        complexity_breakdown,
        file_scores,
        coverage_gaps,
        hotspots,
        ownership,
        ownership_emails: ownership_emails.map(EmailModeArg::to_config),
        targets,
        type_coupling,
        css,
        effort,
        score,
        min_score,
        min_severity: min_severity.map(HealthSeverityCli::to_health_severity),
        report_only,
        since: since.as_deref(),
        min_commits,
        save_snapshot: save_snapshot.as_ref(),
        trend,
        coverage: coverage.as_deref(),
        coverage_root: coverage_root.as_deref(),
        runtime_coverage: runtime_coverage.as_deref(),
        min_invocations_hot,
        min_observation_volume,
        low_traffic_threshold,
    };
    dispatch_health(dispatch, &args)
}

fn dispatch_setup_hooks_command(command: &Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::SetupHooks {
        agent,
        dry_run,
        force,
        user,
        gitignore_claude,
        uninstall,
    } = command
    else {
        unreachable!("setup-hooks dispatcher only handles setup-hooks commands");
    };

    eprintln!(
        "warning: `fallow setup-hooks` is deprecated and will be removed in the next major; use `fallow agent install` or `fallow hooks install --target agent`."
    );
    setup_hooks::run_setup_hooks(&setup_hooks::SetupHooksOptions {
        root: dispatch.root,
        agent: *agent,
        dry_run: *dry_run,
        force: *force,
        user: *user,
        gitignore_claude: *gitignore_claude,
        uninstall: *uninstall,
    })
}

fn dispatch_audit_command(command: Command, dispatch: &DispatchContext<'_>) -> ExitCode {
    let Command::Audit {
        production_dead_code,
        production_health,
        production_dupes,
        dead_code_baseline,
        health_baseline,
        dupes_baseline,
        max_crap,
        coverage,
        coverage_root,
        no_css,
        css_deep,
        no_css_deep,
        gate,
        runtime_coverage,
        min_invocations_hot,
        gate_marker,
        brief,
        max_decisions,
        walkthrough_guide,
        walkthrough_file,
        walkthrough,
        mark_viewed,
        show_cleared,
        show_deprioritized,
    } = command
    else {
        unreachable!("audit dispatcher only handles audit commands");
    };

    // The walkthrough flags imply the brief path (the guide digest + the
    // graph-snapshot pin are brief-path data).
    let brief = brief || walkthrough_guide || walkthrough || walkthrough_file.is_some();

    dispatch_audit(
        dispatch,
        &AuditDispatchArgs {
            production_dead_code,
            production_health,
            production_dupes,
            dead_code_baseline,
            health_baseline,
            dupes_baseline,
            max_crap,
            coverage,
            coverage_root,
            no_css,
            css_deep,
            no_css_deep,
            gate,
            runtime_coverage,
            min_invocations_hot,
            gate_marker,
            brief,
            max_decisions,
            walkthrough_guide,
            walkthrough_file,
            walkthrough,
            mark_viewed,
            show_cleared,
            show_deprioritized,
        },
    )
}

fn dispatch_audit_cache_command(
    dispatch: &DispatchContext<'_>,
    subcommand: &AuditCacheCli,
) -> ExitCode {
    match subcommand {
        AuditCacheCli::Remove { dry_run, yes } => {
            if !*dry_run && !*yes && !std::io::stdin().is_terminal() {
                return emit_error(
                    "audit-cache remove requires --yes (or --force) in non-interactive environments. Use --dry-run to preview removal first, then pass --yes to confirm.",
                    2,
                    dispatch.output,
                );
            }
            match base_worktree::remove_reusable_audit_caches(dispatch.root, *dry_run) {
                Ok(report) => {
                    let action = if *dry_run { "would remove" } else { "removed" };
                    if matches!(dispatch.output, fallow_config::OutputFormat::Json) {
                        let value = serde_json::json!({
                            "kind": "audit-cache-remove",
                            "schema_version": 1,
                            "command": "audit-cache remove",
                            "root": dispatch.root,
                            "dry_run": report.dry_run,
                            "found": report.found,
                            "would_remove": report.found.saturating_sub(report.skipped),
                            "removed": report.removed,
                            "skipped": report.skipped,
                            "complete": report.skipped == 0,
                        });
                        let output_code = report::emit_report_json(
                            &value,
                            "audit cache removal",
                            dispatch.json_style,
                        );
                        if output_code != ExitCode::SUCCESS {
                            return output_code;
                        }
                    } else if !dispatch.quiet {
                        println!(
                            "audit cache: {action} {}, skipped {} for {}",
                            if *dry_run {
                                report.found.saturating_sub(report.skipped)
                            } else {
                                report.removed
                            },
                            report.skipped,
                            dispatch.root.display(),
                        );
                    }
                    if report.skipped == 0 {
                        ExitCode::SUCCESS
                    } else {
                        ExitCode::from(2)
                    }
                }
                Err(error) => emit_error(
                    &format!(
                        "failed to remove audit caches for {}: {error}",
                        dispatch.root.display()
                    ),
                    2,
                    dispatch.output,
                ),
            }
        }
        AuditCacheCli::Prune {
            dry_run,
            max_age_days,
        } => audit_cache_prune::run_audit_cache_prune(&audit_cache_prune::AuditCachePruneOptions {
            root: dispatch.root,
            config_path: dispatch.cli.config.as_ref(),
            allow_remote_extends: dispatch.cli.allow_remote_extends,
            dry_run: *dry_run,
            max_age_days: *max_age_days,
            output: dispatch.output,
            json_style: dispatch.json_style,
            quiet: dispatch.quiet,
        }),
    }
}

fn dispatch_flags_command(dispatch: &DispatchContext<'_>, top: Option<usize>) -> ExitCode {
    let cli = dispatch.cli;
    let root = dispatch.root;
    let output = dispatch.output;
    let quiet = dispatch.quiet;
    let threads = dispatch.threads;
    let production = match resolve_production_modes(cli, root, output, false, false, false) {
        Ok(modes) => modes.for_analysis(fallow_config::ProductionAnalysis::DeadCode),
        Err(code) => return code,
    };
    flags::run_flags(&flags::FlagsOptions {
        root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads,
        quiet,
        allow_remote_extends: cli.allow_remote_extends,
        production,
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        changed_since: cli.changed_since.as_deref(),
        explain: cli.explain,
        top,
    })
}

fn dispatch_suppressions_command(
    dispatch: &DispatchContext<'_>,
    file: &[std::path::PathBuf],
) -> ExitCode {
    let cli = dispatch.cli;
    let root = dispatch.root;
    let output = dispatch.output;
    let production = match resolve_production_modes(cli, root, output, false, false, false) {
        Ok(modes) => modes.for_analysis(fallow_config::ProductionAnalysis::DeadCode),
        Err(code) => return code,
    };
    suppressions::run_suppressions(&suppressions::SuppressionsOptions {
        root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        allow_remote_extends: cli.allow_remote_extends,
        production,
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        changed_since: cli.changed_since.as_deref(),
        file,
    })
}

fn dispatch_guard_command(dispatch: &DispatchContext<'_>, files: &[String]) -> ExitCode {
    guard::run_guard(&guard::GuardOptions {
        root: dispatch.root,
        config_path: &dispatch.cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        quiet: dispatch.quiet,
        allow_remote_extends: dispatch.cli.allow_remote_extends,
        files,
    })
}

fn dispatch_rule_pack_command(dispatch: &DispatchContext<'_>, subcommand: RulePackCli) -> ExitCode {
    let ctx = rule_pack::RulePackContext {
        root: dispatch.root,
        config_path: &dispatch.cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        quiet: dispatch.quiet,
        no_cache: dispatch.cli.no_cache,
        threads: Some(dispatch.threads),
        allow_remote_extends: dispatch.cli.allow_remote_extends,
    };
    rule_pack::run(&map_rule_pack_subcommand(subcommand), &ctx)
}

fn map_rule_pack_subcommand(subcommand: RulePackCli) -> rule_pack::RulePackSubcommand {
    match subcommand {
        RulePackCli::Init {
            name,
            template,
            dir,
            no_config,
        } => rule_pack::RulePackSubcommand::Init(rule_pack::InitArgs {
            name,
            template,
            dir,
            no_config,
        }),
        RulePackCli::List => rule_pack::RulePackSubcommand::List,
        RulePackCli::Test { pack } => {
            rule_pack::RulePackSubcommand::Test(rule_pack::TestArgs { pack })
        }
        RulePackCli::Schema => rule_pack::RulePackSubcommand::Schema,
    }
}

fn map_license_subcommand(sub: LicenseCli) -> license::LicenseSubcommand {
    match sub {
        LicenseCli::Activate {
            jwt,
            from_file,
            stdin,
            trial,
            email,
        } => license::LicenseSubcommand::Activate(license::ActivateArgs {
            raw_jwt: jwt,
            from_file,
            from_stdin: stdin,
            trial,
            email,
        }),
        LicenseCli::Status => license::LicenseSubcommand::Status,
        LicenseCli::Refresh { api_key } => {
            license::LicenseSubcommand::Refresh(license::RefreshArgs { api_key })
        }
        LicenseCli::Deactivate => license::LicenseSubcommand::Deactivate,
    }
}

fn map_telemetry_subcommand(sub: TelemetryCli) -> telemetry::TelemetryCommand {
    match sub {
        TelemetryCli::Status => telemetry::TelemetryCommand::Status,
        TelemetryCli::Enable => telemetry::TelemetryCommand::Enable,
        TelemetryCli::Disable => telemetry::TelemetryCommand::Disable,
        TelemetryCli::Inspect { example } => telemetry::TelemetryCommand::Inspect { example },
    }
}

fn map_ci_subcommand(sub: CiCli) -> ci::CiCommand {
    match sub {
        command @ CiCli::PlanPrComment { .. } => map_ci_plan_pr_comment(command),
        command @ CiCli::PostPrComment { .. } => map_ci_post_pr_comment(command),
        command @ CiCli::PostReview { .. } => map_ci_post_review(command),
        command @ CiCli::PostCheckRun { .. } => map_ci_post_check_run(command),
        command @ CiCli::ReconcileReview { .. } => map_ci_reconcile_review(command),
    }
}

fn map_ci_plan_pr_comment(command: CiCli) -> ci::CiCommand {
    let CiCli::PlanPrComment {
        body,
        marker_id,
        clean,
        existing_comment_id,
        existing_body,
    } = command
    else {
        unreachable!("ci plan-pr-comment mapper called with different variant");
    };

    ci::CiCommand::PlanPrComment {
        body,
        marker_id,
        clean,
        existing_comment_id,
        existing_body,
    }
}

fn map_ci_post_pr_comment(command: CiCli) -> ci::CiCommand {
    let CiCli::PostPrComment {
        provider,
        pr,
        mr,
        body,
        envelope,
        marker_id,
        clean,
        repo,
        project_id,
        api_url,
        dry_run,
    } = command
    else {
        unreachable!("ci post-pr-comment mapper called with different variant");
    };

    ci::CiCommand::PostPrComment {
        provider: map_ci_provider(provider),
        target: pr.or(mr),
        body,
        envelope,
        marker_id,
        clean,
        repo,
        project_id,
        api_url,
        dry_run,
    }
}

fn map_ci_post_review(command: CiCli) -> ci::CiCommand {
    let CiCli::PostReview {
        provider,
        pr,
        mr,
        envelope,
        repo,
        project_id,
        api_url,
        dry_run,
    } = command
    else {
        unreachable!("ci post-review mapper called with different variant");
    };

    ci::CiCommand::PostReview {
        provider: map_ci_provider(provider),
        target: pr.or(mr),
        envelope,
        repo,
        project_id,
        api_url,
        dry_run,
    }
}

fn map_ci_post_check_run(command: CiCli) -> ci::CiCommand {
    let CiCli::PostCheckRun {
        provider,
        decision,
        repo,
        head_sha,
        api_url,
        split_gates,
        dry_run,
    } = command
    else {
        unreachable!("ci post-check-run mapper called with different variant");
    };

    ci::CiCommand::PostCheckRun {
        provider: map_ci_provider(provider),
        decision,
        repo,
        head_sha,
        api_url,
        split_gates,
        dry_run,
    }
}

fn map_ci_reconcile_review(command: CiCli) -> ci::CiCommand {
    let CiCli::ReconcileReview {
        provider,
        pr,
        mr,
        envelope,
        repo,
        project_id,
        api_url,
        dry_run,
    } = command
    else {
        unreachable!("ci reconcile-review mapper called with different variant");
    };

    ci::CiCommand::ReconcileReview {
        provider: map_ci_provider(provider),
        target: pr.or(mr),
        envelope,
        repo,
        project_id,
        api_url,
        dry_run,
    }
}

fn map_ci_provider(provider: CiProviderArg) -> ci::CiProvider {
    match provider {
        CiProviderArg::Github => ci::CiProvider::Github,
        CiProviderArg::Gitlab => ci::CiProvider::Gitlab,
    }
}

fn map_coverage_subcommand(sub: &CoverageCli, explain: bool) -> coverage::CoverageSubcommand {
    match sub {
        CoverageCli::Setup {
            yes,
            non_interactive,
            json,
        } => map_coverage_setup(*yes, *non_interactive, *json, explain),
        CoverageCli::Analyze { .. } => map_coverage_analyze(sub),
        CoverageCli::UploadInventory { .. } => map_coverage_upload_inventory(sub),
        CoverageCli::UploadSourceMaps { .. } => map_coverage_upload_source_maps(sub),
        CoverageCli::UploadStaticFindings { .. } => map_coverage_upload_static_findings(sub),
    }
}

fn map_coverage_setup(
    yes: bool,
    non_interactive: bool,
    json: bool,
    explain: bool,
) -> coverage::CoverageSubcommand {
    coverage::CoverageSubcommand::Setup(coverage::SetupArgs {
        yes,
        non_interactive: non_interactive || json,
        json,
        explain,
    })
}

fn map_coverage_analyze(sub: &CoverageCli) -> coverage::CoverageSubcommand {
    let CoverageCli::Analyze {
        runtime_coverage,
        cloud,
        api_key,
        api_endpoint,
        repo,
        project_id,
        coverage_period,
        environment,
        commit_sha,
        production,
        min_invocations_hot,
        min_observation_volume,
        low_traffic_threshold,
        top,
        blast_radius,
        importance,
        debug_unmatched,
    } = sub
    else {
        unreachable!("coverage analyze mapper called with non-analyze variant");
    };
    coverage::CoverageSubcommand::Analyze(coverage::AnalyzeArgs {
        runtime_coverage: runtime_coverage.clone(),
        cloud: *cloud,
        api_key: api_key.clone(),
        api_endpoint: api_endpoint.clone(),
        repo: repo.clone(),
        project_id: project_id.clone(),
        coverage_period: *coverage_period,
        environment: environment.clone(),
        commit_sha: commit_sha.clone(),
        production: *production,
        min_invocations_hot: *min_invocations_hot,
        min_observation_volume: *min_observation_volume,
        low_traffic_threshold: *low_traffic_threshold,
        top: *top,
        blast_radius: *blast_radius,
        importance: *importance,
        debug_unmatched: *debug_unmatched,
    })
}

fn map_coverage_upload_inventory(sub: &CoverageCli) -> coverage::CoverageSubcommand {
    let CoverageCli::UploadInventory {
        api_key,
        api_endpoint,
        project_id,
        git_sha,
        allow_dirty,
        exclude_paths,
        path_prefix,
        dry_run,
        with_callers,
        ignore_upload_errors,
    } = sub
    else {
        unreachable!("coverage inventory mapper called with non-inventory variant");
    };
    coverage::CoverageSubcommand::UploadInventory(coverage::UploadInventoryArgs {
        api_key: api_key.clone(),
        api_endpoint: api_endpoint.clone(),
        project_id: project_id.clone(),
        git_sha: git_sha.clone(),
        allow_dirty: *allow_dirty,
        exclude_paths: exclude_paths.clone(),
        path_prefix: path_prefix.clone(),
        dry_run: *dry_run,
        with_callers: *with_callers,
        ignore_upload_errors: *ignore_upload_errors,
    })
}

fn map_coverage_upload_source_maps(sub: &CoverageCli) -> coverage::CoverageSubcommand {
    let CoverageCli::UploadSourceMaps {
        dir,
        include,
        exclude,
        repo,
        git_sha,
        endpoint,
        strip_path,
        dry_run,
        concurrency,
        fail_fast,
    } = sub
    else {
        unreachable!("coverage source-map mapper called with non-source-map variant");
    };
    coverage::CoverageSubcommand::UploadSourceMaps(coverage::UploadSourceMapsArgs {
        dir: dir.clone(),
        include: include.clone(),
        exclude: exclude.clone(),
        repo: repo.clone(),
        git_sha: git_sha.clone(),
        endpoint: endpoint.clone(),
        strip_path: *strip_path,
        dry_run: *dry_run,
        concurrency: *concurrency,
        fail_fast: *fail_fast,
    })
}

fn map_coverage_upload_static_findings(sub: &CoverageCli) -> coverage::CoverageSubcommand {
    let CoverageCli::UploadStaticFindings {
        api_key,
        api_endpoint,
        project_id,
        git_sha,
        allow_dirty,
        dry_run,
        ignore_upload_errors,
    } = sub
    else {
        unreachable!("coverage static-findings mapper called with non-static variant");
    };
    coverage::CoverageSubcommand::UploadStaticFindings(coverage::UploadStaticFindingsArgs {
        api_key: api_key.clone(),
        api_endpoint: api_endpoint.clone(),
        project_id: project_id.clone(),
        git_sha: git_sha.clone(),
        allow_dirty: *allow_dirty,
        dry_run: *dry_run,
        ignore_upload_errors: *ignore_upload_errors,
    })
}

struct CheckDispatchArgs {
    filters: IssueFilters,
    trace_opts: TraceOptions,
    include_dupes: bool,
    type_aware: Option<bool>,
    type_aware_project: Vec<std::path::PathBuf>,
    type_aware_require: Option<TypeAwareRequireArg>,
    top: Option<usize>,
    file: Vec<std::path::PathBuf>,
}

#[derive(Clone, Copy)]
struct ListDispatchArgs {
    entry_points: bool,
    files: bool,
    plugins: bool,
    boundaries: bool,
    workspaces: bool,
}

impl ListDispatchArgs {
    fn workspaces() -> Self {
        Self {
            entry_points: false,
            files: false,
            plugins: false,
            boundaries: false,
            workspaces: true,
        }
    }
}

fn dispatch_viz(
    dispatch: &DispatchContext<'_>,
    output_path: Option<&std::path::Path>,
    no_open: bool,
    format: viz::VizFormat,
) -> ExitCode {
    let cli = dispatch.cli;
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::DeadCode) {
        Ok(production) => production,
        Err(code) => return code,
    };
    viz::run_viz(&viz::VizOptions {
        root: dispatch.root,
        config_path: &cli.config,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        production,
        allow_remote_extends: cli.allow_remote_extends,
        output_path,
        no_open,
        format,
    })
}

fn dispatch_watch(dispatch: &DispatchContext<'_>, no_clear: bool) -> ExitCode {
    let cli = dispatch.cli;
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::DeadCode) {
        Ok(production) => production,
        Err(code) => return code,
    };
    watch::run_watch(&watch::WatchOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        allow_remote_extends: cli.allow_remote_extends,
        production,
        clear_screen: !no_clear,
        explain: cli.explain,
        include_entry_exports: cli.include_entry_exports,
        type_aware: cli.type_aware_override(),
        type_aware_projects: &cli.type_aware_project,
        type_aware_require: cli.type_aware_require.map(Into::into),
    })
}

#[derive(Clone, Copy)]
struct FixDispatchArgs {
    dry_run: bool,
    yes: bool,
    no_create_config: bool,
}

fn dispatch_fix(dispatch: &DispatchContext<'_>, args: FixDispatchArgs) -> ExitCode {
    let cli = dispatch.cli;
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::DeadCode) {
        Ok(production) => production,
        Err(code) => return code,
    };
    fix::run_fix(&fix::FixOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        emit_output: true,
        allow_remote_extends: cli.allow_remote_extends,
        dry_run: args.dry_run,
        yes: args.yes,
        production,
        no_create_config: args.no_create_config,
        type_aware: cli.type_aware_override(),
        type_aware_projects: &cli.type_aware_project,
        type_aware_require: cli.type_aware_require.map(Into::into),
    })
}

fn dispatch_list(dispatch: &DispatchContext<'_>, args: ListDispatchArgs) -> ExitCode {
    let cli = dispatch.cli;
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::DeadCode) {
        Ok(production) => production,
        Err(code) => return code,
    };
    list::run_list(&ListOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output: dispatch.output,
        json_style: dispatch.json_style,
        threads: dispatch.threads,
        no_cache: cli.no_cache,
        entry_points: args.entry_points,
        files: args.files,
        plugins: args.plugins,
        boundaries: args.boundaries,
        workspaces: args.workspaces,
        production,
        allow_remote_extends: cli.allow_remote_extends,
    })
}

fn dispatch_check(dispatch: &DispatchContext<'_>, args: &CheckDispatchArgs) -> ExitCode {
    let cli = dispatch.cli;
    let (output, quiet, fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::DeadCode) {
        Ok(production) => production,
        Err(code) => return code,
    };
    if let Some(code) = validate_type_aware_check_options(dispatch, args) {
        return code;
    }
    check::run_check(&CheckOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet,
        allow_remote_extends: cli.allow_remote_extends,
        fail_on_issues,
        filters: &args.filters,
        changed_since: cli.changed_since.as_deref(),
        diff_index: None,
        use_shared_diff_index: true,
        baseline: cli.baseline.as_deref(),
        save_baseline: cli.save_baseline.as_deref(),
        sarif_file: cli.sarif_file.as_deref(),
        production,
        production_override: Some(production),
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        group_by: cli.group_by,
        include_dupes: args.include_dupes,
        type_aware: args.type_aware,
        type_aware_config_override: None,
        type_aware_projects: &args.type_aware_project,
        type_aware_require: args.type_aware_require.map(Into::into),
        trace_opts: &args.trace_opts,
        explain: cli.explain,
        top: args.top,
        file: &args.file,
        include_entry_exports: cli.include_entry_exports,
        summary: cli.summary,
        regression_opts: dispatch.regression_opts(
            cli.changed_since.is_some()
                || cli.workspace.is_some()
                || cli.changed_workspaces.is_some()
                || !args.file.is_empty(),
        ),
        retain_modules_for_health: false,
        defer_performance: false,
        analysis_snapshot: fallow_config::AnalysisSnapshot::Current,
    })
}

fn validate_type_aware_check_options(
    dispatch: &DispatchContext<'_>,
    args: &CheckDispatchArgs,
) -> Option<ExitCode> {
    let output = dispatch.output;
    if !args.type_aware_project.is_empty() && args.type_aware != Some(true) {
        return Some(emit_error(
            "--type-aware-project requires --type-aware",
            2,
            output,
        ));
    }
    if args.type_aware_require.is_some() && args.type_aware != Some(true) {
        return Some(emit_error(
            "--type-aware-require requires --type-aware",
            2,
            output,
        ));
    }
    if args.trace_opts.symbol_impact.is_some() && args.type_aware != Some(true) {
        return Some(emit_error(
            "--symbol-impact requires --type-aware",
            2,
            output,
        ));
    }
    let focused_output = args.trace_opts.trace_export.is_some()
        || args.trace_opts.trace_file.is_some()
        || args.trace_opts.trace_dependency.is_some()
        || args.trace_opts.impact_closure.is_some()
        || args.trace_opts.symbol_impact.is_some();
    if focused_output
        && !matches!(
            output,
            fallow_config::OutputFormat::Human | fallow_config::OutputFormat::Json
        )
    {
        return Some(emit_error(
            "focused trace and impact queries support human and JSON output",
            2,
            output,
        ));
    }
    if args.type_aware == Some(true)
        && !matches!(
            output,
            fallow_config::OutputFormat::Human
                | fallow_config::OutputFormat::Json
                | fallow_config::OutputFormat::Sarif
                | fallow_config::OutputFormat::Compact
                | fallow_config::OutputFormat::Markdown
                | fallow_config::OutputFormat::CodeClimate
                | fallow_config::OutputFormat::PrCommentGithub
                | fallow_config::OutputFormat::PrCommentGitlab
                | fallow_config::OutputFormat::ReviewGithub
                | fallow_config::OutputFormat::ReviewGitlab
        )
    {
        return Some(emit_error(
            "--type-aware supports human, JSON, SARIF, compact, markdown, CodeClimate, PR-comment, and review output; pair presentation formats with the JSON artifact to preserve semantic provenance",
            2,
            output,
        ));
    }
    None
}

/// Resolve the three-state `ignoreImports` CLI override from the opt-in /
/// opt-out flag pair. clap's `conflicts_with` guarantees the two are never both
/// set, so this maps `--no-ignore-imports` -> `Some(false)`, `--ignore-imports`
/// -> `Some(true)`, and neither -> `None` (defer to config, which defaults to
/// `true`).
fn resolve_ignore_imports(ignore_imports: bool, no_ignore_imports: bool) -> Option<bool> {
    if no_ignore_imports {
        Some(false)
    } else if ignore_imports {
        Some(true)
    } else {
        None
    }
}

struct DupesDispatchArgs {
    mode: Option<DupesMode>,
    near: bool,
    min_tokens: Option<usize>,
    min_lines: Option<usize>,
    min_occurrences: Option<usize>,
    threshold: Option<f64>,
    skip_local: bool,
    cross_language: bool,
    ignore_imports: bool,
    no_ignore_imports: bool,
    top: Option<usize>,
    no_fragments: bool,
    trace: Option<String>,
}

fn dispatch_dupes(dispatch: &DispatchContext<'_>, args: &DupesDispatchArgs) -> ExitCode {
    let cli = dispatch.cli;
    let (output, quiet, _fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    let production = match dispatch.production_for(fallow_config::ProductionAnalysis::Dupes) {
        Ok(production) => production,
        Err(code) => return code,
    };
    dupes::run_dupes(&DupesOptions {
        root: dispatch.root,
        config_path: &cli.config,
        output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet,
        allow_remote_extends: cli.allow_remote_extends,
        mode: args.mode,
        near: args.near,
        min_tokens: args.min_tokens,
        min_lines: args.min_lines,
        min_occurrences: args.min_occurrences,
        threshold: args.threshold,
        skip_local: args.skip_local,
        cross_language: args.cross_language,
        ignore_imports: resolve_ignore_imports(args.ignore_imports, args.no_ignore_imports),
        top: args.top,
        baseline_path: cli.baseline.as_deref(),
        save_baseline_path: cli.save_baseline.as_deref(),
        production,
        production_override: Some(production),
        trace: args.trace.as_deref(),
        changed_since: cli.changed_since.as_deref(),
        diff_index: None,
        use_shared_diff_index: true,
        changed_files: None,
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        explain: cli.explain,
        explain_skipped: cli.explain_skipped,
        summary: cli.summary,
        group_by: cli.group_by,
        performance: cli.performance,
        include_fragments: !args.no_fragments,
    })
}

struct AuditDispatchArgs {
    production_dead_code: bool,
    production_health: bool,
    production_dupes: bool,
    dead_code_baseline: Option<PathBuf>,
    health_baseline: Option<PathBuf>,
    dupes_baseline: Option<PathBuf>,
    max_crap: Option<f64>,
    coverage: Option<PathBuf>,
    coverage_root: Option<PathBuf>,
    no_css: bool,
    css_deep: bool,
    no_css_deep: bool,
    gate: Option<AuditGateArg>,
    runtime_coverage: Option<PathBuf>,
    min_invocations_hot: u64,
    gate_marker: Option<String>,
    brief: bool,
    max_decisions: usize,
    /// Emit the agent-contract walkthrough guide instead of the brief body.
    walkthrough_guide: bool,
    /// Post-validate an agent's judgment JSON from this path against the
    /// live graph.
    walkthrough_file: Option<PathBuf>,
    /// Render the existing walkthrough guide as a staged human/markdown tour.
    walkthrough: bool,
    /// Changed files to record as VIEWED before rendering the tour.
    mark_viewed: Vec<PathBuf>,
    /// Expand the Cleared panel (de-prioritized + viewed) in the tour.
    show_cleared: bool,
    /// Expand the de-prioritized units in the human focus map.
    show_deprioritized: bool,
}

struct ResolvedAuditInputs {
    audit_cfg: fallow_config::AuditConfig,
    cache_dir: PathBuf,
    production: ProductionModes,
    dead_code_baseline: Option<PathBuf>,
    health_baseline: Option<PathBuf>,
    dupes_baseline: Option<PathBuf>,
    /// Istanbul coverage inputs resolved with the health precedence (flag,
    /// env, then `health.coverage` / `health.coverageRoot`), so the head and
    /// base passes score from the same map the standalone health run uses.
    coverage: Option<PathBuf>,
    coverage_root: Option<PathBuf>,
}

fn dispatch_audit(dispatch: &DispatchContext<'_>, args: &AuditDispatchArgs) -> ExitCode {
    let cli = dispatch.cli;
    let output = dispatch.output;

    if cli.baseline.is_some() || cli.save_baseline.is_some() {
        return emit_error(
            "audit uses per-analysis baselines. Use --dead-code-baseline, --health-baseline, or --dupes-baseline (or save them with `fallow dead-code|health|dupes --save-baseline <file>`)",
            2,
            output,
        );
    }

    let inputs = match resolve_audit_inputs(dispatch, args) {
        Ok(inputs) => inputs,
        Err(code) => return code,
    };

    run_resolved_audit(dispatch, args, &inputs)
}

fn resolve_audit_inputs(
    dispatch: &DispatchContext<'_>,
    args: &AuditDispatchArgs,
) -> Result<ResolvedAuditInputs, ExitCode> {
    let cli = dispatch.cli;
    let root = dispatch.root;
    let output = dispatch.output;
    let config = load_config(
        root,
        &cli.config,
        LoadConfigArgs {
            output,
            no_cache: cli.no_cache,
            threads: dispatch.threads,
            production: cli.production,
            quiet: dispatch.quiet,
            allow_remote_extends: cli.allow_remote_extends,
        },
    )?;
    let cache_dir = config.cache_dir.clone();
    let audit_cfg = config.audit;
    let production = resolve_production_modes(
        cli,
        root,
        output,
        args.production_dead_code,
        args.production_health,
        args.production_dupes,
    )?;
    let resolved_dead_code_baseline = resolve_audit_baseline_path(
        root,
        args.dead_code_baseline.as_deref(),
        audit_cfg.dead_code_baseline.as_deref(),
    );
    let resolved_health_baseline = resolve_audit_baseline_path(
        root,
        args.health_baseline.as_deref(),
        audit_cfg.health_baseline.as_deref(),
    );
    let resolved_dupes_baseline = resolve_audit_baseline_path(
        root,
        args.dupes_baseline.as_deref(),
        audit_cfg.dupes_baseline.as_deref(),
    );
    let coverage_inputs = resolve_coverage_inputs(
        args.coverage.as_deref(),
        args.coverage_root.as_deref(),
        output,
        || Ok(config.health),
    )?;

    Ok(ResolvedAuditInputs {
        audit_cfg,
        cache_dir,
        production,
        dead_code_baseline: resolved_dead_code_baseline,
        health_baseline: resolved_health_baseline,
        dupes_baseline: resolved_dupes_baseline,
        coverage: coverage_inputs.coverage,
        coverage_root: coverage_inputs.coverage_root,
    })
}

fn audit_css_enabled(config: &fallow_config::AuditConfig, args: &AuditDispatchArgs) -> bool {
    !args.no_css && config.css.unwrap_or(true)
}

fn audit_css_deep_enabled(config: &fallow_config::AuditConfig, args: &AuditDispatchArgs) -> bool {
    audit_css_enabled(config, args)
        && !args.no_css_deep
        && (args.css_deep || config.css_deep.unwrap_or(true))
}

fn run_resolved_audit(
    dispatch: &DispatchContext<'_>,
    args: &AuditDispatchArgs,
    inputs: &ResolvedAuditInputs,
) -> ExitCode {
    let cli = dispatch.cli;
    audit::run_audit_with_type_aware(
        &audit::AuditOptions {
            root: dispatch.root,
            config_path: &cli.config,
            cache_dir: &inputs.cache_dir,
            output: dispatch.output,
            json_style: dispatch.json_style,
            no_cache: cli.no_cache,
            threads: dispatch.threads,
            quiet: dispatch.quiet,
            allow_remote_extends: cli.allow_remote_extends,
            changed_since: cli.changed_since.as_deref(),
            production: cli.production,
            production_dead_code: Some(inputs.production.dead_code),
            production_health: Some(inputs.production.health),
            production_dupes: Some(inputs.production.dupes),
            workspace: cli.workspace.as_deref(),
            changed_workspaces: cli.changed_workspaces.as_deref(),
            explain: cli.explain,
            explain_skipped: cli.explain_skipped,
            performance: cli.performance,
            group_by: cli.group_by,
            dead_code_baseline: inputs.dead_code_baseline.as_deref(),
            health_baseline: inputs.health_baseline.as_deref(),
            dupes_baseline: inputs.dupes_baseline.as_deref(),
            health_baseline_mode: cli.baseline_mode.unwrap_or_default().into(),
            max_crap: args.max_crap,
            coverage: inputs.coverage.as_deref(),
            coverage_root: inputs.coverage_root.as_deref(),
            gate: args.gate.map_or(inputs.audit_cfg.gate, Into::into),
            include_entry_exports: cli.include_entry_exports,
            // Styling analytics, including deep cross-file reachability, is on
            // by default in `fallow audit`; both layers remain verdict-neutral
            // unless a user escalates a styling rule to error.
            css: audit_css_enabled(&inputs.audit_cfg, args),
            css_deep: audit_css_deep_enabled(&inputs.audit_cfg, args),
            runtime_coverage: args.runtime_coverage.as_deref(),
            min_invocations_hot: args.min_invocations_hot,
            brief: args.brief,
            max_decisions: args.max_decisions,
            walkthrough_guide: args.walkthrough_guide,
            walkthrough: args.walkthrough,
            mark_viewed: &args.mark_viewed,
            show_cleared: args.show_cleared,
            walkthrough_file: args.walkthrough_file.as_deref(),
            show_deprioritized: args.show_deprioritized,
        },
        args.gate_marker.as_deref(),
        audit::AuditTypeAwareOptions {
            enabled: cli.type_aware_override(),
            config_default: inputs.audit_cfg.type_aware,
            projects: &cli.type_aware_project,
            require: cli.type_aware_require.map(Into::into),
        },
    )
}

/// Dispatch `fallow decision-surface`: the separable apex. Reuses the audit
/// input resolution in brief mode (changed-code scope) with all gating /
/// coverage / baseline knobs defaulted, then renders ONLY the decision surface.
fn dispatch_decision_surface(dispatch: &DispatchContext<'_>, max_decisions: usize) -> ExitCode {
    let args = decision_surface_audit_args(max_decisions);
    let inputs = match resolve_audit_inputs(dispatch, &args) {
        Ok(inputs) => inputs,
        Err(code) => return code,
    };
    audit::run_decision_surface(&decision_surface_audit_options(
        dispatch,
        &inputs,
        max_decisions,
    ))
}

fn decision_surface_audit_args(max_decisions: usize) -> AuditDispatchArgs {
    AuditDispatchArgs {
        production_dead_code: false,
        production_health: false,
        production_dupes: false,
        dead_code_baseline: None,
        health_baseline: None,
        dupes_baseline: None,
        max_crap: None,
        coverage: None,
        coverage_root: None,
        no_css: true,
        css_deep: false,
        no_css_deep: false,
        gate: None,
        runtime_coverage: None,
        min_invocations_hot: 0,
        gate_marker: None,
        brief: true,
        max_decisions,
        walkthrough_guide: false,
        walkthrough_file: None,
        walkthrough: false,
        mark_viewed: Vec::new(),
        show_cleared: false,
        show_deprioritized: false,
    }
}

fn decision_surface_audit_options<'a>(
    dispatch: &'a DispatchContext<'a>,
    inputs: &'a ResolvedAuditInputs,
    max_decisions: usize,
) -> audit::AuditOptions<'a> {
    let cli = dispatch.cli;
    audit::AuditOptions {
        root: dispatch.root,
        config_path: &cli.config,
        cache_dir: &inputs.cache_dir,
        output: dispatch.output,
        json_style: dispatch.json_style,
        no_cache: cli.no_cache,
        threads: dispatch.threads,
        quiet: dispatch.quiet,
        allow_remote_extends: cli.allow_remote_extends,
        changed_since: cli.changed_since.as_deref(),
        production: cli.production,
        production_dead_code: Some(inputs.production.dead_code),
        production_health: Some(inputs.production.health),
        production_dupes: Some(inputs.production.dupes),
        workspace: cli.workspace.as_deref(),
        changed_workspaces: cli.changed_workspaces.as_deref(),
        explain: cli.explain,
        explain_skipped: cli.explain_skipped,
        performance: cli.performance,
        group_by: cli.group_by,
        dead_code_baseline: inputs.dead_code_baseline.as_deref(),
        health_baseline: inputs.health_baseline.as_deref(),
        dupes_baseline: inputs.dupes_baseline.as_deref(),
        health_baseline_mode: cli.baseline_mode.unwrap_or_default().into(),
        max_crap: None,
        coverage: None,
        coverage_root: None,
        gate: inputs.audit_cfg.gate,
        include_entry_exports: cli.include_entry_exports,
        // Decision-surface (brief apex) does not render styling; keep it lean.
        css: false,
        css_deep: false,
        runtime_coverage: None,
        min_invocations_hot: 0,
        brief: true,
        max_decisions,
        walkthrough_guide: false,
        walkthrough: false,
        mark_viewed: &[],
        show_cleared: false,
        walkthrough_file: None,
        show_deprioritized: false,
    }
}

struct HealthDispatchArgs<'a> {
    max_cyclomatic: Option<u16>,
    max_cognitive: Option<u16>,
    max_crap: Option<f64>,
    top: Option<usize>,
    sort: health::SortBy,
    complexity: bool,
    complexity_breakdown: bool,
    file_scores: bool,
    coverage_gaps: bool,
    hotspots: bool,
    ownership: bool,
    ownership_emails: Option<fallow_config::EmailMode>,
    targets: bool,
    type_coupling: bool,
    css: bool,
    effort: Option<EffortFilter>,
    score: bool,
    min_score: Option<f64>,
    min_severity: Option<fallow_output::FindingSeverity>,
    report_only: bool,
    since: Option<&'a str>,
    min_commits: Option<u32>,
    save_snapshot: Option<&'a Option<String>>,
    trend: bool,
    coverage: Option<&'a std::path::Path>,
    coverage_root: Option<&'a std::path::Path>,
    runtime_coverage: Option<&'a std::path::Path>,
    min_invocations_hot: u64,
    min_observation_volume: Option<u32>,
    low_traffic_threshold: Option<f64>,
}

type ResolvedHealthCoverageInputs = fallow_api::CoverageInputs;

/// Resolve Istanbul coverage inputs for `health`, bare combined mode, and
/// `audit` (#2359) with the precedence owned by
/// [`fallow_api::resolve_coverage_inputs`]: the CLI flag, then
/// `FALLOW_COVERAGE` / `FALLOW_COVERAGE_ROOT` (read here, at the CLI
/// boundary), then `health.coverage` / `health.coverageRoot`. Auto-detection
/// of `coverage/coverage-final.json` stays in the engine and only applies when
/// every layer is empty. `config_health` is consulted only when both a flag
/// and an env var are absent for at least one input, so a command that has
/// not loaded config yet can defer that load. A relative winning root is a
/// structured exit 2 before any analysis starts.
fn resolve_coverage_inputs(
    cli_coverage: Option<&std::path::Path>,
    cli_coverage_root: Option<&std::path::Path>,
    output: fallow_config::OutputFormat,
    config_health: impl FnOnce() -> Result<fallow_config::HealthConfig, ExitCode>,
) -> Result<ResolvedHealthCoverageInputs, ExitCode> {
    let explicit = fallow_api::CoverageInputs {
        coverage: cli_coverage.map(std::path::Path::to_path_buf),
        coverage_root: cli_coverage_root.map(std::path::Path::to_path_buf),
    };
    let env = fallow_api::CoverageInputs {
        coverage: path_from_env("FALLOW_COVERAGE"),
        coverage_root: path_from_env("FALLOW_COVERAGE_ROOT"),
    };
    let config_health = if fallow_api::CoverageInputs::needs_config_layer(&explicit, &env) {
        Some(config_health()?)
    } else {
        None
    };

    fallow_api::resolve_coverage_inputs(explicit, env, config_health.as_ref())
        .map_err(|err| emit_error(&err.to_string(), 2, output))
}

/// [`resolve_coverage_inputs`] for commands that load config lazily: the
/// config is read only when a flag and env var are both absent.
fn resolve_health_coverage_inputs(
    dispatch: &DispatchContext<'_>,
    cli_coverage: Option<&std::path::Path>,
    cli_coverage_root: Option<&std::path::Path>,
) -> Result<ResolvedHealthCoverageInputs, ExitCode> {
    resolve_coverage_inputs(cli_coverage, cli_coverage_root, dispatch.output, || {
        Ok(load_config(
            dispatch.root,
            &dispatch.cli.config,
            LoadConfigArgs {
                output: dispatch.output,
                no_cache: dispatch.cli.no_cache,
                threads: dispatch.threads,
                production: dispatch.cli.production,
                quiet: dispatch.quiet,
                allow_remote_extends: dispatch.cli.allow_remote_extends,
            },
        )?
        .health)
    })
}

fn path_from_env(name: &str) -> Option<PathBuf> {
    std::env::var_os(name)
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
}

fn validate_health_report_only_gate(
    report_only: bool,
    min_score: Option<f64>,
    min_severity: Option<fallow_output::FindingSeverity>,
    output: fallow_config::OutputFormat,
) -> Result<(), ExitCode> {
    if report_only && (min_score.is_some() || min_severity.is_some()) {
        return Err(emit_error(
            "--report-only cannot be combined with --min-score or --min-severity. \
             --report-only always exits 0; drop it to gate on score/severity, or \
             drop the gate flags to stay advisory.",
            2,
            output,
        ));
    }

    Ok(())
}

fn resolve_runtime_coverage_options(
    runtime_coverage: Option<&std::path::Path>,
    min_invocations_hot: u64,
    min_observation_volume: Option<u32>,
    low_traffic_threshold: Option<f64>,
    output: fallow_config::OutputFormat,
) -> Result<Option<fallow_engine::health::RuntimeCoverageOptions>, ExitCode> {
    let Some(path) = runtime_coverage else {
        return Ok(None);
    };

    health::coverage::prepare_options(
        path,
        min_invocations_hot,
        min_observation_volume,
        low_traffic_threshold,
        output,
    )
    .map(Some)
}

fn dispatch_health(dispatch: &DispatchContext<'_>, args: &HealthDispatchArgs<'_>) -> ExitCode {
    let cli = dispatch.cli;
    let root = dispatch.root;
    let (output, _quiet, _fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    if let Err(code) = validate_health_report_only_gate(
        args.report_only,
        args.min_score,
        args.min_severity,
        output,
    ) {
        return code;
    }
    let runtime_coverage = match resolve_runtime_coverage_options(
        args.runtime_coverage,
        args.min_invocations_hot,
        args.min_observation_volume,
        args.low_traffic_threshold,
        output,
    ) {
        Ok(options) => options,
        Err(code) => return code,
    };
    let production = match resolve_production_modes(cli, root, output, false, false, false) {
        Ok(modes) => modes.for_analysis(fallow_config::ProductionAnalysis::Health),
        Err(code) => return code,
    };
    let coverage_inputs =
        match resolve_health_coverage_inputs(dispatch, args.coverage, args.coverage_root) {
            Ok(inputs) => inputs,
            Err(code) => return code,
        };
    let run = derive_health_dispatch_run(args, output, &coverage_inputs, runtime_coverage);
    run_health_dispatch(dispatch, args, ResolvedHealthDispatch { run, production })
}

fn derive_health_dispatch_run<'a>(
    args: &'a HealthDispatchArgs<'a>,
    output: fallow_config::OutputFormat,
    coverage_inputs: &'a ResolvedHealthCoverageInputs,
    runtime_coverage: Option<fallow_engine::health::RuntimeCoverageOptions>,
) -> fallow_engine::health::HealthRunOptions<'a> {
    let mut run = fallow_engine::health::derive_health_run_options(
        fallow_engine::health::HealthRunOptionsInput {
            output,
            thresholds: health_threshold_overrides(args),
            top: args.top,
            sort: args.sort.clone().into(),
            complexity: args.complexity,
            file_scores: args.file_scores,
            coverage_gaps: args.coverage_gaps,
            hotspots: args.hotspots,
            ownership: args.ownership,
            ownership_emails: args.ownership_emails,
            targets: args.targets,
            css: args.css,
            effort: args.effort.map(EffortFilter::to_estimate),
            score: args.score,
            gates: health_gate_options(args),
            snapshot_requested: args.save_snapshot.is_some(),
            trend: args.trend,
            since: args.since,
            min_commits: args.min_commits,
            coverage_inputs: health_coverage_inputs(coverage_inputs),
            runtime_coverage,
        },
    );
    if args.type_coupling && !run.sections.any_section {
        run.sections = fallow_engine::health::DerivedHealthSections {
            any_section: true,
            complexity: false,
            file_scores: false,
            coverage_gaps: false,
            hotspots: false,
            targets: false,
            css: false,
            score: false,
            force_full: false,
            score_only_output: false,
        };
    }
    run
}

fn health_threshold_overrides(
    args: &HealthDispatchArgs<'_>,
) -> fallow_engine::health::HealthThresholdOverrides {
    fallow_engine::health::HealthThresholdOverrides {
        max_cyclomatic: args.max_cyclomatic,
        max_cognitive: args.max_cognitive,
        max_crap: args.max_crap,
    }
}

fn health_gate_options(args: &HealthDispatchArgs<'_>) -> fallow_engine::health::HealthGateOptions {
    fallow_engine::health::HealthGateOptions {
        min_score: args.min_score,
        min_severity: args.min_severity,
        report_only: args.report_only,
    }
}

fn health_coverage_inputs(
    coverage_inputs: &ResolvedHealthCoverageInputs,
) -> fallow_engine::health::HealthCoverageInputs<'_> {
    fallow_engine::health::HealthCoverageInputs {
        coverage: coverage_inputs.coverage.as_deref(),
        coverage_root: coverage_inputs.coverage_root.as_deref(),
        coverage_relocated: false,
    }
}

/// Resolved inputs threaded from `dispatch_health` into the `HealthOptions`
/// builder. Owns the normalized engine run contract and resolved production
/// mode.
struct ResolvedHealthDispatch<'a> {
    run: fallow_engine::health::HealthRunOptions<'a>,
    production: bool,
}

/// Build `HealthOptions` from the parsed args plus the resolved dispatch inputs,
/// then run the health analysis.
fn run_health_dispatch(
    dispatch: &DispatchContext<'_>,
    args: &HealthDispatchArgs<'_>,
    resolved: ResolvedHealthDispatch<'_>,
) -> ExitCode {
    let cli = dispatch.cli;
    let (output, quiet, _fail_on_issues) =
        (dispatch.output, dispatch.quiet, dispatch.fail_on_issues);
    let run = resolved.run;
    let sections = run.sections;
    let production = resolved.production;
    health::run_health(
        &HealthOptions {
            root: dispatch.root,
            config_path: &cli.config,
            output,
            no_cache: cli.no_cache,
            threads: dispatch.threads,
            quiet,
            thresholds: run.thresholds,
            top: run.top,
            sort: run.sort,
            production,
            production_override: Some(production),
            allow_remote_extends: cli.allow_remote_extends,
            changed_since: cli.changed_since.as_deref(),
            diff_index: None,
            use_shared_diff_index: true,
            workspace: cli.workspace.as_deref(),
            changed_workspaces: cli.changed_workspaces.as_deref(),
            baseline: cli.baseline.as_deref(),
            save_baseline: cli.save_baseline.as_deref(),
            baseline_mode: cli.baseline_mode.unwrap_or_default().into(),
            baseline_mode_explicit: cli.baseline_mode.is_some(),
            complexity: sections.complexity,
            file_scores: sections.file_scores,
            coverage_gaps: sections.coverage_gaps,
            config_activates_coverage_gaps: !sections.any_section,
            hotspots: sections.hotspots,
            ownership: run.ownership,
            ownership_emails: run.ownership_emails,
            targets: sections.targets,
            css: sections.css,
            css_deep: false,
            force_full: sections.force_full,
            score_only_output: sections.score_only_output,
            enforce_coverage_gap_gate: true,
            effort: run.effort,
            score: sections.score,
            gates: run.gates,
            since: run.since,
            min_commits: run.min_commits,
            explain: cli.explain,
            summary: cli.summary,
            save_snapshot: args
                .save_snapshot
                .map(|opt| PathBuf::from(opt.as_deref().unwrap_or_default())),
            trend: args.trend,
            coverage_inputs: run.coverage_inputs,
            performance: cli.performance,
            runtime_coverage: run.runtime_coverage,
            churn_file: cli.churn_file.as_deref(),
            analysis_identity: fallow_types::semantic::SemanticAnalysisIdentity::default(),
            complexity_breakdown: args.complexity_breakdown,
            group_by: cli.group_by.map(Into::into),
        },
        dispatch.json_style,
        &health::TypeAwareHealthOptions {
            enabled: cli.type_aware_override(),
            requested: args.type_coupling,
            unfiltered: health_type_coupling_is_default_section(args),
            projects: &cli.type_aware_project,
            require: cli.type_aware_require.map(Into::into),
        },
    )
}

fn health_type_coupling_is_default_section(args: &HealthDispatchArgs<'_>) -> bool {
    !args.complexity
        && !args.file_scores
        && !args.coverage_gaps
        && !args.hotspots
        && !args.ownership
        && !args.targets
        && !args.css
        && !args.score
        && args.min_score.is_none()
        && args.min_severity.is_none()
        && args.runtime_coverage.is_none()
}

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

    /// Validates that the CLI definition has no flag name collisions, missing
    /// fields, or other structural errors. Catches issues like a global alias
    /// `--base` colliding with a subcommand's `--base` flag.
    #[test]
    fn cli_definition_has_no_flag_collisions() {
        use clap::CommandFactory;
        Cli::command().debug_assert();
    }

    #[test]
    fn impact_statusline_subcommand_parses() {
        use clap::Parser;

        let cli = Cli::try_parse_from(["fallow", "impact", "statusline"]).expect("argv parses");
        assert!(matches!(
            cli.command,
            Some(Command::Impact {
                subcommand: Some(ImpactCli::Statusline),
                ..
            })
        ));
    }

    #[test]
    fn impact_statusline_bypasses_command_epilogue() {
        use clap::Parser;

        let statusline =
            Cli::try_parse_from(["fallow", "impact", "statusline"]).expect("argv parses");
        assert!(is_impact_statusline(&statusline));

        let status = Cli::try_parse_from(["fallow", "impact", "status"]).expect("argv parses");
        assert!(!is_impact_statusline(&status));

        let all_statusline =
            Cli::try_parse_from(["fallow", "impact", "--all", "statusline"]).expect("argv parses");
        assert!(!is_impact_statusline(&all_statusline));
    }

    #[test]
    fn regression_baseline_help_explains_the_default_destination() {
        use clap::CommandFactory;
        let help = Cli::command().render_long_help().to_string();

        assert!(help.contains("Omit PATH to update regression.baseline"));
        assert!(help.contains("discovered fallow config"));
        assert!(help.contains("create .fallowrc.json when none exists"));
    }

    /// The root `--help` cheat sheet is a static const that cannot call the
    /// shared renderer, so this test is the only guard that it stays in sync
    /// with `TASK_MATRIX`. Every row's command string must appear verbatim.
    #[test]
    fn after_help_lists_every_task_matrix_command() {
        for row in crate::task_matrix::TASK_MATRIX {
            assert!(
                TOP_LEVEL_AFTER_LONG_HELP.contains(row.command),
                "root --help cheat sheet is missing task-matrix command '{}'; \
                 update the top_level_task_cheat_sheet! fragment to match TASK_MATRIX",
                row.command
            );
        }
    }

    /// The curated command groups replace clap's auto-generated subcommand
    /// list, so a new subcommand stays invisible in `fallow --help` unless it
    /// is added here. Substring matching is not enough (e.g. `--trace`
    /// contains `trace`), so each name must lead a group line. The full
    /// `--help` surface is the one that must stay complete; `-h` is the
    /// curated progressive subset.
    #[test]
    fn after_help_lists_every_visible_subcommand() {
        use clap::CommandFactory;

        for sub in Cli::command().get_subcommands() {
            if sub.is_hide_set() {
                continue;
            }
            let name = sub.get_name();
            let listed = TOP_LEVEL_AFTER_LONG_HELP
                .lines()
                .any(|line| line.split_whitespace().next() == Some(name));
            assert!(
                listed,
                "root --help command list is missing subcommand '{name}'; \
                 add it to a top_level_*_command_groups! section"
            );
        }
    }

    /// `-h` is the progressive entry point: it must stay scannable (ecosystem
    /// norm is 40-80 lines) while leading with the task cheat sheet and
    /// closing with the pointer to the complete `--help` surface.
    #[test]
    fn short_help_stays_scannable_with_cheat_sheet_and_pointer() {
        use clap::CommandFactory;

        let help = Cli::command().render_help().to_string();
        let lines = help.lines().count();
        assert!(
            lines < 90,
            "root -h grew to {lines} lines; keep the short surface under 90 \
             (curate hide_short_help and the short after-help instead)"
        );
        assert!(help.contains("When the agent is about to..."));
        assert!(help.contains("Run fallow --help for the complete command list."));
    }

    /// The high-value and coarse admin commands each get a distinct telemetry
    /// workflow instead of the `Unknown` catch-all, so command families stay
    /// answerable without uploading raw command lines.
    #[test]
    fn high_value_commands_route_to_distinct_workflows() {
        use clap::Parser;
        use fallow_config::OutputFormat;

        let distinct = [
            (vec!["fallow", "impact"], telemetry::Workflow::Impact),
            (vec!["fallow", "security"], telemetry::Workflow::Security),
            (vec!["fallow", "fix"], telemetry::Workflow::Fix),
            (
                vec!["fallow", "explain", "unused-exports"],
                telemetry::Workflow::Explain,
            ),
            (
                vec!["fallow", "watch"],
                telemetry::Workflow::CodeQualityReview,
            ),
            (
                vec!["fallow", "list"],
                telemetry::Workflow::ProjectInventory,
            ),
            (
                vec!["fallow", "workspaces"],
                telemetry::Workflow::ProjectInventory,
            ),
            (
                vec!["fallow", "schema"],
                telemetry::Workflow::ProjectInventory,
            ),
            (vec!["fallow", "init"], telemetry::Workflow::Setup),
            (
                vec!["fallow", "hooks", "install", "--target", "git"],
                telemetry::Workflow::Setup,
            ),
            (vec!["fallow", "config-schema"], telemetry::Workflow::Setup),
            (vec!["fallow", "plugin-schema"], telemetry::Workflow::Setup),
            (
                vec!["fallow", "rule-pack-schema"],
                telemetry::Workflow::Setup,
            ),
            (vec!["fallow", "config"], telemetry::Workflow::Setup),
            (
                vec!["fallow", "ci-template", "gitlab"],
                telemetry::Workflow::Setup,
            ),
            (vec!["fallow", "migrate"], telemetry::Workflow::Setup),
            (
                vec!["fallow", "telemetry", "status"],
                telemetry::Workflow::Setup,
            ),
            (vec!["fallow", "setup-hooks"], telemetry::Workflow::Setup),
            (
                vec!["fallow", "audit-cache", "remove", "--root", "."],
                telemetry::Workflow::Setup,
            ),
            (
                vec!["fallow", "license", "status"],
                telemetry::Workflow::License,
            ),
        ];
        for (argv, expected) in distinct {
            let cli = Cli::try_parse_from(&argv).expect("argv parses");
            assert_eq!(
                telemetry_workflow_for_command(cli.command.as_ref(), OutputFormat::Json),
                expected,
                "{argv:?} should map to {expected:?}"
            );
        }
    }

    /// `-v`, `-V`, and `--version` must all trigger clap's Version action so
    /// the version prints regardless of which spelling the user reaches for
    /// (issue #916). clap surfaces a Version action from `try_get_matches_from`
    /// as the `DisplayVersion` error kind.
    #[test]
    fn version_flag_accepts_lower_v_upper_v_and_long() {
        use clap::CommandFactory;
        for argv in [["fallow", "-v"], ["fallow", "-V"], ["fallow", "--version"]] {
            let err = Cli::command()
                .try_get_matches_from(argv)
                .expect_err("version flag should short-circuit parsing");
            assert_eq!(
                err.kind(),
                clap::error::ErrorKind::DisplayVersion,
                "{argv:?} should trigger the Version action"
            );
        }
    }

    /// Guard against deferred-work wording leaking into clap-rendered help.
    /// `stub`, `placeholder`, and `not yet` framings tell users the feature
    /// is broken or pending; they belong in tracked issues, not in `--help`.
    /// Walk every (sub)command and assert each rendered long-help is clean.
    #[test]
    fn cli_help_text_contains_no_implementation_status_wording() {
        use clap::CommandFactory;
        let mut root = Cli::command();
        let mut violations: Vec<(String, String)> = Vec::new();
        visit_help(&mut root, "fallow", &mut violations);
        assert!(
            violations.is_empty(),
            "found implementation-status wording in --help output:\n{}",
            violations
                .iter()
                .map(|(cmd, line)| format!("  {cmd}: {line}"))
                .collect::<Vec<_>>()
                .join("\n")
        );
    }

    #[test]
    fn dependency_override_help_is_package_manager_neutral() {
        use clap::CommandFactory;
        let help = Cli::command()
            .find_subcommand_mut("dead-code")
            .expect("dead-code command")
            .render_long_help()
            .to_string();

        assert!(help.contains("Only report unused package-manager dependency overrides"));
        assert!(help.contains("Only report misconfigured package-manager dependency overrides"));
        assert!(!help.contains("unused pnpm dependency overrides"));
        assert!(!help.contains("misconfigured pnpm dependency overrides"));
    }

    #[test]
    fn top_level_help_groups_commands_by_workflow() {
        use clap::CommandFactory;
        let help = Cli::command().render_long_help().to_string();
        let expected_order = [
            "Analysis:",
            "  dead-code",
            "  dupes",
            "  health",
            "  flags",
            "  security",
            "  audit",
            "Workflow:",
            "  watch",
            "  fix",
            "Project inspection:",
            "  list",
            "  workspaces",
            "  explain",
            "  impact",
            "  viz",
            "Setup and configuration:",
            "  init",
            "  recommend",
            "  migrate",
            "  config",
            "  config-schema",
            "  plugin-schema",
            "  plugin-check",
            "  rule-pack-schema",
            "Automation and CI:",
            "  ci",
            "  ci-template",
            "  hooks",
            "  setup-hooks",
            "Runtime coverage:",
            "  coverage",
            "  license",
            "Reference:",
            "  schema",
            "  help",
            "Options:",
        ];
        let mut cursor = 0;
        for needle in expected_order {
            let Some(offset) = help[cursor..].find(needle) else {
                panic!("top-level help missing `{needle}` after byte {cursor}:\n{help}");
            };
            cursor += offset + needle.len();
        }
    }

    #[test]
    fn security_help_hides_globals_rejected_by_security_validator() {
        let help = render_security_help(SecurityHelpTarget::Parent);

        for long in SECURITY_UNSUPPORTED_GLOBAL_LONGS {
            assert!(
                !help_contains_long_flag(&help, long),
                "security help must hide unsupported --{long}:\n{help}"
            );
        }

        for long in [
            "root",
            "config",
            "format",
            "quiet",
            "no-cache",
            "threads",
            "changed-since",
            "diff-file",
            "diff-stdin",
            "workspace",
            "changed-workspaces",
            "ci",
            "fail-on-issues",
            "sarif-file",
            "summary",
            "output-file",
            "max-file-size",
            "explain",
            "surface",
        ] {
            assert!(
                help_contains_long_flag(&help, long),
                "security help must keep supported --{long}:\n{help}"
            );
        }
    }

    #[test]
    fn security_help_detection_covers_subcommand_and_help_alias_forms() {
        assert_eq!(
            security_help_target(["security", "--help"]),
            Some(SecurityHelpTarget::Parent)
        );
        assert_eq!(
            security_help_target(["security", "-h"]),
            Some(SecurityHelpTarget::Parent)
        );
        assert_eq!(
            security_help_target(["--format", "json", "security", "--help"]),
            Some(SecurityHelpTarget::Parent)
        );
        assert_eq!(
            security_help_target(["help", "security"]),
            Some(SecurityHelpTarget::Parent)
        );
        assert_eq!(
            security_help_target(["security", "survivors", "--help"]),
            Some(SecurityHelpTarget::Survivors)
        );
        assert_eq!(
            security_help_target(["security", "survivors", "-h"]),
            Some(SecurityHelpTarget::Survivors)
        );
        assert_eq!(
            security_help_target(["help", "security", "survivors"]),
            Some(SecurityHelpTarget::Survivors)
        );
        assert_eq!(
            security_help_target(["security", "blind-spots", "--help"]),
            Some(SecurityHelpTarget::BlindSpots)
        );
        assert_eq!(
            security_help_target(["help", "security", "blind-spots"]),
            Some(SecurityHelpTarget::BlindSpots)
        );
        assert_eq!(security_help_target(["health", "--help"]), None);
        assert_eq!(security_help_target(["help", "health"]), None);
    }

    #[test]
    fn security_unsupported_global_validator_matches_hidden_help_contract() {
        for (argv, expected) in [
            (vec!["fallow", "security", "--performance"], "--performance"),
            (
                vec!["fallow", "security", "--baseline", "base.json"],
                "--baseline",
            ),
            (
                vec!["fallow", "security", "--dupes-mode", "weak"],
                "--dupes-mode",
            ),
        ] {
            let cli = Cli::try_parse_from(argv).expect("security global parses before validation");
            assert_eq!(unsupported_security_global(&cli), Some(expected));
        }

        let explain = Cli::try_parse_from(["fallow", "security", "--explain"])
            .expect("security --explain parses");
        assert_eq!(unsupported_security_global(&explain), None);
    }

    #[test]
    fn programmatic_common_options_track_analysis_affecting_cli_globals() {
        use clap::CommandFactory;

        let cli_flags: std::collections::BTreeSet<String> = Cli::command()
            .get_arguments()
            .filter(|arg| arg.is_global_set())
            .filter_map(|arg| arg.get_long().map(str::to_owned))
            .filter(|name| {
                matches!(
                    name.as_str(),
                    "root"
                        | "config"
                        | "allow-remote-extends"
                        | "no-cache"
                        | "threads"
                        | "changed-since"
                        | "diff-file"
                        | "production"
                        | "workspace"
                        | "changed-workspaces"
                        | "explain"
                )
            })
            .collect();
        let programmatic_flags: std::collections::BTreeSet<String> =
            fallow_api::COMMON_ANALYSIS_OPTION_FLAGS
                .iter()
                .map(|flag| (*flag).to_owned())
                .collect();

        assert_eq!(programmatic_flags, cli_flags);
    }

    #[test]
    fn dead_code_registry_filter_flags_are_exposed_by_clap() {
        use clap::CommandFactory;

        let cli = Cli::command();
        let dead_code = cli
            .get_subcommands()
            .find(|command| command.get_name() == "dead-code")
            .expect("dead-code subcommand is registered");
        let cli_flags: std::collections::BTreeSet<String> = dead_code
            .get_arguments()
            .filter_map(|arg| arg.get_long().map(|long| format!("--{long}")))
            .collect();

        for flag in fallow_types::issue_meta::DEAD_CODE_FILTER_FLAGS.iter() {
            assert!(
                cli_flags.contains(*flag),
                "registry filter flag {flag} is missing from dead-code clap args"
            );
        }
    }

    fn help_contains_long_flag(help: &str, long: &str) -> bool {
        let flag = format!("--{long}");
        help.split(|c: char| c.is_whitespace() || c == ',' || c == '[' || c == ']')
            .any(|token| token == flag)
    }

    fn visit_help(cmd: &mut clap::Command, path: &str, violations: &mut Vec<(String, String)>) {
        let help = cmd.render_long_help().to_string();
        for line in scan_forbidden(&help) {
            violations.push((path.to_owned(), line));
        }
        let names: Vec<String> = cmd
            .get_subcommands()
            .map(|sub| sub.get_name().to_owned())
            .collect();
        for name in names {
            if name == "help" {
                continue;
            }
            if let Some(sub) = cmd.find_subcommand_mut(&name) {
                let sub_path = format!("{path} {name}");
                visit_help(sub, &sub_path, violations);
            }
        }
    }

    fn scan_forbidden(s: &str) -> Vec<String> {
        let lower = s.to_ascii_lowercase();
        let mut out = Vec::new();
        for word in ["stub", "placeholder"] {
            if let Some(idx) = find_whole_word(&lower, word) {
                out.push(extract_line(s, idx));
            }
        }
        if let Some(idx) = lower.find("not yet") {
            out.push(extract_line(s, idx));
        }
        out
    }

    fn find_whole_word(haystack: &str, word: &str) -> Option<usize> {
        let bytes = haystack.as_bytes();
        let mut start = 0;
        while let Some(rel) = haystack[start..].find(word) {
            let abs = start + rel;
            let before_ok = abs == 0 || !bytes[abs - 1].is_ascii_alphanumeric();
            let after_idx = abs + word.len();
            let after_ok = after_idx >= bytes.len() || !bytes[after_idx].is_ascii_alphanumeric();
            if before_ok && after_ok {
                return Some(abs);
            }
            start = abs + word.len();
        }
        None
    }

    fn extract_line(s: &str, byte_idx: usize) -> String {
        let line_start = s[..byte_idx].rfind('\n').map_or(0, |i| i + 1);
        let line_end = s[byte_idx..].find('\n').map_or(s.len(), |i| byte_idx + i);
        s[line_start..line_end].trim().to_owned()
    }

    #[test]
    fn emit_error_returns_given_exit_code() {
        let code = emit_error("test error", 2, fallow_config::OutputFormat::Human);
        assert_eq!(code, ExitCode::from(2));
    }

    fn telemetry_run_for_mode(mode: telemetry::AnalysisMode) -> TelemetryRun {
        TelemetryRun {
            workflow: telemetry::Workflow::Health,
            output: fallow_config::OutputFormat::Json,
            quiet: true,
            start: std::time::Instant::now(),
            context: telemetry::WorkflowContext {
                run_scope: telemetry::RunScope::FullProject,
                config_shape: telemetry::ConfigShape::Default,
                output_destination: telemetry::OutputDestination::Stdout,
                analysis_mode: mode,
            },
        }
    }

    #[test]
    fn fallback_failure_reason_skips_success_and_findings() {
        let run = telemetry_run_for_mode(telemetry::AnalysisMode::Static);

        assert_eq!(fallback_failure_reason_for(&run, ExitCode::SUCCESS), None);
        assert_eq!(fallback_failure_reason_for(&run, ExitCode::from(1)), None);
    }

    #[test]
    fn fallback_failure_reason_classifies_network_auth_and_analysis() {
        let static_run = telemetry_run_for_mode(telemetry::AnalysisMode::Static);
        let cloud_run = telemetry_run_for_mode(telemetry::AnalysisMode::ProductionCoverage);

        assert_eq!(
            fallback_failure_reason_for(&static_run, ExitCode::from(api::NETWORK_EXIT_CODE)),
            Some(telemetry::FailureReason::Network),
        );
        assert_eq!(
            fallback_failure_reason_for(&static_run, ExitCode::from(12)),
            Some(telemetry::FailureReason::Auth),
        );
        assert_eq!(
            fallback_failure_reason_for(&cloud_run, ExitCode::from(3)),
            Some(telemetry::FailureReason::Auth),
        );
        assert_eq!(
            fallback_failure_reason_for(&static_run, ExitCode::from(2)),
            Some(telemetry::FailureReason::Analysis),
        );
    }

    #[test]
    fn bare_coverage_flags_parse_without_subcommand() {
        let cli = Cli::try_parse_from([
            "fallow",
            "--coverage",
            "coverage/coverage-final.json",
            "--coverage-root",
            "/ci/workspace",
        ])
        .expect("bare combined coverage flags should parse");
        assert!(cli.command.is_none());
        assert_eq!(
            cli.coverage.as_deref(),
            Some(std::path::Path::new("coverage/coverage-final.json"))
        );
        assert_eq!(
            cli.coverage_root.as_deref(),
            Some(std::path::Path::new("/ci/workspace"))
        );
    }

    #[test]
    fn bare_coverage_before_subcommand_is_detectable() {
        let cli = Cli::try_parse_from([
            "fallow",
            "--coverage",
            "coverage/coverage-final.json",
            "dead-code",
        ])
        .expect("clap should parse pre-subcommand bare coverage for custom rejection");
        assert!(cli.command.is_some());
        assert!(cli_has_bare_coverage_input(&cli));
        let message = bare_coverage_subcommand_error_message();
        assert!(message.contains("bare combined-mode flags"));
        assert!(message.contains("fallow health --coverage <coverage-final.json>"));
    }

    #[test]
    fn subcommand_coverage_flag_keeps_regular_clap_error() {
        let Err(err) = Cli::try_parse_from(["fallow", "dead-code", "--coverage"]) else {
            panic!("dead-code --coverage should fail to parse");
        };
        assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument);
    }

    #[test]
    fn type_aware_flags_parse_for_semantic_analysis() {
        let cli = Cli::try_parse_from([
            "fallow",
            "dead-code",
            "--unused-class-members",
            "--type-aware",
            "--type-aware-project",
            "tsconfig.json",
            "--type-aware-project",
            "packages/web/tsconfig.json",
        ])
        .expect("type-aware flag should parse");
        assert!(cli.type_aware);
        assert_eq!(
            cli.type_aware_project,
            [
                PathBuf::from("tsconfig.json"),
                PathBuf::from("packages/web/tsconfig.json")
            ]
        );
        let Some(Command::Check {
            unused_class_members,
            ..
        }) = cli.command
        else {
            panic!("dead-code should parse as the check command");
        };
        assert!(unused_class_members);
    }

    #[test]
    fn no_type_aware_conflicts_with_type_aware() {
        let Err(err) = Cli::try_parse_from(["fallow", "audit", "--type-aware", "--no-type-aware"])
        else {
            panic!("--no-type-aware must conflict with --type-aware");
        };
        assert_eq!(err.kind(), clap::error::ErrorKind::ArgumentConflict);
    }

    #[test]
    fn no_type_aware_forces_semantic_analysis_off() {
        let cli = Cli::try_parse_from(["fallow", "audit", "--no-type-aware"])
            .expect("--no-type-aware should parse on audit");
        assert_eq!(cli.type_aware_override(), Some(false));

        let cli = Cli::try_parse_from(["fallow", "dead-code", "--type-aware"])
            .expect("--type-aware should parse");
        assert_eq!(cli.type_aware_override(), Some(true));

        let cli = Cli::try_parse_from(["fallow", "dead-code"]).expect("bare command should parse");
        assert_eq!(cli.type_aware_override(), None);
    }

    #[test]
    fn type_aware_status_output_hides_host_paths() {
        let root = Path::new("/private/work/project");
        let output = type_aware_status_output(
            root,
            fallow_api::TypeAwareStatus {
                available: false,
                discovery_source: Some("environment-override"),
                companion_path: Some(PathBuf::from("/private/tools/fallow-type-aware")),
                package_version: None,
                protocol_version: 7,
                backend_family: None,
                backend_version: None,
                remediation: Some(
                    "failed to launch /private/tools/fallow-type-aware from /private/work/project"
                        .to_string(),
                ),
            },
        );

        assert_eq!(
            output.schema_version.0,
            fallow_output::TYPE_AWARE_STATUS_SCHEMA_VERSION
        );
        assert_eq!(output.companion_path.as_deref(), Some("fallow-type-aware"));
        let remediation = output.remediation.expect("remediation");
        assert!(!remediation.contains("/private/"));
        assert!(remediation.contains("fallow-type-aware"));
    }

    #[test]
    fn format_parsing_covers_all_variants() {
        assert!(matches!(parse_format_arg("json"), Some(Format::Json)));
        assert!(matches!(parse_format_arg("JSON"), Some(Format::Json)));
        assert!(matches!(parse_format_arg("human"), Some(Format::Human)));
        assert!(matches!(parse_format_arg("sarif"), Some(Format::Sarif)));
        assert!(matches!(parse_format_arg("compact"), Some(Format::Compact)));
        assert!(matches!(
            parse_format_arg("markdown"),
            Some(Format::Markdown)
        ));
        assert!(matches!(parse_format_arg("md"), Some(Format::Markdown)));
        assert!(matches!(
            parse_format_arg("codeclimate"),
            Some(Format::CodeClimate)
        ));
        assert!(matches!(
            parse_format_arg("gitlab-codequality"),
            Some(Format::CodeClimate)
        ));
        assert!(matches!(
            parse_format_arg("gitlab-code-quality"),
            Some(Format::CodeClimate)
        ));
        assert!(matches!(
            parse_format_arg("pr-comment-github"),
            Some(Format::PrCommentGithub)
        ));
        assert!(matches!(
            parse_format_arg("pr-comment-gitlab"),
            Some(Format::PrCommentGitlab)
        ));
        assert!(matches!(
            parse_format_arg("review-github"),
            Some(Format::ReviewGithub)
        ));
        assert!(matches!(
            parse_format_arg("review-gitlab"),
            Some(Format::ReviewGitlab)
        ));
        assert!(matches!(parse_format_arg("badge"), Some(Format::Badge)));
        assert!(parse_format_arg("xml").is_none());
        assert!(parse_format_arg("").is_none());
    }

    #[test]
    fn quiet_parsing_logic() {
        let parse = |s: &str| -> bool { s == "1" || s.eq_ignore_ascii_case("true") };
        assert!(parse("1"));
        assert!(parse("true"));
        assert!(parse("TRUE"));
        assert!(parse("True"));
        assert!(!parse("0"));
        assert!(!parse("false"));
        assert!(!parse("yes"));
    }

    #[test]
    fn tracing_filter_defaults_to_warn_without_env() {
        assert_eq!(build_tracing_filter(None).to_string(), "warn");
    }

    #[test]
    fn tracing_filter_respects_explicit_env_directives() {
        assert_eq!(build_tracing_filter(Some("info")).to_string(), "info");
    }

    #[test]
    fn tracing_filter_treats_empty_env_as_off() {
        assert_eq!(build_tracing_filter(Some("")).to_string(), "off");
        assert_eq!(build_tracing_filter(Some("   ")).to_string(), "off");
    }
}