Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 234f96b

Browse files
committed
fix(types): the filter-builder doc reader strips comments before it locates the terminator
objectui#9073. `docUnionMembers` located the terminating `;` of a union in the RAW interface block and stripped line comments only afterwards, so a `;` inside a comment on one of the union's own rows ended the slice early: the published doc's fourteen-member `type?:` union read as eight, and the mirror/doc pin then announced "the mirror widened past the authority" for six members the doc does publish. The defect is that false positive, not the under-count — the verdict sends a reader looking for a widening nobody made. Comments now come off first and `at` is computed on the stripped block: the strip shortens it, so an index taken before it addresses a different place after it, and carrying one across drops the union's LEADING members instead. Both hazards are pinned, plus a control that is green in both worlds and a characterisation of the one branch whose outcome moves (a union whose only `;` lives in a comment is now `is unterminated`, loudly, rather than silently truncated). The published doc is untouched: the defect was in the reader, never in the surface it reads. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UzHd6hDYatoDn17BuwKxnZ
1 parent 4784bb3 commit 234f96b

2 files changed

Lines changed: 174 additions & 9 deletions

File tree

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
---
3+
4+
Test-only: `packages/types/src/__tests__/filter-builder-mirror-6939.test.ts`. It sits
5+
under `src/`, so the presence gate counts it, but nothing published moves — the
6+
package's build `tsconfig.json` excludes `**/__tests__/**` and its `files` list is
7+
`["dist", "README.md", "CHANGELOG.md", "LICENSE"]`, so the file never reaches a
8+
consumer. Declared as releasing nothing.
9+
10+
objectui#9073: the doc reader objectui#8774 introduced located the terminating `;` of a
11+
union in the RAW interface block and stripped line comments only afterwards. A `;`
12+
inside a comment on one of the union's own rows therefore ended the slice early — the
13+
published doc's FOURTEEN-member `type?:` union read as EIGHT — and the mirror/doc pin
14+
then rendered *this mirror accepts `type` members … never published — the mirror
15+
widened past the authority.* for six members the doc does publish.
16+
17+
⭐ The defect is the FALSE POSITIVE, not the under-count: that verdict sends whoever
18+
reads it to look for a widening nobody made, and a checker that lies confidently is
19+
worse than one that stays quiet.
20+
21+
Comments now come off BEFORE the key is located, and `at` is computed on the stripped
22+
block — stripping shortens it, so an index taken before the strip addresses a different
23+
place after it, and carrying one across drops the union's LEADING members instead. Both
24+
hazards are pinned, alongside a control that is green in both worlds.
25+
26+
⛔ No accept set moves and the published doc is untouched: the defect was in the reader,
27+
never in the surface it reads. One existing throw branch changes outcome — a union whose
28+
only `;` lives in a comment is now `is unterminated` (loud) rather than a silently
29+
truncated set; the throw's wording is unchanged and the two throws the floor test pins
30+
are unaffected.

‎packages/types/src/__tests__/filter-builder-mirror-6939.test.ts‎

