madr-lint 0.1.0 → 0.2.0

package/dist/cli.js

@@ -6,14 +6,152 @@ var __export = (target, all) => {
 };
 
 // src/cli.ts
-import { readFileSync as readFileSync4 } from "fs";
+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";
 
-// src/core/cache.ts
-import { createHash } from "crypto";
+// 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";
 function computeContentHash(content) {
   return createHash("sha1").update(content, "utf8").digest("hex");
 }
@@ -33,12 +171,12 @@ function stableStringify(value) {
   return "{" + entries.map(([k, v]) => JSON.stringify(k) + ":" + stableStringify(v)).join(",") + "}";
 }
 function manifestPath(cacheDir) {
-  return join(cacheDir, "manifest.json");
+  return join2(cacheDir, "manifest.json");
 }
 function loadManifest(path) {
-  if (!existsSync(path)) return null;
+  if (!existsSync2(path)) return null;
   try {
-    const data = JSON.parse(readFileSync(path, "utf8"));
+    const data = JSON.parse(readFileSync2(path, "utf8"));
     if (typeof data.version !== "string" || typeof data.configHash !== "string" || typeof data.files !== "object" || data.files === null) {
       return null;
     }
@@ -48,12 +186,12 @@ function loadManifest(path) {
   }
 }
 function saveManifest(path, manifest) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(manifest), "utf8");
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, JSON.stringify(manifest), "utf8");
 }
 
 // src/core/config.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { resolve } from "path";
 import { createJiti } from "jiti";
 
@@ -64,7 +202,7 @@ var recommended = {
   "madr/no-broken-links": "error",
   "madr/no-duplicate-numbering": "error",
   // Convention-only — opt in if your team treats ADR numbering as a
-  // contiguous sequence. See docs/rules/no-numbering-gap.md.
+  // contiguous sequence. See https://knktkc.github.io/madr-lint/rules/no-numbering-gap/.
   "madr/no-numbering-gap": "off",
   "madr/required-sections": "error",
   "madr/status-enum": "error",
@@ -85,12 +223,43 @@ var CONFIG_FILES = [
   "madr-lint.config.mjs",
   "madr-lint.config.cjs"
 ];
+var ConfigFileNotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigFileNotFoundError";
+  }
+};
+function loadConfigFromPath(filePath) {
+  let raw;
+  try {
+    raw = readFileSync3(filePath, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      throw new ConfigFileNotFoundError(`Config file not found: ${filePath}`);
+    }
+    if (code === "EISDIR") {
+      throw new ConfigFileNotFoundError(
+        `Config path is a directory, not a file: ${filePath}`
+      );
+    }
+    throw err;
+  }
+  if (filePath.endsWith(".json")) {
+    const parsed = JSON.parse(raw);
+    return resolveExtends(parsed);
+  }
+  const jiti = createJiti(import.meta.url, { interopDefault: true });
+  const loaded = jiti(filePath);
+  const config = typeof loaded === "object" && loaded !== null && "default" in loaded ? loaded.default : loaded;
+  return resolveExtends(config);
+}
 function loadConfig(cwd) {
   for (const name of CONFIG_FILES) {
     const path = resolve(cwd, name);
-    if (!existsSync2(path)) continue;
+    if (!existsSync3(path)) continue;
     if (name.endsWith(".json")) {
-      const parsed = JSON.parse(readFileSync2(path, "utf8"));
+      const parsed = JSON.parse(readFileSync3(path, "utf8"));
       return resolveExtends(parsed);
     }
     const jiti = createJiti(import.meta.url, { interopDefault: true });
@@ -115,17 +284,17 @@ function resolveExtends(config) {
 }
 
 // src/core/discover.ts
-import { existsSync as existsSync3, readdirSync, statSync } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync4, readdirSync, statSync } from "fs";
+import { join as join3 } from "path";
 function findAdrFiles(target) {
-  if (!existsSync3(target)) return [];
+  if (!existsSync4(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) => join2(e.parentPath, e.name)).toSorted();
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => join3(e.parentPath, e.name)).toSorted();
 }
 
 // src/core/ignore.ts
