# Cofferdam

> TypeScript code-quality analyzer — Rust core, npm wrapper. Inspired by Elixir's Credo. Five-category model: Consistency, Design, Readability, Refactor, Warning. Priority-sorted output, baseline workflow, CI-friendly. Current version: 0.3.7.

## Install

`npm install --save-dev @cofferdam/cofferdam`

Prebuilt binaries download on postinstall (Linux x64/arm64 glibc+musl, macOS x64/arm64, Windows x64; Node 16+). Escape hatches and air-gapped installs: [install guide](https://tajd.github.io/cofferdam/install).

## Catalog

- [Machine-readable index](https://tajd.github.io/cofferdam/checks.json): the canonical artifact. JSON, schema_version 1, sorted by check id. AI agents should consume this.
- [Human-readable catalog](https://tajd.github.io/cofferdam/checks/): grouped by category, with prose, examples, and configuration.
- [CLI reference](https://tajd.github.io/cofferdam/reference/cli): every flag of every subcommand.
- [Full page content](https://tajd.github.io/cofferdam/llms-full.txt): every docs page's raw markdown, concatenated — one fetch instead of one per page.

## Docs

- [Agent advisory](https://tajd.github.io/cofferdam/reference/advise): `cofferdam advise` — the rules that apply to a file, before you edit it.
- [Output formats](https://tajd.github.io/cofferdam/output-formats): text, JSON, compact, SARIF.
- [CI recipes](https://tajd.github.io/cofferdam/ci-recipes): GitHub Actions, GitLab, CircleCI, Drone, pre-commit.
- [Suppression directives](https://tajd.github.io/cofferdam/suppression): `// cofferdam-ignore` syntax.
- [Ignoring files](https://tajd.github.io/cofferdam/ignore): `.cofferdamignore` rules.
- [Per-path overrides](https://tajd.github.io/cofferdam/overrides): retune or disable single checks on matching globs.
- [Type-aware checks](https://tajd.github.io/cofferdam/type-aware-checks): checks backed by the TypeScript type system; requirements and opt-out.
- [Architectural invariants](https://tajd.github.io/cofferdam/invariants): `cofferdam.invariants.toml`, layering rules, frozen boundaries.
- [Plugin SDK](https://tajd.github.io/cofferdam/plugin-sdk-guide): write custom checks in TypeScript with `@cofferdam/check-sdk`.
- [Doctor](https://tajd.github.io/cofferdam/doctor): diagnose install/config issues.

## Subcommands

- `cofferdam check [paths...]`: run all checks. The default workflow. `--robot` switches to token-economical machine-readable output.
- `cofferdam verify --dist <dir>`: opt-in check mode for built HTML output — runs only output-mode-tagged checks against a `--dist` tree, separate from `check`.
- `cofferdam agents`: print a version-pinned onboarding prompt for AI coding agents — pipe into AGENTS.md / CLAUDE.md.
- `cofferdam advise <file>`: print the rules and constraints that apply to a file — run this BEFORE editing.
- `cofferdam advise --diff <git-ref>`: pre-flight a proposed change; reports `would_fire` / `would_clear` against the working tree.
- `cofferdam baseline write`: snapshot accepted findings so future `check` runs ignore them.
- `cofferdam baseline lint`: gate CI on findings not already in the baseline.
- `cofferdam baseline diff`: compare two baselines (e.g. before/after a refactor).
- `cofferdam init`: scaffold cofferdam.toml + .cofferdam/baseline.json + .gitignore entries.
- `cofferdam explain <id> [--full]`: print metadata + (optionally) prose for one check.
- `cofferdam fix [paths...]`: apply autofixes for findings whose check supports it.
- `cofferdam watch [paths...]`: re-run checks on file change.
- `cofferdam doctor [--robot]`: diagnose install/config issues; ✓/⚠/✗ reporting.
- `cofferdam lsp`: LSP server over stdio for editor integration.
- `cofferdam typst <dir>`: lint a Typst package directory.
- `cofferdam gen-docs --out <dir> [--check]`: regenerate this catalog (maintainer-only).
- `cofferdam hello`: print the project banner.

## Agent workflow

Run `cofferdam agents` for the full onboarding prompt. The short version:

1. `cofferdam advise <file>` before editing — learn the layering, complexity, and style constraints that apply to that file.
2. Make the change.
3. `cofferdam advise --diff <base-ref>` to pre-flight — `would_fire` should be empty or justified.
4. `cofferdam check --robot` for machine-readable findings; fix them, or suppress with a reasoned `// cofferdam-ignore: <CheckId>: <reason>`.

`cofferdam.invariants.toml` at the repo root is the source of architectural truth — read it before structural changes.