madr-lint 0.3.0 → 0.4.0

package/dist/cli.js

@@ -6,198 +6,17 @@ var __export = (target, all) => {
 };
 
 // src/cli.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { relative as relative2, resolve as resolve3, sep as sep2 } from "path";
-import { defineCommand, runMain } from "citty";
+import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { relative as relative2, resolve as resolve5, sep as sep2 } from "path";
+import { defineCommand as defineCommand2, runMain } from "citty";
 
-// src/core/baseline.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
-
-// src/core/types.ts
-var INTERNAL_ERROR_RULE_NAME = "core/internal-error";
-function isProjectRule(rule9) {
-  return "check" in rule9;
-}
-
-// src/core/baseline.ts
-var BASELINE_VERSION = 1;
-var BASELINE_DISPLAY_PATH = ".madr-lint/baseline.json";
-function baselinePath(cwd) {
-  return join(cwd, ".madr-lint", "baseline.json");
-}
-function nullProtoMap() {
-  return /* @__PURE__ */ Object.create(null);
-}
-function buildBaseline(diagnostics) {
-  const entries = nullProtoMap();
-  for (const d of diagnostics) {
-    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) continue;
-    const byRule = entries[d.path] ??= nullProtoMap();
-    const byMessage = byRule[d.ruleName] ??= nullProtoMap();
-    byMessage[d.messageId] = (byMessage[d.messageId] ?? 0) + 1;
-  }
-  return { version: BASELINE_VERSION, entries };
-}
-function serializeBaseline(baseline) {
-  const sortedEntries = nullProtoMap();
-  for (const path of Object.keys(baseline.entries).toSorted()) {
-    const byRule = baseline.entries[path] ?? {};
-    const sortedByRule = nullProtoMap();
-    for (const rule9 of Object.keys(byRule).toSorted()) {
-      const byMessage = byRule[rule9] ?? {};
-      const sortedByMessage = nullProtoMap();
-      for (const messageId of Object.keys(byMessage).toSorted()) {
-        sortedByMessage[messageId] = byMessage[messageId] ?? 0;
-      }
-      sortedByRule[rule9] = sortedByMessage;
-    }
-    sortedEntries[path] = sortedByRule;
-  }
-  const ordered = { version: baseline.version, entries: sortedEntries };
-  return JSON.stringify(ordered, null, 2) + "\n";
-}
-function loadBaseline(path) {
-  if (!existsSync(path)) return null;
-  try {
-    const data = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof data.entries !== "object" || data.entries === null) return null;
-    return {
-      version: typeof data.version === "number" ? data.version : BASELINE_VERSION,
-      entries: rebuildEntries(data.entries)
-    };
-  } catch {
-    return null;
-  }
-}
-function rebuildEntries(raw) {
-  const entries = nullProtoMap();
-  for (const [path, rawByRule] of Object.entries(raw)) {
-    if (typeof rawByRule !== "object" || rawByRule === null) continue;
-    const byRule = nullProtoMap();
-    for (const [rule9, rawByMessage] of Object.entries(rawByRule)) {
-      if (typeof rawByMessage !== "object" || rawByMessage === null) continue;
-      const byMessage = nullProtoMap();
-      for (const [messageId, count] of Object.entries(
-        rawByMessage
-      )) {
-        if (typeof count === "number") byMessage[messageId] = count;
-      }
-      byRule[rule9] = byMessage;
-    }
-    entries[path] = byRule;
-  }
-  return entries;
-}
-function writeBaseline(path, baseline) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, serializeBaseline(baseline), "utf8");
-}
-var KEY_SEP = "\0";
-function fingerprint(d) {
-  return d.path + KEY_SEP + d.ruleName + KEY_SEP + d.messageId;
-}
-function applyBaseline(diagnostics, baseline) {
-  const remaining = /* @__PURE__ */ new Map();
-  for (const [path, byRule] of Object.entries(baseline.entries)) {
-    for (const [rule9, byMessage] of Object.entries(byRule)) {
-      if (rule9 === INTERNAL_ERROR_RULE_NAME) continue;
-      for (const [messageId, count] of Object.entries(byMessage)) {
-        remaining.set(path + KEY_SEP + rule9 + KEY_SEP + messageId, count);
-      }
-    }
-  }
-  const kept = [];
-  let hidden = 0;
-  for (const d of diagnostics) {
-    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) {
-      kept.push(d);
-      continue;
-    }
-    const key = fingerprint(d);
-    const left = remaining.get(key);
-    if (left !== void 0 && left > 0) {
-      remaining.set(key, left - 1);
-      hidden++;
-    } else {
-      kept.push(d);
-    }
-  }
-  return { kept, hidden };
-}
-function totalCount(baseline) {
-  let total = 0;
-  for (const byRule of Object.values(baseline.entries)) {
-    for (const byMessage of Object.values(byRule)) {
-      for (const count of Object.values(byMessage)) total += count;
-    }
-  }
-  return total;
-}
-function baselineWriteSummary(baseline) {
-  const violations = totalCount(baseline);
-  const files = Object.keys(baseline.entries).length;
-  const v = `${violations} ${violations === 1 ? "violation" : "violations"}`;
-  const f = `${files} ${files === 1 ? "file" : "files"}`;
-  return `Wrote ${v} across ${f} to ${BASELINE_DISPLAY_PATH}`;
-}
-function baselineMalformedWarning() {
-  return `madr-lint: warning: ${BASELINE_DISPLAY_PATH} is malformed; ignoring it (run --update-baseline to regenerate)`;
-}
-function baselineHiddenSummary(hidden) {
-  return `${hidden} ${hidden === 1 ? "problem" : "problems"} hidden by baseline (${BASELINE_DISPLAY_PATH})`;
-}
-
-// src/core/cache.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-var CACHE_SCHEMA_VERSION = 2;
-function computeContentHash(content) {
-  return createHash("sha1").update(content, "utf8").digest("hex");
-}
-function computeConfigHash(config) {
-  return createHash("sha1").update(stableStringify(config), "utf8").digest("hex");
-}
-function stableStringify(value) {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return "[" + value.map(stableStringify).join(",") + "]";
-  }
-  const entries = Object.entries(value).toSorted(
-    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
-  );
-  return "{" + entries.map(([k, v]) => JSON.stringify(k) + ":" + stableStringify(v)).join(",") + "}";
-}
-function manifestPath(cacheDir) {
-  return join2(cacheDir, "manifest.json");
-}
-function loadManifest(path) {
-  if (!existsSync2(path)) return null;
-  try {
-    const data = JSON.parse(readFileSync2(path, "utf8"));
-    if (
-      // Single invalidation point for schema drift: an unknown (or absent)
-      // schema version nulls here, so every consumer sees a cold cache — no
-      // scattered re-hydration of stale-shape entries downstream.
-      data.schemaVersion !== CACHE_SCHEMA_VERSION || typeof data.version !== "string" || typeof data.configHash !== "string" || typeof data.files !== "object" || data.files === null
-    ) {
-      return null;
-    }
-    return data;
-  } catch {
-    return null;
-  }
-}
-function saveManifest(path, manifest) {
-  mkdirSync2(dirname2(path), { recursive: true });
-  writeFileSync2(path, JSON.stringify(manifest), "utf8");
-}
+// src/commands/init.ts
+import { writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve4 } from "path";
+import { defineCommand } from "citty";
 
 // src/core/config.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { resolve } from "path";
 import { createJiti } from "jiti";
 