@@ -152,7 +321,7 @@ function matchesPattern(relativePath, base, pattern) {
 }
 
 // src/core/lint.ts
-import { readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 import { isAbsolute, relative, resolve as resolve2, sep } from "path";
 
 // src/core/runner.ts
@@ -167,20 +336,33 @@ function parseFile(content) {
   const data = matter.data;
   const frontmatter = Object.keys(data).length > 0 ? data : null;
   const ast = fromMarkdown(matter.content);
-  const listMetadata = extractListMetadata(ast);
+  const listResult = extractListMetadataWithLoc(ast);
+  const listMetadata = listResult?.values ?? null;
   let metadata = null;
+  let metadataLoc = listResult && Object.keys(listResult.loc).length > 0 ? { ...listResult.loc } : null;
   if (frontmatter && listMetadata) {
     const frontmatterDefined = {};
     for (const [k, v] of Object.entries(frontmatter)) {
       if (v !== null && v !== void 0) frontmatterDefined[k] = v;
     }
     metadata = { ...listMetadata, ...frontmatterDefined };
+    if (metadataLoc) {
+      for (const k of Object.keys(frontmatterDefined)) delete metadataLoc[k];
+      if (Object.keys(metadataLoc).length === 0) metadataLoc = null;
+    }
   } else if (frontmatter) {
     metadata = frontmatter;
   } else if (listMetadata) {
     metadata = listMetadata;
   }
-  return { frontmatter, listMetadata, metadata, ast, body: matter.content };
+  return {
+    frontmatter,
+    listMetadata,
+    metadata,
+    metadataLoc,
+    ast,
+    body: matter.content
+  };
 }
 var RECOGNIZED_METADATA_KEYS = /* @__PURE__ */ new Set([
   "status",
@@ -190,7 +372,7 @@ var RECOGNIZED_METADATA_KEYS = /* @__PURE__ */ new Set([
   "consulted",
   "informed"
 ]);
-function extractListMetadata(ast) {
+function extractListMetadataWithLoc(ast) {
   let firstList = null;
   for (const child of ast.children) {
     if (child.type === "heading") {
@@ -205,17 +387,20 @@ function extractListMetadata(ast) {
     break;
   }
   if (!firstList) return null;
-  const result = {};
+  const values = {};
+  const loc = {};
   for (const item of firstList.children) {
     const pair = extractListItemKV(item);
-    if (pair && !(pair.key in result)) {
-      result[pair.key] = pair.value;
+    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 };
     }
   }
-  const hasRecognizedKey = Object.keys(result).some(
+  const hasRecognizedKey = Object.keys(values).some(
     (k) => RECOGNIZED_METADATA_KEYS.has(k)
   );
-  return hasRecognizedKey ? result : null;
+  return hasRecognizedKey ? { values, loc } : null;
 }
 var KEY_PATTERN = /^[A-Za-z][A-Za-z0-9 \-_]*$/;
 var SEPARATOR_PATTERN = /^\s*:\s*/;
@@ -255,6 +440,118 @@ function extractListItemKV(item) {
   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);
+    }
+  }
+  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;
+  const nextNonBlankLine = (after) => {
+    lines ??= body.split("\n");
+    for (let ln = after + 1; ln <= lines.length; ln++) {
+      if ((lines[ln - 1] ?? "").trim() !== "") return ln;
+    }
+    return null;
+  };
+  const index = {
+    fileDisableAll: false,
+    fileDisableRules: /* @__PURE__ */ new Set(),
+    ranged: [],
+    nextLine: /* @__PURE__ */ new Map()
+  };
+  for (const directive of all) {
+    switch (directive.kind) {
+      case "disable-file": {
+        if (directive.rules === null) index.fileDisableAll = true;
+        else for (const rule9 of directive.rules) index.fileDisableRules.add(rule9);
+        break;
+      }
+      case "disable":
+      case "enable": {
+        index.ranged.push(directive);
+        break;
+      }
+      case "disable-next-line": {
+        const target = nextNonBlankLine(directive.line);
+        if (target === null) break;
+        let entry = index.nextLine.get(target);
+        if (!entry) {
+          entry = { all: false, rules: /* @__PURE__ */ new Set() };
+          index.nextLine.set(target, entry);
+        }
+        if (directive.rules === null) entry.all = true;
+        else for (const rule9 of directive.rules) entry.rules.add(rule9);
+        break;
+      }
+    }
+  }
+  index.ranged.sort((a, b) => a.line - b.line);
+  return index;
+}
+function directiveApplies(directive, ruleName) {
+  return directive.rules === null || directive.rules.includes(ruleName);
+}
+function isSuppressed(index, ruleName, line) {
+  if (index.fileDisableAll || index.fileDisableRules.has(ruleName)) return true;
+  if (line !== void 0) {
+    const next = index.nextLine.get(line);
+    if (next && (next.all || next.rules.has(ruleName))) return true;
+  }
+  const ceiling = line ?? Number.POSITIVE_INFINITY;
+  let disabled = false;
+  for (const directive of index.ranged) {
+    if (directive.line > ceiling) break;
+    if (directiveApplies(directive, ruleName)) {
+      disabled = directive.kind === "disable";
+    }
+  }
+  return disabled;
+}
+function filterSuppressed(diagnostics, index) {
+  return diagnostics.filter((d) => {
+    if (d.ruleName === INTERNAL_ERROR_RULE_NAME) return true;
+    return !isSuppressed(index, d.ruleName, d.loc?.line);
+  });
+}
+
 // src/core/runner.ts
 var ajv = new Ajv({ strict: true, allErrors: true });
 var validatorCache = /* @__PURE__ */ new WeakMap();
@@ -266,7 +563,6 @@ function getValidator(schema) {
   }
   return validator;
 }
-var INTERNAL_ERROR_RULE_NAME = "core/internal-error";
 var RuleOptionsError = class extends Error {
   constructor(ruleName, ajvErrors) {
     super(`Invalid options for rule ${ruleName}: ${ajvErrors}`);
@@ -277,6 +573,27 @@ var RuleOptionsError = class extends Error {
   ruleName;
   ajvErrors;
 };
+var PerFileRuleContext = class {
+  file;
+  options;
+  report;
+  ensureParsed;
+  constructor(file, options, ensureParsed, report) {
+    this.file = file;
+    this.options = options;
+    this.ensureParsed = ensureParsed;
+    this.report = report;
+  }
+  get frontmatter() {
+    return this.ensureParsed().frontmatter;
+  }
+  get metadata() {
+    return this.ensureParsed().metadata;
+  }
+  get metadataLoc() {
+    return this.ensureParsed().metadataLoc;
+  }
+};
 function runRulesOnFile(rules, file, runtime = {}) {
   const diagnostics = [];
   const severity = runtime.severity ?? "error";
@@ -300,16 +617,11 @@ function runRulesOnFile(rules, file, runtime = {}) {
         throw new RuleOptionsError(rule9.meta.name, ajv.errorsText(validator.errors));
       }
     }
-    const context = {
+    const context = new PerFileRuleContext(
       file,
-      get frontmatter() {
-        return ensureParsed().frontmatter;
-      },
-      get metadata() {
-        return ensureParsed().metadata;
-      },
-      options: mergedOptions,
-      report(d) {
+      mergedOptions,
+      ensureParsed,
+      (d) => {
         diagnostics.push({
           ruleName: rule9.meta.name,
           severity,
@@ -317,7 +629,7 @@ function runRulesOnFile(rules, file, runtime = {}) {
           ...d
         });
       }
-    };
+    );
     let listeners;
     try {
       listeners = rule9.create(context);
@@ -336,7 +648,11 @@ function runRulesOnFile(rules, file, runtime = {}) {
   if (hasASTRule) {
     walk(ensureParsed().ast, enterMap, exitMap);
   }
-  return diagnostics;
+  if (diagnostics.length === 0) return diagnostics;
+  if (!file.content.includes(DIRECTIVE_PREFIX)) return diagnostics;
+  const { ast, body } = ensureParsed();
+  const directives = collectDirectives(ast, body);
+  return directives ? filterSuppressed(diagnostics, directives) : diagnostics;
 }
 function internalErrorDiagnostic(ruleName, operation, err, path) {
   return {
@@ -394,6 +710,7 @@ function buildProjectFile(file) {
   return {
     path: file.path,
     content: file.content,
+    body: parsed.body,
     frontmatter: parsed.frontmatter,
     metadata: parsed.metadata,
     ast: parsed.ast
@@ -440,11 +757,6 @@ function runRulesOnProject(rules, files, runtime = {}) {
   return diagnostics;
 }
 
-// src/core/types.ts
-function isProjectRule(rule9) {
-  return "check" in rule9;
-}
-
 // src/core/lint.ts
 function toPosix(p) {
   if (sep === "/") return p;
@@ -454,7 +766,7 @@ function lintFiles(opts) {
   const allDiagnostics = [];
   const fileEntries = opts.files.map((absolutePath) => ({
     relativePath: toPosix(relative(opts.cwd, absolutePath)),
-    content: readFileSync3(absolutePath, "utf8")
+    content: readFileSync4(absolutePath, "utf8")
   }));
   const perFileRules = [];
   const projectRules = [];
@@ -545,8 +857,9 @@ function lintFiles(opts) {
       if (sev === "error") errorRules.push(rule9);
       else if (sev === "warn") warnRules.push(rule9);
     }
+    const projectDiagnostics = [];
     if (errorRules.length > 0) {
-      allDiagnostics.push(
+      projectDiagnostics.push(
         ...runRulesOnProject(errorRules, projectFiles, {
           severity: "error",
           fileExists,
@@ -555,7 +868,7 @@ function lintFiles(opts) {
       );
     }
     if (warnRules.length > 0) {
-      allDiagnostics.push(
+      projectDiagnostics.push(
         ...runRulesOnProject(warnRules, projectFiles, {
           severity: "warn",
           fileExists,
@@ -563,14 +876,27 @@ function lintFiles(opts) {
         })
       );
     }
+    allDiagnostics.push(
+      ...filterSuppressedProjectDiagnostics(projectDiagnostics, projectFiles)
+    );
   }
   if (manifest && opts.cache) {
     saveManifest(manifestPath(opts.cache.dir), manifest);
   }
+  if (!opts.baseline) {
+    return {
+      filesChecked: opts.files.length,
+      filesFromCache,
+      diagnostics: allDiagnostics,
+      baselineHidden: 0
+    };
+  }
+  const applied = applyBaseline(allDiagnostics, opts.baseline);
   return {
     filesChecked: opts.files.length,
     filesFromCache,
-    diagnostics: allDiagnostics
+    diagnostics: applied.kept,
+    baselineHidden: applied.hidden
   };
 }
 function runPerFileRulesForFile(perFileRules, ruleSeverity, optionsByRule, file) {
@@ -605,6 +931,25 @@ function runPerFileRulesForFile(perFileRules, ruleSeverity, optionsByRule, file)
   }
   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;
@@ -621,6 +966,8 @@ function extractOptionsByRule(ruleSeverity) {
 // 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.");
@@ -669,7 +1016,7 @@ function formatSummary(errors, warnings) {
   return parts.join(", ");
 }
 var jsonReporter = {
-  format(diagnostics, rulesByName) {
+  format(diagnostics, rulesByName, meta) {
     const errors = diagnostics.filter((d) => d.severity === "error").length;
     const warnings = diagnostics.filter((d) => d.severity === "warn").length;
     const payload = {
@@ -677,7 +1024,10 @@ var jsonReporter = {
       summary: {
         total: diagnostics.length,
         errors,
-        warnings
+        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,
@@ -737,10 +1087,40 @@ var sarifReporter = {
     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 message = escapeGhMessage(renderMessage(d, rulesByName));
+      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 reporters = {
   text: textReporter,
   json: jsonReporter,
-  sarif: sarifReporter
+  sarif: sarifReporter,
+  github: githubReporter
 };
 
 // src/rules/index.ts
@@ -793,7 +1173,7 @@ var rule = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Validate that ADR `date` (frontmatter or v2 bold-list) is a valid ISO 8601 calendar date (YYYY-MM-DD)",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/date-iso8601.md",
+      url: "https://knktkc.github.io/madr-lint/rules/date-iso8601/",
       recommended: true
     },
     messages: {
@@ -825,8 +1205,10 @@ var rule = {
       return;
     }
     if (!isValidIso8601Date(dateStr)) {
+      const loc = context.metadataLoc?.[fieldName];
       context.report({
         messageId: "invalidDate",
+        ...loc ? { loc } : {},
         data: { date: dateStr }
       });
     }
@@ -884,7 +1266,7 @@ var rule2 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Enforce ADR filename convention NNNN-kebab-case.md",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/filename-format.md",
+      url: "https://knktkc.github.io/madr-lint/rules/filename-format/",
       recommended: true
     },
     messages: {
@@ -910,7 +1292,7 @@ var rule2 = {
 var filename_format_default = rule2;
 
 // src/rules/no-broken-links/index.ts
-import { dirname as dirname2, posix } from "path";
+import { dirname as dirname3, posix } from "path";
 
 // src/rules/no-broken-links/schema.json
 var schema_default3 = {
@@ -963,7 +1345,7 @@ var rule3 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Relative-path Markdown links must resolve to an existing file in the project",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/no-broken-links.md",
+      url: "https://knktkc.github.io/madr-lint/rules/no-broken-links/",
       recommended: true
     },
     messages: {
@@ -985,13 +1367,15 @@ var rule3 = {
         if (isExternalOrAnchor(url)) continue;
         const pathOnly = safeDecode(stripAnchorAndQuery(url));
         if (pathOnly === "") continue;
-        const fileDir = dirname2(file.path);
+        const fileDir = dirname3(file.path);
         const resolvedPath = resolveRelative(fileDir, pathOnly);
         const exists = knownPaths.has(resolvedPath) || (context.fileExists?.(resolvedPath) ?? false);
         if (!exists) {
+          const start = link.position?.start;
           context.report({
             messageId: "brokenLink",
             path: file.path,
+            ...start ? { loc: { line: start.line, column: start.column } } : {},
             data: { url, resolvedPath }
           });
         }
@@ -1021,7 +1405,7 @@ var rule4 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "No two ADRs share the same NNNN- number prefix",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/no-duplicate-numbering.md",
+      url: "https://knktkc.github.io/madr-lint/rules/no-duplicate-numbering/",
       recommended: true
     },
     messages: {
@@ -1080,7 +1464,7 @@ var rule5 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Detect gaps in ADR numbering (e.g. 0001 and 0003 exist but 0002 is missing). Convention-only; default off.",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/no-numbering-gap.md",
+      url: "https://knktkc.github.io/madr-lint/rules/no-numbering-gap/",
       recommended: false
     },
     messages: {
@@ -1156,7 +1540,7 @@ var rule6 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Enforce that ADRs contain required heading sections",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/required-sections.md",
+      url: "https://knktkc.github.io/madr-lint/rules/required-sections/",
       recommended: true
     },
     messages: {
@@ -1233,7 +1617,7 @@ var rule7 = {
     versionCompat: ["v2", "v3", "v4"],
     docs: {
       description: "Validate that ADR `status` (frontmatter or v2 bold-list) is in the allowed enum",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/status-enum.md",
+      url: "https://knktkc.github.io/madr-lint/rules/status-enum/",
       recommended: true
     },
     messages: {
@@ -1267,8 +1651,10 @@ var rule7 = {
         ...values,
         ...prefixValues.map((p) => `${p} ...`)
       ];
+      const loc = context.metadataLoc?.status;
       context.report({
         messageId: "invalidStatus",
+        ...loc ? { loc } : {},
         data: { status, allowed }
       });
     }
@@ -1309,7 +1695,7 @@ var rule8 = {
     versionCompat: ["v3", "v4"],
     docs: {
       description: "Frontmatter `supersedes` and `superseded-by` must reference each other bidirectionally",
-      url: "https://github.com/knktkc/madr-lint/blob/main/docs/rules/supersedes-bidirectional.md",
+      url: "https://knktkc.github.io/madr-lint/rules/supersedes-bidirectional/",
       recommended: true
     },
     messages: {
@@ -1392,7 +1778,7 @@ function toPosix2(p) {
   return p.split(sep2).join("/");
 }
 var pkg = JSON.parse(
-  readFileSync4(new URL("../package.json", import.meta.url), "utf8")
+  readFileSync5(new URL("../package.json", import.meta.url), "utf8")
 );
 var main = defineCommand({
   meta: {
@@ -1418,14 +1804,71 @@ var main = defineCommand({
     },
     format: {
       type: "string",
-      description: "Reporter format: text (default), json, or sarif",
+      description: "Reporter format: text (default), json, sarif, or github",
       default: "text"
+    },
+    baseline: {
+      type: "boolean",
+      description: "Subtract .madr-lint/baseline.json when present (use --no-baseline to ignore it)",
+      default: true
+    },
+    "update-baseline": {
+      type: "boolean",
+      description: "Rewrite .madr-lint/baseline.json from a full lint, then exit 0",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Report errors only; suppress warnings from output",
+      default: false
+    },
+    "max-warnings": {
+      type: "string",
+      description: "Exit 1 when warning count exceeds n. n=0 means any warning fails. Negative = no limit.",
+      required: false
+    },
+    config: {
+      type: "string",
+      description: "Path to config file, bypassing auto-discovery",
+      required: false
     }
   },
   run({ args }) {
     const cwd = process.cwd();
-    let config = loadConfig(cwd);
-    if (Object.keys(config.rules).length === 0) {
+    let maxWarnings = -1;
+    const rawMaxWarnings = args["max-warnings"];
+    if (rawMaxWarnings !== void 0) {
+      const parsed = Number(rawMaxWarnings);
+      if (rawMaxWarnings.trim() === "" || !Number.isInteger(parsed)) {
+        console.error(
+          `Invalid --max-warnings "${rawMaxWarnings}": must be an integer.`
+        );
+        process.exit(2);
+      }
+      maxWarnings = parsed;
+    }
+    let config;
+    let configExplicit = false;
+    const configArg = args.config;
+    if (configArg) {
+      const absConfigPath = resolve3(cwd, configArg);
+      try {
+        config = loadConfigFromPath(absConfigPath);
+        configExplicit = true;
+      } catch (err) {
+        if (err instanceof ConfigFileNotFoundError) {
+          console.error(err.message);
+        } else {
+          console.error(
+            `Failed to load config "${configArg}": ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        process.exit(2);
+      }
+    } else {
+      config = loadConfig(cwd);
+    }
+    if (!configExplicit && Object.keys(config.rules).length === 0) {
       config = resolveExtends({ extends: ["madr-lint:recommended"] });
     }
     const positionals = args._ ?? [];
@@ -1461,6 +1904,13 @@ var main = defineCommand({
       }),
       pkgVersion: pkg.version
     } : null;
+    const baselineFile = baselinePath(cwd);
+    const updateBaseline = args["update-baseline"] === true;
+    const useBaseline = !updateBaseline && args.baseline !== false;
+    const baseline = useBaseline ? loadBaseline(baselineFile) : null;
+    if (useBaseline && baseline === null && existsSync5(baselineFile)) {
+      console.error(baselineMalformedWarning());
+    }
     const allRulesArray = Object.values(rules_exports);
     let result;
     try {
@@ -1469,7 +1919,8 @@ var main = defineCommand({
         ruleSeverity: config.rules,
         files,
         cwd,
-        cache: cacheConfig
+        cache: cacheConfig,
+        baseline
       });
     } catch (err) {
       if (err instanceof RuleOptionsError) {
@@ -1478,6 +1929,12 @@ var main = defineCommand({
       }
       throw err;
     }
+    if (updateBaseline) {
+      const built = buildBaseline(result.diagnostics);
+      writeBaseline(baselineFile, built);
+      console.log(baselineWriteSummary(built));
+      process.exit(0);
+    }
     const rulesByName = new Map(
       allRulesArray.map((r) => [r.meta.name, r])
     );
@@ -1489,11 +1946,28 @@ var main = defineCommand({
       );
       process.exit(2);
     }
-    console.log(reporter.format(result.diagnostics, rulesByName));
-    const errorCount = result.diagnostics.filter(
-      (d) => d.severity === "error"
-    ).length;
-    process.exit(errorCount > 0 ? 1 : 0);
+    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);
   }
 });
 await runMain(main);