automategraph 1.5.1 → 1.5.3

package/tests/report.ts

@@ -0,0 +1,452 @@
+/* ============================================================
+ * Static web report generator — writes:
+ *   report/index.html   (self-contained dashboard, no network deps)
+ *   report/report.json  (machine-readable full results)
+ *
+ * v1.1: fully kind-driven. Adding a new test pack (see TEST_KINDS
+ * in harness.ts) requires no changes here.
+ * ============================================================ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+import { KindTotals, RunSummary, TestKind, TestResultRecord } from "./harness";
+
+const KIND_META: Record<TestKind, { badge: string; blurb: string; color: string }> = {
+  unit: {
+    badge: "UNIT",
+    blurb: "constructor validation, error model, event bus, storage, freezing, lifecycle, scheduler, retry, cancellation",
+    color: "#7c9cff"
+  },
+  integration: {
+    badge: "COMPLEX",
+    blurb: "end-to-end pipelines, failure semantics, concurrency & scale, listeners, plugin lifecycle, cancellation",
+    color: "#c084fc"
+  },
+  async: {
+    badge: "ASYNC",
+    blurb: "async node callbacks across every path: success, retry, ONTHROW, timeout, abort, fan-out, checkpoints",
+    color: "#4fd1c5"
+  },
+  upgrade: {
+    badge: "UPGRADE",
+    blurb: "Wave 1 (v1.1) guarantees: drain deadline, completion policies, sticky FAIL_FAST, FALLBACK routing, budgets, linting, isomorphic build",
+    color: "#f0b429"
+  },
+  conformance: {
+    badge: "CONFORMANCE",
+    blurb: "the storage adapter contract is enforced by a checker with teeth, plus the snapshot wire format",
+    color: "#31c48d"
+  },
+  lint: {
+    badge: "LINT",
+    blurb: "the SUCCESS_DEAD_END rule: non-terminal nodes whose success path has nowhere to go",
+    color: "#fb923c"
+  },
+  edges: {
+    badge: "EDGES",
+    blurb: "typed edges: deep-equality/t predicate routing, else edges, parallel edges and explicit Next/goto routing",
+    color: "#38bdf8"
+  },
+  registry: {
+    badge: "REGISTRY",
+    blurb: "the function registry: run/test by name, lazy resolution, UNKNOWN_FUNCTION, fingerprints",
+    color: "#a78bfa"
+  },
+  graphjson: {
+    badge: "JSON",
+    blurb: "graph data files: parsing a document into a definition, total validation, engine from JSON",
+    color: "#34d399"
+  },
+  scripts: {
+    badge: "SCRIPTS",
+    blurb: "script loading: exported and self-registered functions, format detection, process-global namespace freeze",
+    color: "#f472b6"
+  }
+};
+
+const UNIT_CATEGORIES: Array<[string, string]> = [
+  ["Graph validation", "Constructor-time rejection of malformed graph definitions"],
+  ["Error classes & utilities", "Error hierarchy, codes, id/time generation, throw coercion"],
+  ["EventBus", "Required vs non-required listeners, ordering, isolation, teardown"],
+  ["InMemoryStorage", "Atomic snapshot semantics and copy isolation"],
+  ["Graph freezing", "Immutability of definitions after construction"],
+  ["Engine lifecycle", "State machine, single-run guard, plugin init/shutdown"],
+  ["Execution & scheduler", "Scheduling, fan-out, contexts, events, checkpoints, settlement"],
+  ["Retry", "RETRY policy looping, delays, attempt accounting"],
+  ["Cancellation", "Cooperative abort, cancellation events, terminal no-ops"]
+];
+
+const escapeHtml = (value: string): string =>
+  value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+
+export function findingsOf(record: TestResultRecord): string[] {
+  const derived = record.logs
+    .filter(line => line.startsWith("finding:"))
+    .map(line => line.replace(/^finding:\s*/, ""));
+  if (record.finding) derived.unshift(record.finding);
+  return [...new Set(derived)];
+}
+
+function renderTestRow(record: TestResultRecord): string {
+  const findings = findingsOf(record);
+  const isFinding = findings.length > 0;
+  const classes = [
+    "row",
+    record.status === "passed" ? "ok" : "bad",
+    record.kind
+  ].join(" ");
+
+  const details: string[] = [];
+
+  if (isFinding) {
+    details.push(
+      `<div class="detail finding"><span class="tag">findings</span><ul>` +
+        findings.map(line => `<li>${escapeHtml(line)}</li>`).join("") +
+        "</ul></div>"
+    );
+  }
+
+  if (record.logs.length > 0) {
+    details.push(
+      `<div class="detail"><span class="tag">observations</span><ul>` +
+        record.logs.map(line => `<li>${escapeHtml(line)}</li>`).join("") +
+        "</ul></div>"
+    );
+  }
+
+  if (record.error) {
+    details.push(
+      `<div class="detail error"><span class="tag">error</span>` +
+        `<div class="errline">${escapeHtml(record.error.name)}: ${escapeHtml(record.error.message)}</div>` +
+        (record.error.stack
+          ? `<pre>${escapeHtml(record.error.stack.split("\n").slice(0, 8).join("\n"))}</pre>`
+          : "") +
+        "</div>"
+    );
+  }
+
+  return `
+  <details class="${classes}" data-kind="${record.kind}" data-status="${record.status}" data-finding="${isFinding}" data-search="${escapeHtml(
+    (record.id + " " + record.category + " " + record.name + " " + findings.join(" ")).toLowerCase()
+  )}">
+    <summary>
+      <span class="pill ${record.status}">${record.status === "passed" ? "PASS" : "FAIL"}</span>
+      <span class="id">${escapeHtml(record.id)}</span>
+      <span class="cat">${escapeHtml(record.category)}</span>
+      <span class="name">${escapeHtml(record.name)}</span>
+      ${isFinding ? '<span class="star" title="documents an engine semantic">finding</span>' : ""}
+      <span class="ms">${record.durationMs} ms</span>
+    </summary>
+    ${details.join("") || '<div class="detail muted">No additional observations.</div>'}
+  </details>`;
+}
+
+function bar(label: string, kind: TestKind, totals: KindTotals, durationMs: number): string {
+  const pct = totals.total === 0 ? 0 : Math.round((totals.passed / totals.total) * 100);
+  return `
+  <div class="barrow">
+    <div class="barlabel"><span class="badge ${kind}">${KIND_META[kind]?.badge ?? kind.toUpperCase()}</span> ${escapeHtml(label)}</div>
+    <div class="track"><div class="fill ${totals.failed > 0 ? "warn" : ""}" style="width:${pct}%">${pct}%</div></div>
+    <div class="barmeta">${totals.passed}/${totals.total} · ${durationMs} ms</div>
+  </div>`;
+}
+
+export function writeReport(summary: RunSummary, workspaceRoot: string): { htmlPath: string; jsonPath: string } {
+  const reportDir = path.join(workspaceRoot, "report");
+  fs.mkdirSync(reportDir, { recursive: true });
+
+  const jsonPath = path.join(reportDir, "report.json");
+  fs.writeFileSync(jsonPath, JSON.stringify(summary, null, 2), "utf8");
+
+  const { totals } = summary;
+  const kinds = Object.keys(KIND_META) as TestKind[];
+  const findings = summary.tests.flatMap(test =>
+    findingsOf(test).map(text => ({ test, text }))
+  );
+  const failedTests = summary.tests.filter(test => test.status === "failed");
+
+  const testsOfKind = (kind: TestKind): TestResultRecord[] =>
+    summary.tests.filter(test => test.kind === kind);
+
+  const categoryDurations = new Map(
+    summary.byCategory.map(entry => [`${entry.kind}::${entry.category}`, entry.durationMs])
+  );
+
+  const kindSummary = kinds
+    .map(kind => `${totals.byKind[kind].total} ${KIND_META[kind].badge.toLowerCase()}`)
+    .join(" + ");
+
+  const processHygiene =
+    summary.unhandledRejections.length === 0
+      ? `<span class="pill passed">clean</span> no unhandled rejections observed during the run`
+      : `<span class="pill failed">noisy</span> ${summary.unhandledRejections.length} unhandled rejection(s) observed`;
+
+  const inventoryTable = (kind: TestKind): string => {
+    const tests = testsOfKind(kind);
+    if (tests.length === 0) return "";
+    return `
+  <h3>${tests.length} ${KIND_META[kind].badge} cases — ${escapeHtml(KIND_META[kind].blurb)}</h3>
+  <table>
+    <tr><th>#</th><th>Case</th><th>Area</th><th>Time</th></tr>
+    ${tests
+      .map(
+        test =>
+          `<tr><td>${escapeHtml(test.id)}</td><td>${escapeHtml(test.name)}</td>` +
+          `<td class="muted">${escapeHtml(test.category)}</td><td>${test.durationMs} ms</td></tr>`
+      )
+      .join("")}
+  </table>`;
+  };
+
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>AutomateGraph Execution Engine — Test Report (${totals.total} tests)</title>
+<style>
+  :root{
+    --bg:#0b1020; --panel:#121a33; --panel2:#0f1730; --line:#24304f;
+    --txt:#e7ecf7; --muted:#94a3c4; --accent:#6ea8fe; --ok:#31c48d; --bad:#f4645f;
+    --warn:#f0b429; --unit:#7c9cff; --complex:#c084fc; --async:#4fd1c5;
+    --upgrade:#f0b429; --conformance:#31c48d;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:radial-gradient(1200px 600px at 15% -10%,#16224a 0%,var(--bg) 55%);color:var(--txt);
+    font:15px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
+  .wrap{max-width:1180px;margin:0 auto;padding:32px 20px 80px}
+  h1{font-size:30px;margin:0 0 6px;letter-spacing:-.4px}
+  h2{font-size:19px;margin:34px 0 12px;letter-spacing:-.2px}
+  h3{font-size:14px;margin:20px 0 8px;color:var(--muted);text-transform:uppercase;letter-spacing:.07em}
+  .sub{color:var(--muted);margin:0 0 22px}
+  .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin:22px 0 8px}
+  .card{background:linear-gradient(180deg,var(--panel),var(--panel2));border:1px solid var(--line);
+    border-radius:14px;padding:14px 16px}
+  .card .k{color:var(--muted);font-size:12px;text-transform:uppercase;letter-spacing:.08em}
+  .card .v{font-size:25px;font-weight:700;margin-top:4px}
+  .card.good .v{color:var(--ok)} .card.bad .v{color:var(--bad)}
+  .barrow{display:grid;grid-template-columns:340px 1fr 130px;gap:12px;align-items:center;padding:6px 0;border-bottom:1px dashed #1c2540}
+  .barlabel{font-size:13.5px}
+  .track{background:#0a1024;border:1px solid var(--line);border-radius:999px;height:16px;overflow:hidden}
+  .fill{height:100%;background:linear-gradient(90deg,#2f7cf6,#31c48d);color:#04122b;font-size:10.5px;
+    font-weight:700;text-align:right;padding-right:6px;line-height:16px}
+  .fill.warn{background:linear-gradient(90deg,#f0b429,#f4645f)}
+  .barmeta{color:var(--muted);font-size:12.5px;text-align:right}
+  .badge{display:inline-block;font-size:10.5px;font-weight:700;letter-spacing:.06em;padding:2px 7px;border-radius:6px;vertical-align:middle}
+  .badge.unit{background:#1b2a55;color:var(--unit)}
+  .badge.integration{background:#331b55;color:var(--complex)}
+  .badge.async{background:#123a3a;color:var(--async)}
+  .badge.upgrade{background:#3a2b0d;color:var(--upgrade)}
+  .badge.conformance{background:#0f3627;color:var(--conformance)}
+  .badge.lint{background:#3a2410;color:#fb923c}
+  .badge.edges{background:#0d2a3a;color:#38bdf8}
+  .badge.registry{background:#2a1f45;color:#a78bfa}
+  .badge.graphjson{background:#0e3229;color:#34d399}
+  .badge.scripts{background:#3d1f2f;color:#f472b6}
+  .pill{display:inline-block;font-size:11px;font-weight:700;padding:2px 8px;border-radius:999px}
+  .pill.passed{background:#10322a;color:var(--ok);border:1px solid #1c5b46}
+  .pill.failed{background:#3a1620;color:var(--bad);border:1px solid #7a2b32}
+  .findings{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:12px}
+  .fcard{background:var(--panel);border:1px solid var(--line);border-left:3px solid var(--warn);border-radius:12px;padding:12px 14px}
+  .fcard .fid{color:var(--warn);font-weight:700;font-size:12px}
+  .fcard .ftitle{font-weight:600;margin:2px 0 6px}
+  .fcard .fbody{color:#c8d3ec;font-size:13.5px}
+  .toolbar{display:flex;gap:10px;flex-wrap:wrap;align-items:center;margin:14px 0}
+  .btn{background:#16204a;border:1px solid var(--line);color:var(--txt);border-radius:999px;padding:6px 13px;
+    font-size:13px;cursor:pointer}
+  .btn.active{background:#233b7a;border-color:#3b57a6}
+  input[type=search]{background:#0d142c;border:1px solid var(--line);color:var(--txt);border-radius:999px;
+    padding:7px 14px;min-width:260px;font-size:13.5px}
+  .row{border:1px solid var(--line);border-radius:10px;margin:6px 0;background:var(--panel2)}
+  .row summary{display:grid;grid-template-columns:64px 62px 210px 1fr 74px 78px;gap:10px;align-items:center;
+    padding:9px 12px;cursor:pointer;list-style:none}
+  .row summary::-webkit-details-marker{display:none}
+  .row.ok{border-left:3px solid var(--ok)} .row.bad{border-left:3px solid var(--bad)}
+  .row .id{color:var(--muted);font-size:12.5px;font-variant-numeric:tabular-nums}
+  .row .cat{color:#b9c6e6;font-size:13px}
+  .row .name{font-size:13.5px}
+  .row .ms{color:var(--muted);font-size:12px;text-align:right}
+  .row .star{color:var(--warn);font-size:11px;border:1px solid #5f4a12;background:#2a2208;border-radius:6px;
+    padding:1px 6px;justify-self:start}
+  .detail{padding:10px 14px 12px;border-top:1px solid #1a2340;font-size:13.5px;color:#c8d3ec}
+  .detail .tag{display:inline-block;font-size:10.5px;font-weight:700;letter-spacing:.06em;color:#8fa6d8;
+    text-transform:uppercase;margin-right:8px}
+  .detail ul{margin:6px 0 0 18px;padding:0}
+  .detail.error .errline{color:#ffb3b0;font-weight:600}
+  pre{background:#080d1c;border:1px solid #1c2540;border-radius:8px;padding:10px;overflow:auto;font-size:12.5px;color:#b9c6e6}
+  .muted{color:var(--muted)}
+  table{width:100%;border-collapse:collapse;font-size:13.5px}
+  th,td{text-align:left;padding:8px 10px;border-bottom:1px solid #1c2540;vertical-align:top}
+  th{color:var(--muted);font-weight:600;font-size:12px;text-transform:uppercase;letter-spacing:.06em}
+  code{background:#0d142c;border:1px solid #1c2540;border-radius:6px;padding:1px 6px;font-size:12.5px}
+  .note{background:#101a38;border:1px solid var(--line);border-radius:12px;padding:12px 16px;color:#c8d3ec;font-size:13.5px}
+  .note.warn{border-color:#5f4a12;background:#241d09}
+  footer{color:var(--muted);font-size:12.5px;margin-top:28px;border-top:1px solid #1c2540;padding-top:14px}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>AutomateGraph Execution Engine v1.5 — Test Report</h1>
+  <p class="sub">${totals.total} tests (${kindSummary}) executed against the single-file isomorphic core.
+  Generated ${escapeHtml(summary.generatedAt)} · Node ${escapeHtml(summary.nodeVersion)} · wall clock ${summary.durationMs} ms.</p>
+
+  <div class="cards">
+    <div class="card"><div class="k">Total</div><div class="v">${totals.total}</div></div>
+    <div class="card good"><div class="k">Passed</div><div class="v">${totals.passed}</div></div>
+    <div class="card ${totals.failed ? "bad" : "good"}"><div class="k">Failed</div><div class="v">${totals.failed}</div></div>
+    ${kinds
+      .map(
+        kind =>
+          `<div class="card"><div class="k">${KIND_META[kind].badge}</div><div class="v">${totals.byKind[kind].passed}/${totals.byKind[kind].total}</div></div>`
+      )
+      .join("")}
+    <div class="card"><div class="k">Findings</div><div class="v">${findings.length}</div></div>
+    <div class="card"><div class="k">Duration</div><div class="v">${(summary.durationMs / 1000).toFixed(2)}s</div></div>
+  </div>
+
+  <p class="note">Process hygiene on shutdown: ${processHygiene}. Each test runs in sequence with a per-test
+  timeout, so a hang or a leaked promise surfaces in this report instead of hanging the suite.</p>
+
+  <p class="note warn"><strong>v1.1 changed two observable behaviours:</strong> a cooperative callback that
+  <em>rejects because of</em> an abort now settles <code>CANCELLED</code> (was <code>FAILED</code> + unhandled error), and
+  <code>FAIL_FAST</code> is sticky at node level (was a one-off queue flush). <strong>v1.2 added the
+  <code>SUCCESS_DEAD_END</code> lint error.</strong> <strong>v1.3 adds typed edges</strong> — <code>next</code> now accepts
+  <code>{ nextNode, result, test, parallel }</code> objects (exclusive, ordered, first-match-wins, deep
+  equality) alongside the original strings (parallel, unchanged), plus explicit routing via
+  <code>return new Next(target, value)</code> or <code>context.goto(target)</code>. <strong>v1.4 adds the
+  function registry</strong> — <code>run</code> and edge <code>test</code> may name a registered function,
+  resolved lazily at evaluation time, with <code>{ fingerprint, names }</code> reported on
+  every run — plus a JSON loader (<code>src/graph-json.ts</code>) that turns a graph
+  document into a definition with total, path-carrying validation. <strong>v1.5 loads scripts</strong> —
+  a document may declare where its functions live (<code>path</code>, inline
+  <code>source</code> or <code>url</code>), the script either exports them or registers itself through
+  <code>globalThis.GraphEngine.registerEngineNamespace()</code>, and a namespace is frozen once per
+  process. Purely additive: every v1.0–v1.4 graph keeps its behaviour. See
+  <code>CHANGELOG.md</code>.</p>
+
+  <h2>Results by category</h2>
+  ${summary.byCategory
+    .map(entry =>
+      bar(
+        entry.category,
+        entry.kind,
+        { total: entry.total, passed: entry.passed, failed: entry.failed },
+        entry.durationMs
+      )
+    )
+    .join("")}
+
+  <h2>Engine semantics documented by the findings (${findings.length})</h2>
+  <div class="findings">
+    ${findings
+      .map(
+        ({ test, text }) => `<div class="fcard">
+          <div class="fid">${escapeHtml(test.id)} · ${escapeHtml(KIND_META[test.kind]?.badge ?? test.kind)}</div>
+          <div class="ftitle">${escapeHtml(test.name)}</div>
+          <div class="fbody">${escapeHtml(text)}</div>
+        </div>`
+      )
+      .join("")}
+  </div>
+
+  <h2>Test inventory</h2>
+  <h3>${UNIT_CATEGORIES.length} unit categories (${totals.byKind.unit.total} tests)</h3>
+  <table>
+    <tr><th>Category</th><th>Focus</th><th>Count</th><th>Time</th></tr>
+    ${UNIT_CATEGORIES.map(([category, focus]) => {
+      const count = summary.tests.filter(
+        test => test.kind === "unit" && test.category === category
+      ).length;
+      const duration = categoryDurations.get(`unit::${category}`) ?? 0;
+      return `<tr><td>${escapeHtml(category)}</td><td class="muted">${escapeHtml(focus)}</td><td>${count}</td><td>${duration} ms</td></tr>`;
+    }).join("")}
+  </table>
+  ${(["integration", "async", "upgrade", "conformance", "lint", "edges", "registry", "graphjson", "scripts"] as TestKind[]).map(inventoryTable).join("")}
+
+  <h2>All test results</h2>
+  <div class="toolbar">
+    <button class="btn active" data-filter="all">All (${totals.total})</button>
+    ${kinds
+      .map(
+        kind =>
+          `<button class="btn" data-filter="${kind}">${KIND_META[kind].badge} (${totals.byKind[kind].total})</button>`
+      )
+      .join("")}
+    <button class="btn" data-filter="failed">Failed (${totals.failed})</button>
+    <button class="btn" data-filter="finding">Findings (${findings.length})</button>
+    <input type="search" id="q" placeholder="Search id, category, test name…"/>
+  </div>
+  <div id="rows">
+    ${kinds
+      .map(kind => testsOfKind(kind).map(renderTestRow).join(""))
+      .join("")}
+  </div>
+
+  <h2>How the suite was run</h2>
+  <div class="note">
+    <p style="margin-top:0"><code>npx tsc -p tsconfig.json</code> compiles <code>src/</code> and the tests to <code>js/</code>,
+    <code>npx tsc -p tsconfig.browser.json</code> proves the core is isomorphic (DOM libs, no Node types — asserted by the
+    UPGRADE pack), then <code>node js/tests/runner.js</code> executes all ${totals.total} cases (${kinds
+    .map(kind => `${totals.byKind[kind].total} ${KIND_META[kind].badge.toLowerCase()}`)
+    .join(" + ")}) and writes
+    <code>report/report.json</code> plus this page. No third-party test framework: <code>tests/harness.ts</code> provides
+    exception-based checks, per-test timeouts and log capture.</p>
+    <p>Artifacts: <code>src/automategraph.ts</code> (engine), <code>src/storage-adapter.ts</code> (adapter contract +
+    wire format), <code>src/storage-conformance.ts</code> (adapter checker), <code>tests/unit.test.ts</code>,
+    <code>tests/complex.test.ts</code>, <code>tests/async.test.ts</code>, <code>tests/upgrade.test.ts</code>,
+    <code>tests/conformance.test.ts</code>, <code>tests/lint.test.ts</code>, <code>tests/edges.test.ts</code>, <code>tests/registry.test.ts</code>, <code>tests/graphjson.test.ts</code>, <code>tests/scripts.test.ts</code>, <code>docs/diagrams/</code>,
+    <code>CHANGELOG.md</code>, <code>UPGRADE-PROPOSAL.md</code>.</p>
+  </div>
+
+  <footer>
+    ${failedTests.length === 0
+      ? `All ${totals.total} tests passed. Findings above are deliberate documentation of observed engine behaviour, not failures.`
+      : `${failedTests.length} failing test(s): ${failedTests.map(test => escapeHtml(test.id)).join(", ")}`}
+  </footer>
+</div>
+<script>
+  (function () {
+    var active = "all";
+    var buttons = Array.prototype.slice.call(document.querySelectorAll(".btn[data-filter]"));
+    var rows = Array.prototype.slice.call(document.querySelectorAll("#rows > details"));
+    var query = document.getElementById("q");
+
+    function apply() {
+      var needle = (query.value || "").trim().toLowerCase();
+      rows.forEach(function (row) {
+        var kindOk =
+          active === "all" ||
+          (active === "failed" && row.dataset.status === "failed") ||
+          (active === "finding" && row.dataset.finding === "true") ||
+          row.dataset.kind === active;
+        var textOk = needle === "" || row.dataset.search.indexOf(needle) !== -1;
+        row.style.display = kindOk && textOk ? "" : "none";
+      });
+    }
+
+    buttons.forEach(function (button) {
+      button.addEventListener("click", function () {
+        active = button.dataset.filter;
+        buttons.forEach(function (other) { other.classList.toggle("active", other === button); });
+        apply();
+      });
+    });
+
+    query.addEventListener("input", apply);
+    apply();
+  })();
+</script>
+</body>
+</html>`;
+
+  const htmlPath = path.join(reportDir, "index.html");
+  fs.writeFileSync(htmlPath, html, "utf8");
+
+  return { htmlPath, jsonPath };
+}

package/tests/runner.ts

@@ -0,0 +1,58 @@
+/* ============================================================
+ * Test entry point — runs every registered case, prints a
+ * summary and writes the web report (report/index.html + JSON).
+ * ============================================================ */
+
+import * as path from "path";
+
+import { TEST_KINDS, runAll } from "./harness";
+import { findingsOf, writeReport } from "./report";
+
+import "./unit.test";
+import "./complex.test";
+import "./async.test";
+import "./upgrade.test";
+import "./conformance.test";
+import "./lint.test";
+import "./edges.test";
+import "./registry.test";
+import "./graphjson.test";
+import "./scripts.test";
+
+async function main(): Promise<void> {
+  const summary = await runAll();
+
+  const workspaceRoot = path.resolve(__dirname, "..", "..");
+  const { htmlPath, jsonPath } = writeReport(summary, workspaceRoot);
+
+  process.stdout.write("\n────────────────────────────────────────────\n");
+
+  for (const kind of TEST_KINDS) {
+    const totals = summary.totals.byKind[kind];
+    if (totals.total === 0) continue;
+    const label = kind.toUpperCase().padEnd(12, " ");
+    process.stdout.write(
+      `${label}${totals.passed}/${totals.total} passed\n`
+    );
+  }
+
+  const findingCount = summary.tests.reduce(
+    (total, test) => total + findingsOf(test).length,
+    0
+  );
+
+  process.stdout.write(
+    `TOTAL      ${summary.totals.passed}/${summary.totals.total} passed in ${summary.durationMs}ms\n`
+  );
+  process.stdout.write(`FINDINGS   ${findingCount}\n`);
+  process.stdout.write(`REPORT     ${htmlPath}\n`);
+  process.stdout.write(`JSON       ${jsonPath}\n`);
+  if (summary.unhandledRejections.length > 0) {
+    process.stdout.write(`WARN       ${summary.unhandledRejections.length} unhandled rejection(s)\n`);
+  }
+  process.stdout.write("────────────────────────────────────────────\n");
+
+  process.exit(summary.totals.failed > 0 ? 1 : 0);
+}
+
+void main();