Enum WorkspaceDiagnosticKind 

pub enum WorkspaceDiagnosticKind {
    UndeclaredWorkspace,
    MalformedPackageJson {
        error: String,
    },
    GlobMatchedNoPackageJson {
        pattern: String,
    },
    MalformedTsconfig {
        error: String,
    },
    TsconfigReferenceDirMissing,
    MalformedPnpmWorkspaceYaml {
        error: String,
    },
    SkippedLargeFile {
        size_bytes: u64,
    },
    SkippedMinifiedFile {
        size_bytes: u64,
    },
    SkippedSourceDotdir,
    SourceReadFailure {
        error: String,
    },
    SourceParseDegraded {
        error_count: u32,
        panicked: bool,
    },
    BunLockbOverrideResolutionSkipped,
    BunLockOverrideResolutionSkipped,
    BunResolutionsShadowedByOverrides,
    NodeModulesMissing,
    BoundariesNotConfigured,
    RulePacksNotConfigured,
    ExcludedByDefaultIgnore {
        pattern: String,
        file_count: u32,
        directory_count: u32,
    },
}

Why a workspace-discovery candidate was rejected, or why a sibling directory looked workspace-like but was not declared.

Wire-format names are kebab-case so JSON consumers (CI integrations, MCP agents, LSP clients) get a stable, language-neutral identifier.

Variants

UndeclaredWorkspace

A directory contains package.json but is not declared as a workspace in package.json workspaces, pnpm-workspace.yaml, or tsconfig.json references. Surfaced by find_undeclared_workspaces.

MalformedPackageJson

A declared workspace’s package.json failed to parse. The directory is dropped from discovery, but analysis still proceeds (degraded).

Fields

error: String

serde_json parse error text.

GlobMatchedNoPackageJson

A workspace glob pattern matched a directory that contains no package.json. Honors the extended skip list and ignorePatterns before emitting.

Fields

pattern: String

The glob pattern that matched the directory.

MalformedTsconfig

tsconfig.json exists at the root but failed to parse. Project references cannot be discovered.

Fields

error: String

JSONC parse error text.

TsconfigReferenceDirMissing

tsconfig.json lists a references[].path that does not point to an existing directory.

MalformedPnpmWorkspaceYaml

pnpm-workspace.yaml exists but failed to parse as YAML. Catalog and dependency-override analysis proceeds with no entries (degraded), so catalog:-referenced dependencies may be misclassified until the syntax is fixed.

Fields

error: String

serde_yaml_ng parse error text.

SkippedLargeFile

