feat(pr-quality-gate): bundle Portal coverage tooling with the skill

Makes PR #7 self-contained: the coverage-guard step now ships with its tooling.
- portal/vite.portal.config.ts: v8 coverage block scoped to the Portal source
  (inert unless --coverage; also converts the file to single quotes per Biome)
- scripts/sync-upstream.sh: --coverage mode (installs the matching v8 provider,
  emits portal-coverage/coverage-summary.json)
- scripts/coverage-diff.mjs: renders a base-vs-head Portal coverage table for a
  PR body (head-only fallback when base predates the tooling)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mo4islona

portal/vite.portal.config.ts

@@ -1,19 +1,34 @@
-import path from "node:path";
-import { defineConfig } from "vitest/config";
+import path from 'node:path';
+import { defineConfig } from 'vitest/config';
 // run the Portal-layer unit tests in isolation (no Foundry globalSetup): copied next to
 // packages/core/ by scripts/sync-upstream.sh, where ./src points at the patched core.
 export default defineConfig({
   resolve: {
     alias: {
-      "@": path.resolve(__dirname, "./src"),
-      "@ponder/utils": path.resolve(__dirname, "../utils/src"),
+      '@': path.resolve(__dirname, './src'),
+      '@ponder/utils': path.resolve(__dirname, '../utils/src'),
     },
   },
   test: {
     include: [
-      "src/sync-historical/portal*.test.ts",
-      "src/sync-historical/realtime*.test.ts",
+      'src/sync-historical/portal*.test.ts',
+      'src/sync-historical/realtime*.test.ts',
     ],
     testTimeout: 15000,
+    // Coverage is scoped to the Portal layer (the whole diff vs upstream ponder). Inert on a plain
+    // `--test` run: it only activates under `--coverage` (see scripts/sync-upstream.sh --coverage),
+    // so the normal path needs no coverage provider installed.
+    coverage: {
+      provider: 'v8',
+      reporter: ['json-summary', 'text-summary'],
+      reportsDirectory: 'portal-coverage',
+      include: [
+        'src/sync-historical/portal.ts',
+        'src/sync-historical/portal-transform.ts',
+        'src/sync-historical/portal-realtime.ts',
+        'src/sync-historical/portal-realtime-wire.ts',
+        'src/sync-historical/realtime.ts',
+      ],
+    },
   },
 });

