fix(lint): parse Markdown and MDX in WH001/WH002, autofix .mdx prose

.claude/hooks/markdown-on-save.sh

@@ -14,7 +14,7 @@
 # The commit hook stays a check; this fixes early enough that it rarely fires.
 #
 # The two branches below are mutually exclusive by extension: markdownlint's
-# generic fixers never see .mdx. See scripts/fix-mdx-fences.mjs for why.
+# generic fixers never see .mdx. See scripts/fix-mdx.mjs for why.
 #
 # Safety: best-effort throughout. A missing tool, an unparseable file, or a
 # lint error that has no fix leaves the file alone and never blocks the edit.
@@ -57,11 +57,11 @@ fi
 # corrects spelling there). The generic markdownlint rules are deliberately
 # never run against MDX — markdownlint parses CommonMark, MDX
 # does not, and where the two disagree a generic autofix rewrites the inside of
-# a code block. fix-mdx-fences only ever inserts a blank line beside a JSX tag,
-# so its worst failure is a render-neutral blank line. `make lint` still CHECKS
-# .mdx; it just never acts on the disagreement. Mirrors `fix:md`.
+# a code block. fix-mdx applies only WH002's blank lines and WH001's joins, read
+# from an MDX parse, and won't write a result that changes more than whitespace
+# around prose. `make lint` still CHECKS .mdx with every rule. Mirrors `fix:md`.
 if [ "${rel##*.}" = "mdx" ]; then
-  node scripts/fix-mdx-fences.mjs "$rel" >/dev/null 2>&1 || true
+  node scripts/fix-mdx.mjs "$rel" >/dev/null 2>&1 || true
 elif [ -x node_modules/.bin/markdownlint-cli2 ]; then
   # Plain Markdown: markdownlint's parse IS authoritative, so the full fixer
   # chain is safe. `--no-globs` keeps it to this one file rather than the whole

.markdownlint-cli2.jsonc

@@ -22,16 +22,18 @@
   // would "fix" code that only looks like prose. .mdx IS linted, but through the
   // `**/*.mdx` glob on `lint:md` in package.json, not this file's `globs`, which
   // are .md only so that no generic pass — `fix:md` or a bare `--fix` — can
-  // reach MDX (see the globs note below). The only fixer that touches .mdx is
-  // scripts/fix-mdx-fences.mjs, which just inserts blank lines beside JSX tags.
+  // reach MDX (see the globs note below). The only structural fixer that touches
+  // .mdx is scripts/fix-mdx.mjs, which applies WH001 and WH002 and nothing else.
   //
   // customRules live here and nowhere else — the VS Code extension reads this
   // file too, so no editor-side setting is needed (markdownlint.customRules is
   // deprecated in favor of this file). Note the editor only activates on
-  // Markdown, so .mdx gets no squiggles either way. CI reports both; `make fix`
-  // repairs WH001 in .md and only WH002 in .mdx:
+  // Markdown, so .mdx gets no squiggles either way. CI reports both, and
+  // `make fix` repairs both, in .md and .mdx alike. Both read a parse tree —
+  // markdownlint's micromark tokens, plus an MDX parse for .mdx — not line shape:
   //   WH001  prose paragraphs must not be hard-wrapped   (autofix: joins them)
-  //   WH002  MDX fence adjacent to a JSX tag needs a blank line (fixed in phase 1)
+  //   WH002  MDX fence beside a JSX tag, or inside what CommonMark reads as an
+  //          HTML block, needs a blank line (fixed in phase 1, fix-mdx.mjs)
   // Both are enabled in .markdownlint.json with no path-scoped carve-out of any
   // kind — WH001 over every tracked Markdown file, exactly what CONTRIBUTING.md
   // tells contributors; WH002 over every .mdx (it returns early on .md, where

.vscode/settings.json

@@ -76,10 +76,10 @@
     // below for MDX, running exactly the generic fixers the config globs keep
     // away from .mdx (see the note below).
     //
-    // WH002's autofix is owned by scripts/fix-mdx-fences.mjs, not by fix-on-save:
+    // MDX autofixes are owned by scripts/fix-mdx.mjs, not by fix-on-save:
     // the generic markdownlint fixers are never run over .mdx, because where
     // their CommonMark parse disagrees with MDX they rewrite the inside of a
-    // code block. `make fix` (or the markdown-on-save hook) repairs it instead.
+    // code block. `make fix` (or the markdown-on-save hook) repairs MDX instead.
     "editor.codeActionsOnSave": {
       "source.fixAll.markdownlint": "explicit"
     }

AGENTS.md