Lines changed: 144 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -284,16 +284,28 @@ function docInterfaceBlock(doc: string, iface: string): string {
284284
* Every quoted member of the union `<iface>.<key>` declares, in the doc's own
285285
* order. The union may span LINES — the doc lays `type?:` out over five rows —
286286
* so the slice runs to the terminating `;`, not to the end of the line. Line
287-
* comments are stripped first: `// Field type` sits inside that slice, and an
288-
* apostrophe in some future one would otherwise mint a phantom member.
287+
* comments are stripped first: `// Field type` sits inside that slice, an
288+
* apostrophe in some future one would otherwise mint a phantom member, and a
289+
* `;` in one would otherwise be mistaken for the terminator (objectui#9073).
289290
*/
290291
function docUnionMembers(doc: string, iface: string, key: string): string[] {
291-
const block = docInterfaceBlock(doc, iface);
292+
// ⛔ Comments come off FIRST, and everything after this line addresses the
293+
// stripped block only (objectui#9073). Locating the terminating `;` in the
294+
// raw block and stripping afterwards let a `;` inside a union-row comment
295+
// end the slice early: the fourteen-member union read as eight, and the
296+
// mirror/doc pin then announced a widening that had not happened — a
297+
// confident lie, which is worse than silence.
298+
//
299+
// ⚠️ And it is a two-sided fix, not a one-line one: stripping SHORTENS the
300+
// block, so an index taken before the strip addresses a different place
301+
// after it. `at` is therefore computed here, on the stripped block, and
302+
// never carried across from the raw one.
303+
const block = docInterfaceBlock(doc, iface).replace(/\/\/[^\n]*/g, '');
292304
const at = block.indexOf(`\n ${key}:`);
293305
if (at === -1) throw new Error(`${DOC}: \`${iface}\` no longer declares \`${key}\``);
294306
const end = block.indexOf(';', at);
295307
if (end === -1) throw new Error(`${DOC}: \`${iface}.${key}\` is unterminated`);
296-
const body = block.slice(at, end).replace(/\/\/[^\n]*/g, '');
308+
const body = block.slice(at, end);
297309
const members = [...body.matchAll(/'([^']*)'/g)].map((m) => m[1]);
298310
if (members.length === 0) {
299311
throw new Error(`${DOC}: \`${iface}.${key}\` parsed to ZERO members`);
@@ -317,6 +329,23 @@ function documentedTypes(): string[] {
317329
return docUnionMembers(publishedDoc(), 'FilterField', 'type?');
318330
}
319331

332+
/**
333+
* The "the mirror widened past the authority" verdict, as a function and a
334+
* sentence rather than an expression buried in one assertion (objectui#9073).
335+
*
336+
* It is lifted out because a controlled input has to be pushed through THE SAME
337+
* comparison and THE SAME sentence the pin renders — a copy of either could
338+
* drift away from the thing it is there to vouch for, and this diagnosis is
339+
* exactly the one that was observed to fire falsely.
340+
*/
341+
const WIDENED_MESSAGE =
342+
`this mirror accepts \`type\` members ${DOC} never published — the mirror widened ` +
343+
`past the authority.`;
344+
345+
function widenedPastTheDoc(documented: string[]): string[] {
346+
return mirrorTypeMembers().filter((t) => !documented.includes(t));
347+
}
348+
320349
/** The enum this mirror actually declares, behind `.optional()`. */
321350
function mirrorTypeMembers(): string[] {
322351
return (FilterFieldSchema as unknown as {
@@ -429,11 +458,7 @@ describe('objectui#6939 — the type vocabulary', () => {
429458
`way objectui#4814 retired \`owner\` — reappearing in it is a doc REGRESSION, ` +
430459
`not a widening, and the doc edit is what gets reverted.`,
431460
).toEqual([]);
432-
expect(
433-
declared.filter((t) => !documented.includes(t)),
434-
`this mirror accepts \`type\` members ${DOC} never published — the mirror widened ` +
435-
`past the authority.`,
436-
).toEqual([]);
461+
expect(widenedPastTheDoc(documented), WIDENED_MESSAGE).toEqual([]);
437462
expect([...declared].sort()).toEqual([...documented].sort());
438463
});
439464

@@ -499,6 +524,116 @@ describe('objectui#6939 — the type vocabulary', () => {
499524
});
500525
});
501526

527+
/* ── objectui#9073 — the reader's comment/terminator ORDER ────────────────── */
528+
529+
/**
530+
* The fixtures below are CONTROLLED INPUTS, not declarations found in this
531+
* tree, and that is the shape of the card: objectui#9073 is a defect in a
532+
* test-embedded READER, so nothing in the shipped surface is wrong and there is
533+
* nothing to find. No comment anywhere in the published doc carries a `;`
534+
* today — a fixture claiming to have found one would be describing a tree that
535+
* does not exist.
536+
*
537+
* So each one is the REAL doc with exactly one comment rewritten, anchored to a
538+
* literal row rather than hand-written, so that the fixture cannot quietly
539+
* become a straw man when the doc moves: a vanished anchor THROWS.
540+
*/
541+
const UNION_ROW = " | 'date' | 'datetime' | 'time'\n";
542+
const EARLIER_ROW = " value: string; // Field identifier\n";
543+
544+
function docWith(anchor: string, replacement: string): string {
545+
const doc = publishedDoc();
546+
if (!doc.includes(anchor)) {
547+
throw new Error(
548+
`${DOC}: objectui#9073 fixture anchor ${JSON.stringify(anchor)} is gone — ` +
549+
`the fixture no longer perturbs the doc it claims to perturb`,
550+
);
551+
}
552+
// Function replacement: a literal `$&`/`$1` in the text would otherwise be a
553+
// substitution pattern rather than the bytes written here.
554+
return doc.replace(anchor, () => replacement);
555+
}
556+
557+
describe('objectui#9073 — the doc reader strips comments BEFORE it locates the terminator', () => {
558+
it('a `;` inside a union-row comment no longer truncates the union — nor reports a widening that never happened', () => {
559+
// ⭐ What this card is about is the FALSE POSITIVE, not the under-count.
560+
// The reader used to locate the terminating `;` in the RAW block and strip
561+
// comments only afterwards, so the `;` in the comment injected below ended
562+
// the slice EIGHT members in. The mirror's fourteen then read as six
563+
// members the doc "never published", and the pin above rendered
564+
// WIDENED_MESSAGE — announcing a widening nobody had made and sending
565+
// whoever read it to look for a change that does not exist. A reader that
566+
// under-counts a mirror does not stay quiet; it lies confidently.
567+
const poisoned = docWith(
568+
UNION_ROW,
569+
" | 'date' | 'datetime' | 'time' // dates; and date-times\n",
570+
);
571+
const documented = docUnionMembers(poisoned, 'FilterField', 'type?');
572+
// The DIAGNOSIS first, deliberately: through the same function and the
573+
// same sentence the pin renders rather than a copy of either, so the red
574+
// run prints the false verdict itself and not a symptom of it.
575+
expect(widenedPastTheDoc(documented), WIDENED_MESSAGE).toEqual([]);
576+
// …and the read underneath it, seeded from the authority rather than from
577+
// a count kept here — the reason objectui#8774 deleted this file's
578+
// hand-kept `DOCUMENTED_FOURTEEN`.
579+
expect(documented).toEqual(documentedTypes());
580+
});
581+
582+
it('a `;` in a comment BEFORE the key keeps the anchor in ONE coordinate system', () => {
583+
// ⚠️ The trap in the one-line reading of this repair. Stripping comments
584+
// SHORTENS the block, so an index computed on the raw block addresses a
585+
// different place in the stripped one. An implementation that strips the
586+
// comments but carries the old `at` across starts its slice INSIDE the
587+
// union and silently drops the LEADING members — a second wrong answer
588+
// reached from the same fix, and one the test above cannot see.
589+
//
590+
// The comment rewritten here sits BEFORE `type?:`, so it never enters the
591+
// slice at all and cannot affect the terminator search either. It can only
592+
// be caught by that coordinate shift, which is why it is a separate leg.
593+
const shifted = docWith(
594+
EARLIER_ROW,
595+
" value: string; // Field identifier; never the label\n",
596+
);
597+
expect(docUnionMembers(shifted, 'FilterField', 'type?')).toEqual(documentedTypes());
598+
});
599+
600+
it('CONTROL — a doc with no `;` in any comment reads identically in both worlds', () => {
601+
// ⚠️ Named a control because it CANNOT tell the two worlds apart: the
602+
// published doc carries no `;` inside a comment, so this is green before
603+
// the repair and green after it. It is here so the two legs above are
604+
// readable as perturbations of a known-good answer — ⛔ it is not evidence
605+
// that the repair works, and it must not be counted as any.
606+
expect(docUnionMembers(publishedDoc(), 'FilterGroup', 'logic')).toEqual(['and', 'or']);
607+
expect(widenedPastTheDoc(documentedTypes()), WIDENED_MESSAGE).toEqual([]);
608+
});
609+
610+
it('a union whose only `;` is inside a comment is UNTERMINATED — loudly, not truncated silently', () => {
611+
// The ONE existing branch this repair moves, recorded here rather than
612+
// discovered by somebody later. Before: the comment's `;` was accepted as
613+
// the terminator and the reader returned a truncated set in silence.
614+
// After: the comment is gone before the search runs, the block genuinely
615+
// has no terminator past the key, and `is unterminated` fires — the throw
616+
// that was already here, wording untouched. Silent-and-wrong → loud is the
617+
// direction this file already declares for its readers ("absence is LOUD
618+
// here"); the two throws pinned in the floor test are not moved at all.
619+
//
620+
// Hand-written rather than doc-anchored, and it has to be: the real block
621+
// carries further `;` after the union (`options?: Array<{ … }>;`), so no
622+
// edit to a COMMENT can leave the real block unterminated.
623+
const handWritten = [
624+
'interface FilterField {',
625+
' type?:',
626+
" | 'text'",
627+
" | 'number' // no terminator past here; only this comment has one",
628+
'}',
629+
'',
630+
].join('\n');
631+
expect(() => docUnionMembers(handWritten, 'FilterField', 'type?')).toThrow(
632+
'`FilterField.type?` is unterminated',
633+
);
634+
});
635+
});
636+
502637
describe('objectui#6939 — the group shape is `{ id, logic, conditions }`', () => {
503638
it('accepts the shape the catalog authors and `EMPTY_GROUP` emits', () => {
504639
expect(FilterGroupSchema.safeParse({ id: 'root', logic: 'and', conditions: [] }).success).toBe(true);

0 commit comments

Comments
 (0)