Debugging contracts in tests (Trial)

[kriskowal]

Update: 2023-12-04 source maps are not currently threaded through Zoe so debugging a bundled contract, even under Node.js, will not work end to end.

As security conscious engineers, we are inclined to handle source maps with care. One does not simply trust a source map as an attacker can craft a source map that hides their attack. One should not scrutinize a contract through the lens of a source map. However, if you’re debugging your own contract, a source map can hide some of the mechanisms behind our virtualization of modules in Hardened JavaScript. While we continue to make these mechanisms less invasive for the sake of auditors, you can reap the benefits of a better developer experience by enabling local source map debugging.

We facilitate source maps in contracts by keeping a content-addressed source map cache in your home directory. The bundler and importer must both be configured to recognize this cache in your tests.

Bundling

If you’re using the bundle-source CLI from @endo/bundle-source, the source map cache is on by default.

If you’re using bundleSource directly from @endo/bundle-source, the cacheSourceMaps option must be enabled explicitly.

import bundleSource from '@endo/bundle-source';
const bundle = await bundleSource(entryPath, { cacheSourceMaps: true });

If you’re using makeNodeBundleCache from @endo/bundle-source/cache.js:

import { makeNodeBundleCache } from '@endo/bundle-source/cache.js';
const cache = makeNodeBundleCache('bundles', {
  cacheSourceMaps: true,
}, nodeModuleSpecifier => import(nodeModuleSpecifier));
const bundle = cache.load(entryPath);

Importing

If you’re using importBundle directly from @endo/import-bundle thread the computeSourceMapLocation power from @endo/import-bundle/source-map-node.js:

import { importBundle } from '@endo/import-bundle';
import { computeSourceMapLocation } from '@endo/import-bundle/source-map-node.js';
const application = importBundle(bundle, { computeSourceMapLocation });

[erights]

In test-automaticRefund.js changing

agoric-sdk/packages/zoe/test/unitTests/contracts/test-automaticRefund.js

Line 21 in e26232e

const bundle = await bundleSource(automaticRefundRoot);

to

  const bundle = await bundleSource(automaticRefundRoot, {
    cacheSourceMaps: true,
  });

causes type error

$ tsc
test/unitTests/contracts/test-automaticRefund.js(21,24): error TS2769: No overload matches this call.
  Overload 1 of 4, '(startFilename: string, format: ModuleFormat, powers?: { read?: ReadFn | undefined; canonical?: CanonicalFn | undefined; externals?: string[] | undefined; } | undefined): Promise<...>', gave the following error.
    Argument of type '{ cacheSourceMaps: boolean; }' is not assignable to parameter of type 'ModuleFormat'.
  Overload 2 of 4, '(startFilename: string, bundleOptions: BundleOptions<"endoZipBase64">, powers?: { read?: ReadFn | undefined; canonical?: CanonicalFn | undefined; externals?: string[] | undefined; } | undefined): Promise<...>', gave the following error.
    Argument of type '{ cacheSourceMaps: boolean; }' is not assignable to parameter of type 'BundleOptions<"endoZipBase64">'.
      Object literal may only specify known properties, and 'cacheSourceMaps' does not exist in type 'BundleOptions<"endoZipBase64">'.
  Overload 3 of 4, '(startFilename: string, formatOrOptions?: ModuleFormat | BundleOptions<ModuleFormat> | undefined, powers?: { read?: ReadFn | undefined; canonical?: CanonicalFn | undefined; externals?: string[] | undefined; } | undefined): Promise<...>', gave the following error.
    Argument of type '{ cacheSourceMaps: boolean; }' is not assignable to parameter of type 'ModuleFormat | BundleOptions<ModuleFormat> | undefined'.
      Object literal may only specify known properties, and 'cacheSourceMaps' does not exist in type 'BundleOptions<ModuleFormat>'.
error Command failed with exit code 2.                                                                                                                                                                                            
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
ERROR: "lint:types" exited with 2.
error Command failed with exit code 1.                                                                                                                                                                                            

[erights]

Doesn't seem to work for me. I made the changes shown in the following diff

diff --git a/packages/zoe/src/contracts/automaticRefund.js b/packages/zoe/src/contracts/automaticRefund.js
index 1167ff9ce..12bde9422 100644
--- a/packages/zoe/src/contracts/automaticRefund.js
+++ b/packages/zoe/src/contracts/automaticRefund.js
@@ -15,6 +15,7 @@ import { Far } from '@endo/marshal';
  * @param {ZCF<{}>} zcf
  */
 const start = zcf => {
+  debugger;
   let offersCount = 0n;
 
   /** @type {OfferHandler} */
diff --git a/packages/zoe/test/unitTests/contracts/test-automaticRefund.js b/packages/zoe/test/unitTests/contracts/test-automaticRefund.js
index 317e668a7..577bee87c 100644
--- a/packages/zoe/test/unitTests/contracts/test-automaticRefund.js
+++ b/packages/zoe/test/unitTests/contracts/test-automaticRefund.js
@@ -2,13 +2,23 @@ import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
 
 import path from 'path';
 
-import bundleSource from '@endo/bundle-source';
+import rawBundleSource from '@endo/bundle-source';
 import { E } from '@endo/eventual-send';
 import { claim, splitMany } from '@agoric/ertp/src/legacy-payment-helpers.js';
 
 import { setup } from '../setupBasicMints.js';
 import { setupNonFungible } from '../setupNonFungibleMints.js';
 
+const bundleSource = (startFilename, options = {}, powers = undefined) =>
+  rawBundleSource(
+    startFilename,
+    {
+      cacheSourceMaps: true,
+      ...options,
+    },
+    powers,
+  );
+
 const filename = new URL(import.meta.url).pathname;
 const dirname = path.dirname(filename);

did a yarn build

And then ran in vscode under the debugger. I see the debugger stopped in the right-hand pane below:

[erights]

Those diffs now at #8541

[erights]

Probably a completely separate problem, but just in case. When I run in the debugger to get to the debugger; statement, along the way the debugger stops at

Any idea why?

[erights]

Another possibly related mystery. Without cacheSourceMaps in the GiMiX project I see

which I would only expect to see if gimix.js used keyShape as a variable name. However, on both the source and the mangled bundle, there is only one mention of keyShape, and it is as a property name:

[mhofman]

Not sure why <node_internals> is showing up for some endo and agoric packages.

For helping VS code find the sources referenced by the source maps, it may need some config help. Some pointers:

• sourceMapResolution
• sourceMapPathOverrides

[kriskowal]

I’ve filed a task to thread a relevant option thru to importBundle in Zoë or SwingSet controller so it can rendezvous the sourceMapURL #8580

I also observed over @dckc’s shoulder that I need to add to the front-matter of this discussion instructions on how to thread the bundle source option thru makeNodeBundleCache.

[kriskowal]

Source maps are clearly not working end-to-end. Zoë is not injecting source map URLs.

Per #8611, Zoë itself is a bundled contract, and because @import-bundle/source-map-node.js depends on Node.js’s URL package, Zoë is going to need a custom computeSourceMapURL and for that to be threaded differently. Zoë does not need the URL module’s IO power, but will need to be configured with the cache’s file:/// URL and for that to be threaded somehow.

[dckc]

Zoë itself is a bundled contract

nit: it's bundled, like source for all vats; but it's not a contract.