Skip to main content

fallow_types/
workspace.rs

1//! Workspace and source-discovery diagnostic data types.
2//!
3//! The serializable `WorkspaceDiagnostic` / `WorkspaceDiagnosticKind` pair
4//! lives here, upstream of both `fallow-config` (which owns the registry and
5//! emission logic and re-exports these types for back-compat) and
6//! `fallow-output` (which embeds `Vec<WorkspaceDiagnostic>` in its JSON
7//! envelopes). Keeping the data types in `fallow-types` lets the output layer
8//! reference the real, schema-bearing type instead of an opaque
9//! `serde_json::Value` newtype, so `workspace_diagnostics[]` keeps its typed
10//! `kind`/`path`/`message` shape (and the typed `kind` oneOf) in
11//! `docs/output-schema.json` without coupling output contracts to config
12//! loading.
13
14use std::path::{Path, PathBuf};
15
16use rustc_hash::FxHashSet;
17#[cfg(feature = "schema")]
18use schemars::JsonSchema;
19use serde::{Deserialize, Serialize};
20
21use crate::path_util::display_relative;
22use crate::serde_path;
23
24#[path = "workspace_config_entry.rs"]
25mod config_entry;
26#[path = "workspace_plugin_text.rs"]
27mod plugin_text;
28
29pub use config_entry::{OVERRIDE_REASON_BASE_RULE_OFF, OVERRIDE_REASON_PROJECT_LEVEL};
30
31/// Why the declared pnpm version ignores the `overrides` section of
32/// `pnpm-workspace.yaml`.
33#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
34#[cfg_attr(feature = "schema", derive(JsonSchema))]
35#[serde(rename_all = "kebab-case")]
36pub enum PnpmWorkspaceOverridesIgnoredCause {
37    /// pnpm 10 or earlier, and the root `package.json` declares non-empty
38    /// `pnpm.overrides` or `resolutions`. pnpm uses these entries in place
39    /// of the `pnpm-workspace.yaml` overrides.
40    PackageJsonOverrides,
41    /// pnpm before 10.5.1, which does not read the `overrides` section of
42    /// `pnpm-workspace.yaml`.
43    PnpmVersion,
44}
45
46/// Whether the project had a `node_modules` directory at a point in time.
47///
48/// A dead-code baseline records this when it is saved, so a later run in a
49/// different install state can say that its results can differ.
50#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
51#[cfg_attr(feature = "schema", derive(JsonSchema))]
52#[serde(rename_all = "kebab-case")]
53pub enum NodeModulesState {
54    /// `node_modules` existed, or the project legitimately runs without it.
55    Present,
56    /// `node_modules` did not exist.
57    Missing,
58}
59
60impl NodeModulesState {
61    /// The wire token, as it appears in JSON.
62    #[must_use]
63    pub const fn as_str(self) -> &'static str {
64        match self {
65            Self::Present => "present",
66            Self::Missing => "missing",
67        }
68    }
69}
70
71/// Why a workspace-discovery candidate was rejected, or why a sibling
72/// directory looked workspace-like but was not declared.
73///
74/// Wire-format names are kebab-case so JSON consumers (CI integrations, MCP
75/// agents, LSP clients) get a stable, language-neutral identifier.
76#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
77#[cfg_attr(feature = "schema", derive(JsonSchema))]
78#[serde(tag = "kind", rename_all = "kebab-case")]
79pub enum WorkspaceDiagnosticKind {
80    /// A directory contains `package.json` but is not declared as a workspace
81    /// in `package.json` `workspaces`, `pnpm-workspace.yaml`, or
82    /// `tsconfig.json` `references`. Surfaced by
83    /// `find_undeclared_workspaces`.
84    UndeclaredWorkspace,
85    /// A declared workspace's `package.json` failed to parse. The directory is
86    /// dropped from discovery, but analysis still proceeds (degraded).
87    MalformedPackageJson {
88        /// `serde_json` parse error text.
89        error: String,
90    },
91    /// A workspace glob pattern matched a directory that contains no
92    /// `package.json`. Honors the extended skip list and `ignorePatterns`
93    /// before emitting.
94    GlobMatchedNoPackageJson {
95        /// The glob pattern that matched the directory.
96        pattern: String,
97    },
98    /// A workspace entry is an absolute path or has `..` segments that lead
99    /// above the project root, so it can name directories outside the root. Fallow skips the entry
100    /// before it reads the disk and analyzes no package from it. `path` is
101    /// the file that declares the entry (`package.json`,
102    /// `pnpm-workspace.yaml`, `deno.json` or `deno.jsonc`), or the project
103    /// root for an entry of the fallow config `workspaces.patterns`. The
104    /// diagnostic never names a directory outside the root.
105    ///
106    /// npm, pnpm and yarn accept such an entry, so fallow does not exit with
107    /// an error on it. The project root is the security boundary of a run.
108    WorkspaceGlobOutsideRoot {
109        /// The workspace entry, as written in the file.
110        pattern: String,
111    },
112    /// A positive workspace pattern names a directory that does not exist.
113    /// The check reads the literal part of the pattern before the first
114    /// segment with a glob character (`vite` for `vite/packages/*`). A pattern
115    /// without a literal part (`**/pkg`) never gets this diagnostic, and a
116    /// literal directory that exists but holds no package does not get it
117    /// either. `path` is the file that declares the pattern, or the project
118    /// root for an entry of the fallow config `workspaces.patterns`.
119    ///
120    /// A repository that clones other repositories into the workspace in CI
121    /// declares such patterns. The packages there can consume catalog
122    /// entries, so the run does not report `unused-catalog-entries` while a
123    /// pattern of this kind exists. For a `packages` entry of the
124    /// `pnpm-workspace.yaml` of a nested pnpm project, the pattern is
125    /// relative to that file, and the run does not report the unused entries
126    /// of that catalog only.
127    WorkspacePatternDirMissing {
128        /// The workspace pattern, as written in the file.
129        pattern: String,
130    },
131    /// A directory has its own `package.json` and `pnpm-workspace.yaml`, and
132    /// no workspace pattern of the root manifests declares it. pnpm installs
133    /// it as an independent project. Fallow analyzes it as a workspace, so its
134    /// `package.json` owns its files and dependencies. The members that the
135    /// `packages` list of its `pnpm-workspace.yaml` declares are workspaces
136    /// too. The `catalog:` references of the project and its members resolve
137    /// against its own catalog, not against the root catalog.
138    ///
139    /// Information only: nothing is lost from the analysis, so
140    /// `degrades_analysis` is false.
141    NestedProjectRoot,
142    /// The root `tsconfig.json`, or a config in its `extends` chain, exists
143    /// but failed to parse. `path` names the file that failed. Fallow ignores
144    /// the project references, path aliases and compiler options of that file.
145    MalformedTsconfig {
146        /// JSONC parse error text.
147        error: String,
148    },
149    /// `tsconfig.json` lists a `references[].path` that does not point to an
150    /// existing directory.
151    TsconfigReferenceDirMissing,
152    /// `pnpm-workspace.yaml` exists but failed to parse as YAML. The catalog
153    /// checks are skipped and dependency-override analysis proceeds without
154    /// the file's entries (degraded) until the syntax is fixed.
155    MalformedPnpmWorkspaceYaml {
156        /// YAML parse error text.
157        error: String,
158    },
159    /// A source file was skipped at discovery because it exceeds the configured
160    /// per-file size limit (`--max-file-size` / `FALLOW_MAX_FILE_SIZE`, default
161    /// 5 MB). The file is never read, parsed, or analyzed, guarding against the
162    /// out-of-memory blowup a single multi-MB generated/vendored/bundled file
163    /// causes (issue #1086). Surfaced by source discovery, not workspace
164    /// discovery, but shares this channel so the skip is visible in
165    /// `workspace_diagnostics[]` on `fallow dead-code / dupes / health` JSON.
166    SkippedLargeFile {
167        /// On-disk size of the skipped file in bytes.
168        size_bytes: u64,
169    },
170    /// A large JavaScript bundle was skipped at discovery because it appears to
171    /// be minified generated output. The file is never parsed or analyzed,
172    /// guarding against sub-limit bundles that can still create very large ASTs
173    /// and extraction payloads (issue #1086). Use `--max-file-size 0` when the
174    /// bundled file really should be analyzed.
175    SkippedMinifiedFile {
176        /// On-disk size of the skipped file in bytes.
177        size_bytes: u64,
178    },
179    /// A dot-prefixed directory was not traversed by source discovery even
180    /// though it contains at least one source file the project has not
181    /// excluded. Hidden directories are skipped by default apart from a small
182    /// convention allowlist (`.storybook`, `.vitepress`, `.well-known`,
183    /// `.changeset`, `.github`) and the directories an active framework plugin
184    /// or a `package.json` script reference contributes, so files inside are
185    /// never parsed and their imports and exports are invisible to every
186    /// analysis. A file, export or dependency that only the directory uses can
187    /// be reported as unused. A `!<dir>/**` entry in `ignorePatterns` adds the
188    /// directory to traversal (issue #2452). Or add the file to `entry`, the
189    /// export to `ignoreExports` or the dependency to `ignoreDependencies` to
190    /// stop that false positive, or add the directory to `ignorePatterns` to
191    /// silence this (issue #461). Running
192    /// fallow with `--root` against the directory analyzes it on its own and
193    /// does not fix the main run (issue #2797).
194    ///
195    /// "Not excluded" is measured the way the run measures it: a directory
196    /// whose contents are gitignored, or excluded by `ignorePatterns`, or (on
197    /// a `--production` run) excluded as test or story files, never earns this
198    /// diagnostic, because the advertised remedies would find nothing there
199    /// either. Generated tool output and non-git VCS metadata are excluded by
200    /// name.
201    ///
202    /// The advisory is best-effort and bounded: one run inspects a fixed
203    /// number of skipped directories with a fixed I/O budget, in sorted path
204    /// order, so a pathological tree yields a deterministic prefix rather than
205    /// an unbounded array or an unbounded scan. The stderr note says "at
206    /// least" when a ceiling bound the run.
207    ///
208    /// Surfaced by source discovery, not workspace discovery, but shares this
209    /// channel so the skip is visible in `workspace_diagnostics[]` on
210    /// `fallow dead-code / dupes / health` JSON.
211    ///
212    /// Unlike the two skipped-file kinds beside it, this one is CAPPED. To
213    /// bound the directory reads the check costs, a run classifies at most 64
214    /// candidate directories and spends at most 1024 directory entries across
215    /// all of them, so on a project that exceeds either ceiling the array is a
216    /// prefix of the skipped directories rather than all of them, and the
217    /// stderr note says "at least N". No measured repository comes close to
218    /// either ceiling. A consumer needing an exact total should run fallow
219    /// with `--root` against the tree rather than infer one from this array.
220    SkippedSourceDotdir,
221    /// A source discovered with a stable [`FileId`](crate::discover::FileId)
222    /// could not be read before parsing. Analysis continues with the remaining
223    /// sparse module IDs and reports the underlying filesystem or UTF-8 error.
224    SourceReadFailure {
225        /// Filesystem or UTF-8 decoding error from `read_to_string`.
226        error: String,
227    },
228    /// A source file was read but parsed with diagnostics, so the module
229    /// extracted from it may be missing imports, exports, or references after
230    /// the first error. Analysis proceeds with the partial module, which is why
231    /// this is reported: an import the parser never saw credits nothing, and its
232    /// target can surface as a confident `unused-file` or `unused-export`
233    /// finding with a `delete-file` or `remove-export` action on it.
234    ///
235    /// Recorded by the parse stage, alongside `source-read-failure`, and never
236    /// used to withhold a finding. oxc reports recoverable errors for valid
237    /// syntax newer than the parser as well as for genuinely broken files, so
238    /// gating findings on this would mute real results project-wide instead of
239    /// just the affected file.
240    ///
241    /// A file that `ignoreFindings` covers is not reported. The user marked it
242    /// as broken on purpose, so its partial parse also adds no caveat to other
243    /// findings and does not count for the parse-error gate.
244    SourceParseDegraded {
245        /// Number of parser diagnostics reported for the file.
246        error_count: u32,
247        /// `true` when the parser abandoned the file instead of recovering, so
248        /// the extracted module is a fragment at best.
249        panicked: bool,
250    },
251    /// A source file nests brackets deeper than the parser cap, or needs more
252    /// stack than fallow reserves, so it was not parsed at all. The file can be
253    /// valid code, so this is not reported as a syntax error, but it degrades
254    /// the run in the same way: its imports credit nothing. It counts for the
255    /// parse-error gate and adds the same caveats as `source-parse-degraded`.
256    SourceNestingTooDeep {
257        /// The bracket nesting cap of the pre-parse scan.
258        limit: u32,
259    },
260    /// Dependency-override resolution was skipped because bun's legacy binary
261    /// `bun.lockb` sits next to this `package.json`, fallow cannot read the
262    /// binary format, and no parseable text lockfile was found to use
263    /// instead: no `bun.lock` that parses, and no readable `pnpm-lock.yaml`,
264    /// `package-lock.json`, or `npm-shrinkwrap.json`. A `yarn.lock` is never
265    /// consulted (yarn ignores `overrides`), so it does not prevent the skip
266    /// either. The manifest declares overrides, so the
267    /// `unused-dependency-overrides` check would otherwise have run; without
268    /// resolution ground truth it would flag every transitive-only pin, so no
269    /// unused-override findings are reported at all (issue #2358). Surfaced
270    /// by the override analysis, not workspace discovery, but shares this
271    /// channel so the skip is visible in `workspace_diagnostics[]` JSON and
272    /// as a stderr warning.
273    BunLockbOverrideResolutionSkipped,
274    /// Dependency-override resolution was skipped because bun's text
275    /// `bun.lock` exists but could not be parsed and no readable pnpm or npm
276    /// lockfile was available as independent resolution ground truth.
277    BunLockOverrideResolutionSkipped,
278    /// Dependency-override resolution was skipped because `pnpm-lock.yaml`
279    /// exists but could not be parsed, for example because it still holds
280    /// unresolved merge-conflict markers, and no other parseable lockfile was
281    /// available as independent resolution ground truth.
282    PnpmLockOverrideResolutionSkipped,
283    /// Dependency-override resolution was skipped because `package-lock.json`
284    /// or `npm-shrinkwrap.json` exists but could not be parsed, for example
285    /// because it still holds unresolved merge-conflict markers, and no other
286    /// parseable lockfile was available as independent resolution ground
287    /// truth.
288    NpmLockOverrideResolutionSkipped,
289    /// A bun manifest declares both `overrides` and a non-empty `resolutions`
290    /// object. Bun applies `overrides` and ignores `resolutions`, so fallow
291    /// reports the shadowed configuration without offering removal advice.
292    BunResolutionsShadowedByOverrides,
293    /// The declared pnpm version ignores the `overrides` section of
294    /// `pnpm-workspace.yaml`. pnpm does not print a warning. Fallow reports
295    /// no findings for the ignored entries. `cause` tells why pnpm ignores
296    /// the section.
297    PnpmWorkspaceOverridesIgnored {
298        /// Why pnpm ignores the section. The cause decides the remedy.
299        cause: PnpmWorkspaceOverridesIgnoredCause,
300    },
301    /// The project has no `node_modules` directory and is not a Deno project
302    /// that legitimately runs without one. Analysis proceeds, but three things
303    /// degrade silently: package `exports` and conditional exports cannot be
304    /// read, so imports into a dependency's subpaths resolve less precisely;
305    /// framework plugins that activate on an installed package stay inactive,
306    /// so their entry points and path aliases are missing; and a dependency's
307    /// installed shape cannot be inspected, so type-only dependency
308    /// classification falls back to declaration-based heuristics.
309    ///
310    /// Recorded once per run by the source walk, anchored at the missing
311    /// `node_modules` directory so the reported path is a real location rather
312    /// than the empty string a root-anchored diagnostic would render. This used
313    /// to be a bare `tracing::warn!` duplicated in two pipelines, so it never
314    /// reached JSON output and never reached `fallow doctor`, which reported
315    /// `pass` on a tree that had never been installed.
316    NodeModulesMissing,
317    /// `boundaries` is empty while `boundary-violation` is not `off`, so the
318    /// boundary detector never ran. Its summary counters are therefore
319    /// structurally zero and say nothing about the project.
320    ///
321    /// This is the UNCONFIGURED zero, not the user-chosen one: a project that
322    /// sets `boundary-violation: off` asked for silence and can see that
323    /// choice in `fallow config`. A project that left `boundaries` empty
324    /// cannot distinguish "no violations" from "nothing was measured".
325    BoundariesNotConfigured,
326    /// `rulePacks` is empty while `policy-violation` is not `off`, so the
327    /// policy detector never ran and its summary counters are structurally
328    /// zero. The unconfigured counterpart of
329    /// [`Self::BoundariesNotConfigured`].
330    RulePacksNotConfigured,
331    /// One of fallow's built-in discovery ignore patterns (`**/dist/**`,
332    /// `**/build/**`, `**/coverage/**`, and the four minified-bundle globs)
333    /// removed at least one candidate source file from this walk. The files
334    /// are never read, so their imports and exports are invisible to every
335    /// analysis, and until issue #2638 the drop was completely silent:
336    /// pointing fallow at a directory a built-in pattern matches returned a
337    /// clean report with exit 0 and nothing said why.
338    ///
339    /// `**/node_modules/**` is carved out and never appears in `pattern`:
340    /// installed dependencies are not the first-party source this diagnostic
341    /// is about, and a project that does not gitignore them would get a
342    /// five-figure count with no useful remedy. `**/.git/**` cannot fire,
343    /// because hidden directories are not traversed.
344    ///
345    /// One entry per pattern, never per file or per directory, so the array
346    /// grows by at most the number of built-in patterns on a project of any
347    /// size. `path` anchors at the matched directory holding the most excluded
348    /// files for that pattern, ties broken by the lexicographically first
349    /// path, so two runs on one tree report the same location. On a nested
350    /// match it is the DEEPEST segment the pattern matched
351    /// (`build/tools/build`, not `build`), because that is the directory the
352    /// `--root` remedy names and re-rooting at a shallower one would leave a
353    /// matching segment behind. That directory is the
354    /// largest group and not a majority: a flat monorepo can spread ten
355    /// excluded files over ten sibling `dist/` directories and every one of
356    /// them is then "the largest". `file_count` spans all of them, and
357    /// `directory_count` says how many there were, so a reader can tell a
358    /// single tree from a scattered one without a directory list in the
359    /// payload.
360    ///
361    /// Three properties of the population are load-bearing and easy to
362    /// misread:
363    ///
364    /// - **Gitignored trees count zero.** Source discovery honors
365    ///   `.gitignore`, `.git/info/exclude`, and the global gitignore, and
366    ///   prunes those directories before this check runs. The honest reading
367    ///   is "candidate source files git did not already hide and a built-in
368    ///   pattern then dropped", which is why a repository that gitignores its
369    ///   own `dist/` never sees this diagnostic.
370    /// - **A user `ignorePatterns` entry is not a surprise.** The compiled
371    ///   ignore set is the union of `ignorePatterns` and the built-ins, so a
372    ///   file both matched was an explicit project choice and is attributed to
373    ///   no pattern here. A `!` entry in `ignorePatterns` lifts a built-in for
374    ///   the paths it matches (issue #2940), and a lifted file is discovered,
375    ///   so it is never counted here.
376    /// - **The remedy depends on the pattern's shape.** A directory-shaped
377    ///   built-in (`**/dist/**`) is matched against the path relative to the
378    ///   run root, so re-rooting inside the matched directory removes the
379    ///   matched segment and the files become visible: the message advertises
380    ///   `fallow --root <dir>`. A file-shaped built-in (`**/*.min.js` and the
381    ///   three other bundle globs) matches on the file name and keeps matching
382    ///   at any root, so the message says so and points at renaming instead of
383    ///   handing out a command that provably does nothing.
384    ///
385    /// Deliberately NOT one of the [`Self::source_never_analyzed`] kinds. These
386    /// exclusions are the product's designed behavior on generated output, not
387    /// a degraded run: answering `true` would attach `IncompleteFileAnalysis`
388    /// and `IncompleteImportGraph` caveats to findings on nearly every project
389    /// that keeps a non-gitignored `dist/` or `coverage/`, and make `fallow
390    /// fix` withhold `delete-file` and `remove-export` actions project-wide.
391    ExcludedByDefaultIgnore {
392        /// The built-in glob that matched, verbatim (for example
393        /// `**/build/**`).
394        pattern: String,
395        /// Candidate source files this pattern excluded in this walk, across
396        /// every directory it matched, not just the one `path` anchors at.
397        /// Exact: the walk counts each excluded candidate once.
398        file_count: u32,
399        /// Distinct directories this pattern matched at, `path` included, and
400        /// not the number of directories that held the files. A
401        /// directory-shaped pattern (`**/dist/**`) matches at the directory it
402        /// names, so an excluded subtree counts once however many nested
403        /// directories inside it held source: a `dist/` holding files in three
404        /// sub-directories reports `1`. A file-shaped pattern (`**/*.min.js`)
405        /// has no directory to collapse to and counts each matched file's own
406        /// parent. Exact either way, and anything above `1` says `path` names
407        /// one matched location out of several.
408        directory_count: u32,
409    },
410    /// The walk finished with no source file to analyze at all, so every
411    /// finding count this run reports is zero because nothing was measured
412    /// rather than because the project is clean (issue #2686).
413    ///
414    /// Distinct from [`Self::ExcludedByDefaultIgnore`], which reports one
415    /// pattern's exclusions and is designed behavior on generated output. The
416    /// alarm is not the exclusion, it is having nothing left afterwards, and
417    /// that condition also fires with no exclusion at all: a docs-only
418    /// repository, a workspace member with no TypeScript, or a path filter that
419    /// matched nothing. `excluded_file_count` names the built-in-ignore
420    /// contribution so the common cause is still attributable, and is `0` when
421    /// no built-in pattern took part.
422    ///
423    /// This is the kind a CI consumer reads to tell "measured zero" from
424    /// "measured nothing": the human report has said so since 3.26.0, but only
425    /// in human format and only under the built-in-ignore cause, so `--quiet
426    /// --format json` saw a clean green either way.
427    NoSourceFilesAnalyzed {
428        /// Candidate source files the built-in ignore patterns removed from
429        /// this walk, summed across every pattern. `0` when the walk found no
430        /// candidate to exclude in the first place.
431        excluded_file_count: u32,
432    },
433    /// Per-file health scoring failed, so the score list is empty and the
434    /// scored-file count is `0` because nothing was measured rather than
435    /// because the project has no files worth scoring. Every score-derived
436    /// number (the average maintainability index, the refactoring targets, the
437    /// hotspot complexity half) is then structurally zero (issue #2689).
438    FileScoresUnavailable {
439        /// Scoring error text.
440        error: String,
441    },
442    /// Churn-based hotspot analysis was skipped, so the hotspots, churn and
443    /// ownership sections report nothing at all. The remaining health sections
444    /// are unaffected.
445    HotspotsSkipped {
446        /// Which input stopped it, as a kebab-case token: `not-a-repository`,
447        /// `no-commits`, `invalid-since` or `churn-file-unreadable`. The set is
448        /// open.
449        ///
450        /// The cause decides the remedy, which is why it is on the wire: a run
451        /// outside a repository is fixed by running fallow inside one, a
452        /// branch without a commit by committing, a malformed `--since` by
453        /// respelling the flag, and a churn file that changed under the run by
454        /// rerunning it. A consumer reading only the kind would offer the first
455        /// remedy for all four.
456        cause: String,
457    },
458    /// Change coupling found no pairs because the history cannot show them.
459    /// The `change_coupling` section is present with an empty `pairs` list,
460    /// and this entry tells why the list is empty.
461    ChangeCouplingSkipped {
462        /// Kebab-case token: `shallow-clone` (the fetched history is
463        /// incomplete) or `too-few-commits` (fewer analyzed commits than the
464        /// minimum revisions of one file). The set is open.
465        cause: String,
466    },
467    /// The repository is a shallow clone, so churn is measured over the fetched
468    /// history only and every hotspot figure is incomplete.
469    ShallowClone {
470        /// `true` when the run also asked for ownership attribution, which a
471        /// shallow clone skews further by inflating single-author dominance.
472        ownership_requested: bool,
473    },
474    /// No commit timestamp was available, so churn recency and ownership
475    /// staleness were measured against the wall clock and drift between two
476    /// runs over the same commit.
477    UnpinnedClock,
478    /// Ownership attribution was requested but its inputs did not load, so
479    /// hotspot entries carry degraded or absent owner signals.
480    OwnershipUnavailable {
481        /// Which input failed, as a kebab-case token: `invalid-bot-pattern` or
482        /// `codeowners-parse-failed`. The set is open.
483        cause: String,
484        /// Underlying error text.
485        error: String,
486    },
487    /// A saved health snapshot could not be read or parsed, so the trend is
488    /// computed over fewer snapshots than the project has on disk and a
489    /// direction can flip on the missing point alone.
490    TrendSnapshotUnreadable {
491        /// Filesystem or JSON error text.
492        error: String,
493    },
494    /// A grouped health run asked for a trend, but the baseline snapshot holds
495    /// no group data that matches this run, so the groups carry no trend. The
496    /// project trend is not affected. `path` names the baseline snapshot.
497    TrendGroupBaselineUnavailable {
498        /// Why the groups have no baseline, as a kebab-case token:
499        /// `snapshot-has-no-groups` or `grouped-by-mismatch`. The set is open.
500        cause: String,
501    },
502    /// A framework plugin read a build config and could not read one of its
503    /// keys in full, so part of what the key declares never reached the
504    /// analysis. `path` names the config file.
505    ///
506    /// The reader is syntactic, so a key whose value is computed at build time
507    /// is invisible to it: a Module Federation `exposes: makeExposes()` or a
508    /// `remotes` map spread from an environment module declares entries this
509    /// run does not know about. The consequence is a finding, not a missing
510    /// number: an unread `exposes` target is not registered as an entry point
511    /// and its file can surface as `unused-file`, and an unread `remotes` alias
512    /// is not treated as provided by a remote container and its import can
513    /// surface as an unlisted dependency.
514    ///
515    /// Recorded by the plugin stage, which runs before analysis and is not
516    /// cached, so the entry is present on a warm cache too. A bare
517    /// `tracing::warn!` from inside the plugin reaches no envelope and no CI
518    /// consumer (issue #2736).
519    ///
520    /// A source file that calls the Module Federation runtime API gets the same
521    /// entry: `path` names the source file, `key` names the runtime function
522    /// (`registerRemotes`, `loadRemote`, `init`, `createInstance`) and
523    /// `reason` is `dynamic-argument` when the call receives a value that is
524    /// not a static literal. The analysis records it from the facts of the
525    /// parse, which a warm cache restores (issue #2795). A `.vue` or `.svelte`
526    /// file gets it for a call in its `<script>` blocks (issue #2876).
527    PluginConfigUnreadable {
528        /// The plugin that read the config, as it labels itself:
529        /// `module-federation` for a standalone `module-federation.config.*`,
530        /// or the bundler plugin (`webpack`, `rspack`, `rsbuild`, `vite`) that
531        /// read the same options inline from its own config.
532        plugin: String,
533        /// The config key that was present and not fully readable (`exposes`,
534        /// `remotes`), or the Module Federation runtime function whose
535        /// argument was not readable (`registerRemotes`, `loadRemote`, `init`,
536        /// `createInstance`). The set is open.
537        key: String,
538        /// Why it could not be read, as a kebab-case token:
539        /// `not-object-literal`, `array-form`, `spread`,
540        /// `unreadable-entries`, `unrecognized-call`,
541        /// `import-target-unreadable` or `dynamic-argument`. The set is open.
542        ///
543        /// The reason decides the remedy, which is why it is on the wire: a
544        /// value that is not an object literal is fixed by writing one, while
545        /// unreadable entries are fixed by naming those entries in the config
546        /// option the message points at.
547        reason: String,
548    },
549    /// A framework plugin read a config key it understands, does not model
550    /// that key's effect, and therefore stood a modeled default down. `path`
551    /// names the config file.
552    ///
553    /// A file can also be the `path`: a Nuxt file that reads `#components` or
554    /// `#imports` in a way fallow cannot narrow to names, such as a spread of
555    /// a namespace import, has `key` set to that module and `reason` set to
556    /// `key-effect-not-modeled`. Every name of the module then counts as used.
557    ///
558    /// The Nuxt auto-import gate is the case this exists for. With
559    /// `autoImports` enabled fallow drops the Nuxt convention entry patterns
560    /// so a genuinely unreferenced convention file is reported, and a
561    /// `components:` or `imports:` block whose effect it cannot model keeps
562    /// them, which silently costs the user the findings they opted in for.
563    ///
564    /// Deliberately NOT one of the [`Self::warns_on_stderr`] kinds. Nothing
565    /// was lost that the run could have measured: the patterns stayed, so
566    /// findings are suppressed rather than invented, and a project in this
567    /// state would otherwise warn on every run forever with "write different
568    /// config" as the only remedy, which is the reason
569    /// `boundaries-not-configured` is off stderr as well.
570    PluginEffectNotModeled {
571        /// The plugin that read the config, as it labels itself (`nuxt`).
572        plugin: String,
573        /// The config key whose effect is not modeled (`components`,
574        /// `imports`), or the virtual module a file reads (`#components`,
575        /// `#imports`). The set is open.
576        key: String,
577        /// Why the effect is not modeled, as a kebab-case token:
578        /// `key-effect-not-modeled` when the key's own value is the reason,
579        /// `config-property-unreadable` when a top-level property of the same
580        /// config file could not be read statically, so no surface in it can
581        /// be classified at all. The set is open.
582        reason: String,
583    },
584    /// Test coverage was auto-detected on disk rather than passed with
585    /// `--coverage`, and `path` names the file that fed the CRAP scores.
586    ///
587    /// Deliberately NOT one of the [`Self::warns_on_stderr`] kinds: nothing
588    /// degraded, the run measured exactly what it found. It is provenance, and
589    /// it is on the wire because a score computed against a file the user did
590    /// not name is not reproducible and nothing else says which file it was.
591    CoverageAutoDetected,
592    /// `fallow flags --retirement` asked for flag age, but the repository is
593    /// a shallow clone. Blame and pickaxe see the fetched history only, so
594    /// every age would be too young. The report gives no age.
595    FlagAgeShallowClone,
596    /// `fallow flags --retirement` asked for flag age, but git history is
597    /// not available. The report gives no age.
598    FlagAgeUnavailable {
599        /// Why no history is available, as a kebab-case token:
600        /// `not-a-repository` or `no-commits`. The set is open.
601        cause: String,
602    },
603    /// A glob in `ignoreDependencies` matched no dependency that a
604    /// `package.json` of the project declares, so the entry had no effect in
605    /// this run. The usual cause is a typo in the scope or the name.
606    ///
607    /// The dead-code run records it only when the unused-dependency check ran
608    /// and the run reports dependency findings. A run filtered to other issue
609    /// types (`--unused-files`) or scoped to files (`--file`) does not record
610    /// it. An exact-name entry never produces it. `path` is the project root.
611    ///
612    /// Not a degraded run: the analysis measured what it was asked to, so
613    /// `degrades_analysis` is false and no finding carries a caveat.
614    IgnoreDependenciesGlobUnmatched {
615        /// The `ignoreDependencies` entry, as written in the config.
616        pattern: String,
617    },
618    /// A pattern in `ignoreFindings` matched no finding of the dead-code run,
619    /// so the entry had no effect in this run. The usual cause is a typo in
620    /// the path.
621    ///
622    /// The pattern is compared with every finding the analysis produced,
623    /// before issue-type filters and scope filters, so a filtered run does not
624    /// make a pattern look unused. `path` is the project root.
625    ///
626    /// Not a degraded run, for the same reason as
627    /// [`Self::IgnoreDependenciesGlobUnmatched`].
628    IgnoreFindingsPatternUnmatched {
629        /// The `ignoreFindings` entry, as written in the config.
630        pattern: String,
631    },
632    /// An `entry` pattern matched only files that another source (a
633    /// `package.json` field or script, a plugin, `dynamicallyLoaded`) makes
634    /// runtime entry points (issue #3824). Not for a pattern that matches no
635    /// file, nor a `--production` run. `path` is the root. Not degraded.
636    EntryPatternRedundant {
637        /// The `entry` pattern, as written in the config.
638        pattern: String,
639    },
640    /// An `ignoreDependencies` entry hid no dependency finding (issue #3824).
641    /// A glob that matches no declared dependency is
642    /// [`Self::IgnoreDependenciesGlobUnmatched`] instead. Same conditions as
643    /// that kind, and not a `--production` run. `path` is the root.
644    IgnoreDependenciesEntryRedundant {
645        /// The `ignoreDependencies` entry, as written in the config.
646        pattern: String,
647    },
648    /// An `ignorePatterns` glob excluded no file that the run would otherwise
649    /// analyze (issue #3824). Never a `!` exception, a glob that names a
650    /// hidden directory, or a `--production` run. A glob for build output has
651    /// an effect only after a build. `path` is the root. Not degraded.
652    IgnorePatternsEntryRedundant {
653        /// The `ignorePatterns` glob, as written in the config.
654        pattern: String,
655    },
656    /// An `overrides` rule cannot change the result (issue #4065). `reason` is
657    /// `project-level` (fallow reads only the top-level severity of the rule)
658    /// or `base-rule-off` (the top-level rule is off after CLI flags, so its
659    /// detector does not run). The token set is open. `path` is the root. Not
660    /// degraded, and no finding or exit code changes.
661    OverrideRuleIneffective {
662        /// The canonical rule name, also when the config uses an alias.
663        rule: String,
664        /// The `overrides[].files` globs, as written in the config.
665        files: Vec<String>,
666        /// Why the rule has no effect, as a kebab-case token.
667        reason: String,
668    },
669    /// An explicit issue-type selection asked for a rule that the config sets
670    /// to `off`, so that check did not run (issue #4067). One entry per rule.
671    /// The opt-in flags that turn their rule on and a run with no selection
672    /// never report it. `path` is the root. Not degraded: the run measured
673    /// what the config asked for, and no finding or exit code changes.
674    RequestedRuleOff {
675        /// The canonical rule name in `rules`.
676        rule: String,
677        /// The canonical CLI selector of the request, such as `--unused-deps`.
678        /// A typed API or MCP request reports the same selector.
679        flag: String,
680    },
681    /// The dead-code baseline was saved in a different install state than
682    /// this run: one of the two runs had `node_modules` and the other did not.
683    /// Findings that need installed packages (dependency, unlisted,
684    /// unresolved-import and script-binary findings) can differ, so the run
685    /// can report baseline findings as new. `path` is the baseline file.
686    ///
687    /// Only a baseline that records its install state can report this. A
688    /// legacy baseline has no record, so the state is unknown.
689    BaselineInstallStateMismatch {
690        /// The install state when the baseline was saved.
691        baseline_node_modules: NodeModulesState,
692        /// The install state of this run.
693        run_node_modules: NodeModulesState,
694    },
695}
696
697impl WorkspaceDiagnosticKind {
698    /// Stable kebab-case identifier used in dedupe keys and tracing payloads.
699    #[must_use]
700    pub const fn id(&self) -> &'static str {
701        match self {
702            Self::UndeclaredWorkspace => "undeclared-workspace",
703            Self::MalformedPackageJson { .. } => "malformed-package-json",
704            Self::GlobMatchedNoPackageJson { .. } => "glob-matched-no-package-json",
705            Self::WorkspaceGlobOutsideRoot { .. } => "workspace-glob-outside-root",
706            Self::WorkspacePatternDirMissing { .. } => "workspace-pattern-dir-missing",
707            Self::NestedProjectRoot => "nested-project-root",
708            Self::MalformedTsconfig { .. } => "malformed-tsconfig",
709            Self::TsconfigReferenceDirMissing => "tsconfig-reference-dir-missing",
710            Self::MalformedPnpmWorkspaceYaml { .. } => "malformed-pnpm-workspace-yaml",
711            Self::SkippedLargeFile { .. } => "skipped-large-file",
712            Self::SkippedMinifiedFile { .. } => "skipped-minified-file",
713            Self::SkippedSourceDotdir => "skipped-source-dotdir",
714            Self::SourceReadFailure { .. } => "source-read-failure",
715            Self::SourceParseDegraded { .. } => "source-parse-degraded",
716            Self::SourceNestingTooDeep { .. } => "source-nesting-too-deep",
717            Self::BunLockbOverrideResolutionSkipped => "bun-lockb-override-resolution-skipped",
718            Self::BunLockOverrideResolutionSkipped => "bun-lock-override-resolution-skipped",
719            Self::PnpmLockOverrideResolutionSkipped => "pnpm-lock-override-resolution-skipped",
720            Self::NpmLockOverrideResolutionSkipped => "npm-lock-override-resolution-skipped",
721            Self::BunResolutionsShadowedByOverrides => "bun-resolutions-shadowed-by-overrides",
722            Self::PnpmWorkspaceOverridesIgnored { .. } => "pnpm-workspace-overrides-ignored",
723            Self::NodeModulesMissing => "node-modules-missing",
724            Self::BoundariesNotConfigured => "boundaries-not-configured",
725            Self::RulePacksNotConfigured => "rule-packs-not-configured",
726            Self::ExcludedByDefaultIgnore { .. } => "excluded-by-default-ignore",
727            Self::NoSourceFilesAnalyzed { .. } => "no-source-files-analyzed",
728            Self::FileScoresUnavailable { .. } => "file-scores-unavailable",
729            Self::HotspotsSkipped { .. } => "hotspots-skipped",
730            Self::ChangeCouplingSkipped { .. } => "change-coupling-skipped",
731            Self::ShallowClone { .. } => "shallow-clone",
732            Self::UnpinnedClock => "unpinned-clock",
733            Self::OwnershipUnavailable { .. } => "ownership-unavailable",
734            Self::TrendSnapshotUnreadable { .. } => "trend-snapshot-unreadable",
735            Self::TrendGroupBaselineUnavailable { .. } => "trend-group-baseline-unavailable",
736            Self::PluginConfigUnreadable { .. } => "plugin-config-unreadable",
737            Self::PluginEffectNotModeled { .. } => "plugin-effect-not-modeled",
738            Self::CoverageAutoDetected => "coverage-auto-detected",
739            Self::FlagAgeShallowClone => "flag-age-shallow-clone",
740            Self::FlagAgeUnavailable { .. } => "flag-age-unavailable",
741            Self::IgnoreDependenciesGlobUnmatched { .. } => "ignore-dependencies-glob-unmatched",
742            Self::IgnoreFindingsPatternUnmatched { .. } => "ignore-findings-pattern-unmatched",
743            Self::EntryPatternRedundant { .. } => "entry-pattern-redundant",
744            Self::IgnoreDependenciesEntryRedundant { .. } => "ignore-dependencies-entry-redundant",
745            Self::IgnorePatternsEntryRedundant { .. } => "ignore-patterns-entry-redundant",
746            Self::OverrideRuleIneffective { .. } => "override-rule-ineffective",
747            Self::RequestedRuleOff { .. } => "requested-rule-off",
748            Self::BaselineInstallStateMismatch { .. } => "baseline-install-state-mismatch",
749        }
750    }
751
752    /// Whether this diagnostic is worth a `tracing::warn!` line on stderr, on
753    /// top of its permanent entry in `workspace_diagnostics[]`.
754    ///
755    /// A warning is for a run whose RESULTS are degraded: something the user
756    /// installed, wrote, or expected did not reach the analysis. The two
757    /// unconfigured-check kinds are not that. They fire in the product's
758    /// default state, on every project that never opted into boundaries or
759    /// rule packs, and they will keep firing forever, because the remedy they
760    /// offer is to write configuration in order to silence a warning about not
761    /// having written configuration. They stay in the structured array, where a
762    /// consumer that wants to distinguish "measured zero" from "measured
763    /// nothing" can read them, and off the stderr surface that every other
764    /// command shares.
765    ///
766    /// `coverage-auto-detected` answers false for a third reason: it reports
767    /// the provenance of an input that DID load, so a consumer sentence about a
768    /// degraded run would state something untrue about it. Its own note is
769    /// printed by the health pipeline.
770    ///
771    /// `plugin-effect-not-modeled` answers false for the first reason: the
772    /// config was readable and nothing the run could have measured was lost,
773    /// so it would warn forever on a project whose `nuxt.config` fallow does
774    /// not model. Its sibling `plugin-config-unreadable` answers true, because
775    /// there a declaration the user wrote did not reach the analysis and
776    /// findings can be wrong in either direction.
777    #[must_use]
778    pub const fn warns_on_stderr(&self) -> bool {
779        match self {
780            Self::BoundariesNotConfigured
781            | Self::RulePacksNotConfigured
782            | Self::ExcludedByDefaultIgnore { .. }
783            | Self::PluginEffectNotModeled { .. }
784            | Self::CoverageAutoDetected
785            | Self::TrendGroupBaselineUnavailable { .. }
786            | Self::ChangeCouplingSkipped { .. }
787            | Self::IgnoreDependenciesGlobUnmatched { .. }
788            | Self::IgnoreFindingsPatternUnmatched { .. }
789            | Self::EntryPatternRedundant { .. }
790            | Self::IgnoreDependenciesEntryRedundant { .. }
791            | Self::IgnorePatternsEntryRedundant { .. }
792            | Self::OverrideRuleIneffective { .. }
793            | Self::RequestedRuleOff { .. }
794            | Self::NestedProjectRoot => false,
795            Self::UndeclaredWorkspace
796            | Self::MalformedPackageJson { .. }
797            | Self::GlobMatchedNoPackageJson { .. }
798            | Self::WorkspaceGlobOutsideRoot { .. }
799            | Self::WorkspacePatternDirMissing { .. }
800            | Self::MalformedTsconfig { .. }
801            | Self::TsconfigReferenceDirMissing
802            | Self::MalformedPnpmWorkspaceYaml { .. }
803            | Self::SkippedLargeFile { .. }
804            | Self::SkippedMinifiedFile { .. }
805            | Self::SkippedSourceDotdir
806            | Self::SourceReadFailure { .. }
807            | Self::SourceParseDegraded { .. }
808            | Self::SourceNestingTooDeep { .. }
809            | Self::BunLockbOverrideResolutionSkipped
810            | Self::BunLockOverrideResolutionSkipped
811            | Self::PnpmLockOverrideResolutionSkipped
812            | Self::NpmLockOverrideResolutionSkipped
813            | Self::BunResolutionsShadowedByOverrides
814            | Self::PnpmWorkspaceOverridesIgnored { .. }
815            | Self::NodeModulesMissing
816            | Self::NoSourceFilesAnalyzed { .. }
817            | Self::FileScoresUnavailable { .. }
818            | Self::HotspotsSkipped { .. }
819            | Self::ShallowClone { .. }
820            | Self::UnpinnedClock
821            | Self::OwnershipUnavailable { .. }
822            | Self::TrendSnapshotUnreadable { .. }
823            | Self::PluginConfigUnreadable { .. }
824            | Self::FlagAgeShallowClone
825            | Self::FlagAgeUnavailable { .. }
826            | Self::BaselineInstallStateMismatch { .. } => true,
827        }
828    }
829
830    /// Whether this diagnostic is produced by SOURCE discovery (the file walk in
831    /// `discover_files`) rather than WORKSPACE discovery (config load). Source-
832    /// discovery diagnostics are APPENDED to the registry after config load, so
833    /// `stash_workspace_diagnostics` must preserve them when it replaces the
834    /// workspace-discovery set, otherwise the per-analysis config re-loads in
835    /// combined-mode (`fallow` with no subcommand re-loads config for check,
836    /// dupes, and health) wipe them before the JSON envelope is built (issue
837    /// #1086).
838    #[must_use]
839    pub const fn is_source_discovery(&self) -> bool {
840        matches!(
841            self,
842            Self::SkippedLargeFile { .. }
843                | Self::SkippedMinifiedFile { .. }
844                | Self::SkippedSourceDotdir
845                | Self::SourceReadFailure { .. }
846                | Self::SourceParseDegraded { .. }
847                | Self::SourceNestingTooDeep { .. }
848                | Self::NodeModulesMissing
849                | Self::ExcludedByDefaultIgnore { .. }
850                | Self::NoSourceFilesAnalyzed { .. }
851        )
852    }
853
854    /// Whether this diagnostic is written by the source file WALK
855    /// (`discover_files`), the subset of [`Self::is_source_discovery`] that a
856    /// walk replaces wholesale for its root. `source-read-failure` is the
857    /// other source-discovery kind and is NOT one of these: the parse stage
858    /// records it after the walk, so it has to keep reaching consumers through
859    /// the registry.
860    ///
861    /// A walk-recorded entry must reach an analysis from its OWN walk's return
862    /// value. Combined mode runs the dead-code and duplication walks under
863    /// `rayon::join` whenever a per-analysis `production` split stops them from
864    /// sharing a file list, so a registry read answers "whichever walk wrote
865    /// last" and varies between runs of the same command (issue #2366).
866    #[must_use]
867    pub const fn is_source_walk_recorded(&self) -> bool {
868        matches!(
869            self,
870            Self::SkippedLargeFile { .. }
871                | Self::SkippedMinifiedFile { .. }
872                | Self::SkippedSourceDotdir
873                | Self::NodeModulesMissing
874                | Self::ExcludedByDefaultIgnore { .. }
875                | Self::NoSourceFilesAnalyzed { .. }
876        )
877    }
878
879    /// Whether this diagnostic reports a source file whose contents this run
880    /// never analyzed, so every import and export the file holds is invisible
881    /// to the module graph.
882    ///
883    /// This is the class `reachability_caveats[]` exists for. A file the run
884    /// never read credits nothing, so the modules it imports surface as
885    /// confident `unused-file` and `unused-export` findings carrying
886    /// `delete-file` and `remove-export` actions, and `fallow fix` would
887    /// otherwise apply the removal against source that still imports the
888    /// target.
889    ///
890    /// All four discovery-side kinds qualify, for the same reason and with the
891    /// same consequence:
892    ///
893    /// - `skipped-large-file` and `skipped-minified-file`: the file is in the
894    ///   project tree and was never opened, so its import list is unknown.
895    /// - `skipped-source-dotdir`: the directory holds at least one source file
896    ///   the project did not exclude, and none of them were traversed. The
897    ///   diagnostic is capped, so it under-reports rather than over-reports;
898    ///   its presence still proves unseen source exists.
899    /// - `source-read-failure`: the file was discovered and then could not be
900    ///   read, so nothing was extracted from it at all.
901    ///
902    /// `source-parse-degraded` is deliberately NOT one of these, though it
903    /// belongs to the same family. Neither is `excluded-by-default-ignore`,
904    /// for a different reason: that one reports designed behavior on generated
905    /// output rather than a degraded run, and its own doc comment carries the
906    /// argument.
907    ///
908    /// `source-parse-degraded`: that file WAS read, so it has a module and
909    /// a graph node and its reachability is observable, which lets the caveat
910    /// pass narrow it: a degraded module that is itself unreachable cannot
911    /// change a reachability verdict. Every kind above has no node to ask (a
912    /// read failure has one with nothing extracted into it), so no narrowing
913    /// is available and the caveat they raise is run-level.
914    ///
915    /// The match is exhaustive on purpose: a new "the run did not see this
916    /// file" kind has to be classified here, and answering `true` is the only
917    /// wiring its findings need in order to inherit both the caveat and the
918    /// `fallow fix` withholding that follows it.
919    #[must_use]
920    pub const fn source_never_analyzed(&self) -> bool {
921        match self {
922            Self::SkippedLargeFile { .. }
923            | Self::SkippedMinifiedFile { .. }
924            | Self::SkippedSourceDotdir
925            | Self::SourceReadFailure { .. } => true,
926            Self::UndeclaredWorkspace
927            | Self::MalformedPackageJson { .. }
928            | Self::GlobMatchedNoPackageJson { .. }
929            | Self::WorkspaceGlobOutsideRoot { .. }
930            | Self::WorkspacePatternDirMissing { .. }
931            | Self::NestedProjectRoot
932            | Self::MalformedTsconfig { .. }
933            | Self::TsconfigReferenceDirMissing
934            | Self::MalformedPnpmWorkspaceYaml { .. }
935            | Self::SourceParseDegraded { .. }
936            | Self::SourceNestingTooDeep { .. }
937            | Self::BunLockbOverrideResolutionSkipped
938            | Self::BunLockOverrideResolutionSkipped
939            | Self::PnpmLockOverrideResolutionSkipped
940            | Self::NpmLockOverrideResolutionSkipped
941            | Self::BunResolutionsShadowedByOverrides
942            | Self::PnpmWorkspaceOverridesIgnored { .. }
943            | Self::NodeModulesMissing
944            | Self::BoundariesNotConfigured
945            | Self::RulePacksNotConfigured
946            | Self::ExcludedByDefaultIgnore { .. }
947            | Self::NoSourceFilesAnalyzed { .. }
948            | Self::FileScoresUnavailable { .. }
949            | Self::HotspotsSkipped { .. }
950            | Self::ChangeCouplingSkipped { .. }
951            | Self::ShallowClone { .. }
952            | Self::UnpinnedClock
953            | Self::OwnershipUnavailable { .. }
954            | Self::TrendSnapshotUnreadable { .. }
955            | Self::TrendGroupBaselineUnavailable { .. }
956            | Self::PluginConfigUnreadable { .. }
957            | Self::PluginEffectNotModeled { .. }
958            | Self::CoverageAutoDetected
959            | Self::FlagAgeShallowClone
960            | Self::FlagAgeUnavailable { .. }
961            | Self::IgnoreDependenciesGlobUnmatched { .. }
962            | Self::IgnoreFindingsPatternUnmatched { .. }
963            | Self::EntryPatternRedundant { .. }
964            | Self::IgnoreDependenciesEntryRedundant { .. }
965            | Self::IgnorePatternsEntryRedundant { .. }
966            | Self::OverrideRuleIneffective { .. }
967            | Self::RequestedRuleOff { .. }
968            | Self::BaselineInstallStateMismatch { .. } => false,
969        }
970    }
971
972    /// Whether this diagnostic is recorded by the ANALYZE stage (the
973    /// dependency-catalog and override detectors) rather than by workspace or
974    /// source discovery. Analysis-stage diagnostics reach the registry through
975    /// `record_workspace_diagnostics` after config load, so
976    /// `stash_workspace_diagnostics` must preserve them across combined-mode's
977    /// per-analysis config re-loads, and every analyze pass clears its previous
978    /// entries before re-recording so a fixed cause drops out on the next run
979    /// (issue #2366). The match is exhaustive on purpose: a new kind must be
980    /// classified here before it compiles.
981    ///
982    /// Classify a kind `true` ONLY when a detector reachable from the dead-code
983    /// analyze pass (`find_dead_code_full`) re-records it, because that pass is
984    /// the single clear site. A kind recorded exclusively by another stage would
985    /// be cleared by the next dead-code pass and never come back.
986    #[must_use]
987    pub const fn is_analysis_stage(&self) -> bool {
988        match self {
989            Self::MalformedPnpmWorkspaceYaml { .. }
990            | Self::BunLockbOverrideResolutionSkipped
991            | Self::BunLockOverrideResolutionSkipped
992            | Self::PnpmLockOverrideResolutionSkipped
993            | Self::NpmLockOverrideResolutionSkipped
994            | Self::BunResolutionsShadowedByOverrides
995            | Self::PnpmWorkspaceOverridesIgnored { .. }
996            | Self::BoundariesNotConfigured
997            | Self::RulePacksNotConfigured => true,
998            Self::UndeclaredWorkspace
999            | Self::MalformedPackageJson { .. }
1000            | Self::GlobMatchedNoPackageJson { .. }
1001            | Self::WorkspaceGlobOutsideRoot { .. }
1002            | Self::WorkspacePatternDirMissing { .. }
1003            | Self::NestedProjectRoot
1004            | Self::MalformedTsconfig { .. }
1005            | Self::TsconfigReferenceDirMissing
1006            | Self::SkippedLargeFile { .. }
1007            | Self::SkippedMinifiedFile { .. }
1008            | Self::SkippedSourceDotdir
1009            | Self::SourceReadFailure { .. }
1010            | Self::SourceParseDegraded { .. }
1011            | Self::SourceNestingTooDeep { .. }
1012            | Self::NodeModulesMissing
1013            | Self::ExcludedByDefaultIgnore { .. }
1014            | Self::NoSourceFilesAnalyzed { .. }
1015            | Self::FileScoresUnavailable { .. }
1016            | Self::HotspotsSkipped { .. }
1017            | Self::ChangeCouplingSkipped { .. }
1018            | Self::ShallowClone { .. }
1019            | Self::UnpinnedClock
1020            | Self::OwnershipUnavailable { .. }
1021            | Self::TrendSnapshotUnreadable { .. }
1022            | Self::TrendGroupBaselineUnavailable { .. }
1023            | Self::PluginConfigUnreadable { .. }
1024            | Self::PluginEffectNotModeled { .. }
1025            | Self::CoverageAutoDetected
1026            | Self::FlagAgeShallowClone
1027            | Self::FlagAgeUnavailable { .. }
1028            | Self::IgnoreDependenciesGlobUnmatched { .. }
1029            | Self::IgnoreFindingsPatternUnmatched { .. }
1030            | Self::EntryPatternRedundant { .. }
1031            | Self::IgnoreDependenciesEntryRedundant { .. }
1032            | Self::IgnorePatternsEntryRedundant { .. }
1033            | Self::OverrideRuleIneffective { .. }
1034            | Self::RequestedRuleOff { .. }
1035            | Self::BaselineInstallStateMismatch { .. } => false,
1036        }
1037    }
1038
1039    /// Whether this diagnostic is recorded by the HEALTH pipeline (scoring,
1040    /// churn, ownership, trend, coverage input resolution) rather than by
1041    /// workspace discovery, source discovery or the analyze stage.
1042    ///
1043    /// Health-stage diagnostics are appended to the registry after config
1044    /// load, so `stash_workspace_diagnostics` must preserve them across
1045    /// combined mode's per-analysis config re-loads, and the health run clears
1046    /// its previous entries before re-recording so a fixed CODEOWNERS drops out
1047    /// on the next run (issue #2689).
1048    ///
1049    /// They are deliberately NOT [`Self::is_analysis_stage`], although they
1050    /// share both of those properties. That predicate additionally means "the
1051    /// dead-code analyze pass re-records this", and the pass clears every kind
1052    /// answering it on entry. Health computes file scores by running that same
1053    /// pass, so a health-stage kind classified there would be wiped mid-run by
1054    /// the analysis it is reporting on.
1055    #[must_use]
1056    pub const fn is_health_stage(&self) -> bool {
1057        match self {
1058            Self::FileScoresUnavailable { .. }
1059            | Self::HotspotsSkipped { .. }
1060            | Self::ChangeCouplingSkipped { .. }
1061            | Self::ShallowClone { .. }
1062            | Self::UnpinnedClock
1063            | Self::OwnershipUnavailable { .. }
1064            | Self::TrendSnapshotUnreadable { .. }
1065            | Self::TrendGroupBaselineUnavailable { .. }
1066            | Self::CoverageAutoDetected => true,
1067            Self::UndeclaredWorkspace
1068            | Self::MalformedPackageJson { .. }
1069            | Self::GlobMatchedNoPackageJson { .. }
1070            | Self::WorkspaceGlobOutsideRoot { .. }
1071            | Self::WorkspacePatternDirMissing { .. }
1072            | Self::NestedProjectRoot
1073            | Self::MalformedTsconfig { .. }
1074            | Self::TsconfigReferenceDirMissing
1075            | Self::MalformedPnpmWorkspaceYaml { .. }
1076            | Self::SkippedLargeFile { .. }
1077            | Self::SkippedMinifiedFile { .. }
1078            | Self::SkippedSourceDotdir
1079            | Self::SourceReadFailure { .. }
1080            | Self::SourceParseDegraded { .. }
1081            | Self::SourceNestingTooDeep { .. }
1082            | Self::BunLockbOverrideResolutionSkipped
1083            | Self::BunLockOverrideResolutionSkipped
1084            | Self::PnpmLockOverrideResolutionSkipped
1085            | Self::NpmLockOverrideResolutionSkipped
1086            | Self::BunResolutionsShadowedByOverrides
1087            | Self::PnpmWorkspaceOverridesIgnored { .. }
1088            | Self::NodeModulesMissing
1089            | Self::BoundariesNotConfigured
1090            | Self::RulePacksNotConfigured
1091            | Self::ExcludedByDefaultIgnore { .. }
1092            | Self::PluginConfigUnreadable { .. }
1093            | Self::PluginEffectNotModeled { .. }
1094            | Self::NoSourceFilesAnalyzed { .. }
1095            | Self::FlagAgeShallowClone
1096            | Self::FlagAgeUnavailable { .. }
1097            | Self::IgnoreDependenciesGlobUnmatched { .. }
1098            | Self::IgnoreFindingsPatternUnmatched { .. }
1099            | Self::EntryPatternRedundant { .. }
1100            | Self::IgnoreDependenciesEntryRedundant { .. }
1101            | Self::IgnorePatternsEntryRedundant { .. }
1102            | Self::OverrideRuleIneffective { .. }
1103            | Self::RequestedRuleOff { .. }
1104            | Self::BaselineInstallStateMismatch { .. } => false,
1105        }
1106    }
1107
1108    /// Whether this diagnostic is recorded by the PLUGIN stage (framework
1109    /// plugins reading their own build configs) rather than by workspace
1110    /// discovery, source discovery, the analyze stage or the health pipeline.
1111    ///
1112    /// Plugin-stage diagnostics are recorded after config load, so
1113    /// `stash_workspace_diagnostics` must preserve them across combined mode's
1114    /// per-analysis config re-loads, and each plugin run replaces the previous
1115    /// run's set so a fixed config drops out on the next run (issue #2736).
1116    ///
1117    /// They are deliberately NOT [`Self::is_analysis_stage`], although they
1118    /// share both of those properties. That predicate additionally means "the
1119    /// dead-code analyze pass re-records this", and the pass clears every kind
1120    /// answering it on entry. Plugins run in the prelude of that same pass, so
1121    /// a plugin-stage kind classified there would be wiped inside the run that
1122    /// produced it.
1123    ///
1124    /// The match is exhaustive on purpose: a new kind must be classified here
1125    /// before it compiles.
1126    #[must_use]
1127    pub const fn is_plugin_stage(&self) -> bool {
1128        match self {
1129            Self::PluginConfigUnreadable { .. } | Self::PluginEffectNotModeled { .. } => true,
1130            Self::UndeclaredWorkspace
1131            | Self::MalformedPackageJson { .. }
1132            | Self::GlobMatchedNoPackageJson { .. }
1133            | Self::WorkspaceGlobOutsideRoot { .. }
1134            | Self::WorkspacePatternDirMissing { .. }
1135            | Self::NestedProjectRoot
1136            | Self::MalformedTsconfig { .. }
1137            | Self::TsconfigReferenceDirMissing
1138            | Self::MalformedPnpmWorkspaceYaml { .. }
1139            | Self::SkippedLargeFile { .. }
1140            | Self::SkippedMinifiedFile { .. }
1141            | Self::SkippedSourceDotdir
1142            | Self::SourceReadFailure { .. }
1143            | Self::SourceParseDegraded { .. }
1144            | Self::SourceNestingTooDeep { .. }
1145            | Self::BunLockbOverrideResolutionSkipped
1146            | Self::BunLockOverrideResolutionSkipped
1147            | Self::PnpmLockOverrideResolutionSkipped
1148            | Self::NpmLockOverrideResolutionSkipped
1149            | Self::BunResolutionsShadowedByOverrides
1150            | Self::PnpmWorkspaceOverridesIgnored { .. }
1151            | Self::NodeModulesMissing
1152            | Self::BoundariesNotConfigured
1153            | Self::RulePacksNotConfigured
1154            | Self::ExcludedByDefaultIgnore { .. }
1155            | Self::NoSourceFilesAnalyzed { .. }
1156            | Self::FileScoresUnavailable { .. }
1157            | Self::HotspotsSkipped { .. }
1158            | Self::ChangeCouplingSkipped { .. }
1159            | Self::ShallowClone { .. }
1160            | Self::UnpinnedClock
1161            | Self::OwnershipUnavailable { .. }
1162            | Self::TrendSnapshotUnreadable { .. }
1163            | Self::TrendGroupBaselineUnavailable { .. }
1164            | Self::CoverageAutoDetected
1165            | Self::FlagAgeShallowClone
1166            | Self::FlagAgeUnavailable { .. }
1167            | Self::IgnoreDependenciesGlobUnmatched { .. }
1168            | Self::IgnoreFindingsPatternUnmatched { .. }
1169            | Self::EntryPatternRedundant { .. }
1170            | Self::IgnoreDependenciesEntryRedundant { .. }
1171            | Self::IgnorePatternsEntryRedundant { .. }
1172            | Self::OverrideRuleIneffective { .. }
1173            | Self::RequestedRuleOff { .. }
1174            | Self::BaselineInstallStateMismatch { .. } => false,
1175        }
1176    }
1177}
1178
1179/// Render a byte count as a megabyte figure with one decimal place for
1180/// human-readable diagnostic messages (e.g. `12.3 MB`).
1181#[must_use]
1182fn format_size_mb(bytes: u64) -> String {
1183    #[expect(
1184        clippy::cast_precision_loss,
1185        reason = "display-only size figure; precision loss past 2^53 bytes is irrelevant"
1186    )]
1187    let mb = bytes as f64 / (1024.0 * 1024.0);
1188    format!("{mb:.1} MB")
1189}
1190
1191/// A diagnostic about a workspace-discovery candidate.
1192///
1193/// The `message` field is a human-readable rendering derived from `kind`. It
1194/// always ends with a concrete next step ("fix the JSON syntax", "remove from
1195/// `workspaces`", "add to `ignorePatterns`") so first-time users have a path
1196/// forward.
1197#[derive(Debug, Clone, Serialize, Deserialize)]
1198#[cfg_attr(feature = "schema", derive(JsonSchema))]
1199pub struct WorkspaceDiagnostic {
1200    /// Path to the directory or file that triggered the diagnostic.
1201    #[serde(serialize_with = "serde_path::serialize")]
1202    pub path: PathBuf,
1203    /// Kind discriminator with the typed payload.
1204    #[serde(flatten)]
1205    pub kind: WorkspaceDiagnosticKind,
1206    /// Human-readable rendering derived from `kind` + `path`. Always ends
1207    /// with a next-step hint.
1208    pub message: String,
1209    /// True when this diagnostic reports a run whose RESULTS are degraded:
1210    /// something the user installed, wrote, or expected did not reach the
1211    /// analysis. Projected from [`WorkspaceDiagnosticKind::warns_on_stderr`],
1212    /// which is the same classification that decides whether the CLI prints a
1213    /// stderr line, so a CI log built from this field and a local non-quiet run
1214    /// say the same thing.
1215    ///
1216    /// Omitted when false, which is what keeps every clean run byte-identical.
1217    /// The two unconfigured-check kinds answer false on purpose: they fire in
1218    /// the product's default state on every project that never opted into
1219    /// boundaries or rule packs, so warning on them would warn forever. So does
1220    /// `excluded-by-default-ignore`, which is designed behavior on generated
1221    /// output; the alarm for that case is `no-source-files-analyzed`.
1222    ///
1223    /// Read this instead of hardcoding a kind allowlist: a degrading kind added
1224    /// in a later release then reaches an unchanged consumer.
1225    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1226    pub degrades_analysis: bool,
1227}
1228
1229impl WorkspaceDiagnostic {
1230    /// Construct a diagnostic with the message rendered from `kind` + `path`.
1231    ///
1232    /// `root` is used to produce project-relative paths in the message text
1233    /// AND inside the variant payload (e.g. the `error` field of
1234    /// `MalformedPackageJson` / `MalformedTsconfig` which embed the absolute
1235    /// file path from `PackageJson::load()`'s error text). Without the
1236    /// payload-side normalisation the embedded path would survive
1237    /// environment-specific differences (CI vs Docker vs local) because the
1238    /// post-serialisation `strip_root_prefix` only catches whole-string
1239    /// matches, not paths embedded mid-sentence.
1240    ///
1241    /// If `path` is not under `root` (e.g. canonicalisation crossed a
1242    /// symlink), the absolute path is emitted instead.
1243    ///
1244    /// `path` also loses any no-op `.` component, for the same reason the
1245    /// payload loses a glob's `./` prefix: one directory reached through two
1246    /// spellings of one glob must be one diagnostic.
1247    #[must_use]
1248    pub fn new(root: &Path, path: PathBuf, kind: WorkspaceDiagnosticKind) -> Self {
1249        let path = normalise_diagnostic_path(path);
1250        let kind = normalise_payload_paths(root, kind);
1251        let message = render_message(root, &path, &kind);
1252        let degrades_analysis = kind.warns_on_stderr();
1253        Self {
1254            path,
1255            kind,
1256            message,
1257            degrades_analysis,
1258        }
1259    }
1260
1261    /// Return this diagnostic with `path` rewritten relative to `root`.
1262    ///
1263    /// `path` is stored absolute so callers can act on it. Every JSON envelope
1264    /// emits it project-relative instead: the analysis envelopes get there
1265    /// through the post-serialisation `strip_root_prefix` pass, which the
1266    /// `fallow workspaces` / `fallow list --workspaces` envelope and the MCP
1267    /// `project_info` tool never run, so those emitted the absolute path while
1268    /// the sibling `workspaces[].path` next to it was relative. They normalise
1269    /// at the typed layer with this method instead.
1270    ///
1271    /// Paths outside `root` (canonicalisation crossed a symlink) are left
1272    /// absolute, matching how [`Self::new`] renders the message.
1273    ///
1274    /// A diagnostic anchored at the root itself becomes `.`, not the empty
1275    /// path: an empty string is not a location, and the analysis envelopes'
1276    /// post-serialisation strip only removes a `root + separator` prefix, so a
1277    /// root-anchored path that stays absolute here leaks a host path.
1278    #[must_use]
1279    pub fn into_root_relative(mut self, root: &Path) -> Self {
1280        if let Ok(relative) = self.path.strip_prefix(root) {
1281            self.path = if relative.as_os_str().is_empty() {
1282                PathBuf::from(".")
1283            } else {
1284                relative.to_path_buf()
1285            };
1286        }
1287        self
1288    }
1289}
1290
1291/// Rebuild `path` from its components so one directory has one spelling.
1292///
1293/// The dedupe key was never the problem: [`Path`] equality already ignores an
1294/// interior `.`, so `<root>/./pkgs/aaa` and `<root>/pkgs/aaa` are one key. The
1295/// stored bytes were. A workspace glob spelled `./pkgs/*` in `package.json`
1296/// expands to the first spelling and the same glob spelled `pkgs/*` in
1297/// `pnpm-workspace.yaml` expands to the second, and the two envelope families
1298/// make a project-relative path differently: the analysis envelopes strip the
1299/// root as a string (leaving `./pkgs/aaa`) while the workspace listing
1300/// envelope uses [`WorkspaceDiagnostic::into_root_relative`] (leaving
1301/// `pkgs/aaa`). Whichever
1302/// manifest happened to be read first then decided which shape every consumer
1303/// saw. Collapsing at construction gives them one answer (issue #2366).
1304///
1305/// A path that is already component-clean rebuilds to itself. Serialization
1306/// normalises separators, so the rebuild is wire-invisible on Windows.
1307fn normalise_diagnostic_path(path: PathBuf) -> PathBuf {
1308    let rebuilt: PathBuf = path.components().collect();
1309    if rebuilt.as_os_str() == path.as_os_str() {
1310        path
1311    } else {
1312        rebuilt
1313    }
1314}
1315
1316/// Strip the project root from absolute paths embedded inside variant
1317/// payloads (the `error` field of malformed-config and source-read failures),
1318/// and drop a glob pattern's no-op `./` prefix.
1319///
1320/// Mirrors the per-platform `display()` byte sequence so the substring match
1321/// works on Windows too.
1322///
1323/// The pattern prefix matters because the payload is part of the dedupe key in
1324/// [`merge_workspace_diagnostics`]. A repository whose `package.json` declares
1325/// `"./apps/**"` and whose `pnpm-workspace.yaml` declares `apps/**` names one
1326/// glob twice, and without this both spellings would report every package-less
1327/// directory under `apps/` a second time (issue #2366).
1328fn normalise_payload_paths(root: &Path, kind: WorkspaceDiagnosticKind) -> WorkspaceDiagnosticKind {
1329    let root_str = root.display().to_string();
1330    let root_alt = root_str.replace('\\', "/");
1331    let normalise = |text: String| -> String {
1332        let stripped = text
1333            .replace(&format!("{root_str}/"), "")
1334            .replace(&format!("{root_alt}/"), "");
1335        stripped
1336            .replace(&format!("{root_str}\\"), "")
1337            .replace(&format!("{root_alt}\\"), "")
1338    };
1339    match kind {
1340        WorkspaceDiagnosticKind::MalformedPackageJson { error } => {
1341            WorkspaceDiagnosticKind::MalformedPackageJson {
1342                error: normalise(error),
1343            }
1344        }
1345        WorkspaceDiagnosticKind::MalformedTsconfig { error } => {
1346            WorkspaceDiagnosticKind::MalformedTsconfig {
1347                error: normalise(error),
1348            }
1349        }
1350        WorkspaceDiagnosticKind::SourceReadFailure { error } => {
1351            WorkspaceDiagnosticKind::SourceReadFailure {
1352                error: normalise(error),
1353            }
1354        }
1355        WorkspaceDiagnosticKind::FileScoresUnavailable { error } => {
1356            WorkspaceDiagnosticKind::FileScoresUnavailable {
1357                error: normalise(error),
1358            }
1359        }
1360        WorkspaceDiagnosticKind::OwnershipUnavailable { cause, error } => {
1361            WorkspaceDiagnosticKind::OwnershipUnavailable {
1362                cause,
1363                error: normalise(error),
1364            }
1365        }
1366        WorkspaceDiagnosticKind::TrendSnapshotUnreadable { error } => {
1367            WorkspaceDiagnosticKind::TrendSnapshotUnreadable {
1368                error: normalise(error),
1369            }
1370        }
1371        WorkspaceDiagnosticKind::GlobMatchedNoPackageJson { pattern } => {
1372            WorkspaceDiagnosticKind::GlobMatchedNoPackageJson {
1373                pattern: canonical_glob_pattern(pattern),
1374            }
1375        }
1376        WorkspaceDiagnosticKind::WorkspaceGlobOutsideRoot { pattern } => {
1377            WorkspaceDiagnosticKind::WorkspaceGlobOutsideRoot {
1378                pattern: canonical_glob_pattern(pattern),
1379            }
1380        }
1381        WorkspaceDiagnosticKind::WorkspacePatternDirMissing { pattern } => {
1382            WorkspaceDiagnosticKind::WorkspacePatternDirMissing {
1383                pattern: canonical_glob_pattern(pattern),
1384            }
1385        }
1386        other => other,
1387    }
1388}
1389
1390/// Drop the leading `./` (or `.\`) a workspace glob may carry, so the same
1391/// pattern declared in two manifests is one payload.
1392///
1393/// A pattern that is nothing BUT the prefix (`"./"`, the root itself) keeps
1394/// its spelling: stripping it would report an empty `pattern` field and an
1395/// empty quoted glob in the warning text, which names no glob at all.
1396fn canonical_glob_pattern(pattern: String) -> String {
1397    for prefix in ["./", ".\\"] {
1398        if let Some(rest) = pattern.strip_prefix(prefix)
1399            && !rest.is_empty()
1400        {
1401            return rest.to_owned();
1402        }
1403    }
1404    pattern
1405}
1406
1407/// Concatenate two diagnostic lists, keeping the first occurrence of each
1408/// `(kind, path)` pair and the order of `primary` followed by the entries only
1409/// `secondary` has.
1410///
1411/// The single place diagnostics from two observation points are folded
1412/// together: an engine session's own capture plus the process registry, and
1413/// the combined run's per-analysis lists (issue #2366). A combined run walks
1414/// the project once per analysis, and per-analysis `production` modes can make
1415/// those walks see different file sets, so no single observation point holds
1416/// everything the run recorded; the union does, and folding it the same way
1417/// everywhere is what keeps the CLI and the programmatic route answering
1418/// identically.
1419///
1420/// The key is the WHOLE kind, payload included, not its
1421/// [`id`](WorkspaceDiagnosticKind::id). Two entries can share a kind id and a
1422/// path and still be two distinct diagnostics: overlapping workspace globs
1423/// (`["packages/*", "packages/*/*"]`) each report the same package-less
1424/// directory with their own `pattern`, and the standalone envelopes report
1425/// both. An id-keyed fold silently dropped the second one.
1426#[must_use]
1427pub fn merge_workspace_diagnostics(
1428    primary: Vec<WorkspaceDiagnostic>,
1429    secondary: Vec<WorkspaceDiagnostic>,
1430) -> Vec<WorkspaceDiagnostic> {
1431    let mut merged = Vec::with_capacity(primary.len() + secondary.len());
1432    let mut seen: FxHashSet<(WorkspaceDiagnosticKind, PathBuf)> = FxHashSet::default();
1433    for diagnostic in primary.into_iter().chain(secondary) {
1434        let key = (diagnostic.kind.clone(), diagnostic.path.clone());
1435        if seen.insert(key) {
1436            merged.push(diagnostic);
1437        }
1438    }
1439    merged
1440}
1441
1442/// Keep the first occurrence of each `(kind, path)` pair in one list.
1443///
1444/// The single-list form of [`merge_workspace_diagnostics`], applied where
1445/// diagnostics are produced rather than where two observation points are
1446/// folded: workspace discovery reads `package.json` `workspaces`,
1447/// `pnpm-workspace.yaml` `packages`, `deno.json` `workspace` and the root
1448/// `tsconfig.json` references additively, so a repository that declares one
1449/// glob in two of them reports every package-less directory under it twice.
1450/// Deduplicating at that source is what keeps the JSON envelopes, the
1451/// aggregated stderr warning and the process registry telling one story
1452/// (issue #2366).
1453#[must_use]
1454pub fn dedupe_workspace_diagnostics(
1455    diagnostics: Vec<WorkspaceDiagnostic>,
1456) -> Vec<WorkspaceDiagnostic> {
1457    merge_workspace_diagnostics(diagnostics, Vec::new())
1458}
1459
1460/// The first segment of a glob that contains no glob metacharacter, so it
1461/// names a real directory rather than a wildcard.
1462///
1463/// Source discovery uses it to decide which directory a built-in ignore
1464/// pattern excluded a file "at"; `render_message` uses it to decide which
1465/// remedy is true for that pattern. The two have to agree, so the function
1466/// lives here rather than once per crate: a pattern with such a segment
1467/// (`**/dist/**`) is lifted by re-rooting inside the matched directory,
1468/// because the glob is matched against the path relative to the run root. A
1469/// pattern without one (`**/*.min.js`) matches on the file name and keeps
1470/// matching at every root.
1471#[must_use]
1472pub fn glob_first_literal_segment(pattern: &str) -> Option<&str> {
1473    pattern.split('/').find(|segment| {
1474        !segment.is_empty()
1475            && !segment.contains(['*', '?', '[', ']', '{', '}'])
1476            && *segment != "."
1477            && *segment != ".."
1478    })
1479}
1480
1481/// The catalog entries that a `workspace-pattern-dir-missing` diagnostic
1482/// keeps out of the run, as the subject of a sentence. `source_display` is
1483/// the declaring file, relative to the project root.
1484///
1485/// A missing directory of a root pattern hides consumers of every catalog. A
1486/// missing directory of a `packages` entry of a nested `pnpm-workspace.yaml`
1487/// hides consumers of the catalog of that file only.
1488#[must_use]
1489pub fn missing_pattern_dir_skipped_entries(source_display: &str) -> &'static str {
1490    if source_display.contains('/') && source_display.ends_with("pnpm-workspace.yaml") {
1491        "Unused entries of the catalog in that file"
1492    } else {
1493        "Unused catalog entries"
1494    }
1495}
1496
1497/// The directory part of a workspace pattern: the segments before the first
1498/// segment with a glob character, joined with `/`.
1499///
1500/// `vite/packages/*` gives `vite/packages`, `vite` gives `vite`, and a
1501/// pattern that starts with a glob segment (`**/pkg`, `{a,b}/*`) gives
1502/// `None`. A leading `./` and empty or `.` segments are dropped. Workspace
1503/// discovery uses it to find a pattern whose directory does not exist, and
1504/// the diagnostic message uses it to name that directory, so both read the
1505/// same part of the pattern.
1506#[must_use]
1507pub fn workspace_pattern_literal_dir(pattern: &str) -> Option<String> {
1508    let literal: Vec<&str> = pattern
1509        .split(['/', '\\'])
1510        .filter(|segment| !segment.is_empty() && *segment != ".")
1511        .take_while(|segment| !segment.contains(['*', '?', '[', ']', '{', '}']))
1512        .collect();
1513    if literal.is_empty() {
1514        None
1515    } else {
1516        Some(literal.join("/"))
1517    }
1518}
1519
1520fn render_message(root: &Path, path: &Path, kind: &WorkspaceDiagnosticKind) -> String {
1521    let display = display_relative(root, path);
1522    match kind {
1523        WorkspaceDiagnosticKind::UndeclaredWorkspace => format!(
1524            "Directory '{display}' contains package.json but is not declared as a workspace. \
1525             Add it to package.json workspaces or pnpm-workspace.yaml, or add it to ignorePatterns."
1526        ),
1527        WorkspaceDiagnosticKind::MalformedPackageJson { error } => format!(
1528            "Dropped workspace '{display}': package.json is not valid JSON ({error}). \
1529             Fix the JSON syntax or remove '{display}' from the workspaces pattern."
1530        ),
1531        WorkspaceDiagnosticKind::GlobMatchedNoPackageJson { pattern } => format!(
1532            "Glob '{pattern}' matched '{display}' but no package.json is present. \
1533             Add a package.json, narrow the pattern, or add '{display}' to ignorePatterns."
1534        ),
1535        WorkspaceDiagnosticKind::WorkspaceGlobOutsideRoot { pattern } => {
1536            let source = if display.is_empty() {
1537                "the fallow config `workspaces.patterns`".to_owned()
1538            } else {
1539                format!("'{display}'")
1540            };
1541            format!(
1542                "Skipped workspace entry '{pattern}' in {source}: it is an absolute path \
1543                 or its '..' segments lead above the project root, so it can match directories \
1544                 outside the root. \
1545                 Fallow analyzes no package from it. Move the package inside the project root, \
1546                 or run fallow with --root set to a directory that holds both."
1547            )
1548        }
1549        WorkspaceDiagnosticKind::WorkspacePatternDirMissing { pattern } => {
1550            let source = if display.is_empty() {
1551                "the fallow config `workspaces.patterns`".to_owned()
1552            } else {
1553                format!("'{display}'")
1554            };
1555            let dir = workspace_pattern_literal_dir(pattern).unwrap_or_else(|| pattern.clone());
1556            let skipped = missing_pattern_dir_skipped_entries(&display);
1557            format!(
1558                "Workspace pattern '{pattern}' in {source} names directory '{dir}', which does \
1559                 not exist. Fallow analyzes no package from it. {skipped} are not \
1560                 reported in this run, because packages in that directory can use them. \
1561                 Create the directory before the run, or remove the pattern."
1562            )
1563        }
1564        WorkspaceDiagnosticKind::NestedProjectRoot => format!(
1565            "Directory '{display}' has its own pnpm-workspace.yaml, so it is an independent \
1566             project. Fallow analyzes it as a workspace: its package.json owns its files and \
1567             dependencies, the packages that its pnpm-workspace.yaml declares are workspaces, \
1568             and their catalog references resolve against its own catalog. Add '{display}' to \
1569             ignorePatterns to exclude it."
1570        ),
1571        WorkspaceDiagnosticKind::MalformedTsconfig { error } => format!(
1572            "tsconfig at '{display}' failed to parse ({error}); \
1573             its project references, path aliases and compiler options are ignored. \
1574             Fix the JSON syntax."
1575        ),
1576        WorkspaceDiagnosticKind::TsconfigReferenceDirMissing => format!(
1577            "tsconfig.json references '{display}' but the directory does not exist. \
1578             Update or remove the reference, or restore the missing directory."
1579        ),
1580        WorkspaceDiagnosticKind::MalformedPnpmWorkspaceYaml { error } => format!(
1581            "'{display}' is not valid YAML ({error}). Catalog checks are skipped \
1582             and its override entries are ignored until it parses. pnpm install \
1583             can accept this file, but `pnpm add` and YAML formatters reject it. \
1584             Indent each continuation line of a quoted value or a `[...]` / \
1585             `{{...}}` list deeper than its key."
1586        ),
1587        WorkspaceDiagnosticKind::SkippedLargeFile { size_bytes } => format!(
1588            "Skipped '{display}' ({size}): exceeds the max file size limit. \
1589             Its imports and exports are not analyzed. Raise the limit with \
1590             --max-file-size <MB> (or FALLOW_MAX_FILE_SIZE), or add '{display}' \
1591             to ignorePatterns.",
1592            size = format_size_mb(*size_bytes)
1593        ),
1594        WorkspaceDiagnosticKind::SkippedMinifiedFile { size_bytes } => format!(
1595            "Skipped '{display}' ({size}): appears to be minified generated JavaScript. \
1596             Its imports and exports are not analyzed. Add '{display}' to ignorePatterns, \
1597             rename it with a .min.js suffix, or use --max-file-size 0 if this file \
1598             should be analyzed.",
1599            size = format_size_mb(*size_bytes)
1600        ),
1601        WorkspaceDiagnosticKind::SkippedSourceDotdir => format!(
1602            "Skipped hidden directory '{display}': it contains source files but hidden \
1603             directories are not traversed. Its imports and exports are not analyzed. \
1604             A file, export or dependency that only this directory uses can be reported as \
1605             unused. To analyze it, add '!{display}/**' to ignorePatterns. To stop \
1606             that false positive without that, add the file to entry, the export to \
1607             ignoreExports or the dependency to ignoreDependencies. To silence this message, \
1608             add '{display}/**' to ignorePatterns. fallow --root {display} analyzes only \
1609             that directory on its own and does not fix this run."
1610        ),
1611        WorkspaceDiagnosticKind::SourceReadFailure { error } => format!(
1612            "Could not read source '{display}' ({error}). Restore the file or its read permissions, \
1613             ensure it contains valid UTF-8 text, or add '{display}' to ignorePatterns."
1614        ),
1615        WorkspaceDiagnosticKind::SourceParseDegraded {
1616            error_count,
1617            panicked,
1618        } => {
1619            let outcome = if *panicked {
1620                "the parser stopped there"
1621            } else {
1622                "the parser recovered and continued"
1623            };
1624            format!(
1625                "Parsed '{display}' with {error_count} error(s); {outcome}. Imports, exports, and \
1626                 references it did not reach are missing from this run, so files and symbols it \
1627                 uses can be reported as unused. Fix the syntax, or ignore this if the file uses \
1628                 syntax newer than fallow's parser."
1629            )
1630        }
1631        WorkspaceDiagnosticKind::SourceNestingTooDeep { limit } => format!(
1632            "Did not parse '{display}': it nests brackets deeper than {limit} levels, or it \
1633             needs more stack than fallow reserves, so a parse could overflow the stack. Its \
1634             imports and exports are missing from this run, so files and symbols it uses can be \
1635             reported as unused, and while the file is reachable `fallow fix` holds back its \
1636             actions for the whole project. Add '{display}' to ignoreFindings if it is generated \
1637             code, or reduce its nesting."
1638        ),
1639        WorkspaceDiagnosticKind::BunLockbOverrideResolutionSkipped => format!(
1640            "Skipped dependency-override resolution for '{display}': bun's legacy binary bun.lockb \
1641             sits next to it, fallow cannot read the binary format, and no parseable text lockfile \
1642             (bun.lock, pnpm-lock.yaml, package-lock.json, or npm-shrinkwrap.json) was found to \
1643             use instead, so unused-dependency-overrides findings are not reported. Run bun install \
1644             --save-text-lockfile (bun 1.2 or newer) to write a text bun.lock, or delete the stale \
1645             bun.lockb if this repository no longer uses bun."
1646        ),
1647        WorkspaceDiagnosticKind::BunLockOverrideResolutionSkipped => format!(
1648            "Skipped dependency-override resolution because '{display}' could not be parsed and \
1649             no readable pnpm or npm lockfile was available, so unused-dependency-overrides \
1650             findings are not reported. Run bun install to regenerate the text lockfile, then \
1651             rerun fallow."
1652        ),
1653        WorkspaceDiagnosticKind::PnpmLockOverrideResolutionSkipped => format!(
1654            "Skipped dependency-override resolution because '{display}' could not be parsed and \
1655             no other parseable lockfile was available, so unused-dependency-overrides findings \
1656             are not reported. Resolve any merge-conflict markers in the lockfile, or run pnpm \
1657             install to regenerate it, then rerun fallow."
1658        ),
1659        WorkspaceDiagnosticKind::NpmLockOverrideResolutionSkipped => format!(
1660            "Skipped dependency-override resolution because '{display}' could not be parsed and \
1661             no other parseable lockfile was available, so unused-dependency-overrides findings \
1662             are not reported. Resolve any merge-conflict markers in the lockfile, or run npm \
1663             install to regenerate it, then rerun fallow."
1664        ),
1665        WorkspaceDiagnosticKind::BunResolutionsShadowedByOverrides => format!(
1666            "'{display}' declares both `overrides` and non-empty `resolutions`; bun applies \
1667             `overrides` and ignores `resolutions`. Move the intended pins into `overrides` or \
1668             remove the shadowed `resolutions` entries."
1669        ),
1670        WorkspaceDiagnosticKind::PnpmWorkspaceOverridesIgnored {
1671            cause: PnpmWorkspaceOverridesIgnoredCause::PackageJsonOverrides,
1672        } => format!(
1673            "pnpm 10 and earlier ignore the `overrides` in '{display}' because the root package.json \
1674             declares `pnpm.overrides` or `resolutions`, so fallow does not check them. Move the \
1675             entries into one source."
1676        ),
1677        WorkspaceDiagnosticKind::PnpmWorkspaceOverridesIgnored {
1678            cause: PnpmWorkspaceOverridesIgnoredCause::PnpmVersion,
1679        } => format!(
1680            "pnpm versions before 10.5.1 do not read the `overrides` in '{display}', so fallow \
1681             does not check them. Update `packageManager` to pnpm 10.5.1 or later, or move the \
1682             entries into `pnpm.overrides` in the root package.json."
1683        ),
1684        WorkspaceDiagnosticKind::NodeModulesMissing => format!(
1685            "'{display}' does not exist. Package exports and conditional exports cannot be read, \
1686             framework plugins that activate on an installed package stay inactive, and \
1687             dependency classification degrades, so imports and dependencies can be \
1688             misreported. Run npm install / pnpm install / yarn / bun install first."
1689        ),
1690        WorkspaceDiagnosticKind::BoundariesNotConfigured => {
1691            "No architecture boundaries are configured, so the boundary detector did not run and \
1692             its violation counts are zero because nothing was measured. Add `boundaries` to the \
1693             config, or set `boundary-violation` to off to state that the check is not wanted."
1694                .to_string()
1695        }
1696        WorkspaceDiagnosticKind::RulePacksNotConfigured => {
1697            "No rule packs are configured, so the policy detector did not run and its violation \
1698             counts are zero because nothing was measured. Add `rulePacks` to the config, or set \
1699             `policy-violation` to off to state that the check is not wanted."
1700                .to_string()
1701        }
1702        WorkspaceDiagnosticKind::NoSourceFilesAnalyzed {
1703            excluded_file_count,
1704        } => {
1705            if *excluded_file_count == 0 {
1706                "No source files were analyzed, so every finding count this run reports is zero \
1707                 because nothing was measured. Check the analysis root, ignorePatterns, and any \
1708                 path or workspace filter this run applied."
1709                    .to_owned()
1710            } else {
1711                format!(
1712                    "No source files were analyzed. Fallow's built-in ignore patterns excluded \
1713                     {excluded_file_count} candidate files, so every finding count this run \
1714                     reports is zero because nothing was measured; run with --explain-skipped \
1715                     for the breakdown."
1716                )
1717            }
1718        }
1719        WorkspaceDiagnosticKind::FileScoresUnavailable { error } => format!(
1720            "Could not compute per-file health scores ({error}), so the score list is empty and \
1721             the scored-file count is 0 because nothing was measured rather than because the \
1722             project has nothing to score. Rerun with --no-cache, or scope the run to a \
1723             subdirectory to find the input that fails."
1724        ),
1725        WorkspaceDiagnosticKind::HotspotsSkipped { cause } => match cause.as_str() {
1726            "invalid-since" => "Hotspot analysis was skipped because --since could not be read \
1727                 as a time window, so the hotspots, churn and ownership sections report nothing \
1728                 rather than zero. Spell it as a duration such as 6m or 90d, or drop it to use \
1729                 the default window."
1730                .to_owned(),
1731            "no-commits" => "Hotspot analysis was skipped because the current branch has no \
1732                 commits yet, so the hotspots, churn and ownership sections report nothing \
1733                 rather than zero. Commit the project to give churn a history, or pass \
1734                 --churn-file with exported change history."
1735                .to_owned(),
1736            "churn-file-unreadable" => format!(
1737                "Hotspot analysis was skipped because the churn file '{display}' could no longer \
1738                 be read after it was validated, so the hotspots, churn and ownership sections \
1739                 report nothing rather than zero. Make sure nothing rewrites the file while \
1740                 fallow runs, and rerun."
1741            ),
1742            // The original single cause, whose wording predates the token and
1743            // is kept byte-identical: a consumer matching on this sentence is
1744            // reading the same run it always was.
1745            _ => "Hotspot analysis was skipped because no git repository was found at the \
1746                  project root, so the hotspots, churn and ownership sections report nothing \
1747                  rather than zero. Run fallow inside the repository, or pass --churn-file with \
1748                  exported change history."
1749                .to_owned(),
1750        },
1751        WorkspaceDiagnosticKind::ChangeCouplingSkipped { cause } => match cause.as_str() {
1752            "shallow-clone" => "Change coupling was not measured because the repository is a \
1753                 shallow clone, so no change coupling pairs are reported. Fetch the full \
1754                 history with `git fetch --unshallow` to measure it."
1755                .to_owned(),
1756            _ => "Change coupling found no pairs because the history window has fewer \
1757                  analyzed commits than the minimum revisions of one file. Widen the window \
1758                  with --since, or lower health.changeCoupling.minRevisions."
1759                .to_owned(),
1760        },
1761        WorkspaceDiagnosticKind::ShallowClone {
1762            ownership_requested,
1763        } => {
1764            let ownership = if *ownership_requested {
1765                " Ownership signals are skewed too, because a shallow clone inflates \
1766                 single-author dominance."
1767            } else {
1768                ""
1769            };
1770            format!(
1771                "This is a shallow clone, so churn covers only the fetched history and every \
1772                 hotspot figure is incomplete.{ownership} Run git fetch --unshallow for the full \
1773                 history."
1774            )
1775        }
1776        WorkspaceDiagnosticKind::UnpinnedClock => {
1777            "No commit timestamp was available, so churn recency and ownership staleness were \
1778             measured against the wall clock and drift between runs over the same commit. Set \
1779             FALLOW_CLOCK_EPOCH to pin the run clock."
1780                .to_owned()
1781        }
1782        WorkspaceDiagnosticKind::OwnershipUnavailable { cause, error } => {
1783            if cause == "codeowners-parse-failed" {
1784                format!(
1785                    "Ownership signals are degraded: CODEOWNERS could not be parsed ({error}), \
1786                     so hotspot entries carry no declared owner. Fix the CODEOWNERS syntax, or \
1787                     drop --ownership for this run."
1788                )
1789            } else {
1790                format!(
1791                    "Ownership signals are degraded: health.ownership.botPatterns contains an \
1792                     invalid glob ({error}), so no author is classified as a bot and bot commits \
1793                     count towards ownership. Fix the pattern, or remove it from the config."
1794                )
1795            }
1796        }
1797        WorkspaceDiagnosticKind::TrendSnapshotUnreadable { error } => format!(
1798            "Skipped health snapshot '{display}' ({error}), so the trend is computed over fewer \
1799             snapshots than this project has on disk. Delete the unreadable file, or rewrite it \
1800             with fallow health --save-snapshot."
1801        ),
1802        WorkspaceDiagnosticKind::TrendGroupBaselineUnavailable { cause } => {
1803            if cause == "grouped-by-mismatch" {
1804                format!(
1805                    "Health snapshot '{display}' was saved with a different --group-by mode, so \
1806                     the groups have no trend. The project trend is not affected. Save a new \
1807                     snapshot with the same --group-by mode."
1808                )
1809            } else {
1810                format!(
1811                    "Health snapshot '{display}' holds no group data, so the groups have no \
1812                     trend. The project trend is not affected. Save a new snapshot with \
1813                     --group-by and --save-snapshot."
1814                )
1815            }
1816        }
1817        WorkspaceDiagnosticKind::CoverageAutoDetected => format!(
1818            "Coverage was auto-detected at '{display}' rather than passed with --coverage, so the \
1819             CRAP scores depend on whichever coverage file is on disk at run time. Pass --coverage \
1820             '{display}' explicitly for reproducible scores."
1821        ),
1822        WorkspaceDiagnosticKind::FlagAgeShallowClone => {
1823            "This is a shallow clone, so the flag retirement report gives no flag age. Run git \
1824             fetch --unshallow for the full history, or pass --flag-age off."
1825                .to_owned()
1826        }
1827        WorkspaceDiagnosticKind::BaselineInstallStateMismatch {
1828            baseline_node_modules,
1829            ..
1830        } => {
1831            let (saved, now, remedy) = match baseline_node_modules {
1832                NodeModulesState::Present => (
1833                    "present",
1834                    "has no node_modules",
1835                    "Install dependencies before you compare",
1836                ),
1837                NodeModulesState::Missing => (
1838                    "missing",
1839                    "has node_modules",
1840                    "Compare without installed dependencies",
1841                ),
1842            };
1843            format!(
1844                "The baseline '{display}' was saved with node_modules {saved}, and this run \
1845                 {now}. Findings that need installed packages (dependency, unlisted, \
1846                 unresolved-import and script-binary findings) can differ, so the run can report \
1847                 baseline findings as new. {remedy}, or save the baseline again in the same \
1848                 install state."
1849            )
1850        }
1851        WorkspaceDiagnosticKind::IgnoreDependenciesGlobUnmatched { .. }
1852        | WorkspaceDiagnosticKind::IgnoreFindingsPatternUnmatched { .. }
1853        | WorkspaceDiagnosticKind::EntryPatternRedundant { .. }
1854        | WorkspaceDiagnosticKind::IgnoreDependenciesEntryRedundant { .. }
1855        | WorkspaceDiagnosticKind::IgnorePatternsEntryRedundant { .. }
1856        | WorkspaceDiagnosticKind::OverrideRuleIneffective { .. }
1857        | WorkspaceDiagnosticKind::RequestedRuleOff { .. } => {
1858            config_entry::config_entry_message(kind)
1859        }
1860        WorkspaceDiagnosticKind::FlagAgeUnavailable { cause } => {
1861            if cause == "no-commits" {
1862                "The flag retirement report gives no flag age, because the current branch has no \
1863                 commit. Commit the code, or pass --flag-age off."
1864                    .to_owned()
1865            } else {
1866                "The flag retirement report gives no flag age, because no git repository was \
1867                 found at the project root. Run fallow inside the repository, or pass --flag-age \
1868                 off."
1869                    .to_owned()
1870            }
1871        }
1872        WorkspaceDiagnosticKind::PluginConfigUnreadable {
1873            plugin,
1874            key,
1875            reason,
1876        } => {
1877            let (consequence, advice) = plugin_text::unreadable_key_consequence(key, reason);
1878            format!(
1879                "Plugin '{plugin}': `{key}` in '{display}' {situation}, so {consequence}. {advice}",
1880                situation = plugin_text::unreadable_situation(reason)
1881            )
1882        }
1883        WorkspaceDiagnosticKind::PluginEffectNotModeled {
1884            plugin,
1885            key,
1886            reason,
1887        } => {
1888            // Two causes, one effect, one remedy. Each cause gets its own
1889            // sentence: the cause and the effect on the findings are separate
1890            // facts, and one sentence with two `so` clauses states neither fact
1891            // clearly.
1892            let effect = "`autoImports` kept the convention entry patterns for that surface, and \
1893                          fallow reports no unused file there. Write the setting as static \
1894                          literals, or remove the key to use the framework defaults.";
1895            if key.starts_with('#') {
1896                format!(
1897                    "Plugin '{plugin}': fallow cannot read which names '{display}' takes from \
1898                     `{key}`, so every name of `{key}` counts as used, and fallow reports no \
1899                     unused file for these names. Read each name with a member access such as \
1900                     `C.Card`, or import it by name."
1901                )
1902            } else if reason == "config-property-unreadable" {
1903                format!(
1904                    "Plugin '{plugin}': fallow cannot read a top-level property in '{display}', so \
1905                     it cannot classify the `{key}` surface. {effect}"
1906                )
1907            } else {
1908                format!(
1909                    "Plugin '{plugin}': fallow does not model the effect of `{key}` in \
1910                     '{display}'. {effect}"
1911                )
1912            }
1913        }
1914        WorkspaceDiagnosticKind::ExcludedByDefaultIgnore {
1915            pattern,
1916            file_count,
1917            directory_count,
1918        } => {
1919            // `path` is a location, and an empty string is not one: a built-in
1920            // that matched a file sitting directly at the analysis root
1921            // anchors at the root itself.
1922            let display = if display.is_empty() {
1923                ".".to_owned()
1924            } else {
1925                display
1926            };
1927            // The payload carries no directory list, so the message names the
1928            // one directory `path` anchors at. With several excluded
1929            // directories that is the largest group and NOT a majority, so the
1930            // sentence says which claim it is making and how many directories
1931            // it is leaving unnamed.
1932            let location = if *directory_count > 1 {
1933                format!(
1934                    "Skipped {file_count} source files across {directory_count} directories, \
1935                     the largest group under '{display}'"
1936                )
1937            } else if *file_count == 1 {
1938                format!("Skipped 1 source file under '{display}'")
1939            } else {
1940                format!("Skipped {file_count} source files under '{display}'")
1941            };
1942            let singular = *file_count == 1 && *directory_count <= 1;
1943            let (subject, effect) = if singular {
1944                ("it matches", "it imports, exports, or defines")
1945            } else {
1946                ("they match", "they import, export, or define")
1947            };
1948            // Only a directory-shaped built-in is lifted by re-rooting. Telling
1949            // a user with a `vendor/lib.min.js` to run `fallow --root vendor`
1950            // hands them a command that excludes the same file again.
1951            let remedy = if glob_first_literal_segment(pattern).is_some() {
1952                format!(
1953                    "To analyze first-party source there, add '!{display}/**' to \
1954                     ignorePatterns, or analyze that directory on its own with \
1955                     fallow --root {display}."
1956                )
1957            } else {
1958                "This pattern matches a file name rather than a directory, so re-running under \
1959                 a different --root excludes the same files again. Rename first-party source \
1960                 that only looks generated, dropping the '.min' or '.bundle' infix, or add a \
1961                 '!' entry for the file to ignorePatterns."
1962                    .to_owned()
1963            };
1964            format!(
1965                "{location}: {subject} fallow's built-in ignore pattern '{pattern}', so nothing \
1966                 {effect} is visible to this run. {remedy}"
1967            )
1968        }
1969    }
1970}
1971
1972#[cfg(test)]
1973#[path = "workspace_tests.rs"]
1974mod tests;