Skip to content

Hold the public surface to a report, and the report to the Rust - #10

Merged
tamnd merged 1 commit into
mainfrom
api-gate
Aug 19, 2026
Merged

Hold the public surface to a report, and the report to the Rust#10
tamnd merged 1 commit into
mainfrom
api-gate

Conversation

@tamnd

@tamnd tamnd commented Aug 19, 2026

Copy link
Copy Markdown
Owner

Two links of one chain, in the package job because it already pays for the build they need.

The first asks whether binding.d.cts still says what the Rust says. That file is generated by the build and committed, and a committed generated file is one that can go stale: change a signature, forget to rebuild, and the package ships types describing a function that is no longer there. Nothing was checking that until now.

The second asks whether etc/zudb.api.md still says what binding.d.cts says. The report is what api-extractor is for here: a change to what this package exports arrives as a diff in one small file somebody has to read, rather than as a line buried in six hundred generated ones. The report is committed, npm run check:api verifies it, and npm run check:api:update is what you run when the change was intended.

What the report leaves out is written into the workflow beside it rather than left to be discovered. api-extractor reads declarations rather than the type checker's merged view, so it does not follow the declare module augmentation in zudb.d.cts, and stream and Symbol.asyncDispose are missing from Connection in the report. Those two are held from the other side, by the fixtures under test/types that call both and are compiled by check:types under the settings a user's compiler would use.

Both gates are validated the way the leak gates in the last change were: a renamed export has to fail them, and the step that renames one puts the tree back before anything else looks at it.

projectFolder is spelled out in api-extractor.json because there is no tsconfig.json at the root to infer it from, and tools/api-extractor.tsconfig.json is the settings from test/types with skipLibCheck turned on, since this run is a reader rather than a checker.

Two links of one chain, both in the package job because it already paid
for the build they need. The first asks whether binding.d.cts still says
what the Rust says: that file is generated and committed, and a
committed generated file can go stale, which ships types describing a
function that is no longer there. The second asks whether
etc/zudb.api.md still says what binding.d.cts says, so a change to what
this package exports arrives as a diff in one small file somebody reads
rather than as a line buried in six hundred generated ones.

What the report leaves out is written into the workflow beside it.
api-extractor reads declarations rather than the type checker's merged
view, so it does not follow the module augmentation in zudb.d.cts and
misses stream and Symbol.asyncDispose on Connection. Those two are held
from the other side, by the fixtures under test/types that call both and
are compiled under the settings a user's compiler would use.

The gate is validated the way the leak gates are: a renamed export has
to fail it.
@tamnd
tamnd merged commit 88a4584 into main Aug 19, 2026
22 checks passed
@tamnd
tamnd deleted the api-gate branch August 19, 2026 01:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant