Add inline template definitions to pointer schema

- Define `templates`/`in` collection type for declaring templates
  within a pointer, following the `define`/`in` pattern from scope
- Implement template context stack in dereference loop to merge
  inline templates with external templates (inline takes precedence)
- Update struct storage example to define `packed-field` template
  inline, making the example fully self-contained
- Add documentation page for templates collection
- Add unit tests for inline template definitions

Author: gnidan

packages/format/src/types/pointer/pointer.ts

@@ -130,15 +130,17 @@ export namespace Pointer {
     | Collection.List
     | Collection.Conditional
     | Collection.Scope
-    | Collection.Reference;
+    | Collection.Reference
+    | Collection.Templates;
 
   export const isCollection = (value: unknown): value is Collection =>
     [
       Collection.isGroup,
       Collection.isList,
       Collection.isConditional,
       Collection.isScope,
-      Collection.isReference
+      Collection.isReference,
+      Collection.isTemplates
     ].some(guard => guard(value));
 
   export namespace Collection {
@@ -223,6 +225,23 @@ export namespace Pointer {
             ([k, v]) => isIdentifier(k) && isIdentifier(v)
           )
         ))
+
+    export interface Templates {
+      templates: {
+        [identifier: string]: Pointer.Template;
+      };
+      in: Pointer;
+    }
+
+    export const isTemplates = (value: unknown): value is Templates =>
+      !!value &&
+        typeof value === "object" &&
+        "templates" in value &&
+        typeof value.templates === "object" && !!value.templates &&
+        Object.keys(value.templates).every(isIdentifier) &&
+        Object.values(value.templates).every(isTemplate) &&
+        "in" in value &&
+        isPointer(value.in);
   }
 
   export type Expression =

packages/pointers/src/dereference/generate.ts

