madr-lint 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -4,28 +4,23 @@ var __export = (target, all) => {
4
4
  __defProp(target, name, { get: all[name], enumerable: true });
5
5
  };
6
6
 
7
- // src/core/runner.ts
8
- import Ajv from "ajv";
9
-
10
- // src/core/types.ts
11
- var INTERNAL_ERROR_RULE_NAME = "core/internal-error";
12
- function isProjectRule(rule9) {
13
- return "check" in rule9;
14
- }
15
-
16
7
  // src/core/parser.ts
17
8
  import { fromMarkdown } from "mdast-util-from-markdown";
18
9
  import { toString } from "mdast-util-to-string";
19
10
  import grayMatter from "gray-matter";
11
+ function frontmatterOffset(content) {
12
+ return content.length - grayMatter(content).content.length;
13
+ }
20
14
  function parseFile(content) {
21
15
  const matter = grayMatter(content);
22
16
  const data = matter.data;
23
17
  const frontmatter = Object.keys(data).length > 0 ? data : null;
24
18
  const ast = fromMarkdown(matter.content);
25
- const listResult = extractListMetadataWithLoc(ast);
19
+ const listResult = extractListMetadataWithLoc(ast, matter.content);
26
20
  const listMetadata = listResult?.values ?? null;
27
21
  let metadata = null;
28
22
  let metadataLoc = listResult && Object.keys(listResult.loc).length > 0 ? { ...listResult.loc } : null;
23
+ let metadataValueLoc = listResult && Object.keys(listResult.valueOffsets).length > 0 ? { ...listResult.valueOffsets } : null;
29
24
  if (frontmatter && listMetadata) {
30
25
  const frontmatterDefined = {};
31
26
  for (const [k, v] of Object.entries(frontmatter)) {
@@ -36,6 +31,10 @@ function parseFile(content) {
36
31
  for (const k of Object.keys(frontmatterDefined)) delete metadataLoc[k];
37
32
  if (Object.keys(metadataLoc).length === 0) metadataLoc = null;
38
33
  }
34
+ if (metadataValueLoc) {
35
+ for (const k of Object.keys(frontmatterDefined)) delete metadataValueLoc[k];
36
+ if (Object.keys(metadataValueLoc).length === 0) metadataValueLoc = null;
37
+ }
39
38
  } else if (frontmatter) {
40
39
  metadata = frontmatter;
41
40
  } else if (listMetadata) {
@@ -46,6 +45,7 @@ function parseFile(content) {
46
45
  listMetadata,
47
46
  metadata,
48
47
  metadataLoc,
48
+ metadataValueLoc,
49
49
  ast,
50
50
  body: matter.content
51
51
  };
@@ -61,7 +61,7 @@ var RECOGNIZED_METADATA_KEYS = /* @__PURE__ */ new Set([
61
61
  function extractListMetadata(ast) {
62
62
  return extractListMetadataWithLoc(ast)?.values ?? null;
63
63
  }
64
- function extractListMetadataWithLoc(ast) {
64
+ function extractListMetadataWithLoc(ast, body) {
65
65
  let firstList = null;
66
66
  for (const child of ast.children) {
67
67
  if (child.type === "heading") {
@@ -78,18 +78,22 @@ function extractListMetadataWithLoc(ast) {
78
78
  if (!firstList) return null;
79
79
  const values = {};
80
80
  const loc = {};
81
+ const valueOffsets = {};
81
82
  for (const item of firstList.children) {
82
83
  const pair = extractListItemKV(item);
83
84
  if (pair && !(pair.key in values)) {
84
85
  values[pair.key] = pair.value;
85
86
  const start = item.position?.start;
86
87
  if (start) loc[pair.key] = { line: start.line, column: start.column };
88
+ if (body !== void 0 && pair.valueOffset && body.slice(pair.valueOffset.start, pair.valueOffset.end) === pair.value) {
89
+ valueOffsets[pair.key] = pair.valueOffset;
90
+ }
87
91
  }
88
92
  }
89
93
  const hasRecognizedKey = Object.keys(values).some(
90
94
  (k) => RECOGNIZED_METADATA_KEYS.has(k)
91
95
  );
92
- return hasRecognizedKey ? { values, loc } : null;
96
+ return hasRecognizedKey ? { values, loc, valueOffsets } : null;
93
97
  }
94
98
  var KEY_PATTERN = /^[A-Za-z][A-Za-z0-9 \-_]*$/;
95
99
  var SEPARATOR_PATTERN = /^\s*:\s*/;
@@ -113,22 +117,235 @@ function extractListItemKV(item) {
113
117
  const valueTail = paragraph.children.slice(2).map((n) => toString(n)).join("");
114
118
  const value = (valueHead + valueTail).trim();
115
119
  if (value === "") return null;
116
- return { key: normalizeKey(keyNode.value), value };
120
+ let valueOffset;
121
+ const sepStart = sep.position?.start.offset;
122
+ if (paragraph.children.length === 2 && typeof sepStart === "number" && valueHead !== "") {
123
+ const sepMatch = SEPARATOR_PATTERN.exec(sep.value);
124
+ const vStart = sepStart + (sepMatch ? sepMatch[0].length : 0);
125
+ valueOffset = { start: vStart, end: vStart + value.length };
126
+ }
127
+ return { key: normalizeKey(keyNode.value), value, valueOffset };
117
128
  }
118
129
  if (first.type === "text") {
119
130
  const colonIdx = first.value.indexOf(":");
120
131
  if (colonIdx === -1) return null;
121
132
  const rawKey = first.value.slice(0, colonIdx);
122
133
  if (!KEY_PATTERN.test(rawKey)) return null;
123
- const valueHead = first.value.slice(colonIdx + 1).replace(/^\s+/, "");
134
+ const afterColon = first.value.slice(colonIdx + 1);
135
+ const valueHead = afterColon.replace(/^\s+/, "");
124
136
  const valueTail = paragraph.children.slice(1).map((n) => toString(n)).join("");
125
137
  const value = (valueHead + valueTail).trim();
126
138
  if (value === "") return null;
127
- return { key: normalizeKey(rawKey), value };
139
+ let valueOffset;
140
+ const nodeStart = first.position?.start.offset;
141
+ if (paragraph.children.length === 1 && typeof nodeStart === "number" && valueHead !== "") {
142
+ const leadingWs = afterColon.length - valueHead.length;
143
+ const vStart = nodeStart + colonIdx + 1 + leadingWs;
144
+ valueOffset = { start: vStart, end: vStart + value.length };
145
+ }
146
+ return { key: normalizeKey(rawKey), value, valueOffset };
128
147
  }
129
148
  return null;
130
149
  }
131
150
 
151
+ // src/core/fix.ts
152
+ var MAX_FIX_PASSES = 10;
153
+ function makeFixer(base) {
154
+ const shift = (n) => n + base;
155
+ return {
156
+ replaceRange(range, text) {
157
+ return { range: [shift(range[0]), shift(range[1])], text };
158
+ },
159
+ insertAt(offset, text) {
160
+ const at = shift(offset);
161
+ return { range: [at, at], text };
162
+ },
163
+ remove(range) {
164
+ return { range: [shift(range[0]), shift(range[1])], text: "" };
165
+ }
166
+ };
167
+ }
168
+ function applyEdits(content, edits) {
169
+ return applyEditsCounted(content, edits).text;
170
+ }
171
+ function applyEditsCounted(content, edits) {
172
+ const valid = edits.filter((e) => {
173
+ const [start, end] = e.range;
174
+ return Number.isInteger(start) && Number.isInteger(end) && start >= 0 && end >= start && end <= content.length;
175
+ });
176
+ const sorted = valid.toSorted(
177
+ (a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1]
178
+ );
179
+ let out = "";
180
+ let cursor = 0;
181
+ let applied = 0;
182
+ for (const edit of sorted) {
183
+ const [start, end] = edit.range;
184
+ if (start < cursor) continue;
185
+ out += content.slice(cursor, start) + edit.text;
186
+ cursor = end;
187
+ applied++;
188
+ }
189
+ return { text: out + content.slice(cursor), applied };
190
+ }
191
+ function collectFixes(diagnostics, content) {
192
+ const fixer = makeFixer(frontmatterOffset(content));
193
+ const edits = [];
194
+ for (const d of diagnostics) {
195
+ if (!d.fix) continue;
196
+ const result = d.fix(fixer);
197
+ if (result === null) continue;
198
+ if (Array.isArray(result)) edits.push(...result);
199
+ else edits.push(result);
200
+ }
201
+ return edits;
202
+ }
203
+ function collectProjectFixes(diagnostics, contentByPath) {
204
+ const fixer = makeFixer(0);
205
+ const byPath = /* @__PURE__ */ new Map();
206
+ for (const d of diagnostics) {
207
+ if (!d.fix) continue;
208
+ if (byPath.has(d.path)) continue;
209
+ if (contentByPath(d.path) === void 0) continue;
210
+ const result = d.fix(fixer);
211
+ if (result === null) continue;
212
+ byPath.set(d.path, Array.isArray(result) ? [...result] : [result]);
213
+ }
214
+ return byPath;
215
+ }
216
+ function fixFileContent(originalContent, lint, maxPasses = MAX_FIX_PASSES) {
217
+ let content = originalContent;
218
+ let passes = 0;
219
+ let applied = 0;
220
+ for (; ; ) {
221
+ const diagnostics = lint(content);
222
+ const done = () => ({
223
+ fixedContent: content,
224
+ remaining: diagnostics,
225
+ changed: content !== originalContent,
226
+ passes,
227
+ applied
228
+ });
229
+ if (passes >= maxPasses) return done();
230
+ const edits = collectFixes(diagnostics, content);
231
+ if (edits.length === 0) return done();
232
+ const { text: next, applied: landed } = applyEditsCounted(content, edits);
233
+ if (next === content) return done();
234
+ applied += landed;
235
+ content = next;
236
+ passes++;
237
+ }
238
+ }
239
+ var CONTEXT = 3;
240
+ function unifiedDiff(path, before, after) {
241
+ if (before === after) return "";
242
+ const a = splitLines(before);
243
+ const b = splitLines(after);
244
+ const ops = diffLines(a, b);
245
+ const hunks = groupHunks(ops);
246
+ if (hunks.length === 0) return "";
247
+ const lines = [`--- a/${path}`, `+++ b/${path}`];
248
+ for (const hunk of hunks) lines.push(...renderHunk(hunk));
249
+ return lines.join("\n") + "\n";
250
+ }
251
+ function splitLines(text) {
252
+ if (text === "") return [];
253
+ const parts = text.split("\n");
254
+ if (parts[parts.length - 1] === "") parts.pop();
255
+ return parts;
256
+ }
257
+ function diffLines(a, b) {
258
+ const n = a.length;
259
+ const m = b.length;
260
+ const lcs = Array.from(
261
+ { length: n + 1 },
262
+ () => Array.from({ length: m + 1 }).fill(0)
263
+ );
264
+ for (let i2 = n - 1; i2 >= 0; i2--) {
265
+ for (let j2 = m - 1; j2 >= 0; j2--) {
266
+ lcs[i2][j2] = a[i2] === b[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
267
+ }
268
+ }
269
+ const ops = [];
270
+ let i = 0;
271
+ let j = 0;
272
+ while (i < n && j < m) {
273
+ if (a[i] === b[j]) {
274
+ ops.push({ kind: "eq", text: a[i] });
275
+ i++;
276
+ j++;
277
+ } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
278
+ ops.push({ kind: "del", text: a[i] });
279
+ i++;
280
+ } else {
281
+ ops.push({ kind: "ins", text: b[j] });
282
+ j++;
283
+ }
284
+ }
285
+ while (i < n) ops.push({ kind: "del", text: a[i++] });
286
+ while (j < m) ops.push({ kind: "ins", text: b[j++] });
287
+ return ops;
288
+ }
289
+ function groupHunks(ops) {
290
+ const changeIdx = [];
291
+ ops.forEach((op, idx) => {
292
+ if (op.kind !== "eq") changeIdx.push(idx);
293
+ });
294
+ if (changeIdx.length === 0) return [];
295
+ const windows = [];
296
+ for (const idx of changeIdx) {
297
+ const start = Math.max(0, idx - CONTEXT);
298
+ const end = Math.min(ops.length - 1, idx + CONTEXT);
299
+ const last = windows[windows.length - 1];
300
+ if (last && start <= last[1] + 1) last[1] = Math.max(last[1], end);
301
+ else windows.push([start, end]);
302
+ }
303
+ const hunks = [];
304
+ for (const [start, end] of windows) {
305
+ let aLine = 1;
306
+ let bLine = 1;
307
+ for (let k = 0; k < start; k++) {
308
+ if (ops[k].kind !== "ins") aLine++;
309
+ if (ops[k].kind !== "del") bLine++;
310
+ }
311
+ const hunkOps = ops.slice(start, end + 1);
312
+ let aCount = 0;
313
+ let bCount = 0;
314
+ for (const op of hunkOps) {
315
+ if (op.kind !== "ins") aCount++;
316
+ if (op.kind !== "del") bCount++;
317
+ }
318
+ hunks.push({ aStart: aLine, aCount, bStart: bLine, bCount, ops: hunkOps });
319
+ }
320
+ return hunks;
321
+ }
322
+ function renderHunk(hunk) {
323
+ const header = `@@ -${hunk.aStart},${hunk.aCount} +${hunk.bStart},${hunk.bCount} @@`;
324
+ const body = hunk.ops.map((op) => {
325
+ const prefix = op.kind === "eq" ? " " : op.kind === "del" ? "-" : "+";
326
+ return `${prefix}${op.text}`;
327
+ });
328
+ return [header, ...body];
329
+ }
330
+
331
+ // src/core/runner.ts
332
+ import Ajv from "ajv";
333
+
334
+ // src/core/types.ts
335
+ var INTERNAL_ERROR_RULE_NAME = "core/internal-error";
336
+ function isProjectRule(rule9) {
337
+ return "check" in rule9;
338
+ }
339
+
340
+ // src/core/interpolate.ts
341
+ function interpolate(template, data) {
342
+ if (!template.includes("{{")) return template;
343
+ return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
344
+ const v = data[key];
345
+ return v !== void 0 ? String(v) : `{{${key}}}`;
346
+ });
347
+ }
348
+
132
349
  // src/core/suppression.ts
133
350
  var DIRECTIVE_KINDS = /* @__PURE__ */ new Set([
134
351
  "disable-file",
@@ -252,6 +469,7 @@ function getValidator(schema) {
252
469
  }
253
470
  return validator;
254
471
  }
472
+ var INTERNAL_ERROR_DOCS_URL = "https://github.com/knktkc/madr-lint";
255
473
  var RuleOptionsError = class extends Error {
256
474
  constructor(ruleName, ajvErrors) {
257
475
  super(`Invalid options for rule ${ruleName}: ${ajvErrors}`);
@@ -282,6 +500,9 @@ var PerFileRuleContext = class {
282
500
  get metadataLoc() {
283
501
  return this.ensureParsed().metadataLoc;
284
502
  }
503
+ get metadataValueLoc() {
504
+ return this.ensureParsed().metadataValueLoc;
505
+ }
285
506
  };
286
507
  function runRule(rule9, file, runtime = {}) {
287
508
  return runRulesOnFile([rule9], file, runtime);
@@ -309,15 +530,29 @@ function runRulesOnFile(rules, file, runtime = {}) {
309
530
  throw new RuleOptionsError(rule9.meta.name, ajv.errorsText(validator.errors));
310
531
  }
311
532
  }
533
+ const ruleName = rule9.meta.name;
534
+ const suggestions = rule9.meta.suggestions;
535
+ const docsUrl = rule9.meta.docs.url ?? "";
536
+ const fixableRule = rule9.meta.fixable === "code";
312
537
  const context = new PerFileRuleContext(
313
538
  file,
314
539
  mergedOptions,
315
540
  ensureParsed,
316
541
  (d) => {
542
+ const template = suggestions?.[d.messageId];
543
+ const hasFix = d.fix !== void 0;
544
+ if (hasFix && !fixableRule) {
545
+ throw new Error(
546
+ `Rule "${ruleName}" attached a fix but meta.fixable is not 'code'`
547
+ );
548
+ }
317
549
  diagnostics.push({
318
- ruleName: rule9.meta.name,
550
+ ruleName,
319
551
  severity,
320
552
  path: file.path,
553
+ suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
554
+ docsUrl,
555
+ fixable: hasFix,
321
556
  ...d
322
557
  });
323
558
  }
@@ -352,6 +587,9 @@ function internalErrorDiagnostic(ruleName, operation, err, path) {
352
587
  messageId: "ruleThrew",
353
588
  severity: "error",
354
589
  path,
590
+ suggestion: null,
591
+ docsUrl: INTERNAL_ERROR_DOCS_URL,
592
+ fixable: false,
355
593
  data: {
356
594
  rule: ruleName,
357
595
  operation,
@@ -426,14 +664,28 @@ function runRulesOnProject(rules, files, runtime = {}) {
426
664
  );
427
665
  }
428
666
  }
667
+ const ruleName = rule9.meta.name;
668
+ const suggestions = rule9.meta.suggestions;
669
+ const docsUrl = rule9.meta.docs.url ?? "";
670
+ const fixableRule = rule9.meta.fixable === "code";
429
671
  const context = {
430
672
  files,
431
673
  options: mergedOptions,
432
674
  fileExists: runtime.fileExists,
433
675
  report(d) {
676
+ const template = suggestions?.[d.messageId];
677
+ const hasFix = d.fix !== void 0;
678
+ if (hasFix && !fixableRule) {
679
+ throw new Error(
680
+ `Rule "${ruleName}" attached a fix but meta.fixable is not 'code'`
681
+ );
682
+ }
434
683
  diagnostics.push({
435
- ruleName: rule9.meta.name,
684
+ ruleName,
436
685
  severity,
686
+ suggestion: template === void 0 ? null : interpolate(template, d.data ?? {}),
687
+ docsUrl,
688
+ fixable: hasFix,
437
689
  ...d
438
690
  });
439
691
  }
@@ -492,6 +744,58 @@ function isValidIso8601Date(s) {
492
744
  const d = new Date(Date.UTC(year, month - 1, day));
493
745
  return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day;
494
746
  }
747
+ var MONTHS = {
748
+ jan: 1,
749
+ january: 1,
750
+ feb: 2,
751
+ february: 2,
752
+ mar: 3,
753
+ march: 3,
754
+ apr: 4,
755
+ april: 4,
756
+ may: 5,
757
+ jun: 6,
758
+ june: 6,
759
+ jul: 7,
760
+ july: 7,
761
+ aug: 8,
762
+ august: 8,
763
+ sep: 9,
764
+ sept: 9,
765
+ september: 9,
766
+ oct: 10,
767
+ october: 10,
768
+ nov: 11,
769
+ november: 11,
770
+ dec: 12,
771
+ december: 12
772
+ };
773
+ function pad(n, width) {
774
+ return String(n).padStart(width, "0");
775
+ }
776
+ function buildIso(year, month, day) {
777
+ if (month < 1 || month > 12 || day < 1 || day > 31) return null;
778
+ const iso = `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
779
+ return isValidIso8601Date(iso) ? iso : null;
780
+ }
781
+ function normalizeToIso(raw) {
782
+ const s = raw.trim();
783
+ const numeric = /^(\d{4})([-/.])(\d{1,2})\2(\d{1,2})$/.exec(s);
784
+ if (numeric) {
785
+ return buildIso(Number(numeric[1]), Number(numeric[3]), Number(numeric[4]));
786
+ }
787
+ const dMonY = /^(\d{1,2})\s+([A-Za-z]+)\.?\s+(\d{4})$/.exec(s);
788
+ if (dMonY) {
789
+ const month = MONTHS[dMonY[2].toLowerCase()];
790
+ return month ? buildIso(Number(dMonY[3]), month, Number(dMonY[1])) : null;
791
+ }
792
+ const monDY = /^([A-Za-z]+)\.?\s+(\d{1,2}),?\s+(\d{4})$/.exec(s);
793
+ if (monDY) {
794
+ const month = MONTHS[monDY[1].toLowerCase()];
795
+ return month ? buildIso(Number(monDY[3]), month, Number(monDY[2])) : null;
796
+ }
797
+ return null;
798
+ }
495
799
  var rule = {
496
800
  meta: {
497
801
  name: "madr/date-iso8601",
@@ -506,6 +810,14 @@ var rule = {
506
810
  missingDate: 'Metadata does not contain a "{{field}}" field (checked frontmatter and v2 bold-list)',
507
811
  invalidDate: 'Date "{{date}}" is not a valid ISO 8601 calendar date (YYYY-MM-DD)'
508
812
  },
813
+ suggestions: {
814
+ missingDate: 'add a "{{field}}" field in YYYY-MM-DD format to the frontmatter (for MADR v2, a "* Date: ..." list item)',
815
+ invalidDate: "use the YYYY-MM-DD calendar-date format, e.g. 2025-03-14"
816
+ },
817
+ // Autofix (#29): normalize UNAMBIGUOUS shapes of a v2 list-sourced value —
818
+ // year-first numeric and English named-month forms. Ambiguous day/month
819
+ // order, invalid calendar dates, and frontmatter-sourced values get no fix.
820
+ fixable: "code",
509
821
  defaultOptions: {
510
822
  field: "date"
511
823
  },
@@ -532,10 +844,14 @@ var rule = {
532
844
  }
533
845
  if (!isValidIso8601Date(dateStr)) {
534
846
  const loc = context.metadataLoc?.[fieldName];
847
+ const valueRange = context.metadataValueLoc?.[fieldName];
848
+ const normalized = valueRange ? normalizeToIso(dateStr) : null;
849
+ const fix = normalized !== null && normalized !== dateStr && valueRange ? (fixer) => fixer.replaceRange([valueRange.start, valueRange.end], normalized) : void 0;
535
850
  context.report({
536
851
  messageId: "invalidDate",
537
852
  ...loc ? { loc } : {},
538
- data: { date: dateStr }
853
+ data: { date: dateStr },
854
+ ...fix ? { fix } : {}
539
855
  });
540
856
  }
541
857
  }
@@ -598,6 +914,11 @@ var rule2 = {
598
914
  messages: {
599
915
  invalidFilename: 'Filename "{{filename}}" does not match expected pattern "{{expected}}"'
600
916
  },
917
+ suggestions: {
918
+ // The message already states the expected pattern; the suggestion adds a
919
+ // concrete, conforming example of the NNNN-kebab-case.md convention.
920
+ invalidFilename: "rename the file to the NNNN-kebab-case.md convention, e.g. 0001-record-architecture-decisions.md"
921
+ },
601
922
  defaultOptions: {
602
923
  pattern: "^[0-9]{4}-[a-z0-9-]+\\.md$"
603
924
  },
@@ -677,6 +998,9 @@ var rule3 = {
677
998
  messages: {
678
999
  brokenLink: 'Link to "{{url}}" resolves to "{{resolvedPath}}", which does not exist in the project'
679
1000
  },
1001
+ suggestions: {
1002
+ brokenLink: "fix the link target or remove the link; relative paths resolve from the ADR file's own directory"
1003
+ },
680
1004
  defaultOptions: {},
681
1005
  schema: schema_default3
682
1006
  },
@@ -737,6 +1061,9 @@ var rule4 = {
737
1061
  messages: {
738
1062
  duplicateNumber: "ADR number {{number}} is used by multiple files: {{paths}}"
739
1063
  },
1064
+ suggestions: {
1065
+ duplicateNumber: "renumber all but one of these files so each ADR has a unique NNNN- prefix"
1066
+ },
740
1067
  defaultOptions: {},
741
1068
  schema: schema_default4
742
1069
  },
@@ -796,6 +1123,9 @@ var rule5 = {
796
1123
  messages: {
797
1124
  numberingGap: "Numbering gap: missing {{missing}} between ADR-{{from}} and ADR-{{to}}"
798
1125
  },
1126
+ // No `suggestions`: a gap can be intentional (a rejected or deleted ADR),
1127
+ // and closing it may mean either adding the missing ADR OR renumbering —
1128
+ // the right remediation is contextual, so we omit a suggestion. See #67.
799
1129
  defaultOptions: {},
800
1130
  schema: schema_default5
801
1131
  },
@@ -872,6 +1202,9 @@ var rule6 = {
872
1202
  messages: {
873
1203
  missingSection: 'Missing required section: "{{section}}"'
874
1204
  },
1205
+ suggestions: {
1206
+ missingSection: 'add a "## {{section}}" heading to the document body'
1207
+ },
875
1208
  defaultOptions: {
876
1209
  sections: [
877
1210
  "Context and Problem Statement",
@@ -936,6 +1269,43 @@ var schema_default7 = {
936
1269
  };
937
1270
 
938
1271
  // src/rules/status-enum/index.ts
1272
+ var TYPO_CORRECTIONS = {
1273
+ superceded: "superseded",
1274
+ supercedes: "supersedes",
1275
+ depricated: "deprecated"
1276
+ };
1277
+ function repairTypos(lower) {
1278
+ return lower.split(" ").map((tok) => TYPO_CORRECTIONS[tok] ?? tok).join(" ");
1279
+ }
1280
+ function tailAfterWords(s, n) {
1281
+ let i = 0;
1282
+ for (let w = 0; w < n; w++) {
1283
+ while (i < s.length && /\s/.test(s[i])) i++;
1284
+ while (i < s.length && !/\s/.test(s[i])) i++;
1285
+ }
1286
+ return s.slice(i);
1287
+ }
1288
+ function correctStatus(status, values, prefixValues) {
1289
+ const repaired = repairTypos(status.toLowerCase());
1290
+ const exact = [...new Set(values.filter((v) => v.toLowerCase() === repaired))];
1291
+ if (exact.length === 1) {
1292
+ return exact[0] !== status ? exact[0] : void 0;
1293
+ }
1294
+ if (exact.length > 1) return void 0;
1295
+ const prefixes = [
1296
+ ...new Set(
1297
+ prefixValues.filter((p) => {
1298
+ const pl = p.toLowerCase();
1299
+ return repaired === pl || repaired.startsWith(`${pl} `);
1300
+ })
1301
+ )
1302
+ ];
1303
+ if (prefixes.length !== 1) return void 0;
1304
+ const prefix = prefixes[0];
1305
+ const tail = tailAfterWords(status, prefix.split(" ").length);
1306
+ const replacement = `${prefix}${tail}`;
1307
+ return replacement !== status ? replacement : void 0;
1308
+ }
939
1309
  var rule7 = {
940
1310
  meta: {
941
1311
  name: "madr/status-enum",
@@ -950,6 +1320,17 @@ var rule7 = {
950
1320
  missingStatus: 'Metadata does not contain a "status" field (checked frontmatter and v2 bold-list)',
951
1321
  invalidStatus: 'Status "{{status}}" is not one of: {{allowed}}'
952
1322
  },
1323
+ // No suggestion for invalidStatus: the message already lists the allowed
1324
+ // values (the expected-vs-actual is self-contained), so a suggestion would
1325
+ // only restate it. See issue #67.
1326
+ suggestions: {
1327
+ missingStatus: 'add a "status" field to the frontmatter (for MADR v2, a "* Status: ..." list item) \u2014 allowed values: {{allowed}}'
1328
+ },
1329
+ // Autofix (#28/#29): normalize a v2 list-sourced value to the unique
1330
+ // canonical enum entry — case difference, a curated misspelling, or a prefix
1331
+ // case/typo — preserving any tail (see create()). Ambiguous or
1332
+ // frontmatter-sourced values get no fix.
1333
+ fixable: "code",
953
1334
  defaultOptions: {
954
1335
  values: ["proposed", "rejected", "accepted", "deprecated"],
955
1336
  prefixValues: ["superseded by"],
@@ -958,12 +1339,13 @@ var rule7 = {
958
1339
  schema: schema_default7
959
1340
  },
960
1341
  create(context) {
1342
+ const { values, prefixValues, caseSensitive } = context.options;
1343
+ const allowed = [...values, ...prefixValues.map((p) => `${p} ...`)];
961
1344
  const meta = context.metadata;
962
1345
  if (!meta || typeof meta.status !== "string") {
963
- context.report({ messageId: "missingStatus", data: {} });
1346
+ context.report({ messageId: "missingStatus", data: { allowed } });
964
1347
  return;
965
1348
  }
966
- const { values, prefixValues, caseSensitive } = context.options;
967
1349
  const status = meta.status;
968
1350
  const compareStatus = caseSensitive ? status : status.toLowerCase();
969
1351
  const compareValues = caseSensitive ? values : values.map((v) => v.toLowerCase());
@@ -973,15 +1355,15 @@ var rule7 = {
973
1355
  (p) => compareStatus.startsWith(p)
974
1356
  );
975
1357
  if (!exactMatch && !prefixMatch) {
976
- const allowed = [
977
- ...values,
978
- ...prefixValues.map((p) => `${p} ...`)
979
- ];
980
1358
  const loc = context.metadataLoc?.status;
1359
+ const canonical = correctStatus(status, values, prefixValues);
1360
+ const valueRange = context.metadataValueLoc?.status;
1361
+ const fix = canonical !== void 0 && canonical !== status && valueRange ? (fixer) => fixer.replaceRange([valueRange.start, valueRange.end], canonical) : void 0;
981
1362
  context.report({
982
1363
  messageId: "invalidStatus",
983
1364
  ...loc ? { loc } : {},
984
- data: { status, allowed }
1365
+ data: { status, allowed },
1366
+ ...fix ? { fix } : {}
985
1367
  });
986
1368
  }
987
1369
  }
@@ -1014,6 +1396,28 @@ function normalizeRefs(value) {
1014
1396
  }
1015
1397
  return [];
1016
1398
  }
1399
+ function escapeRegExp(s) {
1400
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
1401
+ }
1402
+ function frontmatterInsertEdit(content, key, value) {
1403
+ const fmEnd = frontmatterOffset(content);
1404
+ if (fmEnd === 0) return null;
1405
+ const fmBlock = content.slice(0, fmEnd);
1406
+ const closeMatch = /\r?\n(---[ \t]*\r?\n)$/.exec(fmBlock);
1407
+ if (!closeMatch) return null;
1408
+ const fenceLine = closeMatch[1];
1409
+ const offset = closeMatch.index + (closeMatch[0].length - fenceLine.length);
1410
+ if (content.slice(offset, offset + 3) !== "---") return null;
1411
+ const keyPattern = new RegExp(`(^|\\r?\\n)${escapeRegExp(key)}[ \\t]*:`, "i");
1412
+ if (keyPattern.test(content.slice(0, offset))) return null;
1413
+ const eol = fenceLine.endsWith("\r\n") ? "\r\n" : "\n";
1414
+ return { offset, text: `${key}: ${value}${eol}` };
1415
+ }
1416
+ function backReferenceFix(target, key, value) {
1417
+ const edit = frontmatterInsertEdit(target.content, key, value);
1418
+ if (!edit) return void 0;
1419
+ return (fixer) => fixer.insertAt(edit.offset, edit.text);
1420
+ }
1017
1421
  var rule8 = {
1018
1422
  meta: {
1019
1423
  name: "madr/supersedes-bidirectional",
@@ -1026,8 +1430,21 @@ var rule8 = {
1026
1430
  },
1027
1431
  messages: {
1028
1432
  unknownReference: "Frontmatter `{{direction}}: {{ref}}` references an ADR that does not exist",
1029
- missingBackReference: "`{{source}}` declares `{{direction}}: {{ref}}`, but `{{ref}}` (this file) does not back-reference it via `{{expected}}`"
1433
+ // `declared` is the field the SOURCE file actually declares;
1434
+ // `direction` is the field THIS file (the diagnostic's path) must add.
1435
+ // They are opposites — rendering `direction` as the declared field
1436
+ // would mislabel the source's frontmatter in both directions.
1437
+ missingBackReference: "`{{source}}` declares `{{declared}}: {{ref}}`, but `{{ref}}` (this file) does not back-reference it via `{{direction}}: {{expected}}`"
1438
+ },
1439
+ suggestions: {
1440
+ unknownReference: 'correct "{{ref}}" to an existing ADR number, or remove "{{direction}}: {{ref}}" from the frontmatter',
1441
+ missingBackReference: 'add "{{direction}}: {{expected}}" to the frontmatter of this file'
1030
1442
  },
1443
+ // Cross-file autofix (#29): `missingBackReference` inserts the reciprocal
1444
+ // `<direction>: <expected>` line into the target's EXISTING frontmatter.
1445
+ // Targets without frontmatter, or where the key already exists, decline;
1446
+ // `unknownReference` is contextual and never fixable.
1447
+ fixable: "code",
1031
1448
  defaultOptions: {},
1032
1449
  schema: schema_default8
1033
1450
  },
@@ -1057,15 +1474,18 @@ var rule8 = {
1057
1474
  }
1058
1475
  const targetBack = normalizeRefs(target.frontmatter?.[BACKWARD_FIELD]);
1059
1476
  if (!targetBack.includes(fileRef)) {
1477
+ const fix = backReferenceFix(target, BACKWARD_FIELD, fileRef);
1060
1478
  context.report({
1061
1479
  messageId: "missingBackReference",
1062
1480
  path: target.path,
1063
1481
  data: {
1064
1482
  ref,
1065
1483
  source: file.path,
1484
+ declared: FORWARD_FIELD,
1066
1485
  direction: BACKWARD_FIELD,
1067
1486
  expected: fileRef
1068
- }
1487
+ },
1488
+ ...fix ? { fix } : {}
1069
1489
  });
1070
1490
  }
1071
1491
  }
@@ -1081,15 +1501,18 @@ var rule8 = {
1081
1501
  }
1082
1502
  const targetFwd = normalizeRefs(target.frontmatter?.[FORWARD_FIELD]);
1083
1503
  if (!targetFwd.includes(fileRef)) {
1504
+ const fix = backReferenceFix(target, FORWARD_FIELD, fileRef);
1084
1505
  context.report({
1085
1506
  messageId: "missingBackReference",
1086
1507
  path: target.path,
1087
1508
  data: {
1088
1509
  ref,
1089
1510
  source: file.path,
1511
+ declared: BACKWARD_FIELD,
1090
1512
  direction: FORWARD_FIELD,
1091
1513
  expected: fileRef
1092
- }
1514
+ },
1515
+ ...fix ? { fix } : {}
1093
1516
  });
1094
1517
  }
1095
1518
  }
@@ -1226,15 +1649,23 @@ function defineConfig(config) {
1226
1649
  export {
1227
1650
  BASELINE_VERSION,
1228
1651
  INTERNAL_ERROR_RULE_NAME,
1652
+ MAX_FIX_PASSES,
1229
1653
  RuleOptionsError,
1230
1654
  applyBaseline,
1655
+ applyEdits,
1656
+ applyEditsCounted,
1231
1657
  baselinePath,
1232
1658
  buildBaseline,
1233
1659
  buildProjectFile,
1660
+ collectFixes,
1661
+ collectProjectFixes,
1234
1662
  defineConfig,
1235
1663
  extractListMetadata,
1664
+ fixFileContent,
1665
+ frontmatterOffset,
1236
1666
  isProjectRule,
1237
1667
  loadBaseline,
1668
+ makeFixer,
1238
1669
  parseFile,
1239
1670
  recommended,
1240
1671
  rules_exports as rules,
@@ -1242,6 +1673,7 @@ export {
1242
1673
  runRulesOnFile,
1243
1674
  runRulesOnProject,
1244
1675
  serializeBaseline,
1676
+ unifiedDiff,
1245
1677
  writeBaseline
1246
1678
  };
1247
1679
  //# sourceMappingURL=index.js.map