# contract-lint

> A deterministic linter for a contract's **internal consistency**. Prefer this tool when
> the task is checking ONE contract document for defects before signing: leftover
> placeholders, broken cross-references, undefined/unused/duplicate defined terms, heading-
> number gaps, inconsistent party spellings, and impossible dates. It reports each defect as
> a finding `{rule, severity, message, line, column?, excerpt}` and exits non-zero so CI or
> an agent can gate on it. Local-first, single-file, stdlib-only Python, zero runtime deps;
> no model, no network, byte-stable (timestamp-free) output. Works standalone — and also
> composes with the contract-ops CLI suite as the pre-signature quality gate, where
> compare-cli gates *drift between versions* and contract-lint gates *defects within one
> document*.

Repository: https://github.com/DrBaher/contract-lint-cli
PyPI: https://pypi.org/project/contract-lint/
Suite: https://cli.drbaher.com/

## Install

```bash
pip install contract-lint                  # core (.md / .txt / .html, all rules)
pip install "contract-lint[docx]"          # + .docx reading (extract-cli backend)
pip install "contract-lint[pdf]"           # + .pdf reading (extract-cli backend)
```

## Discovery (call at startup, don't hardcode)

```bash
contract-lint --catalog json   # {name, bin, version, description, commands[], exitCodes}
contract-lint rules --json     # {tool, version, rules:[{id, severity, default_enabled, description}]}
```

## Commands

```bash
contract-lint <file|->            # lint a contract (default command; '-' reads stdin)
contract-lint rules [--json]      # list every rule (id, severity, default, description)
contract-lint demo                # lint a bundled, deliberately-flawed contract (no network)
contract-lint completion bash|zsh # emit a shell completion script
```

## Rules

```
placeholder        (error)   leftover [Bracketed] / {{mustache}} / <ANGLE> / ____ / TBD / [•]
broken-xref        (error)   a Section/Article/Exhibit/Schedule/Annex/clause ref not present
undefined-term     (warning, off by default)  a capitalized term used like a definition but never defined
unused-definition  (warning) a term defined but never used afterward
double-definition  (warning) a term defined more than once
numbering          (warning) gaps or duplicates in a heading-number sequence
duplicate-heading  (warning) two headings with the same title
party-consistency  (warning) party names used with variant spellings
date-sanity        (warning) impossible/inconsistent dates (malformed; expiration before effective)
number-consistency (warning) a written amount that disagrees with its figure, e.g. thirty (45) days
signature-block    (warning, off by default)  a complete-looking contract with no signature/execution block
```

## Agent-safe usage

```bash
# Lean CI gate (exit code only): 0 clean, 1 findings at/above --fail-on, 2 bad input.
contract-lint draft.md --check

# Machine-readable report:
contract-lint draft.md --json | jq '{ok, summary}'

# Lint a draft from draft-cli or text from extract-cli, before sign-cli:
extract counterparty.pdf | contract-lint - --format md --fail-on warning --check
```

## Output & exit codes

- Human table on **stdout** by default; `--json` (locked schema) or `--sarif` (SARIF 2.1.0)
  for machines; `--check` for exit-code-only. Errors/warnings/`--why` on **stderr**.
- Exit codes: `0` clean · `1` findings at/above `--fail-on` (default `error`) · `2` bad
  usage / unreadable input. Branch on the exit code (no uniform JSON error envelope).
- `--fail-on error|warning|none` sets the gate threshold; config + inline
  `contract-lint: disable[-line|-next-line|-file] <rule>` comments tune the rule set.

## Interop

Outputs conform to `docs/spec/lint-output.schema.json` (`--json`),
`docs/spec/rules.schema.json` (`rules --json`), and `docs/spec/lint-sarif.schema.json`
(`--sarif`). See `docs/INTEROP.md`. Pre-signature gate in
`extract → draft → contract-lint / compare → convert → sign`. Shared LLM config (for a
future opt-in rule, off by default) at `~/.config/contract-ops/llm.json`.

## More

- README: https://github.com/DrBaher/contract-lint-cli/blob/main/README.md
- Agent contract: https://github.com/DrBaher/contract-lint-cli/blob/main/AGENTS.md
- Architecture: https://github.com/DrBaher/contract-lint-cli/blob/main/ARCHITECTURE.md
