Linting from first principles

A linter is a static analyzer for code: it reads the source, builds a model of it (usually an AST), runs a set of rules against the model, and reports rule violations. Static means it never executes the code — which is why a linter can't catch every bug, and also why it can run on every commit in seconds.

The original lint was a 1978 C tool from Bell Labs that found classes of bug the early compilers missed: uninitialized variables, dead code, type confusion. Modern linters extend the lineage in three directions:

• Wider rule sets. Style consistency, naming, library-specific anti-patterns, security smells.
• Faster runtimes. Incremental, parallel, often written in Rust or Go to clear millions of lines in seconds.
• Tighter editor integration. Most ship an LSP server so diagnostics appear inline as you type.

The trade-off in one sentence: a linter is anything that catches mistakes without running the code. The further you push toward catching real bugs, the slower and noisier it gets. The further toward style, the cheaper and quieter — but the less load-bearing for correctness.

Linter rules cluster into four bands by what they enforce and what a violation actually costs:

Most modern tools (ESLint, Ruff, Clippy) bundle plugins covering multiple bands. The clean architectural split — formatters (Prettier, Black, gofmt) own formatting; linters own everything else — has eroded as Ruff, Biome, and others absorb both jobs.

Not every rule deserves to be on by default. A rule that produces 10× more noise than value is removed faster than it is fixed. False positives are the single biggest reason teams disable rules and stop trusting the tool — more on this in step 7.

Auto-fix splits along two axes: how confident the rule is that the fix is correct, and whether the fix preserves behavior.

# Always auto-fixable — pure formatting; behavior unchanged.
x=1+2          # before
x = 1 + 2      # after

# Safely auto-fixable — unused import; no side effects on removal.
import os      # never referenced elsewhere

# Conditional fix — preserves behavior in most cases.
if not (x == None):    # before
if x is not None:      # after — semantically identical when x is None or a value

# Never auto-fixed — would change behavior.
# Rule: "this function should be async"
def fetch(): ...       # turning into async def changes every call site

ESLint classifies rules with fixable: "code" | "whitespace" | null. Ruff splits --fix (safe) from --unsafe-fixes (may alter semantics). The principle is invariant: a fix that might break code under any reasonable interpretation must be opt-in. Erode that and developers stop trusting --fix — at which point the productivity gain inverts.

Naive linters use regex; serious ones parse the source into an Abstract Syntax Tree and walk it. The difference matters because regex can't tell console.log inside a comment from a real call.

// What ESLint sees for: const x = 5
{
  type: "Program",
  body: [{
    type: "VariableDeclaration",
    kind: "const",
    declarations: [{
      type: "VariableDeclarator",
      id: { type: "Identifier", name: "x" },
      init: { type: "Literal", value: 5 }
    }]
  }]
}

A rule like no-var is a visitor: walk every VariableDeclaration node, report when kind === "var". A rule like no-unused-vars needs more: build a scope graph, mark every declared identifier as unused until something references it, report the leftovers at end-of-scope.

AST-based rules are also why linters can auto-fix: a fix means rewriting the AST and printing it back to source. Regex-based replacements break formatting and miss context; AST-based replacements preserve both.

The major linters by language. The implementation-language column matters because it largely sets the speed-of-runtime, and that decides which workflows are practical:

Ruff is the case study in how speed reshapes adoption. flake8 + pylint + isort on a large codebase took 30–60 seconds; Ruff does the same work in under a second. That moves the lint from "CI step" to "every keystroke" and turns rules that were impractical to run pre-commit into the default.

Three integration points, each with a different cost/feedback trade-off:

• Editor / LSP. Diagnostics inline as you type. Tightest loop, lowest cost — the bug surfaces before the commit. Ruff, ESLint, Clippy, and golangci-lint all ship LSP servers.
• Pre-commit hook. Runs on staged files before each commit. Cheap because the file set is small. Catches issues before they reach review. The pre-commit framework or per-repo lefthook/husky are the usual carriers.
• CI gate. Runs on every PR. Authoritative — what the team treats as clean. Slow to iterate against if it is the only signal.

The right shape is usually all three: LSP for fast feedback, pre-commit to keep noisy commits out, CI as the final source of truth. Each layer must run the same rule set — divergent configs between editor and CI is a top cause of works on my machine, fails in CI. Commit the lint config to the repo, install the editor extension that reads it, and gate CI on the same binary.

One caveat: pre-commit hooks should be fast. A 10-second hook trains developers to use --no-verify and ignore the layer entirely.

The hardest thing about linting is not writing rules — it's deciding which to keep on. A rule with a high false-positive rate burns trust at every diagnostic the developer ignores. Once trust is gone, the team begins disabling rules in batches and the tool becomes decorative.

A working heuristic: a rule should be on by default only when its signal-to-noise ratio is above roughly 10:1 — fewer than one false positive per ten real catches. Below that, gate it behind opt-in or drop its severity.

Three patterns that contain false-positive damage:

• Inline disable comments. # noqa: E501, // eslint-disable-next-line, #[allow(clippy::needless_return)]. Cheap escape hatch; visible in code review.
• Severity tiers. error vs warning vs info. CI fails on errors only; warnings are noise the developer can triage when convenient.
• Repository-scoped overrides. Turn rules off in tests/, vendored code, generated files. Stops the tool fighting parts of the codebase that aren't first-party.

The principle: a noisy linter is worse than no linter, because the developer learns to ignore all diagnostics. Tuning is the work.

Most teams eventually reach for custom rules. The trigger is usually a class of mistake that keeps re-appearing in code review and the team wants to mechanize the catch.

// Custom ESLint rule: ban direct calls to fetch() in favor of the app's httpClient.
module.exports = {
  meta: {
    type: "problem",
    docs: { description: "Use httpClient, not fetch" },
    messages: { useClient: "Use httpClient.get/post instead of fetch()." },
  },
  create(context) {
    return {
      CallExpression(node) {
        if (node.callee.type === "Identifier" && node.callee.name === "fetch") {
          context.report({ node, messageId: "useClient" });
        }
      },
    };
  },
};

The honest costs:

• Maintenance. Every language/framework upgrade may change AST node shapes; the custom rule becomes someone's recurring chore.
• Discoverability. The rule's existence has to be findable; otherwise new hires hit the diagnostic and have no idea what convention they violated.
• False-positive risk. Your custom rules are not battle-tested across thousands of repos like the stock ones. Expect to tune.

A custom rule beats a documentation page when the violation is a mechanizable AST pattern. When the rule needs runtime context ("this should call X if inside a transaction"), it is usually outside what linting can express — it belongs in the type system or a code-review checklist.