A source file was skipped at discovery because it exceeds the configured per-file size limit (--max-file-size / FALLOW_MAX_FILE_SIZE, default 5 MB). The file is never read, parsed, or analyzed, guarding against the out-of-memory blowup a single multi-MB generated/vendored/bundled file causes (issue #1086). Surfaced by source discovery, not workspace discovery, but shares this channel so the skip is visible in workspace_diagnostics[] on fallow dead-code / dupes / health JSON.

Fields

size_bytes: u64

On-disk size of the skipped file in bytes.

SkippedMinifiedFile

A large JavaScript bundle was skipped at discovery because it appears to be minified generated output. The file is never parsed or analyzed, guarding against sub-limit bundles that can still create very large ASTs and extraction payloads (issue #1086). Use --max-file-size 0 when the bundled file really should be analyzed.

Fields

size_bytes: u64

On-disk size of the skipped file in bytes.

SkippedSourceDotdir

A dot-prefixed directory was not traversed by source discovery even though it contains at least one source file the project has not excluded. Hidden directories are skipped by default apart from a small convention allowlist (.storybook, .vitepress, .well-known, .changeset, .github) and the directories an active framework plugin or a package.json script reference contributes, so files inside are never parsed and their imports and exports are invisible to every analysis. No config field adds a directory to traversal: run fallow with --root against the directory to analyze it on its own, or add it to ignorePatterns to silence this (issue #461).

“Not excluded” is measured the way the run measures it: a directory whose contents are gitignored, or excluded by ignorePatterns, or (on a --production run) excluded as test or story files, never earns this diagnostic, because the advertised remedies would find nothing there either. Generated tool output and non-git VCS metadata are excluded by name.

The advisory is best-effort and bounded: one run inspects a fixed number of skipped directories with a fixed I/O budget, in sorted path order, so a pathological tree yields a deterministic prefix rather than an unbounded array or an unbounded scan. The stderr note says “at least” when a ceiling bound the run.

Surfaced by source discovery, not workspace discovery, but shares this channel so the skip is visible in workspace_diagnostics[] on fallow dead-code / dupes / health JSON.

Unlike the two skipped-file kinds beside it, this one is CAPPED. To bound the directory reads the check costs, a run classifies at most 64 candidate directories and spends at most 1024 directory entries across all of them, so on a project that exceeds either ceiling the array is a prefix of the skipped directories rather than all of them, and the stderr note says “at least N”. No measured repository comes close to either ceiling. A consumer needing an exact total should run fallow with --root against the tree rather than infer one from this array.

SourceReadFailure

A source discovered with a stable FileId could not be read before parsing. Analysis continues with the remaining sparse module IDs and reports the underlying filesystem or UTF-8 error.

Fields

error: String

Filesystem or UTF-8 decoding error from read_to_string.

SourceParseDegraded

A source file was read but parsed with diagnostics, so the module extracted from it may be missing imports, exports, or references after the first error. Analysis proceeds with the partial module, which is why this is reported: an import the parser never saw credits nothing, and its target can surface as a confident unused-file or unused-export finding with a delete-file or remove-export action on it.

Recorded by the parse stage, alongside source-read-failure, and never used to withhold a finding. oxc reports recoverable errors for valid syntax newer than the parser as well as for genuinely broken files, so gating findings on this would mute real results project-wide instead of just the affected file.

Fields

error_count: u32

Number of parser diagnostics reported for the file.

panicked: bool

true when the parser abandoned the file instead of recovering, so the extracted module is a fragment at best.

BunLockbOverrideResolutionSkipped

Dependency-override resolution was skipped because bun’s legacy binary bun.lockb sits next to this package.json, fallow cannot read the binary format, and no parseable text lockfile was found to use instead: no bun.lock that parses, and no readable pnpm-lock.yaml, package-lock.json, or npm-shrinkwrap.json. A yarn.lock is never consulted (yarn ignores overrides), so it does not prevent the skip either. The manifest declares overrides, so the unused-dependency-overrides check would otherwise have run; without resolution ground truth it would flag every transitive-only pin, so no unused-override findings are reported at all (issue #2358). Surfaced by the override analysis, not workspace discovery, but shares this channel so the skip is visible in workspace_diagnostics[] JSON and as a stderr warning.

BunLockOverrideResolutionSkipped

Dependency-override resolution was skipped because bun’s text bun.lock exists but could not be parsed and no readable pnpm or npm lockfile was available as independent resolution ground truth.

BunResolutionsShadowedByOverrides

A bun manifest declares both overrides and a non-empty resolutions object. Bun applies overrides and ignores resolutions, so fallow reports the shadowed configuration without offering removal advice.

NodeModulesMissing

The project has no node_modules directory and is not a Deno project that legitimately runs without one. Analysis proceeds, but three things degrade silently: package exports and conditional exports cannot be read, so imports into a dependency’s subpaths resolve less precisely; framework plugins that activate on an installed package stay inactive, so their entry points and path aliases are missing; and a dependency’s installed shape cannot be inspected, so type-only dependency classification falls back to declaration-based heuristics.

Recorded once per run by the source walk, anchored at the missing node_modules directory so the reported path is a real location rather than the empty string a root-anchored diagnostic would render. This used to be a bare tracing::warn! duplicated in two pipelines, so it never reached JSON output and never reached fallow doctor, which reported pass on a tree that had never been installed.

BoundariesNotConfigured

boundaries is empty while boundary-violation is not off, so the boundary detector never ran. Its summary counters are therefore structurally zero and say nothing about the project.

This is the UNCONFIGURED zero, not the user-chosen one: a project that sets boundary-violation: off asked for silence and can see that choice in fallow config. A project that left boundaries empty cannot distinguish “no violations” from “nothing was measured”.

RulePacksNotConfigured

rulePacks is empty while policy-violation is not off, so the policy detector never ran and its summary counters are structurally zero. The unconfigured counterpart of Self::BoundariesNotConfigured.

ExcludedByDefaultIgnore

One of fallow’s built-in discovery ignore patterns (**/dist/**, **/build/**, **/coverage/**, and the four minified-bundle globs) removed at least one candidate source file from this walk. The files are never read, so their imports and exports are invisible to every analysis, and until issue #2638 the drop was completely silent: pointing fallow at a directory a built-in pattern matches returned a clean report with exit 0 and nothing said why.

**/node_modules/** is carved out and never appears in pattern: installed dependencies are not the first-party source this diagnostic is about, and a project that does not gitignore them would get a five-figure count with no useful remedy. **/.git/** cannot fire, because hidden directories are not traversed.

One entry per pattern, never per file or per directory, so the array grows by at most the number of built-in patterns on a project of any size. path anchors at the matched directory holding the most excluded files for that pattern, ties broken by the lexicographically first path, so two runs on one tree report the same location. On a nested match it is the DEEPEST segment the pattern matched (build/tools/build, not build), because that is the directory the --root remedy names and re-rooting at a shallower one would leave a matching segment behind. That directory is the largest group and not a majority: a flat monorepo can spread ten excluded files over ten sibling dist/ directories and every one of them is then “the largest”. file_count spans all of them, and directory_count says how many there were, so a reader can tell a single tree from a scattered one without a directory list in the payload.

Three properties of the population are load-bearing and easy to misread:

• Gitignored trees count zero. Source discovery honors .gitignore, .git/info/exclude, and the global gitignore, and prunes those directories before this check runs. The honest reading is “candidate source files git did not already hide and a built-in pattern then dropped”, which is why a repository that gitignores its own dist/ never sees this diagnostic.
• A user ignorePatterns entry is not a surprise. The compiled ignore set is the union of ignorePatterns and the built-ins, so a file both matched was an explicit project choice and is attributed to no pattern here. The union also only ever adds: ignorePatterns cannot negate a built-in, so a config edit is never the remedy.
• The remedy depends on the pattern’s shape. A directory-shaped built-in (**/dist/**) is matched against the path relative to the run root, so re-rooting inside the matched directory removes the matched segment and the files become visible: the message advertises fallow --root <dir>. A file-shaped built-in (**/*.min.js and the three other bundle globs) matches on the file name and keeps matching at any root, so the message says so and points at renaming instead of handing out a command that provably does nothing.

Deliberately NOT one of the Self::source_never_analyzed kinds. These exclusions are the product’s designed behavior on generated output, not a degraded run: answering true would attach IncompleteFileAnalysis and IncompleteImportGraph caveats to findings on nearly every project that keeps a non-gitignored dist/ or coverage/, and make fallow fix withhold delete-file and remove-export actions project-wide.

Fields

pattern: String

The built-in glob that matched, verbatim (for example **/build/**).

file_count: u32

Candidate source files this pattern excluded in this walk, across every directory it matched, not just the one path anchors at. Exact: the walk counts each excluded candidate once.

directory_count: u32

Distinct directories this pattern matched at, path included, and not the number of directories that held the files. A directory-shaped pattern (**/dist/**) matches at the directory it names, so an excluded subtree counts once however many nested directories inside it held source: a dist/ holding files in three sub-directories reports 1. A file-shaped pattern (**/*.min.js) has no directory to collapse to and counts each matched file’s own parent. Exact either way, and anything above 1 says path names one matched location out of several.

Implementations

impl WorkspaceDiagnosticKind

pub const fn id(&self) -> &'static str

Stable kebab-case identifier used in dedupe keys and tracing payloads.

pub const fn warns_on_stderr(&self) -> bool

Whether this diagnostic is worth a tracing::warn! line on stderr, on top of its permanent entry in workspace_diagnostics[].

A warning is for a run whose RESULTS are degraded: something the user installed, wrote, or expected did not reach the analysis. The two unconfigured-check kinds are not that. They fire in the product’s default state, on every project that never opted into boundaries or rule packs, and they will keep firing forever, because the remedy they offer is to write configuration in order to silence a warning about not having written configuration. They stay in the structured array, where a consumer that wants to distinguish “measured zero” from “measured nothing” can read them, and off the stderr surface that every other command shares.

pub const fn is_source_discovery(&self) -> bool

Whether this diagnostic is produced by SOURCE discovery (the file walk in discover_files) rather than WORKSPACE discovery (config load). Source- discovery diagnostics are APPENDED to the registry after config load, so stash_workspace_diagnostics must preserve them when it replaces the workspace-discovery set, otherwise the per-analysis config re-loads in combined-mode (fallow with no subcommand re-loads config for check, dupes, and health) wipe them before the JSON envelope is built (issue #1086).

pub const fn is_source_walk_recorded(&self) -> bool

Whether this diagnostic is written by the source file WALK (discover_files), the subset of Self::is_source_discovery that a walk replaces wholesale for its root. source-read-failure is the other source-discovery kind and is NOT one of these: the parse stage records it after the walk, so it has to keep reaching consumers through the registry.

A walk-recorded entry must reach an analysis from its OWN walk’s return value. Combined mode runs the dead-code and duplication walks under rayon::join whenever a per-analysis production split stops them from sharing a file list, so a registry read answers “whichever walk wrote last” and varies between runs of the same command (issue #2366).

pub const fn source_never_analyzed(&self) -> bool

Whether this diagnostic reports a source file whose contents this run never analyzed, so every import and export the file holds is invisible to the module graph.

This is the class reachability_caveats[] exists for. A file the run never read credits nothing, so the modules it imports surface as confident unused-file and unused-export findings carrying delete-file and remove-export actions, and fallow fix would otherwise apply the removal against source that still imports the target.

All four discovery-side kinds qualify, for the same reason and with the same consequence:

• skipped-large-file and skipped-minified-file: the file is in the project tree and was never opened, so its import list is unknown.
• skipped-source-dotdir: the directory holds at least one source file the project did not exclude, and none of them were traversed. The diagnostic is capped, so it under-reports rather than over-reports; its presence still proves unseen source exists.
• source-read-failure: the file was discovered and then could not be read, so nothing was extracted from it at all.

source-parse-degraded is deliberately NOT one of these, though it belongs to the same family. Neither is excluded-by-default-ignore, for a different reason: that one reports designed behavior on generated output rather than a degraded run, and its own doc comment carries the argument.

source-parse-degraded: that file WAS read, so it has a module and a graph node and its reachability is observable, which lets the caveat pass narrow it: a degraded module that is itself unreachable cannot change a reachability verdict. Every kind above has no node to ask (a read failure has one with nothing extracted into it), so no narrowing is available and the caveat they raise is run-level.

The match is exhaustive on purpose: a new “the run did not see this file” kind has to be classified here, and answering true is the only wiring its findings need in order to inherit both the caveat and the fallow fix withholding that follows it.

pub const fn is_analysis_stage(&self) -> bool

Whether this diagnostic is recorded by the ANALYZE stage (the dependency-catalog and override detectors) rather than by workspace or source discovery. Analysis-stage diagnostics reach the registry through record_workspace_diagnostics after config load, so stash_workspace_diagnostics must preserve them across combined-mode’s per-analysis config re-loads, and every analyze pass clears its previous entries before re-recording so a fixed cause drops out on the next run (issue #2366). The match is exhaustive on purpose: a new kind must be classified here before it compiles.

Classify a kind true ONLY when a detector reachable from the dead-code analyze pass (find_dead_code_full) re-records it, because that pass is the single clear site. A kind recorded exclusively by another stage would be cleared by the next dead-code pass and never come back.

Trait Implementations

impl Clone for WorkspaceDiagnosticKind

fn clone(&self) -> WorkspaceDiagnosticKind

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WorkspaceDiagnosticKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WorkspaceDiagnosticKind

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for WorkspaceDiagnosticKind

impl Hash for WorkspaceDiagnosticKind

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for WorkspaceDiagnosticKind

fn eq(&self, other: &WorkspaceDiagnosticKind) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for WorkspaceDiagnosticKind

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for WorkspaceDiagnosticKind