ci(docs): block merges on parser-level MDX validation (NVIDIA#2145)

Signed-off-by: Mark Chmarny <mark@chmarny.com>

Author: mchmarny

.github/workflows/fern-docs-ci.yaml

@@ -13,6 +13,12 @@
 # limitations under the License.
 
 # Validates Fern docs configuration on pull requests that touch docs or fern/.
+#
+# NOTE: `fern check` validates docs.yml/nav configuration — it does NOT parse
+# MDX, so it cannot catch a construct that aborts `fern generate --docs` at
+# publish time. Parser-level MDX validation is the `docs-mdx` job in
+# merge-gate.yaml, which is the blocking check (see docs/contributor/tests.md
+# "Docs MDX Gate"). This workflow is advisory nav/link validation.
 
 name: Fern Docs CI
 

.github/workflows/merge-gate.yaml

@@ -56,6 +56,7 @@ jobs:
       bom: ${{ steps.changes.outputs.bom }}
       tuning: ${{ steps.changes.outputs.tuning }}
       notices: ${{ steps.changes.outputs.notices }}
+      docs: ${{ steps.changes.outputs.docs }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
@@ -143,6 +144,31 @@ jobs:
               - 'validators/performance/requirements.txt'
               - 'validators/performance/licenses/**'
               - 'THIRD_PARTY_NOTICES.md'
+            docs:
+              # Inputs to the parser-level MDX gate. Only the Fern-published
+              # trees matter — a change anywhere under them can introduce a
+              # construct that parses as CommonMark but aborts
+              # `fern generate --docs`.
+              #
+              # docs/index.yml is Fern's navigation manifest AND the source the
+              # checkers derive their file list from, so it is both an input and
+              # a trigger: adding a page there must run the gate over it.
+              # docs/README.md is the published landing page — the earlier
+              # per-subdirectory globs missed it entirely.
+              #
+              # Everything the gate is MADE of is listed too, so a change to the
+              # gate cannot skip its own verification: the two checkers, the page
+              # enumerator, the locked parser toolchain, this workflow, and the
+              # Makefile — whose `check-docs-mdx-parse` target is what the job
+              # actually invokes, matching why the `renovate` and `notices`
+              # filters watch it.
+              - 'docs/**'
+              - 'tools/check-docs-mdx'
+              - 'tools/check-docs-mdx-parse'
+              - 'tools/docs-published-files'
+              - 'tools/mdx/**'
+              - 'Makefile'
+              - '.github/workflows/merge-gate.yaml'
 
       # code = true iff at least one changed file is NOT docs/markdown/LICENSE.
       #
@@ -385,6 +411,47 @@ jobs:
     steps:
       - run: echo "No Renovate config changes — validation not required"
 
+  # ---------------------------------------------------------------------------
+  # MDX docs gate — parses every Fern-published doc with the real MDX parser.
+  #
+  # `fern check` (Fern Docs CI) does not parse MDX, and the job that does
+  # (`fern generate --docs --preview`) runs in a workflow_run companion whose
+  # status never lands on the PR head SHA, so it can never be required. That
+  # gap let a bare `<=` merge green and then fail every docs publish, including
+  # a release tag (#2050). This job is the blocking replacement: hermetic, no
+  # DOCS_FERN_TOKEN, no dependency on Fern's SaaS being up at merge time.
+  # ---------------------------------------------------------------------------
+
+  docs-mdx:
+    needs: [check-paths]
+    if: needs.check-paths.outputs.docs == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+        with:
+          node-version: '20'
+      # The bash approximation runs first: it is instant and its messages name
+      # the specific hazard, so the common cases fail fast with better output.
+      # The parser then decides — it is the authoritative check, and GITHUB_ACTIONS
+      # makes a missing Node or a failed dependency install a hard error rather
+      # than the local warn-and-skip.
+      - name: Check MDX safety (pattern approximation)
+        run: make check-docs-mdx
+      - name: Validate docs with the real MDX parser
+        run: make check-docs-mdx-parse
+
+  docs-mdx-skip:
+    needs: [check-paths]
+    if: needs.check-paths.outputs.docs != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - run: echo "No published-docs changes — MDX parse gate not required"
+
   # ---------------------------------------------------------------------------
   # BOM version freshness — ensures the committed container-images.md matches
   # the registry pins even on docs-only PRs (which skip the full `tests` job).
@@ -534,6 +601,8 @@ jobs:
       - verify-licenses-skip
       - verify-renovate
       - verify-renovate-skip
+      - docs-mdx
+      - docs-mdx-skip
       - bom-freshness
       - bom-freshness-skip
       - tuning-freshness

.gitignore

@@ -179,3 +179,7 @@ aicr-e2e.xml
 # the repo root. The private-Sigstore e2e's run.sh builds the proxy to $TMPDIR,
 # so this only guards an accidental local build; the source stays tracked.
 /tlsproxy
+
+# Resolved MDX toolchain for tools/check-docs-mdx-parse. The manifest and
+# lockfile in tools/mdx/ ARE committed; only the installed tree is not.
+tools/mdx/node_modules/

.settings.yaml

@@ -39,6 +39,12 @@ linting:
   addlicense: 'v1.2.0'
   # renovate: datasource=github-releases depName=google/go-licenses depType=linting
   go_licenses: 'v2.0.1'
+  # MDX toolchain for tools/check-docs-mdx-parse (the parser-level docs gate) is
+  # owned by tools/mdx/package.json + package-lock.json, not listed here. The
+  # lockfile freezes the full transitive tree, which a version string cannot;
+  # this gate decides which docs merge, so its verdict must be reproducible.
+  # Renovate updates it natively via the npm manager. Same single-source-of-truth
+  # split as the Go toolchain living in .go-version.
 
 # Security Tools
 security_tools:

DEVELOPMENT.md

@@ -222,8 +222,16 @@ make lint
 make lint-go      # Go linting only
 make lint-yaml    # YAML linting only
 make license      # License header check
+
+# Docs published to Fern are parsed as MDX; both checks gate the merge
+make check-docs-mdx        # fast pattern approximation (no dependencies)
+make check-docs-mdx-parse  # real MDX parser, authoritative (needs Node 20+)
 ```
 
+`check-docs-mdx-parse` warns and skips when Node is unavailable locally, but
+hard-fails in CI. See
+[Docs MDX Gate](docs/contributor/tests.md#docs-mdx-gate).
+
 ### 5. Run E2E Tests
 
 ```bash

Makefile

@@ -8,7 +8,7 @@ ifeq ($(IMAGE_REGISTRY),)
 IMAGE_REGISTRY     := ghcr.io/nvidia
 endif
 IMAGE_TAG          ?= latest
-YAML_FILES         := $(shell find . -type f \( -iname "*.yml" -o -iname "*.yaml" \) ! -path "./examples/*" ! -path "./bundle/*" ! -path "./bundles/*" ! -path "*/testdata/*")
+YAML_FILES         := $(shell find . -type f \( -iname "*.yml" -o -iname "*.yaml" \) ! -path "./examples/*" ! -path "./bundle/*" ! -path "./bundles/*" ! -path "*/testdata/*" ! -path "*/node_modules/*")
 COMMIT             := $(shell git rev-parse HEAD)
 BRANCH             := $(shell git rev-parse --abbrev-ref HEAD)
 GO_VERSION         := $(shell cat .go-version 2>/dev/null)
@@ -105,7 +105,7 @@ generate: ## Runs go generate for code generation
 	@echo "Code generation completed"
 
 .PHONY: lint
-lint: lint-go lint-yaml license check-agents-sync check-docs-filenames check-docs-mdx bom-pinning-check ## Lints the entire project (Go, YAML, license headers, and chart-version pins)
+lint: lint-go lint-yaml license check-agents-sync check-docs-filenames check-docs-mdx check-docs-mdx-parse bom-pinning-check ## Lints the entire project (Go, YAML, license headers, and chart-version pins)
 	@echo "Completed Go and YAML lints and ensured license headers"
 
 # Standalone target — NOT part of `make lint` because it requires Docker
@@ -141,6 +141,21 @@ check-docs-filenames: ## Enforces lowercase kebab-case filenames in docs/
 check-docs-mdx: ## Checks docs/ markdown for MDX compatibility (void elements, bare braces, HTML comments, autolinks, bare <tags>)
 	@./tools/check-docs-mdx
 
+# Parser-level docs gate — runs the SAME MDX parser Fern does over every
+# published doc, so a construct that would abort `fern generate --docs` at
+# publish time fails here instead. This is the authoritative check;
+# check-docs-mdx above is a fast, dependency-free approximation kept as a
+# strict subset of it.
+#
+# Part of `make lint` (and therefore `make qualify`). It needs Node 20+ and one
+# `npm ci` of the locked tree in tools/mdx. With Node installed, a local
+# `make qualify` predicts CI as usual; WITHOUT it this check warns and skips, so
+# a local pass no longer implies a CI pass and invalid MDX can still be rejected
+# by the merge-gate `docs-mdx` job, where a missing Node is a HARD FAILURE.
+.PHONY: check-docs-mdx-parse
+check-docs-mdx-parse: ## Validates docs/ with the real MDX parser (requires Node; CI-blocking)
+	@./tools/check-docs-mdx-parse
+
 .PHONY: lint-go
 lint-go: ## Lints Go files with golangci-lint and go vet
 	@set -e; \
@@ -179,7 +194,8 @@ LICENSE_IGNORES = \
 	-ignore 'recipes/evidence/*/*/*.yaml' \
 	-ignore 'THIRD_PARTY_NOTICES.md' \
 	-ignore 'validators/performance/licenses/**' \
-	-ignore '.licenses-cache/**'
+	-ignore '.licenses-cache/**' \
+	-ignore 'tools/mdx/node_modules/**'
 
 # The two recipes/evidence patterns in LICENSE_IGNORES match exactly the
 # generated, header-less pointer shapes MarshalPointer emits — the transient

docs/contributor/tests.md

@@ -479,7 +479,8 @@ half of the pipeline and skips deploy-side assertions.
 `make qualify` is the canonical pre-push command. It runs:
 
 - `test-coverage` — `go test -race ./...` plus the 80% coverage floor.
-- `lint` — golangci-lint with `.golangci.yaml` plus yamllint.
+- `lint` — golangci-lint with `.golangci.yaml`, yamllint, and the docs checks
+  (filenames, MDX patterns, MDX parse — see [Docs MDX Gate](#docs-mdx-gate)).
 - `e2e` — the end-to-end pipeline runner.
 - `scan` — Grype vulnerability scan.
 - `license-check` — license header / dependency-license sweep.
@@ -501,6 +502,66 @@ This applies even to PRs labeled `documentation` when they include
 incidental Go changes. Do not rely on CI to surface lint failures —
 the pre-push gate is local.
 
+## Docs MDX Gate
+
+Fern renders published docs through an MDX parser, so a construct that is valid
+CommonMark can still abort `fern generate --docs` at publish time. A bare `<=`
+in prose is the classic case — MDX reads the `<` as the start of a JSX tag and
+fails with `Unexpected character = (U+003D) before name`.
+
+**Which files are checked.** Both checks derive their file list from
+`docs/index.yml` via `tools/docs-published-files` — Fern's navigation manifest
+is the authoritative statement of what gets parsed. Globbing
+`docs/user`/`docs/integrator`/`docs/contributor` instead was a denylist in
+disguise: it missed `docs/README.md`, the published landing page, so a hazard
+there passed both gates and still broke the publish. Add a page to
+`docs/index.yml` and it is gated that day; a file that is not published is not
+gated at all.
+
+Two checks cover this, both run by `make lint`:
+
+| Check | What it is | Speed |
+|-------|-----------|-------|
+| `make check-docs-mdx` | Pattern-based bash approximation. Names the specific hazard, needs no dependencies. | Instant |
+| `make check-docs-mdx-parse` | The real MDX parser (`@mdx-js/mdx`, locked in `tools/mdx/package-lock.json`). Authoritative. | ~2 s + one `npm ci` |
+
+The parser is the source of truth. The bash rules are deliberately kept as a
+strict **subset** of what it rejects: a miss is caught by the parse gate, but a
+false positive would force you to mangle prose the publish step would have
+accepted. That is why `< 500` and `< 10 s` are fine (MDX only enters tag mode
+when a name-ish character follows `<` immediately) while `<= 2,000` and `<30 s`
+are not.
+
+Hazards only the parser sees: a stray closing tag (`</div>`), an unclosed
+fragment (`<>`), a placeholder sharing a line with well-formed JSX, unbalanced
+expression braces spanning lines, and any acorn-level syntax error.
+
+Well-formed JSX is fine in both — `<Component />` and `<span>text</span>` parse,
+and the Fern component set is authored that way. So is YAML frontmatter: Fern
+strips it before MDX, so a `title: gate <= 2,000` is valid, and both checks skip
+it by line number so later diagnostics still cite the true line.
+
+`check-docs-mdx-parse` needs Node 20+. Without it the script prints a warning
+and exits 0 locally, but **hard-fails under CI** — the `docs-mdx` job in
+`merge-gate.yaml` blocks on it, and the merge gate is the only required status
+check. This is the one place where a green local `make qualify` does not
+guarantee a green CI: if you have no Node, the MDX gate did not actually run.
+
+Fixing a violation is usually one of:
+
+```markdown
+gate <= 2,000   →  gate `<= 2,000`
+<30 s           →  `<30 s`        or  &lt;30 s
+<br>            →  <br />
+{template}      →  \{template\}
+```
+
+Note that `fern check` (the Fern Docs CI job) does **not** parse MDX, and the
+job that does — `fern generate --docs --preview` — runs as a `workflow_run`
+companion whose status never lands on the PR head SHA, so it cannot be a
+required check. `make check-docs-mdx-parse` exists to close that gap without a
+token or a dependency on Fern's service at merge time.
+
 ## Common Gotchas
 
 - **`goreleaser` fails when both `GITLAB_TOKEN` and `GITHUB_TOKEN`