fallow_output/

check.rs

use std::collections::BTreeMap;
use std::path::Path;
use std::time::Duration;

use fallow_types::envelope::{
    BaselineDeltas, BaselineMatch, CheckSummary, ElapsedMs, EntryPoints, Meta, RegressionResult,
    SchemaVersion, ToolVersion,
};
use fallow_types::output::{IssueAction, NextStep};
use fallow_types::output_health::{HealthFindingAction, HealthFindingActionType};
use fallow_types::results::AnalysisResults;
use fallow_types::workspace::WorkspaceDiagnostic;
use serde::Serialize;

use crate::HealthReport;
use crate::root_envelopes::{attach_telemetry_meta, serialize_named_json_output};

/// Current schema version for the dead-code/check JSON envelope.
pub const CHECK_SCHEMA_VERSION: u32 = 10;

/// Schema projection for the dead-code envelope's exact version.
#[cfg(feature = "schema")]
#[allow(dead_code, reason = "schema-only type used by the field projection")]
#[derive(schemars::JsonSchema)]
#[schemars(extend("const" = CHECK_SCHEMA_VERSION))]
struct CheckSchemaVersion(u32);

/// Current schema version for the `fallow architecture` JSON envelope.
///
/// The architecture body is the dead-code body, so a change to that shared
/// body bumps this version and [`CHECK_SCHEMA_VERSION`] together.
pub const ARCHITECTURE_SCHEMA_VERSION: u32 = 1;

/// Schema projection for the architecture envelope's exact version.
///
/// The schema emitter registers this type by name and points the
/// `ArchitectureOutput` and `ArchitectureGroupedOutput` definitions at it.
#[cfg(feature = "schema")]
#[allow(dead_code, reason = "schema-only type used by the field projection")]
#[derive(schemars::JsonSchema)]
#[schemars(extend("const" = ARCHITECTURE_SCHEMA_VERSION))]
pub struct ArchitectureSchemaVersion(u32);

/// The commands that share the dead-code JSON body.
///
/// `fallow dead-code` and `fallow architecture` serialize the same
/// [`CheckOutput`] and [`CheckGroupedOutput`] structs. Only the root `kind`
/// and `schema_version` are different. A closed enum keeps an unknown kind
/// string off the wire.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CheckEnvelope {
    /// `fallow dead-code`, and every embedded `check` section.
    #[default]
    DeadCode,
    /// `fallow architecture`.
    Architecture,
}

impl CheckEnvelope {
    /// The root `kind` of the flat envelope.
    #[must_use]
    pub const fn kind(self) -> &'static str {
        match self {
            Self::DeadCode => "dead-code",
            Self::Architecture => "architecture",
        }
    }

    /// The root `kind` of the `--group-by` envelope.
    #[must_use]
    pub const fn grouped_kind(self) -> &'static str {
        match self {
            Self::DeadCode => "dead-code-grouped",
            Self::Architecture => "architecture-grouped",
        }
    }

    /// The `schema_version` that the envelope reports.
    #[must_use]
    pub const fn schema_version(self) -> u32 {
        match self {
            Self::DeadCode => CHECK_SCHEMA_VERSION,
            Self::Architecture => ARCHITECTURE_SCHEMA_VERSION,
        }
    }

    /// The subcommand that writes the envelope.
    #[must_use]
    pub const fn command(self) -> &'static str {
        match self {
            Self::DeadCode => "dead-code",
            Self::Architecture => "architecture",
        }
    }
}

#[expect(
    clippy::trivially_copy_pass_by_ref,
    reason = "serde `skip_serializing_if` passes the field by reference"
)]
const fn is_zero(count: &usize) -> bool {
    *count == 0
}

