@@ -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 */
290291function 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()`. */
321350function 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+
502637describe ( '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