docs: add troubleshooting note and example of using node_options for nicer stack traces

.aspect/rules/external_repository_action_cache/npm_translate_lock_LTE4Nzc1MDcwNjU=

@@ -18,6 +18,7 @@ examples/npm_package/packages/pkg_b/package.json=1041247977
 examples/npm_package/packages/pkg_d/package.json=1110895851
 examples/npm_package/packages/pkg_e/package.json=-2145239245
 examples/runfiles/package.json=-1545884645
+examples/stack_traces/package.json=2011229626
 examples/webpack_cli/package.json=1911342006
 js/private/coverage/bundle/package.json=-24783848
 js/private/image/package.json=-789619063
@@ -31,5 +32,5 @@ npm/private/test/vendored/is-odd/package.json=1041695223
 npm/private/test/vendored/lodash-4.17.21.tgz=-1206623349
 npm/private/test/vendored/semver-max/package.json=578664053
 package.json=1510979981
-pnpm-lock.yaml=1372779172
+pnpm-lock.yaml=-101429861
 pnpm-workspace.yaml=-1123429050

.bazelignore

@@ -15,6 +15,7 @@ examples/npm_package/packages/pkg_c/node_modules/
 examples/npm_package/packages/pkg_d/node_modules/
 examples/npm_package/packages/pkg_e/node_modules/
 examples/runfiles/node_modules
+examples/stack_traces/node_modules
 examples/webpack_cli/node_modules/
 js/private/coverage/bundle/node_modules
 js/private/image/node_modules

docs/troubleshooting.md

@@ -138,6 +138,15 @@ eslint_bin.eslint_test(
 > NB: We plan to add support for the `.npmrc` `public-hoist-pattern` setting to `rules_js` in a future release.
 > For now, you must emulate public-hoist-pattern in `rules_js` using the `public_hoist_packages` attribute shown above.
 
+## Ugly stack traces
+
+Bazel's sandboxing and runfiles directory layouts can make stack traces and logs hard to read. This issue is common in many
+languages when used within bazel, not only JavaScript.
+
+One solution involving `Error.prepareStackTrace` was [suggested on bazelbuild slack](https://bazelbuild.slack.com/archives/CA31HN1T3/p1733518986229749?thread_ts=1733516180.969159&cid=CA31HN1T3) by [John Firebaugh](https://github.com/jfirebaugh). This overrides `Error.prepareStackTrace` to strip the bazel sandbox and runfiles paths from error stack traces. This also uses [`source-map-support`](https://www.npmjs.com/package/source-map-support) to also apply source maps to the stack traces.
+
+See [examples/stack_traces](../examples/stack_traces) for a working example.
+
 ## Performance
 
 For general bazel performance tips see the [Aspect bazelrc guide](https://docs.aspect.build/guides/bazelrc/#performance-options).

examples/stack_traces/BUILD.bazel

@@ -0,0 +1,33 @@
+load("@aspect_rules_js//js:defs.bzl", "js_library", "js_test")
+load("@npm//:defs.bzl", "npm_link_all_packages")
+
+npm_link_all_packages(name = "node_modules")
+
+js_test(
+    name = "stack_traces",
+    data = [
+        ":library",
+
+        # Include the stack-traces library - this could be wrapped in a `js_test` macro
+        ":stack-traces",
+    ],
+    entry_point = "main.js",
+    node_options = [
+        # Load the stack-traces library at node startup time - this could be wrapped in a `js_test` macro
+        "--require",
+        "$$JS_BINARY__RUNFILES/$$JS_BINARY__WORKSPACE/examples/stack_traces/stacks.cjs",
+    ],
+)
+
+js_library(
+    name = "library",
+    srcs = glob(["lib/**/*.js"]),
+)
+
+# Put the stacks.cjs in a `js_library` that can also declare any dependencies that
+# the --require script may have such as the source-map-support package.
+js_library(
+    name = "stack-traces",
+    srcs = ["stacks.cjs"],
+    deps = [":node_modules/source-map-support"],
+)

examples/stack_traces/lib/a.js

@@ -0,0 +1,7 @@
+module.exports.a = function a() {
+    return b()
+}
+
+function b() {
+    throw new Error('the error')
+}

examples/stack_traces/main.js

@@ -0,0 +1,12 @@
+const { a } = require('./lib/a')
+
+try {
+    a()
+    throw new Error('a() should throw for this test')
+} catch (e) {
+    if (e.stack.indexOf('.runfiles/') !== -1) {
+        throw new Error(
+            'stacks.cjs should have stripped runfiles directories from the stack trace'
+        )
+    }
+}

examples/stack_traces/package.json

@@ -0,0 +1,5 @@
+{
+    "devDependencies": {
+        "source-map-support": "^0.5.21"
+    }
+}

examples/stack_traces/stacks.cjs

@@ -0,0 +1,41 @@
+// Register source-map-support for source maps to be applied on stack traces.
+require('source-map-support/register')
+
+let basePath = process.env.RUNFILES
+    ? `${process.env.RUNFILES}/${process.env.JS_BINARY__WORKSPACE}`
+    : process.cwd()
+
+if (!basePath.endsWith('/')) {
+    basePath = basePath + '/'
+}
+
+/*
+Before:
+    Error: test
+        at foo (/private/var/tmp/_bazel_username/67beefda950d56283b98d96980e6e332/execroot/aspect_rules_js/bazel-out/darwin_arm64-fastbuild/bin/examples/stack_traces/stack_trace_support.sh.runfiles/aspect_rules_js/examples/stack_traces/b.js:2:11)
+        at Object.<anonymous> (/private/var/tmp/_bazel_username/67beefda950d56283b98d96980e6e332/execroot/aspect_rules_js/bazel-out/darwin_arm64-fastbuild/bin/examples/stack_traces/stack_trace_support.sh.runfiles/aspect_rules_js/examples/stack_traces/a.js:4:1)
+        ...
+
+After:
+    Error: test
+        at foo (examples/stack_traces/b.ts:2:9)
+        at Object.<anonymous> (examples/stack_traces/a.ts:5:1)
+        ...
+*/
+
+const basePathRegex = new RegExp(
+    `(at | \\()${basePath
+        .replace(/\\/g, '/')
+        // Escape regex meta-characters.
+        .replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
+        .replace(/-/g, '\\x2d')}`,
+    'g'
+)
+
+const prepareStackTrace = Error.prepareStackTrace
+Error.prepareStackTrace = function (error, stack) {
+    return prepareStackTrace(error, stack)
+        .split('\n')
+        .map((line) => line.replace(basePathRegex, '$1'))
+        .join('\n')
+}