feat: implement bun:jsc heapStats with Perry heap counters

[proggeramlug]

bun:jsc imports previously warned that the module could not be resolved and failed at runtime. Register the module and implement heapStats() / heapStats(true) through the same native callable export for static imports, dynamic imports, and require().

The report contains the ten requested keys, with counters from a per-thread walk of Perry's arenas and tracked malloc GC cells. The walk allocates no JavaScript objects and retains only numeric results; the report and its nested objects are rooted while being built. Type counts use Perry's GC type names, protected counts approximate pinned cells, and the mimalloc compatibility object contains Perry allocator counters. External bytes and protected globals are explicitly documented as untracked/zero; the optional argument is ignored and collection is not forced. The documentation explains these differences from Bun's HeapStats contract.

Validation:

• Original dynamic-import repro prints number, number, object, object, object without an unresolved-import warning.
• Four compiled-executable regressions pass: import-form function identity; dynamic import; require; and dispatch installation without Bun globals. They check exact keys, finite non-negative counters, both argument forms, live retained objects and heap growth across collections.
• Runtime suite: 3137 passed, 4 ignored. API-manifest suite: 39 passed. Codegen suite: 1410 passed, 1 ignored.
• Quick pre-tag checks, formatting, file-size and test-registration checks passed; generated API docs/DTS updated. Documentation lint: passed.
• The affected-crate runner reaches the existing compiler cache-registration failure for PERRY_CONCAT_SITE_CACHE (fixed separately by fix(cache): register concat switch and explain codegen inputs #9748); 1083 compiler tests passed.

Fixes #9743. No version bump.

Summary by CodeRabbit

• New Features

  • Added compatibility for bun:jsc.heapStats() across static, dynamic, namespace, and CommonJS imports.
  • Reports heap usage, capacity, object counts, pinned objects, type breakdowns, and allocator statistics.
  • Added support for runtime-only use without requiring the Bun global.

• Documentation

  • Documented the new bun:jsc module and heapStats() API, including Perry-specific metric details.
  • Updated API references and declarations for bun:jsc, connect, and listen.

• Bug Fixes

  • Resolved issue #9743.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: c82b3789-8ad2-4dbb-a2f3-b857fbdcefbb

📥 Commits

Reviewing files that changed from the base of the PR and between 12efed1 and cd6a701.

📒 Files selected for processing (21)

• changelog.d/9760-bun-jsc-heap-stats.md
• crates/perry-api-manifest/src/entries.rs
• crates/perry-api-manifest/src/entries/part_4.rs
• crates/perry-codegen/src/lower_call/native_table/bun.rs
• crates/perry-codegen/src/nm_install.rs
• crates/perry-codegen/src/runtime_decls/objects.rs
• crates/perry-runtime/src/bun_compat/jsc.rs
• crates/perry-runtime/src/bun_compat/mod.rs
• crates/perry-runtime/src/gc/heap_stats.rs
• crates/perry-runtime/src/gc/mod.rs
• crates/perry-runtime/src/object/native_module/callable_export_arity_table.rs
• crates/perry-runtime/src/object/native_module/callable_export_check.rs
• crates/perry-runtime/src/object/native_module/callable_export_table.rs
• crates/perry-runtime/src/object/native_module/module_keys.rs
• crates/perry-runtime/src/object/native_module_dispatch/dispatch_a_c.rs
• crates/perry-runtime/src/object/native_module_registry.rs
• crates/perry/tests/issue_9743_bun_jsc_heap_stats.rs
• docs/api/perry.d.ts
• docs/src/api/reference.md
• docs/src/stdlib/other.md
• test-files/_helpers/bun_jsc_heap_stats_9743.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds bun:jsc.heapStats() support across manifest resolution, code generation, runtime dispatch, heap census, generated API declarations, documentation, and compiled-binary tests. The implementation reports Perry heap and allocator statistics.

Changes

bun:jsc heapStats

Layer / File(s)	Summary
Manifest and compiler registration crates/perry-api-manifest/..., crates/perry-codegen/...	Registers bun:jsc as a runtime-only native module and maps heapStats to the runtime export.
Heap census and compatibility implementation crates/perry-runtime/src/gc/..., crates/perry-runtime/src/bun_compat/...	Collects arena and allocator counters, builds per-type and pinned-object maps, and returns the Bun-compatible statistics object without forcing garbage collection.
Runtime module exposure and dispatch crates/perry-runtime/src/object/...	Adds module enumeration, callable-export metadata, module registration, and dispatch for bun:jsc.heapStats.
Integration validation and API documentation crates/perry/tests/..., test-files/_helpers/..., docs/api/..., docs/src/..., changelog.d/...	Tests static, namespace, dynamic, and CommonJS access, validates report shape and growth, and documents the new module and fields.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to cd6a7

This adds bun:jsc.heapStats() with documented Perry-specific heap and allocator counters. The supported import paths and result shape are covered, with no current merge-blocking risk identified.

Sequence Diagram(s)

sequenceDiagram
  participant Program
  participant nm_dispatch_bun
  participant js_bun_jsc_heap_stats
  participant heap_stats
  Program->>nm_dispatch_bun: call bun:jsc.heapStats
  nm_dispatch_bun->>js_bun_jsc_heap_stats: forward compatibility argument
  js_bun_jsc_heap_stats->>heap_stats: collect heap and allocator counters
  heap_stats-->>js_bun_jsc_heap_stats: return HeapStats
  js_bun_jsc_heap_stats-->>Program: return heapStats report

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The core changes match issue #9743, but the generated API documentation also adds bun.connect and bun.listen, and docs/src/stdlib/other.md includes an unrelated introductory rewrite. These changes are…	Remove the unrelated bun.connect and bun.listen documentation changes and the unrelated introductory rewrite, or explain why they are required for this PR and link the supporting issue.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 18 files. (3 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: implementing bun:jsc heapStats with Perry heap counters.
Description check	✅ Passed	The description is detailed and covers the purpose, implementation, related issue, validation, documentation, and version-bump status. It does not use every template heading or checklist item, but the…
Linked Issues check	✅ Passed	The implementation satisfies issue #9743. It resolves bun:jsc, supports static, dynamic, and require imports, exposes both heapStats argument forms, returns the required keys and numeric counters, doc…

Full details: Out of Scope Changes check

Explanation

The core changes match issue #9743, but the generated API documentation also adds bun.connect and bun.listen, and docs/src/stdlib/other.md includes an unrelated introductory rewrite. These changes are not part of the bun:jsc heapStats objective.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 18 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Landed on main via merge train #9798 (rebase-merged, so your commits keep their authorship). Thanks!