/// Envelope emitted by `fallow dead-code --format json` (plus the `check`
/// block inside the combined and audit envelopes).
///
/// The body is the full `AnalysisResults` flattened into the envelope so
/// every issue array (`unused_files`, `unused_exports`, ...) lives at the
/// top level, matching the existing wire shape. `entry_points` lifts the
/// otherwise `#[serde(skip)]`'d `AnalysisResults::entry_point_summary` back
/// into the JSON output. `summary` carries the per-category counts the
/// JSON layer always emits.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schema", schemars(title = "fallow dead-code --format json"))]
pub struct CheckOutput {
    /// Dead-code output schema version; currently [`CHECK_SCHEMA_VERSION`].
    #[cfg_attr(feature = "schema", schemars(with = "CheckSchemaVersion"))]
    pub schema_version: SchemaVersion,
    /// Fallow CLI version that produced this output.
    pub version: ToolVersion,
    /// Wall-clock analysis duration in milliseconds.
    pub elapsed_ms: ElapsedMs,
    /// Total findings across all issue arrays; excludes `next_steps`.
    pub total_issues: usize,
    /// Entry-point totals per source, when the analysis recorded them.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub entry_points: Option<EntryPoints>,
    /// Per-category finding counts.
    pub summary: CheckSummary,
    /// Full analysis results, flattened so each issue array sits at the
    /// envelope root.
    #[serde(flatten)]
    pub results: AnalysisResults,
    /// Count deltas against the matched baseline, in baseline runs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub baseline_deltas: Option<BaselineDeltas>,
    /// Which baseline snapshot was matched, in baseline runs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub baseline: Option<BaselineMatch>,
    /// This run's view of the loaded baseline, present only in baseline runs.
    /// Carries the staleness counts, the advisory verdict and `gate_trips`, the
    /// same boolean `--fail-on-stale-baseline` exits on, so a CI integration
    /// reads one field instead of restating the rule. Read `change_scoped`
    /// before dividing `matched_entries` by `baseline_entries`: a narrowed run
    /// can report `matched_entries: 0` on a healthy baseline.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub baseline_staleness: Option<crate::BaselineStaleness>,
    /// The answer to `--finding-id`, present only when the run received one
    /// or more `--finding-id` values. The report then holds only the
    /// requested findings. Read `missing` as resolved only when `conclusive`
    /// is true; a scope, a baseline or a filter can hide a finding that still
    /// exists. See [`crate::FindingIdQuery`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub finding_id_query: Option<crate::FindingIdQuery>,
    /// Regression verdict against the baseline, in `--fail-on-regression` runs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub regression: Option<RegressionResult>,
    /// The verdict of every gate this run evaluated, keyed by name. The CLI
    /// always emits it, with the command's default exit rule in it also when
    /// no flag armed a gate, so a CI integration reads the verdict instead of
    /// guessing from a process status it usually cannot see. A gate fails the
    /// build when `status` is `fail` AND `enforced` is true. The typed
    /// programmatic API runs no CLI gate and leaves it absent. See
    /// [`crate::GateOutcomes`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub gate_outcomes: Option<crate::GateOutcomes>,
    /// Every narrowing or shaping request this run RECEIVED, keyed by name,
    /// absent when it was asked for nothing. An entry whose `status` is not
    /// `applied` means the run could not do what it was asked and reported
    /// something WIDER instead, so what follows is a valid report of a scope
    /// nobody requested. Honoured requests are published too, with
    /// `status: "applied"`, so an absent object means "nothing was asked for",
    /// never "nothing failed". See [`crate::RequestOutcomes`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_outcomes: Option<crate::RequestOutcomes>,
    /// Applied Git refs for exact workspace packages. Absent when no package
    /// baselines were selected, including runs with a global changed-since ref.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub package_baselines: Vec<crate::PackageBaselineStatus>,
    /// `_meta` block with docs and rule definitions, when `--explain` was
    /// passed.
    #[serde(rename = "_meta", default, skip_serializing_if = "Option::is_none")]
    pub meta: Option<Meta>,
    /// Non-fatal diagnostics about the project itself, from all three stages
    /// that record them (issue #473):
    ///
    /// - workspace discovery, at config load: `undeclared-workspace`,
    ///   `malformed-package-json`, `glob-matched-no-package-json`,
    ///   `workspace-glob-outside-root`, `workspace-pattern-dir-missing`,
    ///   `nested-project-root`, `malformed-tsconfig`,
    ///   `tsconfig-reference-dir-missing`;
    /// - source discovery, during the file walk: `skipped-large-file`,
    ///   `skipped-minified-file`, `skipped-source-dotdir`,
    ///   `excluded-by-default-ignore`, `source-read-failure`,
    ///   `source-parse-degraded`, `source-nesting-too-deep`;
    /// - dead-code analysis, from the dependency-catalog and override
    ///   detectors: `malformed-pnpm-workspace-yaml`,
    ///   `bun-lockb-override-resolution-skipped`;
    /// - framework plugins, while they read their own build configs:
    ///   `plugin-config-unreadable`, `plugin-effect-not-modeled`;
    /// - the dead-code result, for config patterns that matched nothing:
    ///   `ignore-dependencies-glob-unmatched`,
    ///   `ignore-findings-pattern-unmatched`.
    ///
    /// Analysis-stage and plugin-stage kinds therefore reach only the envelopes
    /// whose run includes a dead-code analyze pass, never a standalone
    /// `fallow dupes --format json`. `path` is project-root-relative with
    /// forward slashes; the array is omitted when empty. The same list is
    /// repeated on each top-level command's envelope so single-command
    /// consumers see it without having to look at a separate top-level field.
    ///
    /// A diagnostic here is advisory and never withholds a finding. Where an
    /// entry reports a source file this run never fully analyzed
    /// (`source-parse-degraded`, `source-nesting-too-deep`,
    /// `source-read-failure`, `skipped-large-file`, `skipped-minified-file`,
    /// `skipped-source-dotdir`) it can distort a verdict, so the affected
    /// `unused_files[]`, `unused_exports[]`, and dependency entries
    /// additionally carry the caveat themselves in their own
    /// optional `reachability_caveats[]` array, and a reader who never scrolls
    /// back up to this list still sees it. `fallow fix` reads the same array
    /// and withholds the removal while a caveat stands.
    ///
    /// `excluded-by-default-ignore` is the one source-discovery kind that
    /// reports unseen files WITHOUT raising a caveat. It names a built-in
    /// ignore pattern (`**/dist/**`, `**/build/**`, `**/coverage/**`, or one
    /// of the four minified-bundle globs) that removed candidate source files
    /// from the walk, which is designed behavior on generated output rather
    /// than a degraded run, so it is advisory only and no finding inherits it.
    /// One entry per pattern, never per file, so the array stays bounded on a
    /// project of any size. Gitignored trees are pruned before the walk sees
    /// them and count zero, and `**/node_modules/**` is never reported:
    /// installed dependencies are not the first-party source the kind is
    /// about.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Read-only follow-up commands computed from this run's findings, emitted
    /// at the JSON root so an agent acting on the output is pointed at fallow's
    /// adjacent verification capabilities (trace, complexity breakdown, audit,
    /// workspace scoping). Each command is runnable as-is and never mutating;
    /// see [`NextStep`] for both contracts. Omitted when empty or when
    /// `FALLOW_SUGGESTIONS=off`; does NOT contribute to `total_issues`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub next_steps: Vec<NextStep>,
}

/// Envelope emitted by `fallow dead-code --group-by ... --format json`.
///
/// Issues are partitioned into resolver buckets (CODEOWNERS team, directory
/// prefix, workspace package, or GitLab CODEOWNERS section) instead of flat
/// arrays. Each bucket carries the same issue-array shape as the ungrouped
/// `CheckOutput` body, plus per-group `key` / `owners` / `total_issues`.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[cfg_attr(
    feature = "schema",
    schemars(
        title = "fallow dead-code --group-by <owner|directory|package|section> --format json"
    )
)]
pub struct CheckGroupedOutput {
    /// Dead-code output schema version; currently [`CHECK_SCHEMA_VERSION`].
    #[cfg_attr(feature = "schema", schemars(with = "CheckSchemaVersion"))]
    pub schema_version: SchemaVersion,
    /// Fallow CLI version that produced this output.
    pub version: ToolVersion,
    /// Wall-clock analysis duration in milliseconds.
    pub elapsed_ms: ElapsedMs,
    /// Resolver the issues were grouped by.
    pub grouped_by: GroupByMode,
    /// Total findings across all groups.
    pub total_issues: usize,
    /// One bucket per resolver key.
    pub groups: Vec<CheckGroupedEntry>,
    /// `true` when the `unused-load-data-key` detector abstained for the whole
    /// project. The abstain has no file, so it is on the root and not in a
    /// group. An empty `unused_load_data_keys` with this flag set does not
    /// mean the project is clean: the rule could not run safely. Serialized
    /// only when `true`, like the flat `CheckOutput` field.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub unused_load_data_keys_global_abstain: bool,
    /// Number of export and member findings that the run hid because their
    /// file is an unused file. The count covers the whole run, so it is on
    /// the root and not in a group. Serialized only when not zero, like the
    /// flat `CheckOutput` field.
    #[serde(default, skip_serializing_if = "is_zero")]
    pub cascade_hidden: usize,
    /// This run's view of the loaded baseline, present only in baseline runs.
    /// Carries the staleness counts, the advisory verdict and `gate_trips`, the
    /// same boolean `--fail-on-stale-baseline` exits on, so a CI integration
    /// reads one field instead of restating the rule. Read `change_scoped`
    /// before dividing `matched_entries` by `baseline_entries`: a narrowed run
    /// can report `matched_entries: 0` on a healthy baseline.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub baseline_staleness: Option<crate::BaselineStaleness>,
    /// The answer to `--finding-id`, present only when the run received one
    /// or more `--finding-id` values. The report then holds only the
    /// requested findings. Read `missing` as resolved only when `conclusive`
    /// is true; a scope, a baseline or a filter can hide a finding that still
    /// exists. See [`crate::FindingIdQuery`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub finding_id_query: Option<crate::FindingIdQuery>,
    /// The verdict of every gate this run evaluated, keyed by name. The CLI
    /// always emits it, with the command's default exit rule in it also when
    /// no flag armed a gate, so a CI integration reads the verdict instead of
    /// guessing from a process status it usually cannot see. A gate fails the
    /// build when `status` is `fail` AND `enforced` is true. The typed
    /// programmatic API runs no CLI gate and leaves it absent. See
    /// [`crate::GateOutcomes`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub gate_outcomes: Option<crate::GateOutcomes>,
    /// Every narrowing or shaping request this run RECEIVED, keyed by name,
    /// absent when it was asked for nothing. An entry whose `status` is not
    /// `applied` means the run could not do what it was asked and reported
    /// something WIDER instead, so what follows is a valid report of a scope
    /// nobody requested. Honoured requests are published too, with
    /// `status: "applied"`, so an absent object means "nothing was asked for",
    /// never "nothing failed". See [`crate::RequestOutcomes`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_outcomes: Option<crate::RequestOutcomes>,
    /// Applied package Git refs, omitted outside package-baseline runs.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub package_baselines: Vec<crate::PackageBaselineStatus>,
    /// `_meta` block with docs and rule definitions, when `--explain` was
    /// passed.
    #[serde(rename = "_meta", default, skip_serializing_if = "Option::is_none")]
    pub meta: Option<Meta>,
    /// Diagnostics collected for the full analysis before issue grouping.
    /// See [`CheckOutput::workspace_diagnostics`] for the contract.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Read-only follow-up commands computed from the full (ungrouped) findings.
    /// See [`CheckOutput::next_steps`] for the contract.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub next_steps: Vec<NextStep>,
}

