Complete the public type surface and narrow closed-union output fields - #172
Merged
Conversation
Every type named inside an exported type is now itself exported from the package root, so a consumer can import the type of any field instead of hand-rolling its shape. Adds the transitively-referenced fact types (CaptureMode, TargetLane, WorkloadLane, Measured, the CPU-breakdown slices, the layout-shift / soft-nav / thrash / dirtied-by / sourcemap shapes, the raw profile node/frame types, and the driver StepOpts/Until) as named re-exports. Narrow the closed-union output fields off `string`: RecordingMeta.capture and GroupSpanMember.mode to the capture-mode union (extended in record/capture.ts with the node-cpu/node-alloc lanes), and the query views' `target` to "chrome" | "firefox" | "node" (a new TargetLane, the return of recordingLane). RecordingMeta gains a doc note that it carries no `kind` discriminant, the field that marks the sibling run-group manifest. A new unit guard (test/unit/export-completeness.test.mjs) walks the emitted declarations with the TypeScript API and fails if any type reachable from a public export is not itself exported, so this cannot silently regress.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two additive / output-narrowing changes to the public type surface (
src/index.ts), shipping as a minor. No runtime behaviour changes.1. Export the transitively-referenced fact types
The AGENTS.md promise is "import them, do not hand-roll": every type named inside an exported type should itself be importable. It was not. This re-exports the full transitive closure from the package root:
CaptureMode,TargetLane,WorkloadLane,WorkloadIdentity,Measured,CpuBreakdown/CpuSlice/CpuJsSlice,LayoutShift(+Source/Rect),EngineSoftNav,SoftNavRoute(+Lcp),ThrashReport/ThrashStep/DirtiedByWrite/DirtiedByWriteRollup/FirefoxDirtiedByReport,SourceMapDiagnostics/SourceMapFailure.SpanCountsEntry(query),SoftNavVerdict/SoftNavAgreement(soft-nav),FrameFloorMatch(frame-floor).RawProfileNode/RawCallFrame/GeckoSlice.StepOpts/Until(StepOptsgainsexport).Eight of these (
Measured,WorkloadLane,SoftNavAgreement,RawProfileNode,RawCallFrame,GeckoSlice,StepOpts,Until) were surfaced by the guard test below beyond the initial list.2. Narrow the closed-union output fields off
stringRecordingMeta.captureandGroupSpanMember.mode-> theCaptureModeunion, extended inrecord/capture.tswith thenode-cpu/node-allocnode lanes (noprecise-wallarm; the schema-5 epoch gate rejects any pre-5 recording that could carry it).SpansResult.target/SpanAnatomy.target/GroupSpanStitch.target->"chrome" | "firefox" | "node"(a newTargetLane, now the return type ofrecordingLane).Reading these fields now yields the exact literal type instead of a bare string. The spec-open fields (
LoafScript.invokerType,EngineSoftNav.navigationTypes,SoftNavRoute.navigationType,meta.target) are deliberately left asstring.RecordingMetagains a doc note that it carries nokinddiscriminant (the fieldGroupMetastamps"run-group"to mark the sibling manifest).3. Guard test
test/unit/export-completeness.test.mjswalks the emitteddist/*.d.tswith the TypeScript compiler API and fails if any type reachable from a public export is not itself exported. Browser-free, no new dependency (uses the TypeScript already used to build). This is what a dropped or forgotten re-export trips on, instead of a consumer's red build.Notes
GroupSpanMember.modenarrowing needs a boundary cast (member.mode as CaptureMode): the run-group manifest'sGroupMember.modestays the widerstring(out of scope here), but its value is the member recording'smeta.captureverbatim, which is now aCaptureMode.import { CaptureMode }fromrecord/capture.ts; it erases in emit (verified: no runtime require indist/model/meta.js), so there is no runtime cycle.Gates
build, lint, format:check, knip, unit (686 tests, incl. the new guard), e2e (Chrome), and measurement all pass.