Skip to content
Fallow home
All docs pages

Docs home

Findings, rules and gates

Learn what a finding is, how a rule sets its severity, and how severities and gates decide the exit code of a fallow run.

Your first run on an existing project exits with code 1, so a CI job that runs fallow fails at once. You want to keep the report, but fail the job only on the problems that matter to your team. Each problem in the report has a severity, and the severities decide the exit code. You set them, so you choose which problems fail CI and which only show in the report.

Why the first run fails

The entry points of the demo project leave one file and three exports unused. The report also finds two problems with dependencies:

npx fallow dead-code
● Unused files (1)
  src/utils/legacy-currency.ts
  Files not reachable from any entry point
  https://fallow.tools/docs/explanations/dead-code/#unused-files

● Unused exports (3)
  src/lib/format.ts
    :3 formatPercent
  src/lib/index.ts
    :1 formatPercent (re-export)
  src/services/orders.ts
    :18 cancelOrder
  Exported symbols with no known consumers

✗ 1 file · 3 exports · 1 unused dependency · 1 unlisted dependency (0.05s)

The ✗ at the start of the last line means that the run failed. Each problem in it fails the run, because each one has the severity error by default.

Findings and issue types

A finding is one problem that fallow reports at one place: a file, a line, a name or a package. The report above shows four findings in two groups, and the last line counts two more.

The issue type is the kind of a finding. Each finding has one issue type, for example unused-file or unused-export. The issue type tells you what the finding means and how to act on it. Each issue type has a reference page: Issue types lists them all.

Rules and severities

You cannot set a severity for one finding, but you can set it for an issue type. A rule is the entry in the rules config that sets the severity of one issue type. The severity has one of three values:

SeverityFallow reports the findingThe finding fails the run
errorYesYes, exit code 1
warnYesNo. --fail-on-issues makes it fail.
offNo. Fallow does not look for it.No

Each issue type has a default severity. Most issue types that report unused code are at error, for example unused files, unused exports and unused dependencies. Other issue types are at warn, and some are off until you turn them on. The page of each issue type gives its default.

Set the severities in your config file. The key of a rule is often the plural form of the issue type, for example unused-exports for unused-export. The page of each issue type gives its key.

Suppose that your team moves the order functions to a new API, and the old exports must stay until the move ends. This config file keeps the unused exports in the report, but they do not fail the run:

// .fallowrc.jsonc
{
  "rules": {
    // The export cleanup waits for the API migration.
    "unused-exports": "warn"
  }
}

A run of the unused exports alone now exits with code 0. The summary line starts with ⚠:

npx fallow dead-code --unused-exports
⚠ 3 exports (0.06s)

The full fallow dead-code run still exits with code 1, because the unused file and the two dependency findings stay at error. Give each rule that you lower a comment with the reason, so that the team knows when to set it back. Rules and severities shows how to set a rule for some files only.

Gates

A finding at error is the most common reason for exit code 1, but it is not the only one. A gate is a condition that makes a command exit with code 1.

Bare fallow in a machine format exits 0 on findings. In JSON or SARIF, the bare fallow command does not enforce its gates, so a CI step that runs fallow --format json passes with findings at error. Add --fail-on-issues to make it fail. The bare run in a machine format has the details.

These are the gates that most projects use:

GateFails when
SeverityA finding has the severity error.
--fail-on-issuesA finding has the severity error or warn.
A thresholdA number goes past a limit, for example fallow dupes --threshold 5 when more than 5% of the code is duplicated.
The audit verdictA changed-code check gives the verdict fail.

Most CI jobs need only the severity gate. Add --fail-on-issues when a finding at warn must fail the job too. Other options add more gates, for example --fail-on-regression and --fail-on-stale-baseline, and Global options lists them. --ci is the same as --format sarif --fail-on-issues --quiet, a short form for a CI job that uploads SARIF.

Exit code 1 is a result of the analysis. Fallow uses code 2 for invalid input, for example a broken config file. Exit codes lists each code.

The bare run in a machine format

The bare fallow command runs all analyses. In a machine format, it reports the failed gates but does not enforce them, so a tool can read the full report without a failed step. On the demo project, the four forms of the command give these exit codes:

CommandExit code on the demo project
fallow1
fallow --format json0
fallow --format json --fail-on-issues1
fallow dead-code --format json1

The JSON run prints this line on stderr:

[W] Exit code 0: gates error-severity-findings (6 at or above error), health-findings (1 at or above error) failed, but bare fallow does not enforce them in --format json. To exit 1 on them, pass --fail-on-issues.

The JSON output also has a gate_outcomes object. A gate with "status": "fail" and "enforced": false failed, but did not set the exit code.

Act on a finding

A severity decides what fails the run. You still have to decide what to do with each finding, and each one needs one of three actions:

  • Fix the code. Delete the unused code, or add the missing dependency. Remove unused code with fallow fix shows the fixes that fallow can apply.
  • Teach fallow. When fallow is wrong, tell it about your project in the config file, for example with an entry pattern. Fix a false positive gives the fix for each cause.
  • Suppress the finding. Keep the code, and add a comment such as // fallow-ignore-next-line unused-export above it. Suppress a finding shows each comment form.

To stop old findings from failing CI before you fix them, use a baseline.

What a severity cannot do

A rule applies to each finding of its issue type, in the whole project or in the files of an override. To keep one finding and fail on the others, suppress that finding.

A severity does not change how fallow finds a problem. When fallow reports code that your project uses, change the config or the code. Do not lower the severity of the issue type.

Next

  • Next: Plugins. Read it when fallow reports a file that your framework loads.
  • Issue types: each issue type with its default severity.
  • Exit codes: each exit code of each command.