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:
| Severity | Fallow reports the finding | The finding fails the run |
|---|---|---|
error | Yes | Yes, exit code 1 |
warn | Yes | No. --fail-on-issues makes it fail. |
off | No. 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:
| Gate | Fails when |
|---|---|
| Severity | A finding has the severity error. |
--fail-on-issues | A finding has the severity error or warn. |
| A threshold | A number goes past a limit, for example fallow dupes --threshold 5 when more than 5% of the code is duplicated. |
| The audit verdict | A 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:
| Command | Exit code on the demo project |
|---|---|
fallow | 1 |
fallow --format json | 0 |
fallow --format json --fail-on-issues | 1 |
fallow dead-code --format json | 1 |
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
entrypattern. 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-exportabove 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.