Skip to content

fix(api-manifest): make platform constants OS-independent so api-docs-drift is deterministic - #3838

Merged
proggeramlug merged 1 commit into
mainfrom
fix/api-docs-platform-determinism
May 31, 2026
Merged

proggeramlug merged 1 commit into
mainfrom
fix/api-docs-platform-determinism

Conversation

@proggeramlug

Copy link
Copy Markdown
Contributor

Summary

api-docs-drift currently fails for every open PR — including ones whose only change is unrelated runtime code (e.g. #3733). Root cause: the constants manifest 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:

Gated to Linux Gated to macOS
O_DIRECT, O_NOATIME, SIGSTKFLT, SIGPOLL, SIGPWR, RTLD_DEEPBIND O_SYMLINK, SIGINFO

…and api-docs-drift then fails for all subsequent PRs until the docs are regenerated on Linux again. (Diagnosed while trying to land #3733: its only change is object_ops.rs, yet CI showed a constants-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 @types follow). The runtime constants module still only exposes a real value where the OS provides one, so behavior is unchanged: an absent constant reads as undefined, matching Node.

Verification

  • Docs regenerated on macOS now contain both the Linux and macOS constants (the deterministic union), so a Linux CI regen produces the identical output → no drift. This PR's own api-docs-drift should pass, and it unblocks the check for all PRs going forward.
  • The manifest test that asserted the old gating (RTLD_DEEPBIND.is_some() == cfg!(linux-gnu)) is updated to assert unconditional presence; all 25 perry-api-manifest tests pass. cargo fmt --check clean.

Impact

Unblocks the api-docs-drift required check repo-wide. After this merges, the #3527 chain PRs (#3733 and the regex fix #3777) rebase green.

…-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.
@proggeramlug
proggeramlug merged commit f0eefdb into main May 31, 2026
11 checks passed
@proggeramlug
proggeramlug deleted the fix/api-docs-platform-determinism branch May 31, 2026 18:59
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