node:util: implement getCallSites stack frame helper #3434

Summary

Perry does not implement util.getCallSites([frameCount][, options]). Node exposes this helper and returns an array of stack frame objects with stable fields such as functionName, scriptName, lineNumber, and columnNumber, with validation for invalid frameCount values.

Node Behavior

Minimal repro:

import * as util from "node:util";

function probe() {
  const sites = util.getCallSites(3);
  console.log("typeof:", typeof util.getCallSites);
  console.log("array:", Array.isArray(sites));
  console.log("length:", sites.length);

  for (const [i, site] of sites.entries()) {
    console.log(`${i} keys:`, Object.keys(site).sort().join(","));
    console.log(`${i} function:`, site.functionName);
    console.log(`${i} line type:`, typeof site.lineNumber);
    console.log(`${i} column type:`, typeof site.columnNumber);
  }
}

probe();

for (const frameCount of [0, -1, "x"] as any[]) {
  try {
    console.log(`arg ${JSON.stringify(frameCount)}:`, util.getCallSites(frameCount).length);
  } catch (err) {
    const e = err as NodeJS.ErrnoException;
    console.log(`arg ${JSON.stringify(frameCount)} error:`, e.name, e.code, e.message.split("\n")[0]);
  }
}

Node v25.9.0 with FORCE_COLOR=0 node --experimental-strip-types prints typeof: function, returns an array of three frame objects whose keys include column,columnNumber,functionName,lineNumber,scriptId,scriptName, and rejects 0 / -1 with ERR_OUT_OF_RANGE plus non-number frameCount with ERR_INVALID_ARG_TYPE.

Perry Behavior

Focused probe test-files/tmp_util_get_call_sites.ts fails at compile time:

Collecting modules...
Error: `util.getCallSites` is not implemented in Perry — see `perry --print-api-manifest` for the supported surface, or set `PERRY_ALLOW_UNIMPLEMENTED=1` to ignore. (#463)

Evidence:

• ./run_parity_tests.sh --filter tmp_util_get_call_sites
• report: test-parity/reports/parity_report_20260530_110606.json
• Node output: test-parity/output/node/tmp_util_get_call_sites.txt
• Perry compile log: test-parity/output/tmp_util_get_call_sites.compile_error.log
• docs list util.getCallSites([frameCount][, options]) as a gap in docs/runtime-parity-gaps.md.
• crates/perry-api-manifest/src/entries.rs omits getCallSites from the supported util surface.

Suggested PR Cut

Batch this with related issues in:
node:util: diagnostics helper parity

Good batch candidates:

• node:util: implement remaining top-level helper APIs #2514

Do not batch with:

• unrelated modules
• broad subsystem rewrites
• fixes needing different test harnesses

Acceptance

• parity/regression test proves util.getCallSites returns Node-compatible frame objects for a bounded frameCount
• invalid frameCount values throw Node-compatible ERR_OUT_OF_RANGE / ERR_INVALID_ARG_TYPE errors
• related known-failure/docs/manifest entries updated if touched