@@ -238,7 +57,7 @@ var ConfigFileNotFoundError = class extends Error {
 function loadConfigFromPath(filePath) {
   let raw;
   try {
-    raw = readFileSync3(filePath, "utf8");
+    raw = readFileSync(filePath, "utf8");
   } catch (err) {
     const code = err.code;
     if (code === "ENOENT") {
@@ -263,9 +82,9 @@ function loadConfigFromPath(filePath) {
 function loadConfig(cwd) {
   for (const name of CONFIG_FILES) {
     const path = resolve(cwd, name);
-    if (!existsSync3(path)) continue;
+    if (!existsSync(path)) continue;
     if (name.endsWith(".json")) {
-      const parsed = JSON.parse(readFileSync3(path, "utf8"));
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
       return resolveExtends(parsed);
     }
     const jiti = createJiti(import.meta.url, { interopDefault: true });
@@ -290,71 +109,40 @@ function resolveExtends(config) {
 }
 
 // src/core/discover.ts
-import { existsSync as existsSync4, readdirSync, statSync } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { join } from "path";
 function findAdrFiles(target) {
-  if (!existsSync4(target)) return [];
+  if (!existsSync2(target)) return [];
   const stat = statSync(target);
   if (stat.isFile()) {
     return target.endsWith(".md") ? [target] : [];
   }
   if (!stat.isDirectory()) return [];
   const entries = readdirSync(target, { recursive: true, withFileTypes: true });
-  return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => join3(e.parentPath, e.name)).toSorted();
-}
-
-// src/core/ignore.ts
-import { basename } from "path";
-import picomatch from "picomatch";
-function shouldIgnore(relativePath, patterns) {
-  if (patterns.length === 0) return false;
-  const base = basename(relativePath);
-  for (const pattern of patterns) {
-    if (matchesPattern(relativePath, base, pattern)) return true;
-  }
-  return false;
-}
-function matchesPattern(relativePath, base, pattern) {
-  if (relativePath === pattern) return true;
-  const matcher = picomatch(pattern, { dot: true });
-  if (matcher(relativePath)) return true;
-  if (matcher(base)) return true;
-  if (pattern.includes("/") && !pattern.startsWith("**/")) {
-    const suffixMatcher = picomatch(`**/${pattern}`, { dot: true });
-    if (suffixMatcher(relativePath)) return true;
-  }
-  return false;
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => join(e.parentPath, e.name)).toSorted();
 }
 
-// src/core/lint.ts
-import { readFileSync as readFileSync4, statSync as statSync2 } from "fs";
-import { isAbsolute, relative, resolve as resolve2, sep } from "path";
-
-// src/core/runner.ts
-import Ajv from "ajv";
-
-// src/core/interpolate.ts
-function interpolate(template, data) {
-  if (!template.includes("{{")) return template;
-  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
-    const v = data[key];
-    return v !== void 0 ? String(v) : `{{${key}}}`;
-  });
-}
+// src/core/init.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join2, resolve as resolve2 } from "path";
 
 // src/core/parser.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString } from "mdast-util-to-string";
 import grayMatter from "gray-matter";
+function frontmatterOffset(content) {
+  return content.length - grayMatter(content).content.length;
+}
 function parseFile(content) {
   const matter = grayMatter(content);
   const data = matter.data;
   const frontmatter = Object.keys(data).length > 0 ? data : null;
   const ast = fromMarkdown(matter.content);
-  const listResult = extractListMetadataWithLoc(ast);
+  const listResult = extractListMetadataWithLoc(ast, matter.content);
   const listMetadata = listResult?.values ?? null;
   let metadata = null;
   let metadataLoc = listResult && Object.keys(listResult.loc).length > 0 ? { ...listResult.loc } : null;
+  let metadataValueLoc = listResult && Object.keys(listResult.valueOffsets).length > 0 ? { ...listResult.valueOffsets } : null;
   if (frontmatter && listMetadata) {
     const frontmatterDefined = {};
     for (const [k, v] of Object.entries(frontmatter)) {
@@ -365,6 +153,10 @@ function parseFile(content) {
       for (const k of Object.keys(frontmatterDefined)) delete metadataLoc[k];
       if (Object.keys(metadataLoc).length === 0) metadataLoc = null;
     }
+    if (metadataValueLoc) {
+      for (const k of Object.keys(frontmatterDefined)) delete metadataValueLoc[k];
+      if (Object.keys(metadataValueLoc).length === 0) metadataValueLoc = null;
+    }
   } else if (frontmatter) {
     metadata = frontmatter;
   } else if (listMetadata) {
@@ -375,6 +167,7 @@ function parseFile(content) {
     listMetadata,
     metadata,
     metadataLoc,
+    metadataValueLoc,
     ast,
     body: matter.content
   };
@@ -387,7 +180,7 @@ var RECOGNIZED_METADATA_KEYS = /* @__PURE__ */ new Set([
   "consulted",
   "informed"
 ]);
-function extractListMetadataWithLoc(ast) {
+function extractListMetadataWithLoc(ast, body) {
   let firstList = null;
   for (const child of ast.children) {
     if (child.type === "heading") {
@@ -404,18 +197,22 @@ function extractListMetadataWithLoc(ast) {
   if (!firstList) return null;
   const values = {};
   const loc = {};
+  const valueOffsets = {};
   for (const item of firstList.children) {
     const pair = extractListItemKV(item);
     if (pair && !(pair.key in values)) {
       values[pair.key] = pair.value;
       const start = item.position?.start;
       if (start) loc[pair.key] = { line: start.line, column: start.column };
+      if (body !== void 0 && pair.valueOffset && body.slice(pair.valueOffset.start, pair.valueOffset.end) === pair.value) {
+        valueOffsets[pair.key] = pair.valueOffset;
+      }
     }
   }
   const hasRecognizedKey = Object.keys(values).some(
     (k) => RECOGNIZED_METADATA_KEYS.has(k)
   );
-  return hasRecognizedKey ? { values, loc } : null;
+  return hasRecognizedKey ? { values, loc, valueOffsets } : null;
 }
 var KEY_PATTERN = /^[A-Za-z][A-Za-z0-9 \-_]*$/;
 var SEPARATOR_PATTERN = /^\s*:\s*/;
@@ -439,63 +236,589 @@ function extractListItemKV(item) {
     const valueTail = paragraph.children.slice(2).map((n) => toString(n)).join("");
     const value = (valueHead + valueTail).trim();
     if (value === "") return null;
-    return { key: normalizeKey(keyNode.value), value };
+    let valueOffset;
+    const sepStart = sep3.position?.start.offset;
+    if (paragraph.children.length === 2 && typeof sepStart === "number" && valueHead !== "") {
+      const sepMatch = SEPARATOR_PATTERN.exec(sep3.value);
+      const vStart = sepStart + (sepMatch ? sepMatch[0].length : 0);
+      valueOffset = { start: vStart, end: vStart + value.length };
+    }
+    return { key: normalizeKey(keyNode.value), value, valueOffset };
   }
   if (first.type === "text") {
     const colonIdx = first.value.indexOf(":");
     if (colonIdx === -1) return null;
     const rawKey = first.value.slice(0, colonIdx);
     if (!KEY_PATTERN.test(rawKey)) return null;
-    const valueHead = first.value.slice(colonIdx + 1).replace(/^\s+/, "");
+    const afterColon = first.value.slice(colonIdx + 1);
+    const valueHead = afterColon.replace(/^\s+/, "");
     const valueTail = paragraph.children.slice(1).map((n) => toString(n)).join("");
     const value = (valueHead + valueTail).trim();
     if (value === "") return null;
-    return { key: normalizeKey(rawKey), value };
+    let valueOffset;
+    const nodeStart = first.position?.start.offset;
+    if (paragraph.children.length === 1 && typeof nodeStart === "number" && valueHead !== "") {
+      const leadingWs = afterColon.length - valueHead.length;
+      const vStart = nodeStart + colonIdx + 1 + leadingWs;
+      valueOffset = { start: vStart, end: vStart + value.length };
+    }
+    return { key: normalizeKey(rawKey), value, valueOffset };
   }
   return null;
 }
 
-// src/core/suppression.ts
-var DIRECTIVE_KINDS = /* @__PURE__ */ new Set([
-  "disable-file",
-  "disable",
-  "enable",
-  "disable-next-line"
-]);
-var DIRECTIVE_PREFIX = "madr-lint-";
-function parseDirective(value, line) {
-  const trimmed = value.trim();
-  if (!trimmed.startsWith("<!--") || !trimmed.endsWith("-->")) return null;
-  const inner = trimmed.slice(4, -3).trim();
-  if (inner.includes("<!--") || inner.includes("-->")) return null;
-  if (!inner.startsWith(DIRECTIVE_PREFIX)) return null;
-  const afterPrefix = inner.slice(DIRECTIVE_PREFIX.length);
-  const wsIndex = afterPrefix.search(/\s/);
-  const keyword = wsIndex === -1 ? afterPrefix : afterPrefix.slice(0, wsIndex);
-  if (!DIRECTIVE_KINDS.has(keyword)) return null;
-  const rest = wsIndex === -1 ? "" : afterPrefix.slice(wsIndex);
-  return { kind: keyword, rules: parseRuleList(rest), line };
-}
-function parseRuleList(rest) {
-  const trimmed = rest.trim();
-  if (trimmed === "") return null;
-  const rules = trimmed.split(",").map((s) => s.trim()).filter((s) => s !== "");
-  return rules.length > 0 ? rules : null;
-}
-function walkHtml(node, out) {
-  if (node.type === "html") {
-    const line = node.position?.start.line;
-    if (typeof line === "number") {
-      const directive = parseDirective(node.value, line);
-      if (directive) out.push(directive);
+// src/core/init.ts
+var GETTING_STARTED_URL = "https://knktkc.github.io/madr-lint/guides/getting-started/";
+var ADR_DIR_CANDIDATES = [
+  "docs/adr",
+  "docs/decisions",
+  "doc/adr",
+  "adr",
+  "docs/architecture/decisions"
+];
+var ADR_FILE_PATTERN = /^\d{4}-.*\.md$/;
+function detectAdrDir(cwd) {
+  for (const candidate of ADR_DIR_CANDIDATES) {
+    let entries;
+    try {
+      entries = readdirSync2(resolve2(cwd, candidate), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    if (entries.some((e) => e.isFile() && ADR_FILE_PATTERN.test(e.name))) {
+      return { adrDir: candidate, source: "detected" };
     }
   }
-  if ("children" in node && Array.isArray(node.children)) {
-    for (const child of node.children) walkHtml(child, out);
-  }
+  return { adrDir: "docs/adr", source: "fallback" };
 }
-function collectDirectives(ast, body) {
-  const all = [];
+function detectFileVersion(content) {
+  let parsed;
+  try {
+    parsed = parseFile(content);
+  } catch {
+    return null;
+  }
+  if (parsed.frontmatter) {
+    return "decision-makers" in parsed.frontmatter ? "v4" : "v3";
+  }
+  if (parsed.listMetadata) return "v2";
+  return null;
+}
+function detectMadrVersion(cwd, adrDir) {
+  const dir = resolve2(cwd, adrDir);
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch {
+    return "auto";
+  }
+  const sample = entries.filter((e) => e.isFile() && ADR_FILE_PATTERN.test(e.name)).map((e) => e.name).toSorted().slice(0, 20);
+  const votes = { v2: 0, v3: 0, v4: 0 };
+  for (const name of sample) {
+    let content;
+    try {
+      content = readFileSync2(join2(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    const version = detectFileVersion(content);
+    if (version) votes[version]++;
+  }
+  const max = Math.max(votes.v2, votes.v3, votes.v4);
+  if (max === 0) return "auto";
+  const winners = ["v2", "v3", "v4"].filter(
+    (v) => votes[v] === max
+  );
+  return winners.length === 1 ? winners[0] : "auto";
+}
+var CONFIG_FILENAME_BY_FORMAT = {
+  ts: "madr-lint.config.ts",
+  json: ".madrlintrc.json"
+};
+function detectConfigFormat(cwd) {
+  if (existsSync3(resolve2(cwd, "tsconfig.json"))) return "ts";
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync2(resolve2(cwd, "package.json"), "utf8")
+    );
+    if (pkg2.dependencies?.["typescript"] !== void 0 || pkg2.devDependencies?.["typescript"] !== void 0) {
+      return "ts";
+    }
+  } catch {
+  }
+  return "json";
+}
+function findExistingConfigFile(cwd) {
+  for (const name of CONFIG_FILES) {
+    if (existsSync3(resolve2(cwd, name))) return name;
+  }
+  return null;
+}
+function tsQuote(value) {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function renderConfig(format, options) {
+  if (format === "json") {
+    const config = {
+      extends: ["madr-lint:recommended"],
+      adrDir: options.adrDir
+    };
+    if (options.madrVersion !== "auto") config.madrVersion = options.madrVersion;
+    return `${JSON.stringify(config, null, 2)}
+`;
+  }
+  const versionLine = options.madrVersion !== "auto" ? `
+  madrVersion: ${tsQuote(options.madrVersion)},` : "";
+  return `import { defineConfig } from 'madr-lint';
+
+export default defineConfig({
+  extends: ['madr-lint:recommended'],
+  adrDir: ${tsQuote(options.adrDir)},${versionLine}
+});
+`;
+}
+function buildEpilogue(input) {
+  const dirNote = input.adrDirSource === "detected" ? "(detected)" : input.adrDirSource === "override" ? "(from --dir)" : input.filesChecked === 0 ? "(default \u2014 no existing ADRs found, so init created nothing yet; add your first ADR here)" : "(default \u2014 no NNNN-*.md at its top level, though the initial lint found Markdown files nested inside)";
+  const lines = [
+    `Wrote ${input.configPath}`,
+    "",
+    `  ADR directory: ${input.adrDir} ${dirNote}`,
+    "",
+    "Next steps:",
+    "  - Lint your ADRs: npx madr-lint"
+  ];
+  const total = input.errors + input.warnings;
+  if (input.filesChecked > 0 && total > 0) {
+    lines.push(
+      `  - The initial lint found ${input.errors} error(s) and ${input.warnings} warning(s) across ${input.filesChecked} file(s).`,
+      "    Adopting on a legacy repo? Snapshot the debt so only new violations fail the build:",
+      "      npx madr-lint --update-baseline"
+    );
+  }
+  lines.push(`  - Docs: ${GETTING_STARTED_URL}`);
+  return lines.join("\n");
+}
+
+// src/core/lint.ts
+import { readFileSync as readFileSync5, statSync as statSync2 } from "fs";
+import { isAbsolute, relative, resolve as resolve3, sep } from "path";
+
+// src/core/baseline.ts
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { dirname, join as join3 } from "path";
+
+// src/core/types.ts
+var INTERNAL_ERROR_RULE_NAME = "core/internal-error";
+function isProjectRule(rule9) {
+  return "check" in rule9;
+}
+
+// src/core/baseline.ts
+var BASELINE_VERSION = 1;
+var BASELINE_DISPLAY_PATH = ".madr-lint/baseline.json";
+function baselinePath(cwd) {
+  return join3(cwd, ".madr-lint", "baseline.json");
+}
+function nullProtoMap() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function buildBaseline(diagnostics) {
+  const entries = nullProtoMap();
+  for (const d of diagnostics) {
+    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) continue;
+    const byRule = entries[d.path] ??= nullProtoMap();
+    const byMessage = byRule[d.ruleName] ??= nullProtoMap();
+    byMessage[d.messageId] = (byMessage[d.messageId] ?? 0) + 1;
+  }
+  return { version: BASELINE_VERSION, entries };
+}
+function serializeBaseline(baseline) {
+  const sortedEntries = nullProtoMap();
+  for (const path of Object.keys(baseline.entries).toSorted()) {
+    const byRule = baseline.entries[path] ?? {};
+    const sortedByRule = nullProtoMap();
+    for (const rule9 of Object.keys(byRule).toSorted()) {
+      const byMessage = byRule[rule9] ?? {};
+      const sortedByMessage = nullProtoMap();
+      for (const messageId of Object.keys(byMessage).toSorted()) {
+        sortedByMessage[messageId] = byMessage[messageId] ?? 0;
+      }
+      sortedByRule[rule9] = sortedByMessage;
+    }
+    sortedEntries[path] = sortedByRule;
+  }
+  const ordered = { version: baseline.version, entries: sortedEntries };
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+function loadBaseline(path) {
+  if (!existsSync4(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync3(path, "utf8"));
+    if (typeof data.entries !== "object" || data.entries === null) return null;
+    return {
+      version: typeof data.version === "number" ? data.version : BASELINE_VERSION,
+      entries: rebuildEntries(data.entries)
+    };
+  } catch {
+    return null;
+  }
+}
+function rebuildEntries(raw) {
+  const entries = nullProtoMap();
+  for (const [path, rawByRule] of Object.entries(raw)) {
+    if (typeof rawByRule !== "object" || rawByRule === null) continue;
+    const byRule = nullProtoMap();
+    for (const [rule9, rawByMessage] of Object.entries(rawByRule)) {
+      if (typeof rawByMessage !== "object" || rawByMessage === null) continue;
+      const byMessage = nullProtoMap();
+      for (const [messageId, count] of Object.entries(
+        rawByMessage
+      )) {
+        if (typeof count === "number") byMessage[messageId] = count;
+      }
+      byRule[rule9] = byMessage;
+    }
+    entries[path] = byRule;
+  }
+  return entries;
+}
+function writeBaseline(path, baseline) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, serializeBaseline(baseline), "utf8");
+}
+var KEY_SEP = "\0";
+function fingerprint(d) {
+  return d.path + KEY_SEP + d.ruleName + KEY_SEP + d.messageId;
+}
+function applyBaseline(diagnostics, baseline) {
+  const remaining = /* @__PURE__ */ new Map();
+  for (const [path, byRule] of Object.entries(baseline.entries)) {
+    for (const [rule9, byMessage] of Object.entries(byRule)) {
+      if (rule9 === INTERNAL_ERROR_RULE_NAME) continue;
+      for (const [messageId, count] of Object.entries(byMessage)) {
+        remaining.set(path + KEY_SEP + rule9 + KEY_SEP + messageId, count);
+      }
+    }
+  }
+  const kept = [];
+  let hidden = 0;
+  for (const d of diagnostics) {
+    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) {
+      kept.push(d);
+      continue;
+    }
+    const key = fingerprint(d);
+    const left = remaining.get(key);
+    if (left !== void 0 && left > 0) {
+      remaining.set(key, left - 1);
+      hidden++;
+    } else {
+      kept.push(d);
+    }
+  }
+  return { kept, hidden };
+}
+function totalCount(baseline) {
+  let total = 0;
+  for (const byRule of Object.values(baseline.entries)) {
+    for (const byMessage of Object.values(byRule)) {
+      for (const count of Object.values(byMessage)) total += count;
+    }
+  }
+  return total;
+}
+function baselineWriteSummary(baseline) {
+  const violations = totalCount(baseline);
+  const files = Object.keys(baseline.entries).length;
+  const v = `${violations} ${violations === 1 ? "violation" : "violations"}`;
+  const f = `${files} ${files === 1 ? "file" : "files"}`;
+  return `Wrote ${v} across ${f} to ${BASELINE_DISPLAY_PATH}`;
+}
+function baselineMalformedWarning() {
+  return `madr-lint: warning: ${BASELINE_DISPLAY_PATH} is malformed; ignoring it (run --update-baseline to regenerate)`;
+}
+function baselineHiddenSummary(hidden) {
+  return `${hidden} ${hidden === 1 ? "problem" : "problems"} hidden by baseline (${BASELINE_DISPLAY_PATH})`;
+}
+
+// src/core/cache.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+var CACHE_SCHEMA_VERSION = 3;
+function computeContentHash(content) {
+  return createHash("sha1").update(content, "utf8").digest("hex");
+}
+function computeConfigHash(config) {
+  return createHash("sha1").update(stableStringify(config), "utf8").digest("hex");
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const entries = Object.entries(value).toSorted(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  return "{" + entries.map(([k, v]) => JSON.stringify(k) + ":" + stableStringify(v)).join(",") + "}";
+}
+function manifestPath(cacheDir) {
+  return join4(cacheDir, "manifest.json");
+}
+function loadManifest(path) {
+  if (!existsSync5(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync4(path, "utf8"));
+    if (
+      // Single invalidation point for schema drift: an unknown (or absent)
+      // schema version nulls here, so every consumer sees a cold cache — no
+      // scattered re-hydration of stale-shape entries downstream.
+      data.schemaVersion !== CACHE_SCHEMA_VERSION || typeof data.version !== "string" || typeof data.configHash !== "string" || typeof data.files !== "object" || data.files === null
+    ) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+function saveManifest(path, manifest) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, JSON.stringify(manifest), "utf8");
+}
+
+// src/core/fix.ts
+var MAX_FIX_PASSES = 10;
+function makeFixer(base) {
+  const shift = (n) => n + base;
+  return {
+    replaceRange(range, text) {
+      return { range: [shift(range[0]), shift(range[1])], text };
+    },
+    insertAt(offset, text) {
+      const at = shift(offset);
+      return { range: [at, at], text };
+    },
+    remove(range) {
+      return { range: [shift(range[0]), shift(range[1])], text: "" };
+    }
+  };
+}
+function applyEditsCounted(content, edits) {
+  const valid = edits.filter((e) => {
+    const [start, end] = e.range;
+    return Number.isInteger(start) && Number.isInteger(end) && start >= 0 && end >= start && end <= content.length;
+  });
+  const sorted = valid.toSorted(
+    (a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1]
+  );
+  let out = "";
+  let cursor = 0;
+  let applied = 0;
+  for (const edit of sorted) {
+    const [start, end] = edit.range;
+    if (start < cursor) continue;
+    out += content.slice(cursor, start) + edit.text;
+    cursor = end;
+    applied++;
+  }
+  return { text: out + content.slice(cursor), applied };
+}
+function collectFixes(diagnostics, content) {
+  const fixer = makeFixer(frontmatterOffset(content));
+  const edits = [];
+  for (const d of diagnostics) {
+    if (!d.fix) continue;
+    const result = d.fix(fixer);
+    if (result === null) continue;
+    if (Array.isArray(result)) edits.push(...result);
+    else edits.push(result);
+  }
+  return edits;
+}
+function collectProjectFixes(diagnostics, contentByPath) {
+  const fixer = makeFixer(0);
+  const byPath = /* @__PURE__ */ new Map();
+  for (const d of diagnostics) {
+    if (!d.fix) continue;
+    if (byPath.has(d.path)) continue;
+    if (contentByPath(d.path) === void 0) continue;
+    const result = d.fix(fixer);
+    if (result === null) continue;
+    byPath.set(d.path, Array.isArray(result) ? [...result] : [result]);
+  }
+  return byPath;
+}
+function fixFileContent(originalContent, lint, maxPasses = MAX_FIX_PASSES) {
+  let content = originalContent;
+  let passes = 0;
+  let applied = 0;
+  for (; ; ) {
+    const diagnostics = lint(content);
+    const done = () => ({
+      fixedContent: content,
+      remaining: diagnostics,
+      changed: content !== originalContent,
+      passes,
+      applied
+    });
+    if (passes >= maxPasses) return done();
+    const edits = collectFixes(diagnostics, content);
+    if (edits.length === 0) return done();
+    const { text: next, applied: landed } = applyEditsCounted(content, edits);
+    if (next === content) return done();
+    applied += landed;
+    content = next;
+    passes++;
+  }
+}
+var CONTEXT = 3;
+function unifiedDiff(path, before, after) {
+  if (before === after) return "";
+  const a = splitLines(before);
+  const b = splitLines(after);
+  const ops = diffLines(a, b);
+  const hunks = groupHunks(ops);
+  if (hunks.length === 0) return "";
+  const lines = [`--- a/${path}`, `+++ b/${path}`];
+  for (const hunk of hunks) lines.push(...renderHunk(hunk));
+  return lines.join("\n") + "\n";
+}
+function splitLines(text) {
+  if (text === "") return [];
+  const parts = text.split("\n");
+  if (parts[parts.length - 1] === "") parts.pop();
+  return parts;
+}
+function diffLines(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const lcs = Array.from(
+    { length: n + 1 },
+    () => Array.from({ length: m + 1 }).fill(0)
+  );
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      lcs[i2][j2] = a[i2] === b[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ kind: "eq", text: a[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      ops.push({ kind: "del", text: a[i] });
+      i++;
+    } else {
+      ops.push({ kind: "ins", text: b[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ kind: "del", text: a[i++] });
+  while (j < m) ops.push({ kind: "ins", text: b[j++] });
+  return ops;
+}
+function groupHunks(ops) {
+  const changeIdx = [];
+  ops.forEach((op, idx) => {
+    if (op.kind !== "eq") changeIdx.push(idx);
+  });
+  if (changeIdx.length === 0) return [];
+  const windows = [];
+  for (const idx of changeIdx) {
+    const start = Math.max(0, idx - CONTEXT);
+    const end = Math.min(ops.length - 1, idx + CONTEXT);
+    const last = windows[windows.length - 1];
+    if (last && start <= last[1] + 1) last[1] = Math.max(last[1], end);
+    else windows.push([start, end]);
+  }
+  const hunks = [];
+  for (const [start, end] of windows) {
+    let aLine = 1;
+    let bLine = 1;
+    for (let k = 0; k < start; k++) {
+      if (ops[k].kind !== "ins") aLine++;
+      if (ops[k].kind !== "del") bLine++;
+    }
+    const hunkOps = ops.slice(start, end + 1);
+    let aCount = 0;
+    let bCount = 0;
+    for (const op of hunkOps) {
+      if (op.kind !== "ins") aCount++;
+      if (op.kind !== "del") bCount++;
+    }
+    hunks.push({ aStart: aLine, aCount, bStart: bLine, bCount, ops: hunkOps });
+  }
+  return hunks;
+}
+function renderHunk(hunk) {
+  const header = `@@ -${hunk.aStart},${hunk.aCount} +${hunk.bStart},${hunk.bCount} @@`;
+  const body = hunk.ops.map((op) => {
+    const prefix = op.kind === "eq" ? " " : op.kind === "del" ? "-" : "+";
+    return `${prefix}${op.text}`;
+  });
+  return [header, ...body];
+}
+
+// src/core/runner.ts
+import Ajv from "ajv";
+
+// src/core/interpolate.ts
+function interpolate(template, data) {
+  if (!template.includes("{{")) return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const v = data[key];
+    return v !== void 0 ? String(v) : `{{${key}}}`;
+  });
+}
+
+// src/core/suppression.ts
+var DIRECTIVE_KINDS = /* @__PURE__ */ new Set([
+  "disable-file",
+  "disable",
+  "enable",
+  "disable-next-line"
+]);
+var DIRECTIVE_PREFIX = "madr-lint-";
+function parseDirective(value, line) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("<!--") || !trimmed.endsWith("-->")) return null;
+  const inner = trimmed.slice(4, -3).trim();
+  if (inner.includes("<!--") || inner.includes("-->")) return null;
+  if (!inner.startsWith(DIRECTIVE_PREFIX)) return null;
+  const afterPrefix = inner.slice(DIRECTIVE_PREFIX.length);
+  const wsIndex = afterPrefix.search(/\s/);
+  const keyword = wsIndex === -1 ? afterPrefix : afterPrefix.slice(0, wsIndex);
+  if (!DIRECTIVE_KINDS.has(keyword)) return null;
+  const rest = wsIndex === -1 ? "" : afterPrefix.slice(wsIndex);
+  return { kind: keyword, rules: parseRuleList(rest), line };
+}
+function parseRuleList(rest) {
+  const trimmed = rest.trim();
+  if (trimmed === "") return null;
+  const rules = trimmed.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  return rules.length > 0 ? rules : null;
+}
+function walkHtml(node, out) {
+  if (node.type === "html") {
+    const line = node.position?.start.line;
+    if (typeof line === "number") {
+      const directive = parseDirective(node.value, line);
+      if (directive) out.push(directive);
+    }
+  }
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) walkHtml(child, out);
+  }
+}
+function collectDirectives(ast, body) {
+  const all = [];
   walkHtml(ast, all);
   if (all.length === 0) return null;
   let lines = null;
@@ -609,6 +932,9 @@ var PerFileRuleContext = class {
   get metadataLoc() {
     return this.ensureParsed().metadataLoc;
   }
+  get metadataValueLoc() {
+    return this.ensureParsed().metadataValueLoc;
+  }
 };
 function runRulesOnFile(rules, file, runtime = {}) {
   const diagnostics = [];
@@ -636,18 +962,26 @@ function runRulesOnFile(rules, file, runtime = {}) {
     const ruleName = rule9.meta.name;
     const suggestions = rule9.meta.suggestions;
     const docsUrl = rule9.meta.docs.url ?? "";
+    const fixableRule = rule9.meta.fixable === "code";
     const context = new PerFileRuleContext(
       file,
       mergedOptions,
       ensureParsed,
       (d) => {
         const template = suggestions?.[d.messageId];
+        const hasFix = d.fix !== void 0;
+        if (hasFix && !fixableRule) {
+          throw new Error(
+            `Rule "${ruleName}" attached a fix but meta.fixable is not 'code'`
+          );
+        }
         diagnostics.push({
           ruleName,
           severity,
           path: file.path,
           suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
           docsUrl,
+          fixable: hasFix,
           ...d
         });
       }
@@ -684,6 +1018,7 @@ function internalErrorDiagnostic(ruleName, operation, err, path) {
     path,
     suggestion: null,
     docsUrl: INTERNAL_ERROR_DOCS_URL,
+    fixable: false,
     data: {
       rule: ruleName,
       operation,
@@ -761,17 +1096,25 @@ function runRulesOnProject(rules, files, runtime = {}) {
     const ruleName = rule9.meta.name;
     const suggestions = rule9.meta.suggestions;
     const docsUrl = rule9.meta.docs.url ?? "";
+    const fixableRule = rule9.meta.fixable === "code";
     const context = {
       files,
       options: mergedOptions,
       fileExists: runtime.fileExists,
       report(d) {
         const template = suggestions?.[d.messageId];
+        const hasFix = d.fix !== void 0;
+        if (hasFix && !fixableRule) {
+          throw new Error(
+            `Rule "${ruleName}" attached a fix but meta.fixable is not 'code'`
+          );
+        }
         diagnostics.push({
           ruleName,
           severity,
           suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
           docsUrl,
+          fixable: hasFix,
           ...d
         });
       }
@@ -796,7 +1139,7 @@ function lintFiles(opts) {
   const allDiagnostics = [];
   const fileEntries = opts.files.map((absolutePath) => ({
     relativePath: toPosix(relative(opts.cwd, absolutePath)),
-    content: readFileSync4(absolutePath, "utf8")
+    content: readFileSync5(absolutePath, "utf8")
   }));
   const perFileRules = [];
   const projectRules = [];
@@ -860,55 +1203,14 @@ function lintFiles(opts) {
     const projectFiles = fileEntries.map(
       (f) => buildProjectFile({ path: f.relativePath, content: f.content })
     );
-    const projectRoot = resolve2(opts.cwd);
-    const existsCache = /* @__PURE__ */ new Map();
-    const fileExists = (resolvedPath) => {
-      const cached = existsCache.get(resolvedPath);
-      if (cached !== void 0) return cached;
-      const abs = resolve2(projectRoot, resolvedPath);
-      const rel = relative(projectRoot, abs);
-      const escapesRoot = rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
-      let result;
-      if (escapesRoot) {
-        result = false;
-      } else {
-        try {
-          result = statSync2(abs, { throwIfNoEntry: false })?.isFile() ?? false;
-        } catch {
-          result = false;
-        }
-      }
-      existsCache.set(resolvedPath, result);
-      return result;
-    };
-    const errorRules = [];
-    const warnRules = [];
-    for (const rule9 of enabledProjectRules) {
-      const sev = resolveSeverity(opts.ruleSeverity[rule9.meta.name]);
-      if (sev === "error") errorRules.push(rule9);
-      else if (sev === "warn") warnRules.push(rule9);
-    }
-    const projectDiagnostics = [];
-    if (errorRules.length > 0) {
-      projectDiagnostics.push(
-        ...runRulesOnProject(errorRules, projectFiles, {
-          severity: "error",
-          fileExists,
-          optionsByRule
-        })
-      );
-    }
-    if (warnRules.length > 0) {
-      projectDiagnostics.push(
-        ...runRulesOnProject(warnRules, projectFiles, {
-          severity: "warn",
-          fileExists,
-          optionsByRule
-        })
-      );
-    }
     allDiagnostics.push(
-      ...filterSuppressedProjectDiagnostics(projectDiagnostics, projectFiles)
+      ...runProjectPass(
+        projectFiles,
+        enabledProjectRules,
+        opts.ruleSeverity,
+        optionsByRule,
+        opts.cwd
+      )
     );
   }
   if (manifest && opts.cache) {
@@ -930,241 +1232,225 @@ function lintFiles(opts) {
     baselineHidden: applied.hidden
   };
 }
-function runPerFileRulesForFile(perFileRules, ruleSeverity, optionsByRule, file) {
-  const fileContext = {
-    content: file.content,
-    path: file.relativePath
-  };
-  const errorRules = [];
-  const warnRules = [];
-  for (const rule9 of perFileRules) {
-    const sev = resolveSeverity(ruleSeverity[rule9.meta.name]);
-    if (sev === "off") continue;
-    if (sev === "error") errorRules.push(rule9);
-    else warnRules.push(rule9);
-  }
-  const diagnostics = [];
-  if (errorRules.length > 0) {
-    diagnostics.push(
-      ...runRulesOnFile(errorRules, fileContext, {
-        severity: "error",
-        optionsByRule
-      })
-    );
-  }
-  if (warnRules.length > 0) {
-    diagnostics.push(
-      ...runRulesOnFile(warnRules, fileContext, {
-        severity: "warn",
-        optionsByRule
-      })
-    );
-  }
-  return diagnostics;
-}
-function filterSuppressedProjectDiagnostics(diagnostics, projectFiles) {
-  if (diagnostics.length === 0) return [];
-  const fileByPath = new Map(projectFiles.map((f) => [f.path, f]));
-  const indexByPath = /* @__PURE__ */ new Map();
-  const indexFor = (path) => {
-    const cached = indexByPath.get(path);
-    if (cached !== void 0) return cached;
-    const file = fileByPath.get(path);
-    const index = file && file.content.includes(DIRECTIVE_PREFIX) ? collectDirectives(file.ast, file.body) : null;
-    indexByPath.set(path, index);
-    return index;
-  };
-  return diagnostics.filter((d) => {
-    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) return true;
-    const index = indexFor(d.path);
-    if (!index) return true;
-    return !isSuppressed(index, d.ruleName, d.loc?.line);
-  });
-}
-function resolveSeverity(config) {
-  if (config === void 0) return "off";
-  if (typeof config === "string") return config;
-  return config[0];
-}
-function extractOptionsByRule(ruleSeverity) {
-  const map = {};
-  for (const [name, config] of Object.entries(ruleSeverity)) {
-    if (Array.isArray(config) && config[1]) map[name] = config[1];
+function lintAndFix(opts) {
+  const perFileRules = [];
+  const projectRules = [];
+  for (const rule9 of opts.rules) {
+    if (isProjectRule(rule9)) projectRules.push(rule9);
+    else perFileRules.push(rule9);
   }
-  return map;
-}
-
-// src/core/reporter.ts
-import pc from "picocolors";
-var textReporter = {
-  // Deliberately 2-param (meta unused): the CLI prints baselineHiddenSummary()
-  // itself for text format, so the footer can outlive a suppressed banner.
-  format(diagnostics, rulesByName) {
-    if (diagnostics.length === 0) {
-      return pc.green("\u2713 All clear.");
-    }
-    const byFile = groupByFile(diagnostics);
-    const lines = [];
-    const gutter = " ".repeat(9 + 28 + 2);
-    for (const [file, fileDiagnostics] of byFile) {
-      lines.push(pc.underline(file));
-      const docsByRule = /* @__PURE__ */ new Map();
-      for (const d of fileDiagnostics) {
-        const sev = d.severity === "error" ? pc.red("  error  ") : pc.yellow("  warn   ");
-        const ruleId = pc.dim(d.ruleName.padEnd(28));
-        const message = renderMessage(d, rulesByName);
-        lines.push(`${sev}${ruleId}  ${message}`);
-        if (d.suggestion) {
-          lines.push(`${gutter}${pc.cyan(`\u2192 ${d.suggestion}`)}`);
-        }
-        if (d.docsUrl && !docsByRule.has(d.ruleName)) {
-          docsByRule.set(d.ruleName, d.docsUrl);
-        }
-      }
-      for (const [ruleName, url] of docsByRule) {
-        lines.push(pc.dim(`  ${ruleName}  ${url}`));
+  const optionsByRule = extractOptionsByRule(opts.ruleSeverity);
+  const baseline = opts.baseline ?? null;
+  const files = [];
+  const remaining = [];
+  let fixed = 0;
+  let baselineHidden = 0;
+  for (const absPath of opts.files) {
+    const relativePath = toPosix(relative(opts.cwd, absPath));
+    const original = readFileSync5(absPath, "utf8");
+    let lastHidden = 0;
+    const lint = (content) => {
+      const raw = runPerFileRulesForFile(
+        perFileRules,
+        opts.ruleSeverity,
+        optionsByRule,
+        { relativePath, content }
+      );
+      if (!baseline) {
+        lastHidden = 0;
+        return raw;
       }
-      lines.push("");
-    }
-    const errors = diagnostics.filter((d) => d.severity === "error").length;
-    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
-    lines.push(pc.bold(formatSummary(errors, warnings)));
-    return lines.join("\n");
-  }
-};
-function groupByFile(diagnostics) {
-  const map = /* @__PURE__ */ new Map();
-  for (const d of diagnostics) {
-    if (!map.has(d.path)) map.set(d.path, []);
-    map.get(d.path)?.push(d);
-  }
-  return map;
-}
-function renderMessage(d, rulesByName) {
-  const rule9 = rulesByName.get(d.ruleName);
-  const template = rule9?.meta.messages[d.messageId] ?? d.messageId;
-  return interpolate(template, d.data ?? {});
-}
-function formatSummary(errors, warnings) {
-  const parts = [];
-  if (errors > 0) parts.push(`${errors} ${errors === 1 ? "error" : "errors"}`);
-  if (warnings > 0) parts.push(`${warnings} ${warnings === 1 ? "warning" : "warnings"}`);
-  return parts.join(", ");
-}
-var jsonReporter = {
-  format(diagnostics, rulesByName, meta) {
-    const errors = diagnostics.filter((d) => d.severity === "error").length;
-    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
-    const payload = {
-      version: 1,
-      summary: {
-        total: diagnostics.length,
-        errors,
-        warnings,
-        // Always present (0 when no baseline) so CI consumers can detect an
-        // active baseline without probing for the key. SARIF stays untouched.
-        baselineHidden: meta?.baselineHidden ?? 0
-      },
-      results: diagnostics.map((d) => ({
-        path: d.path,
-        ruleName: d.ruleName,
-        messageId: d.messageId,
-        severity: d.severity,
-        message: renderMessage(d, rulesByName),
-        // Self-contained diagnostics (#67): always present so consumers can
-        // rely on the keys — `suggestion` is null when the rule declares none.
-        suggestion: d.suggestion,
-        docsUrl: d.docsUrl,
-        data: d.data ?? {}
-      }))
+      const sub = applyBaseline(raw, baseline);
+      lastHidden = sub.hidden;
+      return sub.kept;
     };
-    return JSON.stringify(payload, null, 2);
-  }
-};
-var sarifReporter = {
-  format(diagnostics, rulesByName) {
-    const ruleNames = [...new Set(diagnostics.map((d) => d.ruleName))];
-    const ruleIndex = new Map(ruleNames.map((name, i) => [name, i]));
-    const sarifRules = ruleNames.map((name) => {
-      const rule9 = rulesByName.get(name);
-      return {
-        id: name,
-        name: name.replace(/[^A-Za-z0-9]/g, "_"),
-        shortDescription: { text: rule9?.meta.docs.description ?? name },
-        helpUri: rule9?.meta.docs.url
-      };
+    const res = fixFileContent(original, lint, opts.maxPasses);
+    files.push({
+      path: relativePath,
+      absPath,
+      original,
+      fixed: res.fixedContent,
+      changed: res.changed
     });
-    const sarifResults = diagnostics.map((d) => ({
-      ruleId: d.ruleName,
-      ruleIndex: ruleIndex.get(d.ruleName) ?? 0,
-      level: d.severity === "error" ? "error" : "warning",
-      message: { text: renderMessage(d, rulesByName) },
-      locations: [
-        {
-          physicalLocation: {
-            artifactLocation: { uri: d.path, uriBaseId: "%SRCROOT%" },
-            region: { startLine: 1 }
-          }
-        }
-      ]
-    }));
-    const sarif = {
-      $schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
-      version: "2.1.0",
-      runs: [
-        {
-          tool: {
-            driver: {
-              name: "madr-lint",
-              informationUri: "https://github.com/knktkc/madr-lint",
-              rules: sarifRules
-            }
-          },
-          results: sarifResults
+    remaining.push(...res.remaining);
+    fixed += res.applied;
+    baselineHidden += lastHidden;
+  }
+  const enabledProjectRules = projectRules.filter(
+    (rule9) => resolveSeverity(opts.ruleSeverity[rule9.meta.name]) !== "off"
+  );
+  if (enabledProjectRules.length > 0) {
+    const contentByPath = new Map(files.map((f) => [f.path, f.fixed]));
+    const maxPasses = opts.maxPasses ?? MAX_FIX_PASSES;
+    let projectDiags = [];
+    let passes = 0;
+    for (; ; ) {
+      const projectFiles = files.map(
+        (f) => buildProjectFile({ path: f.path, content: contentByPath.get(f.path) ?? f.fixed })
+      );
+      let diags = runProjectPass(
+        projectFiles,
+        enabledProjectRules,
+        opts.ruleSeverity,
+        optionsByRule,
+        opts.cwd
+      );
+      let hiddenThisPass = 0;
+      if (baseline) {
+        const sub = applyBaseline(diags, baseline);
+        diags = sub.kept;
+        hiddenThisPass = sub.hidden;
+      }
+      projectDiags = diags;
+      if (passes >= maxPasses) {
+        baselineHidden += hiddenThisPass;
+        break;
+      }
+      const fixesByPath = collectProjectFixes(diags, (p) => contentByPath.get(p));
+      let progressed = false;
+      for (const [path, edits] of fixesByPath) {
+        const before = contentByPath.get(path);
+        if (before === void 0) continue;
+        const { text, applied } = applyEditsCounted(before, edits);
+        if (text !== before) {
+          contentByPath.set(path, text);
+          fixed += applied;
+          progressed = true;
         }
-      ]
-    };
-    return JSON.stringify(sarif, null, 2);
+      }
+      if (!progressed) {
+        baselineHidden += hiddenThisPass;
+        break;
+      }
+      passes++;
+    }
+    for (const f of files) {
+      const c = contentByPath.get(f.path);
+      if (c !== void 0 && c !== f.fixed) {
+        f.fixed = c;
+        f.changed = f.fixed !== f.original;
+      }
+    }
+    remaining.push(...projectDiags);
   }
-};
-function escapeGhMessage(s) {
-  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+  return { files, diagnostics: remaining, fixed, baselineHidden };
 }
-function escapeGhProperty(s) {
-  return escapeGhMessage(s).replace(/,/g, "%2C").replace(/:/g, "%3A");
+function runPerFileRulesForFile(perFileRules, ruleSeverity, optionsByRule, file) {
+  const fileContext = {
+    content: file.content,
+    path: file.relativePath
+  };
+  const errorRules = [];
+  const warnRules = [];
+  for (const rule9 of perFileRules) {
+    const sev = resolveSeverity(ruleSeverity[rule9.meta.name]);
+    if (sev === "off") continue;
+    if (sev === "error") errorRules.push(rule9);
+    else warnRules.push(rule9);
+  }
+  const diagnostics = [];
+  if (errorRules.length > 0) {
+    diagnostics.push(
+      ...runRulesOnFile(errorRules, fileContext, {
+        severity: "error",
+        optionsByRule
+      })
+    );
+  }
+  if (warnRules.length > 0) {
+    diagnostics.push(
+      ...runRulesOnFile(warnRules, fileContext, {
+        severity: "warn",
+        optionsByRule
+      })
+    );
+  }
+  return diagnostics;
 }
-var githubReporter = {
-  format(diagnostics, rulesByName, meta) {
-    const lines = [];
-    for (const d of diagnostics) {
-      const level = d.severity === "error" ? "error" : "warning";
-      const file = escapeGhProperty(d.path);
-      const title = escapeGhProperty(d.ruleName);
-      const rendered = renderMessage(d, rulesByName);
-      const message = escapeGhMessage(
-        d.suggestion ? `${rendered} \u2014 ${d.suggestion}` : rendered
-      );
-      const linePart = d.loc ? `,line=${d.loc.line}` : "";
-      lines.push(`::${level} file=${file}${linePart},title=${title}::${message}`);
+function makeFileExists(cwd) {
+  const projectRoot = resolve3(cwd);
+  const existsCache = /* @__PURE__ */ new Map();
+  return (resolvedPath) => {
+    const cached = existsCache.get(resolvedPath);
+    if (cached !== void 0) return cached;
+    const abs = resolve3(projectRoot, resolvedPath);
+    const rel = relative(projectRoot, abs);
+    const escapesRoot = rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+    let result;
+    if (escapesRoot) {
+      result = false;
+    } else {
+      try {
+        result = statSync2(abs, { throwIfNoEntry: false })?.isFile() ?? false;
+      } catch {
+        result = false;
+      }
     }
-    const errors = diagnostics.filter((d) => d.severity === "error").length;
-    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
-    const summaryParts = [];
-    if (errors > 0) summaryParts.push(`${errors} ${errors === 1 ? "error" : "errors"}`);
-    if (warnings > 0) summaryParts.push(`${warnings} ${warnings === 1 ? "warning" : "warnings"}`);
-    if (summaryParts.length === 0) summaryParts.push("0 errors, 0 warnings");
-    const baselineHidden = meta?.baselineHidden ?? 0;
-    if (baselineHidden > 0) summaryParts.push(`${baselineHidden} hidden by baseline`);
-    lines.push(summaryParts.join(", "));
-    return lines.join("\n");
+    existsCache.set(resolvedPath, result);
+    return result;
+  };
+}
+function runProjectPass(projectFiles, enabledProjectRules, ruleSeverity, optionsByRule, cwd) {
+  const fileExists = makeFileExists(cwd);
+  const errorRules = [];
+  const warnRules = [];
+  for (const rule9 of enabledProjectRules) {
+    const sev = resolveSeverity(ruleSeverity[rule9.meta.name]);
+    if (sev === "error") errorRules.push(rule9);
+    else if (sev === "warn") warnRules.push(rule9);
   }
-};
-var reporters = {
-  text: textReporter,
-  json: jsonReporter,
-  sarif: sarifReporter,
-  github: githubReporter
-};
+  const projectDiagnostics = [];
+  if (errorRules.length > 0) {
+    projectDiagnostics.push(
+      ...runRulesOnProject(errorRules, projectFiles, {
+        severity: "error",
+        fileExists,
+        optionsByRule
+      })
+    );
+  }
+  if (warnRules.length > 0) {
+    projectDiagnostics.push(
+      ...runRulesOnProject(warnRules, projectFiles, {
+        severity: "warn",
+        fileExists,
+        optionsByRule
+      })
+    );
+  }
+  return filterSuppressedProjectDiagnostics(projectDiagnostics, projectFiles);
+}
+function filterSuppressedProjectDiagnostics(diagnostics, projectFiles) {
+  if (diagnostics.length === 0) return [];
+  const fileByPath = new Map(projectFiles.map((f) => [f.path, f]));
+  const indexByPath = /* @__PURE__ */ new Map();
+  const indexFor = (path) => {
+    const cached = indexByPath.get(path);
+    if (cached !== void 0) return cached;
+    const file = fileByPath.get(path);
+    const index = file && file.content.includes(DIRECTIVE_PREFIX) ? collectDirectives(file.ast, file.body) : null;
+    indexByPath.set(path, index);
+    return index;
+  };
+  return diagnostics.filter((d) => {
+    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) return true;
+    const index = indexFor(d.path);
+    if (!index) return true;
+    return !isSuppressed(index, d.ruleName, d.loc?.line);
+  });
+}
+function resolveSeverity(config) {
+  if (config === void 0) return "off";
+  if (typeof config === "string") return config;
+  return config[0];
+}
+function extractOptionsByRule(ruleSeverity) {
+  const map = {};
+  for (const [name, config] of Object.entries(ruleSeverity)) {
+    if (Array.isArray(config) && config[1]) map[name] = config[1];
+  }
+  return map;
+}
 
 // src/rules/index.ts
 var rules_exports = {};
@@ -1209,6 +1495,58 @@ function isValidIso8601Date(s) {
   const d = new Date(Date.UTC(year, month - 1, day));
   return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day;
 }
+var MONTHS = {
+  jan: 1,
+  january: 1,
+  feb: 2,
+  february: 2,
+  mar: 3,
+  march: 3,
+  apr: 4,
+  april: 4,
+  may: 5,
+  jun: 6,
+  june: 6,
+  jul: 7,
+  july: 7,
+  aug: 8,
+  august: 8,
+  sep: 9,
+  sept: 9,
+  september: 9,
+  oct: 10,
+  october: 10,
+  nov: 11,
+  november: 11,
+  dec: 12,
+  december: 12
+};
+function pad(n, width) {
+  return String(n).padStart(width, "0");
+}
+function buildIso(year, month, day) {
+  if (month < 1 || month > 12 || day < 1 || day > 31) return null;
+  const iso = `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+  return isValidIso8601Date(iso) ? iso : null;
+}
+function normalizeToIso(raw) {
+  const s = raw.trim();
+  const numeric = /^(\d{4})([-/.])(\d{1,2})\2(\d{1,2})$/.exec(s);
+  if (numeric) {
+    return buildIso(Number(numeric[1]), Number(numeric[3]), Number(numeric[4]));
+  }
+  const dMonY = /^(\d{1,2})\s+([A-Za-z]+)\.?\s+(\d{4})$/.exec(s);
+  if (dMonY) {
+    const month = MONTHS[dMonY[2].toLowerCase()];
+    return month ? buildIso(Number(dMonY[3]), month, Number(dMonY[1])) : null;
+  }
+  const monDY = /^([A-Za-z]+)\.?\s+(\d{1,2}),?\s+(\d{4})$/.exec(s);
+  if (monDY) {
+    const month = MONTHS[monDY[1].toLowerCase()];
+    return month ? buildIso(Number(monDY[3]), month, Number(monDY[2])) : null;
+  }
+  return null;
+}
 var rule = {
   meta: {
     name: "madr/date-iso8601",
@@ -1227,6 +1565,10 @@ var rule = {
       missingDate: 'add a "{{field}}" field in YYYY-MM-DD format to the frontmatter (for MADR v2, a "* Date: ..." list item)',
       invalidDate: "use the YYYY-MM-DD calendar-date format, e.g. 2025-03-14"
     },
+    // Autofix (#29): normalize UNAMBIGUOUS shapes of a v2 list-sourced value —
+    // year-first numeric and English named-month forms. Ambiguous day/month
+    // order, invalid calendar dates, and frontmatter-sourced values get no fix.
+    fixable: "code",
     defaultOptions: {
       field: "date"
     },
@@ -1253,10 +1595,14 @@ var rule = {
     }
     if (!isValidIso8601Date(dateStr)) {
       const loc = context.metadataLoc?.[fieldName];
+      const valueRange = context.metadataValueLoc?.[fieldName];
+      const normalized = valueRange ? normalizeToIso(dateStr) : null;
+      const fix = normalized !== null && normalized !== dateStr && valueRange ? (fixer) => fixer.replaceRange([valueRange.start, valueRange.end], normalized) : void 0;
       context.report({
         messageId: "invalidDate",
         ...loc ? { loc } : {},
-        data: { date: dateStr }
+        data: { date: dateStr },
+        ...fix ? { fix } : {}
       });
     }
   }
@@ -1264,7 +1610,7 @@ var rule = {
 var date_iso8601_default = rule;
 
 // src/rules/filename-format/index.ts
-import { basename as basename2 } from "path";
+import { basename } from "path";
 
 // src/core/regex-safety.ts
 import safeRegex from "safe-regex2";
@@ -1332,7 +1678,7 @@ var rule2 = {
   create(context) {
     const { pattern } = context.options;
     const regex = assertSafeRegex(pattern, "madr/filename-format", "pattern");
-    const filename = basename2(context.file.path);
+    const filename = basename(context.file.path);
     if (!regex.test(filename)) {
       context.report({
         messageId: "invalidFilename",
@@ -1441,7 +1787,7 @@ var rule3 = {
 var no_broken_links_default = rule3;
 
 // src/rules/no-duplicate-numbering/index.ts
-import { basename as basename3 } from "path";
+import { basename as basename2 } from "path";
 
 // src/rules/no-duplicate-numbering/schema.json
 var schema_default4 = {
@@ -1475,7 +1821,7 @@ var rule4 = {
   check(context) {
     const byNumber = /* @__PURE__ */ new Map();
     for (const file of context.files) {
-      const match = NUMBER_REGEX.exec(basename3(file.path));
+      const match = NUMBER_REGEX.exec(basename2(file.path));
       if (!match) continue;
       const number = match[1];
       if (number === void 0) continue;
@@ -1500,7 +1846,7 @@ var rule4 = {
 var no_duplicate_numbering_default = rule4;
 
 // src/rules/no-numbering-gap/index.ts
-import { basename as basename4 } from "path";
+import { basename as basename3 } from "path";
 
 // src/rules/no-numbering-gap/schema.json
 var schema_default5 = {
@@ -1537,7 +1883,7 @@ var rule5 = {
   check(context) {
     const numberToPath = /* @__PURE__ */ new Map();
     for (const file of context.files) {
-      const match = NUMBER_REGEX2.exec(basename4(file.path));
+      const match = NUMBER_REGEX2.exec(basename3(file.path));
       if (!match?.[1]) continue;
       const n = Number.parseInt(match[1], 10);
       if (!Number.isNaN(n)) numberToPath.set(n, file.path);
@@ -1674,6 +2020,43 @@ var schema_default7 = {
 };
 
 // src/rules/status-enum/index.ts
+var TYPO_CORRECTIONS = {
+  superceded: "superseded",
+  supercedes: "supersedes",
+  depricated: "deprecated"
+};
+function repairTypos(lower) {
+  return lower.split(" ").map((tok) => TYPO_CORRECTIONS[tok] ?? tok).join(" ");
+}
+function tailAfterWords(s, n) {
+  let i = 0;
+  for (let w = 0; w < n; w++) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    while (i < s.length && !/\s/.test(s[i])) i++;
+  }
+  return s.slice(i);
+}
+function correctStatus(status, values, prefixValues) {
+  const repaired = repairTypos(status.toLowerCase());
+  const exact = [...new Set(values.filter((v) => v.toLowerCase() === repaired))];
+  if (exact.length === 1) {
+    return exact[0] !== status ? exact[0] : void 0;
+  }
+  if (exact.length > 1) return void 0;
+  const prefixes = [
+    ...new Set(
+      prefixValues.filter((p) => {
+        const pl = p.toLowerCase();
+        return repaired === pl || repaired.startsWith(`${pl} `);
+      })
+    )
+  ];
+  if (prefixes.length !== 1) return void 0;
+  const prefix = prefixes[0];
+  const tail = tailAfterWords(status, prefix.split(" ").length);
+  const replacement = `${prefix}${tail}`;
+  return replacement !== status ? replacement : void 0;
+}
 var rule7 = {
   meta: {
     name: "madr/status-enum",
@@ -1694,6 +2077,11 @@ var rule7 = {
     suggestions: {
       missingStatus: 'add a "status" field to the frontmatter (for MADR v2, a "* Status: ..." list item) \u2014 allowed values: {{allowed}}'
     },
+    // Autofix (#28/#29): normalize a v2 list-sourced value to the unique
+    // canonical enum entry — case difference, a curated misspelling, or a prefix
+    // case/typo — preserving any tail (see create()). Ambiguous or
+    // frontmatter-sourced values get no fix.
+    fixable: "code",
     defaultOptions: {
       values: ["proposed", "rejected", "accepted", "deprecated"],
       prefixValues: ["superseded by"],
@@ -1719,10 +2107,14 @@ var rule7 = {
     );
     if (!exactMatch && !prefixMatch) {
       const loc = context.metadataLoc?.status;
+      const canonical = correctStatus(status, values, prefixValues);
+      const valueRange = context.metadataValueLoc?.status;
+      const fix = canonical !== void 0 && canonical !== status && valueRange ? (fixer) => fixer.replaceRange([valueRange.start, valueRange.end], canonical) : void 0;
       context.report({
         messageId: "invalidStatus",
         ...loc ? { loc } : {},
-        data: { status, allowed }
+        data: { status, allowed },
+        ...fix ? { fix } : {}
       });
     }
   }
@@ -1730,7 +2122,7 @@ var rule7 = {
 var status_enum_default = rule7;
 
 // src/rules/supersedes-bidirectional/index.ts
-import { basename as basename5 } from "path";
+import { basename as basename4 } from "path";
 
 // src/rules/supersedes-bidirectional/schema.json
 var schema_default8 = {
@@ -1745,7 +2137,7 @@ var ADR_NUMBER_REGEX = /^(\d{4})-/;
 var FORWARD_FIELD = "supersedes";
 var BACKWARD_FIELD = "superseded-by";
 function extractAdrNumber(path) {
-  const match = ADR_NUMBER_REGEX.exec(basename5(path));
+  const match = ADR_NUMBER_REGEX.exec(basename4(path));
   return match?.[1] ?? null;
 }
 function normalizeRefs(value) {
@@ -1755,6 +2147,28 @@ function normalizeRefs(value) {
   }
   return [];
 }
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function frontmatterInsertEdit(content, key, value) {
+  const fmEnd = frontmatterOffset(content);
+  if (fmEnd === 0) return null;
+  const fmBlock = content.slice(0, fmEnd);
+  const closeMatch = /\r?\n(---[ \t]*\r?\n)$/.exec(fmBlock);
+  if (!closeMatch) return null;
+  const fenceLine = closeMatch[1];
+  const offset = closeMatch.index + (closeMatch[0].length - fenceLine.length);
+  if (content.slice(offset, offset + 3) !== "---") return null;
+  const keyPattern = new RegExp(`(^|\\r?\\n)${escapeRegExp(key)}[ \\t]*:`, "i");
+  if (keyPattern.test(content.slice(0, offset))) return null;
+  const eol = fenceLine.endsWith("\r\n") ? "\r\n" : "\n";
+  return { offset, text: `${key}: ${value}${eol}` };
+}
+function backReferenceFix(target, key, value) {
+  const edit = frontmatterInsertEdit(target.content, key, value);
+  if (!edit) return void 0;
+  return (fixer) => fixer.insertAt(edit.offset, edit.text);
+}
 var rule8 = {
   meta: {
     name: "madr/supersedes-bidirectional",
@@ -1777,6 +2191,11 @@ var rule8 = {
       unknownReference: 'correct "{{ref}}" to an existing ADR number, or remove "{{direction}}: {{ref}}" from the frontmatter',
       missingBackReference: 'add "{{direction}}: {{expected}}" to the frontmatter of this file'
     },
+    // Cross-file autofix (#29): `missingBackReference` inserts the reciprocal
+    // `<direction>: <expected>` line into the target's EXISTING frontmatter.
+    // Targets without frontmatter, or where the key already exists, decline;
+    // `unknownReference` is contextual and never fixable.
+    fixable: "code",
     defaultOptions: {},
     schema: schema_default8
   },
@@ -1804,50 +2223,381 @@ var rule8 = {
           });
           continue;
         }
-        const targetBack = normalizeRefs(target.frontmatter?.[BACKWARD_FIELD]);
-        if (!targetBack.includes(fileRef)) {
-          context.report({
-            messageId: "missingBackReference",
-            path: target.path,
-            data: {
-              ref,
-              source: file.path,
-              declared: FORWARD_FIELD,
-              direction: BACKWARD_FIELD,
-              expected: fileRef
-            }
-          });
+        const targetBack = normalizeRefs(target.frontmatter?.[BACKWARD_FIELD]);
+        if (!targetBack.includes(fileRef)) {
+          const fix = backReferenceFix(target, BACKWARD_FIELD, fileRef);
+          context.report({
+            messageId: "missingBackReference",
+            path: target.path,
+            data: {
+              ref,
+              source: file.path,
+              declared: FORWARD_FIELD,
+              direction: BACKWARD_FIELD,
+              expected: fileRef
+            },
+            ...fix ? { fix } : {}
+          });
+        }
+      }
+      for (const ref of backwardRefs) {
+        const target = adrIndex.get(ref);
+        if (!target) {
+          context.report({
+            messageId: "unknownReference",
+            path: file.path,
+            data: { ref, direction: BACKWARD_FIELD }
+          });
+          continue;
+        }
+        const targetFwd = normalizeRefs(target.frontmatter?.[FORWARD_FIELD]);
+        if (!targetFwd.includes(fileRef)) {
+          const fix = backReferenceFix(target, FORWARD_FIELD, fileRef);
+          context.report({
+            messageId: "missingBackReference",
+            path: target.path,
+            data: {
+              ref,
+              source: file.path,
+              declared: BACKWARD_FIELD,
+              direction: FORWARD_FIELD,
+              expected: fileRef
+            },
+            ...fix ? { fix } : {}
+          });
+        }
+      }
+    }
+  }
+};
+var supersedes_bidirectional_default = rule8;
+
+// src/commands/init.ts
+var initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description: "Scaffold a madr-lint config file (detects ADR directory, MADR version, and TS vs JSON)"
+  },
+  args: {
+    force: {
+      type: "boolean",
+      description: "Overwrite an existing config file",
+      default: false
+    },
+    dir: {
+      type: "string",
+      description: "ADR directory to write into the config, overriding detection",
+      required: false
+    },
+    json: {
+      type: "boolean",
+      description: "Emit a machine-readable JSON summary instead of text",
+      default: false
+    }
+  },
+  run({ args }) {
+    const cwd = process.cwd();
+    const rawDir = args.dir;
+    if (rawDir !== void 0 && rawDir.trim() === "") {
+      console.error(`Invalid --dir "${rawDir}": must be a non-empty path.`);
+      process.exit(2);
+    }
+    const existing = findExistingConfigFile(cwd);
+    if (existing && args.force !== true) {
+      console.error(
+        `A madr-lint config already exists: ${existing}. Re-run with --force to overwrite.`
+      );
+      process.exit(2);
+    }
+    let adrDir;
+    let adrDirSource;
+    if (rawDir !== void 0) {
+      adrDir = rawDir;
+      adrDirSource = "override";
+    } else {
+      const detected = detectAdrDir(cwd);
+      adrDir = detected.adrDir;
+      adrDirSource = detected.source;
+    }
+    const madrVersion = detectMadrVersion(cwd, adrDir);
+    const configFormat = detectConfigFormat(cwd);
+    const configPath = CONFIG_FILENAME_BY_FORMAT[configFormat];
+    writeFileSync3(
+      resolve4(cwd, configPath),
+      renderConfig(configFormat, { adrDir, madrVersion })
+    );
+    if (existing && existing !== configPath) {
+      const oldWins = CONFIG_FILES.indexOf(existing) < CONFIG_FILES.indexOf(configPath);
+      console.error(
+        oldWins ? `Note: ${existing} still exists and precedes ${configPath} in config discovery \u2014 remove it to make the new config take effect.` : `Note: the leftover ${existing} is now shadowed by ${configPath}, which precedes it in config discovery \u2014 you can delete it.`
+      );
+    }
+    const files = findAdrFiles(resolve4(cwd, adrDir));
+    let errors = 0;
+    let warnings = 0;
+    if (files.length > 0) {
+      try {
+        const config = resolveExtends({ extends: ["madr-lint:recommended"] });
+        const allRules = Object.values(rules_exports);
+        const result = lintFiles({
+          rules: allRules,
+          ruleSeverity: config.rules,
+          files,
+          cwd,
+          cache: null,
+          baseline: null
+        });
+        for (const d of result.diagnostics) {
+          if (d.severity === "error") errors++;
+          else warnings++;
+        }
+      } catch (err) {
+        console.error(
+          `Note: the initial lint failed (${err instanceof Error ? err.message : String(err)}); the config was still written.`
+        );
+      }
+    }
+    const filesChecked = files.length;
+    const suggestUpdateBaseline = filesChecked > 0 && errors + warnings > 0;
+    if (args.json === true) {
+      console.log(
+        JSON.stringify(
+          {
+            written: true,
+            configPath,
+            configFormat,
+            adrDir,
+            adrDirSource,
+            madrVersion,
+            filesChecked,
+            errors,
+            warnings,
+            suggestUpdateBaseline,
+            docsUrl: GETTING_STARTED_URL
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(
+        buildEpilogue({
+          adrDir,
+          adrDirSource,
+          configPath,
+          filesChecked,
+          errors,
+          warnings
+        })
+      );
+    }
+    process.exit(0);
+  }
+});
+
+// src/core/ignore.ts
+import { basename as basename5 } from "path";
+import picomatch from "picomatch";
+function shouldIgnore(relativePath, patterns) {
+  if (patterns.length === 0) return false;
+  const base = basename5(relativePath);
+  for (const pattern of patterns) {
+    if (matchesPattern(relativePath, base, pattern)) return true;
+  }
+  return false;
+}
+function matchesPattern(relativePath, base, pattern) {
+  if (relativePath === pattern) return true;
+  const matcher = picomatch(pattern, { dot: true });
+  if (matcher(relativePath)) return true;
+  if (matcher(base)) return true;
+  if (pattern.includes("/") && !pattern.startsWith("**/")) {
+    const suffixMatcher = picomatch(`**/${pattern}`, { dot: true });
+    if (suffixMatcher(relativePath)) return true;
+  }
+  return false;
+}
+
+// src/core/reporter.ts
+import pc from "picocolors";
+var textReporter = {
+  // Deliberately 2-param (meta unused): the CLI prints baselineHiddenSummary()
+  // itself for text format, so the footer can outlive a suppressed banner.
+  format(diagnostics, rulesByName) {
+    if (diagnostics.length === 0) {
+      return pc.green("\u2713 All clear.");
+    }
+    const byFile = groupByFile(diagnostics);
+    const lines = [];
+    const gutter = " ".repeat(9 + 28 + 2);
+    for (const [file, fileDiagnostics] of byFile) {
+      lines.push(pc.underline(file));
+      const docsByRule = /* @__PURE__ */ new Map();
+      for (const d of fileDiagnostics) {
+        const sev = d.severity === "error" ? pc.red("  error  ") : pc.yellow("  warn   ");
+        const ruleId = pc.dim(d.ruleName.padEnd(28));
+        const message = renderMessage(d, rulesByName);
+        const fixTag = d.fixable ? pc.dim(" \u{1F527} fixable") : "";
+        lines.push(`${sev}${ruleId}  ${message}${fixTag}`);
+        if (d.suggestion) {
+          lines.push(`${gutter}${pc.cyan(`\u2192 ${d.suggestion}`)}`);
+        }
+        if (d.docsUrl && !docsByRule.has(d.ruleName)) {
+          docsByRule.set(d.ruleName, d.docsUrl);
         }
       }
-      for (const ref of backwardRefs) {
-        const target = adrIndex.get(ref);
-        if (!target) {
-          context.report({
-            messageId: "unknownReference",
-            path: file.path,
-            data: { ref, direction: BACKWARD_FIELD }
-          });
-          continue;
+      for (const [ruleName, url] of docsByRule) {
+        lines.push(pc.dim(`  ${ruleName}  ${url}`));
+      }
+      lines.push("");
+    }
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
+    lines.push(pc.bold(formatSummary(errors, warnings)));
+    return lines.join("\n");
+  }
+};
+function groupByFile(diagnostics) {
+  const map = /* @__PURE__ */ new Map();
+  for (const d of diagnostics) {
+    if (!map.has(d.path)) map.set(d.path, []);
+    map.get(d.path)?.push(d);
+  }
+  return map;
+}
+function renderMessage(d, rulesByName) {
+  const rule9 = rulesByName.get(d.ruleName);
+  const template = rule9?.meta.messages[d.messageId] ?? d.messageId;
+  return interpolate(template, d.data ?? {});
+}
+function formatSummary(errors, warnings) {
+  const parts = [];
+  if (errors > 0) parts.push(`${errors} ${errors === 1 ? "error" : "errors"}`);
+  if (warnings > 0) parts.push(`${warnings} ${warnings === 1 ? "warning" : "warnings"}`);
+  return parts.join(", ");
+}
+var jsonReporter = {
+  format(diagnostics, rulesByName, meta) {
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
+    const payload = {
+      version: 1,
+      summary: {
+        total: diagnostics.length,
+        errors,
+        warnings,
+        // Always present (0 when no baseline) so CI consumers can detect an
+        // active baseline without probing for the key. SARIF stays untouched.
+        baselineHidden: meta?.baselineHidden ?? 0,
+        // `fixed` appears ONLY when a fix pass ran (#28) — a plain lint keeps
+        // the summary shape it always had.
+        ...meta?.fixed !== void 0 ? { fixed: meta.fixed } : {}
+      },
+      // Dry-run diffs (#28): embedded so `--fix-dry-run --format json` keeps
+      // stdout pure JSON while still delivering the diff. Absent otherwise.
+      ...meta?.fixDiffs !== void 0 ? { diffs: meta.fixDiffs } : {},
+      results: diagnostics.map((d) => ({
+        path: d.path,
+        ruleName: d.ruleName,
+        messageId: d.messageId,
+        severity: d.severity,
+        message: renderMessage(d, rulesByName),
+        // Self-contained diagnostics (#67): always present so consumers can
+        // rely on the keys — `suggestion` is null when the rule declares none.
+        suggestion: d.suggestion,
+        docsUrl: d.docsUrl,
+        // Autofix (#28): whether `--fix` can repair this diagnostic.
+        fixable: d.fixable,
+        data: d.data ?? {}
+      }))
+    };
+    return JSON.stringify(payload, null, 2);
+  }
+};
+var sarifReporter = {
+  format(diagnostics, rulesByName) {
+    const ruleNames = [...new Set(diagnostics.map((d) => d.ruleName))];
+    const ruleIndex = new Map(ruleNames.map((name, i) => [name, i]));
+    const sarifRules = ruleNames.map((name) => {
+      const rule9 = rulesByName.get(name);
+      return {
+        id: name,
+        name: name.replace(/[^A-Za-z0-9]/g, "_"),
+        shortDescription: { text: rule9?.meta.docs.description ?? name },
+        helpUri: rule9?.meta.docs.url
+      };
+    });
+    const sarifResults = diagnostics.map((d) => ({
+      ruleId: d.ruleName,
+      ruleIndex: ruleIndex.get(d.ruleName) ?? 0,
+      level: d.severity === "error" ? "error" : "warning",
+      message: { text: renderMessage(d, rulesByName) },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: d.path, uriBaseId: "%SRCROOT%" },
+            region: { startLine: 1 }
+          }
         }
-        const targetFwd = normalizeRefs(target.frontmatter?.[FORWARD_FIELD]);
-        if (!targetFwd.includes(fileRef)) {
-          context.report({
-            messageId: "missingBackReference",
-            path: target.path,
-            data: {
-              ref,
-              source: file.path,
-              declared: BACKWARD_FIELD,
-              direction: FORWARD_FIELD,
-              expected: fileRef
+      ]
+    }));
+    const sarif = {
+      $schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "madr-lint",
+              informationUri: "https://github.com/knktkc/madr-lint",
+              rules: sarifRules
             }
-          });
+          },
+          results: sarifResults
         }
-      }
+      ]
+    };
+    return JSON.stringify(sarif, null, 2);
+  }
+};
+function escapeGhMessage(s) {
+  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeGhProperty(s) {
+  return escapeGhMessage(s).replace(/,/g, "%2C").replace(/:/g, "%3A");
+}
+var githubReporter = {
+  format(diagnostics, rulesByName, meta) {
+    const lines = [];
+    for (const d of diagnostics) {
+      const level = d.severity === "error" ? "error" : "warning";
+      const file = escapeGhProperty(d.path);
+      const title = escapeGhProperty(d.ruleName);
+      const rendered = renderMessage(d, rulesByName);
+      const message = escapeGhMessage(
+        d.suggestion ? `${rendered} \u2014 ${d.suggestion}` : rendered
+      );
+      const linePart = d.loc ? `,line=${d.loc.line}` : "";
+      lines.push(`::${level} file=${file}${linePart},title=${title}::${message}`);
     }
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.filter((d) => d.severity === "warn").length;
+    const summaryParts = [];
+    if (errors > 0) summaryParts.push(`${errors} ${errors === 1 ? "error" : "errors"}`);
+    if (warnings > 0) summaryParts.push(`${warnings} ${warnings === 1 ? "warning" : "warnings"}`);
+    if (summaryParts.length === 0) summaryParts.push("0 errors, 0 warnings");
+    const baselineHidden = meta?.baselineHidden ?? 0;
+    if (baselineHidden > 0) summaryParts.push(`${baselineHidden} hidden by baseline`);
+    lines.push(summaryParts.join(", "));
+    return lines.join("\n");
   }
 };
-var supersedes_bidirectional_default = rule8;
+var reporters = {
+  text: textReporter,
+  json: jsonReporter,
+  sarif: sarifReporter,
+  github: githubReporter
+};
 
 // src/cli.ts
 function toPosix2(p) {
@@ -1855,9 +2605,9 @@ function toPosix2(p) {
   return p.split(sep2).join("/");
 }
 var pkg = JSON.parse(
-  readFileSync5(new URL("../package.json", import.meta.url), "utf8")
+  readFileSync6(new URL("../package.json", import.meta.url), "utf8")
 );
-var main = defineCommand({
+var main = defineCommand2({
   meta: {
     name: "madr-lint",
     version: pkg.version,
@@ -1908,6 +2658,16 @@ var main = defineCommand({
       type: "string",
       description: "Path to config file, bypassing auto-discovery",
       required: false
+    },
+    fix: {
+      type: "boolean",
+      description: "Apply autofixes in place; exit code reflects remaining problems",
+      default: false
+    },
+    "fix-dry-run": {
+      type: "boolean",
+      description: "Show a diff of the fixes that --fix would apply; write nothing",
+      default: false
     }
   },
   run({ args }) {
@@ -1928,7 +2688,7 @@ var main = defineCommand({
     let configExplicit = false;
     const configArg = args.config;
     if (configArg) {
-      const absConfigPath = resolve3(cwd, configArg);
+      const absConfigPath = resolve5(cwd, configArg);
       try {
         config = loadConfigFromPath(absConfigPath);
         configExplicit = true;
@@ -1973,7 +2733,7 @@ var main = defineCommand({
     const cacheEnabled = (args.cache ?? config.cache) === true;
     const cacheDir = args["cache-dir"] ?? config.cacheLocation;
     const cacheConfig = cacheEnabled ? {
-      dir: resolve3(cwd, cacheDir),
+      dir: resolve5(cwd, cacheDir),
       configHash: computeConfigHash({
         rules: config.rules,
         ignorePatterns: config.ignorePatterns,
@@ -1985,10 +2745,107 @@ var main = defineCommand({
     const updateBaseline = args["update-baseline"] === true;
     const useBaseline = !updateBaseline && args.baseline !== false;
     const baseline = useBaseline ? loadBaseline(baselineFile) : null;
-    if (useBaseline && baseline === null && existsSync5(baselineFile)) {
+    if (useBaseline && baseline === null && existsSync6(baselineFile)) {
       console.error(baselineMalformedWarning());
     }
     const allRulesArray = Object.values(rules_exports);
+    const format = args.format ?? "text";
+    const reportAndExit = (diagnostics, baselineHidden, fixedCount, dryRun, fixDiffs) => {
+      const rulesByName = new Map(
+        allRulesArray.map((r) => [r.meta.name, r])
+      );
+      const reporter = reporters[format];
+      if (!reporter) {
+        console.error(
+          `Unknown --format "${format}". Available: ${Object.keys(reporters).join(", ")}`
+        );
+        process.exit(2);
+      }
+      const warningCount = diagnostics.filter((d) => d.severity === "warn").length;
+      const errorCount = diagnostics.filter((d) => d.severity === "error").length;
+      const overWarningLimit = maxWarnings >= 0 && warningCount > maxWarnings;
+      const reported = args.quiet ? diagnostics.filter((d) => d.severity !== "warn") : diagnostics;
+      const suppressAllClear = format === "text" && reported.length === 0 && overWarningLimit;
+      if (!suppressAllClear) {
+        console.log(
+          reporter.format(reported, rulesByName, {
+            baselineHidden,
+            ...fixedCount !== void 0 ? { fixed: fixedCount } : {},
+            ...fixDiffs !== void 0 ? { fixDiffs } : {}
+          })
+        );
+      }
+      if (format === "text" && baselineHidden > 0) {
+        console.log(baselineHiddenSummary(baselineHidden));
+      }
+      if (format === "text" && fixedCount !== void 0 && fixedCount > 0) {
+        const noun = fixedCount === 1 ? "problem" : "problems";
+        console.log(
+          dryRun ? `${fixedCount} ${noun} fixable (dry run; no files written)` : `Fixed ${fixedCount} ${noun}`
+        );
+      }
+      if (overWarningLimit) {
+        console.error(
+          `madr-lint: ${warningCount} warning(s) found, exceeds --max-warnings ${maxWarnings}`
+        );
+      }
+      process.exit(errorCount > 0 || overWarningLimit ? 1 : 0);
+    };
+    const fixMode = args.fix === true || args["fix-dry-run"] === true;
+    if (fixMode && updateBaseline) {
+      console.error(
+        "madr-lint: --update-baseline cannot be combined with --fix or --fix-dry-run"
+      );
+      process.exit(2);
+    }
+    if (fixMode) {
+      const dryRun = args["fix-dry-run"] === true;
+      let fixResult;
+      try {
+        fixResult = lintAndFix({
+          rules: allRulesArray,
+          ruleSeverity: config.rules,
+          files,
+          cwd,
+          baseline
+        });
+      } catch (err) {
+        if (err instanceof RuleOptionsError) {
+          console.error(`Invalid rule options in config: ${err.message}`);
+          process.exit(2);
+        }
+        throw err;
+      }
+      let fixDiffs;
+      if (dryRun) {
+        const changed = fixResult.files.filter((f) => f.changed);
+        if (format === "text") {
+          for (const f of changed) {
+            process.stdout.write(unifiedDiff(f.path, f.original, f.fixed));
+          }
+        } else if (format === "json") {
+          fixDiffs = changed.map((f) => ({
+            path: f.path,
+            diff: unifiedDiff(f.path, f.original, f.fixed)
+          }));
+        } else {
+          for (const f of changed) {
+            process.stderr.write(unifiedDiff(f.path, f.original, f.fixed));
+          }
+        }
+      } else {
+        for (const f of fixResult.files) {
+          if (f.changed) writeFileSync4(f.absPath, f.fixed, "utf8");
+        }
+      }
+      reportAndExit(
+        fixResult.diagnostics,
+        fixResult.baselineHidden,
+        fixResult.fixed,
+        dryRun,
+        fixDiffs
+      );
+    }
     let result;
     try {
       result = lintFiles({
@@ -2012,40 +2869,13 @@ var main = defineCommand({
       console.log(baselineWriteSummary(built));
       process.exit(0);
     }
-    const rulesByName = new Map(
-      allRulesArray.map((r) => [r.meta.name, r])
-    );
-    const format = args.format ?? "text";
-    const reporter = reporters[format];
-    if (!reporter) {
-      console.error(
-        `Unknown --format "${format}". Available: ${Object.keys(reporters).join(", ")}`
-      );
-      process.exit(2);
-    }
-    const allDiagnostics = result.diagnostics;
-    const warningCount = allDiagnostics.filter((d) => d.severity === "warn").length;
-    const errorCount = allDiagnostics.filter((d) => d.severity === "error").length;
-    const overWarningLimit = maxWarnings >= 0 && warningCount > maxWarnings;
-    const reported = args.quiet ? allDiagnostics.filter((d) => d.severity !== "warn") : allDiagnostics;
-    const suppressAllClear = format === "text" && reported.length === 0 && overWarningLimit;
-    if (!suppressAllClear) {
-      console.log(
-        reporter.format(reported, rulesByName, {
-          baselineHidden: result.baselineHidden
-        })
-      );
-    }
-    if (format === "text" && result.baselineHidden > 0) {
-      console.log(baselineHiddenSummary(result.baselineHidden));
-    }
-    if (overWarningLimit) {
-      console.error(
-        `madr-lint: ${warningCount} warning(s) found, exceeds --max-warnings ${maxWarnings}`
-      );
-    }
-    process.exit(errorCount > 0 || overWarningLimit ? 1 : 0);
+    reportAndExit(result.diagnostics, result.baselineHidden, void 0, false);
   }
 });
-await runMain(main);
+var rawArgs = process.argv.slice(2);
+if (rawArgs[0] === "init") {
+  await runMain(initCommand, { rawArgs: rawArgs.slice(1) });
+} else {
+  await runMain(main);
+}
 //# sourceMappingURL=cli.js.map