ReviewOS

zig-utils/zig-js

ABI inventory: scan explicit extern c declarations

#331
Closed chris opened this 9 days ago ·
9 days ago

Tracked by: #134, #163, #164 Discovered while validating #329.

Problem

The Home/Bun private ABI scanner recognizes extern fn but not the equally valid explicit extern "c" fn spelling. As a result, pinned consumer declarations such as Bun__JSValue__deserialize are absent from both inventories, while the C-export classifier correctly rejects the implementation as unclassified. CI also does not currently run the aggregate c-api-audit, so the drift escaped the #323 acceptance matrix.

Scope

  • Teach the comment/string-aware scanner to parse explicit C linkage without weakening declaration boundaries.
  • Add scanner self-tests for extern fn, extern "c" fn, comments/strings, multiline declarations, and non-C link names.
  • Regenerate the pinned Home and Bun inventories from their exact source revisions.
  • Keep Bun__JSValue__deserialize classified as a real private consumer declaration, not an exception whitelist.
  • Add the aggregate C-API/private-export audit to CI if it is not already covered by an equivalent gate.
  • Refresh ABI counts and documentation.

Acceptance

  • Both inventories contain the exact deserialize declaration and digest from their pinned sources.
  • zig build c-api-audit, Home/Bun private audits, and scanner self-tests pass.
  • CI prevents future exported-but-uninventoried ABI symbols.
9 days ago

Implemented in e4ee7c7 and pushed to main.

The fix scans default and explicit extern "c"/"C" declarations, excludes non-C named libraries, classifies libc imports, and keeps a deterministic unique-symbol contract while retaining repeated declaration provenance. Both pinned inventories now contain the exact Bun__JSValue__deserialize declaration and SHA-256 digest.

Acceptance evidence:

  • scanner self-tests: 4 passed (default/explicit linkage, multiline syntax, masked comments/strings, non-C names, duplicate provenance)
  • exact pinned regeneration/audits: Home 538 symbols from 66 files; Bun 484 from 59 files
  • all three Home alias revisions: exact contract match
  • zig build c-api-audit: clean, 353 private profile exports classified
  • Home runtime fixture: 333/333 linked; runtime matrix passed

CI now has a private-abi-boundary leg running the parser tests, aggregate export audit, both inventories, and runtime fixture. Leaving open until the descendant CI run is green.

9 days ago

Accepted on main. The explicit C-link declaration inventory landed in e4ee7c7b; the final descendant matrix at 19d10631 is fully green across all 41 jobs: https://github.com/zig-utils/zig-js/actions/runs/29706564614

Sign in to comment on this issue.