From f411d55591e2ce586fddc0373feef3f824ad9633 Mon Sep 17 00:00:00 2001
From: gsxdsm <gsxdsm@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:52:13 -0700
Subject: [PATCH] test(docs): the PLUGIN_AUTHORING TOC guard rejected legal
 nested entries, and has been red on main (#3036)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## A legal Markdown sub-entry turned this guard red

```
AssertionError: Invalid TOC line: - [Theming & Overlay Layering for Dashboard Views](#theming--overlay-layering-for-dashboard-views)
```

That line is an ordinary nested TOC entry, indented under item 8 of
`docs/PLUGIN_AUTHORING.md`. The parser did `.map(line => line.trim())`
**first** and then required every line to match the top-level `N.
[title](#anchor)` shape — so indentation, the one thing distinguishing a
sub-entry from a malformed top-level one, was destroyed before it could
be used.

**The doc was never wrong.** Only the parser was, and it has been red on
`main` since the entry was added.

Indentation is now read before trimming. Sub-entries are still required
to be well-formed links; they just do not participate in the numbering
or the count.

## Both guard directions verified by breaking them

A looser parser that skipped anything unrecognised would have made the
failure go away while quietly ending the guard's usefulness — so I
checked it still fails in both directions:

| mutation | result |
| --- | --- |
| top-level `9.` rewritten as a bullet | still fails (`Invalid TOC
line`) |
| nested entry replaced with un-linked prose | still fails (`Invalid
nested TOC line`) |

## The wider finding, which matters more than this fix

I found it by sweeping `scripts/__tests__` against clean `main`: **688
passing, 7 failing test files.**

| suite | failing assertion |
| --- | --- |
| `ci-test-shard-timings` | committed timing snapshot references live
test files |
| `dependency-security-floor` | pnpm overrides pin transitive protobufjs
to a safe floor |
| `engine-vitest-gate-policy` | pg gate canaries remain a subset of the
enabled suite |
| `plugin-authoring-docs` | **this PR** |
| `release-prompt-gate` | release dry-run exits before proceed
confirmation |
| `verify-fast` | defaults to every canonical pretest validator |
| `workflow-reliability-release-check` | manifest references existing
seam files |

All sit **outside the merge gate**. That is now the third instance of
this pattern I have hit — #2969's 15 red agent-action tests and #3033's
stale ratchet list were the others — and it is clearly systemic rather
than incidental.

I fixed only the one in plugin territory. The rest span CI sharding,
**dependency security** (that protobufjs floor is a security assertion
currently not holding), release gating and workflow manifests. Each
needs its owner's judgement about whether the assertion or the world is
wrong, and a drive-by "make it green" is exactly how a real signal gets
erased — `dependency-security-floor` especially.

## Verification (measured)

- this suite — **4 passed / 0 failed** (was 1 failed)
- `eslint` — clean

Test-only; the doc is untouched. No changeset.
---
 .../__tests__/plugin-authoring-docs.test.mjs  | 25 ++++++++++++++++---
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/scripts/__tests__/plugin-authoring-docs.test.mjs b/scripts/__tests__/plugin-authoring-docs.test.mjs
index 4d933a4ade..1e1a57ee03 100644
--- a/scripts/__tests__/plugin-authoring-docs.test.mjs
+++ b/scripts/__tests__/plugin-authoring-docs.test.mjs
@@ -54,10 +54,27 @@ test("PLUGIN_AUTHORING TOC includes top-level dashboard views and anchors align
   const tocMatch = doc.match(/## Table of Contents\n\n([\s\S]*?)\n---/);
   assert.ok(tocMatch, "Table of Contents block should exist");
 
-  const tocLines = tocMatch[1]
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean);
+  /*
+  FNXC:PluginAuthoringDocs 2026-07-31-18:20:
+  NESTED TOC entries are legal Markdown, and this parser rejected them by flattening indentation away.
+
+  `- [Theming & Overlay Layering for Dashboard Views](...)` sits indented under item 8 — an ordinary
+  sub-entry. The old code trimmed every line first and then required ALL of them to match the
+  top-level `N. [title](#anchor)` shape, so adding a perfectly valid sub-entry turned this assertion
+  red on `main`, and it has been red since.
+
+  Indentation is the discriminator, so it is read BEFORE trimming. Sub-entries are still required to
+  be well-formed links — they are simply not top-level sections and do not participate in the
+  numbering or the count. A malformed TOP-LEVEL line still fails exactly as before, which is the guard
+  this test exists to be.
+  */
+  const rawTocLines = tocMatch[1].split("\n").filter((line) => line.trim());
+  const subEntries = rawTocLines.filter((line) => /^\s+/.test(line));
+  for (const line of subEntries) {
+    assert.ok(/^\s+-\s+\[.+\]\(#.+\)$/.test(line.replace(/\s+$/, "")), `Invalid nested TOC line: ${line}`);
+  }
+
+  const tocLines = rawTocLines.filter((line) => !/^\s/.test(line)).map((line) => line.trim());
 
   const tocEntries = tocLines.map((line) => {
     const m = line.match(/^(\d+)\.\s+\[(.+)\]\(#(.+)\)$/);