bugc: emit fold transform on constant folding (#225)

* bugc: emit fold transform on constant folding

Marks constant-folded values with transform:["fold"] so debuggers
can show that a value is a compile-time-evaluated constant rather
than source the user wrote.

Adds Ir.Utils.addTransform(debug, ...ids), which composes transform
markers as a flat sibling key on a debug context (per the flat-
composition convention) and appends to any existing transform array
— so an instruction touched by multiple passes accumulates the
multiset (e.g. ["fold","coalesce"]).

ConstantFoldingStep applies it to folded binary and hash results.
Although a folded const instruction is typically dissolved by
constant propagation + DCE, ConstantPropagationStep already carries
the folded const's operationDebug into the consuming instruction, so
the marker survives to the emitted bytecode's runtimeInstructions
(the tracer widget's path) at levels 1-3.

Adds an end-to-end test asserting the fold marker reaches the
bytecode at levels 1/2/3 and is absent at level 0.

* bugc: route tailcall transform through addTransform helper

Refactor buildTailCallJumpOptions to emit its transform:["tailcall"]
marker via Ir.Utils.addTransform instead of a hand-written key, so all
transform emission (fold/tailcall/coalesce/...) routes through the one
helper. Behavior is identical — the back-edge JUMP still carries
return + invoke + transform:["tailcall"] — but composition stays
consistent (e.g. a folded-then-tailcall instruction would accumulate
the multiset) and there's no divergent hand-rolled site.

Existing #217 tailcall tests pass unchanged.

Author: gnidan

packages/bugc/src/evmgen/generation/control-flow/terminator.ts

@@ -1,5 +1,6 @@
 import type * as Format from "@ethdebug/format";
 import type * as Ir from "#ir";
+import { Utils as IrUtils } from "#ir";
 import type * as Evm from "#evm";
 import type { Stack } from "#evm";
 import type { State } from "#evmgen/state";
@@ -440,7 +441,7 @@ function generateReturnEpilogue<S extends Stack>(
  * resolved later by patchInvokeTarget.
  */
 function buildTailCallJumpOptions(tailCall: Ir.Block.TailCall): {
-  debug: { context: Format.Program.Context };
+  debug: Ir.Instruction.Debug;
 } {
   const declaration =
     tailCall.declarationLoc && tailCall.declarationSourceId
@@ -451,8 +452,7 @@ function buildTailCallJumpOptions(tailCall: Ir.Block.TailCall): {
       : undefined;
 
   const combined: Format.Program.Context.Return &
-    Format.Program.Context.Invoke &
-    Format.Program.Context.Transform = {
+    Format.Program.Context.Invoke = {
     return: {
       identifier: tailCall.function,
       ...(declaration ? { declaration } : {}),
@@ -469,10 +469,18 @@ function buildTailCallJumpOptions(tailCall: Ir.Block.TailCall): {
         },
       },
     },
-    transform: ["tailcall"],
   };
 
-  return { debug: { context: combined as Format.Program.Context } };
+  // Route through the shared helper so all transform emission
+  // (fold/tailcall/coalesce/...) composes consistently: the
+  // `transform` marker becomes a flat sibling key appended to
+  // any existing transform array.
+  return {
+    debug: IrUtils.addTransform(
+      { context: combined as Format.Program.Context },
+      "tailcall",
+    ),
+  };
 }
 
 /** PUSH an integer as the smallest PUSHn. */

packages/bugc/src/evmgen/transform-contexts.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Verifies that optimizer `transform` markers are emitted onto
+ * the resulting bytecode's debug contexts, on the same
+ * `runtimeInstructions` path the docs tracer widget consumes.
+ *
+ * Level 1 constant folding attaches `transform: ["fold"]` to the
+ * folded value's instruction; a debugger can then show that a
+ * PUSH is a compile-time-evaluated constant rather than source
+ * the user wrote.
+ */
+import { describe, it, expect } from "vitest";
+
+import { compile } from "#compiler";
+import type * as Format from "@ethdebug/format";
+import { Program } from "@ethdebug/format";
+
+const { Context } = Program;
+
+type OptLevel = 0 | 1 | 2 | 3;
+
+async function compileBytecode(source: string, level: OptLevel) {
+  const result = await compile({
+    to: "bytecode",
+    source,
+    optimizer: { level },
+  });
+  if (!result.success) {
+    const errors = result.messages.error ?? [];
+    throw new Error(
+      `Compilation failed at level ${level}:\n` +
+        errors
+          .map((e: { message?: string }) => e.message ?? String(e))
+          .join("\n"),
+    );
+  }
+  return result.value.bytecode;
+}
+
+/** Flatten a context into leaves, unwrapping gather/pick. */
+function leaves(ctx: Format.Program.Context): Format.Program.Context[] {
+  if (Context.isGather(ctx)) return ctx.gather.flatMap(leaves);
+  if ("pick" in ctx && Array.isArray((ctx as { pick: unknown[] }).pick)) {
+    return (ctx as { pick: Format.Program.Context[] }).pick.flatMap(leaves);
+  }
+  return [ctx];
+}
+
+/**
+ * Count instructions in the widget-path array whose context
+ * (at top level or in any leaf) carries a transform containing
+ * the given identifier.
+ */
+function countTransform(
+  instructions: { debug?: { context?: Format.Program.Context } }[],
+  id: string,
+): number {
+  let count = 0;
+  for (const instr of instructions) {
+    const ctx = instr.debug?.context;
+    if (!ctx) continue;
+    const hit = [ctx, ...leaves(ctx)].some(
+      (c) => Context.isTransform(c) && c.transform.includes(id),
+    );
+    if (hit) count += 1;
+  }
+  return count;
+}
+
+describe("optimizer emits fold transform contexts", () => {
+  // `2 + 3` and `4 * 5` fold to constants at level 1.
+  const source = `name Fold;
+
+storage { [0] r: uint256; }
+create { r = 0; }
+code { r = (2 + 3) * (4 * 5); }`;
+
+  it("emits no fold transform at level 0", async () => {
+    const bc = await compileBytecode(source, 0);
+    expect(countTransform(bc.runtimeInstructions, "fold")).toBe(0);
+  });
+
+  for (const level of [1, 2, 3] as const) {
+    it(`emits fold transform at level ${level}`, async () => {
+      const bc = await compileBytecode(source, level);
+      expect(countTransform(bc.runtimeInstructions, "fold")).toBeGreaterThan(0);
+    });
+  }
+});

packages/bugc/src/ir/utils/debug.ts

@@ -350,3 +350,36 @@ export function preserveSubInstructionDebug(
     ...additionalContexts.map((c) => ({ context: c })),
   );
 }
+
+/**
+ * Add one or more `transform` optimization markers to a debug
+ * context, composing them as a flat sibling key alongside any
+ * existing context discriminators (per the flat-composition
+ * convention: gather is only for same-key collisions).
+ *
+ * Markers are appended to any existing `transform` array on the
+ * context, so an instruction touched by multiple passes
+ * accumulates the multiset — e.g. a folded value later merged
+ * yields `transform: ["fold", "coalesce"]`.
+ */
+export function addTransform(
+  debug: Ir.Instruction.Debug | undefined,
+  ...ids: Format.Program.Context.Transform.Identifier[]
+): Ir.Instruction.Debug {
+  const existing = debug?.context;
+
+  const prior: Format.Program.Context.Transform.Identifier[] =
+    existing &&
+    "transform" in existing &&
+    Array.isArray((existing as Format.Program.Context.Transform).transform)
+      ? (existing as Format.Program.Context.Transform).transform
+      : [];
+
+  const transform = [...prior, ...ids];
+
+  if (!existing) {
+    return { context: { transform } };
+  }
+
+  return { context: { ...existing, transform } };
+}

packages/bugc/src/optimizer/steps/constant-folding.ts

@@ -134,7 +134,10 @@ export class ConstantFoldingStep extends BaseOptimizationStep {
       value: result,
       type: this.getResultType(inst.op, typeof result),
       dest: inst.dest,
-      operationDebug: Ir.Utils.preserveDebug(inst),
+      operationDebug: Ir.Utils.addTransform(
+        Ir.Utils.preserveDebug(inst),
+        "fold",
+      ),
     };
   }
 
@@ -266,7 +269,10 @@ export class ConstantFoldingStep extends BaseOptimizationStep {
       value: hashValue,
       type: Ir.Type.Scalar.bytes32,
       dest: inst.dest,
-      operationDebug: Ir.Utils.preserveDebug(inst),
+      operationDebug: Ir.Utils.addTransform(
+        Ir.Utils.preserveDebug(inst),
+        "fold",
+      ),
     };
   }