test: add ethdebug/conformance

.github/workflows/ethdebug.yml

@@ -0,0 +1,166 @@
+name: ETHDebug
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/ethdebug.yml"
+      - "package.json"
+      - "yarn.lock"
+      - "tsconfig*.json"
+      - "schemas/**"
+      - "packages/format/**"
+      - "packages/conformance/**"
+  workflow_dispatch:
+    inputs:
+      solidity_ref:
+        description: Solidity ref to build for solc
+        default: develop
+        required: true
+      soldb_ref:
+        description: SolDB ref to build
+        default: main
+        required: true
+
+concurrency:
+  group: ethdebug-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FOUNDRY_VERSION: v1.0.0
+  SOLIDITY_REF: ${{ github.event.inputs.solidity_ref || 'develop' }}
+  SOLDB_REF: ${{ github.event.inputs.soldb_ref || 'main' }}
+
+jobs:
+  conformance:
+    name: solc + soldb conformance
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout ethdebug/format
+        uses: actions/checkout@v4
+        with:
+          path: format
+
+      - name: Checkout SolDB
+        uses: actions/checkout@v4
+        with:
+          repository: walnuthq/soldb
+          ref: ${{ env.SOLDB_REF }}
+          path: soldb
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+          cache-dependency-path: format/yarn.lock
+
+      - name: Install format dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: format
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Fetch prebuilt solc with ETHDebug support
+        id: fetch-solc
+        continue-on-error: true
+        env:
+          CIRCLECI_TOKEN: ${{ secrets.CIRCLECI_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          python -m pip install git+https://github.com/argotorg/solc-bench.git
+          solc-bench fetch "${SOLIDITY_REF}" \
+            --output "${GITHUB_WORKSPACE}/solidity/build/solc/solc" \
+            --force
+
+      - name: Install Rust toolchain
+        run: |
+          rustup toolchain install stable --profile minimal
+          rustup default stable
+
+      - name: Cache Cargo build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/git
+            ~/.cargo/registry
+            soldb/target
+          key: ${{ runner.os }}-soldb-cargo-${{ hashFiles('soldb/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-soldb-cargo-
+
+      - name: Build SolDB
+        run: cargo build --bin soldb
+        working-directory: soldb
+
+      - name: Checkout Solidity
+        if: steps.fetch-solc.outcome != 'success'
+        uses: actions/checkout@v4
+        with:
+          repository: argotorg/solidity
+          ref: ${{ env.SOLIDITY_REF }}
+          path: solidity
+          submodules: recursive
+
+      - name: Install Solidity build dependencies
+        if: steps.fetch-solc.outcome != 'success'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            ccache \
+            cmake \
+            libboost-filesystem-dev \
+            libboost-program-options-dev \
+            libboost-system-dev \
+            libboost-test-dev \
+            libcln-dev \
+            ninja-build
+
+      - name: Cache Solidity ccache
+        if: steps.fetch-solc.outcome != 'success'
+        uses: actions/cache@v4
+        with:
+          path: ~/.ccache
+          key: ${{ runner.os }}-solidity-ccache-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-solidity-ccache-
+
+      - name: Build solc with ETHDebug support
+        if: steps.fetch-solc.outcome != 'success'
+        run: |
+          cmake \
+            -S solidity \
+            -B solidity/build \
+            -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DTESTS=OFF \
+            -DTOOLS=OFF \
+            -DPEDANTIC=OFF \
+            -DCMAKE_C_COMPILER_LAUNCHER=ccache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+          cmake --build solidity/build --target solc --parallel 2
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: ${{ env.FOUNDRY_VERSION }}
+
+      - name: Show external tool versions
+        run: |
+          solidity/build/solc/solc --version
+          soldb/target/debug/soldb --version
+          anvil --version
+          cast --version
+
+      - name: Run ETHDebug conformance tests
+        env:
+          ETHDEBUG_CONFORMANCE_SOLC: ${{ github.workspace }}/solidity/build/solc/solc
+          ETHDEBUG_CONFORMANCE_SOLDB: ${{ github.workspace }}/soldb/target/debug/soldb
+          ETHDEBUG_CONFORMANCE_ANVIL: anvil
+          ETHDEBUG_CONFORMANCE_CAST: cast
+        run: yarn --cwd packages/conformance test:external
+        working-directory: format

.prettierignore

@@ -9,6 +9,9 @@ package-lock.json
 # Auto-generated files
 packages/format/src/schemas/yamls.ts
 
+# Solidity fixtures are compiler inputs; this repo has no Solidity Prettier parser.
+packages/conformance/test/fixtures/solc/**/*.sol
+
 # Docusaurus build output
 packages/web/.docusaurus/
 packages/web/build/

package.json

@@ -5,7 +5,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "yarn --cwd packages/format prepare:yamls && tsc --build packages/format packages/pointers packages/evm packages/bugc packages/programs-react packages/pointers-react",
+    "build": "yarn --cwd packages/format prepare:yamls && tsc --build packages/format packages/pointers packages/evm packages/bugc packages/conformance packages/programs-react packages/pointers-react",
     "bundle": "tsx ./bin/bundle-schema.ts",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",

packages/conformance/README.md

@@ -0,0 +1,51 @@
+# @ethdebug/conformance
+
+Reusable ETHDebug conformance infrastructure.
+
+This package is intentionally language- and consumer-neutral. Compiler adapters
+produce ETHDebug artifacts; consumer adapters exercise debugger implementations
+against those artifacts.
+
+Current adapters:
+
+- `bugc`: in-process BUG compiler adapter.
+- `solc`: external `solc --standard-json` adapter.
+- `soldb`: external SolDB CLI adapter.
+
+The first layer checks the contract that every compiler should satisfy:
+
+- emitted programs are valid `ethdebug/format/program` objects,
+- resources and compilations are valid when present,
+- source references used by programs resolve to compilation sources.
+
+Static validation uses both the package's TypeScript type guards and the
+published JSON-Schemas. The schemas are normative; the type guards remain as an
+extra compatibility signal for TypeScript consumers. Negative fixtures are kept
+alongside positive fixtures to prove the validator rejects malformed artifacts.
+
+The second layer checks real debugger consumers: tests can run a debugger,
+parse its output, and assert resources, source steps, frames, or values. SolDB
+is the first consumer backend, but the runner is not tied to SolDB. The SolDB
+adapter can materialize compiler output as a SolDB-compatible debug directory
+and then drive `soldb info resources` over it. The optional Foundry adapter
+starts a local `anvil --steps-tracing` node, deploys a compiled contract with
+`cast`, sends a transaction, and scripts SolDB's interactive REPL to assert
+source-line breakpoint set/hit behavior.
+
+Consumer adapters are black-box by default so the same harness can test CLIs,
+libraries, or services. The current SolDB adapter shells out to the CLI because
+that is the stable public integration point; a future SolDB library adapter can
+be added without changing the compiler conformance layer.
+
+External adapters are opt-in in tests:
+
+```console
+ETHDEBUG_CONFORMANCE_SOLC=/path/to/solc yarn test
+ETHDEBUG_CONFORMANCE_SOLDB=/path/to/soldb yarn test
+ETHDEBUG_CONFORMANCE_ANVIL=/path/to/anvil ETHDEBUG_CONFORMANCE_CAST=/path/to/cast yarn test
+```
+
+To run the full Solidity -> SolDB resources path, set `ETHDEBUG_CONFORMANCE_SOLC`
+and `ETHDEBUG_CONFORMANCE_SOLDB`. If `anvil` and `cast` are on `PATH`, the
+SolDB breakpoint test runs as well; the executable paths can be overridden with
+`ETHDEBUG_CONFORMANCE_ANVIL` and `ETHDEBUG_CONFORMANCE_CAST`.

packages/conformance/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ethdebug/conformance",
+  "version": "0.1.0-0",
+  "description": "Reusable ETHDebug conformance runner and adapters",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "imports": {
+    "#adapters/anvil": {
+      "types": "./src/adapters/anvil.ts",
+      "default": "./dist/src/adapters/anvil.js"
+    },
+    "#adapters/bugc": {
+      "types": "./src/adapters/bugc.ts",
+      "default": "./dist/src/adapters/bugc.js"
+    },
+    "#adapters/soldb": {
+      "types": "./src/adapters/soldb.ts",
+      "default": "./dist/src/adapters/soldb.js"
+    },
+    "#adapters/solc": {
+      "types": "./src/adapters/solc.ts",
+      "default": "./dist/src/adapters/solc.js"
+    },
+    "#runner": {
+      "types": "./src/runner.ts",
+      "default": "./dist/src/runner.js"
+    },
+    "#types": {
+      "types": "./src/types.ts",
+      "default": "./dist/src/types.js"
+    }
+  },
+  "scripts": {
+    "prepare": "tsc",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:external": "vitest run --no-file-parallelism --maxWorkers=1"
+  },
+  "dependencies": {
+    "@ethdebug/bugc": "^0.1.0-0",
+    "@ethdebug/format": "^0.1.0-0",
+    "@hyperjump/json-schema": "^1.17.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}