Filed unlabelled with suggested routing — domain:* and grading belong to triage. Suggested routing: domain:ui by the packages table (packages/types), though the subject is a gate, so domain:devx is defensible; triage decides.
Provenance: hit live by the dev implementing #6475 (PR #6704) while writing a docstring. Worked around in that PR by rewording; the gate itself is unchanged, so the next person to write a comment in that file meets it again with no warning.
The mechanism
packages/types/src/__tests__/zod-mirror-parity.test.ts's SPEC_DERIVED_PAIRS re-check determines which zod mirrors reference a spec schema by scanning raw text between export const boundaries in packages/types/src/zod/*.zod.ts, looking for a \bSpec[A-Z]\w* token.
It is a text scanner, not an AST reader. So it cannot distinguish:
- a real reference —
SpecGanttConfigSchema.extend(...) in code; from - the same token appearing in a comment.
What actually happened
The dev added a docstring above the privateGanttConfigExtensionFields const. That const sits textually between the ObjectTreeSchema and ObjectGanttSchema export boundaries. The docstring mentioned SpecGanttConfigSchema in prose.
The scanner attributed that mention to ObjectTreeSchema — a schema that references no spec schema at all — and SPEC_DERIVED_PAIRS matches what the mirror sources actually do went red.
Two properties make this expensive out of proportion to its size:
- A comment changed a gate's verdict. Nothing about the emitted types, the runtime, or the mirror's actual spec dependency moved. Prose did.
- The false attribution lands on the neighbouring export, not the one being edited. The red names
ObjectTreeSchema; the edit was near ObjectGanttSchema. Someone who did not write the docstring themselves has no reason to connect the failure to a comment several lines away, in a different declaration's window.
That combination — a green-to-red flip caused by prose, blamed on an innocent neighbour — is the signature of a gate people learn to route around individually rather than fix.
Why the workaround is not the fix
PR #6704 reworded the docstring to avoid the literal token and left a comment recording the trap. That was the correct call inside that PR's fence — it was a gantt card, not a gate card, and widening it would have been wrong.
But the resulting state is a gate whose correct usage is "do not mention certain identifiers in comments in this file", enforced by a comment that asks the next editor to remember. That is a convention held by discipline, which is precisely what a gate is supposed to replace.
Suggested directions (untried, not prescriptive)
- Strip comments before scanning. Cheapest fix, keeps the text-scanner shape; needs care with strings that contain comment-like sequences.
- Parse instead of scan. Most correct, most work; the file is TypeScript and the question ("does this export's initializer reference a
Spec* symbol?") is an AST query. - Attribute by declaration, not by text window. Even keeping the scan, a private
const between two exports currently has its text charged to whichever export precedes it. Whatever the token-matching rule, the windowing is independently wrong.
⚠️ Whoever takes this: the bug's own shape makes a naive test dangerous — a fixture that mentions a Spec* token in a comment must be asserted to produce no finding, and one that references it in code must still produce one. A fix that stops seeing comments and stops seeing real references would go green on the existing suite while destroying the gate. Show the positive direction still fires.
Refs: #6475 / PR #6704 (where it was hit, with the reworded docstring and trap marker) · #6472 (GanttConfigExtensionFields, the const whose docstring triggered it).
Filed unlabelled with suggested routing —
domain:*and grading belong to triage. Suggested routing:domain:uiby the packages table (packages/types), though the subject is a gate, sodomain:devxis defensible; triage decides.Provenance: hit live by the dev implementing #6475 (PR #6704) while writing a docstring. Worked around in that PR by rewording; the gate itself is unchanged, so the next person to write a comment in that file meets it again with no warning.
The mechanism
packages/types/src/__tests__/zod-mirror-parity.test.ts'sSPEC_DERIVED_PAIRSre-check determines which zod mirrors reference a spec schema by scanning raw text betweenexport constboundaries inpackages/types/src/zod/*.zod.ts, looking for a\bSpec[A-Z]\w*token.It is a text scanner, not an AST reader. So it cannot distinguish:
SpecGanttConfigSchema.extend(...)in code; fromWhat actually happened
The dev added a docstring above the private
GanttConfigExtensionFieldsconst. That const sits textually between theObjectTreeSchemaandObjectGanttSchemaexport boundaries. The docstring mentionedSpecGanttConfigSchemain prose.The scanner attributed that mention to
ObjectTreeSchema— a schema that references no spec schema at all — andSPEC_DERIVED_PAIRS matches what the mirror sources actually dowent red.Two properties make this expensive out of proportion to its size:
ObjectTreeSchema; the edit was nearObjectGanttSchema. Someone who did not write the docstring themselves has no reason to connect the failure to a comment several lines away, in a different declaration's window.That combination — a green-to-red flip caused by prose, blamed on an innocent neighbour — is the signature of a gate people learn to route around individually rather than fix.
Why the workaround is not the fix
PR #6704 reworded the docstring to avoid the literal token and left a comment recording the trap. That was the correct call inside that PR's fence — it was a gantt card, not a gate card, and widening it would have been wrong.
But the resulting state is a gate whose correct usage is "do not mention certain identifiers in comments in this file", enforced by a comment that asks the next editor to remember. That is a convention held by discipline, which is precisely what a gate is supposed to replace.
Suggested directions (untried, not prescriptive)
Spec*symbol?") is an AST query.constbetween two exports currently has its text charged to whichever export precedes it. Whatever the token-matching rule, the windowing is independently wrong.Spec*token in a comment must be asserted to produce no finding, and one that references it in code must still produce one. A fix that stops seeing comments and stops seeing real references would go green on the existing suite while destroying the gate. Show the positive direction still fires.Refs: #6475 / PR #6704 (where it was hit, with the reworded docstring and trap marker) · #6472 (
GanttConfigExtensionFields, the const whose docstring triggered it).