docs: refresh Node.js compatibility status + document .js compilation

[proggeramlug]

What

Documentation-only refresh after the recent Node.js parity sprint (PRs ~#4900–#5040+). Brings the public docs in line with current behavior and corrects several stale claims.

Why

The docs hadn't kept pace with the runtime work. Perry now sits at ~95% Node.js/TypeScript compatibility and passes ~97% of Node's own test suite (2792/2863 cases, node v26.3.0, 53 node:* modules — test-parity/node_suite_baseline.json), and it compiles plain JavaScript (.js/.cjs/.mjs/.jsx) source directly. Several docs still described pre-v0.5 limitations (no SharedArrayBuffer/Atomics, decorators unsupported, generators/Symbols/Proxy missing).

Changes

• README: new "Node.js compatibility" section (~97% Node test suite / ~95% overall) + note that Perry compiles .js/.cjs/.mjs/.jsx directly; fix the stale Decorators: ❌ not supported row → legacy TS decorators + emitDecoratorMetadata.
• docs/src/introduction.md: add Node.js compatibility bullet + plain-JavaScript compilation note.
• docs/src/language/supported-features.md: new "JavaScript (.js) Input" and "Node.js Compatibility" sections.
• docs/src/language/limitations.md: correct the stale "no SharedArrayBuffer or Atomics" claim (real cross-thread Atomics + SAB landed via Atomics.wait/notify/waitAsync are non-blocking fakes — real blocking + cross-agent wakeups (follow-up to #4794) #4913); note .js compilation.
• docs/src/threading/overview.md: document the SharedArrayBuffer/Atomics shared-state escape hatch.
• docs/runtime-parity-gaps.md: add a behavioral-status header (the list counts API surface, not pass rate).
• docs/typescript-parity-gaps.md (v0.4.56) & docs/typescript-compatibility-tests.md (v0.4.50): add prominent "historical/outdated" banners pointing at the maintained source of truth — these predate generators/Symbols/Proxy/etc. landing.

docs/runtime-parity.md is intentionally left untouched: it's a deliberately Perry-agnostic Node/Bun API inventory, not a status doc.

Notes

• Docs-only; no version bump or CHANGELOG entry included (left for the maintainer to fold in per the repo workflow). Happy to add one if preferred.
• The ~95% figure is anchored to the measurable ~97% Node-test-suite pass rate so the claims have a defensible source.

Summary by CodeRabbit

• Documentation
  • Enhanced Node.js compatibility documentation with ~95% behavioral parity metrics and ~97% test-suite pass rate details.
  • Clarified support for JavaScript file inputs (.js, .cjs, .mjs, .jsx) compiled through the same pipeline as TypeScript.
  • Documented SharedArrayBuffer and Atomics for cross-thread memory sharing and coordination.
  • Updated parity tracking references and limitation clarifications for improved maintainability.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ffe48c99-b601-40d5-83b4-2207f2a169ce

📥 Commits

Reviewing files that changed from the base of the PR and between 35b2e58 and bb7bc49.

📒 Files selected for processing (8)

• README.md
• docs/runtime-parity-gaps.md
• docs/src/introduction.md
• docs/src/language/limitations.md
• docs/src/language/supported-features.md
• docs/src/threading/overview.md
• docs/typescript-compatibility-tests.md
• docs/typescript-parity-gaps.md

---

📝 Walkthrough

Walkthrough

Documentation-only PR updating Perry's docs across seven files to cover: JavaScript file input support (.js/.cjs/.mjs/.jsx through the same native pipeline), Node.js behavioral parity metrics (~95% parity, ~97% Node v26 test pass rate), SharedArrayBuffer/Atomics cross-thread shared-memory support, historical-warning stamps on outdated parity docs, and a decorator support correction in the README feature table.

Changes

Documentation Updates

Layer / File(s)	Summary
JavaScript input support docs docs/src/language/limitations.md, docs/src/language/supported-features.md, docs/src/introduction.md	Adds a limitations note, a new "JavaScript (.js) Input" section in supported-features, and introduction updates (new JS paragraph, "Zero config" extended to .js) all stating Perry compiles .js/.cjs/.mjs/.jsx through the same native pipeline with the same dynamic restrictions.
Node.js parity metrics and historical doc updates README.md, docs/src/introduction.md, docs/runtime-parity-gaps.md, docs/typescript-compatibility-tests.md, docs/typescript-parity-gaps.md	Adds a "Node.js compatibility" subsection to README and a matching introduction bullet with parity figures; adds a v0.5.x behavioral-status block to runtime-parity-gaps.md; stamps typescript-compatibility-tests.md and typescript-parity-gaps.md with historical warnings redirecting to current gap tracking. Also updates the README decorators row from "not supported" to "legacy TS decorators".
SharedArrayBuffer/Atomics threading docs docs/src/language/limitations.md, docs/src/threading/overview.md	Replaces the prior "no SharedArrayBuffer/Atomics" limitation with updated guidance: SharedArrayBuffer aliases bytes across spawn/parallelMap agents, Atomics including wait/notify works for coordination, and typed-array views must be rebuilt per agent rather than captured directly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, the docs get a glow-up today,
JS files join the pipeline — hip-hip-hooray!
SharedArrayBuffer shares bytes, how neat,
Node parity at ~95%, can't be beat.
Old warnings stamped, the history kept,
While the rabbit reviewed each line and slept. 🌙

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/nodejs-parity-update

---

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