ref(wasm): share build id stamping across prepare and sourcemaps

- Give on-disk build id stamping a single home in lib/wasm/stamp.ts, so
  every command stamps under the same rule
- Keep split.ts pure: it stays a bytes-in/bytes-out port of the Rust
  wasm-split, with stamp.ts as the filesystem layer above it
- Write sourcemap debug IDs through the existing map mutation path
- Drop a stamping option no command used

Author: d2anamaria

packages/cli/src/lib/sourcemap/debug-id.ts

@@ -72,9 +72,10 @@ export type SourcemapStampResult = {
  *
  * Unlike {@link injectDebugId} this touches no host file, so it suits maps
  * whose companion artifact is not JavaScript — a wasm module carries its own
- * id in a custom section and must never be rewritten as text. Nothing is
- * offset either: `mappings` only shifts when injection prepends a runtime
- * snippet line to a JS bundle.
+ * id in a custom section and must never be rewritten as text. The map itself is
+ * edited by {@link mutateSourcemap}, so it gains the id under both field
+ * spellings exactly as an injected map does, with no `mappings` offset:
+ * `mappings` only shifts when injection prepends a runtime snippet line.
  *
  * Idempotent: a map already carrying `debugId` is left byte-identical.
  *
@@ -96,8 +97,7 @@ export async function setSourcemapDebugId(
   if (options.dryRun) {
     return { written: false, replaced: existing };
   }
-  map.debug_id = debugId;
-  map.debugId = debugId;
+  mutateSourcemap(map, debugId, { offsetMappings: false });
   await writeFile(mapPath, JSON.stringify(map));
   return { written: true, replaced: existing };
 }

packages/cli/src/lib/sourcemap/wasm.ts

@@ -25,10 +25,10 @@ import { parseSections } from "../wasm/binary.js";
 import {
   buildIdFromSections,
   debugIdFromBuildId,
-  ensureWasmBuildId,
   formatBuildId,
 } from "../wasm/build-id.js";
 import { isDebugCompanionPath } from "../wasm/prepare.js";
+import { ensureBuildIdOnDisk } from "../wasm/stamp.js";
 import { setSourcemapDebugId } from "./debug-id.js";
 import { type DiscoveryDiagnostic, SOURCEMAP_SKIP_DIRS } from "./inject.js";
 
@@ -65,15 +65,10 @@ export type WasmSyncResult = {
   moduleStamped: boolean;
 };
 
-/** Controls the id a pair is reconciled onto, and whether anything is written. */
+/** Whether reconciling a pair is allowed to write. */
 export type WasmSyncOptions = {
   /** Report what would change without touching either file. */
   dryRun?: boolean;
-  /**
-   * Build id to stamp when the module has none. Defaults to a random UUID.
-   * A library-level seam for deterministic tests, not a CLI flag.
-   */
-  buildId?: Uint8Array;
 };
 
 /**
@@ -94,14 +89,11 @@ export async function syncWasmSourcemap(
 ): Promise<WasmSyncResult> {
   const { wasmPath, mapPath } = pair;
 
-  // One parse serves both the read and the stamp — `ensureWasmBuildId` takes
-  // the sections it should re-encode, so nothing re-reads the module.
-  const sections = parseSections(await readFile(wasmPath));
-  const existing = buildIdFromSections(sections);
-  const buildId = await ensureWasmBuildId(wasmPath, sections, existing, {
-    buildId: options.buildId,
-    dryRun: options.dryRun,
-  });
+  // One read serves both the lookup and the stamp. Reading the id first also
+  // spares an already-stamped module the full re-encode `stampBuildId` does.
+  const bytes = await readFile(wasmPath);
+  const existing = buildIdFromSections(parseSections(bytes));
+  const buildId = await ensureBuildIdOnDisk(wasmPath, bytes, existing, options);
   const moduleStamped = !existing && buildId !== null;
 
   const debugId = buildId

packages/cli/src/lib/wasm/prepare.ts

@@ -32,6 +32,7 @@ import {
   randomBuildId,
 } from "./build-id.js";
 import { splitWasm } from "./split.js";
+import { ensureBuildIdOnDisk, stampBuildId } from "./stamp.js";
 
 const log = logger.withTag("wasm.prepare");
 
@@ -239,49 +240,6 @@ async function readCompanionBuildId(path: string): Promise<Uint8Array | null> {
   }
 }
 
-/**
- * Give a module a build id, writing it back in place when it has none.
- *
- * `wasm-split` stamps every module it processes regardless of debug quality.
- * Sentry matches a stack frame to its debug file by build id, so an unstamped
- * module can never be symbolicated — not even from a debug file uploaded
- * later. Stamping now keeps that option open.
- *
- * @param path - Module to stamp.
- * @param bytes - The module as read from disk.
- * @param existing - Id the module already carries, if any.
- * @returns The effective build id, or `null` when a dry run left the module
- *   untouched.
- */
-async function ensureBuildIdOnDisk(
-  path: string,
-  bytes: Uint8Array,
-  existing: Uint8Array | null,
-  options: PrepareOptions
-): Promise<Uint8Array | null> {
-  // Checked before splitting so an already-stamped module is never re-encoded.
-  if (existing) {
-    return existing;
-  }
-  if (options.dryRun) {
-    return null;
-  }
-  const stamped = stampBuildId(bytes, options.buildId);
-  await writeFile(path, stamped.module);
-  return stamped.buildId;
-}
-
-/**
- * Stamp a module with a build id, changing nothing else.
- *
- * A split with neither `strip` nor `companion` is exactly that, so stamping
- * shares one implementation with the real split rather than reassembling the
- * section list by hand.
- */
-function stampBuildId(bytes: Uint8Array, buildId?: Uint8Array) {
-  return splitWasm(bytes, { ...(buildId ? { buildId } : {}) });
-}
-
 /** Whether two build ids are byte-identical. */
 function buildIdsMatch(a: Uint8Array | null, b: Uint8Array | null): boolean {
   if (!(a && b) || a.length !== b.length) {

packages/cli/src/lib/wasm/stamp.ts

@@ -0,0 +1,71 @@
+/**
+ * Writing a build id onto a module already on disk.
+ *
+ * Kept apart from `split.ts`, which stays a pure bytes-in/bytes-out port of the
+ * Rust `wasm-split`. Everything here is the file-level layer above it, shared
+ * by `debug-files prepare` and the wasm sourcemap path so both stamp under the
+ * same rule: an id already on the module always wins, and a dry run writes
+ * nothing.
+ */
+
+import { writeFile } from "node:fs/promises";
+import { type SplitWasmResult, splitWasm } from "./split.js";
+
+/** How to stamp a module that carries no build id yet. */
+export type StampOptions = {
+  /** Id to use when one must be minted. Defaults to a random v4 UUID. */
+  buildId?: Uint8Array;
+  /** Report what would change without writing. */
+  dryRun?: boolean;
+};
+
+/**
+ * Stamp a module with a build id, changing nothing else.
+ *
+ * A split with neither `strip` nor `companion` is exactly that, so stamping
+ * shares one implementation with the real split rather than reassembling the
+ * section list by hand.
+ *
+ * @param bytes - The module as read from disk
+ * @param buildId - Id to stamp when the module carries none
+ * @returns The effective id and the re-encoded module
+ */
+export function stampBuildId(
+  bytes: Uint8Array,
+  buildId?: Uint8Array
+): SplitWasmResult {
+  return splitWasm(bytes, { buildId });
+}
+
+/**
+ * Give a module a build id, writing it back in place when it has none.
+ *
+ * `wasm-split` stamps every module it processes regardless of debug quality.
+ * Sentry matches a stack frame to its debug file by build id, so an unstamped
+ * module can never be symbolicated — not even from a debug file uploaded
+ * later. Stamping now keeps that option open.
+ *
+ * @param path - Module to stamp
+ * @param bytes - The module as read from disk
+ * @param existing - Id the module already carries, if any
+ * @param options - Which id to mint, and whether to write at all
+ * @returns The effective build id, or `null` when a dry run left the module
+ *   untouched
+ */
+export async function ensureBuildIdOnDisk(
+  path: string,
+  bytes: Uint8Array,
+  existing: Uint8Array | null,
+  options: StampOptions = {}
+): Promise<Uint8Array | null> {
+  // Checked before splitting so an already-stamped module is never re-encoded.
+  if (existing) {
+    return existing;
+  }
+  if (options.dryRun) {
+    return null;
+  }
+  const stamped = stampBuildId(bytes, options.buildId);
+  await writeFile(path, stamped.module);
+  return stamped.buildId;
+}

packages/cli/test/lib/sourcemap/wasm.test.ts

@@ -16,12 +16,19 @@ import {
   discoverWasmPairs,
   syncWasmSourcemap,
 } from "../../../src/lib/sourcemap/wasm.js";
+import { parseSections } from "../../../src/lib/wasm/binary.js";
 import {
-  encodeModule,
-  makeBuildIdSection,
-  makeCustomSection,
-} from "../../../src/lib/wasm/binary.js";
-import { uuidToBytes } from "../../../src/lib/wasm/build-id.js";
+  buildIdFromSections,
+  debugIdFromBuildId,
+  formatBuildId,
+  uuidToBytes,
+} from "../../../src/lib/wasm/build-id.js";
+import {
+  byteVector,
+  customSection,
+  fromHex,
+  wasmModule,
+} from "../wasm/helpers.js";
 
 /** Deterministic build id used wherever the exact debug ID matters. */
 const FIXED_UUID = "00000000-0000-4000-8000-000000000000";
@@ -37,12 +44,14 @@ beforeEach(async () => {
 
 /** Write a wasm module, optionally carrying a `build_id`. */
 async function writeWasm(name: string, buildId?: string): Promise<string> {
-  const sections = [makeCustomSection("name", Uint8Array.from([0x00]))];
+  const sections = [customSection("name", fromHex("00"))];
   if (buildId) {
-    sections.push(makeBuildIdSection(uuidToBytes(buildId) as Uint8Array));
+    sections.push(
+      customSection("build_id", byteVector(uuidToBytes(buildId) as Uint8Array))
+    );
   }
   const path = join(dir, name);
-  await writeFile(path, encodeModule(sections));
+  await writeFile(path, wasmModule(sections));
   return path;
 }
 
@@ -67,6 +76,12 @@ async function readMap(path: string): Promise<Record<string, unknown>> {
   return JSON.parse(await readFile(path, "utf-8"));
 }
 
+/** Read the debug ID a module's `build_id` section stands for. */
+async function readModuleDebugId(path: string): Promise<string | undefined> {
+  const buildId = buildIdFromSections(parseSections(await readFile(path)));
+  return buildId ? debugIdFromBuildId(formatBuildId(buildId)) : undefined;
+}
+
 describe("syncWasmSourcemap", () => {
   test("stamps the map with the id the module already carries", async () => {
     const wasmPath = await writeWasm("app.wasm", FIXED_UUID);
@@ -89,14 +104,13 @@ describe("syncWasmSourcemap", () => {
     const wasmPath = await writeWasm("bare.wasm");
     const mapPath = await writeMap("bare.wasm.map");
 
-    const result = await syncWasmSourcemap(
-      { wasmPath, mapPath },
-      { buildId: uuidToBytes(FIXED_UUID) as Uint8Array }
-    );
+    const result = await syncWasmSourcemap({ wasmPath, mapPath });
 
     expect(result.moduleStamped).toBe(true);
-    expect(result.debugId).toBe(FIXED_UUID);
-    expect((await readMap(mapPath)).debug_id).toBe(FIXED_UUID);
+    // The minted id is random, so the invariant to check is that both sides
+    // ended up with the one now on the module.
+    expect(result.debugId).toBe(await readModuleDebugId(wasmPath));
+    expect((await readMap(mapPath)).debug_id).toBe(result.debugId);
   });
 
   test("writes nothing when the map already carries the module's id", async () => {
@@ -192,7 +206,12 @@ describe("discoverWasmPairs", () => {
     await mkdir(join(dir, "vendor"));
     await writeFile(
       join(dir, "vendor", "lib.wasm"),
-      encodeModule([makeBuildIdSection(uuidToBytes(FIXED_UUID) as Uint8Array)])
+      wasmModule([
+        customSection(
+          "build_id",
+          byteVector(uuidToBytes(FIXED_UUID) as Uint8Array)
+        ),
+      ])
     );
     await writeFile(join(dir, "vendor", "lib.wasm.map"), '{"version":3}');
     const wasmPath = await writeWasm("app.wasm", FIXED_UUID);