waygraph 0.16.0 → 0.16.1

package/dist/live/traverse/traverse.js

@@ -1,207 +1,13 @@
 import { Engine } from "../../engine/engine.js";
-import { buildFlow } from "../../engine/flow/flow.js";
+import { envFlag, envString } from "../../engine/env.js";
 import { MemPage } from "../../engine/mem/mem.js";
-import { buildExploreContext, buildExploreMenu, } from "../auto/explore.js";
-import { detectHere, memStubValue } from "../auto/auto.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+import { chromiumExecutablePath } from "../../runtime/browser.js";
 import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
-import { EdgeLeaseCoordinator } from "./lease.js";
+import { buildExploreContext, } from "../auto/explore.js";
 import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./coverage.js";
-import { chromiumExecutablePath } from "../../runtime/browser.js";
-import { envFlag, envString } from "../../engine/env.js";
-import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
-function seedMem(library, mem, dataJson) {
-    const raw = dataJson ?? envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
-    let envParsed = {};
-    if (raw) {
-        try {
-            envParsed = JSON.parse(raw);
-        }
-        catch {
-            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
-        }
-    }
-    for (const entry of library.values()) {
-        for (const k of entry.block.requires ?? []) {
-            if (mem.has(k))
-                continue;
-            if (k.name in envParsed) {
-                mem.set(k, envParsed[k.name]);
-                continue;
-            }
-            const def = memStubValue(k);
-            if (def !== undefined)
-                mem.set(k, def);
-        }
-    }
-}
-function snapshotMem(library, mem) {
-    const out = {};
-    for (const entry of library.values()) {
-        for (const k of entry.block.requires ?? []) {
-            if (mem.has(k) && !(k.name in out)) {
-                out[k.name] = mem.get(k);
-            }
-        }
-    }
-    return out;
-}
-function restoreMem(library, mem, snap, dataJson) {
-    seedMem(library, mem, dataJson);
-    for (const entry of library.values()) {
-        for (const k of entry.block.requires ?? []) {
-            if (k.name in snap) {
-                mem.set(k, snap[k.name]);
-            }
-        }
-    }
-}
-function missingMemKeys(entry, mem) {
-    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
-}
-function ensureMem(entry, mem) {
-    const missing = missingMemKeys(entry, mem);
-    if (missing.length === 0)
-        return;
-    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
-        `(pass --data '{...}' or WAYGRAPH_DATA)`);
-}
-function edgeKey(edge) {
-    const id = edge.instanceOption?.id;
-    return id ? `${edge.block}::${id}` : edge.block;
-}
-async function runOneBlock(engine, entry, context, page, mem) {
-    const flow = buildFlow([entry.block], engine.config);
-    const BLOCK_TIMEOUT_MS = 45_000;
-    let timer;
-    try {
-        const ran = await Promise.race([
-            flow.run(context, mem, { page, closeOnFinish: false }),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
-            }),
-        ]);
-        return ran.result;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
-async function runTraverseWorker(opts) {
-    const { traverseId, workerIndex, parallel, maxSteps, maxVisitsPerNode, maxVisitsPerEdge, timeoutMs, graph, library, engine, context, mem, leases, } = opts;
-    let page = opts.page;
-    const startUrl = opts.startUrl;
-    const nodeVisits = new Map();
-    const edgeVisits = new Map();
-    const edgesHit = new Set();
-    let steps = 0;
-    const startedAt = Date.now();
-    let lastHere = opts.from ?? null;
-    let exitCode = 0;
-    let leaf;
-    try {
-        for (;;) {
-            if (Date.now() - startedAt > timeoutMs) {
-                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
-                exitCode = 1;
-                break;
-            }
-            if (steps >= maxSteps) {
-                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
-                exitCode = 1;
-                break;
-            }
-            if (page.isClosed()) {
-                page = await context.newPage();
-                if (startUrl) {
-                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
-                }
-            }
-            const detected = await detectHere(page, library.navBlocks);
-            const here = lastHere ?? detected ?? opts.from ?? null;
-            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
-                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
-                exitCode = 1;
-                break;
-            }
-            const menu = await buildExploreMenu(page, graph, library, here);
-            const candidates = menu.flat.filter((edge) => {
-                const key = edgeKey(edge);
-                if ((edgeVisits.get(key) ?? 0) >= maxVisitsPerEdge)
-                    return false;
-                if (parallel > 1) {
-                    if (EdgeLeaseCoordinator.partitionIndex(key, parallel) !== workerIndex) {
-                        return false;
-                    }
-                }
-                return true;
-            });
-            if (candidates.length === 0) {
-                const label = here ?? detected ?? "unknown";
-                leaf = label;
-                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
-                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
-                break;
-            }
-            const pick = [...candidates].sort((a, b) => {
-                const aWild = a.from === "*" ? 1 : 0;
-                const bWild = b.from === "*" ? 1 : 0;
-                if (aWild !== bWild)
-                    return aWild - bWild;
-                return edgeKey(a).localeCompare(edgeKey(b));
-            })[0];
-            const key = edgeKey(pick);
-            if (!leases.tryClaim(key, traverseId)) {
-                // Another worker won a race (instance fan-out); treat as unavailable.
-                edgeVisits.set(key, maxVisitsPerEdge);
-                continue;
-            }
-            const entry = library.byName.get(pick.block);
-            if (!entry) {
-                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
-                exitCode = 1;
-                break;
-            }
-            const fromLabel = here ?? pick.from;
-            try {
-                if (pick.instanceOption) {
-                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
-                }
-                ensureMem(entry, mem);
-                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
-                    (pick.label ? ` (${pick.label})` : ""));
-                const out = await runOneBlock(engine, entry, context, page, mem);
-                const observed = typeof out === "object" && out && "__state" in out
-                    ? String(out.__state)
-                    : pick.to;
-                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
-                edgesHit.add(key);
-                if (here)
-                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
-                lastHere = observed;
-                steps += 1;
-                if (observed !== pick.to && pick.to !== "*") {
-                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
-                }
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
-                exitCode = 1;
-                break;
-            }
-        }
-    }
-    finally {
-        console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
-    }
-    return {
-        exitCode,
-        steps,
-        edgesHit: [...edgesHit],
-        ...(leaf ? { leaf } : {}),
-    };
-}
+import { EdgeLeaseCoordinator } from "./lease.js";
+import { restoreMem, runTraverseWorker, seedMem, snapshotMem } from "./worker.js";
 /**
  * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
  * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).

package/dist/live/traverse/worker.d.ts

@@ -0,0 +1,37 @@
+import type { BrowserContext, Page } from "@playwright/test";
+import type { WaygraphGraph } from "../../analysis/graph.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import { Engine } from "../../engine/engine.js";
+import { MemPage, type MemKey } from "../../engine/mem/mem.js";
+import type { BlockEntry } from "../../manifest/project.js";
+import { buildExploreContext, type ExploreEdge } from "../auto/explore.js";
+import { EdgeLeaseCoordinator } from "./lease.js";
+import type { TraverseWorkerResult } from "./traverse.js";
+export declare function seedMem(library: Map<string, BlockEntry>, mem: MemPage, dataJson?: string): void;
+export declare function snapshotMem(library: Map<string, BlockEntry>, mem: MemPage): Record<string, unknown>;
+export declare function restoreMem(library: Map<string, BlockEntry>, mem: MemPage, snap: Record<string, unknown>, dataJson?: string): void;
+export declare function missingMemKeys(entry: BlockEntry, mem: MemPage): MemKey<unknown>[];
+export declare function ensureMem(entry: BlockEntry, mem: MemPage): void;
+export declare function edgeKey(edge: ExploreEdge): string;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage): Promise<Checkpoint<string>>;
+export interface WorkerOpts {
+    traverseId: string;
+    workerIndex: number;
+    parallel: number;
+    maxSteps: number;
+    maxVisitsPerNode: number;
+    maxVisitsPerEdge: number;
+    timeoutMs: number;
+    from?: string;
+    startUrl?: string;
+    baseURL?: string;
+    data?: string;
+    graph: WaygraphGraph;
+    library: Awaited<ReturnType<typeof buildExploreContext>>["library"];
+    engine: Engine;
+    context: BrowserContext;
+    page: Page;
+    mem: MemPage;
+    leases: EdgeLeaseCoordinator;
+}
+export declare function runTraverseWorker(opts: WorkerOpts): Promise<TraverseWorkerResult>;

package/dist/live/traverse/worker.js

@@ -0,0 +1,200 @@
+import { envString } from "../../engine/env.js";
+import { buildFlow } from "../../engine/flow/flow.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { detectHere } from "../auto/auto.js";
+import { buildExploreMenu } from "../auto/explore.js";
+import { memStubValue } from "../auto/mem.js";
+import { EdgeLeaseCoordinator } from "./lease.js";
+export function seedMem(library, mem, dataJson) {
+    const raw = dataJson ?? envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
+        }
+    }
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = memStubValue(k);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+export function snapshotMem(library, mem) {
+    const out = {};
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k) && !(k.name in out)) {
+                out[k.name] = mem.get(k);
+            }
+        }
+    }
+    return out;
+}
+export function restoreMem(library, mem, snap, dataJson) {
+    seedMem(library, mem, dataJson);
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (k.name in snap) {
+                mem.set(k, snap[k.name]);
+            }
+        }
+    }
+}
+export function missingMemKeys(entry, mem) {
+    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
+}
+export function ensureMem(entry, mem) {
+    const missing = missingMemKeys(entry, mem);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
+        `(pass --data '{...}' or WAYGRAPH_DATA)`);
+}
+export function edgeKey(edge) {
+    const id = edge.instanceOption?.id;
+    return id ? `${edge.block}::${id}` : edge.block;
+}
+export async function runOneBlock(engine, entry, context, page, mem) {
+    const flow = buildFlow([entry.block], engine.config);
+    const BLOCK_TIMEOUT_MS = 45000;
+    let timer;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        return ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function runTraverseWorker(opts) {
+    const { traverseId, workerIndex, parallel, maxSteps, maxVisitsPerNode, maxVisitsPerEdge, timeoutMs, graph, library, engine, context, mem, leases, } = opts;
+    let page = opts.page;
+    const startUrl = opts.startUrl;
+    const nodeVisits = new Map();
+    const edgeVisits = new Map();
+    const edgesHit = new Set();
+    let steps = 0;
+    const startedAt = Date.now();
+    let lastHere = opts.from ?? null;
+    let exitCode = 0;
+    let leaf;
+    try {
+        for (;;) {
+            if (Date.now() - startedAt > timeoutMs) {
+                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
+                exitCode = 1;
+                break;
+            }
+            if (steps >= maxSteps) {
+                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
+                exitCode = 1;
+                break;
+            }
+            if (page.isClosed()) {
+                page = await context.newPage();
+                if (startUrl) {
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+                }
+            }
+            const detected = await detectHere(page, library.navBlocks);
+            const here = lastHere ?? detected ?? opts.from ?? null;
+            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
+                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
+                exitCode = 1;
+                break;
+            }
+            const menu = await buildExploreMenu(page, graph, library, here);
+            const candidates = menu.flat.filter((edge) => {
+                const key = edgeKey(edge);
+                if ((edgeVisits.get(key) ?? 0) >= maxVisitsPerEdge)
+                    return false;
+                if (parallel > 1) {
+                    if (EdgeLeaseCoordinator.partitionIndex(key, parallel) !== workerIndex) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+            if (candidates.length === 0) {
+                const label = here ?? detected ?? "unknown";
+                leaf = label;
+                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
+                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
+                break;
+            }
+            const pick = [...candidates].sort((a, b) => {
+                const aWild = a.from === "*" ? 1 : 0;
+                const bWild = b.from === "*" ? 1 : 0;
+                if (aWild !== bWild)
+                    return aWild - bWild;
+                return edgeKey(a).localeCompare(edgeKey(b));
+            })[0];
+            const key = edgeKey(pick);
+            if (!leases.tryClaim(key, traverseId)) {
+                // Another worker won a race (instance fan-out); treat as unavailable.
+                edgeVisits.set(key, maxVisitsPerEdge);
+                continue;
+            }
+            const entry = library.byName.get(pick.block);
+            if (!entry) {
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
+                exitCode = 1;
+                break;
+            }
+            const fromLabel = here ?? pick.from;
+            try {
+                if (pick.instanceOption) {
+                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
+                }
+                ensureMem(entry, mem);
+                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
+                    (pick.label ? ` (${pick.label})` : ""));
+                const out = await runOneBlock(engine, entry, context, page, mem);
+                const observed = typeof out === "object" && out && "__state" in out
+                    ? String(out.__state)
+                    : pick.to;
+                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
+                edgesHit.add(key);
+                if (here)
+                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
+                lastHere = observed;
+                steps += 1;
+                if (observed !== pick.to && pick.to !== "*") {
+                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
+                exitCode = 1;
+                break;
+            }
+        }
+    }
+    finally {
+        console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
+    }
+    return {
+        exitCode,
+        steps,
+        edgesHit: [...edgesHit],
+        ...(leaf ? { leaf } : {}),
+    };
+}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "waygraph",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -54,6 +57,7 @@
     "test:ui": "playwright test --ui",
     "test:unit": "node --import tsx/esm --test tests/unit/*.spec.ts",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",
+    "examples:link": "node scripts/link-examples.mjs",
     "example:saucedemo:test": "npm --prefix examples/saucedemo test",
     "example:saucedemo:auto": "npm --prefix examples/saucedemo run auto",
     "check:structure": "node scripts/check-structure.mjs",