/// Single resolver bucket inside `CheckGroupedOutput`. Carries the group's
/// identifier, optional section owners, and a per-group flattened
/// `AnalysisResults`.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CheckGroupedEntry {
    /// Resolver key: team name, directory prefix, package name, or section.
    pub key: String,
    /// Owners of a GitLab CODEOWNERS section; present for section grouping.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub owners: Option<Vec<String>>,
    /// Findings in this group.
    pub total_issues: usize,
    /// Group-scoped analysis results, flattened like the ungrouped body.
    #[serde(flatten)]
    pub results: AnalysisResults,
}

/// Resolver mode label for grouped envelopes (dead-code, dupes, health).
///
/// `owner` groups by CODEOWNERS team, `directory` groups by top-level
/// directory prefix, `package` groups by workspace package name, `section`
/// groups by GitLab CODEOWNERS `[Section]` header name.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "lowercase")]
pub enum GroupByMode {
    /// Group by CODEOWNERS team.
    Owner,
    /// Group by top-level directory prefix.
    Directory,
    /// Group by workspace package name.
    Package,
    /// Group by GitLab CODEOWNERS `[Section]` header name.
    Section,
}

/// Inputs for building the dead-code JSON envelope.
pub struct CheckOutputInput {
    /// Dead-code output schema version to report.
    pub schema_version: u32,
    /// Fallow CLI version to report.
    pub version: String,
    /// Wall-clock analysis duration; serialized as whole milliseconds.
    pub elapsed: Duration,
    /// Engine analysis results to embed.
    pub results: AnalysisResults,
    /// Whether duplicate-export findings are fixable via config edits, which
    /// flips their `config_fixable` action flag.
    pub config_fixable: bool,
    /// `_meta` block to attach when `--explain` was passed.
    pub meta: Option<Meta>,
    /// Workspace-discovery, source-discovery, and analysis-stage diagnostics.
    /// See [`CheckOutput::workspace_diagnostics`] for the contract.
    pub workspace_diagnostics: Vec<WorkspaceDiagnostic>,
    /// Read-only follow-up commands computed from this run's findings.
    pub next_steps: Vec<NextStep>,
}

/// Build the typed dead-code JSON envelope from engine results.
#[must_use]
pub fn build_check_output(input: CheckOutputInput) -> CheckOutput {
    let mut results = input.results;
    apply_config_fixable_to_duplicate_exports(&mut results, input.config_fixable);
    harmonize_multi_kind_suppress_line_actions(&mut results);
    CheckOutput {
        schema_version: SchemaVersion(input.schema_version),
        version: ToolVersion(input.version),
        elapsed_ms: ElapsedMs(input.elapsed.as_millis() as u64),
        total_issues: results.total_issues(),
        entry_points: results
            .entry_point_summary
            .as_ref()
            .map(|entry_points| EntryPoints {
                total: entry_points.total,
                sources: entry_points
                    .by_source
                    .iter()
                    .map(|(key, value)| (key.replace(' ', "_"), *value))
                    .collect(),
            }),
        summary: build_check_summary(&results),
        results,
        baseline_deltas: None,
        baseline: None,
        baseline_staleness: None,
        finding_id_query: None,
        regression: None,
        gate_outcomes: None,
        request_outcomes: None,
        package_baselines: Vec::new(),
        meta: input.meta,
        workspace_diagnostics: input.workspace_diagnostics,
        next_steps: input.next_steps,
    }
}

fn serialize_check_family_json_output<T: Serialize>(
    output: T,
    kind: &'static str,
    analysis_run_id: Option<&str>,
) -> Result<serde_json::Value, serde_json::Error> {
    let mut value = serialize_named_json_output(output, kind)?;
    attach_telemetry_meta(&mut value, analysis_run_id);
    Ok(value)
}

/// Serialize `fallow dead-code --format json`.
///
/// # Errors
///
/// Returns a serde error when the dead-code output cannot be converted to JSON.
pub fn serialize_check_json_output(
    output: CheckOutput,
    analysis_run_id: Option<&str>,
) -> Result<serde_json::Value, serde_json::Error> {
    serialize_check_family_json_output(output, "dead-code", analysis_run_id)
}

/// Serialize `fallow dead-code --group-by ... --format json`.
///
/// # Errors
///
/// Returns a serde error when the grouped dead-code output cannot be converted
/// to JSON.
pub fn serialize_check_grouped_json_output(
    output: CheckGroupedOutput,
    analysis_run_id: Option<&str>,
) -> Result<serde_json::Value, serde_json::Error> {
    serialize_check_family_json_output(output, "dead-code-grouped", analysis_run_id)
}

/// Serialize `fallow architecture --format json`.
///
/// The body is the dead-code body. The caller sets `schema_version` to
/// [`ARCHITECTURE_SCHEMA_VERSION`].
///
/// # Errors
///
/// Returns a serde error when the output cannot be converted to JSON.
pub fn serialize_architecture_json_output(
    output: CheckOutput,
    analysis_run_id: Option<&str>,
) -> Result<serde_json::Value, serde_json::Error> {
    serialize_check_family_json_output(output, CheckEnvelope::Architecture.kind(), analysis_run_id)
}

/// Serialize `fallow architecture --group-by ... --format json`.
///
/// # Errors
///
/// Returns a serde error when the grouped output cannot be converted to JSON.
pub fn serialize_architecture_grouped_json_output(
    output: CheckGroupedOutput,
    analysis_run_id: Option<&str>,
) -> Result<serde_json::Value, serde_json::Error> {
    serialize_check_family_json_output(
        output,
        CheckEnvelope::Architecture.grouped_kind(),
        analysis_run_id,
    )
}

