feat: support archive input for opcode_source (#204)

## Summary
Adds an optional \`archive\` field to \`tests.source.opcode_source\`
alongside the existing \`file\`. When set, benchmarkoor downloads the
archive (local path, HTTP(S) URL, or GitHub Actions artifact URL),
extracts it, and looks up the configured \`file\` inside the extracted
tree by basename.

Supported archive formats:
- \`.zip\`
- \`.tar.gz\`
- GitHub Actions artifact zips containing an inner \`.tar.gz\`
(auto-unpacked)

Example config:
\`\`\`yaml
runner:
  benchmark:
    tests:
      opcode_source:
archive:
https://github.com/NethermindEth/gas-benchmarks/actions/runs/24460911828/artifacts/6456466898
        file: opcodes_tracing.json
\`\`\`

### Reuse
- The archive download goes through the existing \`fetchCached\`
pipeline, inheriting ETag / Last-Modified revalidation, the GitHub
artifact URL rewrite with bearer-token auth (\`runner.github_token\`),
and the per-URL on-disk cache.
- The extracted directory is cached separately (keyed on
\`sha256(archivePath)[:16]\`) and refreshed only when \`fetchCached\`
reports the archive was re-downloaded.
- Reuses \`detectArchiveFormat\`, \`extractZipFile\`,
\`extractTarGzFile\`, \`extractInnerTarballs\`.

### Docs
- \`docs/configuration.md\` — new subsections and options table updated
with the archive mode.
- \`config.example.yaml\` — commented archive-mode example.

## Test plan
- [x] \`go vet\` + \`go test ./pkg/executor/ ./pkg/config/\` pass
- [x] Manual: configure \`opcode_source.archive\` with the GitHub
Actions artifact URL from the example, verify the opcode JSON is
extracted and opcodes appear on the heatmap
- [x] Manual: configure \`opcode_source.archive\` with a local
\`.tar.gz\`, verify the same
- [x] Manual: existing \`opcode_source.file\` (direct JSON URL) still
works unchanged

Author: skylenet

config.example.yaml

@@ -205,9 +205,16 @@ runner:
     #
     #   # Optional: External opcode metadata for the test suite.
     #   # A JSON file mapping test names to opcode counts: {"test_name": {"OPCODE": count, ...}}
-    #   # Can be a local path or a URL (including GitHub Actions artifact URLs).
+    #   # Two modes:
+    #   #   1. Direct JSON file (local path or URL):
     #   # opcode_source:
     #   #   file: opcodes_tracing.json
+    #   #
+    #   #   2. Archive (.zip / .tar.gz / GitHub Actions artifact) containing the JSON file.
+    #   #      `file` is the filename to look up inside the extracted archive.
+    #   # opcode_source:
+    #   #   archive: https://github.com/NethermindEth/gas-benchmarks/actions/runs/24460911828/artifacts/6456466898
+    #   #   file: opcodes_tracing.json
 
 # Optional: API server for authentication and user management.
 # When configured, the UI can integrate with the API for login, admin, and role-based access.

docs/configuration.md

@@ -377,7 +377,9 @@ tests:
 
 ##### Opcode Source
 
-Optional external opcode metadata can be configured alongside the test source:
+Optional external opcode metadata can be configured alongside the test source. Two modes are supported.
+
+**Direct JSON file** — `file` is a local path or URL to the JSON file:
 
 ```yaml
 runner:
@@ -387,13 +389,27 @@ runner:
         file: opcodes_tracing.json  # Local path or URL to a JSON file
 ```
 
+**Archive mode** — `archive` is a `.zip` / `.tar.gz` (or a GitHub Actions artifact URL) that contains the JSON file; `file` is the filename to look up inside the extracted archive:
+
+```yaml
+runner:
+  benchmark:
+    tests:
+      opcode_source:
+        archive: https://github.com/NethermindEth/gas-benchmarks/actions/runs/24460911828/artifacts/6456466898
+        file: opcodes_tracing.json  # Filename inside the archive
+```
+
+`archive` can also be a plain URL to a `.zip` / `.tar.gz`, or a local path to one. When `archive` is set, `file` is interpreted as a filename inside the extracted tree (matched by basename, so nested folders are walked automatically).
+
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `file` | string | Yes | Local path or URL to a JSON file mapping test names to opcode counts: `{"test_name": {"OPCODE": count, ...}}` |
+| `file` | string | Yes | When `archive` is unset: local path or URL to the JSON file. When `archive` is set: filename to look up inside the extracted archive |
+| `archive` | string | No | Optional local path or URL to a `.zip` / `.tar.gz` / GitHub Actions artifact containing the opcode JSON file. When set, `file` names the entry inside the 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.
+**Archive extraction:** ZIP archives are extracted and any inner tarballs (common in GitHub Actions artifacts) are automatically extracted as well. Both direct-file and archive downloads are cache-validated on each run via HTTP `ETag` / `Last-Modified` — the archive (and its extraction) is refreshed automatically when the origin changes.
 
 ##### EEST Fixtures Source
 

pkg/config/config.go

@@ -412,8 +412,15 @@ type ArchiveSourceConfig struct {
 
 // OpcodeSourceConfig defines an external opcode metadata file.
 // The file is a JSON map of test name → opcode → count.
+//
+// Two modes are supported:
+//   - Direct file: set File to a local path or URL pointing at the JSON file.
+//   - Archive: set Archive to a .zip / .tar.gz (or GitHub Actions artifact URL).
+//     The archive is downloaded + extracted, and File is then the filename
+//     to look up inside the extracted tree.
 type OpcodeSourceConfig struct {
-	File string `yaml:"file" mapstructure:"file"` // Local path or URL to a JSON file.
+	File    string `yaml:"file" mapstructure:"file"`                 // JSON file path — inside the archive when Archive is set, otherwise a local path or URL.
+	Archive string `yaml:"archive,omitempty" mapstructure:"archive"` // Optional local path or URL to a .zip / .tar.gz archive containing File.
 }
 
 // StepsConfig defines glob patterns for each step type.

pkg/executor/opcode.go

@@ -2,6 +2,8 @@ package executor
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"os"
@@ -11,12 +13,28 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
-// loadOpcodes resolves the opcode source file (local path or URL),
-// reads the JSON map, and attaches opcode counts to prepared tests.
+// loadOpcodes resolves the opcode source file (local path, URL, or a file
+// inside an archive), reads the JSON map, and attaches opcode counts to
+// prepared tests.
 func (e *executor) loadOpcodes(ctx context.Context) error {
 	file := e.cfg.OpcodeSource.File
+	archive := e.cfg.OpcodeSource.Archive
+
+	var (
+		resolved string
+		err      error
+	)
+
+	if archive != "" {
+		if file == "" {
+			return fmt.Errorf("opcode_source.file (filename inside the archive) is required when opcode_source.archive is set")
+		}
+
+		resolved, err = resolveOpcodeFromArchive(ctx, archive, file, e.cfg.CacheDir, e.cfg.GitHubToken, e.log)
+	} else {
+		resolved, err = resolveFile(ctx, file, e.cfg.CacheDir, e.cfg.GitHubToken, e.log)
+	}
 
-	resolved, err := resolveFile(ctx, file, e.cfg.CacheDir, e.cfg.GitHubToken, e.log)
 	if err != nil {
 		return fmt.Errorf("resolving opcode file: %w", err)
 	}
@@ -61,12 +79,17 @@ func (e *executor) loadOpcodes(ctx context.Context) error {
 		}
 	}
 
-	e.log.WithFields(logrus.Fields{
+	logFields := logrus.Fields{
 		"file":          file,
 		"total_entries": filtered,
 		"matched_tests": matched,
 		"total_tests":   len(e.prepared.Tests),
-	}).Info("Loaded external opcode data")
+	}
+	if archive != "" {
+		logFields["archive"] = archive
+	}
+
+	e.log.WithFields(logFields).Info("Loaded external opcode data")
 
 	if unmatched := filtered - matched; unmatched > 0 {
 		e.log.WithField("unmatched", unmatched).Warn(
@@ -120,3 +143,178 @@ func resolveFile(ctx context.Context, file, cacheDir, githubToken string, log lo
 
 	return file, nil
 }
+
+// resolveOpcodeFromArchive downloads (with cache validation) an archive
+// containing the opcode JSON file and returns the path to the extracted
+// file within it. Supports local paths, HTTP(S) URLs, and GitHub Actions
+// artifact browser URLs.
+func resolveOpcodeFromArchive(
+	ctx context.Context,
+	archive, file, cacheDir, githubToken string,
+	log logrus.FieldLogger,
+) (string, error) {
+	// Step 1 — get a local path to the archive.
+	archivePath, changed, err := resolveArchiveRef(ctx, archive, cacheDir, githubToken, log)
+	if err != nil {
+		return "", fmt.Errorf("resolving opcode archive: %w", err)
+	}
+
+	// Step 2 — extract into a stable, per-archive cache dir. Re-extract
+	// whenever the underlying archive was (re-)downloaded.
+	extractDir, err := extractOpcodeArchive(archivePath, cacheDir, changed, log)
+	if err != nil {
+		return "", fmt.Errorf("extracting opcode archive: %w", err)
+	}
+
+	// Step 3 — find the requested file by basename under the extraction
+	// root, then fall back to an exact relative path if that didn't match.
+	found, err := findFileInDir(extractDir, file)
+	if err != nil {
+		return "", fmt.Errorf("opcode file %q not found in archive: %w", file, err)
+	}
+
+	return found, nil
+}
+
+// resolveArchiveRef resolves an archive reference (local path or URL) to a
+// local file path. The `changed` return value is true when the call caused
+// a fresh download.
+func resolveArchiveRef(
+	ctx context.Context,
+	ref, cacheDir, githubToken string,
+	log logrus.FieldLogger,
+) (string, bool, error) {
+	if strings.HasPrefix(ref, "http://") || strings.HasPrefix(ref, "https://") {
+		downloadURL := ref
+
+		var token string
+
+		if ghArtifactURLPattern.MatchString(ref) && githubToken != "" {
+			m := ghArtifactURLPattern.FindStringSubmatch(ref)
+			downloadURL = fmt.Sprintf(
+				"https://api.github.com/repos/%s/actions/artifacts/%s/zip",
+				m[1], m[2],
+			)
+			token = githubToken
+		}
+
+		res, err := fetchCached(ctx, log, ref, downloadURL, token, cacheDir, "opcode-archive")
+		if err != nil {
+			return "", false, err
+		}
+
+		return res.Path, res.Changed, nil
+	}
+
+	// Local file path.
+	if !filepath.IsAbs(ref) {
+		absPath, err := filepath.Abs(ref)
+		if err != nil {
+			return "", false, fmt.Errorf("resolving path %q: %w", ref, err)
+		}
+
+		ref = absPath
+	}
+
+	if _, err := os.Stat(ref); os.IsNotExist(err) {
+		return "", false, fmt.Errorf("archive %q does not exist", ref)
+	}
+
+	return ref, false, nil
+}
+
+// extractOpcodeArchive extracts archivePath into a stable cache directory
+// keyed by sha256(archivePath). The extraction is reused on subsequent
+// runs unless `forceRefresh` is true (set when fetchCached reported the
+// archive was re-downloaded). GitHub Actions artifact zips that contain
+// an inner tarball are auto-extracted as well.
+func extractOpcodeArchive(archivePath, cacheDir string, forceRefresh bool, log logrus.FieldLogger) (string, error) {
+	if cacheDir == "" {
+		cacheDir = os.TempDir()
+	}
+
+	hash := sha256.Sum256([]byte(archivePath))
+	extractDir := filepath.Join(cacheDir, "opcode-archive-extract-"+hex.EncodeToString(hash[:8]))
+
+	if forceRefresh {
+		_ = os.RemoveAll(extractDir)
+	}
+
+	if _, err := os.Stat(extractDir); err == nil {
+		log.WithField("path", extractDir).Info("Using cached opcode archive extraction")
+		return extractDir, nil
+	}
+
+	if err := os.MkdirAll(extractDir, 0755); err != nil {
+		return "", fmt.Errorf("creating extraction directory: %w", err)
+	}
+
+	format, err := detectArchiveFormat(archivePath)
+	if err != nil {
+		return "", err
+	}
+
+	switch format {
+	case archiveFormatZip:
+		if err := extractZipFile(archivePath, extractDir); err != nil {
+			return "", fmt.Errorf("extracting zip: %w", err)
+		}
+		// GitHub Actions artifacts are zips containing an inner tar.gz;
+		// unpack those too so findFileInDir can see the actual JSON.
+		if err := extractInnerTarballs(extractDir, log); err != nil {
+			return "", fmt.Errorf("extracting inner tarballs: %w", err)
+		}
+	case archiveFormatTarGz:
+		if err := extractTarGzFile(archivePath, extractDir); err != nil {
+			return "", fmt.Errorf("extracting tar.gz: %w", err)
+		}
+	default:
+		return "", fmt.Errorf("unsupported archive format: %s", format)
+	}
+
+	log.WithField("path", extractDir).Info("Extracted opcode archive")
+
+	return extractDir, nil
+}
+
+// findFileInDir walks dir recursively and returns the absolute path of the
+// first file whose basename matches name. If name contains a path
+// separator, it is treated as a relative path from dir and matched exactly.
+func findFileInDir(dir, name string) (string, error) {
+	// Exact relative match first.
+	if strings.ContainsAny(name, "/\\") {
+		candidate := filepath.Join(dir, name)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate, nil
+		}
+	}
+
+	var found string
+
+	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+
+		if info.IsDir() {
+			return nil
+		}
+
+		if filepath.Base(path) == filepath.Base(name) {
+			found = path
+
+			return filepath.SkipAll
+		}
+
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+
+	if found == "" {
+		return "", fmt.Errorf("%q not found under %q", name, dir)
+	}
+
+	return found, nil
+}