Adopt Fallow in an existing repo

This guide is for repositories that already have backlog: unused code, duplicates, complexity hotspots, and existing exceptions.

By the end of this guide you will have:

• a repo-level Fallow policy encoded in config
• dead code fixed or intentionally modeled
• duplication at or below your chosen threshold
• complex functions refactored or consciously widened with a written justification
• fallow audit enforcing the same policy on changed files

Repo clean vs PR clean

These are different goals. Both matter. Do them in order.

Start with repo clean. Then turn on PR clean.

Before you start

1. First run: get the whole picture

From your project root:

npx fallow

The quick start covers the focused commands you will use during cleanup (dead-code, dupes, health) and fallow init for generating a starting config.

2. Decide the project policy before triage

Do not start by suppressing findings one by one. That path turns into an ever-growing list of inline exceptions and no coherent policy.

First decide, as a team:

• what counts as a real entry point (workers, scripts, route files, dynamically loaded modules)
• which files are generated or out of scope
• which packages are public APIs that ship exports outside the repo
• which dependencies are runtime-provided or intentionally retained
• which health thresholds you actually want to enforce
• whether duplication should warn or fail

A reasonable starting point:

{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "ignorePatterns": ["**/*.generated.ts", "**/*.d.ts"],
  "rules": {
    "unresolved-imports": "error",
    "unlisted-dependencies": "error",
    "unused-exports": "warn"
  }
}

Rules you do not list inherit their defaults. Health thresholds default to maxCyclomatic: 20 and maxCognitive: 15; override in a health block only when your repo's realistic baseline differs.

3. Work findings in the right order

Use this order for most existing repos. Each step removes noise that would otherwise distort the next step.

1. 1

   Fix unresolved imports and unlisted dependencies

   High confidence, low debate. These are real bugs waiting to happen and should be cleared first.

   npx fallow dead-code --unresolved-imports
   npx fallow dead-code --unlisted-deps

2. 2

   Delete unused files

   Unreachable files are usually safe cleanup. Use fallow list --entry-points to sanity-check reachability before deleting anything you are unsure about.

   npx fallow dead-code --unused-files
   npx fallow list --entry-points

3. 3

   Remove unused dependencies

   Remove dead packages early. This reduces noise in later steps and speeds up installs.

   npx fallow dead-code --unused-deps

4. 4

   Clean up unused exports, types, enum members, and class members

   Usually the biggest category. Fix real dead code. Model intentional API surface with visibility tags or config instead of suppressing it. Hand this step to an agent using the prompt in section 8.

   npx fallow dead-code --unused-exports --unused-types

   Add --unused-enum-members and --unused-class-members when you want to focus on those categories explicitly. In a TypeScript project, add --type-aware when aliases, re-exports, class contracts, packages, or exact consumers affect the decision. This starts an optional, slower semantic pass. See Type-aware TypeScript analysis and the fallow dead-code reference.

5. 5

   Consolidate duplication

   Merge repeated logic into shared helpers. Only ignore generated or template-heavy files when the duplication is genuinely intentional.

   npx fallow dupes
   npx fallow dupes --mode semantic   # also catch renamed-variable clones

6. 6

   Split health hotspots

   fallow health output includes Hotspots and Targets sections that rank the worst offenders. Use those to prioritize. Do not bike-shed every file above the mean.

   npx fallow health

4. Match the reason to the right mechanism

Do not default to inline suppression. Pick the mechanism that matches the reason.

External or public API

Exports consumed outside the repo (published libraries, SDKs, public packages).

Prefer, in order:

• @public, @internal, @beta, @alpha JSDoc visibility tags on the export
• publicPackages as the coarse switch for "this whole package is external API"
• ignoreExports only when file-level or export-level exceptions cannot be expressed any other way

publicPackages and visibility tags are complementary, not alternatives: publicPackages marks the package as externally consumed; @public/@internal tags distinguish public API from internal helpers that happen to be exported for cross-file use.

Framework or runtime-discovered entry points

Files your framework or runtime invokes but no other module imports directly (workers, CLI scripts, route files, plugin modules).

Prefer, in order:

• built-in plugin detection (Next.js, Vite, NestJS, Remotion, and dozens more are handled out of the box)
• entry for project-specific entry globs
• dynamicallyLoaded for code pulled in through reflection, manifests, or dynamic imports
• fallow list --entry-points to inspect what Fallow already considers reachable

Generated or vendored files

Files produced by a build step, code generator, or vendored third-party bundle.

Prefer:

• ignorePatterns to exclude them from analysis entirely
• health.ignore when the noise is health-only and dead-code analysis should still run
• duplication configuration for clone-heavy generated code

Runtime-provided or intentionally retained dependencies

Packages installed for runtime usage only (no static import), CLI tools, or peer dependencies.

Prefer:

• ignoreDependencies with the exact package names

