cofferdam

Appearance

Command-Line Help for cofferdam ​

This document contains the help content for the cofferdam command-line program.

Command Overview:

cofferdam ​

TypeScript code-quality analyzer

Usage: cofferdam <COMMAND>

Subcommands: ​
  • hello — Print the project banner
  • check — Run all checks against files or directories. With no arguments, walks the current directory
  • verify — Opt-in check mode for built HTML output (CD-85). Discovers only the given output directory (e.g. dist/, .next/, build/) and runs ONLY checks explicitly tagged as output-mode-eligible (Check::output_mode() == true) against it — plain cofferdam check runs never see this tree and are completely unaffected
  • baseline — Manage the baseline of accepted findings. The baseline lets you drop cofferdam into an existing project without immediately failing CI on every pre-existing finding
  • explain — Print the metadata and prose explanation for one check (built-in or plugin). Use this when a finding's check ID isn't self-explanatory and you want the rationale, default severity, configurable options, and any relevant flags without leaving the terminal. Add --full to also render the companion markdown body (motivation, examples, config snippets) sourced from the check catalog
  • init — Scaffold cofferdam.toml + .cofferdam/baseline.json + .gitignore entries so a new project has a working cofferdam check after one command. Refuses to overwrite an existing cofferdam.toml without --force
  • doctor — Diagnose install and configuration issues. Reports each check as ✓ / ⚠ / ✗ with a one-line remediation hint on failure. Exit 0 on all-pass, 1 if any check fails. Diagnostic only — never modifies files
  • watch — Re-analyze on file change (cd-9hp.4 cp1b). Discovers files once, registers a recursive filesystem watcher, and re-runs the engine on each detected change. A shared in-memory parse cache survives across iterations, so unchanged files skip parse on every subsequent pass. Text output only — for scripted use cases keep cofferdam check
  • fix — Apply mechanical autofixes for supported checks. Runs the engine against the given paths, groups fixable findings by file, applies edits in reverse byte-offset order, and writes each modified file atomically (write to a temp path then rename). Unsupported checks are silently skipped. Prints a summary to stderr
  • agents — Print the agent-onboarding prompt — a ready-to-paste markdown block that tells an AI coding agent how to use cofferdam in this repository. Covers advise, advise --diff, check --robot, and the cofferdam.invariants.toml contract. Output is version-pinned so AGENTS.md / CLAUDE.md generators can detect staleness. Pipe into a file to create or refresh an agent context fragment:
  • advise — JIT architectural advisory for agents — emit the rules that apply to a given file or directory, INDEPENDENT of whether any current code violates them. Designed for agentic edit loops: an LLM agent shells out before editing a file, gets back layer membership and per-rule constraints, and adjusts its plan before writing code. Static projection — does not parse, does not run checks, does not build the project graph. With no arguments, walks the current directory
  • gen-docs — Regenerate the docs catalog from CheckMeta. Writes per-check markdown files, a schema-stable JSON index, an llms.txt root index, and the CLI reference page (from clap-markdown). Use --check to fail when the committed files are out of date — same shape as cargo fmt --check
  • lsp — Run the Language Server Protocol server over stdio (cd-9hp.4 cp5). Editors that speak LSP — VS Code (via the bundled extension stub at editors/vscode), Helix, neovim — connect and receive workspace diagnostics on save. The server hydrates the cp4 disk cache at startup and persists it on shutdown. Run with no arguments; the LSP transport handles its own configuration via the standard initialize request
  • typst — Lint a Typst package directory for Typst Universe submission hygiene (manifest fields, license, naming, README, bundle hygiene). Standalone from the AST engine — the unit of analysis is the package directory (typst.toml + LICENSE + README.md + bundle), not individual .typ files

cofferdam hello ​

Print the project banner

Usage: cofferdam hello

cofferdam check ​

Run all checks against files or directories. With no arguments, walks the current directory

