fix(docs): fail-closed MDX check for bare '<' + MDX-safe content (NVIDIA#2127)

Signed-off-by: Nathan Hensley <nhensley@nvidia.com>
Co-authored-by: Mark Chmarny <mchmarny@users.noreply.github.com>

Author: njhensley

docs/contributor/api-server.md

@@ -122,7 +122,7 @@ and serializes the `ErrorResponse` shape (`code`, `message`, `details`,
 
 Critical rule, enforced at this single chokepoint:
 
-> Embed `Cause.Error()` in `details["error"]` **only when status < 500**.
+> Embed `Cause.Error()` in `details["error"]` **only when `status < 500`**.
 > 4xx errors typically carry validator feedback the client needs;
 > 5xx errors carry internal paths, kubeconfig contents, or upstream
 > service hostnames that must not leak.

docs/integrator/aks-gpu-setup.md

@@ -308,8 +308,8 @@ check-nvidia-smi) for training and inference, and the training performance
 phase passes the calibrated NCCL all-reduce gate at 157.29 GB/s (16 GiB
 message size across 2 nodes, gate >= 150). The Dynamo inference counterpart
 (`h100-aks-ubuntu-inference-dynamo`) passes `inference-perf` at
-148,004 tok/s throughput (gate >= 50,000) with 579.70 ms TTFT p99
-(gate <= 2,000) — Qwen/Qwen3-8B at 256 concurrency per GPU via
+148,004 tok/s throughput (gate `>= 50,000`) with 579.70 ms TTFT p99
+(gate `<= 2,000`) — Qwen/Qwen3-8B at 256 concurrency per GPU via
 dynamo-router on a single ND96isr node. Other SKUs and node images have
 not been exercised — run `aicr validate` after deployment and report gaps.
 

docs/user/component-catalog.md

@@ -70,7 +70,7 @@ Not every component appears in every recipe. The recipe engine selects component
 
 Production GPU leaf recipes (H100, GB200, RTX Pro 6000 on EKS / AKS / GKE / OKE / LKE) enable the NFD Topology Updater. It publishes per-node `NodeResourceTopology` CRDs that describe NUMA zones, GPU-to-NUMA affinity, and NIC-to-NUMA affinity. Runtime consumers (NUMA-aware schedulers, debugging via `kubectl get noderesourcetopologies`) can read these CRDs without further configuration.
 
-The Topology Updater requires the kubelet `podResources` gRPC socket. The `KubeletPodResources` feature gate has been on by default since Kubernetes 1.15 (Beta) and reached GA in Kubernetes 1.28; AICR's recipe constraints on the affected leaves require K8s ≥ 1.30 or higher, so this is satisfied in practice. Recipes targeting Kubernetes < 1.15 must enable the feature gate explicitly. Kind / KWOK simulated clusters do not run a real kubelet and therefore leave the Topology Updater disabled — kind-based recipes will not see `NodeResourceTopology` CRDs.
+The Topology Updater requires the kubelet `podResources` gRPC socket. The `KubeletPodResources` feature gate has been on by default since Kubernetes 1.15 (Beta) and reached GA in Kubernetes 1.28; AICR's recipe constraints on the affected leaves require K8s ≥ 1.30 or higher, so this is satisfied in practice. Recipes targeting Kubernetes `< 1.15` must enable the feature gate explicitly. Kind / KWOK simulated clusters do not run a real kubelet and therefore leave the Topology Updater disabled — kind-based recipes will not see `NodeResourceTopology` CRDs.
 
 See the upstream [Topology Updater docs](https://kubernetes-sigs.github.io/node-feature-discovery/stable/usage/nfd-topology-updater.html) for runtime consumer examples.
 

docs/user/validation.md

@@ -530,7 +530,7 @@ exits 8 by default, and is informational only under `--fail-on-error=false`.)
 | **B** | `inference-perf` is selected but `dynamo-platform` is not in recipe `componentRefs` | `skipped - dynamo-platform not in recipe components` |
 | **C** | `dynamo-platform` is declared but the `DynamoGraphDeployment` CRD is not installed on the cluster (operator not deployed yet) | `skipped - DynamoGraphDeployment CRD not installed on cluster (dynamo-platform component declared but operator not deployed yet)` |
 
-Guards fire before any cluster mutation, so skips are cheap (typically < 10 s).
+Guards fire before any cluster mutation, so skips are cheap (typically `< 10 s`).
 
 ## Configured GPU allocation policy
 

tools/check-docs-mdx

@@ -24,6 +24,27 @@
 #   5. Bare angle-bracket placeholders (<word>) outside fenced and inline code
 #      — MDX interprets them as JSX component tags and fails on unexpected
 #      content that follows.
+#   6. Bare '<' NOT followed by a valid JSX name-start (fail-closed allowlist)
+#      — a '<' before anything other than a letter, '/', '!', or '>' (e.g.
+#      '<=', '< 5', '<3', '<-', or a trailing '<') is a parse error. Unlike
+#      checks 4 and 5, which match a '<' that IS followed by a name-start,
+#      this rule fails closed on every other '<'-follow, so future hazards in
+#      that family are caught by default rather than needing a new pattern.
+#
+# Code handling (applies to all checks): fenced code blocks in BOTH backtick
+# (```) and tilde (~~~) styles are skipped, following CommonMark fence rules —
+# a fence opens on a run of >= 3 of either character and closes only on a later
+# line whose leading run is the SAME character and at least as long. Inline
+# code spans are stripped before scanning; a span opens on a run of N backticks
+# and closes at the next run of exactly N backticks, so spans of any
+# backtick-run length are honored (not just single-backtick spans).
+#
+# NOTE: this checker remains an APPROXIMATION of the MDX parser, not a
+# reimplementation of it. It can still drift on hazard classes outside the
+# '<'-follow family covered above (e.g. malformed JSX attributes, unbalanced
+# expression braces spanning lines, or acorn-level syntax errors). A green run
+# is NOT parser-level validation — it means none of the known hazard patterns
+# matched, not that Fern's MDX parser will accept the file.
 
 set -euo pipefail
 
@@ -55,14 +76,21 @@ for dir in "${SEARCH_DIRS[@]}"; do
       echo "MDX: non-self-closing void element: ${file}:${match}"
       ERRORS=$((ERRORS + 1))
     done < <(awk '
-      /^```/ { in_fence = !in_fence; next }
+      match($0, /^(`{3,}|~{3,})/) {
+        m = substr($0, RSTART, RLENGTH); ch = substr(m, 1, 1); len = length(m)
+        if (!in_fence) { in_fence = 1; fch = ch; flen = len; next }
+        else if (ch == fch && len >= flen) { in_fence = 0; next }
+        # else: fence-like line inside a fence of a different char/shorter run
+        # is content -> fall through to the in_fence guard below.
+      }
       in_fence { next }
       { print NR": "$0 }
     ' "$file" | grep -E "<(${VOID_ELEMENTS})([[:space:]][^>]*)?" | grep -Ev "<(${VOID_ELEMENTS})([[:space:]][^>]*)?[[:space:]]*/>" || true)
   done < <(find "${dir}" -type f \( -name '*.md' -o -name '*.mdx' \) "${EXCLUDE_ARGS[@]}" 2>/dev/null)
 done
 
