Adopt fallow in an existing repository
Adopt fallow in a repository with many findings: set a policy, fix the entry points, clean the backlog in order and stop new findings.
On a repository that is some years old, the first run of fallow often lists hundreds of findings. Nobody can fix them in one sprint. If the team suppresses them one by one, the list of exceptions grows, and new findings hide between the old ones. At the end of this guide, your repository has a fallow policy in its config file and a backlog that you clean in a fixed order. A check stops new findings on each pull request.
The work has two parts. First you clean the whole repository once. Then a changed-code check keeps each change clean. You can turn on that check before the backlog is gone, so the backlog cannot grow while you clean it.
Before you start
- Read Entry points and reachability and Findings.
- Install the dependencies of the project.
- Coming from knip? Run
fallow migratefirst. See Migrate from knip. - In a monorepo, do the steps for one package at a time. See Set up fallow in a monorepo.
Steps
1. Run fallow once
npx fallow
The last line of the report names each analysis with findings, and the file to start with. In the demo project, it reads:
Failed: dead-code (6 issues), dupes (1 clone group), health (1 above threshold): start with src/services/customers.ts
Do not fix findings yet, because a finding that you fix before step 3 can be a false positive.
2. Decide the policy
The first report shows how much work the cleanup is, and the team decides how to do it. Decide these points together:
- which issue types fail CI (
error) and which only report (warn), - which files are generated or out of scope,
- which packages ship an API to users outside the repository,
- which complexity limits you enforce.
Write the answers in the config file:
// .fallowrc.jsonc
{
"$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
"ignorePatterns": ["src/generated/**"],
"rules": {
"unresolved-imports": "error",
"unlisted-dependencies": "error",
"unused-files": "error",
"unused-dependencies": "error",
"unused-exports": "warn"
}
}
A rule with warn reports its findings, but they do not fail the run. With this policy, the 3 unused exports of the demo project end with a warning sign:
⚠ 3 exports (0.02s)
Use warn for the large categories while you clean them, and change them to error when they are clean. A rule that you do not list keeps its default. The complexity limits keep theirs too: a cyclomatic complexity of 20 and a cognitive complexity of 15. Change a limit only when the team agrees on a new standard. Rules has each issue type and its default.
If you do not own the policy, do steps 1 and 3 on a branch, and bring the findings to the discussion.
3. Get the entry points right
The policy says which findings count. Before you act on them, make sure that they are true. Each dead code finding depends on the entry points: one missing entry point makes each file that it imports look unused. Check them first:
npx fallow list --entry-points
npx fallow list --plugins
Found 3 entry points
scripts/seed.js (package.json script `seed`)
src/index.ts (package.json main)
src/math.test.ts (vitest)
Compare the list with the way your project starts: the app, the scripts, the workers, the tests. For each missing entry point, follow Fix a false positive. Then run step 1 again. The number of findings often drops a lot.
4. Clean the backlog in a fixed order
With correct entry points, the findings are real, and you can remove them. The order matters, because each step removes findings that the next step would show. Commit after each step.
-
Unused files. Delete them. A file that no entry point reaches cannot run. When you are not sure, trace the file.
npx fallow dead-code --unused-files -
Dependencies. Fix the unlisted dependencies and the unresolved imports first, because they are bugs that have not failed yet. Then remove the unused dependencies.
npx fallow dead-code --unlisted-deps --unresolved-imports npx fallow dead-code --unused-deps -
Unused exports. This category is usually the largest.
fallow fixremoves theexportkeyword for you. For an export that users of a package need, use step 5.npx fallow dead-code --unused-exports --unused-types -
Duplication. Merge the copies that must change together. See Duplication.
npx fallow dupes -
Complexity. Start with the refactoring targets of the report, not with each file above the average. See Health.
npx fallow health
5. Match each kept finding to the right mechanism
Some findings stay after the cleanup. The code is in use in a way that fallow cannot see, or you keep it on purpose. For each one, find the reason, and use the mechanism for that reason. When you cannot give the reason in one sentence, you probably use the wrong mechanism.
| Reason | Mechanism | Good example | Bad example |
|---|---|---|---|
| A framework or tool runs the file. | A plugin, entry or dynamicallyLoaded | One entry pattern for the worker scripts | A suppression comment in each worker file |
| Users outside the repository import the export. | The entry points of the package, publicPackages, or a /** @public */ tag | publicPackages for the one package that you publish | ignoreExports with "*" on each file of the package |
| A tool generates the file. | ignorePatterns | src/generated/** | An ignorePatterns entry that excludes half of src/ |
| The runtime supplies the package. | ignoreDependencies | One package name | A glob that matches each package of a scope |
| You keep an export for a consumer that does not exist yet. | /** @expected-unused */ | One shim export | The same tag on each unused export |
| One place is correct, and no config fits. | A suppression comment with a reason | One fallow-ignore-next-line with -- reason | The same comment in twenty files: that is a config fact |
| The team has another standard for a whole category. | rules, overrides, health limits | unused-exports: warn for a legacy directory | A higher complexity limit to hide three functions |
Fallow reports a suppression comment and an @expected-unused tag that no longer match a finding as stale. Remove them when fallow reports them. Suppression comments and tags has the syntax of each comment.
6. Stop new findings while the backlog remains
The cleanup takes weeks in a large repository, and each merge in that time can add a finding. Turn on the changed-code check in CI. It analyzes the files that a pull request changes, and only the findings that the change adds fail it:
npx fallow audit
Check each pull request shows the job. To check the whole project on each run, and not only the changed files, save a baseline and compare with it.
7. Define done
A backlog without an end point never closes, so agree on what done means. Work in two stages. Turn on the check of step 6 at the end of stage 1, because new findings then cannot grow the backlog.
Stage 1: the check can run.
- The config file holds the policy. Suppression comments are few, and each one has a reason.
- No unresolved imports and no unlisted dependencies are left.
- The unused files and the unused dependencies are gone.
fallow auditruns in CI, and it passes for new changes.
Stage 2: the backlog is gone.
- No function is above the complexity limits, or the team changed a limit on purpose and wrote down why.
- The duplication is below your limit.
- No stale suppression is left, and each rule is
error.
Check the result
npx fallow
The run exits with code 0, or it fails only on the findings that stage 2 still lists.
If it fails
| Problem | Cause | Fix |
|---|---|---|
| Hundreds of unused files. | Fallow found the wrong entry points. | Go back to step 3. |
| The same exception appears in many files. | The reason is a fact about the project. | Move it to the config file. |
| The warnings never become errors. | Nobody owns the change. | Set a date for the change from warn to error. |
| The baseline only grows. | CI saves a new baseline after each merge. | Save it on a schedule, and review the diff. See Start with a baseline. |
Related
- Next: Check each pull request. Add the changed-code check to CI at the end of stage 1.
- Start with a baseline: check the whole project without the old findings.
- Fix a false positive: the fix for each cause.