cofferdam.toml reference

Every key cofferdam reads. Generated from the loader's own schema, so it cannot fall out of step with what the binary accepts.

A key that appears in no section below is ignored. Cofferdam says so when it loads the file — an unknown key used to parse cleanly and do nothing, which made a typo indistinguishable from a rule that simply never matched.

Exclusion is not configured here: it is a discovery-time decision and lives in .cofferdamignore or .gitignore. To turn a check off over a path glob without removing the file from analysis, use [[overrides]] with disabled = true.

Top level

Keys written at the root of the file, before any table header.

Key	Type	Default	Meaning
plugins	array of paths	[]	Node plugin modules implementing the @cofferdam/check-sdk defineCheck shape. Paths resolve relative to this file's directory.
checks	table	—	Per-check configuration. See the section below.
layers	table	—	Architectural layers for Design.LayerViolation. See the section below. cofferdam.invariants.toml is the preferred home; when both files declare [layers], that one wins and cofferdam prints a hint.
engine	table	—	Engine-level toggles. See the section below.
budgets	table	—	Caps on finding counts. See the section below.
overrides	array of tables	[]	Per-path-glob check configuration. See the section below.
context_suppress	array of tables	[]	Suppression of noisy cofferdam context digest items. See the section below.

[checks."Category.Name"]

One block per check. Option names come from that check's own schema — run cofferdam explain <id> to see them — so cofferdam cannot list them here. Two keys are common to every check.

Keys are chosen by you — each is a check id.

Key	Type	Default	Meaning
severity	string	—	Override the check's default severity: info, low, medium, high or critical.
enabled	bool	—	Passed to the check as an option. Only Refactor.PurityHeuristic declares it (as its opt-in switch); for every other check it is accepted and ignored. To turn a check off over a path glob, use [[overrides]] with disabled = true.

[layers]

Layer name → array of globs. The reserved sub-table [layers.allow] maps each layer to the layers it may import from; an empty array means an isolated layer, and a layer absent from allow may import from anything.

Keys are chosen by you — each is a layer name (or the reserved allow).

[engine]

Engine-level toggles.

Key	Type	Default	Meaning
type_aware	bool	true	Set false to force-disable type-aware checks even when one is registered, so CI machines without Node pay no type-host cost and see no warning.
extra_extensions	array of strings	[]	Extensions to walk beyond the built-in set, e.g. ["md", "mdx"]. Leading dots are stripped; empty entries ignored.

[budgets]

Check id or category name → maximum finding count. Counted including baselined findings: a budget is a cap on total debt, not a CI-gate exemption.

Keys are chosen by you — each is a check id or category name.

[[overrides]]

Repeatable. Each block narrows check configuration to a set of path globs.

Key	Type	Default	Meaning
paths	array of globs	[]	Files this block applies to. Gitignore-style globs, matched against project-relative paths.
checks	table	—	Check id → the same option table a top-level [checks."X.Y"] block takes, plus disabled = true to turn the check off for these paths.

[[context_suppress]]

Repeatable. Each block suppresses one cofferdam context provider on a set of paths.

Key	Type	Default	Meaning
check_id	string	—	The Context.* provider to suppress. Required.
paths	array of globs	[]	Files to suppress it on. Omit for the wildcard form — suppress everything this provider emits.
reason	string	—	Why. Not enforced, but cofferdam context --lint-context-suppress reports rules that no longer match anything, and a reason is what makes the report actionable.

Related files

• cofferdam.invariants.toml — layers, public API, frozen boundaries and scripted invariants. Run cofferdam invariants show to see what a run actually resolved.
• .cofferdamignore — files to keep out of analysis entirely.
• .cofferdam/knowledge/*.md — curated notes surfaced by cofferdam context.