-# --- Checks 2, 3, 4, 5: bare braces, HTML comments, autolinks, bare tags ---
+# --- Checks 2, 3, 4, 5, 6: bare braces, HTML comments, autolinks, bare tags,
+#     and bare '<' not starting a valid tag ---
 # All evaluated outside fenced code blocks; inline code spans are stripped
 # before the line is scanned so legitimate uses inside backticks don't trip.
 for dir in "${SEARCH_DIRS[@]}"; do
@@ -72,7 +100,13 @@ for dir in "${SEARCH_DIRS[@]}"; do
     # `set -e` does not abort the whole scan at the first offending file
     # (otherwise violations in later files are silently skipped).
     if ! awk '
-      /^```/ { in_fence = !in_fence; next }
+      match($0, /^(`{3,}|~{3,})/) {
+        m = substr($0, RSTART, RLENGTH); ch = substr(m, 1, 1); len = length(m)
+        if (!in_fence) { in_fence = 1; fch = ch; flen = len; next }
+        else if (ch == fch && len >= flen) { in_fence = 0; next }
+        # else: fence-like line inside a fence of a different char/shorter run
+        # is content -> fall through to the in_fence guard below.
+      }
       in_fence { next }
       {
         line = $0
@@ -81,7 +115,37 @@ for dir in "${SEARCH_DIRS[@]}"; do
         # below (or any later check). Doing this before the comment scan
         # prevents a backticked, unterminated `{/*` from opening a bogus
         # multi-line region that swallows real hazards on following lines.
-        gsub(/`[^`]*`/, "", line)
+        #
+        # CommonMark inline code spans open with a run of N backticks and close
+        # at the next run of EXACTLY N backticks; the text between (shorter runs
+        # included) is code. Strip each such span for ANY N — this subsumes the
+        # single-backtick (N=1) case. A run with no matching closing run of
+        # equal length is left as literal text (not stripped).
+        stripped = ""
+        tail = line
+        while (match(tail, /`+/)) {
+          n = RLENGTH
+          stripped = stripped substr(tail, 1, RSTART - 1)
+          openrun = substr(tail, RSTART, RLENGTH)
+          after = substr(tail, RSTART + RLENGTH)
+          pos = 1
+          closed = 0
+          while (match(substr(after, pos), /`+/)) {
+            abspos = pos + RSTART - 1
+            if (RLENGTH == n) {
+              tail = substr(after, abspos + RLENGTH)
+              closed = 1
+              break
+            }
+            pos = abspos + RLENGTH
+          }
+          if (!closed) {
+            stripped = stripped openrun after
+            tail = ""
+            break
+          }
+        }
+        line = stripped tail
         # MDX comments {/* ... */} are valid (and used for license headers
         # and the auto-generated splice markers in recipe-health.md). Treat
         # them like code: continue an open multi-line comment, strip
@@ -132,6 +196,20 @@ for dir in "${SEARCH_DIRS[@]}"; do
         printf "MDX: bare <word> tag outside code fence: %s:%d: %s\n", FILENAME, NR, $0
         errors++
       }
+      # Check 6 (fail-closed allowlist): a bare `<` that is NOT followed by a
+      # valid JSX name-start. MDX only accepts `<` before a letter (element),
+      # `/` (closing tag), `!` (declaration/comment, caught by check 3), or `>`
+      # (fragment); anything else — `<=`, `< 5`, `<3`, `<-`, or a trailing `<`
+      # at end of line — is a parse error (e.g. `(gate <= 2,000)` yields
+      # "Unexpected character = (U+003D) before name"). This complements
+      # checks 4 and 5 rather than replacing them: they cover the cases where
+      # `<` IS followed by a name-start (autolinks, placeholders), while this
+      # covers the cases where it is not. Inverting to an allowlist means any
+      # future `<`-follow hazard fails closed by default.
+      line ~ /<([^A-Za-z!\/>]|$)/ {
+        printf "MDX: bare < not starting a valid tag: %s:%d: %s\n", FILENAME, NR, $0
+        errors++
+      }
       END { exit (errors > 0) ? 1 : 0 }
     ' "$file" 2>/dev/null; then
       ERRORS=$((ERRORS + 1))

tools/check-docs-mdx_test.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Unit harness for tools/check-docs-mdx check 6 — the fail-closed allowlist
+# rule for a bare '<' not followed by a valid JSX name-start.
+# Run directly: bash tools/check-docs-mdx_test.sh
+# Wired into CI via `make test` (test-shell target, runs tools/*_test.sh).
+#
+# Hermetic: builds fixture .md files in a temp dir and runs the checker against
+# them, so no docs/ content is read and nothing on disk is mutated. The
+# fixtures pin the regression from issue #2050 (Fern's MDX parser rejects
+# '(gate <= 2,000)' with "Unexpected character = (U+003D) before name", which
+# the denylist-era checker reported as OK) and guard against false positives
+# when the same token is safely wrapped in inline or fenced code.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="${SCRIPT_DIR}/check-docs-mdx"
+
+TMPDIR_TEST="$(mktemp -d)"
+trap 'rm -rf "${TMPDIR_TEST}"' EXIT
+
+fails=0
+pass() { echo "PASS: $1"; }
+fail() { echo "FAIL: $1 — $2"; fails=$((fails + 1)); }
+
+# run <dir>: capture combined stdout+stderr into $OUT and exit code into $RC.
+OUT=""
+RC=0
+run() {
+    OUT="$("${CHECK}" "$1" 2>&1)"
+    RC=$?
+}
+
+check_rc_nonzero() { # <name>
+    if [[ "${RC}" != "0" ]]; then pass "$1"; else fail "$1" "want nonzero rc, got 0"; fi
+}
+check_rc_zero() { # <name>
+    if [[ "${RC}" == "0" ]]; then pass "$1"; else fail "$1" "want rc=0, got ${RC}"; fi
+}
+check_contains() { # <name> <needle>
+    if [[ "${OUT}" == *"$2"* ]]; then pass "$1"; else fail "$1" "expected to contain: $2"; fi
+}
+check_absent() { # <name> <needle>
+    if [[ "${OUT}" != *"$2"* ]]; then pass "$1"; else fail "$1" "expected NOT to contain: $2"; fi
+}
+
+# --- Fixture 1: the #2050 regression — a bare '<= ' outside any code span. ---
+# The checker MUST fail closed here. If check 6 is removed, this token is not
+# a void element (check 1), autolink (check 4), or <name-start> tag (check 5),
+# so nothing else flags it and this assertion fails — proving the rule is what
+# catches it.
+DIR_HAZARD="${TMPDIR_TEST}/hazard"
+mkdir -p "${DIR_HAZARD}"
+cat >"${DIR_HAZARD}/bare-lt.md" <<'MD'
+# Bare less-than-or-equal hazard
+
+The TTFT p99 stays low (gate <= 2,000) under the calibrated inference gate.
+MD
+
+run "${DIR_HAZARD}"
+check_rc_nonzero "bare-lt-exits-nonzero"
+check_contains   "bare-lt-reported" "MDX: bare < not starting a valid tag"
+check_contains   "bare-lt-line-cited" "bare-lt.md:3:"
+
+# --- Fixture 2: the SAME token, but safely wrapped. No false positive. ---
+# Inline backtick span and fenced code block both hide the '<=' from every
+# check, so a clean fixture built only from wrapped hazards must pass.
+DIR_SAFE="${TMPDIR_TEST}/safe"
+mkdir -p "${DIR_SAFE}"
+cat >"${DIR_SAFE}/wrapped-lt.md" <<'MD'
+# Wrapped less-than-or-equal is safe
+
+The TTFT p99 stays low (gate `<= 2,000`) under the calibrated inference gate.
+
+```text
+inference-perf TTFT p99 gate <= 2,000 ms
+```
+
+A valid element like <br /> and a closing </div> must also stay clean.
+MD
+
+run "${DIR_SAFE}"
+check_rc_zero  "wrapped-lt-exits-zero"
+check_absent   "wrapped-lt-no-violation" "bare < not starting a valid tag"
+
+# --- Fixture 3: '<= ' inside a tilde (~~~) fenced code block. No false pos. ---
+# CommonMark honors ~~~ fences as code; the checker must skip their contents
+# just like ``` fences, so the hazard token stays hidden.
+DIR_TILDE="${TMPDIR_TEST}/tilde"
+mkdir -p "${DIR_TILDE}"
+cat >"${DIR_TILDE}/tilde-fence.md" <<'MD'
+# Tilde fence hides the hazard
+
+~~~
+inference-perf TTFT p99 gate <= 2,000 ms
+~~~
+MD
+
+run "${DIR_TILDE}"
+check_rc_zero  "tilde-fence-exits-zero"
+check_absent   "tilde-fence-no-violation" "bare < not starting a valid tag"
+
+# --- Fixture 4: '<= ' inside a double-backtick (``…``) span. No false pos. ---
+# CommonMark closes an N-backtick span at the next run of exactly N backticks;
+# the checker strips spans of any run length, so the '<=' inside is code.
+DIR_DBT="${TMPDIR_TEST}/dbt"
+mkdir -p "${DIR_DBT}"
+cat >"${DIR_DBT}/double-backtick.md" <<'MD'
+# Double-backtick span hides the hazard
+
+Use ``(gate <= 2,000)`` to express the inference gate inline.
+MD
+
+run "${DIR_DBT}"
+check_rc_zero  "double-backtick-exits-zero"
+check_absent   "double-backtick-no-violation" "bare < not starting a valid tag"
+
+# --- Fixture 5: a triple-backtick fence that CONTAINS a lone double-backtick. ---
+# The fence-length rule requires the closing run to be the SAME char and at
+# least as long as the opener, so an inner ``` shorter run (or the lone ``)
+# must NOT close the fence early and expose the hazard on a later line.
+DIR_LEN="${TMPDIR_TEST}/fencelen"
+mkdir -p "${DIR_LEN}"
+cat >"${DIR_LEN}/fence-length.md" <<'MD'
+# Fence-length rule keeps the block open
+
+```
+here is a lone `` double backtick inside the block
+inference-perf TTFT p99 gate <= 2,000 ms
+```
+MD
+
+run "${DIR_LEN}"
+check_rc_zero  "fence-length-exits-zero"
+check_absent   "fence-length-no-violation" "bare < not starting a valid tag"
+
+if (( fails > 0 )); then
+    echo "${fails} test(s) failed"
+    exit 1
+fi
+echo "All check-docs-mdx tests passed"