fix(ses,lockdown): make filenames in stacktraces clickable

erights · erights · commit 45204773d7e3 · 2025-04-05T14:44:20.000-07:00
diff --git a/packages/lockdown/commit-debug.js b/packages/lockdown/commit-debug.js
@@ -21,13 +21,13 @@ lockdown({
   // NOTE TO REVIEWERS: If you see the following line commented out,
   // this may be a development accident that should be fixed before merging.
   //
-  errorTaming: 'unsafe-debug',
+  errorTaming: 'unsafe',
 
   // The default `{stackFiltering: 'concise'}` setting usually makes for a
   // better debugging experience, by severely reducing the noisy distractions
   // of the normal verbose stack traces. Which is why we comment
-  // out the `'verbose'` setting is commented out below. However, some
-  // tools look for the full filename that it expects in order
+  // out the other settings below. However, some
+  // tools look for the full filename path that it expects in order
   // to fetch the source text for diagnostics,
   //
   // Another reason for not commenting it out: The cause
@@ -36,10 +36,14 @@ lockdown({
   // uncomment out the following line. But please do not commit it in that
   // state.
   //
-  // NOTE TO REVIEWERS: If you see the following line *not* commented out,
-  // this may be a development accident that MUST be fixed before merging.
+  // NOTE TO REVIEWERS: If you see the `stackFiltering` settings *not*
+  // commented out below, this may be a development accident that MUST be
+  // fixed before merging.
   //
-  // stackFiltering: 'verbose',
+  // stackFiltering: 'concise', // Omit frames and shorten paths
+  // stackFiltering: 'omit-frames', // Only omit frames. Do not shorten paths
+  // stackFiltering: 'shorten-paths', // Only shorten paths. Do not omit frames
+  // stackFiltering: 'verbose', // Do not omit frames or shorten paths
 
   // The default `{overrideTaming: 'moderate'}` setting does not hurt the
   // debugging experience much. But it will introduce noise into, for example,
diff --git a/packages/lockdown/pre.js b/packages/lockdown/pre.js
@@ -102,13 +102,12 @@ export const lockdown = defaultOptions => {
       // this may be a development accident that MUST be fixed before merging.
       //
       // errorTaming: 'unsafe',
-      //
-      //
+
       // The default `{stackFiltering: 'concise'}` setting usually makes for a
       // better debugging experience, by severely reducing the noisy distractions
       // of the normal verbose stack traces. Which is why we comment
-      // out the `'verbose'` setting is commented out below. However, some
-      // tools look for the full filename that it expects in order
+      // out the other settings below. However, some
+      // tools look for the full filename path that it expects in order
       // to fetch the source text for diagnostics,
       //
       // Another reason for not commenting it out: The cause
@@ -117,12 +116,15 @@ export const lockdown = defaultOptions => {
       // uncomment out the following line. But please do not commit it in that
       // state.
       //
-      // NOTE TO REVIEWERS: If you see the following line *not* commented out,
-      // this may be a development accident that MUST be fixed before merging.
-      //
-      // stackFiltering: 'verbose',
-      //
+      // NOTE TO REVIEWERS: If you see the `stackFiltering` settings *not*
+      // commented out below, this may be a development accident that MUST be
+      // fixed before merging.
       //
+      // stackFiltering: 'concise', // Omit frames and shorten paths
+      // stackFiltering: 'omit-frames', // Only omit frames. Do not shorten paths
+      // stackFiltering: 'shorten-paths', // Only shorten paths. Do not omit frames
+      // stackFiltering: 'verbose', // Do not omit frames or shorten paths
+
       // The default `{overrideTaming: 'moderate'}` setting does not hurt the
       // debugging experience much. But it will introduce noise into, for example,
       // the vscode debugger's object inspector. During debug and test, if you can
@@ -134,8 +136,7 @@ export const lockdown = defaultOptions => {
       // this may be a development accident that MUST be fixed before merging.
       //
       // overrideTaming: 'min',
-      //
-      //
+
       // The default `{consoleTaming: 'safe'}` setting usually makes for a
       // better debugging experience, by wrapping the original `console` with
       // the SES replacement `console` that provides more information about
diff --git a/packages/ses-ava/test/raw-ava-reject.test.js b/packages/ses-ava/test/raw-ava-reject.test.js
@@ -15,8 +15,10 @@ lockdown({
   // the current relevant environment variable setting. To get results
   // independent of that, always uncomment one setting for each switch.
   //
-  stackFiltering: 'concise', // Default. Hide infrastructure, shorten paths
-  // stackFiltering: 'verbose', // Include `assert` infrastructure
+  stackFiltering: 'concise', // Default. Omit likely uninteresting frames. Shorten paths
+  // stackFiltering: 'omit-frames', // Only omit infrastructure frames
+  // stackFiltering: 'shorten-paths', // Only shorten paths
+  // stackFiltering: 'verbose', // Original frames with original paths
   consoleTaming: 'safe', // Default. Console with access to redacted info
   // consoleTaming: 'unsafe', // Host console lacks access to redacted info
   // errorTaming: 'safe', // Default. Hide redacted info on error
diff --git a/packages/ses-ava/test/raw-ava-throw.test.js b/packages/ses-ava/test/raw-ava-throw.test.js
@@ -15,8 +15,10 @@ lockdown({
   // the current relevant environment variable setting. To get results
   // independent of that, always uncomment one setting for each switch.
   //
-  stackFiltering: 'concise', // Default. Hide infrastructure, shorten paths
-  // stackFiltering: 'verbose', // Include `assert` infrastructure
+  stackFiltering: 'concise', // Default. Omit likely uninteresting frames. Shorten paths
+  // stackFiltering: 'omit-frames', // Only omit infrastructure frames
+  // stackFiltering: 'shorten-paths', // Only shorten paths
+  // stackFiltering: 'verbose', // Original frames with original paths
   consoleTaming: 'safe', // Default. Console with access to redacted info
   // consoleTaming: 'unsafe', // Host console lacks access to redacted info
   // errorTaming: 'safe', // Default. Hide redacted info on error
diff --git a/packages/ses-ava/test/ses-ava-reject.test.js b/packages/ses-ava/test/ses-ava-reject.test.js
@@ -16,8 +16,10 @@ lockdown({
   // the current relevant environment variable setting. To get results
   // independent of that, always uncomment one setting for each switch.
   //
-  stackFiltering: 'concise', // Default. Hide infrastructure, shorten paths
-  // stackFiltering: 'verbose', // Include `assert` infrastructure
+  stackFiltering: 'concise', // Default. Omit likely uninteresting frames. Shorten paths
+  // stackFiltering: 'omit-frames', // Only omit infrastructure frames
+  // stackFiltering: 'shorten-paths', // Only shorten paths
+  // stackFiltering: 'verbose', // Original frames with original paths
   consoleTaming: 'safe', // Default. Console with access to redacted info
   // consoleTaming: 'unsafe', // Host console lacks access to redacted info
   // errorTaming: 'safe', // Default. Hide redacted info on error
diff --git a/packages/ses-ava/test/ses-ava-throw.test.js b/packages/ses-ava/test/ses-ava-throw.test.js
@@ -16,8 +16,10 @@ lockdown({
   // the current relevant environment variable setting. To get results
   // independent of that, always uncomment one setting for each switch.
   //
-  stackFiltering: 'concise', // Default. Hide infrastructure, shorten paths
-  // stackFiltering: 'verbose', // Include `assert` infrastructure
+  stackFiltering: 'concise', // Default. Omit likely uninteresting frames. Shorten paths
+  // stackFiltering: 'omit-frames', // Only omit infrastructure frames
+  // stackFiltering: 'shorten-paths', // Only shorten paths
+  // stackFiltering: 'verbose', // Original frames with original paths
   consoleTaming: 'safe', // Default. Console with access to redacted info
   // consoleTaming: 'unsafe', // Host console lacks access to redacted info
   // errorTaming: 'safe', // Default. Hide redacted info on error
diff --git a/packages/ses/NEWS.md b/packages/ses/NEWS.md
@@ -1,9 +1,18 @@
 User-visible changes in `ses`:
 
-# v1.12.0 (2025-03-11)
+# Next release
+
+- Two new `stackFiltering:` options are added
+  - `'omit-frames'` -- Only omit likely uninteresting frames. Keep original paths.
+  - `'shorten-paths'` -- Only shorten paths to text likely clickable in an IDE
 
-- The `evalTaming:` option values are renamed:
+  This fills out the matrix of what should have been orthogonal options.
+  The existing `'concise'` setting both omits likely uninteresting frames and
+  shortens their paths. The existing `'verbose'` setting does neither.
+
+# v1.12.0 (2025-03-11)
 
+- The `evalTaming:` option values are renamed
   - from `'safeEval'`, `'unsafeEval'`, and `'noEval'`
   - to `'safe-eval'`, `'unsafe-eval'`, and `'no-eval'`
 
diff --git a/packages/ses/docs/lockdown.md b/packages/ses/docs/lockdown.md
@@ -30,7 +30,7 @@ Each option is explained in its own section below.
 | `reporting`                      | `'platform'`     | `'console'` `'none'`                   | where to report warnings ([details](#reporting-options))
 | `unhandledRejectionTrapping`     | `'report'`       | `'none'`                               | handling of finalized unhandled rejections ([details](#unhandledrejectiontrapping-options)) |
 | `evalTaming`                     | `'safe-eval'`    | `'unsafe-eval'` `'no-eval'`            | `eval` and `Function` of the start compartment ([details](#evaltaming-options)) |
-| `stackFiltering`                 | `'concise'`      | `'verbose'`                            | deep stacks signal/noise   ([details](#stackfiltering-options)) |
+| `stackFiltering`                 | `'concise'`      | `'omit-frames'` `'shorten-paths'` `'verbose'`  | deep stacks signal/noise   ([details](#stackfiltering-options)) |
 | `overrideTaming`                 | `'moderate'`     | `'min'` or `'severe'`                  | override mistake antidote  ([details](#overridetaming-options)) |
 | `overrideDebug`                  | `[]`             | array of property names                | detect override mistake    ([details](#overridedebug-options)) |
 | `domainTaming`                   | `'safe'`         | `'unsafe'`                             | Node.js `domain` module    ([details](#domaintaming-options)) |
@@ -238,7 +238,7 @@ with the Node `console`, we advise you to also set `overrideTaming: 'min'` so
 that no builtin `constructor` properties are turned into accessors.
 
 Examples from
-[test-deep-send.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/eventual-send/test/test-deep-send.js)
+[deep-send.test.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/eventual-send/test/deep-send.test.js)
 of the eventual-send shim:
 
 <details>
@@ -247,27 +247,27 @@ of the eventual-send shim:
     expected failure (Error#1)
     Nested error
       Error#1: Wut?
-        at Object.bar (packages/eventual-send/test/test-deep-send.js:13:21)
+        at Object.bar (packages/eventual-send/test/deep-send.test.js:13:21)
 
       Error#1 ERROR_NOTE: Thrown from: (Error#2) : 2 . 0
       Error#1 ERROR_NOTE: Rejection from: (Error#3) : 1 . 1
       Nested 2 errors under Error#1
         Error#2: Event: 1.1
-          at Object.foo (packages/eventual-send/test/test-deep-send.js:17:28)
+          at Object.foo (packages/eventual-send/test/deep-send.test.js:17:28)
 
         Error#2 ERROR_NOTE: Caused by: (Error#3)
         Nested error under Error#2
           Error#3: Event: 0.1
-            at Object.test (packages/eventual-send/test/test-deep-send.js:21:22)
-            at packages/eventual-send/test/test-deep-send.js:25:19
+            at Object.test (packages/eventual-send/test/deep-send.test.js:21:22)
+            at packages/eventual-send/test/deep-send.test.js:25:19
             at async Promise.all (index 0)
 </details>
 
 <details>
   <summary>Expand for { consoleTaming: 'unsafe', overrideTaming: 'min' } log output</summary>
 
     expected failure [Error: Wut?
-      at Object.bar (packages/eventual-send/test/test-deep-send.js:13:21)]
+      at Object.bar (packages/eventual-send/test/deep-send.test.js:13:21)]
 </details>
 
 ## `errorTaming` Options
@@ -633,7 +633,11 @@ bugs.
 ```js
 lockdown(); // stackFiltering defaults to 'concise'
 // or
-lockdown({ stackFiltering: 'concise' }); // Preserve important deep stack info
+lockdown({ stackFiltering: 'concise' }); // Preserve important deep stack info. Omit likely uninteresting frames. Shorten paths to likely clickable strings in an IDE
+// vs
+lockdown({ stackFiltering: 'omit-frames' }); // Only omit likely uninteresting frames. Preserve original paths
+// vs
+lockdown({ stackFiltering: 'shorten-paths' }); // Preserve original frames. shorten their paths to likely clickable strings in an IDE.
 // vs
 lockdown({ stackFiltering: 'verbose' }); // Console shows full deep stacks
 ```
@@ -643,6 +647,8 @@ If `lockdown` does not receive a `stackFiltering` option, it will respect
 
 ```console
 LOCKDOWN_STACK_FILTERING=concise
+LOCKDOWN_STACK_FILTERING=omit-frames
+LOCKDOWN_STACK_FILTERING=shorten-paths
 LOCKDOWN_STACK_FILTERING=verbose
 ```
 
@@ -659,32 +665,32 @@ that information is no longer an extraneous distraction. Sometimes the noise
 you filter out actually contains the signal you're looking for. The
 `'verbose'` setting shows, on the console, the full raw stack information
 for each level of the deep stacks.
-Either setting of `stackFiltering` setting is safe. Stack information will
+Any setting of `stackFiltering` is safe. Stack information will
 or will not be available from error objects according to the `errorTaming`
 option and the platform error behavior.
 
 Examples from
-[test-deep-send.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/eventual-send/test/test-deep-send.js)
+[deep-send.test.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/eventual-send/test/deep-send.test.js)
 of the eventual-send shim:
 <details>
   <summary>Expand for { stackFiltering: 'concise' } log output</summary>
 
     expected failure (Error#1)
     Nested error
       Error#1: Wut?
-        at Object.bar (packages/eventual-send/test/test-deep-send.js:13:21)
+        at Object.bar (packages/eventual-send/test/deep-send.test.js:13:21)
 
       Error#1 ERROR_NOTE: Thrown from: (Error#2) : 2 . 0
       Error#1 ERROR_NOTE: Rejection from: (Error#3) : 1 . 1
       Nested 2 errors under Error#1
         Error#2: Event: 1.1
-          at Object.foo (packages/eventual-send/test/test-deep-send.js:17:28)
+          at Object.foo (packages/eventual-send/test/deep-send.test.js:17:28)
 
         Error#2 ERROR_NOTE: Caused by: (Error#3)
         Nested error under Error#2
           Error#3: Event: 0.1
-            at Object.test (packages/eventual-send/test/test-deep-send.js:21:22)
-            at packages/eventual-send/test/test-deep-send.js:25:19
+            at Object.test (packages/eventual-send/test/deep-send.test.js:21:22)
+            at packages/eventual-send/test/deep-send.test.js:25:19
             at async Promise.all (index 0)
 </details>
 
@@ -696,7 +702,7 @@ of the eventual-send shim:
       Error#1: Wut?
         at makeError (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/install-ses/node_modules/ses/dist/ses.cjs:2976:17)
         at Function.fail (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/install-ses/node_modules/ses/dist/ses.cjs:3109:19)
-        at Object.bar (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/test-deep-send.js:13:21)
+        at Object.bar (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/deep-send.test.js:13:21)
         at /Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:388:23
         at Object.applyMethod (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:353:14)
         at doIt (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:395:67)
@@ -713,7 +719,7 @@ of the eventual-send shim:
           at handle (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:396:27)
           at Function.applyMethod (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:312:14)
           at Proxy.&lt;anonymous&gt; (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/E.js:37:49)
-          at Object.foo (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/test-deep-send.js:17:28)
+          at Object.foo (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/deep-send.test.js:17:28)
           at /Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:388:23
           at Object.applyMethod (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:353:14)
           at doIt (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:395:67)
@@ -729,8 +735,8 @@ of the eventual-send shim:
             at handle (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:396:27)
             at Function.applyMethod (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/index.js:312:14)
             at Proxy.<anonymous> (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/src/E.js:37:49)
-            at Object.test (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/test-deep-send.js:21:22)
-            at /Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/test-deep-send.js:25:19
+            at Object.test (/Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/deep-send.test.js:21:22)
+            at /Users/markmiller/src/ongithub/agoric/agoric-sdk/packages/eventual-send/test/deep-send.test.js:25:19
             at Test.callFn (/Users/markmiller/src/ongithub/agoric/agoric-sdk/node_modules/ava/lib/test.js:610:21)
             at Test.run (/Users/markmiller/src/ongithub/agoric/agoric-sdk/node_modules/ava/lib/test.js:623:23)
             at Runner.runSingle (/Users/markmiller/src/ongithub/agoric/agoric-sdk/node_modules/ava/lib/runner.js:280:33)
diff --git a/packages/ses/docs/reference.md b/packages/ses/docs/reference.md
@@ -178,8 +178,10 @@ below.
   </tr>
   <tr>
     <td><code>stackFiltering</code></td>
-    <td><code>'concise'</code> (default) or <code>'verbose'</code></td>
-    <td><code>'concise'</code> preserves important deep stack info,<br>
+    <td><code>'concise'</code> (default) or <code>'omit-frames'</code>  or <code>'shorten-paths'</code> or <code>'verbose'</code></td>
+    <td><code>'concise'</code> preserves important deep stack info, omitting likely unimportant frames and shortening paths<br>
+        <code>'omit-frames'</code> omits likely unimportant frames<br>
+        <code>'shorten-paths'</code> shortens paths to text likely clickable in an IDE<br>
         <code>'verbose'</code> console shows full deep stacks</td>
   </tr>
   <tr>
@@ -314,7 +316,11 @@ option and the platform error behavior.
 ```js
 lockdown(); // stackFiltering defaults to 'concise'
 // or
-lockdown({ stackFiltering: 'concise' }); // Preserve important deep stack info
+lockdown({ stackFiltering: 'concise' }); // Preserve important deep stack info, omitting likely unimportant frames and shortening paths
+// vs
+lockdown({ stackFiltering: 'omit-frames' }); // Omit likely uninteresting frames
+// vs
+lockdown({ stackFiltering: 'shorten-paths' }); // Shorten paths to text likely clickable in an IDE
 // vs
 lockdown({ stackFiltering: 'verbose' }); // Console shows full deep stacks
 ```
diff --git a/packages/ses/src/error/tame-v8-error-constructor.js b/packages/ses/src/error/tame-v8-error-constructor.js
diff --git a/packages/ses/src/lockdown.js b/packages/ses/src/lockdown.js
diff --git a/packages/ses/types.d.ts b/packages/ses/types.d.ts
