Skip to content

fix: resolve the caller frame in CJS error stacks - #1532

Open
aashish254 wants to merge 2 commits into
google:mainfrom
aashish254:fix/caller-location-cjs
Open

aashish254 wants to merge 2 commits into
google:mainfrom
aashish254:fix/caller-location-cjs

Conversation

@aashish254

Copy link
Copy Markdown

Suggests an improvement — no open issue covers it. #629 ("bun support: Error.stack format is different", closed 2024-03) is the sibling case for a different runtime's stacks; the CJS shape is still unhandled.

What

Fail.getCallerLocationFromString() resolved the caller frame by either finding a
Proxy.set marker frame or taking the first frame containing file://. A CJS
stack provides neither: the frames carry plain paths and Node never names a
Proxy.set frame for the $ proxy in the CJS build. With no marker found the
function computed offset = -1 and read lines[-1], which is undefined, so it
fell through to returning the entire raw stack as the at line.

Impact

Every ProcessError raised from a require('zx') script dumps ~10 frames of zx
and Node internals into its message, and the first line is nonsense (the stack
header gets prefixed with at):

    at Error: zx error
    at _Fail.getCallerLocation (/…/zx/build/core.cjs:244:34)
    at $.sync (/…/zx/build/core.cjs:465:23)
    at /…/zx/build/core.cjs:461:62
    at AsyncLocalStorage.run (node:internal/async_local_storage/async_context_frame:65:14)
    at within (/…/zx/build/core.cjs:453:18)
    at /…/zx/build/core.cjs:461:18
    at /…/run.cjs:4:39          <-- the actual caller, 8th line
    at Object.<anonymous> (/…/run.cjs:9:3)
    at Module._compile (node:internal/modules/cjs/loader:1929:14)
    at Object..js (node:internal/modules/cjs/loader:2060:10)
    exit code: 3

After the change, the same call (await $({nothrow: true})\exit 3`` from CJS):

    at /…/run.cjs:4:39
    exit code: 3

12 lines become 1. ESM is untouched: its stacks always reach the existing
file:// branch first, and I verified that the message for the same script as
.mjs is byte-identical before and after.

How

The new branch keeps the Proxy.set rule when it applies. When it does not, the
caller is the first frame that is neither from the module that raised the error
(zx's own core.cjs, read off lines[1], since the error is created inside
getCallerLocation) nor a node: internal — which also covers the deeper
.sync / preset chains, where zx frames and AsyncLocalStorage.run interleave.

Only stacks that previously returned a raw stack dump can take the new branch, so
no currently-correct output changes shape.

import {$} from 'zx'

const p = await $({nothrow: true})`exit 3`
console.log(p.message) // …\n    at /…/run.cjs:4:39\n    exit code: 3

Verification

Run on origin/main (65fc542) + this commit, Node 24, TERM=dumb FORCE_COLOR=3:

  • npm test (build → test:size → fmt:check → test:unit → test:types → test:license): exit 0 — 270 tests, 269 pass, 0 fail, 1 skipped; tsd 1/1; prettier clean; all five size budgets green.
  • npm run test:coverage: src/error.ts at 100% statements / branches / functions / lines; all files 98.6% lines, 91.06% branches (thresholds 98/90).
  • npm run test:smoke:cjs and npm run test:smoke:mjs: ok. The CJS smoke suite gains a case that asserts the message ends with at <this file>:<line>:<col> immediately followed by exit code: 3, and that no core.cjs frame appears in it.
  • Four new unit cases in test/error.test.ts use stacks captured from a real CJS run (async, .sync/preset chain with interleaved internals, and an all-internals stack).
  • Mutation checks: reverting only src/error.ts to its HEAD~1 content fails exactly getCallerLocationFromString-CJS and getCallerLocationFromString-CJS sync (267/270 pass); reverting only build/core.cjs fails the new smoke case at test/smoke/node.test.cjs:32. So both the unit and the smoke witnesses are load-bearing.

Size budget

The fix adds ~160 B to build/core.cjs, which trips three size-limit budgets
(zx-lite 129.46 → measured 129.62, js parts 881.85 → 882.02, all 944.60 →
944.73). I raised the three limits to the measured values, the same way #1423 and
#1464 did. The regenerated bundle is committed in this change.

Note for whoever merges: #1526 also edits .size-limit.json (js parts → 883.03,
all → 945.89), so the two conflict on those two numbers. The resolution is
take-the-larger for those two lines and keep this PR's 129.64 kB for zx-lite.
src/error.ts, test/* and build/core.cjs merge cleanly against #1526, #1315,
#1527 and #1531 (checked with git merge-tree --write-tree in both orders).

  • Setup Set the latest Node.js LTS version.
  • Build: I’ve run npm build before committing and verified the bundle updates correctly.
  • Tests: I’ve run test and confirmed all tests succeed. Added tests to cover my changes if needed.
  • Docs: I’ve added or updated relevant documentation as needed.
  • Sign Commits have verified signatures and follow conventinal commits spec
  • CoC: My changes follow the project’s coding guidelines and Code of Conduct.
  • Review: This PR represents original work and is not solely generated by AI tools.

`Fail.getCallerLocationFromString()` anchored the caller on either a
`Proxy.set` frame or a `file://` URL. A CJS stack has neither, so
`lines[-1]` was read as the fallback index and the whole raw stack
became the `at` line of every `ProcessError` message.

Skip the frames raised from zx's own module and node internals instead,
and keep the first frame left.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant