Crate fallow_config

Expand description

Configuration loading and resolution for fallow.

Owns the user-facing config model (FallowConfig and its sections), config-file discovery and extends inheritance, validation of user-supplied globs and patterns, and resolution into the pre-compiled ResolvedConfig the analysis crates consume. Also hosts workspace and package.json discovery, declarative external plugin definitions, rule packs, and the in-place config editing used by fallow fix.

Config section structs such as RulesConfig are not #[non_exhaustive] and gain new public fields in minor releases as rules are added, so exhaustive struct literals in downstream code are source-breaking on upgrade. Construct them with struct update syntax, for example RulesConfig { unused_files: Severity::Off, ..RulesConfig::default() }, to stay source-compatible.

Modules§

glob_validation: Validation of user-supplied glob patterns from the config file.
jsonc: JSONC parsing helpers pinning the dialect fallow accepts. JSONC parsing helpers shared by every surface that reads user-authored JSONC (config files, external plugin definitions, rule packs), so they all accept exactly the same dialect.
levenshtein: Levenshtein-distance helpers for typo detection across config surfaces.

Structs§

AuditConfig: The audit config section: in-repo defaults for fallow audit, each overridable by its matching CLI flag.
AuthoredRule: Pre-expansion rule preserved on a LogicalGroup.
AutoImportRule: A single convention-based auto-import: a bare identifier name that resolves to an export in source by framework convention, with no explicit import statement in the consuming file.
BoundaryCallsConfig: Boundary forbidden-call policy. Applies only to files classified into a zone; unzoned files are unrestricted, matching the import rules.
BoundaryConfig: Architecture boundary configuration.
BoundaryCoverageConfig: Boundary zone coverage policy.
BoundaryRule: An import rule between zones.
BoundaryZone: A zone grouping files by directory pattern.
CacheConfig: The cache config section: location and size ceiling of fallow’s persistent caches (default directory <root>/.fallow).
CatalogFixConfig: The fix.catalog section: how fallow fix cleans up unused pnpm-workspace.yaml catalog entries.
CompiledIgnoreCatalogReferenceRule: IgnoreCatalogReferenceRule with the optional consumer glob pre-compiled.
CompiledIgnoreDependencyOverrideRule: IgnoreDependencyOverrideRule ready for matching.
CompiledIgnoreExportRule: IgnoreExportRule with the glob pre-compiled into a matcher.
ConfigLoadOptions: Host-controlled trust policy for loading a fallow config.
ConfigOverride: Per-file override entry.
DirManifestProbe: A directory’s package-manifest outcome plus its Deno import map, produced from a single deno.json / deno.jsonc filesystem probe.
DuplicatesConfig: Configuration for code duplication detection.
ExternalPluginDef: A declarative plugin definition loaded from a standalone file or inline config.
ExternalUsedExport: Exports considered used for files matching a pattern.
FallowConfig: The user-facing fallow configuration as authored in .fallowrc.json / .fallowrc.jsonc / fallow.toml (or the fallow key of package.json).
FindingIgnoreMatcher: Compiled project-relative patterns for hiding source-owned findings.
FixConfig: The fix config section: settings for fallow fix apply behavior.
FlagsConfig: Feature flag detection configuration.
ForbiddenCallRule: One forbidden-call entry: files in zone from may not call callees matching callee.
HealthConfig: Configuration for complexity health metrics (fallow health).
HealthThresholdOverride: Per-file or per-function health threshold override.
IgnoreCatalogReferenceRule: Rule for suppressing an unresolved-catalog-reference finding.
IgnoreDependencyOverrideRule: Rule for suppressing dependency-override findings.
IgnoreExportRule: Rule for ignoring specific exports.
IgnoreExportsUsedInFileByKind: Object form of ignoreExportsUsedInFile ({ "type": ..., "interface": ... }), restricting the same-file-use suppression to type-only exports.
InvalidForbiddenCallee: One rejected boundaries.calls.forbidden[] callee pattern.
LogicalGroup: A user-declared zone that fanned out via autoDiscover.
ManifestEntryRule: A rule that seeds entry points DERIVED from framework manifest files.
ManifestExistsPredicate: The explicit field-presence predicate accepted by ManifestCondition.
ManifestFieldPath: A validated field path into a manifest document.
ManifestPathTemplate: A validated manifest-relative entry path with parsed ${field.path} parts.
ManifestSeedRule: A single entry seeded by a ManifestEntryRule, resolved relative to the manifest’s directory.
NapiConfig: The NAPI-RS napi block of a package.json, used to recognize the per-platform artifact packages a native addon generates so they are not reported as unused dependencies. All fields deserialize leniently: a wrong-typed value becomes None/empty instead of failing manifest parsing.
NormalizationConfig: Fine-grained normalization overrides.
OwnershipConfig: Configuration for ownership analysis (fallow health --hotspots --ownership).
PackageJson: Parsed package.json with fields relevant to fallow.
ParsedOverrideKey: Parsed structure of an override key.
PartialRulesConfig: Partial per-issue-type severity for overrides. All fields optional.
PerAnalysisProductionConfig: Object form of the production config key, scoping production mode to individual analysis families in combined fallow and fallow audit.
PnpmCatalog: A single catalog (the default or a named one).
PnpmCatalogData: Structured catalog data extracted from a package manager catalog source.
PnpmCatalogEntry: A single entry inside a catalog.
PnpmCatalogGroup: A named catalog group under catalogs: with no package entries.
PnpmOverrideData: Structured override data extracted from one source.
PnpmOverrideEntry: A single override entry.
RedundantRootPrefix: One redundant-root-prefix pattern in a boundaries.zones[] entry.
RegressionBaseline: Saved per-issue-type counts written by --save-baseline and compared by --fail-on-regression. Every count defaults to 0 when its key is missing, so hand-trimmed baselines stay loadable.
RegressionConfig: The regression config section holding the saved issue-count baseline for the --fail-on-regression gate.
ResolveConfig: Module resolver configuration.
ResolvedBoundaryConfig: Resolved boundary config with pre-compiled glob matchers.
ResolvedBoundaryCoverageConfig: Resolved boundary zone coverage policy.
ResolvedBoundaryRule: A resolved boundary rule.
ResolvedConfig: Fully resolved configuration with all globs pre-compiled.
ResolvedNormalization: Resolved normalization flags: mode defaults merged with user overrides.
ResolvedOverride: Resolved override with pre-compiled glob matchers.
ResolvedZone: A zone with pre-compiled glob matchers.
RulePackDef: A declarative rule pack loaded from a standalone JSON or JSONC file listed in the rulePacks config key.
RulePackError: One rule-pack load or validation failure, anchored at the offending pack file.
RulePackRule: One declarative policy rule inside a rule pack.
RulesConfig: Per-issue-type severity configuration.
ScopedUsedClassMemberRule: A heritage-constrained usedClassMembers rule.
SdkPattern: A custom SDK call pattern for feature flag detection.
SecurityCategories: Include/exclude lists scoping the active security categories. When include is set, only those categories are active; exclude removes categories from the admitted set. Both unset admits catalogue categories. hardcoded-secret still requires explicit inclusion.
SecurityConfig: Scopes fallow security catalogue behavior. An absent category block admits every catalogue category. hardcoded-secret is include-required and only runs when explicitly listed in security.categories.include.
SimilarCodeConfig: Project-owned tuning for the explicit fallow similar-code workflow.
TypeAwareConfig: Shared opt-in configuration for TypeScript semantic analysis.
UnknownZoneRef: One offending zone-name reference in a boundaries.rules[] entry.
UnusedComponentPropsConfig: Options for the unused-component-props rule.
WorkspaceConfig: Workspace configuration for monorepo support.
WorkspaceDiagnostic: A diagnostic about a workspace-discovery candidate.
WorkspaceInfo: Discovered workspace info from package.json, deno.json, pnpm-workspace.yaml, or tsconfig.json references.

