|
| 1 | +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * Pin for how the reference-docs generator escapes `{…}` / `<…>` inside |
| 5 | + * `.describe()` prose — #5452. |
| 6 | + * |
| 7 | + * The escaper wrapped a delimited fragment in an inline-code span, but found |
| 8 | + * its closing partner with `indexOf`, i.e. the FIRST closer rather than the |
| 9 | + * MATCHING one. Nested delimiters are not an exotic input here — `{{var}}` is |
| 10 | + * the template-interpolation syntax the spec's own prose *teaches*, and a |
| 11 | + * filter map (`{ status: { $in: [...] } }`) is an ordinary example — so the |
| 12 | + * wrap ended at the inner `}` and the outer one fell outside the span: |
| 13 | + * `{{var}}` was published as `` `{{var}` `` plus a stray `}`. |
| 14 | + * |
| 15 | + * The issue counted three sites (`grep -rn '`{{' content/docs/references/`). |
| 16 | + * The corpus gate below counts FIVE, because that grep only sees the fragments |
| 17 | + * whose nesting starts at character one; `ai/solution-blueprint.mdx` and |
| 18 | + * `api/analytics.mdx` were cut in exactly the same place with a single leading |
| 19 | + * brace, and no grep for `` `{{ `` could have found them. |
| 20 | + * |
| 21 | + * MEASURED (reverse verification), both directions run: |
| 22 | + * - restoring the old matcher (`raw.indexOf(close, i + 1)` in place of |
| 23 | + * `findMatchingClose`) turns all five nested-delimiter unit cases red |
| 24 | + * (`5 failed | 7 passed`), each reporting the split shape; |
| 25 | + * - and, after re-running `gen:docs` over the restored escaper, the corpus |
| 26 | + * gate goes red with 5 offenders — the same 5 that were on `main`. |
| 27 | + * The direction is the ordinary one (restore the defect → the new pins go red) |
| 28 | + * because these assert a POSITIVE output shape the fix produces, not the |
| 29 | + * absence of a finding. The single-delimiter and unmatched cases stay green |
| 30 | + * either way, which is exactly why the bug survived: the escaper was correct |
| 31 | + * on every shape anyone had thought to look at. |
| 32 | + */ |
| 33 | + |
| 34 | +import fs from 'fs'; |
| 35 | +import path from 'path'; |
| 36 | +import url from 'url'; |
| 37 | + |
| 38 | +import { describe, expect, it } from 'vitest'; |
| 39 | + |
| 40 | +import { escapeMdxDescription } from './lib/escape-mdx'; |
| 41 | + |
| 42 | +const HERE = path.dirname(url.fileURLToPath(import.meta.url)); |
| 43 | +const REPO = path.resolve(HERE, '../../..'); |
| 44 | +const REFERENCES = path.join(REPO, 'content/docs/references'); |
| 45 | + |
| 46 | +describe('escapeMdxDescription — nested delimiters (#5452)', () => { |
| 47 | + it('wraps `{{var}}` whole, leaving no stray closer outside the span', () => { |
| 48 | + expect(escapeMdxDescription('System prompt — supports {{var}} interpolation')).toBe( |
| 49 | + 'System prompt — supports `{{var}}` interpolation', |
| 50 | + ); |
| 51 | + }); |
| 52 | + |
| 53 | + it('wraps a doubled brace inside parentheses (the automation/flow.mdx specimen)', () => { |
| 54 | + expect( |
| 55 | + escapeMdxDescription( |
| 56 | + 'Downstream nodes read prior outputs via expressions ({{nodeId.field}}) regardless.', |
| 57 | + ), |
| 58 | + ).toBe('Downstream nodes read prior outputs via expressions (`{{nodeId.field}}`) regardless.'); |
| 59 | + }); |
| 60 | + |
| 61 | + it('wraps a singly-nested filter map whole (the ai/solution-blueprint.mdx specimen)', () => { |
| 62 | + // The variant `grep '`{{'` could not see: nesting that starts one char in. |
| 63 | + expect(escapeMdxDescription('e.g. { status: { $in: ["received"] } }.')).toBe( |
| 64 | + 'e.g. `{ status: { $in: ["received"] } }`.', |
| 65 | + ); |
| 66 | + }); |
| 67 | + |
| 68 | + it('wraps nested angle delimiters whole', () => { |
| 69 | + // The span opens at the delimiter, not at the identifier in front of it — |
| 70 | + // pre-existing behaviour, and MDX-safe either way. What #5452 changes is |
| 71 | + // that BOTH closing `>` land inside the span instead of one leaking out. |
| 72 | + expect(escapeMdxDescription('Shaped as Array<Record<string, any>> at rest')).toBe( |
| 73 | + 'Shaped as Array`<Record<string, any>>` at rest', |
| 74 | + ); |
| 75 | + }); |
| 76 | + |
| 77 | + it('wraps each of two independent doubled pairs on one line', () => { |
| 78 | + expect(escapeMdxDescription('render {{a.b}} then {{c}} here')).toBe( |
| 79 | + 'render `{{a.b}}` then `{{c}}` here', |
| 80 | + ); |
| 81 | + }); |
| 82 | +}); |
| 83 | + |
| 84 | +describe('escapeMdxDescription — shapes the fix must not disturb', () => { |
| 85 | + it('still wraps a single `{…}` pair', () => { |
| 86 | + expect(escapeMdxDescription('a {token} b')).toBe('a `{token}` b'); |
| 87 | + }); |
| 88 | + |
| 89 | + it('still wraps a `{<id>}` nest in ONE span (no inner backticks)', () => { |
| 90 | + expect(escapeMdxDescription('path {<id>} here')).toBe('path `{<id>}` here'); |
| 91 | + }); |
| 92 | + |
| 93 | + it('still entity-escapes a lone `<` with no partner (SemVer range)', () => { |
| 94 | + expect(escapeMdxDescription('supports >=4.0 <5 only')).toBe('supports >=4.0 <5 only'); |
| 95 | + }); |
| 96 | + |
| 97 | + it('still entity-escapes a lone `{` with no partner', () => { |
| 98 | + expect(escapeMdxDescription('an unclosed { here')).toBe('an unclosed { here'); |
| 99 | + }); |
| 100 | + |
| 101 | + it('still leaves fragments already inside an inline-code span untouched', () => { |
| 102 | + expect(escapeMdxDescription('see `{{var}}` above')).toBe('see `{{var}}` above'); |
| 103 | + }); |
| 104 | +}); |
| 105 | + |
| 106 | +/** |
| 107 | + * Corpus gate over the generator's committed OUTPUT. |
| 108 | + * |
| 109 | + * The invariant is brace BALANCE inside an inline-code span, not the literal |
| 110 | + * `` `{{ ``-plus-stray-`}` string the issue grepped for. Balance is what the |
| 111 | + * defect actually violates — the wrap cut a pair in half — so it catches the |
| 112 | + * two sites whose nesting did not start at character one, and it keeps |
| 113 | + * catching them when the offending prose is reworded. |
| 114 | + * |
| 115 | + * Angle delimiters deliberately get NO corpus gate: `<`/`>` are also the |
| 116 | + * comparison operators, and validation-rule / SemVer examples legitimately |
| 117 | + * carry an unbalanced one inside a code span (`record.amount < 0`, |
| 118 | + * `>=1.2.3`) — 11 such spans, all correct. Nesting for angles is pinned by |
| 119 | + * the positive unit case above instead. Backslash-escaped delimiters are not |
| 120 | + * delimiters: the module-JSDoc path escapes braces as `\{`, so they are |
| 121 | + * dropped before counting. |
| 122 | + */ |
| 123 | +describe('published reference pages keep inline-code braces balanced (#5452)', () => { |
| 124 | + const pages: string[] = []; |
| 125 | + const walk = (dir: string) => { |
| 126 | + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { |
| 127 | + const full = path.join(dir, entry.name); |
| 128 | + if (entry.isDirectory()) walk(full); |
| 129 | + else if (entry.name.endsWith('.mdx')) pages.push(full); |
| 130 | + } |
| 131 | + }; |
| 132 | + walk(REFERENCES); |
| 133 | + |
| 134 | + it('finds the generated reference corpus', () => { |
| 135 | + expect(pages.length).toBeGreaterThan(50); |
| 136 | + }); |
| 137 | + |
| 138 | + it('has no inline-code span with an unbalanced brace', () => { |
| 139 | + const offenders: string[] = []; |
| 140 | + for (const file of pages) { |
| 141 | + const rel = path.relative(REPO, file); |
| 142 | + fs.readFileSync(file, 'utf-8') |
| 143 | + .split('\n') |
| 144 | + .forEach((line, index) => { |
| 145 | + // Odd segments of a backtick split are the inline-code spans. |
| 146 | + const segments = line.split('`'); |
| 147 | + for (let i = 1; i < segments.length; i += 2) { |
| 148 | + const span = segments[i].replace(/\\[{}]/g, ''); |
| 149 | + const opens = span.split('{').length - 1; |
| 150 | + const closes = span.split('}').length - 1; |
| 151 | + if (opens !== closes) offenders.push(`${rel}:${index + 1} \`${segments[i]}\``); |
| 152 | + } |
| 153 | + }); |
| 154 | + } |
| 155 | + expect(offenders).toEqual([]); |
| 156 | + }); |
| 157 | +}); |
0 commit comments