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,
    },
    BunLockbOverrideResolutionSkipped,
    BunLockOverrideResolutionSkipped,
    BunResolutionsShadowedByOverrides,
}

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.

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.

Implementations

impl WorkspaceDiagnosticKind

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

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

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 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