Enums§

AnalysisSnapshot: Which revision an analysis pass describes.
AuditGate: Value of audit.gate: which findings drive the fallow audit verdict.
AutoImportKind: Which export shape a convention auto-import credits when its name is referenced without an explicit import statement.
BoundaryPreset: Built-in architecture presets.
CatalogPrecedingCommentPolicy: Value of fix.catalog.deletePrecedingComments: what happens to comment lines directly above a catalog entry that fallow fix removes. A fallow-keep marker in the block always preserves it regardless of policy.
ConfigFixPlan: Classification of whether fallow can apply config edits at root.
ConfigWriteError: Failure while editing a fallow config file in place (fallow fix config actions such as appending ignoreExports entries).
DetectionMode: Detection mode controlling how aggressively tokens are normalized.
EffectKind: Internal side-effect taxonomy derived from security catalogue rows.
EmailMode: Privacy mode for author emails emitted in ownership output.
EntryPointRole: How a plugin’s discovered entry points contribute to coverage reachability.
ForbiddenCallee: One callee pattern or a list of patterns for a single from zone.
IgnoreExportsUsedInFileConfig: Value of the ignoreExportsUsedInFile config key: whether an export referenced elsewhere in its own file is suppressed from unused-export.
LogicalGroupStatus: Discovery outcome for a LogicalGroup.
ManifestCondition: A typed condition used by a manifest entry gate.
ManifestFieldSegment: One validated traversal step in a ManifestFieldPath.
ManifestFormat: Format of the manifest files a ManifestEntryRule reads.
ManifestPathPart: One parsed part of a manifest entry path template.
MisconfigReason: Why an override entry is misconfigured.
OutputFormat: Output format for fallow results.
OverrideSource: Where an override entry was declared.
PluginDetection: How to detect if a plugin should be activated.
ProductionAnalysis: The analysis families production mode can be scoped to independently via the object form of the production config key.
ProductionConfig: Value of the production config key: excludes test/spec/story/dev files from discovery, either globally or per analysis family.
RulePackRuleKind: Which check a rule-pack rule performs.
Severity: Severity level for rules.
TypeAwareRequire: Completeness policy for opt-in TypeScript semantic analysis.
UsedClassMemberRule: A usedClassMembers entry from config or an external plugin.
WorkspaceDiagnosticKind: Why a workspace-discovery candidate was rejected, or why a sibling directory looked workspace-like but was not declared.
WorkspaceLoadError: Workspace-discovery failures that prevent analysis from proceeding.
ZoneReferenceKind: Which BoundaryRule field carries an unknown zone name.
ZoneValidationError: Validation error from FallowConfig::validate_resolved_boundaries.

