Static Analysis: Linters, Type Checkers and Formatters
Static analysis finds a bug before the code runs. Learn the categories, the tools, and how to add them to a pipeline without friction.
By Velloreth
What static analysis is
Static analysis examines the code without running it.
The advantage: it finds a bug before a test would, and it covers a path a test may not exercise.
The categories:
- A formatter — the code style.
- A linter — a suspicious pattern.
- A type checker — a type error.
- A security scanner — a known vulnerability.
- A complexity analyser — a function that is too complex.
Formatters
A formatter changes the code to a consistent style.
prettier --write .
gofmt -w .
black .
The value is not the specific style. It is that the style is not a topic of discussion, and a diff contains only a real change.
Run it automatically, on save and in a pre-commit hook. A formatting change in a review is noise.
A formatter is not a linter. It does not find a bug; it removes a debate.
Linters
A linter reports a suspicious pattern.
// eslint: no-unused-vars
const x = 1; // 'x' is assigned but never used
// eslint: no-floating-promises
doSomething(); // a promise is not awaited
// eslint: eqeqeq
if (a == b) {} // use ===
The rules that find a real bug are worth enabling first:
- An unused variable
- A missing
await - A comparison with
== - A shadowed variable
- An unreachable code path
The style rules are a matter of taste, and a large set on an existing codebase produces thousands of warnings that nobody reads.
Add the rules gradually. Start with the bug-finding rules, and add the style rules as the codebase is cleaned.
Type checkers
A type checker finds a type error.
function add(a: number, b: number): number {
return a + b;
}
add('1', '2'); // error: argument of type 'string' is not assignable
The value: a whole class of bug is caught at compile time, and the type is documentation.
A gradual adoption is possible: TypeScript allows any, and a // @ts-check comment enables checking in a JavaScript file.
A strict mode catches more, and it is worth enabling for a new project. For an existing one, enable it file by file.
Security scanners
A dependency scanner checks the dependencies against a database of known vulnerabilities.
npm audit
pip-audit
Dependabot or a similar bot opens a pull request for an update.
A static application security test (SAST) scans your own code for a pattern such as a SQL injection or a hardcoded secret.
A secret scanner checks the repository for a committed credential, which is the highest-value check of the three.
Complexity
A complexity analyser flags a function that is too complex.
npx eslint --rule '{"complexity": ["warn", 10]}'
A high complexity is a signal, not a rule. A function with a complexity of 20 is hard to test and hard to read, and it is a candidate for extraction.
The metric is a prompt to look, not a target to hit.
Where to run it
In the editor, so a problem is caught as it is written. This is the earliest and the cheapest point.
In a pre-commit hook, so a problem is caught before it reaches CI.
npx lint-staged
lint-staged runs the formatter and the linter on the staged files only, which is fast.
In CI, so a problem cannot be merged.
The order matters: the editor first, then the hook, then CI. A problem caught in the editor costs seconds; the same problem in CI costs a pipeline run.
Adding it to an existing codebase
Start with the formatter. It is mechanical, and it produces one large diff that is easy to review.
Add the bug-finding lint rules. Fix the violations, and enable the rule.
Add the type checker gradually. Enable it file by file, starting with the new code.
Add the security scanner. It is independent of the code style.
Do not enable every rule at once. A thousand warnings is a signal that nobody reads, and the tool is then ignored.
Common mistakes
A linter that is not run. A rule that is not enforced is a suggestion.
A large rule set on an existing codebase. The warnings are ignored.
A formatter that is not automatic. A manual format step is forgotten.
A type checker with any everywhere. The type system is bypassed, and the value is lost.
A security warning that is ignored. A known vulnerability in a dependency is a real risk.
A pre-commit hook that is slow. A slow hook is bypassed with --no-verify.
Practical guidance
- Use a formatter, and run it automatically.
- Enable the bug-finding lint rules first.
- Add the style rules gradually.
- Use a type checker, and enable strict mode for new code.
- Scan the dependencies for a known vulnerability.
- Scan for a committed secret.
- Run it in the editor, the hook, and CI.
- Keep the pre-commit hook fast.
- Do not enable every rule at once.
For the related guides, see code-review-checklist and ci-cd-pipeline-basics. For the broader context, unit-testing-basics and git-hooks-guide.
Quotable summary
Static analysis examines the code without running it, so it finds a bug before a test would, and a formatter removes the style debate while a linter finds a suspicious pattern and a type checker finds a type error. A formatter should run automatically rather than in a review, because the value is that the style is not a topic of discussion and a diff contains only a real change. Run the analysis in the editor, in a pre-commit hook, and in CI, because a problem caught in the editor costs seconds while the same problem in CI costs a pipeline run. When adding a linter to an existing codebase, start with the rules that find a real bug and add the style rules gradually, because a large rule set produces thousands of warnings that nobody reads.