Merge pull request #89 from ethdebug/materials

Add namespace for schemas for external materials

packages/web/spec/materials/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "ethdebug/format/materials",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Work-in-progress formal schema for ethdebug format"
+  }
+}

packages/web/spec/materials/compilation.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Compilation schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/materials/compilation" }}
+  />

packages/web/spec/materials/id.mdx

@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Identifiers and references
+
+## Identifier schema
+
+This format defines a very loosely specified schema for external IDs.
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/materials/id" }}
+  />
+
+## Reference schema
+
+This format defines a schema for referencing external resources by ID.
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/materials/reference" }}
+  />

packages/web/spec/materials/overview.mdx

@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+:::tip
+
+**ethdebug/format/materials** is a namespace for schemas about external
+resources, including schemas for representing full compiler invocation details,
+schemas for individual sources, particular source ranges, and so on.
+
+Schemas in this namespace exist so that the rest of **ethdebug/format** has
+a consistent way of representing these external resources. These schemas also
+serve to define something of a data model: one aggregation aggregates multiple
+sources, e.g.
+
+:::
+
+This format defines a namespace of schemas for representing external resources
+relevant to smart contract debugging.
+
+## Reading these schemas
+
+The **ethdebug/format/materials** namespace is not a schema itself, but rather
+a collection of closely-related schemas.
+
+These schemas (like all schemas in this format) are specified as
+[JSON Schema](https://json-schema.org), draft 2020-12.
+
+Please refer to the following resources in this section, or see the navigation
+bar for complete contents.
+
+- [Identifiers and references](/spec/materials/id)
+- [Compilation schema](/spec/materials/compilation)
+- [Source schema](/spec/materials/source)
+- [Source range schema](/spec/materials/source-range)

packages/web/spec/materials/source-range.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Source range schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/materials/source-range" }}
+  />

packages/web/spec/materials/source.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Source schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/materials/source" }}
+  />

packages/web/src/schemas.ts

@@ -150,4 +150,24 @@ export const schemaIndex: SchemaIndex = {
     title: "Region reference",
     href: "/spec/pointer/expression#region-references"
   },
+
+  "schema:ethdebug/format/materials/id": {
+    title: "Identifier schema",
+    href: "/spec/materials/id#identifier-schema"
+  },
+
+  "schema:ethdebug/format/materials/reference": {
+    title: "Identifier schema",
+    href: "/spec/materials/id#reference-schema"
+  },
+
+  "schema:ethdebug/format/materials/compilation": {
+    title: "Compilation schema",
+    href: "/spec/materials/compilation"
+  },
+
+  "schema:ethdebug/format/materials/source": {
+    title: "Source schema",
+    href: "/spec/materials/source"
+  },
 };

schemas/materials/compilation.schema.yaml

@@ -0,0 +1,86 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/compilation"
+
+title: ethdebug/format/materials/compilation
+description: |
+  An object representing a single invocation of a compiler.
+
+type: object
+properties:
+  id:
+    description: |
+      Compilation ID. Optional, but **should** be specified.
+
+      This value **should** be globally-unique and generated only from the
+      compiler inputs (settings, sources, etc.); the same compiler inputs/
+      settings **should** produce the same identifier.
+
+    $ref: "schema:ethdebug/format/materials/id"
+
+  compiler:
+    type: object
+    title: Compiler name and version
+    properties:
+      name:
+        type: string
+        description: Compiler name
+
+      version:
+        type: string
+        description: |
+          Compiler version.
+
+          This value **should** be specified using the most detailed version
+          representation available, i.e., including source control hash and
+          compiler build information whenever possible.
+
+    required:
+      - name
+      - version
+
+    examples:
+      - name: lllc
+        version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++
+
+  settings:
+    description: |
+      Compiler settings in a format native to the compiler.
+
+      For compilers whose settings includes full source representations, this
+      field **should** be specified in such a way that avoids large data
+      redundancies (e.g. if compiler settings contain full source
+      representations, then this field would significantly duplicate the
+      information represented by the `sources` field in this object).
+
+      In situations where settings information duplicates information
+      represented elsewhere in **ethdebug/format**, compilers **may** adopt
+      any reasonable strategy, e.g.:
+        - omit duplications partially (leaving the rest of the settings
+          intact)
+        - omit this field entirely
+        - specify this field as a hash of the full settings
+          representation (with the expectation that users of this format will
+          have access to the full representation by some other means)
+
+    allOf:
+      - true
+
+  sources:
+    type: array
+    items:
+      $ref: "schema:ethdebug/format/materials/source"
+
+required:
+  - compiler
+  - sources
+
+examples:
+  - compiler:
+      name: lllc
+      version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++
+    sources:
+      - id: 0
+        path: stdin
+        contents: |
+          (add 1 (mul 2 (add 3 4)))
+        language: LLL

schemas/materials/id.schema.yaml

@@ -0,0 +1,13 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/id"
+
+title: ethdebug/format/materials/id
+description: An opaque external ID (likely generated by compiler)
+
+type:
+  - number
+  - string
+
+examples:
+  - 5
+  - "five"

schemas/materials/reference.schema.yaml

@@ -0,0 +1,22 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/reference"
+
+title: ethdebug/format/materials/reference
+description: A reference to an external resource by ID
+
+type: object
+properties:
+  id:
+    $ref: "schema:ethdebug/format/materials/id"
+
+  type:
+    enum:
+      - compilation
+      - source
+
+required: [id]
+
+unevaluatedProperties: false
+
+examples:
+  - id: 1

schemas/materials/source-range.schema.yaml

@@ -0,0 +1,56 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/source-range"
+
+title: ethdebug/format/materials/source-range
+description: |
+  A range of bytes in a particular source.
+
+  Note that this refers to the bytes range in the original character encoding
+  for the source, not the character encoding used for strings in this JSON
+  format (UTF-8). For compilers that support input sources in encodings other
+  than this format's transmission encoding, compilers **must** address source
+  ranges in this original encoding, and debuggers **must** re-encode source
+  contents obtained from this format _before_ performing any range addressing.
+
+  (Compilers that only accept UTF-8 or ASCII are naturally exempt from this
+  concern.)
+
+type: object
+properties:
+  compilation:
+    title: Compilation reference by ID
+    $ref: "schema:ethdebug/format/materials/reference"
+
+  source:
+    title: Source reference by ID
+    $ref: "schema:ethdebug/format/materials/reference"
+
+  range:
+    type: object
+    properties:
+      offset:
+        description: Byte offset at beginning of range
+        type: number
+
+      length:
+        description: Number of bytes contained in range
+        type: number
+
+    unevaluatedProperties: false
+
+    required:
+      - offset
+      - length
+
+unevaluatedProperties: false
+
+required:
+  - source
+  - range
+
+examples:
+  - source:
+      id: 5
+    range:
+      offset: 20
+      length: 100