madr-lint

madr-lint checks that your MADR files follow the conventions your team relies on — required sections, a valid status, ISO‑8601 dates, filename format, and cross‑file integrity like unique numbering and non‑broken links.

MADR v2 / v3 / v4 aware

Reads YAML frontmatter (v3/v4) and v2 body-list metadata — both bold (- **Status**:) and the canonical plain (* Status:) shapes. Target a version explicitly or let it auto-detect.

ESLint-style rules

Named rules (madr/required-sections, …) with error / warn / off severities and per-rule options validated by a JSON Schema.

Per-file & cross-file

Fast per-file checks (sections, status, dates, filename) plus project rules for unique numbering, the supersedes graph, and link rot.

CLI, library & Action

Run it from the command line, call it programmatically, or drop it into CI as a GitHub Action. Text, JSON, SARIF, and GitHub annotation reporters.

Autofix

--fix / --fix-dry-run mechanically repair the violations that have a safe, unambiguous correction — a misspelled status, a malformed date, a one-sided supersedes link.

Gradual adoption

Inline madr-lint-disable suppression comments for one-off exceptions, and a baseline file to snapshot legacy violations so only new ones fail CI.

Quick look

# scaffold a config — detects your ADR directory and MADR version
npx madr-lint init

# lint the ADRs in your configured adrDir (default: docs/adr)
npx madr-lint

# or point it at explicit paths
npx madr-lint docs/adr

# auto-repair what's mechanically fixable
npx madr-lint --fix

# machine-readable output for CI
npx madr-lint --format sarif

madr-lint.config.ts

import { defineConfig } from 'madr-lint';

export default defineConfig({
  extends: ['madr-lint:recommended'],
  madrVersion: 'auto',
  adrDir: 'docs/adr',
  rules: {
    'madr/filename-format': ['error', { pattern: '^[0-9]{4}-.+\\.md$' }],
    'madr/no-numbering-gap': 'off',
  },
});

Head to Getting started to install and run your first lint, or jump to Configuration for the full set of options.

Building an AI agent or coding assistant integration? See llms.txt for a machine-readable index of these docs, or llms-full.txt for the full text in one fetch.