@@ -38,15 +38,27 @@ export async function* generateRegions(
   // Stack of rename mappings for template references with yields
   const renameStack: Array<Record<string, string>> = [];
 
+  // Stack of template definitions for inline templates
+  const templatesStack: Array<Pointer.Templates> = [];
+
   const stack: Memo[] = [Memo.dereferencePointer(pointer)];
   while (stack.length > 0) {
     const memo: Memo = stack.pop() as Memo;
 
     let memos: Memo[] = [];
     switch (memo.kind) {
       case "dereference-pointer": {
+        // Merge inline templates with base templates (inline takes precedence)
+        const currentTemplates = templatesStack.reduce(
+          (acc, templates) => ({ ...acc, ...templates }),
+          options.templates
+        );
+
         // Process the pointer, intercepting yielded regions to apply renames
-        const process = processPointer(memo.pointer, options);
+        const process = processPointer(memo.pointer, {
+          ...options,
+          templates: currentTemplates
+        });
         let result = await process.next();
         while (!result.done) {
           let region = result.value;
@@ -95,6 +107,14 @@ export async function* generateRegions(
         renameStack.pop();
         break;
       }
+      case "push-templates": {
+        templatesStack.push(memo.templates);
+        break;
+      }
+      case "pop-templates": {
+        templatesStack.pop();
+        break;
+      }
     }
 
     // add new memos to the stack in reverse order

packages/pointers/src/dereference/index.test.ts

@@ -479,4 +479,144 @@ describe("dereference", () => {
     expect(regions[1].name).toEqual("outer-data");
     expect(regions.named("outer-data")).toHaveLength(2);
   });
+
+  it("works for inline template definitions", async () => {
+    const pointer: Pointer = {
+      templates: {
+        "memory-range": {
+          expect: ["offset", "length"],
+          for: {
+            location: "memory",
+            offset: "offset",
+            length: "length"
+          }
+        }
+      },
+      in: {
+        define: {
+          "offset": 0,
+          "length": 32
+        },
+        in: {
+          template: "memory-range"
+        }
+      }
+    };
+
+    const cursor = await dereference(pointer);
+    const { regions } = await cursor.view(state);
+
+    expect(regions).toHaveLength(1);
+    expect(regions[0].offset).toEqual(Data.fromNumber(0));
+    expect(regions[0].length).toEqual(Data.fromNumber(32));
+  });
+
+  it("inline templates take precedence over external templates", async () => {
+    // External template defines a slot-based region
+    const externalTemplates: Pointer.Templates = {
+      "my-region": {
+        expect: ["value"],
+        for: {
+          name: "external",
+          location: "storage",
+          slot: "value"
+        }
+      }
+    };
+
+    // Inline template overrides with memory-based region
+    const pointer: Pointer = {
+      templates: {
+        "my-region": {
+          expect: ["value"],
+          for: {
+            name: "inline",
+            location: "memory",
+            offset: "value",
+            length: 32
+          }
+        }
+      },
+      in: {
+        define: { "value": 64 },
+        in: {
+          template: "my-region"
+        }
+      }
+    };
+
+    const cursor = await dereference(pointer, { templates: externalTemplates });
+    const { regions } = await cursor.view(state);
+
+    expect(regions).toHaveLength(1);
+    expect(regions[0].name).toEqual("inline");
+    expect(regions[0].location).toEqual("memory");
+  });
+
+  it("works for nested inline templates", async () => {
+    const pointer: Pointer = {
+      templates: {
+        "outer-template": {
+          expect: ["base"],
+          for: {
+            templates: {
+              "inner-template": {
+                expect: ["offset"],
+                for: {
+                  name: "data",
+                  location: "memory",
+                  offset: "offset",
+                  length: 32
+                }
+              }
+            },
+            in: {
+              define: { "offset": "base" },
+              in: { template: "inner-template" }
+            }
+          }
+        }
+      },
+      in: {
+        define: { "base": 128 },
+        in: { template: "outer-template" }
+      }
+    };
+
+    const cursor = await dereference(pointer);
+    const { regions } = await cursor.view(state);
+
+    expect(regions).toHaveLength(1);
+    expect(regions[0].name).toEqual("data");
+    expect(regions[0].offset).toEqual(Data.fromNumber(128));
+  });
+
+  it("inline templates with yields work correctly", async () => {
+    const pointer: Pointer = {
+      templates: {
+        "named-slot": {
+          expect: ["slot"],
+          for: {
+            name: "value",
+            location: "storage",
+            slot: "slot"
+          }
+        }
+      },
+      in: {
+        define: { "slot": 5 },
+        in: {
+          template: "named-slot",
+          yields: { "value": "my-slot-value" }
+        }
+      }
+    };
+
+    const cursor = await dereference(pointer);
+    const { regions } = await cursor.view(state);
+
+    expect(regions).toHaveLength(1);
+    expect(regions[0].name).toEqual("my-slot-value");
+    expect(regions.lookup["my-slot-value"]).toBeDefined();
+  });
 });

packages/pointers/src/dereference/memo.ts

@@ -10,7 +10,9 @@ export type Memo =
   | Memo.SaveRegions
   | Memo.SaveVariables
   | Memo.PushRegionRenames
-  | Memo.PopRegionRenames;
+  | Memo.PopRegionRenames
+  | Memo.PushTemplates
+  | Memo.PopTemplates;
 
 export namespace Memo {
   /**
@@ -105,4 +107,37 @@ export namespace Memo {
   export const popRegionRenames = (): PopRegionRenames => ({
     kind: "pop-region-renames"
   });
+
+  /**
+   * A request to push template definitions onto the context stack.
+   * While active, these templates are available for use by reference
+   * collections.
+   */
+  export interface PushTemplates {
+    kind: "push-templates";
+    templates: Pointer.Templates;
+  }
+
+  /**
+   * Initialize a PushTemplates memo
+   */
+  export const pushTemplates =
+    (templates: Pointer.Templates): PushTemplates => ({
+      kind: "push-templates",
+      templates
+    });
+
+  /**
+   * A request to pop the current template definitions from the context stack.
+   */
+  export interface PopTemplates {
+    kind: "pop-templates";
+  }
+
+  /**
+   * Initialize a PopTemplates memo
+   */
+  export const popTemplates = (): PopTemplates => ({
+    kind: "pop-templates"
+  });
 }

packages/pointers/src/dereference/process.ts

@@ -61,6 +61,10 @@ export async function* processPointer(
     return yield* processReference(collection, options);
   }
 
+  if (Pointer.Collection.isTemplates(collection)) {
+    return yield* processTemplates(collection, options);
+  }
+
   console.error("%s", JSON.stringify(pointer, undefined, 2));
   throw new Error("Unexpected unknown kind of pointer");
 }
@@ -203,3 +207,16 @@ async function* processReference(
     Memo.dereferencePointer(pointer)
   ];
 }