/// Mark every duplicate-export finding as fixable through a config edit when
/// the project's config supports automated fixes.
pub fn apply_config_fixable_to_duplicate_exports(
    results: &mut AnalysisResults,
    config_fixable: bool,
) {
    if !config_fixable {
        return;
    }
    for finding in &mut results.duplicate_exports {
        finding.set_config_fixable(true);
    }
}

type SuppressAnchor = (String, u32);

macro_rules! visit_suppress_line_findings {
    ($results:expr, $visit:expr) => {{
        let results = $results;
        for finding in &results.unused_exports {
            $visit(&finding.export.path, finding.export.line, &finding.actions);
        }
        for finding in &results.unused_types {
            $visit(&finding.export.path, finding.export.line, &finding.actions);
        }
        for finding in &results.private_type_leaks {
            $visit(&finding.leak.path, finding.leak.line, &finding.actions);
        }
        for finding in &results.deprecated_exports_in_use {
            $visit(&finding.export.path, finding.export.line, &finding.actions);
        }
        for finding in &results.unused_enum_members {
            $visit(&finding.member.path, finding.member.line, &finding.actions);
        }
        for finding in &results.unused_class_members {
            $visit(&finding.member.path, finding.member.line, &finding.actions);
        }
        for finding in &results.unused_store_members {
            $visit(&finding.member.path, finding.member.line, &finding.actions);
        }
        for finding in &results.unresolved_imports {
            $visit(&finding.import.path, finding.import.line, &finding.actions);
        }
        for finding in &results.unused_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.unused_dev_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.unused_optional_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.type_only_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.test_only_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.dev_dependencies_in_production {
            $visit(&finding.dep.path, finding.dep.line, &finding.actions);
        }
        for finding in &results.circular_dependencies {
            if let Some(path) = finding.cycle.files.first() {
                $visit(path, finding.cycle.line, &finding.actions);
            }
        }
        for finding in &results.package_cycles {
            if let Some(edge) = finding.cycle.edges.first() {
                $visit(&edge.path, edge.line, &finding.actions);
            }
        }
        for finding in &results.boundary_violations {
            $visit(
                &finding.violation.from_path,
                finding.violation.line,
                &finding.actions,
            );
        }
        for finding in &results.boundary_coverage_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &finding.actions,
            );
        }
        for finding in &results.boundary_call_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &finding.actions,
            );
        }
        for finding in &results.policy_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &finding.actions,
            );
        }
        for finding in &results.unused_catalog_entries {
            $visit(&finding.entry.path, finding.entry.line, &finding.actions);
        }
        for finding in &results.empty_catalog_groups {
            $visit(&finding.group.path, finding.group.line, &finding.actions);
        }
        for finding in &results.unresolved_catalog_references {
            $visit(
                &finding.reference.path,
                finding.reference.line,
                &finding.actions,
            );
        }
        for finding in &results.unused_dependency_overrides {
            $visit(&finding.entry.path, finding.entry.line, &finding.actions);
        }
        for finding in &results.misconfigured_dependency_overrides {
            $visit(&finding.entry.path, finding.entry.line, &finding.actions);
        }
        for finding in &results.invalid_client_exports {
            $visit(&finding.export.path, finding.export.line, &finding.actions);
        }
        for finding in &results.mixed_client_server_barrels {
            $visit(&finding.barrel.path, finding.barrel.line, &finding.actions);
        }
        for finding in &results.misplaced_directives {
            $visit(
                &finding.directive_site.path,
                finding.directive_site.line,
                &finding.actions,
            );
        }
        for finding in &results.unprovided_injects {
            $visit(&finding.inject.path, finding.inject.line, &finding.actions);
        }
        for finding in &results.unrendered_components {
            $visit(
                &finding.component.path,
                finding.component.line,
                &finding.actions,
            );
        }
        for finding in &results.route_collisions {
            $visit(
                &finding.collision.path,
                finding.collision.line,
                &finding.actions,
            );
        }
        for finding in &results.dynamic_segment_name_conflicts {
            $visit(
                &finding.conflict.path,
                finding.conflict.line,
                &finding.actions,
            );
        }
        for finding in &results.unused_component_props {
            $visit(&finding.prop.path, finding.prop.line, &finding.actions);
        }
        for finding in &results.absent_component_props {
            $visit(&finding.prop.path, finding.prop.line, &finding.actions);
        }
        for finding in &results.unused_component_emits {
            $visit(&finding.emit.path, finding.emit.line, &finding.actions);
        }
        for finding in &results.unused_component_inputs {
            $visit(&finding.input.path, finding.input.line, &finding.actions);
        }
        for finding in &results.unused_component_outputs {
            $visit(&finding.output.path, finding.output.line, &finding.actions);
        }
        for finding in &results.unused_svelte_events {
            $visit(&finding.event.path, finding.event.line, &finding.actions);
        }
        for finding in &results.unused_effect_layers {
            $visit(&finding.layer.path, finding.layer.line, &finding.actions);
        }
        for finding in &results.unused_tagged_errors {
            $visit(&finding.error.path, finding.error.line, &finding.actions);
        }
        for finding in &results.unproduced_catch_tags {
            $visit(
                &finding.catch_tag.path,
                finding.catch_tag.line,
                &finding.actions,
            );
        }
        for finding in &results.unused_server_actions {
            $visit(&finding.action.path, finding.action.line, &finding.actions);
        }
        for finding in &results.unused_load_data_keys {
            $visit(&finding.key.path, finding.key.line, &finding.actions);
        }
        for finding in &results.prop_drilling_chains {
            if let Some(hop) = finding.chain.hops.first() {
                $visit(&hop.file, hop.line, &finding.actions);
            }
        }
        for finding in &results.thin_wrappers {
            $visit(
                &finding.wrapper.file,
                finding.wrapper.line,
                &finding.actions,
            );
        }
        for finding in &results.duplicate_prop_shapes {
            $visit(&finding.shape.file, finding.shape.line, &finding.actions);
        }
    }};
}

