Expand granular child_process parity coverage

[TheHypnoo]

Summary

• add 27 granular node:child_process fixtures, expanding the suite from 26 to 53 cases
• cover validation, cwd/env behavior, sync input/result shapes, lifecycle and callback ordering, stdio dataflow/flushing, timeout behavior, URL forks, shell/error behavior, and JSON/advanced serialization
• use controlled Node helper programs and deterministic cleanup
• document the current Node, Deno, and Bun primary-source comparison, stable Perry mismatches, stopping judgment, and platform/slow exclusions
• ratchet the measured child-process floor from 26/26 to 43/53 and align oracle metadata with pinned Node 26.5.0

Coverage added

• validation: embedded nulls; direct ChildProcess constructor; option types/ranges; fork overloads; stdio layouts; duplicate/sync IPC; kill signals
• sync: cwd/default env/env coercion; missing cwd; optional args; Buffer/Uint8Array/DataView input; encoding aliases; literal metacharacter arguments; argument preservation; option immutability; windowsHide; basic shell execution; Unicode and infinite maxBuffer; multi-chunk/streamed output above 64 KiB
• async: spawn metadata/default env/optional args; missing-command completion; option immutability; exit/kill lifecycle; exec/execFile success and promisified shapes; callback/stream lifecycle ordering; non-expiring timeout options; text/binary stdin; stream piping; fd3; bounded multi-chunk stdio flushing; WHATWG URL fork
• serialization: JSON plus advanced Buffer, empty/non-empty typed arrays, Map, Set, Date, RegExp, BigInt, and Error values

Verification

• NPM_CONFIG_CACHE=/tmp/perry-npm-cache npx -y prettier@3.6.2 --write <changed files> — passed
• git diff --check — passed
• baseline aggregate validation — 2818/2890 equals the sum of all committed module floors
• ./run_parity_tests.sh --suite node-suite --module child_process with Node 26.5.0 — 42 pass, 10 output mismatches, 0 compile failures, 0 crashes, 1 pre-existing host Node failure, 53 fixtures (80.7% of executed cases)
• NODE_BIN="$(command -v node)" python3 scripts/node_suite_run.py "$PWD/target/release/perry" "$PWD" child_process with Node 26.5.0 — 43/53 (81.1%), diff=10

Diagnostic mismatches

Nine expanded fixtures expose stable differences:

• embedded-null commands/files/arguments are accepted rather than rejected
• invalid options, fork overloads, stdio/IPC layouts, and signals are accepted rather than rejected; direct ChildProcess instances lack Node's prototype identity, initial state, and coded validation errors
• async execFile invokes its callback but returns no ChildProcess handle; promisified exec/execFile results also omit .child
• async spawn metadata/status match but stdout is empty for direct, inherited-env, optional-args, and immutable-options probes; missing-command errors do not reach close
• async stdin writes/statuses match but readable/end state, output dataflow, stream piping, and fd3 differ
• custom async cwd/env exits with status 0 but captures no stdout
• WHATWG URL fork never receives the helper IPC message and ends with unsettled top-level await
• missing-cwd sync errors lack Node's error shape, basic shell execution is treated as ENOENT, and Unicode maxBuffer termination/zero semantics differ
• advanced IPC preserves Buffer, Date, typed arrays, and BigInt but loses Map, Set, RegExp, and Error brands/content

The existing AbortSignal fixture remains the tenth mismatch and now also demonstrates Perry returning true from kill() after close where Node returns false.

Upstream scope and exclusions

Compared against Node.js 608112affae2cf44d2f8a0a6bfe7967193b459c8, Deno f8a17c8171569fa2870d740030aaa59c91fdf9ee, and Bun c4fad462e7dc20e5e9780f848db42e1e2f52186d.

Deferred to separate platform/slow assessments: fork/IPC races and handle transfer beyond deterministic URL/serialization probes; socket/server and cluster/dgram integration; exhaustive signal, UID/GID, detached and scheduler-sensitive behavior; Windows quoting/batch/overlapped stdio; custom-shell discovery; EMFILE/resource exhaustion; large IPC framing; host-object/circular serialization; and multi-megabyte stress.

[coderabbitai]

📝 Walkthrough

Walkthrough

The child_process parity suite adds fixtures for validation, lifecycle ordering, cwd and environment handling, stdio, synchronous inputs and options, IPC serialization, and advanced values. Documentation and Node 26 regression thresholds are updated for the expanded measurements.

Changes

Child process parity suite

