Skip to main content

fallow_types/
output_dead_code.rs

1//! Typed envelope wrappers for the simple 1:1 dead-code findings whose
2//! actions are entirely determined by the wrapper type (no per-instance
3//! discriminants beyond what the bare finding already exposes).
4//!
5//! Each wrapper flattens the bare finding via `#[serde(flatten)]` so the
6//! wire shape matches the previous `actions`-grafted output byte-for-byte.
7//! `actions` is populated at construction time via each wrapper's
8//! `with_actions` constructor and replaces the per-finding `inject_actions`
9//! post-pass in `crates/cli/src/report/json.rs`. `introduced` carries the optional audit
10//! breadcrumb that `crates/cli/src/audit.rs::annotate_issue_array` inserts
11//! into the JSON object via `map.insert`; the wrapper-level field stays
12//! `None` when serialized directly from Rust and is set by the audit pass
13//! only when the issue was introduced relative to the merge-base.
14//!
15//! All nine wrappers ship with `IssueAction` arrays today; they pay the
16//! `serde_json` dependency cost because `IssueAction` transitively
17//! references `AddToConfigValue::RuleObject(serde_json::Map<...>)`. The
18//! variants the wrappers actually emit (`Fix`, `SuppressLine`,
19//! `SuppressFile`, `AddToConfig`) are small, but reusing the existing enum
20//! keeps the wire-shape contract identical to the legacy post-pass.
21//!
22//! `introduced` is typed as `Option<AuditIntroduced>` (transparent newtype
23//! over `bool`) so the regenerated schema renders the field via
24//! `$ref: #/definitions/AuditIntroduced`, matching the reference the prior
25//! post-pass augmentation graft used. The audit pass continues to inject a
26//! bare bool via `map.insert("introduced", ...)`; serde reads it back into
27//! `AuditIntroduced` transparently. The field stays absent at the wire when
28//! `None` (`skip_serializing_if`).
29
30use serde::{Deserialize, Serialize};
31
32use crate::catalog_source::is_pnpm_catalog_source;
33use crate::envelope::AuditIntroduced;
34use crate::output::{
35    AddToConfigAction, AddToConfigKind, AddToConfigValue, FixAction, FixActionType,
36    IgnoreExportsRule, IssueAction, SuppressFileAction, SuppressFileKind, SuppressLineAction,
37    SuppressLineKind, SuppressLineScope,
38};
39pub use crate::results::AbsentComponentPropFinding;
40use crate::results::{
41    BoundaryCallViolation, BoundaryCoverageViolation, BoundaryViolation, CircularDependency,
42    DependencyOverrideSource, DeprecatedExportInUse, DevDependencyInProduction, DuplicateExport,
43    DuplicateExportAlias, DuplicatePropShape, DynamicSegmentNameConflict, EmptyCatalogGroup,
44    InvalidClientExport, MisconfiguredDependencyOverride, MisplacedDirective,
45    MixedClientServerBarrel, PackageCycle, PolicyViolation, PrivateTypeLeak, PropDrillingChain,
46    ReExportCycle, ReExportCycleKind, RouteCollision, TestOnlyDependency, ThinWrapper,
47    TypeOnlyDependency, UnlistedBinary, UnlistedDependency, UnproducedCatchTag, UnprovidedInject,
48    UnrenderedComponent, UnresolvedCatalogReference, UnresolvedImport, UnusedCatalogEntry,
49    UnusedComponentEmit, UnusedComponentInput, UnusedComponentOutput, UnusedComponentProp,
50    UnusedDependency, UnusedDependencyOverride, UnusedEffectLayer, UnusedExport, UnusedFile,
51    UnusedLoadDataKey, UnusedMember, UnusedServerAction, UnusedSvelteEvent, UnusedTaggedError,
52};
53use crate::semantic::{
54    SemanticCandidateDecision, SemanticCandidateDecisionKind, SemanticCompleteness,
55};
56
57/// Shared note for the `duplicate-exports` fix action. This const is the
58/// single source of truth: `crates/cli/src/report/shared.rs` aliases it for
59/// the human report.
60pub const NAMESPACE_BARREL_HINT: &str = "If every location is the sole `index.*` of its directory, this is likely an intentional namespace-barrel API. Prefer adding these files to `ignoreExports` over removing exports.";
61
62/// JSON Schema fragment URL for the `add-to-config` `ignoreExports` action's
63/// `value` payload. Pinned to the main branch so users browsing the action
64/// value can navigate directly to the rule shape.
65const IGNORE_EXPORTS_VALUE_SCHEMA: &str =
66    "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreExports";
67
68/// JSON Schema fragment URL for the `ignoreCatalogReferences` rule items
69/// referenced by `add-to-config` actions on `unresolved-catalog-references`.
70const IGNORE_CATALOG_REFERENCES_VALUE_SCHEMA: &str = "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreCatalogReferences/items";
71
72/// JSON Schema fragment URL for the `ignoreDependencyOverrides` rule items
73/// referenced by `add-to-config` actions on both the unused- and
74/// misconfigured-override findings.
75const IGNORE_DEPENDENCY_OVERRIDES_VALUE_SCHEMA: &str = "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreDependencyOverrides/items";
76
77pub(crate) fn manual_framework_fix(
78    kind: FixActionType,
79    description: &str,
80    note: &str,
81) -> IssueAction {
82    IssueAction::Fix(FixAction {
83        kind,
84        auto_fixable: false,
85        description: description.to_string(),
86        note: Some(note.to_string()),
87        available_in_catalogs: None,
88        suggested_target: None,
89    })
90}
91
92pub(crate) fn suppress_line(comment: &str) -> IssueAction {
93    IssueAction::SuppressLine(SuppressLineAction {
94        kind: SuppressLineKind::SuppressLine,
95        auto_fixable: false,
96        description: "Suppress with an inline comment above the line".to_string(),
97        comment: comment.to_string(),
98        scope: None,
99    })
100}
101
102/// A per-finding caveat on a dead-code verdict that a file this run never
103/// fully analyzed can distort.
104///
105/// Advisory provenance, in the same spirit as the fix path's
106/// `low_confidence_off_graph` / `low_confidence_unresolved_imports` skip
107/// reasons: a caveat NEVER withholds, reorders, downgrades, or re-severities
108/// the finding, and never changes an exit code. It records that the verdict
109/// was computed over an import graph fallow already knows is incomplete, so a
110/// reader who sees the finding also sees the caveat instead of having to
111/// notice a diagnostic at the other end of the envelope.
112///
113/// Deliberately NOT named `confidence`: `health --targets` already emits a
114/// `confidence` key holding an enum string, and a shared consumer helper that
115/// met both would see the same key change type. Emitted on every finding type
116/// that registers it: the reachability arrays (`unused_files[]`,
117/// `unused_exports[]`, `unused_types[]`), the member arrays
118/// (`unused_enum_members[]`, `unused_class_members[]`, `unused_store_members[]`),
119/// and the three dependency arrays. Sorted and deduplicated, absent from the
120/// wire when empty. The set is open in the same sense
121/// `workspace_diagnostics[].kind` is: treat an unrecognised value as "some
122/// caveat" rather than as an error.
123#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
124#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
125#[serde(rename_all = "kebab-case")]
126pub enum ReachabilityCaveat {
127    /// This finding's own file is one the run did not fully analyze, so the
128    /// export and import lists extracted from it may stop short of the real
129    /// ones. That reaches an `unused-file` verdict directly, because the
130    /// "is any export of this file referenced from a reachable module" test
131    /// reads exactly that truncated export list.
132    ///
133    /// Three workspace diagnostics put a file in this state: a partial parse
134    /// (`source-parse-degraded`), no parse (`source-nesting-too-deep`), or no
135    /// read (`source-read-failure`). The token names the consequence rather than
136    /// either cause, so a future kind that leaves a discovered file partially
137    /// extracted carries the same value.
138    ///
139    /// Dependency findings never carry this value: the file they name is a
140    /// `package.json`, not a parsed source module.
141    IncompleteFileAnalysis,
142    /// A module whose import list feeds this verdict was not analyzed, so the
143    /// import that would have credited this finding may never have been seen.
144    ///
145    /// The cause is any workspace diagnostic that leaves a source file's
146    /// imports unseen: a partial parse (`source-parse-degraded`), no parse
147    /// (`source-nesting-too-deep`), no read (`source-read-failure`), or a skip
148    /// by discovery before the read (`skipped-large-file`,
149    /// `skipped-minified-file`, `skipped-source-dotdir`). The token names the
150    /// class rather than any one cause.
151    ///
152    /// Which modules feed the verdict differs by array, and the caveat is
153    /// emitted only when a degraded module is actually one of them:
154    ///
155    /// - `unused_files[]`, `unused_exports[]`, and `unused_types[]` rest on
156    ///   reachability, so only a degraded module that is itself observed
157    ///   reachable can change the verdict. When every degraded module is
158    ///   unreachable the caveat is absent, and soundly: the FIRST missing edge
159    ///   on any entry-point path leaves from a module whose every predecessor
160    ///   edge was observed, so that module is observed reachable. A file the
161    ///   run never read has no module and no graph node, so its reachability
162    ///   is not observable at all and that narrowing cannot be applied: any
163    ///   skipped or unreadable source caveats every reachability verdict in
164    ///   the run.
165    /// - the member arrays (`unused_enum_members[]`, `unused_class_members[]`,
166    ///   `unused_store_members[]`) do not rest on reachability at all: member
167    ///   usage is collected by walking every module the run resolved,
168    ///   reachable or not, so this narrowing does not apply to them either.
169    ///   Same unnarrowed condition as the dependency arrays below, plus the
170    ///   per-finding value above when the member's own file is the one that
171    ///   was incompletely analyzed.
172    /// - the dependency arrays rest on whether ANY module in the project
173    ///   imports the package specifier, reachable or not, so any degraded
174    ///   parse anywhere can hide the import that would have credited the
175    ///   package. Reachability does not narrow that one.
176    ///
177    /// The limit, stated because an approximation presented as exact is worse
178    /// than nothing: this is a RUN-level condition, not proof that a degraded
179    /// module imports this path or package. An import the parser never saw
180    /// cannot be attributed to a target, so the link cannot be narrowed
181    /// further without re-reading the source. Read `workspace_diagnostics[]`
182    /// for which files degraded.
183    IncompleteImportGraph,
184}
185
186impl ReachabilityCaveat {
187    /// The wire token.
188    #[must_use]
189    pub const fn token(self) -> &'static str {
190        match self {
191            Self::IncompleteFileAnalysis => "incomplete-file-analysis",
192            Self::IncompleteImportGraph => "incomplete-import-graph",
193        }
194    }
195
196    /// A one-line explanation for human and agent-facing renderers.
197    ///
198    /// Neither sentence names a single cause. A degraded parse is only one of
199    /// the ways a file goes unread: it may also have been unreadable, or
200    /// skipped before it was ever opened (oversized, minified, in a dotdir).
201    /// Naming the parse case alone sent a reader whose run was degraded by the
202    /// size guard hunting for parse errors that do not exist, so both messages
203    /// point at `workspace_diagnostics[]`, which names the actual files.
204    #[must_use]
205    pub const fn message(self) -> &'static str {
206        match self {
207            Self::IncompleteFileAnalysis => {
208                "low: this file was not fully analyzed, so its extracted exports and imports may be incomplete; see workspace_diagnostics[]"
209            }
210            Self::IncompleteImportGraph => {
211                "low: a module this run did not fully read may hold an import that would credit this; see workspace_diagnostics[]"
212            }
213        }
214    }
215
216    /// A compact label for a one-line human renderer, where the full
217    /// [`Self::message`] would not fit next to the finding.
218    #[must_use]
219    pub const fn short_label(self) -> &'static str {
220        match self {
221            Self::IncompleteFileAnalysis => "incomplete file analysis",
222            Self::IncompleteImportGraph => "incomplete import graph",
223        }
224    }
225}
226
227/// The compact labels of `caveats`, joined for a one-line renderer, or `None`
228/// when there is nothing to say.
229#[must_use]
230pub fn caveat_labels(caveats: &[ReachabilityCaveat]) -> Option<String> {
231    if caveats.is_empty() {
232        return None;
233    }
234    let labels: Vec<&str> = caveats
235        .iter()
236        .map(|caveat| ReachabilityCaveat::short_label(*caveat))
237        .collect();
238    Some(labels.join(", "))
239}
240
241/// The compact parenthetical a one-line human renderer appends to a finding
242/// carrying `caveats`, or `None` when there is nothing to say. Shared by every
243/// dead-code section so the suffix reads the same everywhere.
244#[must_use]
245pub fn caveat_suffix(caveats: &[ReachabilityCaveat]) -> Option<String> {
246    caveat_labels(caveats).map(|labels| format!("{CAVEAT_SUFFIX_MARKER}{labels})"))
247}
248
249/// The opening of the parenthetical [`caveat_suffix`] renders. Public because
250/// one consumer can only see the rendered description: the CI review formats
251/// build their comments from CodeClimate issues, whose `description` is the
252/// only place the caveat survives (the CodeClimate wire is a published
253/// contract with no field for it). Recognising the marker is what lets those
254/// formats withhold a one-click mutation.
255pub const CAVEAT_SUFFIX_MARKER: &str = " (caveat: ";
256
257/// Whether a rendered finding description already carries a caveat
258/// parenthetical, for a surface holding the string rather than the typed
259/// finding.
260///
261/// Lives here, next to the renderer, so the producer and the recogniser cannot
262/// drift; `a_rendered_suffix_is_recognised_by_the_marker` pins the pair.
263#[must_use]
264pub fn description_carries_caveat(description: &str) -> bool {
265    description.contains(CAVEAT_SUFFIX_MARKER)
266}
267
268/// The compact label for one wire token, for a renderer that reads
269/// `reachability_caveats[]` back off a serialized envelope instead of holding
270/// the typed findings.
271///
272/// The value set is OPEN, exactly as the wire documentation says: a token this
273/// build does not recognise is still a caveat, so it is rendered as itself with
274/// its separators relaxed into spaces rather than dropped. Dropping it would
275/// turn a finding whose evidence is incomplete back into a confident one,
276/// which is the failure this whole mechanism exists to prevent.
277#[must_use]
278pub fn caveat_label_for_token(token: &str) -> String {
279    match token {
280        "incomplete-file-analysis" => {
281            ReachabilityCaveat::short_label(ReachabilityCaveat::IncompleteFileAnalysis).to_owned()
282        }
283        "incomplete-import-graph" => {
284            ReachabilityCaveat::short_label(ReachabilityCaveat::IncompleteImportGraph).to_owned()
285        }
286        other => other.replace('-', " "),
287    }
288}
289
290/// The joined compact labels for wire tokens, or `None` when there are none.
291/// The token-side twin of [`caveat_labels`], for renderers driven by a
292/// serialized envelope rather than by typed findings.
293#[must_use]
294pub fn caveat_labels_for_tokens<'a>(tokens: impl IntoIterator<Item = &'a str>) -> Option<String> {
295    let labels: Vec<String> = tokens.into_iter().map(caveat_label_for_token).collect();
296    if labels.is_empty() {
297        return None;
298    }
299    Some(labels.join(", "))
300}
301
302/// The token-side twin of [`caveat_suffix`], so an envelope-driven renderer
303/// appends the same parenthetical as a findings-driven one.
304#[must_use]
305pub fn caveat_suffix_for_tokens<'a>(tokens: impl IntoIterator<Item = &'a str>) -> Option<String> {
306    caveat_labels_for_tokens(tokens).map(|labels| format!("{CAVEAT_SUFFIX_MARKER}{labels})"))
307}
308
309/// The note every mutating action carries once [`MutationEvidence`] withholds
310/// it. One string, so the CLI action array, the LSP diagnostic, and the MCP
311/// tool contract all say the same thing about the same finding.
312pub const INCOMPLETE_EVIDENCE_NOTE: &str = "Evidence is incomplete: a file this run did not fully analyze may hold the reference that \
313     credits this finding, so this mutation is not applied automatically. Resolve the files named \
314     in workspace_diagnostics[] and re-run, or confirm and remove it by hand.";
315
316/// The one question every mutation surface asks before it offers, plans, or
317/// performs a dead-code finding's removal.
318///
319/// A finding whose reachability verdict rests on a file the run never fully
320/// read is still REPORTED, always: a caveat withholds no finding, changes no
321/// severity, and moves no exit code. What it withholds is the automation. The
322/// predicate lives here, next to the findings, rather than in any one consumer,
323/// because it was re-derived per surface three times and a fourth door opened
324/// every time: `fallow fix`, the LSP quick fix, and the `auto_fixable` flag an
325/// agent plans against each answered it differently. Every one of those now
326/// calls [`Self::may_auto_apply_mutation`], so a sixth finding type or a fourth
327/// mutation surface cannot silently opt out.
328///
329/// Implemented only by the findings that can carry a caveat. A finding type
330/// that exposes an auto-fixable mutation and does NOT implement this trait is
331/// the bug this trait exists to make visible; `every_auto_fixable_dead_code_
332/// mutation_is_gated` in this module's tests pins that.
333pub trait MutationEvidence {
334    /// The advisory caveats recorded on the reachability verdict behind this
335    /// finding. Empty when the run analyzed every file it discovered.
336    fn reachability_caveats(&self) -> &[ReachabilityCaveat];
337
338    /// Whether this finding's mutation may be applied without a human first
339    /// being told the evidence is incomplete. THE gate: never re-derive it,
340    /// never widen it per surface.
341    fn may_auto_apply_mutation(&self) -> bool {
342        self.reachability_caveats().is_empty()
343    }
344}
345
346/// Record a run's caveats on a finding, enforcing [`MutationEvidence`] on its
347/// typed `actions` in the same step.
348///
349/// Separate from [`MutationEvidence`] so a read-only consumer (the fixer, the
350/// LSP, a renderer) depends only on the question and never on the answer's
351/// setter. `annotate` in the analysis layer is the single writer.
352pub trait CaveatedFinding: MutationEvidence {
353    /// Store `caveats` and downgrade every mutating action the gate now
354    /// withholds. The field itself stays `pub` (a renderer test builds an
355    /// already-caveated fixture directly, without running the annotation
356    /// pass); every non-test writer goes through this setter instead of the
357    /// field so the downgrade travels with the write.
358    fn set_reachability_caveats(&mut self, caveats: Vec<ReachabilityCaveat>);
359}
360
361/// Downgrade every `Fix` action in `actions` when `caveats` is non-empty, so
362/// the `auto_fixable` flag an agent plans against matches what `fallow fix`
363/// will actually do. Only ever downgrades: a surface that has already decided
364/// a mutation is unsafe for its own reasons keeps that decision.
365fn withhold_caveated_mutations(actions: &mut [IssueAction], caveats: &[ReachabilityCaveat]) {
366    if caveats.is_empty() {
367        return;
368    }
369    for action in actions {
370        let IssueAction::Fix(fix) = action else {
371            continue;
372        };
373        fix.auto_fixable = false;
374        fix.note = Some(match fix.note.take() {
375            Some(existing) => format!("{existing}. {INCOMPLETE_EVIDENCE_NOTE}"),
376            None => INCOMPLETE_EVIDENCE_NOTE.to_string(),
377        });
378    }
379}
380
381/// Implement the gate for a finding wrapper carrying a `reachability_caveats`
382/// field alongside a typed `actions` array. A new caveated finding type adds
383/// one line here rather than a new per-surface branch.
384macro_rules! impl_caveated_finding {
385    ($($finding:ty),+ $(,)?) => {
386        $(
387            impl MutationEvidence for $finding {
388                fn reachability_caveats(&self) -> &[ReachabilityCaveat] {
389                    &self.reachability_caveats
390                }
391            }
392
393            impl CaveatedFinding for $finding {
394                fn set_reachability_caveats(&mut self, caveats: Vec<ReachabilityCaveat>) {
395                    withhold_caveated_mutations(&mut self.actions, &caveats);
396                    self.reachability_caveats = caveats;
397                }
398            }
399        )+
400    };
401}
402
403/// Wire-shape envelope for an [`UnusedFile`] finding. The bare finding
404/// flattens in via `#[serde(flatten)]`, with a typed `actions` array
405/// populated at construction time and the audit-pass `introduced` flag
406/// attached as an optional sibling.
407#[derive(Debug, Clone, Serialize, Deserialize)]
408#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
409pub struct UnusedFileFinding {
410    /// The underlying dead-code entry.
411    #[serde(flatten)]
412    pub file: UnusedFile,
413    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
414    /// `~<k>` suffix when several findings of one type share an identity.
415    /// Line and column are not inputs, so the id survives line shifts,
416    /// reformats and reorders. A rename of the file or the symbol gives a
417    /// new id. Absent in output from older versions.
418    #[serde(default, skip_serializing_if = "Option::is_none")]
419    pub finding_id: Option<String>,
420    /// Suggested next steps: a `delete-file` primary and a `suppress-file`
421    /// secondary. Always emitted (possibly empty for forward-compat).
422    pub actions: Vec<IssueAction>,
423    /// Set by the audit pass when this finding is introduced relative to
424    /// the merge-base. `None` when serialized directly from Rust.
425    #[serde(default, skip_serializing_if = "Option::is_none")]
426    pub introduced: Option<AuditIntroduced>,
427    /// Gate severity of this finding after `rules` and `overrides[].rules`
428    /// resolve for its path. CI formats read it for the annotation, SARIF
429    /// and CodeClimate level. Absent in output from older versions. Not
430    /// part of the finding identity, baseline keys or fingerprints.
431    #[serde(
432        default,
433        skip_serializing_if = "Option::is_none",
434        deserialize_with = "deserialize_effective_severity"
435    )]
436    pub effective_severity: Option<EffectiveSeverity>,
437    /// Advisory caveats on the reachability verdict behind this finding.
438    /// Sorted, deduplicated, and omitted from the wire when empty, so a run
439    /// that analyzed every discovered file is byte-identical. Never gates the
440    /// finding or the `delete-file` action, though `fallow fix` does withhold
441    /// the removal of a caveated finding as low confidence.
442    #[serde(default, skip_serializing_if = "Vec::is_empty")]
443    pub reachability_caveats: Vec<ReachabilityCaveat>,
444}
445
446impl UnusedFileFinding {
447    /// Build the wrapper from a raw [`UnusedFile`], computing the typed
448    /// `actions` array inline. `introduced` stays `None` and is set later
449    /// by `annotate_dead_code_json` if the audit pass runs.
450    #[must_use]
451    pub fn with_actions(file: UnusedFile) -> Self {
452        let actions = vec![
453            IssueAction::Fix(FixAction {
454                kind: FixActionType::DeleteFile,
455                auto_fixable: false,
456                description: "Delete this file".to_string(),
457                note: Some(
458                    "File deletion may remove runtime functionality not visible to static analysis"
459                        .to_string(),
460                ),
461                available_in_catalogs: None,
462                suggested_target: None,
463            }),
464            IssueAction::SuppressFile(SuppressFileAction {
465                kind: SuppressFileKind::SuppressFile,
466                auto_fixable: false,
467                description: "Suppress with a file-level comment at the top of the file"
468                    .to_string(),
469                comment: "// fallow-ignore-file unused-file".to_string(),
470            }),
471        ];
472        Self {
473            finding_id: None,
474            file,
475            actions,
476            introduced: None,
477            effective_severity: None,
478            reachability_caveats: Vec::new(),
479        }
480    }
481}
482
483/// Wire-shape envelope for a [`PrivateTypeLeak`] finding. Mirrors
484/// [`UnusedFileFinding`]: flattens the bare finding and carries a typed
485/// `actions` array (`export-type` primary plus `suppress-line` secondary).
486#[derive(Debug, Clone, Serialize, Deserialize)]
487#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
488pub struct PrivateTypeLeakFinding {
489    /// The underlying dead-code entry.
490    #[serde(flatten)]
491    pub leak: PrivateTypeLeak,
492    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
493    /// `~<k>` suffix when several findings of one type share an identity.
494    /// Line and column are not inputs, so the id survives line shifts,
495    /// reformats and reorders. A rename of the file or the symbol gives a
496    /// new id. Absent in output from older versions.
497    #[serde(default, skip_serializing_if = "Option::is_none")]
498    pub finding_id: Option<String>,
499    /// Suggested next steps. Always emitted (possibly empty for
500    /// forward-compat).
501    pub actions: Vec<IssueAction>,
502    /// Set by the audit pass when this finding is introduced relative to
503    /// the merge-base.
504    #[serde(default, skip_serializing_if = "Option::is_none")]
505    pub introduced: Option<AuditIntroduced>,
506    /// Gate severity of this finding after `rules` and `overrides[].rules`
507    /// resolve for its path. CI formats read it for the annotation, SARIF
508    /// and CodeClimate level. Absent in output from older versions. Not
509    /// part of the finding identity, baseline keys or fingerprints.
510    #[serde(
511        default,
512        skip_serializing_if = "Option::is_none",
513        deserialize_with = "deserialize_effective_severity"
514    )]
515    pub effective_severity: Option<EffectiveSeverity>,
516}
517
518impl PrivateTypeLeakFinding {
519    /// Build the wrapper from a raw [`PrivateTypeLeak`].
520    #[must_use]
521    pub fn with_actions(leak: PrivateTypeLeak) -> Self {
522        let actions = vec![
523            IssueAction::Fix(FixAction {
524                kind: FixActionType::ExportType,
525                auto_fixable: false,
526                description: "Export the referenced private type by name".to_string(),
527                note: Some(
528                    "Keep the type exported while it is part of a public signature".to_string(),
529                ),
530                available_in_catalogs: None,
531                suggested_target: None,
532            }),
533            IssueAction::SuppressLine(SuppressLineAction {
534                kind: SuppressLineKind::SuppressLine,
535                auto_fixable: false,
536                description: "Suppress with an inline comment above the line".to_string(),
537                comment: "// fallow-ignore-next-line private-type-leak".to_string(),
538                scope: None,
539            }),
540        ];
541        Self {
542            finding_id: None,
543            leak,
544            actions,
545            introduced: None,
546            effective_severity: None,
547        }
548    }
549}
550
551/// Wire-shape envelope for a [`DeprecatedExportInUse`] finding. Carries a
552/// manual `migrate-deprecated-export` primary action plus a `suppress-line`
553/// secondary. Never auto-fixable: fallow does not rewrite consumers.
554#[derive(Debug, Clone, Serialize, Deserialize)]
555#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
556pub struct DeprecatedExportInUseFinding {
557    /// The underlying dead-code entry.
558    #[serde(flatten)]
559    pub export: DeprecatedExportInUse,
560    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
561    /// `~<k>` suffix when several findings of one type share an identity.
562    /// Line and column are not inputs, so the id survives line shifts,
563    /// reformats and reorders. A rename of the file or the symbol gives a
564    /// new id. Absent in output from older versions.
565    #[serde(default, skip_serializing_if = "Option::is_none")]
566    pub finding_id: Option<String>,
567    /// Suggested next steps. Always emitted (possibly empty for
568    /// forward-compat).
569    pub actions: Vec<IssueAction>,
570    /// Set by the audit pass when this finding is introduced relative to
571    /// the merge-base.
572    #[serde(default, skip_serializing_if = "Option::is_none")]
573    pub introduced: Option<AuditIntroduced>,
574    /// Gate severity of this finding after `rules` and `overrides[].rules`
575    /// resolve for its path. CI formats read it for the annotation, SARIF
576    /// and CodeClimate level. Absent in output from older versions. Not
577    /// part of the finding identity, baseline keys or fingerprints.
578    #[serde(
579        default,
580        skip_serializing_if = "Option::is_none",
581        deserialize_with = "deserialize_effective_severity"
582    )]
583    pub effective_severity: Option<EffectiveSeverity>,
584}
585
586impl DeprecatedExportInUseFinding {
587    /// Build the wrapper from a raw [`DeprecatedExportInUse`].
588    #[must_use]
589    pub fn with_actions(export: DeprecatedExportInUse) -> Self {
590        let trace_hint = format!(
591            "For the full consumer list, run `fallow dead-code --trace <path>:{}` with the `path` of this finding.",
592            export.export_name
593        );
594        let note = if export.public_api {
595            format!(
596                "This export is public API. External consumers are not visible, so do not remove it on this evidence alone. {trace_hint}"
597            )
598        } else {
599            format!(
600                "Move each consumer to the replacement that the deprecation message names, then remove the export. {trace_hint}"
601            )
602        };
603        let actions = vec![
604            IssueAction::Fix(FixAction {
605                kind: FixActionType::MigrateDeprecatedExport,
606                auto_fixable: false,
607                description: "Move the consumers off the deprecated export".to_string(),
608                note: Some(note),
609                available_in_catalogs: None,
610                suggested_target: None,
611            }),
612            suppress_line("// fallow-ignore-next-line deprecated-export-in-use"),
613        ];
614        Self {
615            finding_id: None,
616            export,
617            actions,
618            introduced: None,
619            effective_severity: None,
620        }
621    }
622}
623
624/// Wire-shape envelope for an [`UnresolvedImport`] finding. Mirrors
625/// [`UnusedFileFinding`]: flattens the bare finding and carries a typed
626/// `actions` array (`resolve-import` primary plus config and inline
627/// suppression actions).
628#[derive(Debug, Clone, Serialize, Deserialize)]
629#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
630pub struct UnresolvedImportFinding {
631    /// The underlying dead-code entry.
632    #[serde(flatten)]
633    pub import: UnresolvedImport,
634    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
635    /// `~<k>` suffix when several findings of one type share an identity.
636    /// Line and column are not inputs, so the id survives line shifts,
637    /// reformats and reorders. A rename of the file or the symbol gives a
638    /// new id. Absent in output from older versions.
639    #[serde(default, skip_serializing_if = "Option::is_none")]
640    pub finding_id: Option<String>,
641    /// Suggested next steps. Always emitted (possibly empty for
642    /// forward-compat).
643    pub actions: Vec<IssueAction>,
644    /// Set by the audit pass when this finding is introduced relative to
645    /// the merge-base.
646    #[serde(default, skip_serializing_if = "Option::is_none")]
647    pub introduced: Option<AuditIntroduced>,
648    /// Gate severity of this finding after `rules` and `overrides[].rules`
649    /// resolve for its path. CI formats read it for the annotation, SARIF
650    /// and CodeClimate level. Absent in output from older versions. Not
651    /// part of the finding identity, baseline keys or fingerprints.
652    #[serde(
653        default,
654        skip_serializing_if = "Option::is_none",
655        deserialize_with = "deserialize_effective_severity"
656    )]
657    pub effective_severity: Option<EffectiveSeverity>,
658}
659
660impl UnresolvedImportFinding {
661    /// Build the wrapper from a raw [`UnresolvedImport`].
662    #[must_use]
663    pub fn with_actions(import: UnresolvedImport) -> Self {
664        let actions = vec![
665            IssueAction::Fix(FixAction {
666                kind: FixActionType::ResolveImport,
667                auto_fixable: false,
668                description: "Fix the import specifier or install the missing module".to_string(),
669                note: Some(
670                    "Verify the module path and check tsconfig paths configuration".to_string(),
671                ),
672                available_in_catalogs: None,
673                suggested_target: None,
674            }),
675            IssueAction::AddToConfig(AddToConfigAction {
676                kind: AddToConfigKind::AddToConfig,
677                auto_fixable: false,
678                description: format!(
679                    "Add \"{}\" to ignoreUnresolvedImports in fallow config",
680                    import.specifier
681                ),
682                config_key: "ignoreUnresolvedImports".to_string(),
683                value: AddToConfigValue::Scalar(import.specifier.clone()),
684                value_schema: Some(
685                    "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreUnresolvedImports/items"
686                        .to_string(),
687                ),
688            }),
689            IssueAction::SuppressLine(SuppressLineAction {
690                kind: SuppressLineKind::SuppressLine,
691                auto_fixable: false,
692                description: "Suppress with an inline comment above the line".to_string(),
693                comment: "// fallow-ignore-next-line unresolved-import".to_string(),
694                scope: None,
695            }),
696        ];
697        Self {
698            finding_id: None,
699            import,
700            actions,
701            introduced: None,
702            effective_severity: None,
703        }
704    }
705}
706
707/// Wire-shape envelope for a [`CircularDependency`] finding. Mirrors
708/// [`UnusedFileFinding`]: flattens the bare finding and carries a typed
709/// `actions` array (`refactor-cycle` primary plus `suppress-line`
710/// secondary).
711#[derive(Debug, Clone, Serialize, Deserialize)]
712#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
713pub struct CircularDependencyFinding {
714    /// The underlying dead-code entry.
715    #[serde(flatten)]
716    pub cycle: CircularDependency,
717    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
718    /// `~<k>` suffix when several findings of one type share an identity.
719    /// Line and column are not inputs, so the id survives line shifts,
720    /// reformats and reorders. A rename of the file or the symbol gives a
721    /// new id. Absent in output from older versions.
722    #[serde(default, skip_serializing_if = "Option::is_none")]
723    pub finding_id: Option<String>,
724    /// Suggested next steps. Always emitted (possibly empty for
725    /// forward-compat).
726    pub actions: Vec<IssueAction>,
727    /// Set by the audit pass when this finding is introduced relative to
728    /// the merge-base.
729    #[serde(default, skip_serializing_if = "Option::is_none")]
730    pub introduced: Option<AuditIntroduced>,
731    /// Gate severity of this finding after `rules` and `overrides[].rules`
732    /// resolve for its path. CI formats read it for the annotation, SARIF
733    /// and CodeClimate level. Absent in output from older versions. Not
734    /// part of the finding identity, baseline keys or fingerprints.
735    #[serde(
736        default,
737        skip_serializing_if = "Option::is_none",
738        deserialize_with = "deserialize_effective_severity"
739    )]
740    pub effective_severity: Option<EffectiveSeverity>,
741}
742
743impl CircularDependencyFinding {
744    /// Build the wrapper from a raw [`CircularDependency`].
745    #[must_use]
746    pub fn with_actions(cycle: CircularDependency) -> Self {
747        let actions = vec![
748            IssueAction::Fix(FixAction {
749                kind: FixActionType::RefactorCycle,
750                auto_fixable: false,
751                description: "Extract shared logic into a separate module to break the cycle"
752                    .to_string(),
753                note: Some(
754                    "Circular imports can cause initialization issues and make code harder to reason about"
755                        .to_string(),
756                ),
757                available_in_catalogs: None,
758                suggested_target: None,
759            }),
760            IssueAction::SuppressLine(SuppressLineAction {
761                kind: SuppressLineKind::SuppressLine,
762                auto_fixable: false,
763                description: "Suppress with an inline comment above the line".to_string(),
764                comment: "// fallow-ignore-next-line circular-dependency".to_string(),
765                scope: None,
766            }),
767        ];
768        Self {
769            finding_id: None,
770            cycle,
771            actions,
772            introduced: None,
773            effective_severity: None,
774        }
775    }
776}
777
778/// Wire-shape envelope for a [`ReExportCycle`] finding. Mirrors
779/// [`CircularDependencyFinding`]: flattens the bare finding and carries a
780/// typed `actions` array (`refactor-re-export-cycle` informational primary
781/// plus `suppress-file` secondary; cycles are file-scoped so a single
782/// file-level suppression on the alphabetically-first member breaks the
783/// cycle, and no `// fallow-ignore-next-line` form makes sense because the
784/// diagnostic is anchored at line 1 col 0 of each member).
785#[derive(Debug, Clone, Serialize, Deserialize)]
786#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
787pub struct ReExportCycleFinding {
788    /// The underlying dead-code entry.
789    #[serde(flatten)]
790    pub cycle: ReExportCycle,
791    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
792    /// `~<k>` suffix when several findings of one type share an identity.
793    /// Line and column are not inputs, so the id survives line shifts,
794    /// reformats and reorders. A rename of the file or the symbol gives a
795    /// new id. Absent in output from older versions.
796    #[serde(default, skip_serializing_if = "Option::is_none")]
797    pub finding_id: Option<String>,
798    /// Suggested next steps. Always emitted (possibly empty for
799    /// forward-compat).
800    pub actions: Vec<IssueAction>,
801    /// Set by the audit pass when this finding is introduced relative to
802    /// the merge-base.
803    #[serde(default, skip_serializing_if = "Option::is_none")]
804    pub introduced: Option<AuditIntroduced>,
805    /// Gate severity of this finding after `rules` and `overrides[].rules`
806    /// resolve for its path. CI formats read it for the annotation, SARIF
807    /// and CodeClimate level. Absent in output from older versions. Not
808    /// part of the finding identity, baseline keys or fingerprints.
809    #[serde(
810        default,
811        skip_serializing_if = "Option::is_none",
812        deserialize_with = "deserialize_effective_severity"
813    )]
814    pub effective_severity: Option<EffectiveSeverity>,
815}
816
817impl ReExportCycleFinding {
818    /// Build the wrapper from a raw [`ReExportCycle`].
819    ///
820    /// The `SuppressFile` action targets the alphabetically-first member
821    /// (`cycle.files[0]`; the `files` Vec is already sorted at graph layer);
822    /// for multi-node cycles the description names the other members so
823    /// consumers see context for why one file-level suppression suffices.
824    #[must_use]
825    pub fn with_actions(cycle: ReExportCycle) -> Self {
826        // The description is a path-free hint about the suppression's
827        // structural effect; the cycle's member list already ships in the
828        // sibling `files` field, so consumers can correlate without
829        // re-reading the description (and absolute paths cannot leak in
830        // here, which the wrapper has no root-prefix context to strip).
831        let suppress_description = match cycle.kind {
832            ReExportCycleKind::SelfLoop => {
833                "Suppress with a file-level comment at the top of this file. \
834                 The cycle is a self-loop, so the suppression covers the entire finding."
835                    .to_string()
836            }
837            ReExportCycleKind::MultiNode => {
838                "Suppress with a file-level comment at the top of this file. \
839                 One suppression on any member breaks the cycle for every member \
840                 (see the sibling `files` array)."
841                    .to_string()
842            }
843        };
844        let actions = vec![
845            IssueAction::Fix(FixAction {
846                kind: FixActionType::RefactorReExportCycle,
847                auto_fixable: false,
848                description: "Remove one `export * from` (or `export { ... } from`) \
849                              statement on any one member to break the cycle"
850                    .to_string(),
851                note: Some(
852                    "Re-export cycles are structurally a no-op: chain propagation through \
853                     the loop never reaches a terminating module, so imports from any member \
854                     may silently come up empty."
855                        .to_string(),
856                ),
857                available_in_catalogs: None,
858                suggested_target: None,
859            }),
860            IssueAction::SuppressFile(SuppressFileAction {
861                kind: SuppressFileKind::SuppressFile,
862                auto_fixable: false,
863                description: suppress_description,
864                comment: "// fallow-ignore-file re-export-cycle".to_string(),
865            }),
866        ];
867        Self {
868            finding_id: None,
869            cycle,
870            actions,
871            introduced: None,
872            effective_severity: None,
873        }
874    }
875}
876
877/// Wire-shape envelope for a [`PackageCycle`] finding. Mirrors
878/// [`CircularDependencyFinding`]: flattens the bare finding and carries a
879/// typed `actions` array (`refactor-cycle` primary plus `suppress-line`
880/// secondary).
881#[derive(Debug, Clone, Serialize, Deserialize)]
882#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
883pub struct PackageCycleFinding {
884    /// The underlying dead-code entry.
885    #[serde(flatten)]
886    pub cycle: PackageCycle,
887    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
888    /// `~<k>` suffix when several findings of one type share an identity.
889    /// Line and column are not inputs, so the id survives line shifts,
890    /// reformats and reorders. A rename of the file or the symbol gives a
891    /// new id. Absent in output from older versions.
892    #[serde(default, skip_serializing_if = "Option::is_none")]
893    pub finding_id: Option<String>,
894    /// Suggested next steps. Always emitted (possibly empty for
895    /// forward-compat).
896    pub actions: Vec<IssueAction>,
897    /// Set by the audit pass when this finding is introduced relative to
898    /// the merge-base.
899    #[serde(default, skip_serializing_if = "Option::is_none")]
900    pub introduced: Option<AuditIntroduced>,
901    /// Gate severity of this finding after `rules` and `overrides[].rules`
902    /// resolve for its path. CI formats read it for the annotation, SARIF
903    /// and CodeClimate level. Absent in output from older versions. Not
904    /// part of the finding identity, baseline keys or fingerprints.
905    #[serde(
906        default,
907        skip_serializing_if = "Option::is_none",
908        deserialize_with = "deserialize_effective_severity"
909    )]
910    pub effective_severity: Option<EffectiveSeverity>,
911}
912
913impl PackageCycleFinding {
914    /// Build the wrapper from a raw [`PackageCycle`].
915    #[must_use]
916    pub fn with_actions(cycle: PackageCycle) -> Self {
917        let actions = vec![
918            IssueAction::Fix(FixAction {
919                kind: FixActionType::RefactorCycle,
920                auto_fixable: false,
921                description: "Remove the imports on one hop of the cycle, for example by \
922                              moving the shared code to a package that both packages import"
923                    .to_string(),
924                note: Some(
925                    "Packages that import each other cannot be built in dependency order"
926                        .to_string(),
927                ),
928                available_in_catalogs: None,
929                suggested_target: None,
930            }),
931            IssueAction::SuppressLine(SuppressLineAction {
932                kind: SuppressLineKind::SuppressLine,
933                auto_fixable: false,
934                description: "Suppress with an inline comment above the import. The cycle \
935                              is gone when every import on one hop is suppressed"
936                    .to_string(),
937                comment: "// fallow-ignore-next-line package-cycle".to_string(),
938                scope: None,
939            }),
940        ];
941        Self {
942            cycle,
943            finding_id: None,
944            actions,
945            introduced: None,
946            effective_severity: None,
947        }
948    }
949}
950
951/// Wire-shape envelope for a [`BoundaryViolation`] finding. Mirrors
952/// [`UnusedFileFinding`]: flattens the bare finding and carries a typed
953/// `actions` array (`refactor-boundary` primary plus `suppress-line`
954/// secondary).
955#[derive(Debug, Clone, Serialize, Deserialize)]
956#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
957pub struct BoundaryViolationFinding {
958    /// The underlying dead-code entry.
959    #[serde(flatten)]
960    pub violation: BoundaryViolation,
961    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
962    /// `~<k>` suffix when several findings of one type share an identity.
963    /// Line and column are not inputs, so the id survives line shifts,
964    /// reformats and reorders. A rename of the file or the symbol gives a
965    /// new id. Absent in output from older versions.
966    #[serde(default, skip_serializing_if = "Option::is_none")]
967    pub finding_id: Option<String>,
968    /// Suggested next steps. Always emitted (possibly empty for
969    /// forward-compat).
970    pub actions: Vec<IssueAction>,
971    /// Set by the audit pass when this finding is introduced relative to
972    /// the merge-base.
973    #[serde(default, skip_serializing_if = "Option::is_none")]
974    pub introduced: Option<AuditIntroduced>,
975    /// Gate severity of this finding after `rules` and `overrides[].rules`
976    /// resolve for its path. CI formats read it for the annotation, SARIF
977    /// and CodeClimate level. Absent in output from older versions. Not
978    /// part of the finding identity, baseline keys or fingerprints.
979    #[serde(
980        default,
981        skip_serializing_if = "Option::is_none",
982        deserialize_with = "deserialize_effective_severity"
983    )]
984    pub effective_severity: Option<EffectiveSeverity>,
985}
986
987impl BoundaryViolationFinding {
988    /// Build the wrapper from a raw [`BoundaryViolation`].
989    #[must_use]
990    pub fn with_actions(violation: BoundaryViolation) -> Self {
991        let actions = vec![
992            IssueAction::Fix(FixAction {
993                kind: FixActionType::RefactorBoundary,
994                auto_fixable: false,
995                description: "Move the import through an allowed zone or restructure the dependency"
996                    .to_string(),
997                note: Some(
998                    "This import crosses an architecture boundary that is not permitted by the configured rules"
999                        .to_string(),
1000                ),
1001                available_in_catalogs: None,
1002                suggested_target: None,
1003            }),
1004            IssueAction::SuppressLine(SuppressLineAction {
1005                kind: SuppressLineKind::SuppressLine,
1006                auto_fixable: false,
1007                description: "Suppress with an inline comment above the line".to_string(),
1008                comment: "// fallow-ignore-next-line boundary-violation".to_string(),
1009                scope: None,
1010            }),
1011        ];
1012        Self {
1013            finding_id: None,
1014            violation,
1015            actions,
1016            introduced: None,
1017            effective_severity: None,
1018        }
1019    }
1020}
1021
1022/// Wire-shape envelope for a [`BoundaryCoverageViolation`] finding. Carries
1023/// actions for assigning the file to a zone or explicitly allowing it to stay
1024/// unmatched.
1025#[derive(Debug, Clone, Serialize, Deserialize)]
1026#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1027pub struct BoundaryCoverageViolationFinding {
1028    /// The underlying coverage entry.
1029    #[serde(flatten)]
1030    pub violation: BoundaryCoverageViolation,
1031    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1032    /// `~<k>` suffix when several findings of one type share an identity.
1033    /// Line and column are not inputs, so the id survives line shifts,
1034    /// reformats and reorders. A rename of the file or the symbol gives a
1035    /// new id. Absent in output from older versions.
1036    #[serde(default, skip_serializing_if = "Option::is_none")]
1037    pub finding_id: Option<String>,
1038    /// Suggested next steps.
1039    pub actions: Vec<IssueAction>,
1040    /// Set by the audit pass when this finding is introduced relative to
1041    /// the merge-base.
1042    #[serde(default, skip_serializing_if = "Option::is_none")]
1043    pub introduced: Option<AuditIntroduced>,
1044    /// Gate severity of this finding after `rules` and `overrides[].rules`
1045    /// resolve for its path. CI formats read it for the annotation, SARIF
1046    /// and CodeClimate level. Absent in output from older versions. Not
1047    /// part of the finding identity, baseline keys or fingerprints.
1048    #[serde(
1049        default,
1050        skip_serializing_if = "Option::is_none",
1051        deserialize_with = "deserialize_effective_severity"
1052    )]
1053    pub effective_severity: Option<EffectiveSeverity>,
1054}
1055
1056impl BoundaryCoverageViolationFinding {
1057    /// Build the wrapper from a raw [`BoundaryCoverageViolation`].
1058    #[must_use]
1059    pub fn with_actions(violation: BoundaryCoverageViolation) -> Self {
1060        let path = violation.path.to_string_lossy().replace('\\', "/");
1061        let actions = vec![
1062            IssueAction::Fix(FixAction {
1063                kind: FixActionType::RefactorBoundary,
1064                auto_fixable: false,
1065                description: "Add this file to a boundary zone pattern or move it under an existing zone"
1066                    .to_string(),
1067                note: Some(
1068                    "Boundary coverage is enabled, so every analyzed source file must match a zone unless allow-listed"
1069                        .to_string(),
1070                ),
1071                available_in_catalogs: None,
1072                suggested_target: None,
1073            }),
1074            IssueAction::AddToConfig(AddToConfigAction {
1075                kind: AddToConfigKind::AddToConfig,
1076                auto_fixable: false,
1077                description: format!(
1078                    "Add \"{path}\" to boundaries.coverage.allowUnmatched in fallow config"
1079                ),
1080                config_key: "boundaries.coverage.allowUnmatched".to_string(),
1081                value: AddToConfigValue::Scalar(path),
1082                value_schema: Some(
1083                    "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/boundaries/properties/coverage/properties/allowUnmatched/items"
1084                        .to_string(),
1085                ),
1086            }),
1087            IssueAction::SuppressFile(SuppressFileAction {
1088                kind: SuppressFileKind::SuppressFile,
1089                auto_fixable: false,
1090                description: "Suppress with a file-level comment at the top of the file"
1091                    .to_string(),
1092                comment: "// fallow-ignore-file boundary-violation".to_string(),
1093            }),
1094        ];
1095        Self {
1096            finding_id: None,
1097            violation,
1098            actions,
1099            introduced: None,
1100            effective_severity: None,
1101        }
1102    }
1103}
1104
1105/// Wire-shape envelope for a [`BoundaryCallViolation`] finding. Carries
1106/// actions for refactoring the forbidden call out of the zone or suppressing
1107/// it with the shared `boundary-violation` token.
1108#[derive(Debug, Clone, Serialize, Deserialize)]
1109#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1110pub struct BoundaryCallViolationFinding {
1111    /// The underlying forbidden-call entry.
1112    #[serde(flatten)]
1113    pub violation: BoundaryCallViolation,
1114    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1115    /// `~<k>` suffix when several findings of one type share an identity.
1116    /// Line and column are not inputs, so the id survives line shifts,
1117    /// reformats and reorders. A rename of the file or the symbol gives a
1118    /// new id. Absent in output from older versions.
1119    #[serde(default, skip_serializing_if = "Option::is_none")]
1120    pub finding_id: Option<String>,
1121    /// Suggested next steps.
1122    pub actions: Vec<IssueAction>,
1123    /// Set by the audit pass when this finding is introduced relative to
1124    /// the merge-base.
1125    #[serde(default, skip_serializing_if = "Option::is_none")]
1126    pub introduced: Option<AuditIntroduced>,
1127    /// Gate severity of this finding after `rules` and `overrides[].rules`
1128    /// resolve for its path. CI formats read it for the annotation, SARIF
1129    /// and CodeClimate level. Absent in output from older versions. Not
1130    /// part of the finding identity, baseline keys or fingerprints.
1131    #[serde(
1132        default,
1133        skip_serializing_if = "Option::is_none",
1134        deserialize_with = "deserialize_effective_severity"
1135    )]
1136    pub effective_severity: Option<EffectiveSeverity>,
1137}
1138
1139impl BoundaryCallViolationFinding {
1140    /// Build the wrapper from a raw [`BoundaryCallViolation`].
1141    #[must_use]
1142    pub fn with_actions(violation: BoundaryCallViolation) -> Self {
1143        let actions = vec![
1144            IssueAction::Fix(FixAction {
1145                kind: FixActionType::RefactorBoundary,
1146                auto_fixable: false,
1147                description: format!(
1148                    "Move the `{}` call out of zone '{}' or behind an allowed abstraction",
1149                    violation.callee, violation.zone,
1150                ),
1151                note: Some(format!(
1152                    "`boundaries.calls.forbidden` bans callees matching `{}` from zone '{}'. The check is syntactic: it applies only to files classified into a zone and does not follow aliased or re-bound callees",
1153                    violation.pattern, violation.zone,
1154                )),
1155                available_in_catalogs: None,
1156                suggested_target: None,
1157            }),
1158            IssueAction::SuppressLine(SuppressLineAction {
1159                kind: SuppressLineKind::SuppressLine,
1160                auto_fixable: false,
1161                description: "Suppress with an inline comment above the line".to_string(),
1162                comment: "// fallow-ignore-next-line boundary-violation".to_string(),
1163                scope: None,
1164            }),
1165            IssueAction::SuppressFile(SuppressFileAction {
1166                kind: SuppressFileKind::SuppressFile,
1167                auto_fixable: false,
1168                description: "Suppress with a file-level comment at the top of the file"
1169                    .to_string(),
1170                comment: "// fallow-ignore-file boundary-violation".to_string(),
1171            }),
1172        ];
1173        Self {
1174            finding_id: None,
1175            violation,
1176            actions,
1177            introduced: None,
1178            effective_severity: None,
1179        }
1180    }
1181}
1182
1183/// Wire-shape envelope for a [`PolicyViolation`] finding. Carries actions for
1184/// replacing the banned call, import, or effect, or suppressing it with a scoped
1185/// `policy-violation:<pack>/<rule-id>` token.
1186#[derive(Debug, Clone, Serialize, Deserialize)]
1187#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1188pub struct PolicyViolationFinding {
1189    /// The underlying rule-pack policy entry.
1190    #[serde(flatten)]
1191    pub violation: PolicyViolation,
1192    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1193    /// `~<k>` suffix when several findings of one type share an identity.
1194    /// Line and column are not inputs, so the id survives line shifts,
1195    /// reformats and reorders. A rename of the file or the symbol gives a
1196    /// new id. Absent in output from older versions.
1197    #[serde(default, skip_serializing_if = "Option::is_none")]
1198    pub finding_id: Option<String>,
1199    /// Suggested next steps.
1200    pub actions: Vec<IssueAction>,
1201    /// Set by the audit pass when this finding is introduced relative to
1202    /// the merge-base.
1203    #[serde(default, skip_serializing_if = "Option::is_none")]
1204    pub introduced: Option<AuditIntroduced>,
1205}
1206
1207impl PolicyViolationFinding {
1208    /// Build the wrapper from a raw [`PolicyViolation`].
1209    #[must_use]
1210    pub fn with_actions(violation: PolicyViolation) -> Self {
1211        let what = match violation.kind {
1212            crate::results::PolicyRuleKind::BannedCall => "call",
1213            crate::results::PolicyRuleKind::BannedImport => "import",
1214            crate::results::PolicyRuleKind::BannedEffect => "effect",
1215            crate::results::PolicyRuleKind::BannedExport => "export",
1216            crate::results::PolicyRuleKind::GdpProofProducer => "proof producer",
1217        };
1218        let description = match &violation.message {
1219            Some(message) => format!("Replace the `{}` {what}: {message}", violation.matched),
1220            None => format!("Replace the `{}` {what}", violation.matched),
1221        };
1222        let suppress_token = format!("policy-violation:{}/{}", violation.pack, violation.rule_id);
1223        let note = if violation.kind == crate::results::PolicyRuleKind::GdpProofProducer {
1224            "This check resolves the gdp-ts factory through static imports and unambiguous re-exports. Move proof creation to an allowed module. It does not verify authorization logic or follow arbitrary wrappers.".to_owned()
1225        } else {
1226            format!(
1227                "Rule `{}/{}` from the configured rule packs bans this {what}. The check is syntactic: it does not follow aliased or re-bound callees, and import matching uses the raw specifier",
1228                violation.pack, violation.rule_id,
1229            )
1230        };
1231        let actions = vec![
1232            IssueAction::Fix(FixAction {
1233                kind: FixActionType::ResolvePolicyViolation,
1234                auto_fixable: false,
1235                description,
1236                note: Some(note),
1237                available_in_catalogs: None,
1238                suggested_target: None,
1239            }),
1240            IssueAction::SuppressLine(SuppressLineAction {
1241                kind: SuppressLineKind::SuppressLine,
1242                auto_fixable: false,
1243                description: "Suppress this rule-pack rule with an inline comment above the line"
1244                    .to_string(),
1245                comment: format!("// fallow-ignore-next-line {suppress_token}"),
1246                scope: None,
1247            }),
1248            IssueAction::SuppressFile(SuppressFileAction {
1249                kind: SuppressFileKind::SuppressFile,
1250                auto_fixable: false,
1251                description:
1252                    "Suppress this rule-pack rule with a file-level comment at the top of the file"
1253                        .to_string(),
1254                comment: format!("// fallow-ignore-file {suppress_token}"),
1255            }),
1256        ];
1257        Self {
1258            finding_id: None,
1259            violation,
1260            actions,
1261            introduced: None,
1262        }
1263    }
1264}
1265
1266/// Wire-shape envelope for an [`UnusedExport`] finding consumed under the
1267/// `unused_exports` key. Same Rust struct as [`UnusedTypeFinding`], with a
1268/// different fix description so consumers can tell value-export from
1269/// type-export removal at the action level.
1270#[derive(Debug, Clone, Serialize, Deserialize)]
1271#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1272pub struct UnusedExportFinding {
1273    /// The underlying dead-code entry.
1274    #[serde(flatten)]
1275    pub export: UnusedExport,
1276    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1277    /// `~<k>` suffix when several findings of one type share an identity.
1278    /// Line and column are not inputs, so the id survives line shifts,
1279    /// reformats and reorders. A rename of the file or the symbol gives a
1280    /// new id. Absent in output from older versions.
1281    #[serde(default, skip_serializing_if = "Option::is_none")]
1282    pub finding_id: Option<String>,
1283    /// Suggested next steps. Always emitted (possibly empty for
1284    /// forward-compat).
1285    pub actions: Vec<IssueAction>,
1286    /// Type-aware evidence for this exact candidate when requested.
1287    #[serde(default, skip_serializing_if = "Option::is_none")]
1288    pub semantic: Option<SemanticCandidateDecision>,
1289    /// Set by the audit pass when this finding is introduced relative to
1290    /// the merge-base.
1291    #[serde(default, skip_serializing_if = "Option::is_none")]
1292    pub introduced: Option<AuditIntroduced>,
1293    /// Gate severity of this finding after `rules` and `overrides[].rules`
1294    /// resolve for its path. CI formats read it for the annotation, SARIF
1295    /// and CodeClimate level. Absent in output from older versions. Not
1296    /// part of the finding identity, baseline keys or fingerprints.
1297    #[serde(
1298        default,
1299        skip_serializing_if = "Option::is_none",
1300        deserialize_with = "deserialize_effective_severity"
1301    )]
1302    pub effective_severity: Option<EffectiveSeverity>,
1303    /// Advisory caveats on the reachability verdict behind this finding.
1304    /// Sorted, deduplicated, and omitted from the wire when empty. Never gates
1305    /// the finding or the `remove-export` action, though `fallow fix` does
1306    /// withhold the removal of a caveated export as low confidence.
1307    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1308    pub reachability_caveats: Vec<ReachabilityCaveat>,
1309}
1310
1311impl UnusedExportFinding {
1312    /// Build the wrapper. When `export.is_re_export` is true, the fix
1313    /// action's `note` warns about possible public-API surface; otherwise
1314    /// `note` is absent on the fix action.
1315    #[must_use]
1316    pub fn with_actions(export: UnusedExport) -> Self {
1317        let note = if export.is_re_export {
1318            Some(
1319                "This finding originates from a re-export; verify it is not part of your public API before removing"
1320                    .to_string(),
1321            )
1322        } else {
1323            None
1324        };
1325        let actions = vec![
1326            IssueAction::Fix(FixAction {
1327                kind: FixActionType::RemoveExport,
1328                auto_fixable: true,
1329                description: "Remove the unused export from the public API".to_string(),
1330                note,
1331                available_in_catalogs: None,
1332                suggested_target: None,
1333            }),
1334            IssueAction::SuppressLine(SuppressLineAction {
1335                kind: SuppressLineKind::SuppressLine,
1336                auto_fixable: false,
1337                description: "Suppress with an inline comment above the line".to_string(),
1338                comment: "// fallow-ignore-next-line unused-export".to_string(),
1339                scope: None,
1340            }),
1341        ];
1342        Self {
1343            finding_id: None,
1344            export,
1345            actions,
1346            semantic: None,
1347            introduced: None,
1348            effective_severity: None,
1349            reachability_caveats: Vec::new(),
1350        }
1351    }
1352
1353    /// Attach type-aware evidence and disable the syntactic fix when semantic
1354    /// analysis could not establish complete negative evidence.
1355    pub fn set_semantic_decision(&mut self, decision: SemanticCandidateDecision) {
1356        set_export_semantic_action(&mut self.actions, &decision, &self.reachability_caveats);
1357        self.semantic = Some(decision);
1358    }
1359}
1360
1361/// Wire-shape envelope for an [`UnusedExport`] finding consumed under the
1362/// `unused_types` key. Wraps the same bare [`UnusedExport`] struct as
1363/// [`UnusedExportFinding`] but emits a fix action targeted at type-only
1364/// declarations, with the same `is_re_export`-aware note swap.
1365#[derive(Debug, Clone, Serialize, Deserialize)]
1366#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1367pub struct UnusedTypeFinding {
1368    /// The underlying dead-code entry.
1369    #[serde(flatten)]
1370    pub export: UnusedExport,
1371    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1372    /// `~<k>` suffix when several findings of one type share an identity.
1373    /// Line and column are not inputs, so the id survives line shifts,
1374    /// reformats and reorders. A rename of the file or the symbol gives a
1375    /// new id. Absent in output from older versions.
1376    #[serde(default, skip_serializing_if = "Option::is_none")]
1377    pub finding_id: Option<String>,
1378    /// Suggested next steps. Always emitted (possibly empty for
1379    /// forward-compat).
1380    pub actions: Vec<IssueAction>,
1381    /// Type-aware evidence for this exact candidate when requested.
1382    #[serde(default, skip_serializing_if = "Option::is_none")]
1383    pub semantic: Option<SemanticCandidateDecision>,
1384    /// Set by the audit pass when this finding is introduced relative to
1385    /// the merge-base.
1386    #[serde(default, skip_serializing_if = "Option::is_none")]
1387    pub introduced: Option<AuditIntroduced>,
1388    /// Gate severity of this finding after `rules` and `overrides[].rules`
1389    /// resolve for its path. CI formats read it for the annotation, SARIF
1390    /// and CodeClimate level. Absent in output from older versions. Not
1391    /// part of the finding identity, baseline keys or fingerprints.
1392    #[serde(
1393        default,
1394        skip_serializing_if = "Option::is_none",
1395        deserialize_with = "deserialize_effective_severity"
1396    )]
1397    pub effective_severity: Option<EffectiveSeverity>,
1398    /// Advisory caveats on the reachability verdict behind this finding.
1399    /// A type export rests on exactly the reachability test an
1400    /// `unused_exports[]` entry does, and the LSP offers the same
1401    /// remove-the-`export`-keyword quick fix for both, so the two must render
1402    /// with the same confidence. Sorted, deduplicated, omitted when empty.
1403    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1404    pub reachability_caveats: Vec<ReachabilityCaveat>,
1405}
1406
1407impl UnusedTypeFinding {
1408    /// Build the wrapper. `is_re_export` swaps the fix note the same way as
1409    /// [`UnusedExportFinding::with_actions`].
1410    #[must_use]
1411    pub fn with_actions(export: UnusedExport) -> Self {
1412        let note = if export.is_re_export {
1413            Some(
1414                "This finding originates from a re-export; verify it is not part of your public API before removing"
1415                    .to_string(),
1416            )
1417        } else {
1418            None
1419        };
1420        let actions = vec![
1421            IssueAction::Fix(FixAction {
1422                kind: FixActionType::RemoveExport,
1423                auto_fixable: true,
1424                description:
1425                    "Remove the `export` (or `export type`) keyword from the type declaration"
1426                        .to_string(),
1427                note,
1428                available_in_catalogs: None,
1429                suggested_target: None,
1430            }),
1431            IssueAction::SuppressLine(SuppressLineAction {
1432                kind: SuppressLineKind::SuppressLine,
1433                auto_fixable: false,
1434                description: "Suppress with an inline comment above the line".to_string(),
1435                comment: "// fallow-ignore-next-line unused-type".to_string(),
1436                scope: None,
1437            }),
1438        ];
1439        Self {
1440            finding_id: None,
1441            export,
1442            actions,
1443            semantic: None,
1444            introduced: None,
1445            effective_severity: None,
1446            reachability_caveats: Vec::new(),
1447        }
1448    }
1449
1450    /// Attach type-aware evidence and disable the syntactic fix when semantic
1451    /// analysis could not establish complete negative evidence.
1452    pub fn set_semantic_decision(&mut self, decision: SemanticCandidateDecision) {
1453        set_export_semantic_action(&mut self.actions, &decision, &self.reachability_caveats);
1454        self.semantic = Some(decision);
1455    }
1456}
1457
1458/// The semantic pass runs in the API layer, AFTER the analysis layer stamped
1459/// this run's caveats, and it is the one code path that RAISES `auto_fixable`.
1460/// It therefore has to ask the gate too, or a `Complete` semantic verdict would
1461/// silently re-open a mutation the incomplete run had already withheld.
1462fn set_export_semantic_action(
1463    actions: &mut [IssueAction],
1464    decision: &SemanticCandidateDecision,
1465    caveats: &[ReachabilityCaveat],
1466) {
1467    let complete_negative = decision.decision
1468        == SemanticCandidateDecisionKind::ConfirmedNoStaticReferences
1469        && decision.status == SemanticCompleteness::Complete;
1470    let Some(IssueAction::Fix(action)) = actions.first_mut() else {
1471        return;
1472    };
1473    action.auto_fixable = complete_negative && caveats.is_empty();
1474    if !complete_negative {
1475        action.note = Some(
1476            "Type-aware analysis retained this candidate because complete negative evidence was not available"
1477                .to_string(),
1478        );
1479    }
1480    if !caveats.is_empty() {
1481        action.note = Some(INCOMPLETE_EVIDENCE_NOTE.to_string());
1482    }
1483}
1484
1485/// Wire-shape envelope for an [`InvalidClientExport`] finding. There is no safe
1486/// auto-fix: the export itself may be a legitimate client-component value
1487/// export that happens to collide with a Next.js server-only name, so removing
1488/// it could break the component. Actions are a manual `move-to-server-module`
1489/// fix (the real remediation) plus a line-level suppress.
1490#[derive(Debug, Clone, Serialize, Deserialize)]
1491#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1492pub struct InvalidClientExportFinding {
1493    /// The underlying dead-code entry.
1494    #[serde(flatten)]
1495    pub export: InvalidClientExport,
1496    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1497    /// `~<k>` suffix when several findings of one type share an identity.
1498    /// Line and column are not inputs, so the id survives line shifts,
1499    /// reformats and reorders. A rename of the file or the symbol gives a
1500    /// new id. Absent in output from older versions.
1501    #[serde(default, skip_serializing_if = "Option::is_none")]
1502    pub finding_id: Option<String>,
1503    /// Suggested next steps. Always emitted (possibly empty for
1504    /// forward-compat).
1505    pub actions: Vec<IssueAction>,
1506    /// Set by the audit pass when this finding is introduced relative to
1507    /// the merge-base.
1508    #[serde(default, skip_serializing_if = "Option::is_none")]
1509    pub introduced: Option<AuditIntroduced>,
1510    /// Gate severity of this finding after `rules` and `overrides[].rules`
1511    /// resolve for its path. CI formats read it for the annotation, SARIF
1512    /// and CodeClimate level. Absent in output from older versions. Not
1513    /// part of the finding identity, baseline keys or fingerprints.
1514    #[serde(
1515        default,
1516        skip_serializing_if = "Option::is_none",
1517        deserialize_with = "deserialize_effective_severity"
1518    )]
1519    pub effective_severity: Option<EffectiveSeverity>,
1520}
1521
1522impl InvalidClientExportFinding {
1523    /// Build the wrapper from a raw [`InvalidClientExport`]. Emits a manual
1524    /// fix action (move the server-only export to a non-client module) plus a
1525    /// line-level suppress: there is no safe auto-fix because removing the
1526    /// export could break a legitimate client component.
1527    #[must_use]
1528    pub fn with_actions(export: InvalidClientExport) -> Self {
1529        let actions = vec![
1530            IssueAction::Fix(FixAction {
1531                kind: FixActionType::MoveToServerModule,
1532                auto_fixable: false,
1533                description: "Move the server-only export to a non-client module and import it from there"
1534                    .to_string(),
1535                note: Some(
1536                    "A \"use client\" file cannot export a Next.js server-only or route-config name; Next.js rejects it at build time"
1537                        .to_string(),
1538                ),
1539                available_in_catalogs: None,
1540                suggested_target: None,
1541            }),
1542            IssueAction::SuppressLine(SuppressLineAction {
1543                kind: SuppressLineKind::SuppressLine,
1544                auto_fixable: false,
1545                description: "Suppress with an inline comment above the line".to_string(),
1546                comment: "// fallow-ignore-next-line invalid-client-export".to_string(),
1547                scope: None,
1548            }),
1549        ];
1550        Self {
1551            finding_id: None,
1552            export,
1553            actions,
1554            introduced: None,
1555            effective_severity: None,
1556        }
1557    }
1558}
1559
1560/// Wire-shape envelope for a [`MixedClientServerBarrel`] finding. There is no
1561/// safe auto-fix: splitting a barrel into separate client and server modules is
1562/// a human decision (the barrel may intentionally aggregate both surfaces).
1563/// Actions are a manual `split-mixed-barrel` fix (the real remediation) plus a
1564/// line-level suppress.
1565#[derive(Debug, Clone, Serialize, Deserialize)]
1566#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1567pub struct MixedClientServerBarrelFinding {
1568    /// The underlying dead-code entry.
1569    #[serde(flatten)]
1570    pub barrel: MixedClientServerBarrel,
1571    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1572    /// `~<k>` suffix when several findings of one type share an identity.
1573    /// Line and column are not inputs, so the id survives line shifts,
1574    /// reformats and reorders. A rename of the file or the symbol gives a
1575    /// new id. Absent in output from older versions.
1576    #[serde(default, skip_serializing_if = "Option::is_none")]
1577    pub finding_id: Option<String>,
1578    /// Suggested next steps. Always emitted (possibly empty for
1579    /// forward-compat).
1580    pub actions: Vec<IssueAction>,
1581    /// Set by the audit pass when this finding is introduced relative to
1582    /// the merge-base.
1583    #[serde(default, skip_serializing_if = "Option::is_none")]
1584    pub introduced: Option<AuditIntroduced>,
1585    /// Gate severity of this finding after `rules` and `overrides[].rules`
1586    /// resolve for its path. CI formats read it for the annotation, SARIF
1587    /// and CodeClimate level. Absent in output from older versions. Not
1588    /// part of the finding identity, baseline keys or fingerprints.
1589    #[serde(
1590        default,
1591        skip_serializing_if = "Option::is_none",
1592        deserialize_with = "deserialize_effective_severity"
1593    )]
1594    pub effective_severity: Option<EffectiveSeverity>,
1595}
1596
1597impl MixedClientServerBarrelFinding {
1598    /// Build the wrapper from a raw [`MixedClientServerBarrel`]. Emits a manual
1599    /// fix action (split the barrel into separate client and server halves)
1600    /// plus a line-level suppress: there is no safe auto-fix because splitting
1601    /// the barrel is a human decision.
1602    #[must_use]
1603    pub fn with_actions(barrel: MixedClientServerBarrel) -> Self {
1604        let actions = vec![
1605            IssueAction::Fix(FixAction {
1606                kind: FixActionType::SplitMixedBarrel,
1607                auto_fixable: false,
1608                description: "Split the barrel so client and server-only modules are re-exported from separate files"
1609                    .to_string(),
1610                note: Some(
1611                    "Importing one name from this barrel drags the other's directive across the client/server boundary"
1612                        .to_string(),
1613                ),
1614                available_in_catalogs: None,
1615                suggested_target: None,
1616            }),
1617            IssueAction::SuppressLine(SuppressLineAction {
1618                kind: SuppressLineKind::SuppressLine,
1619                auto_fixable: false,
1620                description: "Suppress with an inline comment above the line".to_string(),
1621                comment: "// fallow-ignore-next-line mixed-client-server-barrel".to_string(),
1622                scope: None,
1623            }),
1624        ];
1625        Self {
1626            finding_id: None,
1627            barrel,
1628            actions,
1629            introduced: None,
1630            effective_severity: None,
1631        }
1632    }
1633}
1634
1635/// Wire-shape envelope for a [`MisplacedDirective`] finding. There is no safe
1636/// auto-fix: moving a directive to the leading prologue is a small but
1637/// judgement-bearing edit (the author may have intended the file to be a
1638/// server module after all). Actions are a manual `hoist-directive` fix (the
1639/// real remediation) plus a line-level suppress.
1640#[derive(Debug, Clone, Serialize, Deserialize)]
1641#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1642pub struct MisplacedDirectiveFinding {
1643    /// The underlying dead-code entry.
1644    #[serde(flatten)]
1645    pub directive_site: MisplacedDirective,
1646    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1647    /// `~<k>` suffix when several findings of one type share an identity.
1648    /// Line and column are not inputs, so the id survives line shifts,
1649    /// reformats and reorders. A rename of the file or the symbol gives a
1650    /// new id. Absent in output from older versions.
1651    #[serde(default, skip_serializing_if = "Option::is_none")]
1652    pub finding_id: Option<String>,
1653    /// Suggested next steps. Always emitted (possibly empty for
1654    /// forward-compat).
1655    pub actions: Vec<IssueAction>,
1656    /// Set by the audit pass when this finding is introduced relative to
1657    /// the merge-base.
1658    #[serde(default, skip_serializing_if = "Option::is_none")]
1659    pub introduced: Option<AuditIntroduced>,
1660    /// Gate severity of this finding after `rules` and `overrides[].rules`
1661    /// resolve for its path. CI formats read it for the annotation, SARIF
1662    /// and CodeClimate level. Absent in output from older versions. Not
1663    /// part of the finding identity, baseline keys or fingerprints.
1664    #[serde(
1665        default,
1666        skip_serializing_if = "Option::is_none",
1667        deserialize_with = "deserialize_effective_severity"
1668    )]
1669    pub effective_severity: Option<EffectiveSeverity>,
1670}
1671
1672impl MisplacedDirectiveFinding {
1673    /// Build the wrapper from a raw [`MisplacedDirective`]. Emits a manual fix
1674    /// action (hoist the directive to the leading prologue) plus a line-level
1675    /// suppress: there is no safe auto-fix because moving a directive can
1676    /// change module semantics and is a human decision.
1677    #[must_use]
1678    pub fn with_actions(directive_site: MisplacedDirective) -> Self {
1679        let actions = vec![
1680            IssueAction::Fix(FixAction {
1681                kind: FixActionType::HoistDirective,
1682                auto_fixable: false,
1683                description: "Move the directive to the very top of the file, above all imports and statements"
1684                    .to_string(),
1685                note: Some(
1686                    "An RSC bundler honors the directive only in the leading prologue; here it precedes other statements and is silently ignored"
1687                        .to_string(),
1688                ),
1689                available_in_catalogs: None,
1690                suggested_target: None,
1691            }),
1692            IssueAction::SuppressLine(SuppressLineAction {
1693                kind: SuppressLineKind::SuppressLine,
1694                auto_fixable: false,
1695                description: "Suppress with an inline comment above the line".to_string(),
1696                comment: "// fallow-ignore-next-line misplaced-directive".to_string(),
1697                scope: None,
1698            }),
1699        ];
1700        Self {
1701            finding_id: None,
1702            directive_site,
1703            actions,
1704            introduced: None,
1705            effective_severity: None,
1706        }
1707    }
1708}
1709
1710/// Wire-shape envelope for an [`UnprovidedInject`] finding. There is no safe
1711/// auto-fix: the fix is binary but judgement-bearing (add a `provide` for the
1712/// key, or delete the dead inject). Actions are manual remediation guidance
1713/// plus a line-level suppress.
1714#[derive(Debug, Clone, Serialize, Deserialize)]
1715#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1716pub struct UnprovidedInjectFinding {
1717    /// The underlying finding.
1718    #[serde(flatten)]
1719    pub inject: UnprovidedInject,
1720    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1721    /// `~<k>` suffix when several findings of one type share an identity.
1722    /// Line and column are not inputs, so the id survives line shifts,
1723    /// reformats and reorders. A rename of the file or the symbol gives a
1724    /// new id. Absent in output from older versions.
1725    #[serde(default, skip_serializing_if = "Option::is_none")]
1726    pub finding_id: Option<String>,
1727    /// Suggested next steps. Always emitted (possibly empty for
1728    /// forward-compat).
1729    pub actions: Vec<IssueAction>,
1730    /// Set by the audit pass when this finding is introduced relative to
1731    /// the merge-base.
1732    #[serde(default, skip_serializing_if = "Option::is_none")]
1733    pub introduced: Option<AuditIntroduced>,
1734    /// Gate severity of this finding after `rules` and `overrides[].rules`
1735    /// resolve for its path. CI formats read it for the annotation, SARIF
1736    /// and CodeClimate level. Absent in output from older versions. Not
1737    /// part of the finding identity, baseline keys or fingerprints.
1738    #[serde(
1739        default,
1740        skip_serializing_if = "Option::is_none",
1741        deserialize_with = "deserialize_effective_severity"
1742    )]
1743    pub effective_severity: Option<EffectiveSeverity>,
1744}
1745
1746impl UnprovidedInjectFinding {
1747    /// Build the wrapper from a raw [`UnprovidedInject`]. Emits a manual fix
1748    /// action plus a line-level suppress.
1749    #[must_use]
1750    pub fn with_actions(inject: UnprovidedInject) -> Self {
1751        let actions = vec![
1752            manual_framework_fix(
1753                FixActionType::ProvideInject,
1754                "Provide this injected key, or remove the inject / getContext call",
1755                "Manual review required: dependency-injection keys can be provided by framework wiring, tests, or package consumers outside this project.",
1756            ),
1757            suppress_line("// fallow-ignore-next-line unprovided-inject"),
1758        ];
1759        Self {
1760            finding_id: None,
1761            inject,
1762            actions,
1763            introduced: None,
1764            effective_severity: None,
1765        }
1766    }
1767}
1768
1769/// Wire-shape envelope for an [`UnusedServerAction`] finding. There is no safe
1770/// auto-fix: the fix is binary but judgement-bearing (wire the action up to a
1771/// consumer, or delete it). Actions are manual remediation guidance plus a
1772/// line-level suppress.
1773#[derive(Debug, Clone, Serialize, Deserialize)]
1774#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1775pub struct UnusedServerActionFinding {
1776    /// The underlying finding.
1777    #[serde(flatten)]
1778    pub action: UnusedServerAction,
1779    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1780    /// `~<k>` suffix when several findings of one type share an identity.
1781    /// Line and column are not inputs, so the id survives line shifts,
1782    /// reformats and reorders. A rename of the file or the symbol gives a
1783    /// new id. Absent in output from older versions.
1784    #[serde(default, skip_serializing_if = "Option::is_none")]
1785    pub finding_id: Option<String>,
1786    /// Suggested next steps. Always emitted (possibly empty for
1787    /// forward-compat).
1788    pub actions: Vec<IssueAction>,
1789    /// Set by the audit pass when this finding is introduced relative to
1790    /// the merge-base.
1791    #[serde(default, skip_serializing_if = "Option::is_none")]
1792    pub introduced: Option<AuditIntroduced>,
1793    /// Gate severity of this finding after `rules` and `overrides[].rules`
1794    /// resolve for its path. CI formats read it for the annotation, SARIF
1795    /// and CodeClimate level. Absent in output from older versions. Not
1796    /// part of the finding identity, baseline keys or fingerprints.
1797    #[serde(
1798        default,
1799        skip_serializing_if = "Option::is_none",
1800        deserialize_with = "deserialize_effective_severity"
1801    )]
1802    pub effective_severity: Option<EffectiveSeverity>,
1803}
1804
1805impl UnusedServerActionFinding {
1806    /// Build the wrapper from a raw [`UnusedServerAction`]. Emits a manual fix
1807    /// action plus a line-level suppress.
1808    #[must_use]
1809    pub fn with_actions(action: UnusedServerAction) -> Self {
1810        let actions = vec![
1811            manual_framework_fix(
1812                FixActionType::WireServerAction,
1813                "Wire the server action to a caller or form action, or remove it",
1814                "Manual review required: server actions may still be POST-able by action id or invoked reflectively outside the static project graph.",
1815            ),
1816            suppress_line("// fallow-ignore-next-line unused-server-action"),
1817        ];
1818        Self {
1819            finding_id: None,
1820            action,
1821            actions,
1822            introduced: None,
1823            effective_severity: None,
1824        }
1825    }
1826}
1827
1828/// Wire-shape envelope for an [`UnusedLoadDataKey`] finding. There is no safe
1829/// auto-fix: a `load()` fetch can have side effects, so deleting the key is a
1830/// human call. Actions are manual remediation guidance plus a line-level
1831/// suppress.
1832#[derive(Debug, Clone, Serialize, Deserialize)]
1833#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1834pub struct UnusedLoadDataKeyFinding {
1835    /// The underlying finding.
1836    #[serde(flatten)]
1837    pub key: UnusedLoadDataKey,
1838    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1839    /// `~<k>` suffix when several findings of one type share an identity.
1840    /// Line and column are not inputs, so the id survives line shifts,
1841    /// reformats and reorders. A rename of the file or the symbol gives a
1842    /// new id. Absent in output from older versions.
1843    #[serde(default, skip_serializing_if = "Option::is_none")]
1844    pub finding_id: Option<String>,
1845    /// Suggested next steps. Always emitted (possibly empty for
1846    /// forward-compat).
1847    pub actions: Vec<IssueAction>,
1848    /// Set by the audit pass when this finding is introduced relative to
1849    /// the merge-base.
1850    #[serde(default, skip_serializing_if = "Option::is_none")]
1851    pub introduced: Option<AuditIntroduced>,
1852    /// Gate severity of this finding after `rules` and `overrides[].rules`
1853    /// resolve for its path. CI formats read it for the annotation, SARIF
1854    /// and CodeClimate level. Absent in output from older versions. Not
1855    /// part of the finding identity, baseline keys or fingerprints.
1856    #[serde(
1857        default,
1858        skip_serializing_if = "Option::is_none",
1859        deserialize_with = "deserialize_effective_severity"
1860    )]
1861    pub effective_severity: Option<EffectiveSeverity>,
1862}
1863
1864impl UnusedLoadDataKeyFinding {
1865    /// Build the wrapper from a raw [`UnusedLoadDataKey`]. Emits a manual fix
1866    /// action plus a line-level suppress.
1867    #[must_use]
1868    pub fn with_actions(key: UnusedLoadDataKey) -> Self {
1869        let actions = vec![
1870            manual_framework_fix(
1871                FixActionType::UseLoadData,
1872                "Read this load data key from the route UI, or remove it from the load return",
1873                "Manual review required: load functions can perform real server or database work, so verify side effects before deleting the producer.",
1874            ),
1875            suppress_line("// fallow-ignore-next-line unused-load-data-key"),
1876        ];
1877        Self {
1878            finding_id: None,
1879            key,
1880            actions,
1881            introduced: None,
1882            effective_severity: None,
1883        }
1884    }
1885}
1886
1887/// Wire-shape envelope for an [`UnrenderedComponent`] finding. There is no safe
1888/// auto-fix: the fix is binary but judgement-bearing (render the component
1889/// somewhere, or delete the dead component). Actions are manual remediation
1890/// guidance plus a line-level suppress.
1891#[derive(Debug, Clone, Serialize, Deserialize)]
1892#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1893pub struct UnrenderedComponentFinding {
1894    /// The underlying finding.
1895    #[serde(flatten)]
1896    pub component: UnrenderedComponent,
1897    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1898    /// `~<k>` suffix when several findings of one type share an identity.
1899    /// Line and column are not inputs, so the id survives line shifts,
1900    /// reformats and reorders. A rename of the file or the symbol gives a
1901    /// new id. Absent in output from older versions.
1902    #[serde(default, skip_serializing_if = "Option::is_none")]
1903    pub finding_id: Option<String>,
1904    /// Suggested next steps. Always emitted (possibly empty for
1905    /// forward-compat).
1906    pub actions: Vec<IssueAction>,
1907    /// Set by the audit pass when this finding is introduced relative to
1908    /// the merge-base.
1909    #[serde(default, skip_serializing_if = "Option::is_none")]
1910    pub introduced: Option<AuditIntroduced>,
1911    /// Gate severity of this finding after `rules` and `overrides[].rules`
1912    /// resolve for its path. CI formats read it for the annotation, SARIF
1913    /// and CodeClimate level. Absent in output from older versions. Not
1914    /// part of the finding identity, baseline keys or fingerprints.
1915    #[serde(
1916        default,
1917        skip_serializing_if = "Option::is_none",
1918        deserialize_with = "deserialize_effective_severity"
1919    )]
1920    pub effective_severity: Option<EffectiveSeverity>,
1921}
1922
1923impl UnrenderedComponentFinding {
1924    /// Build the wrapper from a raw [`UnrenderedComponent`]. Emits a manual
1925    /// fix action plus a line-level suppress.
1926    #[must_use]
1927    pub fn with_actions(component: UnrenderedComponent) -> Self {
1928        let actions = vec![
1929            manual_framework_fix(
1930                FixActionType::RenderComponent,
1931                "Render the reachable component from project code, or remove it",
1932                "Manual review required: exported library components and dynamic render registries can be intentionally reachable without static template usage.",
1933            ),
1934            suppress_line("// fallow-ignore-next-line unrendered-component"),
1935        ];
1936        Self {
1937            finding_id: None,
1938            component,
1939            actions,
1940            introduced: None,
1941            effective_severity: None,
1942        }
1943    }
1944}
1945
1946/// Wire-shape envelope for an [`UnusedComponentProp`] finding. There is no safe
1947/// auto-fix: removing a declared prop is judgement-bearing (the prop may be part
1948/// of a deliberately-stable public component API). Actions are manual
1949/// remediation guidance plus a line-level suppress at the prop declaration.
1950#[derive(Debug, Clone, Serialize, Deserialize)]
1951#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
1952pub struct UnusedComponentPropFinding {
1953    /// The underlying finding.
1954    #[serde(flatten)]
1955    pub prop: UnusedComponentProp,
1956    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
1957    /// `~<k>` suffix when several findings of one type share an identity.
1958    /// Line and column are not inputs, so the id survives line shifts,
1959    /// reformats and reorders. A rename of the file or the symbol gives a
1960    /// new id. Absent in output from older versions.
1961    #[serde(default, skip_serializing_if = "Option::is_none")]
1962    pub finding_id: Option<String>,
1963    /// Suggested next steps. Always emitted (possibly empty for
1964    /// forward-compat).
1965    pub actions: Vec<IssueAction>,
1966    /// Set by the audit pass when this finding is introduced relative to
1967    /// the merge-base.
1968    #[serde(default, skip_serializing_if = "Option::is_none")]
1969    pub introduced: Option<AuditIntroduced>,
1970    /// Gate severity of this finding after `rules` and `overrides[].rules`
1971    /// resolve for its path. CI formats read it for the annotation, SARIF
1972    /// and CodeClimate level. Absent in output from older versions. Not
1973    /// part of the finding identity, baseline keys or fingerprints.
1974    #[serde(
1975        default,
1976        skip_serializing_if = "Option::is_none",
1977        deserialize_with = "deserialize_effective_severity"
1978    )]
1979    pub effective_severity: Option<EffectiveSeverity>,
1980}
1981
1982impl UnusedComponentPropFinding {
1983    /// Build the wrapper from a raw [`UnusedComponentProp`]. Emits a manual
1984    /// fix action plus a line-level suppress.
1985    #[must_use]
1986    pub fn with_actions(prop: UnusedComponentProp) -> Self {
1987        let actions = vec![
1988            manual_framework_fix(
1989                FixActionType::UseComponentProp,
1990                "Use the declared prop in the component, or remove it from the component API",
1991                "Manual review required: public component APIs can intentionally keep stable props for external consumers.",
1992            ),
1993            suppress_line("// fallow-ignore-next-line unused-component-prop"),
1994        ];
1995        Self {
1996            finding_id: None,
1997            prop,
1998            actions,
1999            introduced: None,
2000            effective_severity: None,
2001        }
2002    }
2003}
2004
2005/// Wire-shape envelope for an [`UnusedComponentEmit`] finding. There is no safe
2006/// auto-fix: removing a declared emit is judgement-bearing (the event may be
2007/// part of a deliberately-stable public component API). Actions are manual
2008/// remediation guidance plus a line-level suppress at the emit declaration.
2009#[derive(Debug, Clone, Serialize, Deserialize)]
2010#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2011pub struct UnusedComponentEmitFinding {
2012    /// The underlying finding.
2013    #[serde(flatten)]
2014    pub emit: UnusedComponentEmit,
2015    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2016    /// `~<k>` suffix when several findings of one type share an identity.
2017    /// Line and column are not inputs, so the id survives line shifts,
2018    /// reformats and reorders. A rename of the file or the symbol gives a
2019    /// new id. Absent in output from older versions.
2020    #[serde(default, skip_serializing_if = "Option::is_none")]
2021    pub finding_id: Option<String>,
2022    /// Suggested next steps. Always emitted (possibly empty for
2023    /// forward-compat).
2024    pub actions: Vec<IssueAction>,
2025    /// Set by the audit pass when this finding is introduced relative to
2026    /// the merge-base.
2027    #[serde(default, skip_serializing_if = "Option::is_none")]
2028    pub introduced: Option<AuditIntroduced>,
2029    /// Gate severity of this finding after `rules` and `overrides[].rules`
2030    /// resolve for its path. CI formats read it for the annotation, SARIF
2031    /// and CodeClimate level. Absent in output from older versions. Not
2032    /// part of the finding identity, baseline keys or fingerprints.
2033    #[serde(
2034        default,
2035        skip_serializing_if = "Option::is_none",
2036        deserialize_with = "deserialize_effective_severity"
2037    )]
2038    pub effective_severity: Option<EffectiveSeverity>,
2039}
2040
2041impl UnusedComponentEmitFinding {
2042    /// Build the wrapper from a raw [`UnusedComponentEmit`]. Emits a manual
2043    /// fix action plus a line-level suppress.
2044    #[must_use]
2045    pub fn with_actions(emit: UnusedComponentEmit) -> Self {
2046        let actions = vec![
2047            manual_framework_fix(
2048                FixActionType::EmitComponentEvent,
2049                "Emit the declared event from the component, or remove it from the component API",
2050                "Manual review required: public component APIs can intentionally keep stable events for external listeners.",
2051            ),
2052            suppress_line("// fallow-ignore-next-line unused-component-emit"),
2053        ];
2054        Self {
2055            finding_id: None,
2056            emit,
2057            actions,
2058            introduced: None,
2059            effective_severity: None,
2060        }
2061    }
2062}
2063
2064/// Wire-shape envelope for an [`UnusedSvelteEvent`] finding. There is no safe
2065/// auto-fix: removing a dispatched event is judgement-bearing (the event may be
2066/// part of a deliberately-stable public component API, or a listener may be
2067/// added later). Actions are manual remediation guidance plus a line-level
2068/// suppress at the `dispatch` call.
2069#[derive(Debug, Clone, Serialize, Deserialize)]
2070#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2071pub struct UnusedSvelteEventFinding {
2072    /// The underlying finding.
2073    #[serde(flatten)]
2074    pub event: UnusedSvelteEvent,
2075    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2076    /// `~<k>` suffix when several findings of one type share an identity.
2077    /// Line and column are not inputs, so the id survives line shifts,
2078    /// reformats and reorders. A rename of the file or the symbol gives a
2079    /// new id. Absent in output from older versions.
2080    #[serde(default, skip_serializing_if = "Option::is_none")]
2081    pub finding_id: Option<String>,
2082    /// Suggested next steps. Always emitted (possibly empty for
2083    /// forward-compat).
2084    pub actions: Vec<IssueAction>,
2085    /// Set by the audit pass when this finding is introduced relative to
2086    /// the merge-base.
2087    #[serde(default, skip_serializing_if = "Option::is_none")]
2088    pub introduced: Option<AuditIntroduced>,
2089    /// Gate severity of this finding after `rules` and `overrides[].rules`
2090    /// resolve for its path. CI formats read it for the annotation, SARIF
2091    /// and CodeClimate level. Absent in output from older versions. Not
2092    /// part of the finding identity, baseline keys or fingerprints.
2093    #[serde(
2094        default,
2095        skip_serializing_if = "Option::is_none",
2096        deserialize_with = "deserialize_effective_severity"
2097    )]
2098    pub effective_severity: Option<EffectiveSeverity>,
2099}
2100
2101impl UnusedSvelteEventFinding {
2102    /// Build the wrapper from a raw [`UnusedSvelteEvent`]. Emits a manual fix
2103    /// action plus a line-level suppress.
2104    #[must_use]
2105    pub fn with_actions(event: UnusedSvelteEvent) -> Self {
2106        let actions = vec![
2107            manual_framework_fix(
2108                FixActionType::WireSvelteEvent,
2109                "Add or forward a listener for this custom event, or remove the dispatch",
2110                "Manual review required: public Svelte component APIs can intentionally dispatch events for package consumers outside this project.",
2111            ),
2112            suppress_line("// fallow-ignore-next-line unused-svelte-event"),
2113        ];
2114        Self {
2115            finding_id: None,
2116            event,
2117            actions,
2118            introduced: None,
2119            effective_severity: None,
2120        }
2121    }
2122}
2123
2124/// Wire-shape envelope for a [`DuplicateExportAlias`] finding. There is no
2125/// safe auto-fix: a consumer outside the project can import any of the
2126/// names. Actions are manual remediation guidance plus a line-level
2127/// suppress.
2128#[derive(Debug, Clone, Serialize, Deserialize)]
2129#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2130pub struct DuplicateExportAliasFinding {
2131    /// The underlying finding.
2132    #[serde(flatten)]
2133    pub alias: DuplicateExportAlias,
2134    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2135    /// `~<k>` suffix when several findings of one type share an identity.
2136    /// Line and column are not inputs, so the id survives line shifts,
2137    /// reformats and reorders. A rename of the file or the binding gives a
2138    /// new id. Absent in output from older versions.
2139    #[serde(default, skip_serializing_if = "Option::is_none")]
2140    pub finding_id: Option<String>,
2141    /// Suggested next steps. Always emitted (possibly empty for
2142    /// forward-compat).
2143    pub actions: Vec<IssueAction>,
2144    /// Set by the audit pass when this finding is introduced relative to
2145    /// the merge-base.
2146    #[serde(default, skip_serializing_if = "Option::is_none")]
2147    pub introduced: Option<AuditIntroduced>,
2148    /// Gate severity of this finding after `rules` and `overrides[].rules`
2149    /// resolve for its path. CI formats read it for the annotation, SARIF
2150    /// and CodeClimate level. Absent in output from older versions. Not
2151    /// part of the finding identity, baseline keys or fingerprints.
2152    #[serde(
2153        default,
2154        skip_serializing_if = "Option::is_none",
2155        deserialize_with = "deserialize_effective_severity"
2156    )]
2157    pub effective_severity: Option<EffectiveSeverity>,
2158}
2159
2160impl DuplicateExportAliasFinding {
2161    /// Build the wrapper from a raw [`DuplicateExportAlias`]. Emits a manual
2162    /// fix action plus a line-level suppress.
2163    #[must_use]
2164    pub fn with_actions(alias: DuplicateExportAlias) -> Self {
2165        let actions = vec![
2166            manual_framework_fix(
2167                FixActionType::RemoveDuplicate,
2168                "Keep one export name for the binding and remove the other names",
2169                "Manual review required: update the importers of a removed name first. Code outside the analyzed project can import any of the names. If the names are an intentional public API, add them to ignoreExports.",
2170            ),
2171            suppress_line("// fallow-ignore-next-line duplicate-export-alias"),
2172        ];
2173        Self {
2174            finding_id: None,
2175            alias,
2176            actions,
2177            introduced: None,
2178            effective_severity: None,
2179        }
2180    }
2181}
2182
2183/// Wire-shape envelope for an [`UnusedEffectLayer`] finding. There is no safe auto-fix: a test or a script outside the project graph can still use the layer. Actions are manual
2184/// remediation guidance plus a line-level suppress.
2185#[derive(Debug, Clone, Serialize, Deserialize)]
2186#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2187pub struct UnusedEffectLayerFinding {
2188    /// The underlying finding.
2189    #[serde(flatten)]
2190    pub layer: UnusedEffectLayer,
2191    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2192    /// `~<k>` suffix when several findings of one type share an identity.
2193    /// Line and column are not inputs, so the id survives line shifts,
2194    /// reformats and reorders. A rename of the file or the symbol gives a
2195    /// new id. Absent in output from older versions.
2196    #[serde(default, skip_serializing_if = "Option::is_none")]
2197    pub finding_id: Option<String>,
2198    /// Suggested next steps. Always emitted (possibly empty for
2199    /// forward-compat).
2200    pub actions: Vec<IssueAction>,
2201    /// Set by the audit pass when this finding is introduced relative to
2202    /// the merge-base.
2203    #[serde(default, skip_serializing_if = "Option::is_none")]
2204    pub introduced: Option<AuditIntroduced>,
2205    /// Gate severity of this finding after `rules` and `overrides[].rules`
2206    /// resolve for its path. CI formats read it for the annotation, SARIF
2207    /// and CodeClimate level. Absent in output from older versions. Not
2208    /// part of the finding identity, baseline keys or fingerprints.
2209    #[serde(
2210        default,
2211        skip_serializing_if = "Option::is_none",
2212        deserialize_with = "deserialize_effective_severity"
2213    )]
2214    pub effective_severity: Option<EffectiveSeverity>,
2215}
2216
2217impl UnusedEffectLayerFinding {
2218    /// Build the wrapper from a raw [`UnusedEffectLayer`]. Emits a manual fix action plus
2219    /// a line-level suppress.
2220    #[must_use]
2221    pub fn with_actions(layer: UnusedEffectLayer) -> Self {
2222        let actions = vec![
2223            manual_framework_fix(
2224                FixActionType::ComposeEffectLayer,
2225                "Compose the layer into a layer that reaches a runtime, or remove it with its unused consumers",
2226                "Manual review required: remove the unused consumer layers first, then this layer. Code outside the analyzed project can still compose it.",
2227            ),
2228            suppress_line("// fallow-ignore-next-line unused-effect-layer"),
2229        ];
2230        Self {
2231            finding_id: None,
2232            layer,
2233            actions,
2234            introduced: None,
2235            effective_severity: None,
2236        }
2237    }
2238}
2239
2240/// Wire-shape envelope for an [`UnusedTaggedError`] finding. There is no safe auto-fix: the error can be part of a public API contract. Actions are manual
2241/// remediation guidance plus a line-level suppress.
2242#[derive(Debug, Clone, Serialize, Deserialize)]
2243#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2244pub struct UnusedTaggedErrorFinding {
2245    /// The underlying finding.
2246    #[serde(flatten)]
2247    pub error: UnusedTaggedError,
2248    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2249    /// `~<k>` suffix when several findings of one type share an identity.
2250    /// Line and column are not inputs, so the id survives line shifts,
2251    /// reformats and reorders. A rename of the file or the symbol gives a
2252    /// new id. Absent in output from older versions.
2253    #[serde(default, skip_serializing_if = "Option::is_none")]
2254    pub finding_id: Option<String>,
2255    /// Suggested next steps. Always emitted (possibly empty for
2256    /// forward-compat).
2257    pub actions: Vec<IssueAction>,
2258    /// Set by the audit pass when this finding is introduced relative to
2259    /// the merge-base.
2260    #[serde(default, skip_serializing_if = "Option::is_none")]
2261    pub introduced: Option<AuditIntroduced>,
2262    /// Gate severity of this finding after `rules` and `overrides[].rules`
2263    /// resolve for its path. CI formats read it for the annotation, SARIF
2264    /// and CodeClimate level. Absent in output from older versions. Not
2265    /// part of the finding identity, baseline keys or fingerprints.
2266    #[serde(
2267        default,
2268        skip_serializing_if = "Option::is_none",
2269        deserialize_with = "deserialize_effective_severity"
2270    )]
2271    pub effective_severity: Option<EffectiveSeverity>,
2272}
2273
2274impl UnusedTaggedErrorFinding {
2275    /// Build the wrapper from a raw [`UnusedTaggedError`]. Emits a manual fix action plus
2276    /// a line-level suppress.
2277    #[must_use]
2278    pub fn with_actions(error: UnusedTaggedError) -> Self {
2279        let actions = vec![
2280            manual_framework_fix(
2281                FixActionType::FailTaggedError,
2282                "Fail with this error where the condition occurs, or remove the class and its catchTag handlers",
2283                "Manual review required: consumers outside the analyzed project can construct or decode the error.",
2284            ),
2285            suppress_line("// fallow-ignore-next-line unused-tagged-error"),
2286        ];
2287        Self {
2288            finding_id: None,
2289            error,
2290            actions,
2291            introduced: None,
2292            effective_severity: None,
2293        }
2294    }
2295}
2296
2297/// Wire-shape envelope for an [`UnproducedCatchTag`] finding. There is no safe auto-fix: the handler can guard against a future producer. Actions are manual
2298/// remediation guidance plus a line-level suppress.
2299#[derive(Debug, Clone, Serialize, Deserialize)]
2300#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2301pub struct UnproducedCatchTagFinding {
2302    /// The underlying finding.
2303    #[serde(flatten)]
2304    pub catch_tag: UnproducedCatchTag,
2305    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2306    /// `~<k>` suffix when several findings of one type share an identity.
2307    /// Line and column are not inputs, so the id survives line shifts,
2308    /// reformats and reorders. A rename of the file or the symbol gives a
2309    /// new id. Absent in output from older versions.
2310    #[serde(default, skip_serializing_if = "Option::is_none")]
2311    pub finding_id: Option<String>,
2312    /// Suggested next steps. Always emitted (possibly empty for
2313    /// forward-compat).
2314    pub actions: Vec<IssueAction>,
2315    /// Set by the audit pass when this finding is introduced relative to
2316    /// the merge-base.
2317    #[serde(default, skip_serializing_if = "Option::is_none")]
2318    pub introduced: Option<AuditIntroduced>,
2319    /// Gate severity of this finding after `rules` and `overrides[].rules`
2320    /// resolve for its path. CI formats read it for the annotation, SARIF
2321    /// and CodeClimate level. Absent in output from older versions. Not
2322    /// part of the finding identity, baseline keys or fingerprints.
2323    #[serde(
2324        default,
2325        skip_serializing_if = "Option::is_none",
2326        deserialize_with = "deserialize_effective_severity"
2327    )]
2328    pub effective_severity: Option<EffectiveSeverity>,
2329}
2330
2331impl UnproducedCatchTagFinding {
2332    /// Build the wrapper from a raw [`UnproducedCatchTag`]. Emits a manual fix action plus
2333    /// a line-level suppress.
2334    #[must_use]
2335    pub fn with_actions(catch_tag: UnproducedCatchTag) -> Self {
2336        let actions = vec![
2337            manual_framework_fix(
2338                FixActionType::RemoveCatchTagHandler,
2339                "Remove the handler for this tag, or fail with the error where the condition occurs",
2340                "Manual review required: a package or code outside the analyzed project can produce the tag.",
2341            ),
2342            suppress_line("// fallow-ignore-next-line unproduced-catch-tag"),
2343        ];
2344        Self {
2345            finding_id: None,
2346            catch_tag,
2347            actions,
2348            introduced: None,
2349            effective_severity: None,
2350        }
2351    }
2352}
2353
2354/// Wire-shape envelope for a [`PropDrillingChain`] finding. There is no safe
2355/// auto-fix: collapsing a drilling chain (colocate the consumer, lift to a
2356/// context, or compose the component) is a design decision. The only action is a
2357/// line-level suppress at the source hop's prop declaration. The rule defaults
2358/// to `off` (opt-in health signal), so this finding is dormant by default.
2359#[derive(Debug, Clone, Serialize, Deserialize)]
2360#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2361pub struct PropDrillingChainFinding {
2362    /// The underlying located chain.
2363    #[serde(flatten)]
2364    pub chain: PropDrillingChain,
2365    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2366    /// `~<k>` suffix when several findings of one type share an identity.
2367    /// Line and column are not inputs, so the id survives line shifts,
2368    /// reformats and reorders. A rename of the file or the symbol gives a
2369    /// new id. Absent in output from older versions.
2370    #[serde(default, skip_serializing_if = "Option::is_none")]
2371    pub finding_id: Option<String>,
2372    /// Suggested next steps. Always emitted (possibly empty for
2373    /// forward-compat).
2374    pub actions: Vec<IssueAction>,
2375    /// Set by the audit pass when this finding is introduced relative to
2376    /// the merge-base.
2377    #[serde(default, skip_serializing_if = "Option::is_none")]
2378    pub introduced: Option<AuditIntroduced>,
2379    /// Rule severity after resolving overrides for the source hop. An explicit
2380    /// `error` enforces the chain; `warn` stays advisory under strict flags.
2381    /// Saved reports use this value for CI levels. Absent in older output.
2382    /// Not part of finding identity, baseline keys or fingerprints.
2383    #[serde(
2384        default,
2385        skip_serializing_if = "Option::is_none",
2386        deserialize_with = "deserialize_effective_severity"
2387    )]
2388    pub effective_severity: Option<EffectiveSeverity>,
2389}
2390
2391impl PropDrillingChainFinding {
2392    /// Build the wrapper from a raw [`PropDrillingChain`]. Emits only a
2393    /// line-level suppress action anchored at the source hop: there is no safe
2394    /// auto-fix because collapsing the chain is a design decision (colocate,
2395    /// lift to context, or compose).
2396    #[must_use]
2397    pub fn with_actions(chain: PropDrillingChain) -> Self {
2398        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
2399            kind: SuppressLineKind::SuppressLine,
2400            auto_fixable: false,
2401            description: "Suppress with an inline comment above the source prop declaration"
2402                .to_string(),
2403            comment: "// fallow-ignore-next-line prop-drilling".to_string(),
2404            scope: None,
2405        })];
2406        Self {
2407            finding_id: None,
2408            chain,
2409            actions,
2410            introduced: None,
2411            effective_severity: None,
2412        }
2413    }
2414}
2415
2416/// Wire-shape envelope for a [`ThinWrapper`] finding. There is no safe
2417/// auto-fix: inlining a thin wrapper at its call sites (or deleting it) is a
2418/// design decision. The only action is a line-level suppress at the wrapper's
2419/// definition. The rule defaults to `off` (opt-in health signal), so this
2420/// finding is dormant by default.
2421#[derive(Debug, Clone, Serialize, Deserialize)]
2422#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2423pub struct ThinWrapperFinding {
2424    /// The underlying located thin wrapper.
2425    #[serde(flatten)]
2426    pub wrapper: ThinWrapper,
2427    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2428    /// `~<k>` suffix when several findings of one type share an identity.
2429    /// Line and column are not inputs, so the id survives line shifts,
2430    /// reformats and reorders. A rename of the file or the symbol gives a
2431    /// new id. Absent in output from older versions.
2432    #[serde(default, skip_serializing_if = "Option::is_none")]
2433    pub finding_id: Option<String>,
2434    /// Suggested next steps. Always emitted (possibly empty for
2435    /// forward-compat).
2436    pub actions: Vec<IssueAction>,
2437    /// Set by the audit pass when this finding is introduced relative to
2438    /// the merge-base.
2439    #[serde(default, skip_serializing_if = "Option::is_none")]
2440    pub introduced: Option<AuditIntroduced>,
2441    /// Rule severity of this finding. Explicit errors enforce analysis gates;
2442    /// warnings stay advisory, including under strict flags. Saved reports
2443    /// retain this value for CI levels without the original config. Absent
2444    /// in output from older versions. Not part of finding identity, baseline
2445    /// keys or fingerprints.
2446    #[serde(
2447        default,
2448        skip_serializing_if = "Option::is_none",
2449        deserialize_with = "deserialize_effective_severity"
2450    )]
2451    pub effective_severity: Option<EffectiveSeverity>,
2452}
2453
2454impl ThinWrapperFinding {
2455    /// Build the wrapper from a raw [`ThinWrapper`]. Emits only a line-level
2456    /// suppress action anchored at the wrapper definition: there is no safe
2457    /// auto-fix because inlining or deleting the wrapper is a design decision.
2458    #[must_use]
2459    pub fn with_actions(wrapper: ThinWrapper) -> Self {
2460        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
2461            kind: SuppressLineKind::SuppressLine,
2462            auto_fixable: false,
2463            description: "Suppress with an inline comment above the component definition"
2464                .to_string(),
2465            comment: "// fallow-ignore-next-line thin-wrapper".to_string(),
2466            scope: None,
2467        })];
2468        Self {
2469            finding_id: None,
2470            wrapper,
2471            actions,
2472            introduced: None,
2473            effective_severity: None,
2474        }
2475    }
2476}
2477
2478/// Wire-shape envelope for a [`DuplicatePropShape`] finding. There is no safe
2479/// auto-fix: extracting a shared `Props` type or a base component for a group of
2480/// same-shaped components is a design decision. The actions are manual guidance
2481/// (extract the shared shape) plus a line-level suppress at the component
2482/// definition and a file-level suppress escape hatch (mirroring the
2483/// route-collision multi-file model). The rule defaults to `off` (opt-in health
2484/// signal), so this finding is dormant by default.
2485#[derive(Debug, Clone, Serialize, Deserialize)]
2486#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2487pub struct DuplicatePropShapeFinding {
2488    /// The underlying duplicate-prop-shape entry.
2489    #[serde(flatten)]
2490    pub shape: DuplicatePropShape,
2491    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2492    /// `~<k>` suffix when several findings of one type share an identity.
2493    /// Line and column are not inputs, so the id survives line shifts,
2494    /// reformats and reorders. A rename of the file or the symbol gives a
2495    /// new id. Absent in output from older versions.
2496    #[serde(default, skip_serializing_if = "Option::is_none")]
2497    pub finding_id: Option<String>,
2498    /// Suggested next steps. Always emitted (possibly empty for
2499    /// forward-compat).
2500    pub actions: Vec<IssueAction>,
2501    /// Set by the audit pass when this finding is introduced relative to
2502    /// the merge-base.
2503    #[serde(default, skip_serializing_if = "Option::is_none")]
2504    pub introduced: Option<AuditIntroduced>,
2505    /// Rule severity of this finding. Explicit errors enforce analysis gates;
2506    /// warnings stay advisory, including under strict flags. Saved reports
2507    /// retain this value for CI levels without the original config. Absent
2508    /// in output from older versions. Not part of finding identity, baseline
2509    /// keys or fingerprints.
2510    #[serde(
2511        default,
2512        skip_serializing_if = "Option::is_none",
2513        deserialize_with = "deserialize_effective_severity"
2514    )]
2515    pub effective_severity: Option<EffectiveSeverity>,
2516}
2517
2518impl DuplicatePropShapeFinding {
2519    /// Build the wrapper from a raw [`DuplicatePropShape`]. Manual guidance is
2520    /// the primary action (extract a shared shape); a line-level suppress at the
2521    /// component definition and a file-level suppress escape hatch follow,
2522    /// mirroring the multi-file route-collision suppress model. There is no safe
2523    /// auto-fix because extracting a shared type or base component is a design
2524    /// decision.
2525    #[must_use]
2526    pub fn with_actions(shape: DuplicatePropShape) -> Self {
2527        let actions = vec![
2528            IssueAction::SuppressLine(SuppressLineAction {
2529                kind: SuppressLineKind::SuppressLine,
2530                auto_fixable: false,
2531                description: "Three or more components share this exact prop shape. Extract one \
2532                              shared `Props` type (or a base component) that every member reuses, \
2533                              or keep them separate if a per-variant divergence is planned. \
2534                              Suppress one member with an inline comment above the component \
2535                              definition."
2536                    .to_string(),
2537                comment: "// fallow-ignore-next-line duplicate-prop-shape".to_string(),
2538                scope: None,
2539            }),
2540            IssueAction::SuppressFile(SuppressFileAction {
2541                kind: SuppressFileKind::SuppressFile,
2542                auto_fixable: false,
2543                description: "Escape hatch: a file-level suppress silences this member but it \
2544                              still appears in its siblings' `sharing_components` (the group is \
2545                              real regardless of suppression)."
2546                    .to_string(),
2547                comment: "// fallow-ignore-file duplicate-prop-shape".to_string(),
2548            }),
2549        ];
2550        Self {
2551            finding_id: None,
2552            shape,
2553            actions,
2554            introduced: None,
2555            effective_severity: None,
2556        }
2557    }
2558}
2559
2560/// Wire-shape envelope for an [`UnusedComponentInput`] finding. There is no safe
2561/// auto-fix: removing a declared input is judgement-bearing (the input may be
2562/// part of a deliberately-stable public component API). The only action is a
2563/// line-level suppress at the input declaration.
2564#[derive(Debug, Clone, Serialize, Deserialize)]
2565#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2566pub struct UnusedComponentInputFinding {
2567    /// The underlying finding.
2568    #[serde(flatten)]
2569    pub input: UnusedComponentInput,
2570    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2571    /// `~<k>` suffix when several findings of one type share an identity.
2572    /// Line and column are not inputs, so the id survives line shifts,
2573    /// reformats and reorders. A rename of the file or the symbol gives a
2574    /// new id. Absent in output from older versions.
2575    #[serde(default, skip_serializing_if = "Option::is_none")]
2576    pub finding_id: Option<String>,
2577    /// Suggested next steps. Always emitted (possibly empty for
2578    /// forward-compat).
2579    pub actions: Vec<IssueAction>,
2580    /// Set by the audit pass when this finding is introduced relative to
2581    /// the merge-base.
2582    #[serde(default, skip_serializing_if = "Option::is_none")]
2583    pub introduced: Option<AuditIntroduced>,
2584    /// Gate severity of this finding after `rules` and `overrides[].rules`
2585    /// resolve for its path. CI formats read it for the annotation, SARIF
2586    /// and CodeClimate level. Absent in output from older versions. Not
2587    /// part of the finding identity, baseline keys or fingerprints.
2588    #[serde(
2589        default,
2590        skip_serializing_if = "Option::is_none",
2591        deserialize_with = "deserialize_effective_severity"
2592    )]
2593    pub effective_severity: Option<EffectiveSeverity>,
2594}
2595
2596impl UnusedComponentInputFinding {
2597    /// Build the wrapper from a raw [`UnusedComponentInput`]. Emits only a
2598    /// line-level suppress action: there is no safe auto-fix because removing an
2599    /// input is a human decision (it may be part of a stable component API).
2600    #[must_use]
2601    pub fn with_actions(input: UnusedComponentInput) -> Self {
2602        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
2603            kind: SuppressLineKind::SuppressLine,
2604            auto_fixable: false,
2605            description: "Suppress with an inline comment above the line".to_string(),
2606            comment: "// fallow-ignore-next-line unused-component-input".to_string(),
2607            scope: None,
2608        })];
2609        Self {
2610            finding_id: None,
2611            input,
2612            actions,
2613            introduced: None,
2614            effective_severity: None,
2615        }
2616    }
2617}
2618
2619/// Wire-shape envelope for an [`UnusedComponentOutput`] finding. There is no safe
2620/// auto-fix: removing a declared output is judgement-bearing (the event may be
2621/// part of a deliberately-stable public component API). The only action is a
2622/// line-level suppress at the output declaration.
2623#[derive(Debug, Clone, Serialize, Deserialize)]
2624#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2625pub struct UnusedComponentOutputFinding {
2626    /// The underlying finding.
2627    #[serde(flatten)]
2628    pub output: UnusedComponentOutput,
2629    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2630    /// `~<k>` suffix when several findings of one type share an identity.
2631    /// Line and column are not inputs, so the id survives line shifts,
2632    /// reformats and reorders. A rename of the file or the symbol gives a
2633    /// new id. Absent in output from older versions.
2634    #[serde(default, skip_serializing_if = "Option::is_none")]
2635    pub finding_id: Option<String>,
2636    /// Suggested next steps. Always emitted (possibly empty for
2637    /// forward-compat).
2638    pub actions: Vec<IssueAction>,
2639    /// Set by the audit pass when this finding is introduced relative to
2640    /// the merge-base.
2641    #[serde(default, skip_serializing_if = "Option::is_none")]
2642    pub introduced: Option<AuditIntroduced>,
2643    /// Gate severity of this finding after `rules` and `overrides[].rules`
2644    /// resolve for its path. CI formats read it for the annotation, SARIF
2645    /// and CodeClimate level. Absent in output from older versions. Not
2646    /// part of the finding identity, baseline keys or fingerprints.
2647    #[serde(
2648        default,
2649        skip_serializing_if = "Option::is_none",
2650        deserialize_with = "deserialize_effective_severity"
2651    )]
2652    pub effective_severity: Option<EffectiveSeverity>,
2653}
2654
2655impl UnusedComponentOutputFinding {
2656    /// Build the wrapper from a raw [`UnusedComponentOutput`]. Emits only a
2657    /// line-level suppress action: there is no safe auto-fix because removing an
2658    /// output is a human decision (it may be part of a stable component API).
2659    #[must_use]
2660    pub fn with_actions(output: UnusedComponentOutput) -> Self {
2661        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
2662            kind: SuppressLineKind::SuppressLine,
2663            auto_fixable: false,
2664            description: "Suppress with an inline comment above the line".to_string(),
2665            comment: "// fallow-ignore-next-line unused-component-output".to_string(),
2666            scope: None,
2667        })];
2668        Self {
2669            finding_id: None,
2670            output,
2671            actions,
2672            introduced: None,
2673            effective_severity: None,
2674        }
2675    }
2676}
2677
2678/// Wire-shape envelope for a [`RouteCollision`] finding. A route collision is a
2679/// guaranteed `next build` failure, so the PRIMARY action is manual guidance
2680/// (move or merge one of the colliding files), NOT a suppress: suppressing a
2681/// build error never makes the build pass. A file-level suppress is offered as
2682/// an escape hatch only.
2683#[derive(Debug, Clone, Serialize, Deserialize)]
2684#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2685pub struct RouteCollisionFinding {
2686    /// The underlying route-collision entry.
2687    #[serde(flatten)]
2688    pub collision: RouteCollision,
2689    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2690    /// `~<k>` suffix when several findings of one type share an identity.
2691    /// Line and column are not inputs, so the id survives line shifts,
2692    /// reformats and reorders. A rename of the file or the symbol gives a
2693    /// new id. Absent in output from older versions.
2694    #[serde(default, skip_serializing_if = "Option::is_none")]
2695    pub finding_id: Option<String>,
2696    /// Suggested next steps. Always emitted (possibly empty for
2697    /// forward-compat).
2698    pub actions: Vec<IssueAction>,
2699    /// Set by the audit pass when this finding is introduced relative to
2700    /// the merge-base.
2701    #[serde(default, skip_serializing_if = "Option::is_none")]
2702    pub introduced: Option<AuditIntroduced>,
2703    /// Gate severity of this finding after `rules` and `overrides[].rules`
2704    /// resolve for its path. CI formats read it for the annotation, SARIF
2705    /// and CodeClimate level. Absent in output from older versions. Not
2706    /// part of the finding identity, baseline keys or fingerprints.
2707    #[serde(
2708        default,
2709        skip_serializing_if = "Option::is_none",
2710        deserialize_with = "deserialize_effective_severity"
2711    )]
2712    pub effective_severity: Option<EffectiveSeverity>,
2713}
2714
2715impl RouteCollisionFinding {
2716    /// Build the wrapper from a raw [`RouteCollision`]. The primary action is
2717    /// manual guidance because suppressing a guaranteed build error is never
2718    /// the right fix; a file-level suppress is the escape hatch only.
2719    #[must_use]
2720    pub fn with_actions(collision: RouteCollision) -> Self {
2721        let actions = vec![
2722            IssueAction::Fix(FixAction {
2723                kind: FixActionType::ResolveRouteCollision,
2724                auto_fixable: false,
2725                description: "Two or more files resolve to the same URL. Move or merge one so \
2726                              each URL has a single owner. Route groups `(name)` and parallel \
2727                              slots `@name` are the only legal same-URL shapes."
2728                    .to_string(),
2729                note: Some(
2730                    "Next.js fails the build with \"You cannot have two parallel pages that \
2731                     resolve to the same path\". See the sibling `conflicting_paths` array for \
2732                     the other files that own this URL."
2733                        .to_string(),
2734                ),
2735                available_in_catalogs: None,
2736                suggested_target: None,
2737            }),
2738            IssueAction::SuppressFile(SuppressFileAction {
2739                kind: SuppressFileKind::SuppressFile,
2740                auto_fixable: false,
2741                description: "Escape hatch only: a file-level suppress silences the finding but \
2742                              does NOT make `next build` pass. Prefer moving or merging a file."
2743                    .to_string(),
2744                comment: "// fallow-ignore-file route-collision".to_string(),
2745            }),
2746        ];
2747        Self {
2748            finding_id: None,
2749            collision,
2750            actions,
2751            introduced: None,
2752            effective_severity: None,
2753        }
2754    }
2755}
2756
2757/// Wire-shape envelope for a [`DynamicSegmentNameConflict`] finding. The
2758/// conflict is a Next.js dev / runtime error (`next build` does NOT catch it),
2759/// so the primary action is manual guidance (rename the dynamic segments to a
2760/// single consistent slug name), with a file-level suppress as escape hatch.
2761#[derive(Debug, Clone, Serialize, Deserialize)]
2762#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2763pub struct DynamicSegmentNameConflictFinding {
2764    /// The underlying dynamic-segment-name-conflict entry.
2765    #[serde(flatten)]
2766    pub conflict: DynamicSegmentNameConflict,
2767    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2768    /// `~<k>` suffix when several findings of one type share an identity.
2769    /// Line and column are not inputs, so the id survives line shifts,
2770    /// reformats and reorders. A rename of the file or the symbol gives a
2771    /// new id. Absent in output from older versions.
2772    #[serde(default, skip_serializing_if = "Option::is_none")]
2773    pub finding_id: Option<String>,
2774    /// Suggested next steps. Always emitted (possibly empty for
2775    /// forward-compat).
2776    pub actions: Vec<IssueAction>,
2777    /// Set by the audit pass when this finding is introduced relative to
2778    /// the merge-base.
2779    #[serde(default, skip_serializing_if = "Option::is_none")]
2780    pub introduced: Option<AuditIntroduced>,
2781    /// Gate severity of this finding after `rules` and `overrides[].rules`
2782    /// resolve for its path. CI formats read it for the annotation, SARIF
2783    /// and CodeClimate level. Absent in output from older versions. Not
2784    /// part of the finding identity, baseline keys or fingerprints.
2785    #[serde(
2786        default,
2787        skip_serializing_if = "Option::is_none",
2788        deserialize_with = "deserialize_effective_severity"
2789    )]
2790    pub effective_severity: Option<EffectiveSeverity>,
2791}
2792
2793impl DynamicSegmentNameConflictFinding {
2794    /// Build the wrapper from a raw [`DynamicSegmentNameConflict`]. Manual
2795    /// guidance primary action; file-level suppress escape hatch only.
2796    #[must_use]
2797    pub fn with_actions(conflict: DynamicSegmentNameConflict) -> Self {
2798        let actions = vec![
2799            IssueAction::Fix(FixAction {
2800                kind: FixActionType::ResolveDynamicSegmentNameConflict,
2801                auto_fixable: false,
2802                description: "Sibling dynamic segments at the same position use different param \
2803                              names. Rename them to one consistent slug name (e.g. pick `[id]` \
2804                              or `[slug]` for both)."
2805                    .to_string(),
2806                note: Some(
2807                    "Next.js throws \"You cannot use different slug names for the same dynamic \
2808                     path\" at dev / runtime when the position is hit; `next build` does not \
2809                     catch it. See the sibling `conflicting_segments` array."
2810                        .to_string(),
2811                ),
2812                available_in_catalogs: None,
2813                suggested_target: None,
2814            }),
2815            IssueAction::SuppressFile(SuppressFileAction {
2816                kind: SuppressFileKind::SuppressFile,
2817                auto_fixable: false,
2818                description: "Escape hatch only: a file-level suppress silences the finding but \
2819                              does NOT stop Next.js from throwing at dev / runtime. Prefer \
2820                              renaming the segments."
2821                    .to_string(),
2822                comment: "// fallow-ignore-file dynamic-segment-name-conflict".to_string(),
2823            }),
2824        ];
2825        Self {
2826            finding_id: None,
2827            conflict,
2828            actions,
2829            introduced: None,
2830            effective_severity: None,
2831        }
2832    }
2833}
2834
2835/// Wire-shape envelope for an [`UnusedMember`] finding consumed under the
2836/// `unused_enum_members` key.
2837#[derive(Debug, Clone, Serialize, Deserialize)]
2838#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2839pub struct UnusedEnumMemberFinding {
2840    /// The underlying dead-code entry.
2841    #[serde(flatten)]
2842    pub member: UnusedMember,
2843    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2844    /// `~<k>` suffix when several findings of one type share an identity.
2845    /// Line and column are not inputs, so the id survives line shifts,
2846    /// reformats and reorders. A rename of the file or the symbol gives a
2847    /// new id. Absent in output from older versions.
2848    #[serde(default, skip_serializing_if = "Option::is_none")]
2849    pub finding_id: Option<String>,
2850    /// Suggested next steps. Always emitted (possibly empty for
2851    /// forward-compat).
2852    pub actions: Vec<IssueAction>,
2853    /// Set by the audit pass when this finding is introduced relative to
2854    /// the merge-base.
2855    #[serde(default, skip_serializing_if = "Option::is_none")]
2856    pub introduced: Option<AuditIntroduced>,
2857    /// Gate severity of this finding after `rules` and `overrides[].rules`
2858    /// resolve for its path. CI formats read it for the annotation, SARIF
2859    /// and CodeClimate level. Absent in output from older versions. Not
2860    /// part of the finding identity, baseline keys or fingerprints.
2861    #[serde(
2862        default,
2863        skip_serializing_if = "Option::is_none",
2864        deserialize_with = "deserialize_effective_severity"
2865    )]
2866    pub effective_severity: Option<EffectiveSeverity>,
2867    /// Advisory caveats on the verdict behind this finding. A member's usage
2868    /// is collected by walking the member accesses of every module the run
2869    /// parsed, so a member whose only reference lives in a file the run never
2870    /// read reads as unused exactly like an export does. Sorted,
2871    /// deduplicated, and omitted from the wire when empty. Never gates the
2872    /// finding; it does withhold the `remove-enum-member` mutation.
2873    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2874    pub reachability_caveats: Vec<ReachabilityCaveat>,
2875}
2876
2877impl UnusedEnumMemberFinding {
2878    /// Build the wrapper from a raw [`UnusedMember`].
2879    #[must_use]
2880    pub fn with_actions(member: UnusedMember) -> Self {
2881        let actions = vec![
2882            IssueAction::Fix(FixAction {
2883                kind: FixActionType::RemoveEnumMember,
2884                auto_fixable: true,
2885                description: "Remove this enum member".to_string(),
2886                note: None,
2887                available_in_catalogs: None,
2888                suggested_target: None,
2889            }),
2890            IssueAction::SuppressLine(SuppressLineAction {
2891                kind: SuppressLineKind::SuppressLine,
2892                auto_fixable: false,
2893                description: "Suppress with an inline comment above the line".to_string(),
2894                comment: "// fallow-ignore-next-line unused-enum-member".to_string(),
2895                scope: None,
2896            }),
2897        ];
2898        Self {
2899            finding_id: None,
2900            member,
2901            actions,
2902            introduced: None,
2903            effective_severity: None,
2904            reachability_caveats: Vec::new(),
2905        }
2906    }
2907}
2908
2909/// Wire-shape envelope for an [`UnusedMember`] finding consumed under the
2910/// `unused_class_members` key. Same Rust struct as
2911/// [`UnusedEnumMemberFinding`]; the fix action and suppress comment carry
2912/// the class-member kebab-case identifier instead.
2913#[derive(Debug, Clone, Serialize, Deserialize)]
2914#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
2915pub struct UnusedClassMemberFinding {
2916    /// The underlying dead-code entry.
2917    #[serde(flatten)]
2918    pub member: UnusedMember,
2919    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
2920    /// `~<k>` suffix when several findings of one type share an identity.
2921    /// Line and column are not inputs, so the id survives line shifts,
2922    /// reformats and reorders. A rename of the file or the symbol gives a
2923    /// new id. Absent in output from older versions.
2924    #[serde(default, skip_serializing_if = "Option::is_none")]
2925    pub finding_id: Option<String>,
2926    /// Suggested next steps. Always emitted (possibly empty for
2927    /// forward-compat).
2928    pub actions: Vec<IssueAction>,
2929    /// Type-aware evidence for this exact candidate when requested.
2930    #[serde(default, skip_serializing_if = "Option::is_none")]
2931    pub semantic: Option<SemanticCandidateDecision>,
2932    /// Internal marker for a framework member that the syntactic analysis
2933    /// suppresses, but the semantic pass may promote after proving complete
2934    /// closed-world absence. Never serialized as part of the public finding.
2935    #[serde(skip)]
2936    #[cfg_attr(feature = "schema", schemars(skip))]
2937    pub semantic_only_candidate: bool,
2938    /// Set by the audit pass when this finding is introduced relative to
2939    /// the merge-base.
2940    #[serde(default, skip_serializing_if = "Option::is_none")]
2941    pub introduced: Option<AuditIntroduced>,
2942    /// Gate severity of this finding after `rules` and `overrides[].rules`
2943    /// resolve for its path. CI formats read it for the annotation, SARIF
2944    /// and CodeClimate level. Absent in output from older versions. Not
2945    /// part of the finding identity, baseline keys or fingerprints.
2946    #[serde(
2947        default,
2948        skip_serializing_if = "Option::is_none",
2949        deserialize_with = "deserialize_effective_severity"
2950    )]
2951    pub effective_severity: Option<EffectiveSeverity>,
2952    /// Advisory caveats on the verdict behind this finding. A class member's
2953    /// usage is collected by the same reachability-free member-access walk an
2954    /// enum member's is, so it takes the enum-member rule unchanged: any module
2955    /// this run analyzed incompletely can hold the access that credits it.
2956    /// Sorted, deduplicated, and omitted from the wire when empty. Never gates
2957    /// the finding; it does withhold the `remove-class-member` mutation that
2958    /// the type-aware pass would otherwise open.
2959    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2960    pub reachability_caveats: Vec<ReachabilityCaveat>,
2961}
2962
2963impl UnusedClassMemberFinding {
2964    /// Build the wrapper from a raw [`UnusedMember`]. Class-member fixes
2965    /// are not auto-applied (members can be used via dependency injection
2966    /// or decorators), so `auto_fixable` is `false` and a context note is
2967    /// attached.
2968    #[must_use]
2969    pub fn with_actions(member: UnusedMember) -> Self {
2970        let actions = vec![
2971            IssueAction::Fix(FixAction {
2972                kind: FixActionType::RemoveClassMember,
2973                auto_fixable: false,
2974                description: "Remove this class member".to_string(),
2975                note: Some(
2976                    "Class member may be used via dependency injection or decorators".to_string(),
2977                ),
2978                available_in_catalogs: None,
2979                suggested_target: None,
2980            }),
2981            IssueAction::SuppressLine(SuppressLineAction {
2982                kind: SuppressLineKind::SuppressLine,
2983                auto_fixable: false,
2984                description: "Suppress with an inline comment above the line".to_string(),
2985                comment: "// fallow-ignore-next-line unused-class-member".to_string(),
2986                scope: None,
2987            }),
2988        ];
2989        Self {
2990            finding_id: None,
2991            member,
2992            actions,
2993            semantic: None,
2994            semantic_only_candidate: false,
2995            introduced: None,
2996            effective_severity: None,
2997            reachability_caveats: Vec::new(),
2998        }
2999    }
3000
3001    /// Mark this finding as latent until semantic analysis proves that the
3002    /// framework contract does not apply and no static references exist.
3003    #[must_use]
3004    pub const fn semantic_only_candidate(mut self) -> Self {
3005        self.semantic_only_candidate = true;
3006        self
3007    }
3008
3009    /// Attach the canonical semantic decision and expose the class-member fix
3010    /// only when the API policy granted closed-world eligibility AND this run
3011    /// holds the evidence for the mutation.
3012    ///
3013    /// This is the one code path that RAISES `auto_fixable` on a class member,
3014    /// and it runs in the API layer AFTER the analysis layer stamped the run's
3015    /// caveats, so it asks the gate for the same reason
3016    /// `set_export_semantic_action` does: a closed-world verdict computed
3017    /// over a program the run never fully read must not re-open a removal the
3018    /// incomplete run already withheld. The withheld note names the evidence
3019    /// gap rather than the semantic explanation, which stays readable on the
3020    /// finding's own `semantic` object.
3021    pub fn set_semantic_decision(&mut self, decision: SemanticCandidateDecision) {
3022        let evidence_complete = self.reachability_caveats.is_empty();
3023        if let Some(IssueAction::Fix(action)) = self.actions.first_mut() {
3024            action.auto_fixable = decision.closed_world_eligible && evidence_complete;
3025            action.note = Some(if evidence_complete {
3026                decision.explanation.clone()
3027            } else {
3028                INCOMPLETE_EVIDENCE_NOTE.to_string()
3029            });
3030        }
3031        self.semantic = Some(decision);
3032    }
3033}
3034
3035/// Wire-shape envelope for an [`UnusedMember`] finding consumed under the
3036/// `unused_store_members` key (a Pinia `state` / `getters` / `actions` key, or
3037/// a setup-store returned key, declared but never accessed by any consumer
3038/// project-wide). Same Rust struct as [`UnusedClassMemberFinding`]. Emits only
3039/// a line-level suppress action: there is no safe auto-fix because a store
3040/// member can be accessed reflectively (a Pinia plugin, `store.$onAction`, or
3041/// dynamic dispatch) in ways syntactic analysis cannot see, so removal is a
3042/// behavioral change the user must own.
3043#[derive(Debug, Clone, Serialize, Deserialize)]
3044#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3045pub struct UnusedStoreMemberFinding {
3046    /// The underlying dead-code entry.
3047    #[serde(flatten)]
3048    pub member: UnusedMember,
3049    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3050    /// `~<k>` suffix when several findings of one type share an identity.
3051    /// Line and column are not inputs, so the id survives line shifts,
3052    /// reformats and reorders. A rename of the file or the symbol gives a
3053    /// new id. Absent in output from older versions.
3054    #[serde(default, skip_serializing_if = "Option::is_none")]
3055    pub finding_id: Option<String>,
3056    /// Suggested next steps. Always emitted (possibly empty for
3057    /// forward-compat).
3058    pub actions: Vec<IssueAction>,
3059    /// Set by the audit pass when this finding is introduced relative to
3060    /// the merge-base.
3061    #[serde(default, skip_serializing_if = "Option::is_none")]
3062    pub introduced: Option<AuditIntroduced>,
3063    /// Gate severity of this finding after `rules` and `overrides[].rules`
3064    /// resolve for its path. CI formats read it for the annotation, SARIF
3065    /// and CodeClimate level. Absent in output from older versions. Not
3066    /// part of the finding identity, baseline keys or fingerprints.
3067    #[serde(
3068        default,
3069        skip_serializing_if = "Option::is_none",
3070        deserialize_with = "deserialize_effective_severity"
3071    )]
3072    pub effective_severity: Option<EffectiveSeverity>,
3073    /// Advisory caveats on the verdict behind this finding. A store member's
3074    /// usage is collected by the same reachability-free member-access walk a
3075    /// class member's is, so it takes the member rule unchanged: any module
3076    /// this run analyzed incompletely can hold the access that credits it.
3077    /// Sorted, deduplicated, and omitted from the wire when empty. There is no
3078    /// mutation here to withhold, because a store member offers none on any
3079    /// surface; this is disclosure only, so a reader deciding by hand is told
3080    /// what the run did not see.
3081    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3082    pub reachability_caveats: Vec<ReachabilityCaveat>,
3083}
3084
3085impl UnusedStoreMemberFinding {
3086    /// Build the wrapper from a raw [`UnusedMember`]. Emits only a line-level
3087    /// suppress action (no auto-fix: store members can be accessed
3088    /// reflectively, so removal is never provably safe).
3089    #[must_use]
3090    pub fn with_actions(member: UnusedMember) -> Self {
3091        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
3092            kind: SuppressLineKind::SuppressLine,
3093            auto_fixable: false,
3094            description: "Suppress with an inline comment above the line".to_string(),
3095            comment: "// fallow-ignore-next-line unused-store-member".to_string(),
3096            scope: None,
3097        })];
3098        Self {
3099            finding_id: None,
3100            member,
3101            actions,
3102            introduced: None,
3103            effective_severity: None,
3104            reachability_caveats: Vec::new(),
3105        }
3106    }
3107}
3108
3109/// Wire-shape envelope for an [`UnusedMember`] finding consumed under the
3110/// `unused_namespace_members` key (an exported member of an exported
3111/// TypeScript namespace that no code reads). `member_name` is the dotted path
3112/// from the exported namespace, for example `Inner.x`. Emits only a
3113/// line-level suppress action: a member can be a multi-line function, class
3114/// or nested namespace, so there is no safe one-line auto-fix.
3115#[derive(Debug, Clone, Serialize, Deserialize)]
3116#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3117pub struct UnusedNamespaceMemberFinding {
3118    /// The underlying dead-code entry.
3119    #[serde(flatten)]
3120    pub member: UnusedMember,
3121    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3122    /// `~<k>` suffix when several findings of one type share an identity.
3123    /// Line and column are not inputs, so the id survives line shifts,
3124    /// reformats and reorders. A rename of the file or the symbol gives a
3125    /// new id. Absent in output from older versions.
3126    #[serde(default, skip_serializing_if = "Option::is_none")]
3127    pub finding_id: Option<String>,
3128    /// Suggested next steps. Always emitted (possibly empty for
3129    /// forward-compat).
3130    pub actions: Vec<IssueAction>,
3131    /// Set by the audit pass when this finding is introduced relative to
3132    /// the merge-base.
3133    #[serde(default, skip_serializing_if = "Option::is_none")]
3134    pub introduced: Option<AuditIntroduced>,
3135    /// Gate severity of this finding after `rules` and `overrides[].rules`
3136    /// resolve for its path. CI formats read it for the annotation, SARIF
3137    /// and CodeClimate level. Absent in output from older versions. Not
3138    /// part of the finding identity, baseline keys or fingerprints.
3139    #[serde(
3140        default,
3141        skip_serializing_if = "Option::is_none",
3142        deserialize_with = "deserialize_effective_severity"
3143    )]
3144    pub effective_severity: Option<EffectiveSeverity>,
3145    /// Advisory caveats on the verdict behind this finding. A namespace
3146    /// member takes the member rule unchanged: any module this run analyzed
3147    /// incompletely can hold the access that credits it. Sorted,
3148    /// deduplicated, and omitted from the wire when empty. This is disclosure
3149    /// only, because a namespace member offers no mutation.
3150    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3151    pub reachability_caveats: Vec<ReachabilityCaveat>,
3152}
3153
3154impl UnusedNamespaceMemberFinding {
3155    /// Build the wrapper from a raw [`UnusedMember`]. Emits only a line-level
3156    /// suppress action.
3157    #[must_use]
3158    pub fn with_actions(member: UnusedMember) -> Self {
3159        let actions = vec![IssueAction::SuppressLine(SuppressLineAction {
3160            kind: SuppressLineKind::SuppressLine,
3161            auto_fixable: false,
3162            description: "Suppress with an inline comment above the line".to_string(),
3163            comment: "// fallow-ignore-next-line unused-namespace-member".to_string(),
3164            scope: None,
3165        })];
3166        Self {
3167            finding_id: None,
3168            member,
3169            actions,
3170            introduced: None,
3171            effective_severity: None,
3172            reachability_caveats: Vec::new(),
3173        }
3174    }
3175}
3176
3177/// Build the `IssueAction` vec for the three `unused_dependencies`,
3178/// `unused_dev_dependencies`, `unused_optional_dependencies` views over the
3179/// same bare [`UnusedDependency`] struct. Each wrapper differs only in the
3180/// `package_json_location` string (`"dependencies"` / `"devDependencies"` /
3181/// `"optionalDependencies"`) baked into the fix-action description and in
3182/// the `suppress_issue_kind` used by the inline-suppress comment. All three
3183/// share the cross-workspace swap (when `dep.used_in_workspaces` is
3184/// non-empty the primary fix flips from `remove-dependency` to
3185/// `move-dependency` because the dep is imported by ANOTHER workspace and
3186/// `fallow fix` cannot safely remove it).
3187fn build_unused_dependency_actions(
3188    dep: &UnusedDependency,
3189    package_json_location: &str,
3190    suppress_issue_kind: &str,
3191) -> Vec<IssueAction> {
3192    let mut actions = Vec::with_capacity(2);
3193    let cross_workspace = !dep.used_in_workspaces.is_empty();
3194    actions.push(if cross_workspace {
3195        IssueAction::Fix(FixAction {
3196            kind: FixActionType::MoveDependency,
3197            auto_fixable: false,
3198            description: "Move this dependency to the workspace package.json that imports it"
3199                .to_string(),
3200            note: Some(
3201                "fallow fix will not remove dependencies that are imported by another workspace"
3202                    .to_string(),
3203            ),
3204            available_in_catalogs: None,
3205            suggested_target: None,
3206        })
3207    } else {
3208        IssueAction::Fix(FixAction {
3209            kind: FixActionType::RemoveDependency,
3210            auto_fixable: true,
3211            description: format!("Remove from {package_json_location} in package.json"),
3212            note: None,
3213            available_in_catalogs: None,
3214            suggested_target: None,
3215        })
3216    });
3217    actions.push(build_ignore_dependencies_suppress_action(
3218        &dep.package_name,
3219        suppress_issue_kind,
3220    ));
3221    actions
3222}
3223
3224/// Build the standard `add-to-config` `ignoreDependencies` suppress action
3225/// for any finding whose primary key is a package name. Used by the four
3226/// dependency-family wrappers (unused / unlisted / type-only / test-only).
3227/// The `_suppress_issue_kind` argument is currently unused; the pre-2.76
3228/// `inject_actions` post-pass also did not embed the issue kind in this
3229/// shape (no inline `// fallow-ignore-next-line ...` comment because the
3230/// finding is anchored at a package.json line, not at a source-file line).
3231fn build_ignore_dependencies_suppress_action(
3232    package_name: &str,
3233    _suppress_issue_kind: &str,
3234) -> IssueAction {
3235    IssueAction::AddToConfig(AddToConfigAction {
3236        kind: AddToConfigKind::AddToConfig,
3237        auto_fixable: false,
3238        description: format!("Add \"{package_name}\" to ignoreDependencies in fallow config"),
3239        config_key: "ignoreDependencies".to_string(),
3240        value: AddToConfigValue::Scalar(package_name.to_string()),
3241        value_schema: Some(
3242            "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreDependencies/items"
3243                .to_string(),
3244        ),
3245    })
3246}
3247
3248/// Wire-shape envelope for an [`UnusedDependency`] finding consumed under
3249/// the `unused_dependencies` key (production deps). Flattens the bare
3250/// finding; the typed `actions` array carries either a `remove-dependency`
3251/// or `move-dependency` primary depending on
3252/// `inner.used_in_workspaces`.
3253#[derive(Debug, Clone, Serialize, Deserialize)]
3254#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3255pub struct UnusedDependencyFinding {
3256    /// The underlying dead-code entry.
3257    #[serde(flatten)]
3258    pub dep: UnusedDependency,
3259    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3260    /// `~<k>` suffix when several findings of one type share an identity.
3261    /// Line and column are not inputs, so the id survives line shifts,
3262    /// reformats and reorders. A rename of the file or the symbol gives a
3263    /// new id. Absent in output from older versions.
3264    #[serde(default, skip_serializing_if = "Option::is_none")]
3265    pub finding_id: Option<String>,
3266    /// Suggested next steps. Always emitted (possibly empty for
3267    /// forward-compat).
3268    pub actions: Vec<IssueAction>,
3269    /// Set by the audit pass when this finding is introduced relative to
3270    /// the merge-base.
3271    #[serde(default, skip_serializing_if = "Option::is_none")]
3272    pub introduced: Option<AuditIntroduced>,
3273    /// Gate severity of this finding after `rules` and `overrides[].rules`
3274    /// resolve for its path. CI formats read it for the annotation, SARIF
3275    /// and CodeClimate level. Absent in output from older versions. Not
3276    /// part of the finding identity, baseline keys or fingerprints.
3277    #[serde(
3278        default,
3279        skip_serializing_if = "Option::is_none",
3280        deserialize_with = "deserialize_effective_severity"
3281    )]
3282    pub effective_severity: Option<EffectiveSeverity>,
3283    /// Advisory caveats on the verdict behind this finding. A dependency is
3284    /// reported unused when NO module in the project imports its specifier,
3285    /// so a module that parsed with errors can hide the import that would
3286    /// have credited the package. Sorted, deduplicated, and omitted from the
3287    /// wire when empty. Never gates the finding, though `fallow fix`
3288    /// withholds the `remove-dependency` write while a caveat stands.
3289    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3290    pub reachability_caveats: Vec<ReachabilityCaveat>,
3291}
3292
3293impl UnusedDependencyFinding {
3294    /// Build the wrapper. Switches the primary fix from `remove-dependency`
3295    /// to `move-dependency` when the dep is imported by another workspace.
3296    #[must_use]
3297    pub fn with_actions(dep: UnusedDependency) -> Self {
3298        let actions = build_unused_dependency_actions(&dep, "dependencies", "unused-dependency");
3299        Self {
3300            finding_id: None,
3301            dep,
3302            actions,
3303            introduced: None,
3304            effective_severity: None,
3305            reachability_caveats: Vec::new(),
3306        }
3307    }
3308}
3309
3310/// Wire-shape envelope for an [`UnusedDependency`] finding consumed under
3311/// the `unused_dev_dependencies` key. Same bare struct as
3312/// [`UnusedDependencyFinding`]; the fix description points at
3313/// `devDependencies` and the suppress comment uses
3314/// `unused-dev-dependency`.
3315#[derive(Debug, Clone, Serialize, Deserialize)]
3316#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3317pub struct UnusedDevDependencyFinding {
3318    /// The underlying dead-code entry.
3319    #[serde(flatten)]
3320    pub dep: UnusedDependency,
3321    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3322    /// `~<k>` suffix when several findings of one type share an identity.
3323    /// Line and column are not inputs, so the id survives line shifts,
3324    /// reformats and reorders. A rename of the file or the symbol gives a
3325    /// new id. Absent in output from older versions.
3326    #[serde(default, skip_serializing_if = "Option::is_none")]
3327    pub finding_id: Option<String>,
3328    /// Suggested next steps. Always emitted (possibly empty for
3329    /// forward-compat).
3330    pub actions: Vec<IssueAction>,
3331    /// Set by the audit pass when this finding is introduced relative to
3332    /// the merge-base.
3333    #[serde(default, skip_serializing_if = "Option::is_none")]
3334    pub introduced: Option<AuditIntroduced>,
3335    /// Gate severity of this finding after `rules` and `overrides[].rules`
3336    /// resolve for its path. CI formats read it for the annotation, SARIF
3337    /// and CodeClimate level. Absent in output from older versions. Not
3338    /// part of the finding identity, baseline keys or fingerprints.
3339    #[serde(
3340        default,
3341        skip_serializing_if = "Option::is_none",
3342        deserialize_with = "deserialize_effective_severity"
3343    )]
3344    pub effective_severity: Option<EffectiveSeverity>,
3345    /// Advisory caveats on the verdict behind this finding. A dependency is
3346    /// reported unused when NO module in the project imports its specifier,
3347    /// so a module that parsed with errors can hide the import that would
3348    /// have credited the package. Sorted, deduplicated, and omitted from the
3349    /// wire when empty. Never gates the finding, though `fallow fix`
3350    /// withholds the `remove-dependency` write while a caveat stands.
3351    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3352    pub reachability_caveats: Vec<ReachabilityCaveat>,
3353}
3354
3355impl UnusedDevDependencyFinding {
3356    /// Build the wrapper.
3357    #[must_use]
3358    pub fn with_actions(dep: UnusedDependency) -> Self {
3359        let actions =
3360            build_unused_dependency_actions(&dep, "devDependencies", "unused-dev-dependency");
3361        Self {
3362            finding_id: None,
3363            dep,
3364            actions,
3365            introduced: None,
3366            effective_severity: None,
3367            reachability_caveats: Vec::new(),
3368        }
3369    }
3370}
3371
3372/// Wire-shape envelope for an [`UnusedDependency`] finding consumed under
3373/// the `unused_optional_dependencies` key. Same bare struct as
3374/// [`UnusedDependencyFinding`]; the fix description points at
3375/// `optionalDependencies`. Reuses the `unused-dependency` suppress
3376/// `IssueKind` because there is no dedicated variant for optional deps.
3377#[derive(Debug, Clone, Serialize, Deserialize)]
3378#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3379pub struct UnusedOptionalDependencyFinding {
3380    /// The underlying dead-code entry.
3381    #[serde(flatten)]
3382    pub dep: UnusedDependency,
3383    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3384    /// `~<k>` suffix when several findings of one type share an identity.
3385    /// Line and column are not inputs, so the id survives line shifts,
3386    /// reformats and reorders. A rename of the file or the symbol gives a
3387    /// new id. Absent in output from older versions.
3388    #[serde(default, skip_serializing_if = "Option::is_none")]
3389    pub finding_id: Option<String>,
3390    /// Suggested next steps. Always emitted (possibly empty for
3391    /// forward-compat).
3392    pub actions: Vec<IssueAction>,
3393    /// Set by the audit pass when this finding is introduced relative to
3394    /// the merge-base.
3395    #[serde(default, skip_serializing_if = "Option::is_none")]
3396    pub introduced: Option<AuditIntroduced>,
3397    /// Gate severity of this finding after `rules` and `overrides[].rules`
3398    /// resolve for its path. CI formats read it for the annotation, SARIF
3399    /// and CodeClimate level. Absent in output from older versions. Not
3400    /// part of the finding identity, baseline keys or fingerprints.
3401    #[serde(
3402        default,
3403        skip_serializing_if = "Option::is_none",
3404        deserialize_with = "deserialize_effective_severity"
3405    )]
3406    pub effective_severity: Option<EffectiveSeverity>,
3407    /// Advisory caveats on the verdict behind this finding. A dependency is
3408    /// reported unused when NO module in the project imports its specifier,
3409    /// so a module that parsed with errors can hide the import that would
3410    /// have credited the package. Sorted, deduplicated, and omitted from the
3411    /// wire when empty. Never gates the finding, though `fallow fix`
3412    /// withholds the `remove-dependency` write while a caveat stands.
3413    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3414    pub reachability_caveats: Vec<ReachabilityCaveat>,
3415}
3416
3417impl UnusedOptionalDependencyFinding {
3418    /// Build the wrapper.
3419    #[must_use]
3420    pub fn with_actions(dep: UnusedDependency) -> Self {
3421        let actions =
3422            build_unused_dependency_actions(&dep, "optionalDependencies", "unused-dependency");
3423        Self {
3424            finding_id: None,
3425            dep,
3426            actions,
3427            introduced: None,
3428            effective_severity: None,
3429            reachability_caveats: Vec::new(),
3430        }
3431    }
3432}
3433
3434/// Wire-shape envelope for an [`UnlistedDependency`] finding. Carries an
3435/// `install-dependency` primary (non-auto-fixable) plus the standard
3436/// `ignoreDependencies` config suppress.
3437#[derive(Debug, Clone, Serialize, Deserialize)]
3438#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3439pub struct UnlistedDependencyFinding {
3440    /// The underlying dead-code entry.
3441    #[serde(flatten)]
3442    pub dep: UnlistedDependency,
3443    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3444    /// `~<k>` suffix when several findings of one type share an identity.
3445    /// Line and column are not inputs, so the id survives line shifts,
3446    /// reformats and reorders. A rename of the file or the symbol gives a
3447    /// new id. Absent in output from older versions.
3448    #[serde(default, skip_serializing_if = "Option::is_none")]
3449    pub finding_id: Option<String>,
3450    /// Suggested next steps. Always emitted (possibly empty for
3451    /// forward-compat).
3452    pub actions: Vec<IssueAction>,
3453    /// Set by the audit pass when this finding is introduced relative to
3454    /// the merge-base.
3455    #[serde(default, skip_serializing_if = "Option::is_none")]
3456    pub introduced: Option<AuditIntroduced>,
3457    /// Gate severity of this finding after `rules` and `overrides[].rules`
3458    /// resolve for its path. CI formats read it for the annotation, SARIF
3459    /// and CodeClimate level. Absent in output from older versions. Not
3460    /// part of the finding identity, baseline keys or fingerprints.
3461    #[serde(
3462        default,
3463        skip_serializing_if = "Option::is_none",
3464        deserialize_with = "deserialize_effective_severity"
3465    )]
3466    pub effective_severity: Option<EffectiveSeverity>,
3467}
3468
3469impl UnlistedDependencyFinding {
3470    /// Build the wrapper.
3471    #[must_use]
3472    pub fn with_actions(dep: UnlistedDependency) -> Self {
3473        let actions = vec![
3474            IssueAction::Fix(FixAction {
3475                kind: FixActionType::InstallDependency,
3476                auto_fixable: false,
3477                description: "Add this package to dependencies in package.json".to_string(),
3478                note: Some(
3479                    "Verify this package should be a direct dependency before adding".to_string(),
3480                ),
3481                available_in_catalogs: None,
3482                suggested_target: None,
3483            }),
3484            build_ignore_dependencies_suppress_action(&dep.package_name, "unlisted-dependency"),
3485        ];
3486        Self {
3487            finding_id: None,
3488            dep,
3489            actions,
3490            introduced: None,
3491            effective_severity: None,
3492        }
3493    }
3494}
3495
3496/// Wire-shape envelope for an [`UnlistedBinary`] finding. Carries an
3497/// `install-dependency` primary (non-auto-fixable) plus an `ignoreBinaries`
3498/// config suppress.
3499#[derive(Debug, Clone, Serialize, Deserialize)]
3500#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3501pub struct UnlistedBinaryFinding {
3502    /// The underlying dead-code entry.
3503    #[serde(flatten)]
3504    pub binary: UnlistedBinary,
3505    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3506    /// `~<k>` suffix when several findings of one type share an identity.
3507    /// Line and column are not inputs, so the id survives line shifts,
3508    /// reformats and reorders. Absent in output from older versions.
3509    #[serde(default, skip_serializing_if = "Option::is_none")]
3510    pub finding_id: Option<String>,
3511    /// Suggested next steps. Always emitted (possibly empty for
3512    /// forward-compat).
3513    pub actions: Vec<IssueAction>,
3514    /// Set by the audit pass when this finding is introduced relative to
3515    /// the merge-base.
3516    #[serde(default, skip_serializing_if = "Option::is_none")]
3517    pub introduced: Option<AuditIntroduced>,
3518    /// Gate severity of this finding after `rules` and `overrides[].rules`
3519    /// resolve for its path. CI formats read it for the annotation, SARIF
3520    /// and CodeClimate level. Absent in output from older versions. Not
3521    /// part of the finding identity, baseline keys or fingerprints.
3522    #[serde(
3523        default,
3524        skip_serializing_if = "Option::is_none",
3525        deserialize_with = "deserialize_effective_severity"
3526    )]
3527    pub effective_severity: Option<EffectiveSeverity>,
3528}
3529
3530impl UnlistedBinaryFinding {
3531    /// Build the wrapper.
3532    #[must_use]
3533    pub fn with_actions(binary: UnlistedBinary) -> Self {
3534        let name = &binary.binary_name;
3535        let actions = vec![
3536            IssueAction::Fix(FixAction {
3537                kind: FixActionType::InstallDependency,
3538                auto_fixable: false,
3539                description: "Add the package that provides this binary to devDependencies"
3540                    .to_string(),
3541                note: Some(
3542                    "If the operating system or the CI image provides this binary, add it to ignoreBinaries instead"
3543                        .to_string(),
3544                ),
3545                available_in_catalogs: None,
3546                suggested_target: None,
3547            }),
3548            IssueAction::AddToConfig(AddToConfigAction {
3549                kind: AddToConfigKind::AddToConfig,
3550                auto_fixable: false,
3551                description: format!("Add \"{name}\" to ignoreBinaries in fallow config"),
3552                config_key: "ignoreBinaries".to_string(),
3553                value: AddToConfigValue::Scalar(name.clone()),
3554                value_schema: Some(
3555                    "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreBinaries/items"
3556                        .to_string(),
3557                ),
3558            }),
3559        ];
3560        Self {
3561            finding_id: None,
3562            binary,
3563            actions,
3564            introduced: None,
3565            effective_severity: None,
3566        }
3567    }
3568}
3569
3570/// Wire-shape envelope for a [`TypeOnlyDependency`] finding. Carries a
3571/// `move-to-dev` primary plus the standard `ignoreDependencies` config
3572/// suppress.
3573#[derive(Debug, Clone, Serialize, Deserialize)]
3574#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3575pub struct TypeOnlyDependencyFinding {
3576    /// The underlying dead-code entry.
3577    #[serde(flatten)]
3578    pub dep: TypeOnlyDependency,
3579    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3580    /// `~<k>` suffix when several findings of one type share an identity.
3581    /// Line and column are not inputs, so the id survives line shifts,
3582    /// reformats and reorders. A rename of the file or the symbol gives a
3583    /// new id. Absent in output from older versions.
3584    #[serde(default, skip_serializing_if = "Option::is_none")]
3585    pub finding_id: Option<String>,
3586    /// Suggested next steps. Always emitted (possibly empty for
3587    /// forward-compat).
3588    pub actions: Vec<IssueAction>,
3589    /// Set by the audit pass when this finding is introduced relative to
3590    /// the merge-base.
3591    #[serde(default, skip_serializing_if = "Option::is_none")]
3592    pub introduced: Option<AuditIntroduced>,
3593    /// Gate severity of this finding after `rules` and `overrides[].rules`
3594    /// resolve for its path. CI formats read it for the annotation, SARIF
3595    /// and CodeClimate level. Absent in output from older versions. Not
3596    /// part of the finding identity, baseline keys or fingerprints.
3597    #[serde(
3598        default,
3599        skip_serializing_if = "Option::is_none",
3600        deserialize_with = "deserialize_effective_severity"
3601    )]
3602    pub effective_severity: Option<EffectiveSeverity>,
3603}
3604
3605impl TypeOnlyDependencyFinding {
3606    /// Build the wrapper.
3607    #[must_use]
3608    pub fn with_actions(dep: TypeOnlyDependency) -> Self {
3609        let actions = vec![
3610            IssueAction::Fix(FixAction {
3611                kind: FixActionType::MoveToDev,
3612                auto_fixable: false,
3613                description: "Move to devDependencies (only type imports are used)".to_string(),
3614                note: Some(
3615                    "Type imports are erased at runtime so this dependency is not needed in production"
3616                        .to_string(),
3617                ),
3618                available_in_catalogs: None,
3619                suggested_target: None,
3620            }),
3621            build_ignore_dependencies_suppress_action(&dep.package_name, "type-only-dependency"),
3622        ];
3623        Self {
3624            finding_id: None,
3625            dep,
3626            actions,
3627            introduced: None,
3628            effective_severity: None,
3629        }
3630    }
3631}
3632
3633/// Wire-shape envelope for a [`TestOnlyDependency`] finding. Carries a
3634/// `move-to-dev` primary (different prose than [`TypeOnlyDependencyFinding`])
3635/// plus the standard `ignoreDependencies` config suppress.
3636#[derive(Debug, Clone, Serialize, Deserialize)]
3637#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3638pub struct TestOnlyDependencyFinding {
3639    /// The underlying dead-code entry.
3640    #[serde(flatten)]
3641    pub dep: TestOnlyDependency,
3642    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3643    /// `~<k>` suffix when several findings of one type share an identity.
3644    /// Line and column are not inputs, so the id survives line shifts,
3645    /// reformats and reorders. A rename of the file or the symbol gives a
3646    /// new id. Absent in output from older versions.
3647    #[serde(default, skip_serializing_if = "Option::is_none")]
3648    pub finding_id: Option<String>,
3649    /// Suggested next steps. Always emitted (possibly empty for
3650    /// forward-compat).
3651    pub actions: Vec<IssueAction>,
3652    /// Set by the audit pass when this finding is introduced relative to
3653    /// the merge-base.
3654    #[serde(default, skip_serializing_if = "Option::is_none")]
3655    pub introduced: Option<AuditIntroduced>,
3656    /// Gate severity of this finding after `rules` and `overrides[].rules`
3657    /// resolve for its path. CI formats read it for the annotation, SARIF
3658    /// and CodeClimate level. Absent in output from older versions. Not
3659    /// part of the finding identity, baseline keys or fingerprints.
3660    #[serde(
3661        default,
3662        skip_serializing_if = "Option::is_none",
3663        deserialize_with = "deserialize_effective_severity"
3664    )]
3665    pub effective_severity: Option<EffectiveSeverity>,
3666}
3667
3668impl TestOnlyDependencyFinding {
3669    /// Build the wrapper.
3670    #[must_use]
3671    pub fn with_actions(dep: TestOnlyDependency) -> Self {
3672        let actions = vec![
3673            IssueAction::Fix(FixAction {
3674                kind: FixActionType::MoveToDev,
3675                auto_fixable: false,
3676                description: "Move to devDependencies (only test files import this)".to_string(),
3677                note: Some(
3678                    "Only test files import this package so it does not need to be a production dependency"
3679                        .to_string(),
3680                ),
3681                available_in_catalogs: None,
3682                suggested_target: None,
3683            }),
3684            build_ignore_dependencies_suppress_action(&dep.package_name, "test-only-dependency"),
3685        ];
3686        Self {
3687            finding_id: None,
3688            dep,
3689            actions,
3690            introduced: None,
3691            effective_severity: None,
3692        }
3693    }
3694}
3695
3696/// Wire-shape envelope for a [`DevDependencyInProduction`] finding. Carries a
3697/// `move-to-prod` primary (the promote-side mirror of
3698/// [`TestOnlyDependencyFinding`]'s `move-to-dev`) plus the standard
3699/// `ignoreDependencies` config suppress.
3700#[derive(Debug, Clone, Serialize, Deserialize)]
3701#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3702pub struct DevDependencyInProductionFinding {
3703    /// The underlying dead-code entry.
3704    #[serde(flatten)]
3705    pub dep: DevDependencyInProduction,
3706    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3707    /// `~<k>` suffix when several findings of one type share an identity.
3708    /// Line and column are not inputs, so the id survives line shifts,
3709    /// reformats and reorders. A rename of the file or the symbol gives a
3710    /// new id. Absent in output from older versions.
3711    #[serde(default, skip_serializing_if = "Option::is_none")]
3712    pub finding_id: Option<String>,
3713    /// Suggested next steps. Always emitted (possibly empty for
3714    /// forward-compat).
3715    pub actions: Vec<IssueAction>,
3716    /// Set by the audit pass when this finding is introduced relative to
3717    /// the merge-base.
3718    #[serde(default, skip_serializing_if = "Option::is_none")]
3719    pub introduced: Option<AuditIntroduced>,
3720    /// Gate severity of this finding after `rules` and `overrides[].rules`
3721    /// resolve for its path. CI formats read it for the annotation, SARIF
3722    /// and CodeClimate level. Absent in output from older versions. Not
3723    /// part of the finding identity, baseline keys or fingerprints.
3724    #[serde(
3725        default,
3726        skip_serializing_if = "Option::is_none",
3727        deserialize_with = "deserialize_effective_severity"
3728    )]
3729    pub effective_severity: Option<EffectiveSeverity>,
3730}
3731
3732impl DevDependencyInProductionFinding {
3733    /// Build the wrapper.
3734    #[must_use]
3735    pub fn with_actions(dep: DevDependencyInProduction) -> Self {
3736        let actions = vec![
3737            IssueAction::Fix(FixAction {
3738                kind: FixActionType::MoveToProd,
3739                auto_fixable: false,
3740                description:
3741                    "Move to dependencies if the deployment installs them (production code imports this)"
3742                        .to_string(),
3743                note: Some(
3744                    "A production-only install (`pnpm install --prod`) omits devDependencies, so an import resolved at runtime breaks. A build that inlines the package into its output resolves nothing at runtime, and moving it there can instead make the deployment require an install it did not need"
3745                        .to_string(),
3746                ),
3747                available_in_catalogs: None,
3748                suggested_target: None,
3749            }),
3750            build_ignore_dependencies_suppress_action(
3751                &dep.package_name,
3752                "dev-dependency-in-production",
3753            ),
3754        ];
3755        Self {
3756            finding_id: None,
3757            dep,
3758            actions,
3759            introduced: None,
3760            effective_severity: None,
3761        }
3762    }
3763}
3764
3765// ── Catalog / dep-override family ───────────────────────────────
3766//
3767// These six wrappers replace the legacy `inject_actions` post-pass in
3768// `crates/cli/src/report/json.rs` for the catalog and dependency-override
3769// findings. Each `with_actions(...)` builds the typed `actions` array
3770// directly from the inner struct (and any per-call context such as
3771// `config_fixable`), so the wire shape is identical to the pre-2.76
3772// post-pass output but the Rust compiler now owns the action contract.
3773
3774/// Wire-shape envelope for a [`DuplicateExport`] finding. Carries up to
3775/// three actions in position-locked order: an `add-to-config` `ignoreExports`
3776/// snippet (only when `locations[]` carries at least one path) followed by
3777/// the `remove-duplicate` fix and the multi-location suppress.
3778///
3779/// The `add-to-config` action sits at position 0 because the documented
3780/// primary slot points at the safe, non-destructive path: the shadcn /
3781/// Radix / bits-ui namespace-barrel case where every `index.*` reexports
3782/// the directory's neighbours. The `remove-duplicate` fix stays as the
3783/// secondary so consumers that pattern-match on `actions[0].type` for
3784/// "primary fix" never propose deletion of an intentional barrel surface.
3785#[derive(Debug, Clone, Serialize, Deserialize)]
3786#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3787pub struct DuplicateExportFinding {
3788    /// The underlying finding.
3789    #[serde(flatten)]
3790    pub export: DuplicateExport,
3791    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3792    /// `~<k>` suffix when several findings of one type share an identity.
3793    /// Line and column are not inputs, so the id survives line shifts,
3794    /// reformats and reorders. A rename of the file or the symbol gives a
3795    /// new id. Absent in output from older versions.
3796    #[serde(default, skip_serializing_if = "Option::is_none")]
3797    pub finding_id: Option<String>,
3798    /// Suggested next steps. Always emitted (possibly empty for
3799    /// forward-compat).
3800    pub actions: Vec<IssueAction>,
3801    /// Set by the audit pass when this finding is introduced relative to
3802    /// the merge-base.
3803    #[serde(default, skip_serializing_if = "Option::is_none")]
3804    pub introduced: Option<AuditIntroduced>,
3805    /// Gate severity of this finding after `rules` and `overrides[].rules`
3806    /// resolve for its path. CI formats read it for the annotation, SARIF
3807    /// and CodeClimate level. Absent in output from older versions. Not
3808    /// part of the finding identity, baseline keys or fingerprints.
3809    #[serde(
3810        default,
3811        skip_serializing_if = "Option::is_none",
3812        deserialize_with = "deserialize_effective_severity"
3813    )]
3814    pub effective_severity: Option<EffectiveSeverity>,
3815}
3816
3817impl DuplicateExportFinding {
3818    /// Build the wrapper with the `add-to-config` action's `auto_fixable`
3819    /// defaulting to `false`. The CLI's `build_json_with_config_fixable`
3820    /// path layers the actual `config_fixable` signal via
3821    /// [`Self::set_config_fixable`] right before serialization (the
3822    /// fix-applier readiness check lives in `fallow-cli::fix` and is not
3823    /// reachable from the analyzer layer where wrappers are first built).
3824    /// Embedders that build `AnalysisResults` directly and never route
3825    /// through the CLI's JSON path keep the conservative default.
3826    #[must_use]
3827    pub fn with_actions(export: DuplicateExport) -> Self {
3828        let mut actions: Vec<IssueAction> = Vec::with_capacity(3);
3829
3830        if let Some(rules) = build_duplicate_exports_ignore_rules(&export) {
3831            actions.push(IssueAction::AddToConfig(AddToConfigAction {
3832                kind: AddToConfigKind::AddToConfig,
3833                auto_fixable: false,
3834                description: "Add an ignoreExports rule so these files are excluded from duplicate-export grouping (use when this duplication is an intentional namespace-barrel API).".to_string(),
3835                config_key: "ignoreExports".to_string(),
3836                value: AddToConfigValue::ExportsRules(rules),
3837                value_schema: Some(IGNORE_EXPORTS_VALUE_SCHEMA.to_string()),
3838            }));
3839        }
3840
3841        actions.push(IssueAction::Fix(FixAction {
3842            kind: FixActionType::RemoveDuplicate,
3843            auto_fixable: false,
3844            description: "Keep one canonical export location and remove the others".to_string(),
3845            note: Some(NAMESPACE_BARREL_HINT.to_string()),
3846            available_in_catalogs: None,
3847            suggested_target: None,
3848        }));
3849
3850        actions.push(IssueAction::SuppressLine(SuppressLineAction {
3851            kind: SuppressLineKind::SuppressLine,
3852            auto_fixable: false,
3853            description: "Suppress with an inline comment above the line".to_string(),
3854            comment: "// fallow-ignore-next-line duplicate-export".to_string(),
3855            scope: Some(SuppressLineScope::PerLocation),
3856        }));
3857
3858        Self {
3859            finding_id: None,
3860            export,
3861            actions,
3862            introduced: None,
3863            effective_severity: None,
3864        }
3865    }
3866
3867    /// Update the position-0 `add-to-config` action's `auto_fixable` flag.
3868    /// Idempotent and a no-op when position 0 is not an `add-to-config`
3869    /// action (happens when the finding has no locations). Called by the
3870    /// CLI's JSON serializer with the result of
3871    /// `crate::fix::is_config_fixable` before emitting bytes.
3872    pub fn set_config_fixable(&mut self, fixable: bool) {
3873        if let Some(IssueAction::AddToConfig(action)) = self.actions.first_mut() {
3874            action.auto_fixable = fixable;
3875        }
3876    }
3877}
3878
3879/// Build a paste-ready `ignoreExports` config value from a duplicate-export
3880/// finding's locations. Returns one `{ file, exports: ["*"] }` entry per
3881/// distinct file in insertion order. `None` when no locations carry a path.
3882fn build_duplicate_exports_ignore_rules(
3883    export: &DuplicateExport,
3884) -> Option<Vec<IgnoreExportsRule>> {
3885    let mut entries: Vec<IgnoreExportsRule> = Vec::with_capacity(export.locations.len());
3886    for loc in &export.locations {
3887        // Normalize separators to forward slashes so pasting the action value
3888        // into `.fallowrc.json` produces a portable rule. On Windows
3889        // `to_string_lossy` preserves backslashes, which the old
3890        // `inject_actions` post-pass implicitly normalized because it read
3891        // the path AFTER `strip_root_prefix` had already run through
3892        // `normalize_uri`; the typed wrapper builds the value before
3893        // serialization, so the normalization has to be explicit here.
3894        let path = loc.path.to_string_lossy().replace('\\', "/");
3895        if path.is_empty() {
3896            continue;
3897        }
3898        if entries.iter().any(|existing| existing.file == path) {
3899            continue;
3900        }
3901        entries.push(IgnoreExportsRule {
3902            file: path,
3903            exports: vec!["*".to_string()],
3904        });
3905    }
3906    if entries.is_empty() {
3907        None
3908    } else {
3909        Some(entries)
3910    }
3911}
3912
3913/// Wire-shape envelope for an [`UnusedCatalogEntry`] finding. Per-instance
3914/// `auto_fixable` flips to `false` when `hardcoded_consumers` is non-empty or
3915/// the source is not `pnpm-workspace.yaml`.
3916#[derive(Debug, Clone, Serialize, Deserialize)]
3917#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
3918pub struct UnusedCatalogEntryFinding {
3919    /// The underlying finding.
3920    #[serde(flatten)]
3921    pub entry: UnusedCatalogEntry,
3922    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
3923    /// `~<k>` suffix when several findings of one type share an identity.
3924    /// Line and column are not inputs, so the id survives line shifts,
3925    /// reformats and reorders. A rename of the file or the symbol gives a
3926    /// new id. Absent in output from older versions.
3927    #[serde(default, skip_serializing_if = "Option::is_none")]
3928    pub finding_id: Option<String>,
3929    /// Suggested next steps. Always emitted.
3930    pub actions: Vec<IssueAction>,
3931    /// Set by the audit pass when this finding is introduced relative to
3932    /// the merge-base.
3933    #[serde(default, skip_serializing_if = "Option::is_none")]
3934    pub introduced: Option<AuditIntroduced>,
3935    /// Gate severity of this finding after `rules` and `overrides[].rules`
3936    /// resolve for its path. CI formats read it for the annotation, SARIF
3937    /// and CodeClimate level. Absent in output from older versions. Not
3938    /// part of the finding identity, baseline keys or fingerprints.
3939    #[serde(
3940        default,
3941        skip_serializing_if = "Option::is_none",
3942        deserialize_with = "deserialize_effective_severity"
3943    )]
3944    pub effective_severity: Option<EffectiveSeverity>,
3945}
3946
3947impl UnusedCatalogEntryFinding {
3948    /// Build the wrapper. Per-instance `auto_fixable` is `true` only when
3949    /// `hardcoded_consumers` is empty and the source is `pnpm-workspace.yaml`;
3950    /// otherwise `fallow fix` skips the entry to avoid breaking installs or
3951    /// applying YAML edits to Bun `package.json` catalogs.
3952    #[must_use]
3953    pub fn with_actions(entry: UnusedCatalogEntry) -> Self {
3954        let is_pnpm_source = is_pnpm_catalog_source(&entry.path);
3955        let auto_fixable = entry.hardcoded_consumers.is_empty() && is_pnpm_source;
3956        let note = if is_pnpm_source {
3957            Some(
3958                "If any consumer declares the same package with a hardcoded version, switch the consumer to `catalog:` before removing"
3959                    .to_string(),
3960            )
3961        } else {
3962            Some(
3963                "fallow fix only edits pnpm-workspace.yaml catalog entries. Edit Bun package.json catalogs manually."
3964                    .to_string(),
3965            )
3966        };
3967        let mut actions = vec![IssueAction::Fix(FixAction {
3968            kind: FixActionType::RemoveCatalogEntry,
3969            auto_fixable,
3970            description: if is_pnpm_source {
3971                "Remove the entry from pnpm-workspace.yaml".to_string()
3972            } else {
3973                "Remove the entry from the catalog source file manually".to_string()
3974            },
3975            note,
3976            available_in_catalogs: None,
3977            suggested_target: None,
3978        })];
3979        if is_pnpm_source {
3980            actions.push(IssueAction::SuppressLine(SuppressLineAction {
3981                kind: SuppressLineKind::SuppressLine,
3982                auto_fixable: false,
3983                description: "Suppress with a YAML comment above the line".to_string(),
3984                comment: "# fallow-ignore-next-line unused-catalog-entry".to_string(),
3985                scope: None,
3986            }));
3987        }
3988        Self {
3989            finding_id: None,
3990            entry,
3991            actions,
3992            introduced: None,
3993            effective_severity: None,
3994        }
3995    }
3996}
3997
3998/// Wire-shape envelope for an [`EmptyCatalogGroup`] finding. Carries a
3999/// `remove-empty-catalog-group` primary. YAML-sourced findings also include a
4000/// YAML-comment suppress action.
4001#[derive(Debug, Clone, Serialize, Deserialize)]
4002#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
4003pub struct EmptyCatalogGroupFinding {
4004    /// The underlying finding.
4005    #[serde(flatten)]
4006    pub group: EmptyCatalogGroup,
4007    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
4008    /// `~<k>` suffix when several findings of one type share an identity.
4009    /// Line and column are not inputs, so the id survives line shifts,
4010    /// reformats and reorders. A rename of the file or the symbol gives a
4011    /// new id. Absent in output from older versions.
4012    #[serde(default, skip_serializing_if = "Option::is_none")]
4013    pub finding_id: Option<String>,
4014    /// Suggested next steps. Always emitted.
4015    pub actions: Vec<IssueAction>,
4016    /// Set by the audit pass when this finding is introduced relative to
4017    /// the merge-base.
4018    #[serde(default, skip_serializing_if = "Option::is_none")]
4019    pub introduced: Option<AuditIntroduced>,
4020    /// Gate severity of this finding after `rules` and `overrides[].rules`
4021    /// resolve for its path. CI formats read it for the annotation, SARIF
4022    /// and CodeClimate level. Absent in output from older versions. Not
4023    /// part of the finding identity, baseline keys or fingerprints.
4024    #[serde(
4025        default,
4026        skip_serializing_if = "Option::is_none",
4027        deserialize_with = "deserialize_effective_severity"
4028    )]
4029    pub effective_severity: Option<EffectiveSeverity>,
4030}
4031
4032impl EmptyCatalogGroupFinding {
4033    /// Build the wrapper.
4034    #[must_use]
4035    pub fn with_actions(group: EmptyCatalogGroup) -> Self {
4036        let auto_fixable = is_pnpm_catalog_source(&group.path);
4037        let mut actions = vec![IssueAction::Fix(FixAction {
4038            kind: FixActionType::RemoveEmptyCatalogGroup,
4039            auto_fixable,
4040            description: if auto_fixable {
4041                "Remove the empty named catalog group from pnpm-workspace.yaml".to_string()
4042            } else {
4043                "Remove the empty named catalog group from the catalog source file manually"
4044                    .to_string()
4045            },
4046            note: Some(if auto_fixable {
4047                "Only named groups under `catalogs:` are flagged; the top-level `catalog:` hook is intentionally ignored"
4048                    .to_string()
4049            } else {
4050                "fallow fix only edits pnpm-workspace.yaml catalog groups. Edit Bun package.json catalogs manually."
4051                    .to_string()
4052            }),
4053            available_in_catalogs: None,
4054            suggested_target: None,
4055        })];
4056        if auto_fixable {
4057            actions.push(IssueAction::SuppressLine(SuppressLineAction {
4058                kind: SuppressLineKind::SuppressLine,
4059                auto_fixable: false,
4060                description: "Suppress with a YAML comment above the line".to_string(),
4061                comment: "# fallow-ignore-next-line empty-catalog-group".to_string(),
4062                scope: None,
4063            }));
4064        }
4065        Self {
4066            finding_id: None,
4067            group,
4068            actions,
4069            introduced: None,
4070            effective_severity: None,
4071        }
4072    }
4073}
4074
4075/// Wire-shape envelope for an [`UnresolvedCatalogReference`] finding. The
4076/// primary action at position 0 discriminates on `available_in_catalogs`:
4077/// `add-catalog-entry` when the array is empty (no other catalog declares
4078/// the package), or `update-catalog-reference` when at least one
4079/// alternative exists. When exactly one alternative exists, the action
4080/// also carries `suggested_target` so deterministic agents can land the
4081/// edit without picking from a list.
4082#[derive(Debug, Clone, Serialize, Deserialize)]
4083#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
4084pub struct UnresolvedCatalogReferenceFinding {
4085    /// The underlying finding.
4086    #[serde(flatten)]
4087    pub reference: UnresolvedCatalogReference,
4088    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
4089    /// `~<k>` suffix when several findings of one type share an identity.
4090    /// Line and column are not inputs, so the id survives line shifts,
4091    /// reformats and reorders. A rename of the file or the symbol gives a
4092    /// new id. Absent in output from older versions.
4093    #[serde(default, skip_serializing_if = "Option::is_none")]
4094    pub finding_id: Option<String>,
4095    /// Suggested next steps. Always emitted; position 0 is the discriminated
4096    /// primary (see struct docs).
4097    pub actions: Vec<IssueAction>,
4098    /// Set by the audit pass when this finding is introduced relative to
4099    /// the merge-base.
4100    #[serde(default, skip_serializing_if = "Option::is_none")]
4101    pub introduced: Option<AuditIntroduced>,
4102    /// Gate severity of this finding after `rules` and `overrides[].rules`
4103    /// resolve for its path. CI formats read it for the annotation, SARIF
4104    /// and CodeClimate level. Absent in output from older versions. Not
4105    /// part of the finding identity, baseline keys or fingerprints.
4106    #[serde(
4107        default,
4108        skip_serializing_if = "Option::is_none",
4109        deserialize_with = "deserialize_effective_severity"
4110    )]
4111    pub effective_severity: Option<EffectiveSeverity>,
4112}
4113
4114impl UnresolvedCatalogReferenceFinding {
4115    /// Build the wrapper. The discriminator at position 0 is the
4116    /// `add-catalog-entry` vs `update-catalog-reference` pick documented on
4117    /// the struct.
4118    #[must_use]
4119    pub fn with_actions(reference: UnresolvedCatalogReference) -> Self {
4120        // Normalize separators to forward slashes so the
4121        // `ignoreCatalogReferences.consumer` action value is portable when
4122        // pasted into a Windows-authored config. See
4123        // `build_duplicate_exports_ignore_rules` for the same pattern.
4124        let consumer_path = reference.path.to_string_lossy().replace('\\', "/");
4125        let primary = catalog_reference_primary_action(&reference);
4126        let fallback = remove_catalog_reference_action();
4127        let suppress = suppress_catalog_reference_action(&reference, consumer_path);
4128
4129        Self {
4130            finding_id: None,
4131            reference,
4132            actions: vec![primary, fallback, suppress],
4133            introduced: None,
4134            effective_severity: None,
4135        }
4136    }
4137}
4138
4139fn catalog_reference_primary_action(reference: &UnresolvedCatalogReference) -> IssueAction {
4140    if reference.available_in_catalogs.is_empty() {
4141        return IssueAction::Fix(FixAction {
4142            kind: FixActionType::AddCatalogEntry,
4143            auto_fixable: false,
4144            description: format!(
4145                "Add `{}` to the `{}` catalog in pnpm-workspace.yaml",
4146                reference.entry_name, reference.catalog_name
4147            ),
4148            note: Some(
4149                "Pin a version that satisfies the consumer's import; no other catalog declares this package today"
4150                    .to_string(),
4151            ),
4152            available_in_catalogs: None,
4153            suggested_target: None,
4154        });
4155    }
4156
4157    let available = reference.available_in_catalogs.clone();
4158    let suggested_target = (available.len() == 1).then(|| available[0].clone());
4159    IssueAction::Fix(FixAction {
4160        kind: FixActionType::UpdateCatalogReference,
4161        auto_fixable: false,
4162        description: format!(
4163            "Switch the reference from `catalog:{}` to a catalog that declares `{}`",
4164            reference.catalog_name, reference.entry_name
4165        ),
4166        note: None,
4167        available_in_catalogs: Some(available),
4168        suggested_target,
4169    })
4170}
4171
4172fn remove_catalog_reference_action() -> IssueAction {
4173    IssueAction::Fix(FixAction {
4174        kind: FixActionType::RemoveCatalogReference,
4175        auto_fixable: false,
4176        description: "Remove the catalog reference and pin a hardcoded version in its place"
4177            .to_string(),
4178        note: Some(
4179            "Use only when neither another catalog declares the package nor the named catalog should grow to include it"
4180                .to_string(),
4181        ),
4182        available_in_catalogs: None,
4183        suggested_target: None,
4184    })
4185}
4186
4187fn suppress_catalog_reference_action(
4188    reference: &UnresolvedCatalogReference,
4189    consumer_path: String,
4190) -> IssueAction {
4191    let mut suppress_value = serde_json::Map::new();
4192    suppress_value.insert(
4193        "package".to_string(),
4194        serde_json::Value::String(reference.entry_name.clone()),
4195    );
4196    suppress_value.insert(
4197        "catalog".to_string(),
4198        serde_json::Value::String(reference.catalog_name.clone()),
4199    );
4200    suppress_value.insert(
4201        "consumer".to_string(),
4202        serde_json::Value::String(consumer_path),
4203    );
4204    IssueAction::AddToConfig(AddToConfigAction {
4205        kind: AddToConfigKind::AddToConfig,
4206        auto_fixable: false,
4207        description: "Suppress this reference via ignoreCatalogReferences in fallow config (use when the catalog edit is intentionally landing in a separate PR or the package is a placeholder).".to_string(),
4208        config_key: "ignoreCatalogReferences".to_string(),
4209        value: AddToConfigValue::RuleObject(suppress_value),
4210        value_schema: Some(IGNORE_CATALOG_REFERENCES_VALUE_SCHEMA.to_string()),
4211    })
4212}
4213
4214/// Wire-shape envelope for an [`UnusedDependencyOverride`] finding. Carries
4215/// a `remove-dependency-override` primary plus an `add-to-config`
4216/// `ignoreDependencyOverrides` suppress scoped to the target package and
4217/// declaration source.
4218#[derive(Debug, Clone, Serialize, Deserialize)]
4219#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
4220pub struct UnusedDependencyOverrideFinding {
4221    /// The underlying finding.
4222    #[serde(flatten)]
4223    pub entry: UnusedDependencyOverride,
4224    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
4225    /// `~<k>` suffix when several findings of one type share an identity.
4226    /// Line and column are not inputs, so the id survives line shifts,
4227    /// reformats and reorders. A rename of the file or the symbol gives a
4228    /// new id. Absent in output from older versions.
4229    #[serde(default, skip_serializing_if = "Option::is_none")]
4230    pub finding_id: Option<String>,
4231    /// Suggested next steps. Always emitted.
4232    pub actions: Vec<IssueAction>,
4233    /// Set by the audit pass when this finding is introduced relative to
4234    /// the merge-base.
4235    #[serde(default, skip_serializing_if = "Option::is_none")]
4236    pub introduced: Option<AuditIntroduced>,
4237    /// Gate severity of this finding after `rules` and `overrides[].rules`
4238    /// resolve for its path. CI formats read it for the annotation, SARIF
4239    /// and CodeClimate level. Absent in output from older versions. Not
4240    /// part of the finding identity, baseline keys or fingerprints.
4241    #[serde(
4242        default,
4243        skip_serializing_if = "Option::is_none",
4244        deserialize_with = "deserialize_effective_severity"
4245    )]
4246    pub effective_severity: Option<EffectiveSeverity>,
4247}
4248
4249impl UnusedDependencyOverrideFinding {
4250    /// Build the wrapper.
4251    #[must_use]
4252    pub fn with_actions(entry: UnusedDependencyOverride) -> Self {
4253        let mut actions: Vec<IssueAction> = Vec::with_capacity(2);
4254        actions.push(IssueAction::Fix(FixAction {
4255            kind: FixActionType::RemoveDependencyOverride,
4256            auto_fixable: false,
4257            description: "Remove the package-manager override entry from its declaration source"
4258                .to_string(),
4259            note: Some(
4260                "Conservative static check; verify against the active package manager's frozen-lockfile install before removing in case the override targets a transitive dependency (CVE-fix pattern)"
4261                    .to_string(),
4262            ),
4263            available_in_catalogs: None,
4264            suggested_target: None,
4265        }));
4266
4267        if let Some(suppress) = build_ignore_dependency_overrides_suppress(
4268            Some(&entry.target_package),
4269            &entry.raw_key,
4270            entry.source,
4271        ) {
4272            actions.push(suppress);
4273        }
4274
4275        Self {
4276            finding_id: None,
4277            entry,
4278            actions,
4279            introduced: None,
4280            effective_severity: None,
4281        }
4282    }
4283}
4284
4285/// Wire-shape envelope for a [`MisconfiguredDependencyOverride`] finding.
4286/// Carries a `fix-dependency-override` primary plus the conditional
4287/// `add-to-config` `ignoreDependencyOverrides` suppress (skipped when both
4288/// `target_package` and `raw_key` are empty, since the rule matcher keys on
4289/// a non-empty package name).
4290#[derive(Debug, Clone, Serialize, Deserialize)]
4291#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
4292pub struct MisconfiguredDependencyOverrideFinding {
4293    /// The underlying finding.
4294    #[serde(flatten)]
4295    pub entry: MisconfiguredDependencyOverride,
4296    /// Stable id of this finding: `dc1:<rule>:<16 hex digits>`, with a
4297    /// `~<k>` suffix when several findings of one type share an identity.
4298    /// Line and column are not inputs, so the id survives line shifts,
4299    /// reformats and reorders. A rename of the file or the symbol gives a
4300    /// new id. Absent in output from older versions.
4301    #[serde(default, skip_serializing_if = "Option::is_none")]
4302    pub finding_id: Option<String>,
4303    /// Suggested next steps. Always emitted.
4304    pub actions: Vec<IssueAction>,
4305    /// Set by the audit pass when this finding is introduced relative to
4306    /// the merge-base.
4307    #[serde(default, skip_serializing_if = "Option::is_none")]
4308    pub introduced: Option<AuditIntroduced>,
4309    /// Gate severity of this finding after `rules` and `overrides[].rules`
4310    /// resolve for its path. CI formats read it for the annotation, SARIF
4311    /// and CodeClimate level. Absent in output from older versions. Not
4312    /// part of the finding identity, baseline keys or fingerprints.
4313    #[serde(
4314        default,
4315        skip_serializing_if = "Option::is_none",
4316        deserialize_with = "deserialize_effective_severity"
4317    )]
4318    pub effective_severity: Option<EffectiveSeverity>,
4319}
4320
4321impl MisconfiguredDependencyOverrideFinding {
4322    /// Build the wrapper. The suppress action is omitted when neither
4323    /// `target_package` (set on `EmptyValue` cases) nor `raw_key` provides a
4324    /// non-empty package name; an `ignoreDependencyOverrides` entry with
4325    /// `package: ""` would be silently ignored by the config parser.
4326    #[must_use]
4327    pub fn with_actions(entry: MisconfiguredDependencyOverride) -> Self {
4328        let mut actions: Vec<IssueAction> = Vec::with_capacity(2);
4329        actions.push(IssueAction::Fix(FixAction {
4330            kind: FixActionType::FixDependencyOverride,
4331            auto_fixable: false,
4332            description:
4333                "Fix the package-manager override key or value: invalid entries are rejected or ignored"
4334                    .to_string(),
4335            note: Some(
4336                "Common shapes: bare `pkg`, scoped `@scope/pkg`, version-selector `pkg@<2`, parent-chain `parent>child`. Valid values include semver ranges, `-` (removal), `$ref` (self-ref), and `npm:alias@^1`."
4337                    .to_string(),
4338            ),
4339            available_in_catalogs: None,
4340            suggested_target: None,
4341        }));
4342
4343        if let Some(suppress) = build_ignore_dependency_overrides_suppress(
4344            entry.target_package.as_deref(),
4345            &entry.raw_key,
4346            entry.source,
4347        ) {
4348            actions.push(suppress);
4349        }
4350
4351        Self {
4352            finding_id: None,
4353            entry,
4354            actions,
4355            introduced: None,
4356            effective_severity: None,
4357        }
4358    }
4359}
4360
4361/// Shared `add-to-config` `ignoreDependencyOverrides` builder for the two
4362/// override findings. Returns `None` when no non-empty package name is
4363/// available; the config parser silently drops entries with an empty
4364/// `package` field, so emitting one would be a no-op that misleads agents.
4365fn build_ignore_dependency_overrides_suppress(
4366    target_package: Option<&str>,
4367    raw_key: &str,
4368    source: DependencyOverrideSource,
4369) -> Option<IssueAction> {
4370    let package = target_package
4371        .filter(|s| !s.is_empty())
4372        .or_else(|| Some(raw_key).filter(|s| !s.is_empty()))?
4373        .to_string();
4374    let mut value = serde_json::Map::new();
4375    value.insert("package".to_string(), serde_json::Value::String(package));
4376    value.insert(
4377        "source".to_string(),
4378        serde_json::Value::String(source.as_label().to_string()),
4379    );
4380    Some(IssueAction::AddToConfig(AddToConfigAction {
4381        kind: AddToConfigKind::AddToConfig,
4382        auto_fixable: false,
4383        description: "Suppress this override finding via ignoreDependencyOverrides in fallow config (use for CVE-fix overrides that target a purely-transitive package).".to_string(),
4384        config_key: "ignoreDependencyOverrides".to_string(),
4385        value: AddToConfigValue::RuleObject(value),
4386        value_schema: Some(IGNORE_DEPENDENCY_OVERRIDES_VALUE_SCHEMA.to_string()),
4387    }))
4388}
4389
4390// ── The mutation gate, registered once ──────────────────────────
4391//
4392// Every finding whose reachability verdict a lost import edge can distort.
4393// The analysis layer stamps caveats through `set_reachability_caveats`, which
4394// enforces the gate on the finding's actions in the same call; every mutation
4395// surface reads the answer back through `may_auto_apply_mutation`.
4396impl_caveated_finding!(
4397    UnusedFileFinding,
4398    UnusedExportFinding,
4399    UnusedTypeFinding,
4400    UnusedEnumMemberFinding,
4401    UnusedClassMemberFinding,
4402    UnusedNamespaceMemberFinding,
4403    UnusedStoreMemberFinding,
4404    UnusedDependencyFinding,
4405    UnusedDevDependencyFinding,
4406    UnusedOptionalDependencyFinding,
4407);
4408
4409/// Gate severity of one finding after rule resolution.
4410///
4411/// It is the severity that `rules` and the matching `overrides[].rules` give
4412/// the finding for its path. `--fail-on-issues` raises `warn` to `error`. A
4413/// finding whose rule is `off` is not reported, so there is no `off` value.
4414/// The type is separate from the health `severity` band, which ranks a
4415/// finding and does not gate it.
4416///
4417/// The `fallow dead-code` findings gate fails when a finding is `error`.
4418/// Other gates (regression, stale baseline) decide on their own inputs. Two
4419/// commands differ: the `fallow audit` `new-only` gate fails only on introduced
4420/// findings, so an inherited `error` finding does not fail the audit, and the
4421/// combined command (`fallow` without a subcommand) exits 0 for machine
4422/// formats unless `--fail-on-issues` or `--ci` is set.
4423///
4424/// Complexity findings carry the same type. The `complexity-cyclomatic`,
4425/// `complexity-cognitive` and `complexity-crap` rules set it, and the
4426/// `fallow health` findings gate and the audit verdict read it.
4427#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
4428#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
4429#[serde(rename_all = "lowercase")]
4430pub enum EffectiveSeverity {
4431    /// The finding fails the run.
4432    Error,
4433    /// The finding is reported and does not fail the run.
4434    Warn,
4435}
4436
4437/// Read an optional [`EffectiveSeverity`] and treat an unknown value as absent.
4438///
4439/// A saved report from a newer version can carry a value this version does not
4440/// know. The renderers then use the rule-based level, as for a report without
4441/// the field, and the envelope still loads.
4442///
4443/// # Errors
4444///
4445/// Returns an error only when the input is not valid JSON-like data.
4446pub fn deserialize_effective_severity<'de, D>(
4447    deserializer: D,
4448) -> Result<Option<EffectiveSeverity>, D::Error>
4449where
4450    D: serde::Deserializer<'de>,
4451{
4452    #[derive(Deserialize)]
4453    #[serde(untagged)]
4454    enum Tolerant {
4455        Known(EffectiveSeverity),
4456        Unknown(serde::de::IgnoredAny),
4457    }
4458    Ok(match Option::<Tolerant>::deserialize(deserializer)? {
4459        Some(Tolerant::Known(severity)) => Some(severity),
4460        Some(Tolerant::Unknown(_)) | None => None,
4461    })
4462}
4463
4464/// A finding wrapper that carries an [`EffectiveSeverity`].
4465///
4466/// The analysis layer writes the value one time after rule resolution. CI
4467/// renderers read it and fall back to the rule-level severity when it is
4468/// absent, for example in a saved report from an older version.
4469pub trait GatedFinding {
4470    /// The gate severity, or `None` when no value was written.
4471    fn effective_severity(&self) -> Option<EffectiveSeverity>;
4472
4473    /// Write the gate severity.
4474    fn set_effective_severity(&mut self, severity: Option<EffectiveSeverity>);
4475}
4476
4477/// Implement [`GatedFinding`] for wrappers with an `effective_severity` field.
4478macro_rules! impl_gated_finding {
4479    ($($finding:ty),+ $(,)?) => {
4480        $(
4481            impl GatedFinding for $finding {
4482                fn effective_severity(&self) -> Option<EffectiveSeverity> {
4483                    self.effective_severity
4484                }
4485
4486                fn set_effective_severity(&mut self, severity: Option<EffectiveSeverity>) {
4487                    self.effective_severity = severity;
4488                }
4489            }
4490        )+
4491    };
4492}
4493
4494impl_gated_finding!(
4495    UnusedFileFinding,
4496    PrivateTypeLeakFinding,
4497    DeprecatedExportInUseFinding,
4498    UnresolvedImportFinding,
4499    CircularDependencyFinding,
4500    ReExportCycleFinding,
4501    PackageCycleFinding,
4502    BoundaryViolationFinding,
4503    BoundaryCoverageViolationFinding,
4504    BoundaryCallViolationFinding,
4505    UnusedExportFinding,
4506    UnusedTypeFinding,
4507    InvalidClientExportFinding,
4508    MixedClientServerBarrelFinding,
4509    MisplacedDirectiveFinding,
4510    UnprovidedInjectFinding,
4511    UnusedServerActionFinding,
4512    UnusedLoadDataKeyFinding,
4513    UnrenderedComponentFinding,
4514    UnusedComponentPropFinding,
4515    AbsentComponentPropFinding,
4516    UnusedComponentEmitFinding,
4517    UnusedSvelteEventFinding,
4518    UnusedEffectLayerFinding,
4519    UnusedTaggedErrorFinding,
4520    UnproducedCatchTagFinding,
4521    UnusedComponentInputFinding,
4522    UnusedComponentOutputFinding,
4523    RouteCollisionFinding,
4524    DynamicSegmentNameConflictFinding,
4525    UnusedEnumMemberFinding,
4526    UnusedClassMemberFinding,
4527    UnusedNamespaceMemberFinding,
4528    UnusedStoreMemberFinding,
4529    UnusedDependencyFinding,
4530    UnusedDevDependencyFinding,
4531    UnusedOptionalDependencyFinding,
4532    UnlistedDependencyFinding,
4533    UnlistedBinaryFinding,
4534    TypeOnlyDependencyFinding,
4535    TestOnlyDependencyFinding,
4536    DevDependencyInProductionFinding,
4537    DuplicateExportFinding,
4538    DuplicateExportAliasFinding,
4539    UnusedCatalogEntryFinding,
4540    EmptyCatalogGroupFinding,
4541    UnresolvedCatalogReferenceFinding,
4542    UnusedDependencyOverrideFinding,
4543    MisconfiguredDependencyOverrideFinding,
4544    PropDrillingChainFinding,
4545    ThinWrapperFinding,
4546    DuplicatePropShapeFinding,
4547    crate::results::StaleSuppression,
4548);
4549
4550// ── Position-0 invariant golden tests ───────────────────────────
4551//
4552// These tests document the load-bearing position-0 semantics that flow
4553// downstream into the GitHub Action / GitLab CI jq scripts, the MCP server
4554// `actions[0].type` pattern-match, and the VS Code LSP code-action
4555// rendering. Snapshot tests assert structural equality; these named tests
4556// document WHY position 0 has a specific value, so a future refactor that
4557// re-orders actions tells you what broke instead of just "the snapshot
4558// changed".
4559#[cfg(test)]
4560#[path = "output_dead_code_caveat_tokens.rs"]
4561mod caveat_tokens;
4562
4563/// The gate, pinned as one property across every finding type rather than as
4564/// one test per mutation surface.
4565///
4566/// Three separate reviewers found three separate mutation paths that had never
4567/// learned about the caveat, because each earlier round fixed the door it
4568/// found. These tests assert the invariant itself: for every dead-code finding
4569/// that can carry a caveat, a caveated finding exposes NO auto-fixable action,
4570/// and an uncaveated one is untouched. Adding a caveated finding type without
4571/// registering it in `impl_caveated_finding!` fails to compile at the
4572/// `set_reachability_caveats` call the annotation pass makes; adding one that
4573/// exposes an auto-fixable mutation and never gets annotated is what
4574/// `every_auto_fixable_dead_code_mutation_is_gated` catches.
4575#[cfg(test)]
4576#[path = "output_dead_code_mutation_gate.rs"]
4577mod mutation_gate;
4578
4579#[cfg(test)]
4580#[path = "output_dead_code_position_0_invariants.rs"]
4581mod position_0_invariants;