madr-lint 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- [#71](https://github.com/knktkc/madr-lint/pull/71) [`55e7b89`](https://github.com/knktkc/madr-lint/commit/55e7b89a5d1dc6c3109e04b02c082aadd713b701) Thanks [@knktkc](https://github.com/knktkc)! - Diagnostics now carry machine-actionable `suggestion` and `docsUrl` in the json/text/github output ([#67](https://github.com/knktkc/madr-lint/issues/67)). Error feedback is self-contained — expected vs actual plus a concrete fix and a docs link — so agents and humans repair violations without a separate doc lookup.
+
+  - **Rule meta** gains an optional declarative `suggestions` map (messageId → template), interpolated with the diagnostic data exactly like `messages`. Rules stay declarative — no imperative suggestion building. Declare an entry only where a mechanical fix exists; omit where the fix is contextual.
+  - **`Diagnostic`** gains `suggestion: string | null` (null when the rule defines none for that message) and `docsUrl: string` (the rule's `docs.url`; the repository for `core/internal-error`), both resolved by the runner at report time.
+  - **Reporters**: `text` renders an indented `→ <suggestion>` line under a diagnostic and prints the docs URL once per rule per file group (compact — never per diagnostic); `json` adds `suggestion` and `docsUrl` to every result (keys always present); `github` appends ` — <suggestion>` to the annotation message (escaped). `sarif` is unchanged — its `helpUri` already carries the docs URL.
+  - **All 8 rules audited**; suggestions filled where the remediation is mechanical (`required-sections`, `status-enum` missing status, `date-iso8601`, `filename-format`, `no-broken-links`, `no-duplicate-numbering`, `supersedes-bidirectional`) and omitted where contextual (`no-numbering-gap`; `status-enum` invalid status already lists the allowed values).
+  - **Fixed** `supersedes-bidirectional`'s `missingBackReference` message, which named the wrong declared field: it now renders the field the source file actually declares (`supersedes:` vs `superseded-by:`) and states the exact `field: value` back-reference to add.
+  - **Breaking (pre-1.0)**: `Diagnostic` gains two required fields — external code that **constructs** `Diagnostic` values must now supply `suggestion` (`string | null`) and `docsUrl` (`string`); consumers that only read diagnostics are unaffected (the keys are always present). The on-disk cache manifest also gains a schema version (`schemaVersion: 2`; missing/mismatched ⇒ cold), so the first run after upgrading re-lints once instead of serving stale-shape cached diagnostics.
+
+  Resolution is report-time only, so it stays zero-cost on clean files and free on the sub-microsecond hot path.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -15,6 +15,8 @@
 [Getting started](https://knktkc.github.io/madr-lint/guides/getting-started/) ·
 [Rules](https://knktkc.github.io/madr-lint/rules/)
 
+<sub>For AI agents: [llms.txt](https://knktkc.github.io/madr-lint/llms.txt) indexes the docs; [llms-full.txt](https://knktkc.github.io/madr-lint/llms-full.txt) has the full text in one fetch; the [AI agents guide](https://knktkc.github.io/madr-lint/guides/ai-agents/) covers the ready-made [`adopt-madr-lint`](https://github.com/knktkc/madr-lint/blob/main/skills/adopt-madr-lint/SKILL.md) / [`new-adr`](https://github.com/knktkc/madr-lint/blob/main/skills/new-adr/SKILL.md) skills.</sub>
+
 </div>
 
 A fast, configurable linter for [MADR](https://adr.github.io/madr/) (Markdown Architectural Decision Records). It validates the things a plain Markdown linter can't: required sections, a valid status, ISO-8601 dates, filename convention, and cross-file integrity like unique numbering and non-broken links — across MADR **v2, v3, and v4**.

package/dist/cli.js

@@ -152,6 +152,7 @@ function baselineHiddenSummary(hidden) {
 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");
 }
@@ -177,7 +178,12 @@ function loadManifest(path) {
   if (!existsSync2(path)) return null;
   try {
     const data = JSON.parse(readFileSync2(path, "utf8"));
-    if (typeof data.version !== "string" || typeof data.configHash !== "string" || typeof data.files !== "object" || data.files === null) {
+    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;
@@ -327,6 +333,15 @@ 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/parser.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString } from "mdast-util-to-string";
@@ -563,6 +578,7 @@ function getValidator(schema) {
   }
   return validator;
 }
+var INTERNAL_ERROR_DOCS_URL = "https://github.com/knktkc/madr-lint";
 var RuleOptionsError = class extends Error {
   constructor(ruleName, ajvErrors) {
     super(`Invalid options for rule ${ruleName}: ${ajvErrors}`);
@@ -617,15 +633,21 @@ function runRulesOnFile(rules, file, runtime = {}) {
         throw new RuleOptionsError(rule9.meta.name, ajv.errorsText(validator.errors));
       }
     }
+    const ruleName = rule9.meta.name;
+    const suggestions = rule9.meta.suggestions;
+    const docsUrl = rule9.meta.docs.url ?? "";
     const context = new PerFileRuleContext(
       file,
       mergedOptions,
       ensureParsed,
       (d) => {
+        const template = suggestions?.[d.messageId];
         diagnostics.push({
-          ruleName: rule9.meta.name,
+          ruleName,
           severity,
           path: file.path,
+          suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
+          docsUrl,
           ...d
         });
       }
@@ -660,6 +682,8 @@ function internalErrorDiagnostic(ruleName, operation, err, path) {
     messageId: "ruleThrew",
     severity: "error",
     path,
+    suggestion: null,
+    docsUrl: INTERNAL_ERROR_DOCS_URL,
     data: {
       rule: ruleName,
       operation,
@@ -734,14 +758,20 @@ function runRulesOnProject(rules, files, runtime = {}) {
         );
       }
     }
+    const ruleName = rule9.meta.name;
+    const suggestions = rule9.meta.suggestions;
+    const docsUrl = rule9.meta.docs.url ?? "";
     const context = {
       files,
       options: mergedOptions,
       fileExists: runtime.fileExists,
       report(d) {
+        const template = suggestions?.[d.messageId];
         diagnostics.push({
-          ruleName: rule9.meta.name,
+          ruleName,
           severity,
+          suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
+          docsUrl,
           ...d
         });
       }
@@ -784,6 +814,7 @@ function lintFiles(opts) {
       manifest = loaded;
     } else {
       manifest = {
+        schemaVersion: CACHE_SCHEMA_VERSION,
         version: opts.cache.pkgVersion,
         configHash: opts.cache.configHash,
         files: {}
@@ -974,13 +1005,24 @@ var textReporter = {
     }
     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}`));
       }
       lines.push("");
     }
@@ -1003,12 +1045,6 @@ function renderMessage(d, rulesByName) {
   const template = rule9?.meta.messages[d.messageId] ?? d.messageId;
   return interpolate(template, d.data ?? {});
 }
-function interpolate(template, data) {
-  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
-    const v = data[key];
-    return v !== void 0 ? String(v) : `{{${key}}}`;
-  });
-}
 function formatSummary(errors, warnings) {
   const parts = [];
   if (errors > 0) parts.push(`${errors} ${errors === 1 ? "error" : "errors"}`);
@@ -1035,6 +1071,10 @@ var jsonReporter = {
         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 ?? {}
       }))
     };
@@ -1100,7 +1140,10 @@ var githubReporter = {
       const level = d.severity === "error" ? "error" : "warning";
       const file = escapeGhProperty(d.path);
       const title = escapeGhProperty(d.ruleName);
-      const message = escapeGhMessage(renderMessage(d, rulesByName));
+      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}`);
     }
@@ -1180,6 +1223,10 @@ var rule = {
       missingDate: 'Metadata does not contain a "{{field}}" field (checked frontmatter and v2 bold-list)',
       invalidDate: 'Date "{{date}}" is not a valid ISO 8601 calendar date (YYYY-MM-DD)'
     },
+    suggestions: {
+      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"
+    },
     defaultOptions: {
       field: "date"
     },
@@ -1272,6 +1319,11 @@ var rule2 = {
     messages: {
       invalidFilename: 'Filename "{{filename}}" does not match expected pattern "{{expected}}"'
     },
+    suggestions: {
+      // The message already states the expected pattern; the suggestion adds a
+      // concrete, conforming example of the NNNN-kebab-case.md convention.
+      invalidFilename: "rename the file to the NNNN-kebab-case.md convention, e.g. 0001-record-architecture-decisions.md"
+    },
     defaultOptions: {
       pattern: "^[0-9]{4}-[a-z0-9-]+\\.md$"
     },
@@ -1351,6 +1403,9 @@ var rule3 = {
     messages: {
       brokenLink: 'Link to "{{url}}" resolves to "{{resolvedPath}}", which does not exist in the project'
     },
+    suggestions: {
+      brokenLink: "fix the link target or remove the link; relative paths resolve from the ADR file's own directory"
+    },
     defaultOptions: {},
     schema: schema_default3
   },
@@ -1411,6 +1466,9 @@ var rule4 = {
     messages: {
       duplicateNumber: "ADR number {{number}} is used by multiple files: {{paths}}"
     },
+    suggestions: {
+      duplicateNumber: "renumber all but one of these files so each ADR has a unique NNNN- prefix"
+    },
     defaultOptions: {},
     schema: schema_default4
   },
@@ -1470,6 +1528,9 @@ var rule5 = {
     messages: {
       numberingGap: "Numbering gap: missing {{missing}} between ADR-{{from}} and ADR-{{to}}"
     },
+    // No `suggestions`: a gap can be intentional (a rejected or deleted ADR),
+    // and closing it may mean either adding the missing ADR OR renumbering —
+    // the right remediation is contextual, so we omit a suggestion. See #67.
     defaultOptions: {},
     schema: schema_default5
   },
@@ -1546,6 +1607,9 @@ var rule6 = {
     messages: {
       missingSection: 'Missing required section: "{{section}}"'
     },
+    suggestions: {
+      missingSection: 'add a "## {{section}}" heading to the document body'
+    },
     defaultOptions: {
       sections: [
         "Context and Problem Statement",
@@ -1624,6 +1688,12 @@ var rule7 = {
       missingStatus: 'Metadata does not contain a "status" field (checked frontmatter and v2 bold-list)',
       invalidStatus: 'Status "{{status}}" is not one of: {{allowed}}'
     },
+    // No suggestion for invalidStatus: the message already lists the allowed
+    // values (the expected-vs-actual is self-contained), so a suggestion would
+    // only restate it. See issue #67.
+    suggestions: {
+      missingStatus: 'add a "status" field to the frontmatter (for MADR v2, a "* Status: ..." list item) \u2014 allowed values: {{allowed}}'
+    },
     defaultOptions: {
       values: ["proposed", "rejected", "accepted", "deprecated"],
       prefixValues: ["superseded by"],
@@ -1632,12 +1702,13 @@ var rule7 = {
     schema: schema_default7
   },
   create(context) {
+    const { values, prefixValues, caseSensitive } = context.options;
+    const allowed = [...values, ...prefixValues.map((p) => `${p} ...`)];
     const meta = context.metadata;
     if (!meta || typeof meta.status !== "string") {
-      context.report({ messageId: "missingStatus", data: {} });
+      context.report({ messageId: "missingStatus", data: { allowed } });
       return;
     }
-    const { values, prefixValues, caseSensitive } = context.options;
     const status = meta.status;
     const compareStatus = caseSensitive ? status : status.toLowerCase();
     const compareValues = caseSensitive ? values : values.map((v) => v.toLowerCase());
@@ -1647,10 +1718,6 @@ var rule7 = {
       (p) => compareStatus.startsWith(p)
     );
     if (!exactMatch && !prefixMatch) {
-      const allowed = [
-        ...values,
-        ...prefixValues.map((p) => `${p} ...`)
-      ];
       const loc = context.metadataLoc?.status;
       context.report({
         messageId: "invalidStatus",
@@ -1700,7 +1767,15 @@ var rule8 = {
     },
     messages: {
       unknownReference: "Frontmatter `{{direction}}: {{ref}}` references an ADR that does not exist",
-      missingBackReference: "`{{source}}` declares `{{direction}}: {{ref}}`, but `{{ref}}` (this file) does not back-reference it via `{{expected}}`"
+      // `declared` is the field the SOURCE file actually declares;
+      // `direction` is the field THIS file (the diagnostic's path) must add.
+      // They are opposites — rendering `direction` as the declared field
+      // would mislabel the source's frontmatter in both directions.
+      missingBackReference: "`{{source}}` declares `{{declared}}: {{ref}}`, but `{{ref}}` (this file) does not back-reference it via `{{direction}}: {{expected}}`"
+    },
+    suggestions: {
+      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'
     },
     defaultOptions: {},
     schema: schema_default8
@@ -1737,6 +1812,7 @@ var rule8 = {
             data: {
               ref,
               source: file.path,
+              declared: FORWARD_FIELD,
               direction: BACKWARD_FIELD,
               expected: fileRef
             }
@@ -1761,6 +1837,7 @@ var rule8 = {
             data: {
               ref,
               source: file.path,
+              declared: BACKWARD_FIELD,
               direction: FORWARD_FIELD,
               expected: fileRef
             }