[wip]

packages/tests/schemas/examples.test.ts

@@ -14,6 +14,7 @@ const idsOfSchemasAllowedToOmitExamples = new Set([
   "schema:ethdebug/format/pointer/region",
   "schema:ethdebug/format/pointer/collection",
   "schema:ethdebug/format/operation",
+  "schema:ethdebug/format/operation/base",
 ]);
 
 describe("Examples", () => {

packages/web/notes

@@ -0,0 +1,22 @@
+ethdebug/format/operation
+  /scope/begin
+  /scope/end
+  /scope/declare
+  /scope/assign
+  /scope/allocate
+  /scope/delete
+
+
+begin
+  **defines scope id (debugger action: push new stack frame for that scope ID)
+  may inherit from another scope id
+  may declare variables
+  may assign variables
+  may allocate variables
+
+
+scope: begin
+id: ...
+declare:
+  x:
+    type:

packages/web/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start",
+    "start": "docusaurus start --host 0.0.0.0",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",

schemas/operation/allocation/begin.schema.yaml

@@ -0,0 +1,51 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/allocation/begin"
+
+title: ethdebug/format/operation/allocation/begin
+description:
+  Describes the starting point for which a particular value has been allocated
+
+type: object
+
+properties:
+  begin:
+    type: string
+    const: allocation
+
+  variable:
+    type: object
+    properties:
+      scope:
+        type: object
+        properties:
+          id:
+            $ref: "schema:ethdebug/format/source/id"
+        required: [id]
+
+      identifier:
+        type: string
+
+      type:
+        $ref: "schema:ethdebug/format/type"
+
+    required:
+      - identifier
+      - type
+
+  pointer:
+    $ref: "schema:ethdebug/format/pointer"
+
+required:
+  - begin
+  - pointer
+
+examples:
+  - begin: allocation
+    variable:
+      identifier: x
+      type:
+        kind: uint
+        bits: 256
+    pointer:
+      location: stack
+      slot: 0

schemas/operation/base.schema.yaml

@@ -5,52 +5,36 @@ title: ethdebug/format/operation/base
 description:
   Defines the minimally necessary schema for a high-level program operation.
 type: object
-oneOf:
-  - $ref: "#/$defs/BeginOperation"
-  - $ref: "#/$defs/EndOperation"
-  - $ref: "#/$defs/SignalOperation"
 
-examples:
-  - activity: begin
-    mode: function-call
+allOf:
+  - oneOf:
+      - required:
+          - begin
+      - required:
+          - end
+      - required:
+          - signal
+  - if:
+      required:
+        - begin
+    then:
+      $ref: "#/$defs/BeginOperation"
 
 $defs:
   BeginOperation:
-    title: BeginOperation
-    description:
-      Represents an operation that starts a mode
     type: object
     properties:
-      activity:
-        const: begin
-      mode:
+      begin:
         type: string
-    required:
-      - activity
-      - mode
 
   EndOperation:
-    title: EndOperation
-    description:
-      Represents an operation that ends a mode
+    type: object
     properties:
-      activity:
-        const: end
-      mode:
+      end:
         type: string
-    required:
-      - activity
-      - mode
 
   SignalOperation:
-    title: SignalOperation
-    description:
-      Represents an operation that is a point-in-time effect
+    type: object
     properties:
-      activity:
-        const: signal
-      topic:
+      signal:
         type: string
-    required:
-      - activity
-      - topic

schemas/operation/function-call/begin.schema.yaml

@@ -0,0 +1,33 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/function-call/begin"
+
+title: ethdebug/format/operation/function-call/begin
+description:
+  Describes the start of a function call operation
+type: object
+
+properties:
+  begin:
+    type: string
+    const: function-call
+
+  definition:
+    type: object
+    properties:
+      name:
+        type: string
+    $ref: "schema:ethdebug/format/source"
+    required:
+      - name
+      - source
+      - range
+
+examples:
+  - begin: function-call
+    definition:
+      name: transfer
+      source:
+        id: 1
+      range:
+        offset: 111
+        length: 82

schemas/operation/scope.schema.yaml

@@ -0,0 +1,27 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/scope"
+
+title: ethdebug/format/operation/scope
+description: |
+  Represents a scope operation
+type: object
+
+properties:
+  action:
+    const: scope
+
+
+allOf:
+  - oneOf:
+      - required: [begin]
+      - required: [end]
+      - required: [scope]
+  - if:
+      required: [begin]
+    then:
+      properties:
+        id:
+          type: [number, string]
+        parent:
+          type: [number, string]
+

schemas/operation/scope/begin.schema.yaml

@@ -0,0 +1,42 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/scope/begin"
+
+title: ethdebug/format/operation/scope/begin
+description: |
+  Describes the start of a new variables scope.
+
+type: object
+
+properties:
+  begin:
+    type: string
+    const: scope
+
+  id:
+    description:
+      The scope ID (defined by compiler)
+    $ref: "schema:ethdebug/format/source/id"
+
+  variables:
+    title: Variables by identifier
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/operation/scope/variable"
+
+required:
+  - id
+  - variables
+
+$ref: "schema:ethdebug/format/operation/base"
+
+examples:
+  - begin: scope
+    id: s__function__call__ragequit__uint256
+    variables:
+      "amount":
+        type:
+          kind: uint
+          bits: 256
+        pointer:
+          location: stack
+          slot: 0

schemas/operation/scope/variable.schema.yaml

@@ -0,0 +1,80 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/scope/variable"
+
+title: ethdebug/format/operation/scope/variable
+description: |
+  Describes a variable as it appears in scope.
+
+type: object
+
+properties:
+  type:
+    $ref: "schema:ethdebug/format/type"
+  pointer:
+    title: Optional ethdebug/format/pointer
+  declaration:
+    $ref: "schema:ethdebug/format/source"
+    required: [range]
+
+if:
+  required: [pointer]
+then:
+  properties:
+    uninitialized:
+      type: boolean
+      default: false
+
+required:
+  - type
+
+examples:
+  - type:
+      kind: uint
+      bits: 256
+    declaration:
+      source:
+        id: 3
+      range:
+        #   uint256 x = ...
+        #   ^^^^^^^^^
+        offset: 555
+        length: 9
+      ast:
+        node:
+          id: 1
+
+  - type:
+      kind: array
+      contains:
+        type:
+          kind: uint
+          bits: 256
+    pointer:
+      # example borrowed from ethdebug/format/pointer; see comments there
+      group:
+        - name: "array-start"
+          location: stack
+          slot: 0
+
+        - name: "array-count"
+          location: memory
+          offset:
+            $read: "array-start"
+          length: $wordsize
+
+        - list:
+            count:
+              $read: "array-count"
+            each: "item-index"
+            is:
+              name: "array-item"
+              location: "memory"
+              offset:
+                $sum:
+                  - .offset: "array-count"
+                  - .length: "array-count"
+                  - $product:
+                      - "item-index"
+                      - .length: "array-item"
+              length: $wordsize
+    uninitialized: true

schemas/source.schema.yaml

@@ -0,0 +1,36 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/source"
+
+title: ethdebug/format/source
+description:
+  Describes a reference to a source or range of characters within that source.
+type: object
+
+properties:
+  source:
+    type: object
+    properties:
+      id:
+        $ref: "schema:ethdebug/format/source/id"
+    required: [id]
+  range:
+    title: Source range
+    $ref: "schema:ethdebug/format/source/range"
+  ast:
+    title: AST node information
+    $ref: "schema:ethdebug/format/source/ast"
+
+required:
+  - source
+
+examples:
+  - source:
+      id: 1
+  - source:
+      id: 2
+    range:
+      offset: 10
+      length: 23
+    ast:
+      node:
+        id: 88