v3.32.0: grouped health trends, markdown from saved runs, dead-code accuracy fixes

Features

• fallow dead-code --absent-component-props reports optional props that callers never pass. The rule reports an optional component prop that no known reachable caller passes. It is off by default. It supports React, Preact, Solid, Qwik, Vue, Svelte, Astro, Angular, Lit and Ember components. Each finding shows the declaration, the callers, the framework and whether a default exists. Fallow gives no finding when it cannot see every caller of the component. Static analysis does not prove that a prop is unreachable at runtime. Review defaults and API intent manually. The rule has no automatic fix.
• fallow health --group-by selects groups and tracks a trend per group. --group <KEY> keeps only the matching groups. It accepts exact keys, globs and ! negations. Each group gets severity and hotspot counts. --save-snapshot on a grouped run stores the group data (snapshot schema v11). --trend or the new --trend-from <PATH> then adds a trend per group. Markdown and the GitHub job summary get a ## Health by <mode> table and one findings block per group. --top N now applies to each group. The MCP check_health tool accepts group and trend_from.
• fallow report --from <file> --format markdown renders saved JSON output. A saved dead-code, dupes, health or bare combined run gives the same markdown as the live run with the same flags. You can analyze once and write both a job summary and a markdown report from one JSON file. The saved output of a combined run does not record --group-by, so its markdown is not grouped. A saved audit, security or fix run, and a combined run with type-aware evidence, exit 2 with a reason.
• fallow dupes marks symlinked clone instances. A clone instance under a symlink now has is_symlink: true in JSON, symlink=true in compact output and a (symlink) marker in human output. To report only duplication between real files, set duplicates.ignoreSymlinks: true or pass --ignore-symlinks. --no-ignore-symlinks overrides the config value. The MCP tools, the Node API, the LSP and the VS Code setting fallow.duplication.ignoreSymlinks accept the same option. Thanks @lzear for the report (#2961).
• fallow agent install adds a native commit gate for Codex. The install writes a PreToolUse handler to .codex/hooks.json and the gate script to .codex/hooks/fallow-gate.sh. The handler runs the audit from the nearest install root, also from a subdirectory. The Claude Code handler now also finds the nearest install root. Run fallow agent install again to get the new handler. Codex runs a hook only after you trust it in /hooks. fallow agent status shows the gate as its own row, and fallow hooks status --format json adds a codex_gate entry. The AGENTS.md block is now routing guidance. fallow hooks install --target agent --agent codex --user now writes the user gate and no longer writes the project AGENTS.md block.
• The new fallow-setup skill tells an agent how to add code-quality tools. The skill is for a JavaScript or TypeScript project. It tells the agent to detect the existing tools, run fallow recommend, install Fallow as a dev dependency and add a CI gate with a baseline. It gives each tool one job, and it removes a tool only after a parity check. fallow agent install writes it next to the fallow skill.
• The gdp-proof-producer rule-pack kind restricts proof producers. The opt-in rule restricts @gdp-ts/core.defineProof calls to allowedFiles. proofKinds assigns literal proof labels to owner modules. The analysis follows static imports and unambiguous re-export chains.
• Fallow has new built-in plugins.
  • release-it keeps each .release-it.* config form and reads the package.json key. It does not read the JSON5, YAML and TOML forms. It credits the plugins and extends packages.
  • eve makes agent modules entry points.
  • ag-ui credits the hooks of a class that extends AbstractAgent directly.
  • nestjs-trpc credits the methods that the module calls.
  • kibana reads kibana.jsonc plugin manifests and adds their entry points.
• The health JSON names the sections that the run produced. The root array sections lists each section that the run computed. With --baseline, summary.baseline_staleness.remaining_findings gives the number of functions above a threshold that the baseline does not accept.
• The CLI, MCP and the LSP report the same finding_id for a security finding. The VS Code "Copy Fallow finding id" quick fix now works on a security candidate (#3035).
• Fallow can suggest its Claude Code plugin. Inside a Claude Code session, Fallow writes one hint line to stderr for human output. Fallow writes the hint only without --quiet, outside CI, and when no Fallow plugin or skill is installed. The hint has no effect until the official marketplace lists the Fallow plugin. Set FALLOW_CLAUDE_CODE_HINT=off or FALLOW_SUGGESTIONS=off to suppress it.

Changed

• Tooling dependencies need evidence of use. Three kinds of devDependency no longer count as used by name alone:

  • A command-line tool from the tooling catalogue.
  • A tooling package of an active plugin.
  • A @types/X package.

  A tool counts as used when a script, a CI workflow or a git hook runs it. It also counts when its config file or its package.json key exists, or when a plugin credits it. Fallow now reads git hooks in .husky/, lefthook, simple-git-hooks and lint-staged configs. A @types/X package counts as used when the project declares or imports X, or names X in tsconfig types. A short list of global type packages, such as @types/node, always counts. --trace-dependency names each credit. Production dependencies still count as used by name.

• Root dependencies follow the nearest manifest. Each import now counts for the nearest manifest that installs the package. Fallow reports a root declaration as unused when each import uses a workspace declaration. The finding has a declared_and_imported_in field that names those workspaces. Such an entry gets one finding, not a second test-only or type-only finding.

• export default Name links to the local binding Name. Fallow now reports unused members of a class that a file exports this way. With ignoreExportsUsedInFile, such a default export is used when the file uses Name.

• fallow health --group-by counts a clone in each group that holds an instance. The group duplicated_lines values now sum to the project value. Group scores can drop once after the upgrade.

• CODEOWNERS matching follows GitHub. A pattern without a trailing / owns the directory contents. * does not match /, apps/ matches an apps directory at any depth, and /* owns only the files at the root. Owner groups can change.

• Gate rows show a count. The health-findings and error-severity-findings entries in gate_outcomes now have observed and threshold_label. The PR decision and the PR comment show the count, for example 6 at or above error.

• fallow hooks install --target agent selects Codex from a .codex/ directory, not from AGENTS.md alone.

Bug fixes

Dependencies

• Fallow no longer reports an optional peer of a used dependency as unused. Fallow also no longer reports a devDependency that the same manifest lists as a peer. An optional peer that the project does not list no longer credits its own peers.
• A peer-only entry no longer hides the ancestor workspace that installs a package. A workspace file can use a package that an ancestor manifest declares. This does not apply to production code in a publishable workspace. An ancestor declaration counts as used when a nested workspace uses it.
• A postcss.config.* file credits the PostCSS plugins that it names, also without a declared postcss package.
• A script binary credits every package that can provide it, for example run-p for npm-run-all2.
• Fallow credits a runtime loader that a tool config needs, such as ts-node for a TypeScript Jest config. The Mocha plugin reads .mocharc files and the mocha key.
• A tool config file in a workspace package credits the root devDependency of that tool.
• require.resolve and import.meta.resolve with any subpath credit the package. require.resolve('pkg') reports an unlisted package. Thanks @DrJKL for the report (#3213).
• import {} from 'pkg', a module augmentation declare module 'pkg', and a node_modules/.bin/<name> path in source credit the package.
• Fallow credits Expo config plugins in the app config, Oxlint jsPlugins inside overrides, and packages in Starlight customCss.
• React Router apps without entry.server no longer report isbot as unused.
• An esbuild call in a test file no longer removes the credit that a dependent workspace gets for the packages of a private sibling. Fallow removes that credit only when a build file or a package script sets every package external.
• --trace-dependency gives the same credits as the dependency report. It names each manifest that the report flags.

Entry points and plugins

• The tsdown and tsup plugins read JSON configs, the package.json key and string or object entry values. They also read config arrays, configs in workspace packages and tsdown workspace globs. Thanks @moltar for the report (#3209).
• Playwright reads every defineConfig argument and the static testDir and testMatch settings.
• These files are now entry points: the test files of a bare node --test script, the tests of a vitest config that a script passes with --config, a file that a command substitution runs, and a file that a CI step runs with Bun.
• The Vite root option moves the default entries. An electron-vite config sets the main and preload entries. Default electron-builder script configs stay used.
• Vercel functions in api/ are entry points, and the Vercel plugin also activates on vercel.json. Next.js instant, prefetch and unstable_dynamicStaleTime segment exports are used.
• Jest setup files that start with <rootDir> resolve, also in projects.
• A config value or an alias replacement that calls a local path helper resolves.
• Quoted commands that concurrently runs count as used.
• A root link: or file: dependency on a local package makes that package a workspace.

Exports, types and class members

• A JSDoc @import tag keeps the imported module used.
• Fallow now reports an orphan module declaration file as an unused file.
• A type that shapes an exported const is no longer an unused type. This covers a wrapper call, a type assertion, a satisfies clause and an inferred factory return. With private-type-leaks on, a private type in a wrapper call, an assertion or an inferred return now gives a finding.
• Fallow now reports an exported type that backs only unused exports.
• Fallow credits class members through a destructured field of an inline-typed parameter, an awaited async factory, a ?? or || fallback, a nullable ternary, and a Map value.
• Fallow credits the exports that code reads through dynamic imports: a member read on an awaited import, a Promise.all destructure, a local loader function, an assignment to an existing binding, and ssrLoadModule.
• A test spy call on a namespace import credits only the spied member.

Import resolution

• An import of ./Button reaches Button/index.ts before a sibling Button.css or Button.vue. Thanks @osazemeu for the report and the initial fix (#3201, #3202).
• A relative import or a package subpath with a missing gitignored target gives no unresolved-import finding. A file URL passed to a filesystem call also gives no such finding.
• A relative import into a tsconfig outDir, and a workspace export with a declaration target, resolve to the source file.
• A * in a package exports target matches files in nested directories.
• A package.json entry under a missing lib/ directory, such as ./lib/index.mjs, maps back to the same-stem source file in src/. A workspace import through an exports target under lib/ also resolves to the source file. Thanks @moltar for the report (#3208).
• Markup inside an inline <script> body is no longer an HTML asset reference.
• Fallow reads a loose deno.json as Deno does. A malformed config in the tsconfig extends chain gives a malformed-tsconfig diagnostic.

Health, duplication, security and CI

• The health score penalizes hotspots only when their score reaches 50 (formula version 3). Trends compare scores only when both formulas are known and equal. Thanks @PaulCailly for the report (#3203).
• fallow health --save-snapshot --trend no longer compares a run with its own snapshot.
• A grouped --score run no longer shows group findings that the project section does not show. Job summaries with a baseline give the number of functions above a threshold.
• A failed run prints one stderr line that names the gate that set exit code 1. In the bare run, the type-aware-require entry now fails when a section fails on type-aware completeness.
• A bare human run with --fail-on-regression prints the regression outcome once.
• fallow dupes --fail-on-issues and --ci exit 1 when clone groups are found. Thanks @TiagoGranelli for the report (#2984).
• overrides[].rules apply to security candidates. fallow security now fails on a candidate only when the rule of that candidate is error. Thanks @TiagoGranelli for the report (#2985).
• The override and catalog checks follow the pnpm version. They skip pnpm.overrides on pnpm 11 and later, and pnpm-workspace.yaml overrides where pnpm ignores them, and the new pnpm-workspace-overrides-ignored diagnostic says why.
• A catalog: value in a pnpm override counts as a catalog reference. unresolved-catalog-references reports an override that names a catalog without that package. Thanks @PrinceD96 for the report (#3078).
• unused-dependency-overrides reports no findings when the npm or pnpm lockfile does not parse and no other lockfile parses. A workspace diagnostic tells you to resolve the merge conflicts or to run the install again.

CLI and editors

• The editor Code Lens above an export shows "imported by N files". Thanks @danielo515 for the report (#3064).
• fallow watch no longer stops on a change outside a nested .gitignore directory.
• The VS Code extension downloads a musl binary on a musl Linux host.
• fallow hooks status and fallow agent status show paths with / on Windows.
• A global flag before the subcommand no longer hides the check and review aliases. fallow security and fallow similar-code reject every --dupes-* override.
• The missing API key message names the cloud command that ran.
• The bundled skill references describe fallow trace --path, fallow coverage analyze --debug-unmatched and the ignoreDependencies globs.

Performance

• YAML files parse faster. A 1.3 MB pnpm-lock.yaml parses in 12 ms in place of 21 ms. A plain number in a pnpm-workspace.yaml override keeps its source text. A pnpm-workspace.yaml that does not parse now reports the malformed-pnpm-workspace-yaml diagnostic.

Upgrade notes

• The extraction and graph cache versions change, so the first run after the upgrade parses all files again.

• These changes can report new unused dependencies:

  • the tooling credit rules,
  • the nearest-manifest rule for root dependencies,
  • the @types/X rule.

  Use ignoreDependencies for a tool that the project runs in a way that Fallow does not see.

• A CI job that runs fallow dupes --ci now fails when the project has clone groups. To keep a job that only reports, use --format sarif --quiet, or gate with --threshold.

• Group scores of fallow health --group-by can drop once. CODEOWNERS owner groups can change.

• The dead-code, audit, review-brief and combined schema versions advance, because the enum of policy rule kinds gains a value.

Full Changelog: v3.31.0...v3.32.0