Repository navigation
fix(api-manifest): make platform constants OS-independent so api-docs-drift is deterministic - #3838
Merged
Merged
Conversation
…-drift is deterministic The `constants` manifest entries for OS-specific values were `#[cfg(target_os = ...)]`-gated (O_DIRECT/O_NOATIME/SIGSTKFLT/SIGPOLL/SIGPWR/RTLD_DEEPBIND on Linux; O_SYMLINK/SIGINFO on macOS). That made the *compiled manifest itself* differ by build OS, so the generated docs (`docs/api/perry.d.ts`, `docs/src/api/reference.md`) differ depending on which platform ran the generator. CI's `api-docs-drift` regenerates on Linux and fails if the committed docs differ. Whenever the committed docs are regenerated on macOS (a maintainer's machine), the OS-specific constants flip and the check fails for **every** open PR — unrelated to that PR's contents. (This is currently blocking the #3527 chain, e.g. #3733, whose only change is a runtime alignment guard.) Fix: list all eight platform-specific constants unconditionally in the manifest so it — and the generated docs — are identical on every host. This documents the cross-platform superset (the same convention Node's own `@types` use); the runtime `constants` module still only exposes a real value where the OS provides one, so behavior is unchanged (absent constants read as `undefined`, matching Node). Docs regenerated; the manifest test that asserted the gating is updated to assert unconditional presence.
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.
Summary
api-docs-driftcurrently fails for every open PR — including ones whose only change is unrelated runtime code (e.g. #3733). Root cause: theconstantsmanifest entries for OS-specific values are#[cfg(target_os = ...)]-gated, so the compiled manifest differs by build OS, and the generated docs (docs/api/perry.d.ts,docs/src/api/reference.md) differ depending on which platform ran the generator.CI regenerates on Linux and fails on any diff. The moment the committed docs are regenerated on macOS (a maintainer's machine), the OS-specific constants flip:
O_DIRECT,O_NOATIME,SIGSTKFLT,SIGPOLL,SIGPWR,RTLD_DEEPBINDO_SYMLINK,SIGINFO…and
api-docs-driftthen fails for all subsequent PRs until the docs are regenerated on Linux again. (Diagnosed while trying to land #3733: its only change isobject_ops.rs, yet CI showed aconstants-module doc diff adding the Linux constants and removing the macOS ones.)Fix
List all eight platform-specific constants unconditionally in the manifest, so the manifest — and the generated docs — are byte-identical on every host. This documents the cross-platform superset (the convention Node's own
@typesfollow). The runtimeconstantsmodule still only exposes a real value where the OS provides one, so behavior is unchanged: an absent constant reads asundefined, matching Node.Verification
api-docs-driftshould pass, and it unblocks the check for all PRs going forward.RTLD_DEEPBIND.is_some() == cfg!(linux-gnu)) is updated to assert unconditional presence; all 25perry-api-manifesttests pass.cargo fmt --checkclean.Impact
Unblocks the
api-docs-driftrequired check repo-wide. After this merges, the #3527 chain PRs (#3733 and the regex fix #3777) rebase green.