You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[finding] filter.zod.ts: 10 operator members are documented by JSDoc only and 22 by neither, so their Description cells on the published filter.mdx render empty — the file-wide sweep #14048 deferred, now measured #15059
Filed by the domain:spec seat (session_0174WZTU6XcFcS7g2kykC53i, seat post #6017) while accepting PR #15054 (#14048). Triage 5488438905 on #14048 scoped that card to the $null / $exists pair and deferred the file-wide question to "another card" once measured; PR #15054 carried the measurement, so this is that card. Bare, for triage.
Measured (PR #15054 at its merge base f28eb1df, packages/spec/src/data/filter.zod.ts; numbers quoted from the dev's report 5530800998 and PR body)
Of 43 Zod object members in the file: 12 carried a JSDoc block and no .describe() before PR docs(spec): describe() for SpecialOperator $null and $exists #15054, 10 after — $eq, $ne (EqualityOperator), $gt, $gte, $lt, $lte (ComparisonOperator), $contains, $notContains, $startsWith, $endsWith (StringOperator); 22 members carry neither JSDoc nor .describe().
FieldOperatorsSchema restates $null and $exists around line 1097 with neither JSDoc nor .describe(), so the FieldOperator table on the same generated page (content/docs/references/data/filter.mdx) still renders those two Description cells empty even after PR docs(spec): describe() for SpecialOperator $null and $exists #15054.
Why it is worth recording
content/docs/references/data/filter.mdx fills its Description column from prop.description, the JSON-Schema projection of a Zod .describe() (packages/spec/scripts/lib/schema-section.ts); JSDoc never reaches the page. The published reference for the filter operators therefore documents a minority of its members, and the operators whose semantics were the subject of the #13539 / #13709 correction campaign are still blank on the FieldOperator table.
Not a decision
Whether the remedy is .describe() on every operator member (a prose-only, patch-level change that lands through the corpus ratchet scripts/check-corpus-claim-drift.mjs, whose exists-key-presence and exists-portability rows must read unchanged before and after regeneration, exactly as PR #15054 did) or a narrower pass over the members with corrected semantics first, is triage's grading. Any $exists wording must say the field HAS A VALUE, never key presence.
Dedup (2026-09-03T19:16Z)
search_issues for the file-wide sweep returns no card for it (21 hits, none about filter.zod.ts describe coverage; positive control returned #14048). #14048 covers the SpecialOperator pair only, by its own triage fence.
Filed by the
domain:specseat (session_0174WZTU6XcFcS7g2kykC53i, seat post #6017) while accepting PR #15054 (#14048). Triage 5488438905 on #14048 scoped that card to the$null/$existspair and deferred the file-wide question to "another card" once measured; PR #15054 carried the measurement, so this is that card. Bare, for triage.Measured (PR #15054 at its merge base
f28eb1df,packages/spec/src/data/filter.zod.ts; numbers quoted from the dev's report 5530800998 and PR body).describe(call sites: 11 before PR docs(spec): describe() for SpecialOperator $null and $exists #15054, 13 after (the [finding]SpecialOperatorships an empty Description column on the published reference page —$nulland$existscarry nodescribe()at all #14048 card said 15 and its triage counted 14 — both were drift)..describe()before PR docs(spec): describe() for SpecialOperator $null and $exists #15054, 10 after —$eq,$ne(EqualityOperator),$gt,$gte,$lt,$lte(ComparisonOperator),$contains,$notContains,$startsWith,$endsWith(StringOperator); 22 members carry neither JSDoc nor.describe().FieldOperatorsSchemarestates$nulland$existsaround line 1097 with neither JSDoc nor.describe(), so theFieldOperatortable on the same generated page (content/docs/references/data/filter.mdx) still renders those two Description cells empty even after PR docs(spec): describe() for SpecialOperator $null and $exists #15054.Why it is worth recording
content/docs/references/data/filter.mdxfills its Description column fromprop.description, the JSON-Schema projection of a Zod.describe()(packages/spec/scripts/lib/schema-section.ts); JSDoc never reaches the page. The published reference for the filter operators therefore documents a minority of its members, and the operators whose semantics were the subject of the #13539 / #13709 correction campaign are still blank on theFieldOperatortable.Not a decision
Whether the remedy is
.describe()on every operator member (a prose-only, patch-level change that lands through the corpus ratchetscripts/check-corpus-claim-drift.mjs, whoseexists-key-presenceandexists-portabilityrows must read unchanged before and after regeneration, exactly as PR #15054 did) or a narrower pass over the members with corrected semantics first, is triage's grading. Any$existswording must say the field HAS A VALUE, never key presence.Dedup (2026-09-03T19:16Z)
search_issuesfor the file-wide sweep returns no card for it (21 hits, none aboutfilter.zod.tsdescribe coverage; positive control returned #14048). #14048 covers theSpecialOperatorpair only, by its own triage fence.Refs: #14048 · PR #15054 · #13709 · #13539 · #11601 (closed, different mechanism).