Layer / File(s)	Summary
Validation fixtures test-parity/node-suite/child_process/validation/*	Exercises null-byte inputs, invalid options, invalid stdio configurations, and invalid kill signals across child-process APIs.
Async process behavior fixtures test-parity/node-suite/child_process/async/*	Verifies callback and lifecycle event ordering, exit metadata, argument and environment propagation, stdin/stdout/stderr data flow, and stream flushing.
Synchronous process behavior fixtures test-parity/node-suite/child_process/sync/*	Covers cwd and environment handling, argument passing, encoding aliases, input views, shell failures, buffering, immutable options, default environment inheritance, and windowsHide.
IPC serialization fixtures test-parity/node-suite/child_process/serialization/basic.ts	Tests JSON and advanced fork serialization with nested values, buffers, maps, sets, dates, regular expressions, typed arrays, bigints, and errors.
Parity documentation and regression floors test-parity/node-suite/child_process/README.md, test-parity/node_suite_baseline.json	Documents upstream coverage, measured mismatches, and exclusions, and updates suite-wide and child_process baseline thresholds.

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

Possibly related PRs

• PerryTS/perry#5097: Related child_process fixtures and regression comparisons.
• PerryTS/perry#5166: Related updates to suite-wide and child_process baseline thresholds.
• PerryTS/perry#6367: Establishes the Node 26.5.0 version used by the parity measurements.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title concisely and accurately summarizes the main change: expanded child_process parity coverage.
Description check	✅ Passed	The description covers the summary, concrete changes, verification, and exclusions, with only non-critical template sections omitted.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/expand-node-child-process-parity

---

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.}

[coderabbitai]

🧹 Nitpick comments (2)

test-parity/node-suite/child_process/async/stdio-flush.ts (1)

3-5: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Improve type safety for child.

Consider using ChildProcessWithoutNullStreams from node:child_process for better type checking on the child argument.

🛠️ Proposed refactor

-function collect(
-  child: any,
-): Promise<{ code: number | null; stdout: string; stderr: string }> {
+function collect(
+  child: import("node:child_process").ChildProcessWithoutNullStreams,
+): Promise<{ code: number | null; stdout: string; stderr: string }> {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test-parity/node-suite/child_process/async/stdio-flush.ts` around lines 3 -
5, Update the collect function’s child parameter to use
ChildProcessWithoutNullStreams imported from node:child_process instead of any,
preserving the existing return type and behavior.

test-parity/node-suite/child_process/async/cwd-env.ts (1)

10-12: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Improve type safety for child.

Consider using the ChildProcess type from node:child_process instead of any for better type checking.

🛠️ Proposed refactor

-function close(child: any): Promise<number | null> {
+function close(child: import("node:child_process").ChildProcess): Promise<number | null> {
   return new Promise((resolve) => child.on("close", resolve));
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test-parity/node-suite/child_process/async/cwd-env.ts` around lines 10 - 12,
Update the close function’s child parameter to use the ChildProcess type
imported from node:child_process instead of any, preserving the existing
Promise<number | null> behavior and close-event handling.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test-parity/node-suite/child_process/async/cwd-env.ts`:
- Around line 10-12: Update the close function’s child parameter to use the
ChildProcess type imported from node:child_process instead of any, preserving
the existing Promise<number | null> behavior and close-event handling.

In `@test-parity/node-suite/child_process/async/stdio-flush.ts`:
- Around line 3-5: Update the collect function’s child parameter to use
ChildProcessWithoutNullStreams imported from node:child_process instead of any,
preserving the existing return type and behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1cb76d34-33d4-40d1-867c-ef4e5a5d539c

📥 Commits

Reviewing files that changed from the base of the PR and between 1524454 and bb4b76d.

📒 Files selected for processing (10)

• test-parity/node-suite/child_process/README.md
• test-parity/node-suite/child_process/async/callback-ordering.ts
• test-parity/node-suite/child_process/async/cwd-env.ts
• test-parity/node-suite/child_process/async/event-ordering.ts
• test-parity/node-suite/child_process/async/stdio-flush.ts
• test-parity/node-suite/child_process/serialization/basic.ts
• test-parity/node-suite/child_process/sync/cwd-env-input.ts
• test-parity/node-suite/child_process/validation/null-bytes.ts
• test-parity/node-suite/child_process/validation/options.ts
• test-parity/node_suite_baseline.json

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test-parity/node_suite_baseline.json`:
- Around line 7-10: Recompute the overall summary in the overall object from the
per-module totals: set pass to 2815 out of 2886 and update pct to the
corresponding floored percentage, replacing the stale 2824 and 97.9 values.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4622f514-7dba-449f-bb0c-0685404dddb0

📥 Commits

Reviewing files that changed from the base of the PR and between bb4b76d and f1ee20f.

📒 Files selected for processing (21)

• test-parity/node-suite/child_process/README.md
• test-parity/node-suite/child_process/async/cwd-env.ts
• test-parity/node-suite/child_process/async/exec-success.ts
• test-parity/node-suite/child_process/async/execfile-args.ts
• test-parity/node-suite/child_process/async/exit-codes.ts
• test-parity/node-suite/child_process/async/spawn-behavior.ts
• test-parity/node-suite/child_process/async/stdio-dataflow.ts
• test-parity/node-suite/child_process/async/stdio-flush.ts
• test-parity/node-suite/child_process/serialization/basic.ts
• test-parity/node-suite/child_process/sync/default-env.ts
• test-parity/node-suite/child_process/sync/encoding-aliases.ts
• test-parity/node-suite/child_process/sync/env-values.ts
• test-parity/node-suite/child_process/sync/error-shell.ts
• test-parity/node-suite/child_process/sync/execfile-args.ts
• test-parity/node-suite/child_process/sync/input-views.ts
• test-parity/node-suite/child_process/sync/maxbuffer-infinity.ts
• test-parity/node-suite/child_process/sync/optional-args-metadata.ts
• test-parity/node-suite/child_process/sync/options-immutable.ts
• test-parity/node-suite/child_process/sync/windows-hide.ts
• test-parity/node-suite/child_process/validation/options.ts
• test-parity/node_suite_baseline.json

🚧 Files skipped from review as they are similar to previous changes (1)

• test-parity/node-suite/child_process/README.md