+
+async function* processTemplates(
+  collection: Pointer.Collection.Templates,
+  options: ProcessOptions
+): Process {
+  const { templates, in: in_ } = collection;
+
+  return [
+    Memo.pushTemplates(templates),
+    Memo.dereferencePointer(in_),
+    Memo.popTemplates()
+  ];
+}

packages/pointers/src/test-cases.ts

@@ -3,35 +3,19 @@ import {
   findExamplePointer,
   type ObserveTraceOptions
 } from "../test/index.js";
-import { Pointer } from "@ethdebug/format";
 import { type Cursor, Data } from "./index.js";
 
 export interface ObserveTraceTest<V> extends ObserveTraceOptions<V> {
   expectedValues: V[];
 }
 
-const packedFieldTemplate: Pointer.Template = {
-  expect: ["struct-storage-contract-variable-slot", "previous", "size"],
-  for: {
-    name: "field",
-    location: "storage",
-    slot: "struct-storage-contract-variable-slot",
-    offset: {
-      $difference: ["previous", "size"]
-    },
-    length: "size"
-  }
-};
-
 const structStorageTest: ObserveTraceTest<{
   x: number;
   y: number;
   salt: string;
 }> = {
+  // This pointer defines the "packed-field" template inline
   pointer: findExamplePointer("packed-field"),
-  templates: {
-    "packed-field": packedFieldTemplate
-  },
   compileOptions: singleSourceCompilation({
     path: "StructStorage.sol",
     contractName: "StructStorage",

packages/web/spec/pointer/collection/templates.mdx

@@ -0,0 +1,17 @@
+---
+sidebar_position: 7
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Templates
+
+A templates collection defines pointer templates inline, making them available
+for use by reference collections within the `in` pointer.
+
+This follows the same pattern as scope (`define`/`in`) but for templates
+instead of variables.
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/pointer/collection/templates" }}
+  />

packages/web/spec/pointer/overview.mdx

@@ -77,5 +77,6 @@ see the navigation bar for complete contents.
   - [**ethdebug/format/pointer/collection/conditional**](/spec/pointer/collection/conditional)
   - [**ethdebug/format/pointer/collection/scope**](/spec/pointer/collection/scope)
   - [**ethdebug/format/pointer/collection/reference**](/spec/pointer/collection/reference)
+  - [**ethdebug/format/pointer/collection/templates**](/spec/pointer/collection/templates)
 
 - [Expression syntax](/spec/pointer/expression) (**ethdebug/format/pointer/expression** schema listing)

packages/web/src/schemas.ts

@@ -105,7 +105,7 @@ const pointerSchemaIndex: SchemaIndex = {
 
   ...(
     [
-      "group", "list", "conditional", "scope", "reference"
+      "group", "list", "conditional", "scope", "reference", "templates"
     ].map(collection => ({
       [`schema:ethdebug/format/pointer/collection/${collection}`]: {
         href: `/spec/pointer/collection/${collection}`