madr-lint 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.1
+
+### Patch Changes
+
+- [#114](https://github.com/knktkc/madr-lint/pull/114) [`e7d3a30`](https://github.com/knktkc/madr-lint/commit/e7d3a30fc84e0cbc4f2f76bcdc50a7681a38b8fc) Thanks [@knktkc](https://github.com/knktkc)! - Fix v2 metadata being silently dropped after an HTML comment ([#73](https://github.com/knktkc/madr-lint/issues/73)). A suppression comment placed _between_ MADR v2 metadata-list items splits the Markdown list in two (CommonMark), and the v2 bridge previously read only the first segment — so a field below the comment vanished from `context.metadata`, turning a line-suppressible `invalidDate` into an unsuppressible file-level `missingDate`. Suppressing was strictly worse than not suppressing.
+
+  - **The v2 metadata block is now the leading run of lists joined across HTML comments.** A comment renders as nothing, so it can no longer end the block. A key below a comment now behaves exactly like one above it: it keeps its own body line, so `<!-- madr-lint-disable-next-line madr/date-iso8601 -->` between items reaches the field below it, and it carries the same value offsets, so — with no directive above it — `--fix` rewrites that field in place (`madr/status-enum`, `madr/date-iso8601`). Not both: `--fix` never rewrites a suppressed problem. Blank lines around the comment do not matter — `disable-next-line` already targets the next non-blank line.
+  - **Only comments bridge.** Visible HTML (`<div>`, `<details>`, or a node like `<!-- a --> visible` that is not purely a comment), a paragraph, a code fence, a thematic break, a blockquote, and a heading of any depth all still end the metadata block — it must lead. Two lists with no comment between them (a bullet-marker change, `* Status:` then `- Date:`) are still two lists, and the second is still not metadata.
+  - **Public API**: `extractListMetadata` now reads list segments separated only by HTML comments. The signature is unchanged and the change is additive — merging can only add keys (duplicate keys still resolve first-wins), so it never returns fewer than before. Two consequences worth knowing: a document whose recognized MADR key sits only in a later segment now returns metadata where it previously returned `null` (which also lets `madr-lint init` cast a v2 version vote for it), and a prose list placed after the metadata block with only a comment between them, before the next heading of any depth, can contribute an extra key.
+  - **Upgrading with a baseline**: a v2 field hidden by this bug was reported as a file-level `missingDate` / `missingStatus`; it is now reported as `invalidDate` / `invalidStatus` on the field's own line. If you baselined the old entry, re-run `madr-lint --update-baseline` — the stored entry no longer absorbs the new diagnostic, and the file goes red on an otherwise unchanged tree.
+  - **Not fixed here**: a directive written as a multi-line `<!--` … `-->` block still resolves to its own second line, so keep `disable-next-line` on a single line. `<div>`-style HTML on the line directly above a metadata item swallows that line into the HTML block, so the item never reaches the AST at all.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -31,12 +31,12 @@ A fast, configurable linter for [MADR](https://adr.github.io/madr/) (Markdown Ar
 
 [MADR](https://github.com/adr/madr) ships no official linter, and the general-purpose tools each cover only part of what an ADR collection needs:
 
-| Tool | Markdown style | Inter-doc links | ADR numbering | Status enum | Date format | Supersedes graph | v2 bold-list |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) | ✅ | — | — | — | — | — | n/a |
-| [lychee](https://github.com/lycheeverse/lychee) | — | ✅ | — | — | — | — | n/a |
-| [adrs (rust)](https://crates.io/crates/adrs) | — | — | ✅ (init) | — | — | ~ | — |
-| **madr-lint** | —¹ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Tool | Markdown style | Inter-doc links | ADR numbering | Status enum | Date format | Supersedes graph | v2 bold-list | Autofix |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) | ✅ | — | — | — | — | — | n/a | ✅ |
+| [lychee](https://github.com/lycheeverse/lychee) | — | ✅ | — | — | — | — | n/a | — |
+| [adrs (rust)](https://crates.io/crates/adrs) | — | — | ✅ (init) | — | — | ~ | — | — |
+| **madr-lint** | —¹ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ~ (3/8 rules) |
 
 ¹ Deliberately *not* Markdown style — pair it with `markdownlint-cli2` if you want both. `madr-lint` owns the ADR-specific semantics.
 
@@ -44,6 +44,7 @@ A fast, configurable linter for [MADR](https://adr.github.io/madr/) (Markdown Ar
 - **ESLint-style rules** — named `madr/*` rules with `error` / `warn` / `off` and per-rule options validated by a JSON Schema.
 - **Per-file & cross-file** — fast single-pass checks plus project rules for unique numbering, the supersedes graph, and link rot.
 - **CLI, library & CI** — `text` / `json` / `sarif` / `github` reporters, a programmatic API, and a drop-in GitHub Actions step.
+- **Autofix** — `--fix` / `--fix-dry-run` mechanically repair the violations that have a safe, unambiguous correction (3 of 8 rules today); everything else still reports with a `suggestion`.
 - **Gradual adoption** — [inline suppression comments](https://knktkc.github.io/madr-lint/guides/suppressing-rules/) for one-off exceptions and a [baseline file](https://knktkc.github.io/madr-lint/guides/adopting-existing-repo/) to snapshot legacy debt so only new violations fail the build.
 
 ## Install
@@ -57,9 +58,15 @@ Node.js 22+. ESM-only. Ships TypeScript types.
 ## Quick start
 
 ```bash
+# Scaffold a config — detects your ADR directory and MADR version
+npx madr-lint init
+
 # Lint the configured adrDir (default: docs/adr)
 npx madr-lint
 
+# Auto-repair what's mechanically fixable, then re-lint
+npx madr-lint --fix
+
 # Explicit paths (files or directories; directories are searched recursively)
 npx madr-lint docs/adr libs/x/adr
 
@@ -92,17 +99,17 @@ Rule values are a severity (`'error' | 'warn' | 'off'`) or a `[severity, options
 
 ## Rules
 
-8 rules — 7 enabled by `recommended`, 1 opt-in. Each page documents its options, examples, and MADR-version compatibility.
+8 rules — 7 enabled by `recommended`, 1 opt-in. 🔧 marks the 3 rules `--fix` can repair. Each page documents its options, examples, and MADR-version compatibility.
 
 | Rule | Type | Default | Checks |
 |---|---|:---:|---|
 | [`madr/required-sections`](https://knktkc.github.io/madr-lint/rules/required-sections/) | per-file | `error` | Required heading sections are present |
-| [`madr/status-enum`](https://knktkc.github.io/madr-lint/rules/status-enum/) | per-file | `error` | `status` is one of the allowed values |
-| [`madr/date-iso8601`](https://knktkc.github.io/madr-lint/rules/date-iso8601/) | per-file | `error` | `date` is a valid ISO-8601 calendar date |
+| [`madr/status-enum`](https://knktkc.github.io/madr-lint/rules/status-enum/) 🔧 | per-file | `error` | `status` is one of the allowed values |
+| [`madr/date-iso8601`](https://knktkc.github.io/madr-lint/rules/date-iso8601/) 🔧 | per-file | `error` | `date` is a valid ISO-8601 calendar date |
 | [`madr/filename-format`](https://knktkc.github.io/madr-lint/rules/filename-format/) | per-file | `error` | Filename matches the ADR convention |
 | [`madr/no-broken-links`](https://knktkc.github.io/madr-lint/rules/no-broken-links/) | project | `error` | Relative links resolve to existing files |
 | [`madr/no-duplicate-numbering`](https://knktkc.github.io/madr-lint/rules/no-duplicate-numbering/) | project | `error` | ADR numbers are unique |
-| [`madr/supersedes-bidirectional`](https://knktkc.github.io/madr-lint/rules/supersedes-bidirectional/) | project | `error` | `supersedes` / `superseded-by` agree |
+| [`madr/supersedes-bidirectional`](https://knktkc.github.io/madr-lint/rules/supersedes-bidirectional/) 🔧 | project | `error` | `supersedes` / `superseded-by` agree |
 | [`madr/no-numbering-gap`](https://knktkc.github.io/madr-lint/rules/no-numbering-gap/) | project | `off` | ADR numbers are contiguous (opt-in) |
 
 ## Use in CI
@@ -125,7 +132,7 @@ jobs:
 ```
 
 > The floating `v0` tag tracks the latest v0.x release; for stricter
-> reproducibility, pin an exact tag like `@v0.3.0`.
+> reproducibility, pin an exact tag like `@v0.4.0`.
 
 Or run it via `npx` in any CI provider:
 

package/dist/cli.js

@@ -180,32 +180,58 @@ var RECOGNIZED_METADATA_KEYS = /* @__PURE__ */ new Set([
   "consulted",
   "informed"
 ]);
+function isHtmlComment(value) {
+  let rest = value.trim();
+  if (rest.length === 0) return false;
+  while (rest.length > 0) {
+    if (!rest.startsWith("<!--")) return false;
+    const end = rest.indexOf("-->", 2);
+    if (end === -1) return false;
+    rest = rest.slice(end + 3).trim();
+  }
+  return true;
+}
 function extractListMetadataWithLoc(ast, body) {
-  let firstList = null;
+  const segments = [];
+  let bridged = false;
   for (const child of ast.children) {
-    if (child.type === "heading") {
-      if (child.depth >= 2) break;
+    if (segments.length === 0) {
+      if (child.type === "heading") {
+        if (child.depth >= 2) break;
+        continue;
+      }
+      if (child.type === "html") continue;
+      if (child.type === "list") {
+        segments.push(child);
+        continue;
+      }
+      break;
+    }
+    if (child.type === "html" && isHtmlComment(child.value)) {
+      bridged = true;
       continue;
     }
-    if (child.type === "html") continue;
-    if (child.type === "list") {
-      firstList = child;
-      break;
+    if (child.type === "list" && bridged) {
+      segments.push(child);
+      bridged = false;
+      continue;
     }
     break;
   }
-  if (!firstList) return null;
+  if (segments.length === 0) return null;
   const values = {};
   const loc = {};
   const valueOffsets = {};
-  for (const item of firstList.children) {
-    const pair = extractListItemKV(item);
-    if (pair && !(pair.key in values)) {
-      values[pair.key] = pair.value;
-      const start = item.position?.start;
-      if (start) loc[pair.key] = { line: start.line, column: start.column };
-      if (body !== void 0 && pair.valueOffset && body.slice(pair.valueOffset.start, pair.valueOffset.end) === pair.value) {
-        valueOffsets[pair.key] = pair.valueOffset;
+  for (const list of segments) {
+    for (const item of list.children) {
+      const pair = extractListItemKV(item);
+      if (pair && !(pair.key in values)) {
+        values[pair.key] = pair.value;
+        const start = item.position?.start;
+        if (start) loc[pair.key] = { line: start.line, column: start.column };
+        if (body !== void 0 && pair.valueOffset && body.slice(pair.valueOffset.start, pair.valueOffset.end) === pair.value) {
+          valueOffsets[pair.key] = pair.valueOffset;
+        }
       }
     }
   }