madr-lint 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -33,6 +33,14 @@ interface RuleMeta<TOptions = Record<string, unknown>> {
     };
     /** messageId -> template string with {{placeholders}}. */
     messages: Record<string, string>;
+    /**
+     * messageId -> machine-actionable remediation template, parallel to
+     * `messages` and interpolated the same way. Partial: declare an entry only
+     * where a concrete, mechanical fix exists; omit where the fix is inherently
+     * contextual. The runner resolves the entry for a reported messageId into
+     * `Diagnostic.suggestion` (null when absent). See issue #67.
+     */
+    suggestions?: Record<string, string>;
     /** Default options merged with user config. */
     defaultOptions: TOptions;
     /** AJV JSON Schema for options. Validated at runRule time. */
@@ -60,6 +68,19 @@ interface Diagnostic {
     };
     /** Data for placeholder interpolation in messages[messageId]. */
     data?: Record<string, unknown>;
+    /**
+     * Machine-actionable remediation, resolved by the runner at report time from
+     * `rule.meta.suggestions[messageId]` (interpolated with `data`, exactly like
+     * the message). `null` when the rule declares no suggestion for this
+     * messageId. Every runner-produced diagnostic sets this. See issue #67.
+     */
+    suggestion: string | null;
+    /**
+     * The rule's documentation URL (`rule.meta.docs.url`), resolved by the runner
+     * so consumers need not reconstruct it from `ruleName`. `core/internal-error`
+     * diagnostics point at the repository; a rule without a docs URL yields `''`.
+     */
+    docsUrl: string;
 }
 interface RuleContext<TOptions = Record<string, unknown>> {
     /** The file being linted. */
@@ -88,8 +109,8 @@ interface RuleContext<TOptions = Record<string, unknown>> {
     }> | null;
     /** User-merged options for this rule (validated against rule.meta.schema). */
     options: TOptions;
-    /** Emit a diagnostic. */
-    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'path'>): void;
+    /** Emit a diagnostic. `suggestion` / `docsUrl` are resolved by the runner. */
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'path' | 'suggestion' | 'docsUrl'>): void;
 }
 /**
  * Visitor map dispatched during single-pass mdast traversal.
@@ -156,9 +177,9 @@ interface ProjectRuleContext<TOptions = Record<string, unknown>> {
     /**
      * Emit a diagnostic. Unlike per-file rules, project rules MUST set
      * `path` explicitly — the runner cannot infer which file the
-     * diagnostic relates to.
+     * diagnostic relates to. `suggestion` / `docsUrl` are resolved by the runner.
      */
-    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity'>): void;
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'suggestion' | 'docsUrl'>): void;
 }
 /**
  * A cross-file rule. Receives all parsed files at once and reports

package/dist/index.js

@@ -13,6 +13,15 @@ function isProjectRule(rule9) {
   return "check" in rule9;
 }
 
+// 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";
@@ -252,6 +261,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}`);
@@ -309,15 +319,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
         });
       }
@@ -352,6 +368,8 @@ function internalErrorDiagnostic(ruleName, operation, err, path) {
     messageId: "ruleThrew",
     severity: "error",
     path,
+    suggestion: null,
+    docsUrl: INTERNAL_ERROR_DOCS_URL,
     data: {
       rule: ruleName,
       operation,
@@ -426,14 +444,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
         });
       }
@@ -506,6 +530,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"
     },
@@ -598,6 +626,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$"
     },
@@ -677,6 +710,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
   },
@@ -737,6 +773,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
   },
@@ -796,6 +835,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
   },
@@ -872,6 +914,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",
@@ -950,6 +995,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"],
@@ -958,12 +1009,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());
@@ -973,10 +1025,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",
@@ -1026,7 +1074,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
@@ -1063,6 +1119,7 @@ var rule8 = {
             data: {
               ref,
               source: file.path,
+              declared: FORWARD_FIELD,
               direction: BACKWARD_FIELD,
               expected: fileRef
             }
@@ -1087,6 +1144,7 @@ var rule8 = {
             data: {
               ref,
               source: file.path,
+              declared: BACKWARD_FIELD,
               direction: FORWARD_FIELD,
               expected: fileRef
             }