Turn off a rule for a file

A rule shouldn’t apply to a specific file: a CLI that legitimately needs stdout, an auto-generated migration, a one-off justified exception. This guide shows the two escape hatches: project-level file exemptions and inline per-line suppression. Both require a reason.

Project-level exceptions file

Drop an exceptions file at the root of the project being checked (same place you run the check). Each checker uses its stack’s native format: chisel-exceptions.toml for Python, chisel-exceptions.json for TypeScript. The schema and the matching semantics are identical; each entry maps file globs to rule IDs and a reason.

Python

chisel-exceptions.toml

[[exceptions]]
files = ["src/legacy/*.py", "src/cli/main.py"]
rules = ["structural:print-banned"]
reason = "CLI requires stdout output"

[[exceptions]]
files = ["src/migrations/*"]
rules = ["*"]               # match every rule
reason = "Auto-generated migrations; no architectural intent."

TypeScript

chisel-exceptions.json

{
  "exceptions": [
    {
      "files": ["src/lib/components/edra/*"],
      "rules": ["component-enforcement"],
      "reason": "Vendored editor; upstream markup, not ours to restyle."
    },
    {
      "files": ["src/lib/generated/*"],
      "rules": ["*"],
      "reason": "Generated API client; regenerated on every build."
    }
  ]
}

• files: glob patterns relative to the project root. * and ? are wildcards, and * also matches across /, so src/*.ts covers nested files too.
• rules: a list of rule IDs, or * to match every rule, or a category prefix like "structural" to match every rule in that category.
• reason: free text explaining why. The checkers don’t parse it, but an entry without one won’t survive review; say why so the next reader doesn’t have to guess.

Inline suppression

For a single line where the rule shouldn’t apply, suppress inline. Each checker uses its own ecosystem’s idiom.

Python

print("boot banner")  # noqa: structural:print-banned — CLI startup banner

Form: # noqa: <rule-id> — <reason>, on the offending line.

TypeScript

// chisel-ignore structural:raw-fetch -- liveness probe, no domain model
await fetch("/healthz");

Form: // chisel-ignore <rule-id> -- <reason>. The directive may sit on the offending line or the line directly above it.

Svelte

<!-- chisel-ignore component-enforcement:html-button-banned -- toolbar trigger, no shadcn slot -->
<button class="...">x</button>

A reason is required. A directive without one suppresses nothing: the original violation stands and the checker adds suppression:missing-reason on top of it. Silencing a rule is a decision someone should have to justify in the diff.

Other forms chisel-js accepts:

• Several rules at once — // chisel-ignore structural:raw-fetch, colour:dynamic-class -- generated file
• A whole category — // chisel-ignore structural -- reviewed
• A whole file — // chisel-ignore-file <rule-id> -- <reason>, in the first five lines.

Syntax differs between the checkers

chisel (Python) uses # noqa:; chisel-js uses // chisel-ignore. Each matches what its ecosystem already reads — noqa in Python, an eslint-disable-shaped directive in TypeScript.

Find the rule ID first

Run chisel explain or read the Python rules / TypeScript rules reference to get the exact rule ID.

Severity and suppression

Severity	Blocks the build?	Suppressible?
ERROR	Yes	Yes — but always with a recorded reason
WARNING	No	Yes
INFO	No	Never blocks, so no need to suppress

Every severity can be suppressed, by either mechanism, and every suppression must carry a reason. The guard is not that some rules are unsuppressible — it is that no suppression is anonymous: an inline directive without a reason fails, and an exceptions entry lives in a tracked file that shows up in review.

That said, most ERROR rules describe a structural problem. If you find yourself silencing one, the fix is usually to move the code, not to quiet the checker. chisel explain <rule-id> states what the rule wants instead.

Verify the exemption worked

Python

chisel check . --json | jq '.violations | length'   # before
# (add the exception / inline directive)
chisel check . --json | jq '.violations | length'   # after

TypeScript

chisel-js check . --json | jq '.violations | length'   # before
# (add the exception / inline directive)
chisel-js check . --json | jq '.violations | length'   # after

Exempted violations disappear from the output entirely; the count dropping confirms the exemption matched. Keep the exceptions file in version control so exemptions are reviewed like any other change.

What’s next

• Block violations before commit: gate commits on a clean check.
• How chisel works: why the rules are fixed rather than configurable.