feat: external opcode metadata for archive sources (#180)

## Summary
- Adds `opcodes` and `opcodes_file` fields to the archive source config,
allowing opcode count data to be provided via an external JSON file when
not using EEST fixtures
- Opcode data is written to `opcode_count` at the top level of each test
in `summary.json`, and the UI opcode heatmap/test detail views now read
from this unified field (with fallback to `eest.info.opcode_count` for
backward compatibility)
- Adds archive source documentation to `docs/configuration.md` and
`config.example.yaml` which were previously missing

## Config example
```yaml
source:
  archive:
    file: https://github.com/.../artifacts/6222084759
    opcodes: "opcodes_tracing.json"
    # Optional: separate archive for the opcodes file
    opcodes_file: https://github.com/.../artifacts/6222074312
    steps:
      test:
        - "perf-devnet-3/testing/*.txt"
```

## Test plan
- [x] `go build ./pkg/executor/... ./pkg/config/...` compiles
- [x] `go test ./pkg/executor/... ./pkg/config/...` passes
- [x] `golangci-lint run` passes on changed packages
- [x] TypeScript type-checks with `npx tsc --noEmit`
- [x] Manual: run with archive source + opcodes config, verify
`summary.json` contains `opcode_count` per test
- [x] Manual: verify UI opcode heatmap renders for non-EEST suite

Author: skylenet

config.example.yaml

@@ -129,7 +129,27 @@ runner:
     #     #     cleanup:
     #     #       - "tests/cleanup/*.txt"
     #
-    #     # Option 3: EEST (Ethereum Execution Spec Tests) fixtures from GitHub releases.
+    #     # Option 3: Archive source (ZIP or tar.gz, local or remote URL).
+    #     # Downloads (if URL), extracts, and discovers tests from the archive contents.
+    #     # GitHub Actions artifact URLs are auto-converted to API download endpoints.
+    #     # archive:
+    #     #   file: https://github.com/NethermindEth/gas-benchmarks/actions/runs/23847558369/artifacts/6222084759
+    #     #   pre_run_steps:
+    #     #     - "perf-devnet-3/gas-bump.txt"
+    #     #     - "perf-devnet-3/funding.txt"
+    #     #   steps:
+    #     #     setup:
+    #     #       - "perf-devnet-3/setup/*.txt"
+    #     #     test:
+    #     #       - "perf-devnet-3/testing/*.txt"
+    #     #   # Optional: External opcode metadata file within the archive.
+    #     #   # JSON mapping test names to opcode counts: {"test_name": {"OPCODE": count}}
+    #     #   # opcodes: "opcodes_tracing.json"
+    #     #   # Optional: Separate archive containing the opcodes file.
+    #     #   # If not set, the opcodes file is searched in the main archive.
+    #     #   # opcodes_file: https://github.com/.../artifacts/6222074312
+    #
+    #     # Option 4: EEST (Ethereum Execution Spec Tests) fixtures from GitHub releases.
     #     # Downloads fixtures directly from ethereum/execution-spec-tests releases.
     #     # Genesis files are auto-resolved per client type from the release.
     #     # eest_fixtures:
@@ -141,7 +161,7 @@ runner:
     #     #   # fixtures_url: https://example.com/fixtures_benchmark.tar.gz
     #     #   # genesis_url: https://example.com/benchmark_genesis.tar.gz
     #
-    #     # Option 3b: EEST fixtures from GitHub Actions artifacts.
+    #     # Option 4b: EEST fixtures from GitHub Actions artifacts.
     #     # Alternative to releases - downloads from workflow run artifacts.
     #     # Uses the gh CLI if available, otherwise falls back to the GitHub REST API
     #     # (requires runner.github_token or BENCHMARKOOR_RUNNER_GITHUB_TOKEN).
@@ -154,7 +174,7 @@ runner:
     #     #   # genesis_artifact_run_id: "12345678901"
     #     #   # fixtures_subdir also works with artifacts
     #
-    #     # Option 3c: EEST fixtures from local directories.
+    #     # Option 4c: EEST fixtures from local directories.
     #     # Points directly at already-extracted fixtures and genesis directories.
     #     # No downloading or caching — useful for local development with locally-built EEST fixtures.
     #     # eest_fixtures:
@@ -163,7 +183,7 @@ runner:
     #     #   # fixtures_subdir also works with local directories
     #     #   # fixtures_subdir: fixtures/blockchain_tests_engine_x  # default
     #
-    #     # Option 3d: EEST fixtures from local .tar.gz tarballs.
+    #     # Option 4d: EEST fixtures from local .tar.gz tarballs.
     #     # Extracts tarballs to a cache directory (keyed by content hash, re-extraction skipped
     #     # if already cached). Useful when you have locally-built tarballs but haven't extracted them.
     #     # eest_fixtures:

docs/configuration.md

@@ -243,7 +243,7 @@ runner:
 
 #### Test Sources
 
-Tests can be loaded from a local directory, a git repository, or EEST (Ethereum Execution Spec Tests) fixtures. Only one source type can be configured.
+Tests can be loaded from a local directory, a git repository, an archive file, or EEST (Ethereum Execution Spec Tests) fixtures. Only one source type can be configured.
 
 ##### Local Source
 
@@ -299,6 +299,46 @@ tests:
 | `steps.test` | []string | No | Glob patterns for test phase files |
 | `steps.cleanup` | []string | No | Glob patterns for cleanup phase files |
 
+##### Archive Source
+
+Tests can be loaded from a ZIP or tar.gz archive file, either from a local path or a URL (including GitHub Actions artifacts).
+
+```yaml
+tests:
+  source:
+    archive:
+      file: https://github.com/NethermindEth/gas-benchmarks/actions/runs/23847558369/artifacts/6222084759
+      pre_run_steps:
+        - "perf-devnet-3/gas-bump.txt"
+        - "perf-devnet-3/funding.txt"
+      steps:
+        setup:
+          - "perf-devnet-3/setup/*.txt"
+        test:
+          - "perf-devnet-3/testing/*.txt"
+      # Optional: External opcode metadata for the test suite.
+      # When provided, opcode counts are included in the suite summary.json
+      # and displayed in the UI opcode heatmap.
+      opcodes: "opcodes_tracing.json"
+      # Optional: Separate archive containing the opcodes file.
+      # If not set, the opcodes file is searched in the main archive.
+      # opcodes_file: https://github.com/NethermindEth/gas-benchmarks/actions/runs/23847558369/artifacts/6222074312
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `file` | string | Yes | Local path or URL to a ZIP or tar.gz archive. GitHub Actions artifact URLs are auto-converted to API endpoints |
+| `pre_run_steps` | []string | No | Glob patterns for steps executed once before all tests |
+| `steps.setup` | []string | No | Glob patterns for setup phase files |
+| `steps.test` | []string | No | Glob patterns for test phase files |
+| `steps.cleanup` | []string | No | Glob patterns for cleanup phase files |
+| `opcodes` | string | No | Filename within the archive containing opcode count metadata (e.g., `opcodes_tracing.json`). The file must be a JSON object mapping test names to opcode counts: `{"test_name": {"OPCODE": count, ...}}` |
+| `opcodes_file` | string | No | Separate archive URL/path containing the opcodes file. If not set, the opcodes file is searched in the main `file` archive |
+
+**GitHub Actions artifacts:** Browser URLs like `https://github.com/{owner}/{repo}/actions/runs/{run_id}/artifacts/{artifact_id}` are automatically converted to the GitHub API download endpoint. A GitHub token is required for artifact downloads (set via `runner.github_token` or `BENCHMARKOOR_RUNNER_GITHUB_TOKEN`).
+
+**Archive extraction:** ZIP archives are extracted and any inner tarballs (common in GitHub Actions artifacts) are automatically extracted as well.
+
 ##### EEST Fixtures Source
 
 EEST (Ethereum Execution Spec Tests) fixtures can be loaded from GitHub releases or GitHub Actions artifacts. This source type downloads fixtures from `ethereum/execution-spec-tests` and converts them to Engine API calls automatically.

pkg/config/config.go

@@ -335,6 +335,8 @@ type LocalSourceV2 struct {
 // The file can be a local path or a URL (HTTP/HTTPS) to a ZIP or tar.gz archive.
 type ArchiveSourceConfig struct {
 	File        string       `yaml:"file" mapstructure:"file"`
+	OpcodesFile string       `yaml:"opcodes_file,omitempty" mapstructure:"opcodes_file"`
+	Opcodes     string       `yaml:"opcodes,omitempty" mapstructure:"opcodes"`
 	PreRunSteps []string     `yaml:"pre_run_steps,omitempty" mapstructure:"pre_run_steps"`
 	Steps       *StepsConfig `yaml:"steps,omitempty" mapstructure:"steps"`
 }