Found while implementing #10791's fence-aware orphan scan
(packages/spec/scripts/check-skill-examples.ts).
The gap
#10791 fixed the orphan scan to be fence-aware (fenceSpans(), lifted from
scripts/check-role-word.mjs's #10533 shape): a marker shown as example text inside a
wrapping fence (e.g. a ```md illustration) is no longer flagged as a misplaced
marker. That fix deliberately left the marked-block extraction loop untouched — it
still recognizes a bare ```ts/```tsx/```typescript fence-open line with no
notion of being inside some other (non-ts) fence, because #10791's card scoped the fix to
the orphan-scan defect only.
That means a fully worked nested illustration — the marker and a real
```ts fence-open, both written as literal text inside an outer wrapping fence (e.g. a
`````` fence wrapping a ```ts example, the same shape #10533's self-test covers for
check-role-word.mjs) — would still misfire: the extraction loop would treat the nested
marker+fence as a genuine top-level block, extract its body, and hand it to `tsc` as if it
were a real example. Depending on what the illustration's placeholder code looks like,
that either compiles by luck or fails the whole gate with a diagnostic that points at
documentation prose, not a real example.
Status
Latent, unconfirmed by a run. Source-derived from reading extractFromFile's two
loops side by side; #10791's own reproduction only exercised the "marker alone, no nested
fence" case (which #10791 fixes correctly and completely). Today's corpus has no
occurrence of a marker and a full nested ts-fence pair inside a wrapping fence, so
nothing currently trips this.
Suggested shape
Two options, un-adjudicated here:
- Make the extraction loop share
fenceSpans() too — skip a ts/tsx/typescript
fence-open line that falls inside some larger non-ts fence's span, the same way the
orphan scan now does. - Leave extraction as-is and instead document (in the file's header comment) that a
worked nested example is unsupported — only a bare marker illustration is safe to
nest — so a future doc author knows the boundary.
Not fixed in #10791's PR: different failure mode (mis-extraction vs. false orphan) from a
different card, and #10791's triage ruling scoped that PR to the orphan-scan defect only.
Found while implementing #10791's fence-aware orphan scan
(
packages/spec/scripts/check-skill-examples.ts).The gap
#10791 fixed the orphan scan to be fence-aware (
fenceSpans(), lifted fromscripts/check-role-word.mjs's #10533 shape): a marker shown as example text inside awrapping fence (e.g. a
```mdillustration) is no longer flagged as a misplacedmarker. That fix deliberately left the marked-block extraction loop untouched — it
still recognizes a bare
```ts/```tsx/```typescriptfence-open line with nonotion of being inside some other (non-ts) fence, because #10791's card scoped the fix to
the orphan-scan defect only.
That means a fully worked nested illustration — the marker and a real
```tsfence-open, both written as literal text inside an outer wrapping fence (e.g. a`````` fence wrapping a ```ts example, the same shape #10533's self-test covers for
check-role-word.mjs) — would still misfire: the extraction loop would treat the nestedmarker+fence as a genuine top-level block, extract its body, and hand it to `tsc` as if it
were a real example. Depending on what the illustration's placeholder code looks like,
that either compiles by luck or fails the whole gate with a diagnostic that points at
documentation prose, not a real example.
Status
Latent, unconfirmed by a run. Source-derived from reading
extractFromFile's twoloops side by side; #10791's own reproduction only exercised the "marker alone, no nested
fence" case (which #10791 fixes correctly and completely). Today's corpus has no
occurrence of a marker and a full nested ts-fence pair inside a wrapping fence, so
nothing currently trips this.
Suggested shape
Two options, un-adjudicated here:
fenceSpans()too — skip ats/tsx/typescriptfence-open line that falls inside some larger non-ts fence's span, the same way the
orphan scan now does.
worked nested example is unsupported — only a bare marker illustration is safe to
nest — so a future doc author knows the boundary.
Not fixed in #10791's PR: different failure mode (mis-extraction vs. false orphan) from a
different card, and #10791's triage ruling scoped that PR to the orphan-scan defect only.