@@ -121,7 +121,7 @@ Tooling notes (the non-obvious bits `make help` won't tell you):
 - `golangci-lint` is pinned in the Makefile (v2.11.4), auto-installed to `.bin/` on first `make lint` — kept out of `go.mod` (its deps conflict with the main module).
 - `pnpm` (≥ 11.21) + `Node 22 LTS` (`.nvmrc`, matches CI) must be on PATH; `make tools` runs one root `pnpm install --frozen-lockfile` across the three workspaces (SDK `clients/ts/`, E2E `tests/e2e/sdk/`, docs `docs/`).
 - **GNU Make 4+** required (uses `--output-sync=target`); macOS ships GNU Make 3.81, which ignores it, so parallel output interleaves. Full setup: `docs/src/content/docs/development.md` § Prerequisites.
-- **Lint split**: Biome owns JS/TS/JSON, markdownlint owns Markdown *and MDX* style — including two repo-local rules, WH001 (no hard-wrapped prose) and WH002 (MDX fence beside a JSX tag) in `scripts/markdownlint-rules/` — misspell owns spelling (all under `make lint`/`make fix`); accuracy/clarity/doc-sync is the `docs-reviewer` gate (§Docs review). See §Markdown authoring rules.
+- **Lint split**: Biome owns JS/TS/JSON, markdownlint owns Markdown *and MDX* style — including two repo-local rules, WH001 (no hard-wrapped prose) and WH002 (an MDX fence beside a JSX tag, or inside what CommonMark reads as an HTML block) in `scripts/markdownlint-rules/` — misspell owns spelling (all under `make lint`/`make fix`); accuracy/clarity/doc-sync is the `docs-reviewer` gate (§Docs review). See §Markdown authoring rules.
 - **Worktrunk** (`wt`, `.config/wt.toml`): `wt switch --create` seeds `.bin/` + `node_modules/` from main, then runs `make tools`.
 
 ## Testing Conventions
@@ -335,7 +335,7 @@ Before finishing a task, grep for the identifiers you touched (field names, env
 
 ### Markdown authoring rules
 
-- **Never hard-wrap prose. One paragraph is one line.** No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries. Wrapped prose makes every later edit rewrap the whole block, so a one-word change lands as a five-line diff. Enforced by WH001 (`scripts/markdownlint-rules/no-hard-wrapped-prose.mjs`), which autofixes. Tables (with or without leading pipes), code, headings, setext underlines, blockquotes, JSX, `$$` display math, multi-line MDX `import`/`export`, and `:::` aside delimiters are left alone; a list item is joined as a unit, marker line included; an aside's *body* is joined but its delimiters are not. Note the four-space rule cuts both ways: any line indented four or more spaces is read as an indented code block and skipped, so a *nested* list item is never joined and must be unwrapped by hand.
+- **Never hard-wrap prose. One paragraph is one line.** No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries. Wrapped prose makes every later edit rewrap the whole block, so a one-word change lands as a five-line diff. Enforced by WH001 (`scripts/markdownlint-rules/no-hard-wrapped-prose.mjs`), which autofixes in `.md` and `.mdx` alike. It joins only what a parser calls a paragraph — markdownlint's own tokens for `.md`, an MDX parse for `.mdx` — so tables (with or without leading pipes), code, headings, setext underlines, JSX, `$$` display math, MDX `import`/`export`, and `:::` aside delimiters are left alone by construction, and so is the inside of a `<pre>`, `<script>`, `<style>` or `<textarea>`, where a line break is content (in `.md`, of one that opens an HTML block; in `.mdx`, of one at any depth, even opened mid-line); a list item is joined as a unit at any depth, marker line included; an aside's *body* is joined but its delimiters are not. A few shapes are neither reported nor fixed, so unwrap them by hand: blockquotes, lines that open with a tag, lines holding an HTML comment, a link reference definition written straight under prose, and a line break inside inline content that keeps it (inline math, an MDX expression or tag, a link title, image alt text, directive attributes, or a code span with spaces beside the break).
 - **In MDX, leave a blank line between a JSX tag and a code fence.** MDX itself renders the glued form correctly — verified by compiling both shapes with the same `@mdx-js/mdx` Astro uses. The blank line is what keeps *markdownlint* agreeing with it: markdownlint parses CommonMark, where `<TabItem …>` opens an HTML block that runs to the next blank line, so a glued fence is not a code block to any generic rule and `markdownlint --fix` will reformat the code inside it:
 
   ````mdx
@@ -348,9 +348,9 @@ Before finishing a task, grep for the identifiers you touched (field names, env
   </TabItem>
   ````
 
-  Enforced by WH002. **`.mdx` is never auto-fixed by the generic markdownlint rules** — `make fix` scopes that pass to `**/*.md`, because where markdownlint's CommonMark parse and MDX disagree a generic autofix rewrites the inside of a code block. MDX gets exactly one *structural* fixer, `scripts/fix-mdx-fences.mjs`, which only ever inserts a blank line beside a JSX tag (misspell still corrects spelling there — its curated list needs no parse). So `make lint` reports MDX problems but `make fix` will not silently repair them — including WH001 wrapping, which you must unwrap by hand in `.mdx`. You can't reach MDX with a bare `markdownlint-cli2 --fix` either — the config globs `.md` only, and the `.mdx` glob lives on `lint:md` — so that hazard is closed by construction rather than by this instruction.
-- **Editors see WH001 in `.md` only.** The markdownlint extension reads `.markdownlint-cli2.jsonc`, `customRules` included, so no `.vscode` setting is needed (`markdownlint.customRules` is deprecated in favor of that file). But it activates on the `markdown` language ID, and `.mdx` is not associated with it — so WH002 never squiggles in the editor, and WH001 squiggles only in `.md`. Don't "fix" that with a `files.associations` entry: it would enable `source.fixAll.markdownlint` on `.mdx`, running exactly the generic fixers that must never see MDX. `make fix` and the agent hook are the MDX path.
-- **These fix themselves as you write.** `.claude/hooks/markdown-on-save.sh` (PostToolUse, sibling of `gofumpt-on-save.sh`) runs the MDX fence pass on `.mdx`, markdownlint `--fix` on `.md`, and misspell on both, so an agent's output is corrected in the same pass rather than costing a lint failure and a manual cleanup. It only sees `Edit`/`Write`/`MultiEdit` — a file written through a Bash heredoc bypasses it, so run `make fix` after doing that.
+  Enforced by WH002, which also catches a fence glued to prose inside an open block (`<Aside>` / `Run this first:` / fence) by asking markdownlint's own parse whether the fence lands inside an HTML block. **`.mdx` is never auto-fixed by the generic markdownlint rules** — `make fix` scopes that pass to `**/*.md`, because where markdownlint's CommonMark parse and MDX disagree a generic autofix rewrites the inside of a code block. MDX gets exactly one *structural* fixer, `scripts/fix-mdx.mjs`, which runs WH002 and WH001 alone through the markdownlint library and refuses to write a result whose block structure, code/math/ESM/JSX blocks or non-whitespace text differ from the input (misspell still corrects spelling there — its curated list needs no parse). It won't insert a blank line inside a list item, where it would make the list loose, or a blockquote, where it would end the quote, or above a fence that a blank line can't separate (one inside `<pre>`, `<script>`, `<style>` or `<textarea>`); it prints each one it leaves, and those, any file it refuses to write, and the generic rules' findings in `.mdx` are fixed by hand. You can't reach MDX with a bare `markdownlint-cli2 --fix` either — the config globs `.md` only, and the `.mdx` glob lives on `lint:md` — so that hazard is closed by construction rather than by this instruction.
+- **The rules need `node_modules`** — they import micromark and its extensions, so run `make tools` before `make lint`, and before expecting squiggles in an editor. **Editors see WH001 in `.md` only.** The markdownlint extension reads `.markdownlint-cli2.jsonc`, `customRules` included, so no `.vscode` setting is needed (`markdownlint.customRules` is deprecated in favor of that file). But it activates on the `markdown` language ID, and `.mdx` is not associated with it — so WH002 never squiggles in the editor, and WH001 squiggles only in `.md`. Don't "fix" that with a `files.associations` entry: it would enable `source.fixAll.markdownlint` on `.mdx`, running exactly the generic fixers that must never see MDX. `make fix` and the agent hook are the MDX path.
+- **These fix themselves as you write.** `.claude/hooks/markdown-on-save.sh` (PostToolUse, sibling of `gofumpt-on-save.sh`) runs `scripts/fix-mdx.mjs` on `.mdx`, markdownlint `--fix` on `.md`, and misspell on both, so an agent's output is corrected in the same pass rather than costing a lint failure and a manual cleanup. It only sees `Edit`/`Write`/`MultiEdit` — a file written through a Bash heredoc bypasses it, so run `make fix` after doing that.
 - **WH001 applies to every tracked Markdown file, with no carve-out** — `AGENTS.md`, `CHANGELOG.md`, `.github/` CI docs and `.claude/` agent prompts included. Path-scoped `.markdownlint.json` files under `.github/` and `.claude/` used to switch it off there; [#521](https://github.com/Wave-RF/WaveHouse/issues/521) deleted them, because a config that silently contradicts `CONTRIBUTING.md` teaches a reviewer reading the config the wrong invariant. Don't reintroduce one — if a file genuinely can't satisfy WH001, say why in a `markdownlint-disable` comment in the file itself, where the next reader sees it. This makes WH001 *broader* than `scripts/docs-prose.sh`, which still skips `.github/` and `.claude/`: mechanical style is cheap to enforce everywhere, a prose review is not.
 
 ### Authoring docs-site pages