scripts/coverage-diff.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Render a Portal-layer coverage diff as a markdown table for a PR body.
+//
+//   node scripts/coverage-diff.mjs <head-summary.json>                     # absolute table
+//   node scripts/coverage-diff.mjs <base-summary.json> <head-summary.json> # diff vs base
+//
+// Inputs are vitest v8 `coverage-summary.json` files (produced by
+// `scripts/sync-upstream.sh <ver> --coverage`, at <core>/portal-coverage/coverage-summary.json).
+// Per-file keys are absolute paths inside the grafted tree; we key rows by basename so base and
+// head line up regardless of the temp workdir. With one argument (e.g. the base branch doesn't have
+// the coverage tooling yet) it prints head absolutes with no deltas.
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.length > 2) {
+  console.error(
+    'usage: node scripts/coverage-diff.mjs [<base-summary.json>] <head-summary.json>',
+  );
+  process.exit(2);
+}
+
+const load = (p) => JSON.parse(readFileSync(p, 'utf8'));
+const headArg = args[args.length - 1];
+const baseArg = args.length === 2 ? args[0] : null;
+const head = load(headArg);
+const base = baseArg ? load(baseArg) : { total: null };
+
+const pct = (entry, metric) => entry?.[metric]?.pct ?? null;
+const fmtPct = (v) => (v === null ? '—' : `${v.toFixed(1)}%`);
+const fmtDelta = (b, h) => {
+  if (b === null || h === null) {
+    return '';
+  }
+
+  const d = h - b;
+
+  if (Math.abs(d) < 0.1) {
+    return '±0';
+  }
+
+  return `${d > 0 ? '+' : ''}${d.toFixed(1)}`;
+};
+
+// Row keys: 'All files' for total, basename for each file (union of base + head).
+const fileKeys = new Map(); // basename -> { base, head }
+
+const collect = (summary, side) => {
+  for (const [k, entry] of Object.entries(summary)) {
+    if (k === 'total') {
+      continue;
+    }
+
+    const name = k.split('/').pop();
+    const row = fileKeys.get(name) ?? {};
+    row[side] = entry;
+    fileKeys.set(name, row);
+  }
+};
+
+collect(base, 'base');
+collect(head, 'head');
+
+const rows = [];
+rows.push({
+  label: '**All files**',
+  base: base.total,
+  head: head.total,
+  changed: true,
+});
+
+for (const [name, { base: b, head: h }] of [...fileKeys].sort()) {
+  const sB = pct(b, 'statements');
+  const sH = pct(h, 'statements');
+  const changed =
+    sB === null || sH === null || Math.abs((sH ?? 0) - (sB ?? 0)) >= 0.1;
+  rows.push({ label: name, base: b, head: h, changed });
+}
+
+const lines = [];
+lines.push('## Coverage (Portal layer)');
+lines.push('');
+lines.push('| File | Stmts | Δ | Branch | Δ | Funcs | Δ |');
+lines.push('|------|-------|---|--------|---|-------|---|');
+
+for (const r of rows) {
+  if (!r.changed) {
+    continue;
+  }
+
+  const sB = pct(r.base, 'statements');
+  const sH = pct(r.head, 'statements');
+  const bB = pct(r.base, 'branches');
+  const bH = pct(r.head, 'branches');
+  const fB = pct(r.base, 'functions');
+  const fH = pct(r.head, 'functions');
+  lines.push(
+    `| ${r.label} | ${fmtPct(sH)} | ${fmtDelta(sB, sH)} | ${fmtPct(bH)} | ${fmtDelta(bB, bH)} | ${fmtPct(fH)} | ${fmtDelta(fB, fH)} |`,
+  );
+}
+
+if (base.total) {
+  const totalDelta = head.total.statements.pct - base.total.statements.pct;
+
+  if (totalDelta < -0.1) {
+    lines.push('');
+    lines.push('⚠️ Overall statement coverage decreased.');
+  }
+}
+
+console.log(lines.join('\n'));

scripts/sync-upstream.sh

@@ -55,5 +55,19 @@ if [ "${2:-}" = "--test" ]; then
   ( cd "$CORE" && pnpm exec vitest run --config vite.portal.config.ts )
 fi
 
+# --coverage: run the same suite with v8 coverage scoped to the Portal source (see the `coverage`
+# block in vite.portal.config.ts). The provider must match the tree's vitest version; the renamed
+# core breaks a workspace-wide `pnpm add` (benchmark still deps ponder@workspace:*), so install it
+# standalone with --ignore-workspace. Writes portal-coverage/coverage-summary.json under $CORE.
+if [ "${2:-}" = "--coverage" ]; then
+  VITEST_VER="$(node -e "const p=require('$CORE/package.json');console.log((p.devDependencies&&p.devDependencies.vitest)||(p.dependencies&&p.dependencies.vitest))")"
+  echo "▶ installing @vitest/coverage-v8@$VITEST_VER (matching vitest)"
+  ( cd "$CORE" && $PNPM add -D "@vitest/coverage-v8@$VITEST_VER" --ignore-workspace )
+
+  echo "▶ running Portal-layer tests with coverage"
+  ( cd "$CORE" && pnpm exec vitest run --config vite.portal.config.ts --coverage )
+  echo "✓ coverage summary → $CORE/portal-coverage/coverage-summary.json"
+fi
+
 echo "✓ built @subsquid/ponder@$VER-sqd.$REV → $CORE"
 echo "  publish: cd $CORE && npm publish --access public --tag latest   # --tag latest: make this prerelease the default install"