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;