Constants§

DEFAULT_MAX_FILE_SIZE_BYTES: DEFAULT_MAX_FILE_SIZE_MB expressed in bytes.
DEFAULT_MAX_FILE_SIZE_MB: Default per-file size ceiling (in megabytes) for source discovery. A value chosen so hand-written source effectively never reaches it while generated API clients, vendored bundles, and minified blobs do. See issue #1086.
KNOWN_RULE_NAMES: Every rule name accepted by RulesConfig deserialization, in kebab-case.

Functions§

add_ignore_exports_rule: Append ignoreExports rules to an existing fallow config file.
add_ignore_exports_rule_to_string: Render the proposed content of a fallow config after appending ignoreExports rules.
add_rule_pack_path: Append a rule-pack path to an existing fallow config file.
add_rule_pack_path_to_string: Render the proposed content of a fallow config after appending a rulePacks entry.
append_workspace_diagnostics: Append additions to the workspace-discovery diagnostics for root, skipping any entry whose (kind id, canonical path) is already present.
atomic_write: Atomically write content to a file via a temporary file and rename.
classify_config_fix_plan: Classify how config-editing fixes should behave for root.
clear_analysis_stage_diagnostics: Remove all analysis-stage diagnostics (see WorkspaceDiagnosticKind::is_analysis_stage) for root from the registry, keeping every workspace-discovery and source-discovery entry.
closest_known_rule_name: Find the closest known rule name to input when it is plausibly a typo.
default_severity_for_kind: The default Severity for an IssueKind under zero config.
dir_has_deno_json: Whether dir has a Deno package/workspace config file.
dir_has_package_manifest: Whether dir has either an npm or Deno package manifest.
discover_and_validate_external_plugins: Discover external plugin definitions AND validate their user-supplied glob patterns. Accumulates all errors across all loaded plugins so the user sees every problem in one run.
discover_external_plugins: Discover and load external plugin definitions for a project.
discover_workspaces: Discover all workspace packages in a monorepo.
discover_workspaces_with_diagnostics: Discover workspace packages and return any diagnostics produced along the way.
find_undeclared_workspaces: Find directories containing package.json that are not declared as workspaces.
find_undeclared_workspaces_with_ignores: Find directories containing package.json that are not declared as workspaces, excluding candidates covered by the supplied ignore globset.
is_config_fixable: Whether fallow fix --yes can apply config edits at root with default config-creation behavior. Drives JSON auto_fixable for config actions.
is_deno_without_node_modules: Whether the project has a root Deno config and should not warn about a missing node_modules directory.
is_opt_in_kind: Whether a rule is opt-in: its default severity is Off, so it detects and reports nothing until a user explicitly enables it.
is_valid_override_value: Check whether value is a valid pnpm override right-hand side, even if it is not a semver range. Returns false when the value is empty, contains a raw newline, or is otherwise garbage.
load_deno_import_map: Load sorted Deno import-map entries and their declaring config path.
load_dir_package_json: Load a directory’s package manifest as PackageJson, preferring package.json and falling back to deno.json / deno.jsonc.
load_member_package_manifest: Load package identity for a workspace member directory.
load_root_deno_workspace_patterns: Load root Deno workspace patterns and their declaring config path.
load_rule_packs: Load and validate every rule pack listed in the rulePacks config key.
override_misconfig_reason: Convenience: is this entry effectively a misconfiguration the user should see as an error?
override_source_label: Source-name string for diagnostics.
parse_bun_package_json_resolutions: Parse the Yarn-style top-level resolutions object of a root package.json the way bun reads it (issue #2367). bun treats resolutions as an alias of overrides with flat string entries: a key is a bare package (left-pad, @scope/pkg, pkg@<2), a yarn dependency path (parent/child, **/child, parent/**/child, where @scope/name spans two path segments), or the pnpm parent>child form. Paths deeper than one parent and non-string values are kept as entries without a parsed key or value so the misconfigured-override detector reports them, matching the warning bun prints before skipping such entries. Keys that start with // are comments and skipped. Returns empty data when the file has no resolutions object or the JSON is malformed. Callers decide whether the repository installs with bun and whether an overrides key shadows the section.
parse_npm_package_json_overrides: Parse the top-level overrides section of a root package.json. Returns an empty PnpmOverrideData when the file has no overrides, when the JSON is malformed, or when the section is present but empty.
parse_override_key: Parse an override key into parent, target, and optional version selectors. Returns None when the key cannot be split into a recognised shape (empty key, parent or target missing).
parse_package_json_catalog_data: Parse Bun catalog sections from a root package.json file.
parse_pnpm_catalog_data: Parse the catalog sections of a pnpm-workspace.yaml file.
parse_pnpm_package_json_overrides: Parse the pnpm.overrides section of a root package.json. Returns an empty PnpmOverrideData when the file has no overrides, when the JSON is malformed, or when the section is present but empty.
parse_pnpm_workspace_overrides: Parse the overrides: section of pnpm-workspace.yaml. Returns an empty PnpmOverrideData when the file has no overrides or when the section is present but empty. Malformed YAML is an Err carrying the parse error text so callers can surface a workspace diagnostic instead of silently dropping every entry.
parse_tsconfig_root_dir: Parse tsconfig.json at the project root and extract compilerOptions.rootDir.
preserve_target_mode: Copy the target file’s existing permissions onto the temp file.
probe_dir_manifest: Load a directory’s package manifest and Deno import map together, probing and parsing deno.json / deno.jsonc once instead of once per consumer.
record_source_read_failures: Replace source-read-failure diagnostics for root with the failures from the current parse while preserving every workspace and discovery diagnostic produced by other stages.
record_workspace_diagnostics: Append diagnostics to the registry for root AND emit their deduplicated stderr warnings, for analysis-stage callers outside this crate (e.g. the pnpm catalog/override gathers in fallow-core) that surface a diagnostic after config load completed. append_workspace_diagnostics alone would reach workspace_diagnostics[] JSON but never warn a human on stderr.
registry_diagnostics_to_fold: Read the registry leg of a diagnostics FOLD: everything workspace_diagnostics_for holds for root EXCEPT the entries a source walk records (see WorkspaceDiagnosticKind::is_source_walk_recorded).
replace_source_discovery_diagnostics: Replace every source-discovery diagnostic for root with diagnostics in ONE registry operation, and hand the same list back to the caller.
resolve_boundaries_for_rule_pack_validation: Resolve boundaries in the same shape used by analysis, without loading rule packs or running discovery.
resolve_max_file_size_bytes: Convert a user-supplied megabyte ceiling into the byte limit stored on ResolvedConfig::max_file_size_bytes. Some(0) means “no limit” (None); any other Some(n) is n MB in bytes; None (unset) keeps the built-in DEFAULT_MAX_FILE_SIZE_BYTES.
stash_workspace_diagnostics: Replace the workspace-discovery diagnostics for root with diagnostics, PRESERVING any source-discovery diagnostics (see WorkspaceDiagnosticKind::is_source_discovery) and analysis-stage diagnostics (see WorkspaceDiagnosticKind::is_analysis_stage) already appended for the root.
validate_rule_pack_zone_references: Validate that rule-pack zones references point at resolved boundary zones.
walkthrough_state_path: Path to the local fallow review --walkthrough viewed-state ledger inside a resolved cache directory (default <root>/.fallow, already gitignored).
workspace_diagnostics_for: Read the workspace-discovery diagnostics produced by the most recent stash_workspace_diagnostics + any subsequent append_workspace_diagnostics calls for root. Returns an empty vector when nothing has been stashed for this root yet (e.g. programmatic callers bypassing the standard loader).
workspace_is_public: Return whether a workspace package name is selected by publicPackages.

Type Aliases§

ConfigWriteResult: Result alias for config-file editing operations.