One-off intentional unused export

An export you want to keep around deliberately (compatibility shims, future API).

Prefer:

• /** @expected-unused */ on the export

One-off false positive

A specific site where Fallow is wrong and no config rule captures the reason cleanly.

Prefer:

• // fallow-ignore-next-line <issue> on the line above
• // fallow-ignore-file <issue> only when the whole file is truly exceptional

Repo-wide policy change

The project genuinely has a different standard for a whole category.

Prefer:

• rules, health, duplication thresholds, or overrides blocks

Do this only when it reflects a real team policy, not to hide a few ugly hotspots.

5. Keep exceptions narrow and reviewable

Narrow exceptions are an asset. Broad exceptions are a debt.

Good:

• a single @public export on a library entry point
• one ignoreDependencies entry for a runtime-provided package
• one entry pattern for worker scripts
• one file-level generated-code ignore with a comment explaining why

Bad:

• broad ignorePatterns that silently exclude half the repo
• repeated inline suppressions that could be one config rule
• raising global health.maxCyclomatic to hide a handful of hotspots (acceptable only when the new threshold reflects a thought-through project standard with written justification)

If you cannot explain an exception in one sentence, it is probably the wrong mechanism.

6. Define done

Work in two stages. Most teams ship fallow audit at the end of stage 1 and finish stage 2 over the following weeks.

Stage 1: good enough to ship fallow audit

• the chosen policy is encoded in config, not accumulated in scattered suppressions
• unresolved imports and unlisted dependencies are cleared
• blatant dead code (unused files, unused dependencies) is removed
• fallow audit is wired into CI and passes for new changes against the default branch

Stage 2: ideal state

• no functions above your chosen health thresholds, either by refactoring or by consciously widening the threshold with written justification
• duplication at or below the chosen threshold
• stale suppressions gone or consciously accepted

7. Turn on PR enforcement

Once stage 1 is done, add the PR gate:

npx fallow audit

fallow audit runs dead code, duplication, and complexity analysis scoped to changed files, then returns a pass, warn, or fail verdict. See the fallow audit reference for flags and CI recipes.

Pick one rollout strategy

{
  "rules": {
    "unused-exports": "warn",
    "unused-files": "warn",
    "unused-dependencies": "warn"
  }
}

You can also configure baselines in .fallowrc.json and run fallow audit with no flags:

{
  "audit": {
    "deadCodeBaseline": "fallow-baselines/dead-code.json",
    "healthBaseline":   "fallow-baselines/health.json",
    "dupesBaseline":    "fallow-baselines/dupes.json"
  }
}

8. Clean up with an agent

Fallow finds the problems. An AI agent (Claude Code, Cursor, Codex, Windsurf, any shell-capable coding assistant) is the right tool to fix them: edits are mechanical but decisions ("delete this export" vs. "mark it @public" vs. "add it to entry") benefit from code-aware judgement.

Three levels of integration, pick whichever your agent supports:

Adopt Fallow in this repository.

Goal:
- use full-repo analysis first (`fallow`, `fallow dead-code`, `fallow dupes`, `fallow health`), not `fallow audit`
- fix real dead code, duplication, and complexity issues in code
- model intentional exceptions with the narrowest correct mechanism
- end with no functions above the repo's chosen health thresholds, or a consciously widened threshold with written justification
- then set up `fallow audit` as a PR gate

Process:
1. Run `npx fallow`, then `npx fallow dead-code`, `npx fallow dupes`, and `npx fallow health`. Use `--format json` if you want structured output.
2. If no config exists, run `fallow init` and create a minimal repo policy.
3. Fix high-confidence issues first:
   - unresolved imports
   - unlisted dependencies
   - unused files (sanity-check with `fallow list --entry-points`)
   - unused dependencies
4. For each remaining finding, choose one path:
   - fix it in code (preferred)
   - model it in config
   - add a narrow inline exception only if it is truly one-off
5. Match reasons to mechanisms:
   - external API: `@public` / `@internal` / `@beta` / `@alpha`, or `publicPackages`
   - runtime or framework entry point: `entry`, `dynamicallyLoaded`, plugin-aware config
   - generated code: `ignorePatterns`, `health.ignore`
   - intentionally retained dependency: `ignoreDependencies`
   - intentional unused export: `@expected-unused` (preferred over inline comments because it self-cleans)
   - one-off false positive: `fallow-ignore-next-line`
   - repo-wide policy: `rules`, `health`, duplication settings, `overrides`
6. Prefer config-level modeling over repeated suppression.
7. Keep every exception narrow and explain why it exists in a commit message.
8. Re-run Fallow after each batch until the repo is clean under the chosen policy.
9. Only after repo cleanup, run `npx fallow audit` and wire it into CI.

At the end, report:
- code changes
- config changes
- exceptions added and why
- anything left
- the final commands and outputs that show the repo is clean

Next steps