macro_rules! visit_suppress_line_findings_mut {
    ($results:expr, $visit:expr) => {{
        let results = $results;
        for finding in &mut results.unused_exports {
            $visit(
                &finding.export.path,
                finding.export.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_types {
            $visit(
                &finding.export.path,
                finding.export.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.private_type_leaks {
            $visit(&finding.leak.path, finding.leak.line, &mut finding.actions);
        }
        for finding in &mut results.deprecated_exports_in_use {
            $visit(
                &finding.export.path,
                finding.export.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_enum_members {
            $visit(
                &finding.member.path,
                finding.member.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_class_members {
            $visit(
                &finding.member.path,
                finding.member.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_store_members {
            $visit(
                &finding.member.path,
                finding.member.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unresolved_imports {
            $visit(
                &finding.import.path,
                finding.import.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.unused_dev_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.unused_optional_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.type_only_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.test_only_dependencies {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.dev_dependencies_in_production {
            $visit(&finding.dep.path, finding.dep.line, &mut finding.actions);
        }
        for finding in &mut results.circular_dependencies {
            if let Some(path) = finding.cycle.files.first() {
                $visit(path, finding.cycle.line, &mut finding.actions);
            }
        }
        for finding in &mut results.package_cycles {
            if let Some(edge) = finding.cycle.edges.first() {
                $visit(&edge.path, edge.line, &mut finding.actions);
            }
        }
        for finding in &mut results.boundary_violations {
            $visit(
                &finding.violation.from_path,
                finding.violation.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.boundary_coverage_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.boundary_call_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.policy_violations {
            $visit(
                &finding.violation.path,
                finding.violation.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_catalog_entries {
            $visit(
                &finding.entry.path,
                finding.entry.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.empty_catalog_groups {
            $visit(
                &finding.group.path,
                finding.group.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unresolved_catalog_references {
            $visit(
                &finding.reference.path,
                finding.reference.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_dependency_overrides {
            $visit(
                &finding.entry.path,
                finding.entry.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.misconfigured_dependency_overrides {
            $visit(
                &finding.entry.path,
                finding.entry.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.invalid_client_exports {
            $visit(
                &finding.export.path,
                finding.export.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.mixed_client_server_barrels {
            $visit(
                &finding.barrel.path,
                finding.barrel.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.misplaced_directives {
            $visit(
                &finding.directive_site.path,
                finding.directive_site.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unprovided_injects {
            $visit(
                &finding.inject.path,
                finding.inject.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unrendered_components {
            $visit(
                &finding.component.path,
                finding.component.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.route_collisions {
            $visit(
                &finding.collision.path,
                finding.collision.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.dynamic_segment_name_conflicts {
            $visit(
                &finding.conflict.path,
                finding.conflict.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_component_props {
            $visit(&finding.prop.path, finding.prop.line, &mut finding.actions);
        }
        for finding in &mut results.absent_component_props {
            $visit(&finding.prop.path, finding.prop.line, &mut finding.actions);
        }
        for finding in &mut results.unused_component_emits {
            $visit(&finding.emit.path, finding.emit.line, &mut finding.actions);
        }
        for finding in &mut results.unused_component_inputs {
            $visit(
                &finding.input.path,
                finding.input.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_component_outputs {
            $visit(
                &finding.output.path,
                finding.output.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_svelte_events {
            $visit(
                &finding.event.path,
                finding.event.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_effect_layers {
            $visit(
                &finding.layer.path,
                finding.layer.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_tagged_errors {
            $visit(
                &finding.error.path,
                finding.error.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unproduced_catch_tags {
            $visit(
                &finding.catch_tag.path,
                finding.catch_tag.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_server_actions {
            $visit(
                &finding.action.path,
                finding.action.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.unused_load_data_keys {
            $visit(&finding.key.path, finding.key.line, &mut finding.actions);
        }
        for finding in &mut results.prop_drilling_chains {
            if let Some(hop) = finding.chain.hops.first() {
                $visit(&hop.file, hop.line, &mut finding.actions);
            }
        }
        for finding in &mut results.thin_wrappers {
            $visit(
                &finding.wrapper.file,
                finding.wrapper.line,
                &mut finding.actions,
            );
        }
        for finding in &mut results.duplicate_prop_shapes {
            $visit(
                &finding.shape.file,
                finding.shape.line,
                &mut finding.actions,
            );
        }
    }};
}

/// Merge same-line suppress actions so multi-kind findings share one comment.
///
/// This runs on typed `AnalysisResults` before serialization. It replaces the
/// older JSON-object walk for normal check output and keeps the action contract
/// owned by the output builders.
pub fn harmonize_multi_kind_suppress_line_actions(results: &mut AnalysisResults) {
    let mut anchors: BTreeMap<SuppressAnchor, Vec<String>> = BTreeMap::new();
    collect_dead_code_suppress_line_anchors(results, &mut anchors);
    retain_multi_kind_anchors(&mut anchors);
    if anchors.is_empty() {
        return;
    }
    rewrite_dead_code_suppress_line_actions(results, &anchors);
}

/// Merge same-line suppress actions across dead-code and health sections.
///
/// Combined and audit output can surface both dead-code and complexity findings
/// anchored to the same source line. This keeps the single-line suppress hint
/// typed until the final JSON serialization step.
pub fn harmonize_dead_code_health_suppress_line_actions(
    dead_code: Option<&mut AnalysisResults>,
    health: Option<&mut HealthReport>,
) {
    let mut anchors: BTreeMap<SuppressAnchor, Vec<String>> = BTreeMap::new();
    if let Some(results) = dead_code.as_deref() {
        collect_dead_code_suppress_line_anchors(results, &mut anchors);
    }
    if let Some(report) = health.as_deref() {
        collect_health_suppress_line_anchors(report, &mut anchors);
    }

    retain_multi_kind_anchors(&mut anchors);
    if anchors.is_empty() {
        return;
    }

    if let Some(results) = dead_code {
        rewrite_dead_code_suppress_line_actions(results, &anchors);
    }
    if let Some(report) = health {
        rewrite_health_suppress_line_actions(report, &anchors);
    }
}

fn retain_multi_kind_anchors(anchors: &mut BTreeMap<SuppressAnchor, Vec<String>>) {
    anchors.retain(|_, kinds| {
        sort_suppression_kinds(kinds);
        kinds.dedup();
        kinds.len() > 1
    });
}

fn collect_dead_code_suppress_line_anchors(
    results: &AnalysisResults,
    anchors: &mut BTreeMap<SuppressAnchor, Vec<String>>,
) {
    visit_suppress_line_findings!(results, |path: &Path, line, actions: &[IssueAction]| {
        collect_action_kinds(path, line, actions, anchors);
    });
}

fn rewrite_dead_code_suppress_line_actions(
    results: &mut AnalysisResults,
    anchors: &BTreeMap<SuppressAnchor, Vec<String>>,
) {
    visit_suppress_line_findings_mut!(
        results,
        |path: &Path, line, actions: &mut Vec<IssueAction>| {
            let anchor = suppress_anchor(path, line);
            if let Some(kinds) = anchors.get(&anchor) {
                let comment = format!("// fallow-ignore-next-line {}", kinds.join(", "));
                rewrite_action_comments(actions, &comment);
            }
        }
    );
}

fn collect_health_suppress_line_anchors(
    report: &HealthReport,
    anchors: &mut BTreeMap<SuppressAnchor, Vec<String>>,
) {
    for finding in &report.findings {
        collect_health_action_kinds(
            &finding.violation.path,
            finding.violation.line,
            &finding.actions,
            anchors,
        );
    }
    for finding in &report.prop_drilling_chains {
        if let Some(hop) = finding.chain.hops.first() {
            collect_action_kinds(&hop.file, hop.line, &finding.actions, anchors);
        }
    }
}

fn rewrite_health_suppress_line_actions(
    report: &mut HealthReport,
    anchors: &BTreeMap<SuppressAnchor, Vec<String>>,
) {
    for finding in &mut report.findings {
        let anchor = suppress_anchor(&finding.violation.path, finding.violation.line);
        if let Some(kinds) = anchors.get(&anchor) {
            let comment = format!("// fallow-ignore-next-line {}", kinds.join(", "));
            rewrite_health_action_comments(&mut finding.actions, &comment);
        }
    }
    for finding in &mut report.prop_drilling_chains {
        if let Some(hop) = finding.chain.hops.first() {
            let anchor = suppress_anchor(&hop.file, hop.line);
            if let Some(kinds) = anchors.get(&anchor) {
                let comment = format!("// fallow-ignore-next-line {}", kinds.join(", "));
                rewrite_action_comments(&mut finding.actions, &comment);
            }
        }
    }
}

fn collect_action_kinds(
    path: &Path,
    line: u32,
    actions: &[IssueAction],
    anchors: &mut BTreeMap<SuppressAnchor, Vec<String>>,
) {
    for action in actions {
        if let Some(comment) = suppress_line_comment(action) {
            let kinds = anchors.entry(suppress_anchor(path, line)).or_default();
            for kind in parse_suppress_line_comment(comment) {
                if !kinds.iter().any(|existing| existing == &kind) {
                    kinds.push(kind);
                }
            }
        }
    }
}

fn collect_health_action_kinds(
    path: &Path,
    line: u32,
    actions: &[HealthFindingAction],
    anchors: &mut BTreeMap<SuppressAnchor, Vec<String>>,
) {
    for action in actions {
        if let Some(comment) = health_suppress_line_comment(action) {
            let kinds = anchors.entry(suppress_anchor(path, line)).or_default();
            for kind in parse_suppress_line_comment(comment) {
                if !kinds.iter().any(|existing| existing == &kind) {
                    kinds.push(kind);
                }
            }
        }
    }
}

fn rewrite_action_comments(actions: &mut [IssueAction], comment: &str) {
    for action in actions {
        if let IssueAction::SuppressLine(suppress) = action {
            suppress.comment = comment.to_string();
        }
    }
}

fn rewrite_health_action_comments(actions: &mut [HealthFindingAction], comment: &str) {
    for action in actions {
        if matches!(action.kind, HealthFindingActionType::SuppressLine) {
            action.comment = Some(comment.to_string());
        }
    }
}

fn suppress_anchor(path: &Path, line: u32) -> SuppressAnchor {
    (path.display().to_string(), line)
}

fn suppress_line_comment(action: &IssueAction) -> Option<&str> {
    match action {
        IssueAction::SuppressLine(action) => Some(&action.comment),
        _ => None,
    }
}

fn health_suppress_line_comment(action: &HealthFindingAction) -> Option<&str> {
    matches!(action.kind, HealthFindingActionType::SuppressLine)
        .then_some(())
        .and(action.comment.as_deref())
}

fn parse_suppress_line_comment(comment: &str) -> Vec<String> {
    comment
        .strip_prefix("// fallow-ignore-next-line ")
        .map(|rest| {
            rest.split(|c: char| c == ',' || c.is_whitespace())
                .filter(|token| !token.is_empty())
                .map(str::to_string)
                .collect()
        })
        .unwrap_or_default()
}

fn sort_suppression_kinds(kinds: &mut [String]) {
    kinds.sort_by_key(|kind| suppression_kind_rank(kind));
}

fn suppression_kind_rank(kind: &str) -> usize {
    match kind {
        "unused-file" => 0,
        "unused-export" => 1,
        "unused-type" => 2,
        "private-type-leak" => 3,
        "unused-enum-member" => 4,
        "unused-class-member" => 5,
        "unused-store-member" => 6,
        "unresolved-import" => 7,
        "unlisted-dependency" => 8,
        "duplicate-export" => 9,
        "circular-dependency" => 10,
        "re-export-cycle" => 11,
        "boundary-violation" => 12,
        "code-duplication" => 13,
        "complexity" => 14,
        "unprovided-inject" => 15,
        "unrendered-component" => 16,
        "unused-server-action" => 17,
        "deprecated-export-in-use" => 18,
        "package-cycle" => 19,
        _ => usize::MAX,
    }
}

/// Compute the per-category `CheckSummary` from analysis results.
#[must_use]
pub fn build_check_summary(results: &AnalysisResults) -> CheckSummary {
    CheckSummary {
        total_issues: results.total_issues(),
        prop_drilling_chains: results.enforced_prop_drilling_count(),
        thin_wrappers: results.enforced_thin_wrapper_count(),
        duplicate_prop_shapes: results.enforced_duplicate_prop_shape_count(),
        unused_files: results.unused_files.len(),
        unused_exports: results.unused_exports.len(),
        unused_types: results.unused_types.len(),
        private_type_leaks: results.private_type_leaks.len(),
        deprecated_exports_in_use: results.deprecated_exports_in_use.len(),
        unused_dependencies: results.unused_dependencies.len()
            + results.unused_dev_dependencies.len()
            + results.unused_optional_dependencies.len(),
        unused_enum_members: results.unused_enum_members.len(),
        unused_class_members: results.unused_class_members.len(),
        unused_store_members: results.unused_store_members.len(),
        unresolved_imports: results.unresolved_imports.len(),
        unlisted_dependencies: results.unlisted_dependencies.len(),
        duplicate_exports: results.duplicate_exports.len(),
        type_only_dependencies: results.type_only_dependencies.len(),
        test_only_dependencies: results.test_only_dependencies.len(),
        dev_dependencies_in_production: results.dev_dependencies_in_production.len(),
        circular_dependencies: results.circular_dependencies.len(),
        re_export_cycles: results.re_export_cycles.len(),
        package_cycles: results.package_cycles.len(),
        boundary_violations: results.boundary_violations.len(),
        boundary_coverage_violations: results.boundary_coverage_violations.len(),
        boundary_call_violations: results.boundary_call_violations.len(),
        policy_violations: results.policy_violations.len(),
        stale_suppressions: results.stale_suppressions.len(),
        unused_catalog_entries: results.unused_catalog_entries.len(),
        empty_catalog_groups: results.empty_catalog_groups.len(),
        unresolved_catalog_references: results.unresolved_catalog_references.len(),
        unused_dependency_overrides: results.unused_dependency_overrides.len(),
        misconfigured_dependency_overrides: results.misconfigured_dependency_overrides.len(),
        invalid_client_exports: results.invalid_client_exports.len(),
        mixed_client_server_barrels: results.mixed_client_server_barrels.len(),
        misplaced_directives: results.misplaced_directives.len(),
        unprovided_injects: results.unprovided_injects.len(),
        unrendered_components: results.unrendered_components.len(),
        unused_component_props: results.unused_component_props.len(),
        absent_component_props: results.absent_component_props.len(),
        unused_component_emits: results.unused_component_emits.len(),
        unused_component_inputs: results.unused_component_inputs.len(),
        unused_component_outputs: results.unused_component_outputs.len(),
        unused_svelte_events: results.unused_svelte_events.len(),
        unused_effect_layers: results.unused_effect_layers.len(),
        unused_tagged_errors: results.unused_tagged_errors.len(),
        unproduced_catch_tags: results.unproduced_catch_tags.len(),
        unused_server_actions: results.unused_server_actions.len(),
        unused_load_data_keys: results.unused_load_data_keys.len(),
        route_collisions: results.route_collisions.len(),
        dynamic_segment_name_conflicts: results.dynamic_segment_name_conflicts.len(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{ComplexityViolation, ExceededThreshold, FindingSeverity, HealthFinding};
    use fallow_types::output_dead_code::{
        ReachabilityCaveat, UnusedExportFinding, UnusedFileFinding, UnusedTypeFinding,
    };
    use fallow_types::results::{UnusedExport, UnusedFile};
    use fallow_types::workspace::WorkspaceDiagnosticKind;

    #[test]
    fn build_check_output_counts_issues_and_entry_points() {
        let mut results = AnalysisResults::default();
        results
            .unused_files
            .push(UnusedFileFinding::with_actions(UnusedFile {
                path: "src/unused.ts".into(),
            }));

        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(42),
            results,
            config_fixable: false,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        });

        assert_eq!(output.schema_version.0, 7);
        assert_eq!(output.total_issues, 1);
        assert_eq!(output.summary.unused_files, 1);
        assert_eq!(output.elapsed_ms.0, 42);
    }

    #[test]
    fn build_check_output_harmonizes_multi_kind_suppress_actions_typed() {
        let mut results = AnalysisResults::default();
        let path = std::path::PathBuf::from("/project/src/shared.ts");
        results
            .unused_exports
            .push(UnusedExportFinding::with_actions(UnusedExport {
                path: path.clone(),
                export_name: "value".to_string(),
                is_type_only: false,
                line: 7,
                col: 0,
                span_start: 0,
                is_re_export: false,
                deprecated: false,
                deprecated_reason: None,
            }));
        results
            .unused_types
            .push(UnusedTypeFinding::with_actions(UnusedExport {
                path,
                export_name: "TypeOnly".to_string(),
                is_type_only: true,
                line: 7,
                col: 0,
                span_start: 0,
                is_re_export: false,
                deprecated: false,
                deprecated_reason: None,
            }));

        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(42),
            results,
            config_fixable: false,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        });

        let export_comment = suppress_comment(&output.results.unused_exports[0].actions);
        let type_comment = suppress_comment(&output.results.unused_types[0].actions);
        assert_eq!(
            export_comment,
            Some("// fallow-ignore-next-line unused-export, unused-type")
        );
        assert_eq!(type_comment, export_comment);
    }

    #[test]
    fn harmonize_dead_code_health_suppress_actions_typed() {
        let mut results = AnalysisResults::default();
        let path = std::path::PathBuf::from("/project/src/shared.ts");
        results
            .unused_exports
            .push(UnusedExportFinding::with_actions(UnusedExport {
                path: path.clone(),
                export_name: "value".to_string(),
                is_type_only: false,
                line: 7,
                col: 0,
                span_start: 0,
                is_re_export: false,
                deprecated: false,
                deprecated_reason: None,
            }));
        let mut health = HealthReport {
            findings: vec![HealthFinding::new(
                ComplexityViolation {
                    path,
                    name: "expensive".to_string(),
                    line: 7,
                    col: 0,
                    cyclomatic: 22,
                    standard_cyclomatic: None,
                    cognitive: 18,
                    line_count: 40,
                    param_count: 1,
                    react_hook_count: 0,
                    react_jsx_max_depth: 0,
                    react_prop_count: 0,
                    react_hook_profile: None,
                    exceeded: ExceededThreshold::Both,
                    severity: FindingSeverity::High,
                    effective_severity: None,
                    crap: None,
                    mutation: None,
                    coverage_pct: None,
                    coverage_tier: None,
                    coverage_source: None,
                    inherited_from: None,
                    component_rollup: None,
                    contributions: Vec::new(),
                    effective_thresholds: None,
                    threshold_source: None,
                },
                vec![HealthFindingAction {
                    kind: HealthFindingActionType::SuppressLine,
                    auto_fixable: false,
                    description: "Suppress with an inline comment above the function declaration"
                        .to_string(),
                    note: None,
                    comment: Some("// fallow-ignore-next-line complexity".to_string()),
                    placement: Some("above-function-declaration".to_string()),
                    target_path: None,
                }],
                None,
            )],
            ..HealthReport::default()
        };

        harmonize_dead_code_health_suppress_line_actions(Some(&mut results), Some(&mut health));

        assert_eq!(
            suppress_comment(&results.unused_exports[0].actions),
            Some("// fallow-ignore-next-line unused-export, complexity")
        );
        assert_eq!(
            health.findings[0].actions[0].comment.as_deref(),
            Some("// fallow-ignore-next-line unused-export, complexity")
        );
    }

    #[test]
    fn check_json_output_uses_output_owned_root_contract() {
        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(42),
            results: AnalysisResults::default(),
            config_fixable: false,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        });

        let value = serialize_check_json_output(output, Some("run-check"))
            .expect("check output should serialize");

        assert_eq!(value["kind"], "dead-code");
        assert_eq!(value["_meta"]["telemetry"]["analysis_run_id"], "run-check");
    }

    #[test]
    fn architecture_json_output_has_architecture_kind_and_version() {
        let envelope = CheckEnvelope::Architecture;
        let output = build_check_output(CheckOutputInput {
            schema_version: envelope.schema_version(),
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(1),
            results: AnalysisResults::default(),
            config_fixable: false,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        });

        let value = serialize_architecture_json_output(output, Some("run-arch"))
            .expect("architecture output should serialize");

        assert_eq!(value["kind"], "architecture");
        assert_eq!(value["schema_version"], ARCHITECTURE_SCHEMA_VERSION);
        assert_eq!(value["_meta"]["telemetry"]["analysis_run_id"], "run-arch");
    }

    #[test]
    fn check_envelope_names_each_family_member() {
        assert_eq!(CheckEnvelope::DeadCode.kind(), "dead-code");
        assert_eq!(CheckEnvelope::DeadCode.grouped_kind(), "dead-code-grouped");
        assert_eq!(
            CheckEnvelope::DeadCode.schema_version(),
            CHECK_SCHEMA_VERSION
        );
        assert_eq!(CheckEnvelope::DeadCode.command(), "dead-code");
        assert_eq!(CheckEnvelope::Architecture.kind(), "architecture");
        assert_eq!(
            CheckEnvelope::Architecture.grouped_kind(),
            "architecture-grouped"
        );
        assert_eq!(
            CheckEnvelope::Architecture.schema_version(),
            ARCHITECTURE_SCHEMA_VERSION
        );
        assert_eq!(CheckEnvelope::Architecture.command(), "architecture");
    }

    /// The degraded-parse caveat has to travel WITH the finding it can distort,
    /// because a reader looking at a `delete-file` action never sees the
    /// diagnostic at the other end of the envelope. It is advisory about the
    /// FINDING and decisive only about the MUTATION: the actions array keeps
    /// its shape and its order, the mutating action reports
    /// `auto_fixable: false`, and a clean finding stays byte-identical.
    #[test]
    fn reachability_caveats_are_absent_when_clean_and_named_when_flagged() {
        let mut results = AnalysisResults::default();
        results
            .unused_files
            .push(UnusedFileFinding::with_actions(UnusedFile {
                path: "/project/src/clean.ts".into(),
            }));
        let mut flagged = UnusedFileFinding::with_actions(UnusedFile {
            path: "/project/src/orphan.ts".into(),
        });
        flagged.reachability_caveats = vec![
            ReachabilityCaveat::IncompleteFileAnalysis,
            ReachabilityCaveat::IncompleteImportGraph,
        ];
        results.unused_files.push(flagged);

        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(1),
            results,
            config_fixable: false,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        });
        let value =
            serialize_check_json_output(output, None).expect("dead-code output should serialize");

        let entries = value["unused_files"]
            .as_array()
            .expect("unused_files array")
            .clone();
        let find = |name: &str| {
            entries
                .iter()
                .find(|entry| {
                    entry["path"]
                        .as_str()
                        .is_some_and(|path| path.ends_with(name))
                })
                .cloned()
                .expect("finding present")
        };

        assert!(
            find("clean.ts").get("reachability_caveats").is_none(),
            "a finding with no caveat must keep the previous wire shape exactly"
        );

        let flagged = find("orphan.ts");
        assert_eq!(
            flagged["reachability_caveats"],
            serde_json::json!(["incomplete-file-analysis", "incomplete-import-graph"]),
            "both caveats are named on the wire, in declaration order"
        );
        assert_eq!(
            flagged["actions"].as_array().map(Vec::len),
            Some(2),
            "the caveat never trims the finding's actions"
        );
        assert_eq!(
            flagged["actions"][0]["type"], "delete-file",
            "nor reorders them, so a consumer reading actions[0].type is unaffected"
        );
        assert_eq!(
            flagged["actions"][0]["auto_fixable"],
            serde_json::json!(false),
            "but the mutation it gates must not advertise itself as applicable"
        );
    }

    #[test]
    fn grouped_check_json_output_uses_output_owned_root_contract() {
        let root = std::path::Path::new("/project");
        let output = CheckGroupedOutput {
            gate_outcomes: None,
            request_outcomes: None,
            package_baselines: Vec::new(),
            baseline_staleness: None,
            finding_id_query: None,
            schema_version: SchemaVersion(7),
            version: ToolVersion("0.0.0".to_string()),
            elapsed_ms: ElapsedMs(1),
            grouped_by: GroupByMode::Directory,
            total_issues: 0,
            groups: Vec::new(),
            unused_load_data_keys_global_abstain: false,
            cascade_hidden: 0,
            meta: None,
            workspace_diagnostics: vec![WorkspaceDiagnostic::new(
                root,
                root.join("src/unreadable.ts"),
                WorkspaceDiagnosticKind::SourceReadFailure {
                    error: "permission denied".to_string(),
                },
            )],
            next_steps: Vec::new(),
        };

        let value = serialize_check_grouped_json_output(output, Some("run-group"))
            .expect("grouped check output should serialize");

        assert_eq!(value["kind"], "dead-code-grouped");
        assert_eq!(value["_meta"]["telemetry"]["analysis_run_id"], "run-group");
        assert_eq!(
            value["workspace_diagnostics"][0]["path"],
            "/project/src/unreadable.ts"
        );
        assert_eq!(
            value["workspace_diagnostics"][0]["kind"],
            "source-read-failure"
        );
    }

    #[test]
    fn architecture_grouped_json_output_has_grouped_kind() {
        let output = CheckGroupedOutput {
            gate_outcomes: None,
            request_outcomes: None,
            package_baselines: Vec::new(),
            baseline_staleness: None,
            finding_id_query: None,
            schema_version: SchemaVersion(ARCHITECTURE_SCHEMA_VERSION),
            version: ToolVersion("0.0.0".to_string()),
            elapsed_ms: ElapsedMs(1),
            grouped_by: GroupByMode::Directory,
            total_issues: 0,
            groups: Vec::new(),
            unused_load_data_keys_global_abstain: false,
            cascade_hidden: 0,
            meta: None,
            workspace_diagnostics: Vec::new(),
            next_steps: Vec::new(),
        };
        let grouped = serialize_architecture_grouped_json_output(output, None)
            .expect("grouped architecture output should serialize");
        assert_eq!(grouped["kind"], "architecture-grouped");
        assert_eq!(grouped["schema_version"], ARCHITECTURE_SCHEMA_VERSION);
    }

    #[test]
    fn workspace_diagnostics_serialize_typed_kind_path_message() {
        let root = std::path::Path::new("/project");
        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(1),
            results: AnalysisResults::default(),
            config_fixable: false,
            meta: None,
            workspace_diagnostics: vec![WorkspaceDiagnostic::new(
                root,
                root.join("packages/legacy"),
                WorkspaceDiagnosticKind::UndeclaredWorkspace,
            )],
            next_steps: Vec::new(),
        });

        let value = serde_json::to_value(&output).expect("check output serializes");
        let diag = &value["workspace_diagnostics"][0];
        assert_eq!(diag["kind"], "undeclared-workspace");
        assert!(
            diag["path"]
                .as_str()
                .is_some_and(|path| path.contains("packages/legacy")),
            "path field is carried verbatim: {diag}"
        );
        assert!(
            diag["message"]
                .as_str()
                .is_some_and(|message| message.contains("packages/legacy")),
            "message is rendered from kind + path: {diag}"
        );
    }

    #[test]
    fn source_read_failure_workspace_diagnostic_serializes_error_payload() {
        let root = std::path::Path::new("/project");
        let output = build_check_output(CheckOutputInput {
            schema_version: 7,
            version: "0.0.0".to_string(),
            elapsed: Duration::from_millis(1),
            results: AnalysisResults::default(),
            config_fixable: false,
            meta: None,
            workspace_diagnostics: vec![WorkspaceDiagnostic::new(
                root,
                root.join("src/removed.ts"),
                WorkspaceDiagnosticKind::SourceReadFailure {
                    error: "No such file or directory".to_string(),
                },
            )],
            next_steps: Vec::new(),
        });

        let value = serde_json::to_value(&output).expect("check output serializes");
        let diagnostic = &value["workspace_diagnostics"][0];
        assert_eq!(diagnostic["kind"], "source-read-failure");
        assert_eq!(diagnostic["error"], "No such file or directory");
        assert!(
            diagnostic["message"]
                .as_str()
                .is_some_and(|message| message.contains("src/removed.ts"))
        );
    }

    fn suppress_comment(actions: &[IssueAction]) -> Option<&str> {
        actions.iter().find_map(|action| match action {
            IssueAction::SuppressLine(action) => Some(action.comment.as_str()),
            _ => None,
        })
    }
}