Usage: cofferdam check [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​

  • --hidden — Walk hidden files/directories (default: skip)

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by category (default)
    • json: Machine-readable JSON. Stable schema, no ANSI, no decorative output
    • compact: Pipe-delimited line-per-finding format. One header line followed by one record per finding. Most token-economical — use when shovelling findings into an AI prompt
    • sarif: SARIF 2.1.0 — OASIS-standard JSON for static-analysis tools. Upload directly to GitHub Code Scanning via github/codeql-action/upload-sarif, or feed Azure DevOps, GitLab, SonarQube, the VS Code Sarif Viewer, etc

  • --robot — Default to a machine-readable format when --format is not set. Token-economical output for AI agents — pairs with --format=compact for the smallest output by far

  • --pretty — Pretty-print JSON output (only with --format=json / --robot)

  • --baseline <PATH> — Path to a baseline file. Defaults to .cofferdam/baseline.json when that file exists. Conflicts with --no-baseline

  • --no-baseline — Disable baseline detection entirely. Equivalent to running without a baseline file present

  • --fail-on-new — Only fail (exit 1) on findings absent from the baseline. Implicit when a baseline is active; pass explicitly to document intent in CI scripts. Has no effect without a baseline

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config

  • --no-config — Disable config-file discovery entirely. Equivalent to running without a cofferdam.toml present

  • --since <GIT-REF> — PR mode — report only findings on files changed in <git-ref>...HEAD. The full project tree is still analysed for cross-file soundness (OrphanExport, DeadExport, import cycles); only the reported findings are filtered to the diff

  • --fail-on <LEVEL> — Severity threshold for the exit-1 gate. Findings below this level still print; the process only exits 1 if at least one finding is at this level or above. Baselined findings never trigger the gate

    Default value: medium

    Possible values: info, low, medium, high, critical

  • --max-issues <N> — Cap rendered findings at the top N by sort priority. The CI gate (--fail-on) still considers the full unbounded set, so truncating output never hides a failure. Pairs with --quiet for compact CI output. 0 disables the cap (default)

    Default value: 0

  • --quiet — Suppress informational output: the trailing N finding(s) summary line, "no TypeScript files found" hints, and the "(showing N of M)" truncation note. Findings, warnings, and errors still print. Has no effect on JSON output (which is already terse)

  • --hide-baselined — Hide baselined findings from text output. The summary line still reports (N new, M baselined) counts so the CI gate remains visible. Has no effect on --format=json (which always includes the per-finding baselined flag) or on the --fail-on gate (which already ignores baselined findings). Useful for routine local runs against repos with substantial baselines (cd-k23 / gh #11)

  • --cache-dir <PATH> — Directory for the disk-backed findings/run cache (cd-9hp.4 cp4). Defaults to .cofferdam/cache/ under CWD. Each cofferdam build writes to a version-scoped subdir so an upgrade invalidates prior caches automatically. Add the directory to .gitignore

  • --no-cache — Disable disk caching entirely. Equivalent to deleting the cache directory before each run. Cold cost only; no correctness difference

  • --fail-on-type-unavailable — Exit with code 2 when a type-aware check is registered but the type oracle could not be started (Node unavailable, ts-morph not installed, or no tsconfig.json found). Default off: oracle failures print a warning and type-aware checks are silently skipped. Use in CI jobs that explicitly rely on type-aware coverage to catch silent regressions

  • --time-checks — Print a per-check + per-phase timing breakdown to stderr (discovery, run loop, pass 2, graph build, finalize A/B, and each check's accumulated time, sorted descending). Findings output (JSON/robot/text) is byte-identical with and without this flag (CD-34)

  • --trend — Append one {date, category, count} JSON row per category to .cofferdam/trend.jsonl (creating it if needed). Counts include baselined findings, same as [budgets] enforcement. Purely additive — no rendering or dashboard; pair with an external tool if you want a chart. (CD-64 D3)

  • --only <CHECK_ID> — Restrict output to findings from one check (dotted id, e.g. Warning.IslandApiConvention). Applied after plugin merge, so it covers both built-in and plugin-emitted findings; budgets, baseline, and the exit-code gate all see only this check's findings. Useful for a CI hook that gates on a single project-specific plugin check without turning on the full suite (CD-74). An id that matches no built-in check (and no plugins are configured) exits 2 rather than silently returning zero findings — a typo here must not make a CI gate pass

cofferdam verify ​

Opt-in check mode for built HTML output (CD-85). Discovers only the given output directory (e.g. dist/, .next/, build/) and runs ONLY checks explicitly tagged as output-mode-eligible (Check::output_mode() == true) against it — plain cofferdam check runs never see this tree and are completely unaffected.

Limitations (v1): CSR/SPA apps with no static HTML output are not supported (would need a headless-render step); findings are NOT mapped back to source locations (build-tool-specific, not attempted) — the reported location is always in the built HTML.

Usage: cofferdam verify [OPTIONS] --dist <DIR>

Options: ​

  • --dist <DIR> — Directory containing built HTML output to check

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by category (default)
    • json: Machine-readable JSON. Stable schema, no ANSI, no decorative output
    • compact: Pipe-delimited line-per-finding format. One header line followed by one record per finding. Most token-economical — use when shovelling findings into an AI prompt
    • sarif: SARIF 2.1.0 — OASIS-standard JSON for static-analysis tools. Upload directly to GitHub Code Scanning via github/codeql-action/upload-sarif, or feed Azure DevOps, GitLab, SonarQube, the VS Code Sarif Viewer, etc

  • --robot — Default to a machine-readable format when --format is not set

  • --pretty — Pretty-print JSON output (only with --format=json / --robot)

  • --fail-on <LEVEL> — Severity threshold for the exit-1 gate

    Default value: medium

    Possible values: info, low, medium, high, critical

  • --quiet — Suppress informational output

  • --config <PATH> — Path to a cofferdam.toml config file. Used for [plugins] discovery only. Defaults to walking up from the current directory. Conflicts with --no-config

  • --no-config — Disable config-file discovery entirely

cofferdam baseline ​

Manage the baseline of accepted findings. The baseline lets you drop cofferdam into an existing project without immediately failing CI on every pre-existing finding

Usage: cofferdam baseline <COMMAND>

Subcommands: ​
  • write — Run the analyzer and write the current set of findings to the baseline file. Subsequent cofferdam check runs ignore these findings for CI-gating purposes; they still print as [baselined] so the team can chip away at them
  • lint — Report baseline entries that are also suppressed inline
  • diff — Compute delta between two baselines
  • prune — Remove baseline entries whose signature matches no current finding (a fixed finding, a deleted file, or a renamed check)
  • ratchet — Lower [budgets] entries in cofferdam.toml to match the current finding count — never raises a budget. Run after fixing findings to lock in the improvement so a regression fails CI even if it's below the old, looser budget

cofferdam baseline write ​

Run the analyzer and write the current set of findings to the baseline file. Subsequent cofferdam check runs ignore these findings for CI-gating purposes; they still print as [baselined] so the team can chip away at them

Usage: cofferdam baseline write [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --output <PATH> — Where to write the baseline. Defaults to .cofferdam/baseline.json in the current directory
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely
  • --robot — Machine-readable JSON output. Emits a delta block when a prior baseline existed; omitted on first run
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline lint ​

Report baseline entries that are also suppressed inline.

A "dual-state" entry is silenced twice — once by the baseline and once by an inline directive — which wastes signal and obscures the true technical-debt posture. Exit 0 if none found, 1 if any (so it is wireable into CI for teams that want to enforce hygiene).

Usage: cofferdam baseline lint [OPTIONS]

Options: ​
  • --robot — Machine-readable JSON. Schema: { dual_state: [...], summary: { count } }
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline diff ​

Compute delta between two baselines.

With two explicit paths: compares them directly. Useful for triage and PR review outside the baseline write path.

Usage: cofferdam baseline diff [OPTIONS] [BASELINE_A] [BASELINE_B]

Arguments: ​
  • <BASELINE_A> — First baseline path
  • <BASELINE_B> — Second baseline path
Options: ​
  • --robot — Machine-readable JSON
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline prune ​

Remove baseline entries whose signature matches no current finding (a fixed finding, a deleted file, or a renamed check).

Keeps the baseline from accumulating dead weight that never gets re-examined once fixed. Default: rewrites the baseline in place. --dry-run lists candidates without writing. --check reports the same list but exits 1 if any exist and never writes — wire into CI to keep baseline hygiene from silently drifting.

Usage: cofferdam baseline prune [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --baseline <PATH> — Path to the baseline file. Defaults to auto-detected .cofferdam/baseline.json
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely
  • --dry-run — List stale entries without writing. Always exits 0
  • --check — List stale entries without writing; exit 1 if any exist. For CI gating on baseline hygiene
  • --robot — Machine-readable JSON output
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam baseline ratchet ​

Lower [budgets] entries in cofferdam.toml to match the current finding count — never raises a budget. Run after fixing findings to lock in the improvement so a regression fails CI even if it's below the old, looser budget

Usage: cofferdam baseline ratchet [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to analyze. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely
  • --dry-run — Compute and print the new budgets without writing them
  • --robot — Machine-readable JSON output
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam explain ​

Print the metadata and prose explanation for one check (built-in or plugin). Use this when a finding's check ID isn't self-explanatory and you want the rationale, default severity, configurable options, and any relevant flags without leaving the terminal. Add --full to also render the companion markdown body (motivation, examples, config snippets) sourced from the check catalog.

Plugin checks: explain discovers plugin-declared checks from cofferdam.toml's plugins = [...] and renders their explanation (and body for --full) the same way as built-ins. Plugins must be loadable from the current working directory; otherwise the unknown-check fallback prints suggestions only from built-ins.

Usage: cofferdam explain [OPTIONS] <CHECK_ID>

Arguments: ​
  • <CHECK_ID> — Dotted check ID, e.g. Warning.TripleEquals. If unknown, the CLI prints the closest matches (substring on the ID) or the full list when nothing matches
Options: ​
  • --robot — Machine-readable JSON. Schema mirrors CheckMeta fields
  • --pretty — Pretty-print JSON output. No effect without --robot
  • --full — Print the full companion markdown body after the metadata summary. In --robot mode, includes a body field in the JSON output. Frontmatter is stripped before display
  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config
  • --no-config — Disable config-file discovery entirely. Plugin checks won't be resolved

cofferdam init ​

Scaffold cofferdam.toml + .cofferdam/baseline.json + .gitignore entries so a new project has a working cofferdam check after one command. Refuses to overwrite an existing cofferdam.toml without --force

Usage: cofferdam init [OPTIONS] [PATH]

Arguments: ​

  • <PATH> — Project root to initialise. Defaults to the current directory

    Default value: .

Options: ​
  • --force — Overwrite an existing cofferdam.toml
  • --baseline — Capture the current set of findings as the baseline. Skip the interactive prompt
  • --no-baseline — Do not capture a baseline. Skip the interactive prompt
  • --robot — Machine-readable JSON summary instead of human output. No prompts; defaults to capturing a baseline

cofferdam doctor ​

Diagnose install and configuration issues. Reports each check as ✓ / ⚠ / ✗ with a one-line remediation hint on failure. Exit 0 on all-pass, 1 if any check fails. Diagnostic only — never modifies files

Usage: cofferdam doctor [OPTIONS]

Options: ​
  • --robot — Machine-readable JSON output. Schema mirrors the per-check CheckResult and a top-level summary tally
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam watch ​

Re-analyze on file change (cd-9hp.4 cp1b). Discovers files once, registers a recursive filesystem watcher, and re-runs the engine on each detected change. A shared in-memory parse cache survives across iterations, so unchanged files skip parse on every subsequent pass. Text output only — for scripted use cases keep cofferdam check

Usage: cofferdam watch [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to watch. Defaults to .
Options: ​

  • --hidden — Walk hidden files/directories

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory

  • --no-config — Disable config-file discovery entirely

  • --debounce <MS> — Debounce filesystem events by this many milliseconds. Lower = faster reaction to a save; higher = fewer duplicate runs when an editor emits multiple events per save. 100 ms is the typical sweet spot

    Default value: 100

cofferdam fix ​

Apply mechanical autofixes for supported checks. Runs the engine against the given paths, groups fixable findings by file, applies edits in reverse byte-offset order, and writes each modified file atomically (write to a temp path then rename). Unsupported checks are silently skipped. Prints a summary to stderr

Usage: cofferdam fix [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files or directories to fix. Defaults to .
Options: ​
  • --hidden — Walk hidden files/directories (default: skip)
  • --no-ignore — Disable .gitignore / .cofferdamignore filtering
  • --dry-run — Preview mode — discover all fixable findings and print what WOULD be changed, but do not modify any file. Exits 0. Use this to audit autofix coverage before committing to a write
  • --robot — Machine-readable JSON output. Emits a structured report instead of human-readable lines. With --dry-run, no files are written; the JSON describes what would change
  • --pretty — Pretty-print JSON output. No effect without --robot

cofferdam agents ​

Print the agent-onboarding prompt — a ready-to-paste markdown block that tells an AI coding agent how to use cofferdam in this repository. Covers advise, advise --diff, check --robot, and the cofferdam.invariants.toml contract. Output is version-pinned so AGENTS.md / CLAUDE.md generators can detect staleness. Pipe into a file to create or refresh an agent context fragment:

cofferdam agents >> AGENTS.md

Usage: cofferdam agents [OPTIONS]

Options: ​
  • --hooks — Emit a paste-ready Claude Code settings.json hooks fragment (plus Cursor/pre-commit equivalents as comments) instead of the onboarding prompt

cofferdam advise ​

JIT architectural advisory for agents — emit the rules that apply to a given file or directory, INDEPENDENT of whether any current code violates them. Designed for agentic edit loops: an LLM agent shells out before editing a file, gets back layer membership and per-rule constraints, and adjusts its plan before writing code. Static projection — does not parse, does not run checks, does not build the project graph. With no arguments, walks the current directory

Usage: cofferdam advise [OPTIONS] [PATHS]...

Arguments: ​
  • <PATHS> — Files, directories, or globs to advise on. Defaults to .. Glob patterns (src/**/*.ts) work; shell expansion is honoured first, then the CLI's own globset matcher
Options: ​

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by file (default)
    • json: Machine-readable JSON array. One object per file

  • --robot — Default to a machine-readable JSON array when --format is not set. Token-economical output for AI agents

  • --pretty — Pretty-print JSON output

  • --config <PATH> — Path to a cofferdam.toml config file. Defaults to walking up from the current directory until one is found or a .git directory is reached. Conflicts with --no-config

  • --no-config — Disable config-file discovery entirely

  • --hidden — Walk hidden files/directories (default: skip)

  • --no-ignore — Disable .gitignore / .cofferdamignore filtering

  • --diff <GIT-REF> — Diff mode — run the engine and any configured plugins against the working tree AND the state at <git-ref>, then report rules that WOULD fire if the change were committed (would_fire) plus rules that currently fire on <git-ref> but are cleared by the change (would_clear). Output is always JSON when this flag is set; --format is ignored

  • --fail-on <LEVEL> — Severity gate for --diff mode. When set, the process exits 1 if any would_fire entry is at or above this level. would_clear never gates. No effect without --diff

    Possible values: info, low, medium, high, critical

  • --analyze — State-of-play mode (CD-65 A4): parse exactly one file (no project graph) and report current/remaining budget for the complexity/length checks (Refactor.CyclomaticComplexity, Refactor.CognitiveComplexity, Readability.MaxFunctionLength, Readability.MaxLineLength, Design.MaxParameters) alongside their configured limit. Requires exactly one path in paths. Always JSON; --format/--diff are ignored

cofferdam gen-docs ​

Regenerate the docs catalog from CheckMeta. Writes per-check markdown files, a schema-stable JSON index, an llms.txt root index, and the CLI reference page (from clap-markdown). Use --check to fail when the committed files are out of date — same shape as cargo fmt --check

Usage: cofferdam gen-docs [OPTIONS]

Options: ​

  • --out <DIR> — Output directory. The catalog lands at <out>/checks.json, <out>/checks/<id>.md, <out>/checks/index.md, <out>/llms.txt, <out>/reference/cli.md

    Default value: docs

  • --check — Don't write — only fail (exit 1) if the existing files would change. The CI gate uses this

cofferdam lsp ​

Run the Language Server Protocol server over stdio (cd-9hp.4 cp5). Editors that speak LSP — VS Code (via the bundled extension stub at editors/vscode), Helix, neovim — connect and receive workspace diagnostics on save. The server hydrates the cp4 disk cache at startup and persists it on shutdown. Run with no arguments; the LSP transport handles its own configuration via the standard initialize request

Usage: cofferdam lsp

cofferdam typst ​

Lint a Typst package directory for Typst Universe submission hygiene (manifest fields, license, naming, README, bundle hygiene). Standalone from the AST engine — the unit of analysis is the package directory (typst.toml + LICENSE + README.md + bundle), not individual .typ files

Usage: cofferdam typst [OPTIONS] [PATH]

Arguments: ​

  • <PATH> — Package directory to lint. Defaults to .

    Default value: .

Options: ​

  • --format <FORMAT> — Output format. Default: text. With --robot and no explicit --format, defaults to json

    Possible values:

    • text: Human-readable text grouped by category (default)
    • json: Machine-readable JSON. Stable schema, no ANSI, no decorative output
    • compact: Pipe-delimited line-per-finding format. One header line followed by one record per finding. Most token-economical — use when shovelling findings into an AI prompt
    • sarif: SARIF 2.1.0 — OASIS-standard JSON for static-analysis tools. Upload directly to GitHub Code Scanning via github/codeql-action/upload-sarif, or feed Azure DevOps, GitLab, SonarQube, the VS Code Sarif Viewer, etc

  • --robot — Default to a machine-readable format when --format is not set

  • --pretty — Pretty-print JSON output (only with --format=json / --robot)

  • --fail-on <LEVEL> — Severity threshold for the exit-1 gate. Findings below this level still print; the process only exits 1 if at least one finding is at this level or above

    Default value: medium

    Possible values: info, low, medium, high, critical

  • --quiet — Suppress the trailing N finding(s) summary line. Findings themselves still print. Has no effect on JSON output

This document was generated automatically by clap-markdown.

MIT License

Copyright © 2026 Thomas Dickson