waygraph 0.15.46 → 0.15.49

package/dist/overlay-beacon.d.ts

@@ -1,44 +0,0 @@
-/**
- * Blind-agent / Playwright checks for waygraph overlay modals.
- *
- * Every live modal root must carry:
- *   data-wg-ui="1"
- *   data-wg-modal="panel|banner|auto-panel"
- *   data-wg-ready="1" when painted and readable
- *
- * Agents: do not claim the stepper works unless
- *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
- */
-import type { Page } from "@playwright/test";
-export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
-export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
-export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
-export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
-export type WgModalKind = "panel" | "banner" | "auto-panel";
-export type WgBeaconRow = {
-    id: string | null;
-    modal: string | null;
-    ready: boolean;
-    phase: string | null;
-    step: string | null;
-    block: string | null;
-    collapsed: boolean;
-    opacity: string;
-    textLen: number;
-    w: number;
-    h: number;
-    visible: boolean;
-};
-/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
-export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
-export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
-/**
- * Hard gate: a blank / missing / opacity-0 modal fails.
- * Use after demo/auto paints its first overlay.
- */
-export declare function assertWgOverlayReady(page: Page, opts?: {
-    modal?: WgModalKind;
-    minTextLen?: number;
-    /** When true, collapsed mini chrome is allowed (still needs visible box + text). */
-    allowCollapsed?: boolean;
-}): Promise<WgBeaconRow>;

package/dist/overlay-beacon.js

@@ -1,85 +0,0 @@
-/**
- * Blind-agent / Playwright checks for waygraph overlay modals.
- *
- * Every live modal root must carry:
- *   data-wg-ui="1"
- *   data-wg-modal="panel|banner|auto-panel"
- *   data-wg-ready="1" when painted and readable
- *
- * Agents: do not claim the stepper works unless
- *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
- */
-export const WG_UI_SEL = '[data-wg-ui="1"]';
-export const WG_READY_PANEL_SEL = '[data-wg-modal="panel"][data-wg-ready="1"]';
-export const WG_READY_AUTO_SEL = '[data-wg-modal="auto-panel"][data-wg-ready="1"]';
-export const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
-/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
-export function readWgOverlayBeaconInPage() {
-    const w = globalThis;
-    if (typeof w.__wgOverlayBeacon === "function")
-        return w.__wgOverlayBeacon();
-    return Array.from(document.querySelectorAll(WG_UI_SEL)).map((el) => {
-        const r = el.getBoundingClientRect();
-        const st = getComputedStyle(el);
-        return {
-            id: el.id || null,
-            modal: el.getAttribute("data-wg-modal"),
-            ready: el.getAttribute("data-wg-ready") === "1",
-            phase: el.getAttribute("data-wg-phase"),
-            step: el.getAttribute("data-wg-step"),
-            block: el.getAttribute("data-wg-block"),
-            collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
-            opacity: st.opacity,
-            textLen: (el.textContent || "").trim().length,
-            w: Math.round(r.width),
-            h: Math.round(r.height),
-            visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
-        };
-    });
-}
-export async function readWgOverlayBeacon(page) {
-    return page.evaluate(() => {
-        const w = window;
-        if (typeof w.__wgOverlayBeacon === "function") {
-            return w.__wgOverlayBeacon();
-        }
-        return Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
-            const r = el.getBoundingClientRect();
-            const st = getComputedStyle(el);
-            return {
-                id: el.id || null,
-                modal: el.getAttribute("data-wg-modal"),
-                ready: el.getAttribute("data-wg-ready") === "1",
-                phase: el.getAttribute("data-wg-phase"),
-                step: el.getAttribute("data-wg-step"),
-                block: el.getAttribute("data-wg-block"),
-                collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
-                opacity: st.opacity,
-                textLen: (el.textContent || "").trim().length,
-                w: Math.round(r.width),
-                h: Math.round(r.height),
-                visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
-            };
-        });
-    });
-}
-/**
- * Hard gate: a blank / missing / opacity-0 modal fails.
- * Use after demo/auto paints its first overlay.
- */
-export async function assertWgOverlayReady(page, opts) {
-    const modal = opts?.modal ?? "panel";
-    const minText = opts?.minTextLen ?? 12;
-    const rows = await readWgOverlayBeacon(page);
-    const hit = rows.find((r) => r.modal === modal &&
-        r.ready &&
-        r.visible &&
-        r.textLen >= minText &&
-        (opts?.allowCollapsed || !r.collapsed || r.textLen >= minText));
-    if (!hit) {
-        throw new Error(`waygraph overlay NOT ready (modal=${modal}, minTextLen=${minText}). ` +
-            `beacons=${JSON.stringify(rows)}. ` +
-            `Do not claim stepper/modal works.`);
-    }
-    return hit;
-}

package/dist/pilot.d.ts

@@ -1,54 +0,0 @@
-/**
- * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
- * real, persistent, inspectable browser session toward a natural-language
- * goal it plans and executes itself.
- *
- * Deliberately NOT a resolver that maps one ask to one Block
- * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
- * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
- * requests are multi-step ("log in and buy the backpack for me", "make a
- * signature draft request") and need an agent that plans a whole sequence
- * against the graph, not a single best-matching edge. `pilotStart` does not
- * plan, resolve, narrate, or act on anything - it only combines two
- * already-proven, separately-existing primitives into one payload:
- *
- * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
- *   real, persistent, visible-if-headful Playwright session an agent can
- *   keep driving across many calls, not a fresh session per request.
- * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
- *   project's Checkpoint/edge/description graph, not just what's reachable
- *   from the session's current position, because planning a multi-step
- *   route needs to see steps ahead, not just the next one.
- *
- * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
- * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
- * agent is holding it. All four already existed before this file did; see
- * openspec/changes/waygraph-pilot/design.md for the worked example (a real
- * login + add-to-cart + checkout run against examples/saucedemo, driven by
- * hand-picking indices from each status response) that proved this needs no
- * new execution primitive.
- */
-import { type WaygraphGraph } from "./analysis/graph.js";
-import { listBrowserSessions, type SessionMeta } from "./auto-session-ipc.js";
-import { type BrowserStartInit } from "./browser.js";
-import type { SessionSnapshot } from "./auto-session.js";
-export interface PilotStartResult {
-    sessionId: string;
-    socketPath: string;
-    headless: boolean;
-    /** The whole project's Block graph - every Checkpoint/edge/description, not just what's reachable right now. */
-    graph: WaygraphGraph;
-    /** The session's starting position, or `null` if the very first `status` read failed. */
-    snapshot: SessionSnapshot | null;
-}
-/**
- * Starts a detached session and reads back its own graph + starting
- * snapshot in one call, so an agent bootstraps with everything it needs
- * (a live session it can keep driving, and the full map of what exists) in
- * one round trip instead of separately knowing to chain `auto --cli
- * --detach` and `waygraph graph` itself.
- */
-export declare function pilotStart(init: BrowserStartInit): Promise<PilotStartResult>;
-/** Reattach to an existing browser session — does not spawn a new browser. */
-export declare function pilotAttach(projectDir: string, sessionId: string, inject?: string[]): Promise<PilotStartResult>;
-export { listBrowserSessions, type SessionMeta };

package/dist/pilot.js

@@ -1,80 +0,0 @@
-/**
- * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
- * real, persistent, inspectable browser session toward a natural-language
- * goal it plans and executes itself.
- *
- * Deliberately NOT a resolver that maps one ask to one Block
- * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
- * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
- * requests are multi-step ("log in and buy the backpack for me", "make a
- * signature draft request") and need an agent that plans a whole sequence
- * against the graph, not a single best-matching edge. `pilotStart` does not
- * plan, resolve, narrate, or act on anything - it only combines two
- * already-proven, separately-existing primitives into one payload:
- *
- * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
- *   real, persistent, visible-if-headful Playwright session an agent can
- *   keep driving across many calls, not a fresh session per request.
- * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
- *   project's Checkpoint/edge/description graph, not just what's reachable
- *   from the session's current position, because planning a multi-step
- *   route needs to see steps ahead, not just the next one.
- *
- * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
- * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
- * agent is holding it. All four already existed before this file did; see
- * openspec/changes/waygraph-pilot/design.md for the worked example (a real
- * login + add-to-cart + checkout run against examples/saucedemo, driven by
- * hand-picking indices from each status response) that proved this needs no
- * new execution primitive.
- */
-import { discoverGraph } from "./analysis/graph.js";
-import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
-import { browserStart } from "./browser.js";
-/**
- * Starts a detached session and reads back its own graph + starting
- * snapshot in one call, so an agent bootstraps with everything it needs
- * (a live session it can keep driving, and the full map of what exists) in
- * one round trip instead of separately knowing to chain `auto --cli
- * --detach` and `waygraph graph` itself.
- */
-export async function pilotStart(init) {
-    const { resolveInjectRoots } = await import("./block-inject.js");
-    const exploreInject = init.inject ??
-        (init.injectTokens?.length ? resolveInjectRoots(init.injectTokens, init.projectDir) : undefined);
-    const started = await browserStart({
-        ...init,
-        ...(exploreInject?.length ? { inject: exploreInject } : {}),
-        // Pilot navigates to baseURL on start (unlike `browser`, which defaults to about:blank).
-        skipInitialNavigation: init.skipInitialNavigation ?? false,
-    });
-    const graph = await discoverGraph(init.projectDir, exploreInject?.length ? { inject: exploreInject } : undefined);
-    const status = await requestSession(init.projectDir, started.sessionId, { op: "status" });
-    return {
-        sessionId: started.sessionId,
-        socketPath: started.socketPath,
-        headless: started.headless,
-        graph,
-        snapshot: status.ok ? status.snapshot : null,
-    };
-}
-/** Reattach to an existing browser session — does not spawn a new browser. */
-export async function pilotAttach(projectDir, sessionId, inject) {
-    const meta = resolveSessionMeta(sessionId, projectDir);
-    if (!meta) {
-        throw new Error(`waygraph pilot attach: no such session "${sessionId}" — run \`waygraph pilot sessions\` from the project dir`);
-    }
-    const graph = await discoverGraph(meta.projectDir, inject?.length ? { inject } : undefined);
-    const status = await requestSession(meta.projectDir, sessionId, { op: "status" });
-    if (!status.ok) {
-        throw new Error(`waygraph pilot attach: session "${sessionId}" not reachable (${status.error})`);
-    }
-    return {
-        sessionId: meta.sessionId,
-        socketPath: meta.socketPath,
-        headless: meta.headless,
-        graph,
-        snapshot: status.snapshot,
-    };
-}
-export { listBrowserSessions };

package/dist/practices-check.d.ts

@@ -1,14 +0,0 @@
-export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
-export interface PracticeWarning {
-    kind: PracticeKind;
-    file: string;
-    /** Short hint for humans/agents. */
-    detail: string;
-}
-export interface PracticeCheckOptions {
-    /** Skip all practice scanning (CLI `--no-practices`). */
-    disabled?: boolean;
-}
-export declare function collectPracticeWarnings(projectDir: string, walkDir: (dir: string, re: RegExp) => string[], opts?: PracticeCheckOptions): PracticeWarning[];
-export declare function practiceKindLabel(kind: PracticeKind): string;
-export declare function formatPracticeWarnings(projectDir: string, warnings: PracticeWarning[]): string[];

package/dist/practices-check.js

@@ -1,195 +0,0 @@
-/**
- * `waygraph check` / `waygraph typecheck` practice warnings — style/typing issues
- * that compile but erode the typed graph. Warnings only (never fail exit code)
- * unless paired with `tsc` errors in `waygraph typecheck`.
- */
-import { readFileSync, readdirSync } from "node:fs";
-import { dirname, relative } from "node:path";
-/** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
-const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
-/** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
-const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
-/** defineAssertBlock, any form - used to scope the empty-verify check below. */
-const IS_ASSERT_BLOCK = /\bdefineAssertBlock\s*[<(]/;
-/**
- * define(Method|Effect)Block<In, Out> with two BARE identifier type args
- * (never a nested generic like Checkpoint<string> - that's WILDCARD_CHECKPOINT's
- * own warning) - lets a real transition (In !== Out) be told apart from a
- * self-loop (In === Out, e.g. fill-username) using only source text.
- */
-const METHOD_EFFECT_GENERIC = /\bdefine(?:Method|Effect)Block\s*<\s*([A-Za-z_$][\w$]*)\s*,\s*([A-Za-z_$][\w$]*)\s*>/;
-/** `verify: []` - a literal empty array, the codegen-stub shape this check exists for. */
-const EMPTY_VERIFY_ARRAY = /\bverify\s*:\s*\[\s*\]/;
-/** Any `verify:` key at all, empty or not. */
-const HAS_VERIFY_KEY = /\bverify\s*:/;
-const SCAN_GLOB = /\.(block|flow)\.ts$/;
-/**
- * A selector string reaching for a regex-based Playwright text pseudo-class (`:has-text(/…/)`,
- * `:text-matches(…)`) or a plain XPath - real, recurring pattern: an LLM asked to target a simple
- * element (one class, one id, one data-attribute) instead writes a regex/XPath from scratch. Not a
- * type error (Playwright's own selector syntax accepts all of this), so nothing else catches it.
- */
-const TEXT_MATCHES_PSEUDO = /:text-matches\(/;
-const HAS_TEXT_REGEX_PSEUDO = /:has-text\(\s*\//;
-const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
-/** A selector string literal inline in a Block file (`.locator("…")`, `click: "…"`, `url: "…"`) -
- *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
- *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
-const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
-const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
-const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
-/** Whole-file opt-out: `// waygraph-ignore-practices` */
-const IGNORE_ALL = /waygraph-ignore-practices/;
-/** Per-kind opt-out: `// waygraph-ignore: multi-input, combined-action` */
-const IGNORE_KINDS = /waygraph-ignore:\s*([^\n*]+)/;
-function walkBlockAndFlowFiles(projectDir, walkDir) {
-    return walkDir(projectDir, SCAN_GLOB);
-}
-function ignoredKindsForFile(src) {
-    if (IGNORE_ALL.test(src))
-        return "all";
-    const m = IGNORE_KINDS.exec(src);
-    if (!m)
-        return new Set();
-    const kinds = new Set();
-    for (const token of m[1].split(/[,;\s]+/)) {
-        const t = token.trim();
-        if (t)
-            kinds.add(t);
-    }
-    return kinds;
-}
-function isIgnored(kind, ignore) {
-    return ignore === "all" || ignore.has(kind);
-}
-function countMatches(src, re) {
-    re.lastIndex = 0;
-    return (src.match(re) ?? []).length;
-}
-export function collectPracticeWarnings(projectDir, walkDir, opts) {
-    if (opts?.disabled)
-        return [];
-    const warnings = [];
-    for (const file of walkBlockAndFlowFiles(projectDir, walkDir)) {
-        const rel = relative(projectDir, file).replace(/\\/g, "/");
-        const src = readFileSync(file, "utf-8");
-        const ignore = ignoredKindsForFile(src);
-        if (!isIgnored("wildcard-checkpoint", ignore) && WILDCARD_CHECKPOINT.test(src)) {
-            warnings.push({
-                kind: "wildcard-checkpoint",
-                file: rel,
-                detail: 'uses Checkpoint<string> in a Block helper generic — prefer a typed Checkpoint from src/states/ (e.g. defineMethodBlock<LoginPage, LoginPage>)',
-            });
-        }
-        if (!isIgnored("assert-no-type-arg", ignore) && ASSERT_NO_TYPE_ARG.test(src)) {
-            warnings.push({
-                kind: "assert-no-type-arg",
-                file: rel,
-                detail: "defineAssertBlock({…}) without an explicit type argument — add defineAssertBlock<YourCheckpoint>({…}) so defineFlow typing stays honest",
-            });
-        }
-        const isMethodOrEffect = METHOD_OR_EFFECT_FILE.test(rel) || METHOD_OR_EFFECT_DEFINE.test(src);
-        if (isMethodOrEffect) {
-            const fills = countMatches(src, /\.fill\s*\(/g);
-            const clicks = countMatches(src, /\.click\s*\(/g);
-            if (!isIgnored("multi-input", ignore) && fills >= 2) {
-                warnings.push({
-                    kind: "multi-input",
-                    file: rel,
-                    detail: `Method/Effect act() has ${fills} .fill() calls — one distinct input per Block (split into separate defineMethodBlock files, e.g. fill-username + fill-password + submit-login)`,
-                });
-            }
-            if (!isIgnored("combined-action", ignore) && fills >= 1 && clicks >= 1) {
-                warnings.push({
-                    kind: "combined-action",
-                    file: rel,
-                    detail: "Method/Effect act() mixes .fill() and .click() — fill and submit must be separate Blocks (see examples/saucedemo login split)",
-                });
-            }
-            const genericMatch = METHOD_EFFECT_GENERIC.exec(src);
-            const isTransition = !!genericMatch && genericMatch[1] !== genericMatch[2];
-            if (isTransition &&
-                !isIgnored("empty-verify", ignore) &&
-                (!HAS_VERIFY_KEY.test(src) || EMPTY_VERIFY_ARRAY.test(src))) {
-                warnings.push({
-                    kind: "empty-verify",
-                    file: rel,
-                    detail: `transition Block (${genericMatch[1]} → ${genericMatch[2]}) has no verify checks — resolve() moving ` +
-                        "to a new Checkpoint is never confirmed by anything; add a Trait (or defineAssertBlock right after it), " +
-                        "or opt out explicitly with // waygraph-ignore: empty-verify if that's intentional",
-                });
-            }
-        }
-        if (!isIgnored("overcomplex-selector", ignore) &&
-            (TEXT_MATCHES_PSEUDO.test(src) || HAS_TEXT_REGEX_PSEUDO.test(src) || XPATH_LOCATOR.test(src))) {
-            const via = TEXT_MATCHES_PSEUDO.test(src)
-                ? ":text-matches(...)"
-                : HAS_TEXT_REGEX_PSEUDO.test(src)
-                    ? ":has-text(/regex/)"
-                    : "an XPath locator";
-            warnings.push({
-                kind: "overcomplex-selector",
-                file: rel,
-                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a _sel.ts/` +
-                    "*.sel.ts export) instead of a regex/XPath match unless the DOM genuinely has no stable selector",
-            });
-        }
-        if (!isIgnored("inline-selector-should-use-sel-file", ignore) && INLINE_SIMPLE_SELECTOR.test(src)) {
-            // Two real, coexisting conventions: the Map layout's own `_sel.ts` (one per page folder, next
-            // to `_nav`/`_page`/`_methods`) and the freeform layout's per-concern `<name>.sel.ts`.
-            const siblingSelFile = readdirSync(dirname(file)).some((f) => f === "_sel.ts" || f.endsWith(".sel.ts"));
-            if (siblingSelFile) {
-                warnings.push({
-                    kind: "inline-selector-should-use-sel-file",
-                    file: rel,
-                    detail: "a selector string is inlined here, but this directory already has a _sel.ts / *.sel.ts file — " +
-                        "add/reuse the selector there instead of a new one-off literal",
-                });
-            }
-        }
-        if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
-            warnings.push({
-                kind: "empty-verify",
-                file: rel,
-                detail: "defineAssertBlock's verify array is empty — an assert Block whose only job is checking will pass " +
-                    "trivially forever; fill in real Traits or remove the stub",
-            });
-        }
-    }
-    return warnings;
-}
-export function practiceKindLabel(kind) {
-    switch (kind) {
-        case "wildcard-checkpoint":
-            return "wildcard Checkpoint<string>";
-        case "assert-no-type-arg":
-            return "assert block missing type arg";
-        case "multi-input":
-            return "multiple inputs in one Block";
-        case "combined-action":
-            return "fill and click in one Block";
-        case "empty-verify":
-            return "empty verify — transition unconfirmed";
-        case "overcomplex-selector":
-            return "regex/XPath selector where a plain one would do";
-        case "inline-selector-should-use-sel-file":
-            return "inline selector — a _sel.ts/*.sel.ts file already exists here";
-        default: {
-            const _exhaustive = kind;
-            return _exhaustive;
-        }
-    }
-}
-export function formatPracticeWarnings(projectDir, warnings) {
-    const lines = [];
-    for (const w of warnings) {
-        lines.push(`waygraph practices: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
-    }
-    if (warnings.length === 0) {
-        lines.push(`waygraph practices: no bad-practice patterns under ${projectDir}`);
-    }
-    else {
-        lines.push(`waygraph practices: ${warnings.length} bad-practice warning${warnings.length === 1 ? "" : "s"}`);
-    }
-    return lines;
-}

package/dist/traverse-coverage.d.ts

@@ -1,59 +0,0 @@
-export interface TraverseCoverageReport {
-    version: 1;
-    generatedAt: string;
-    projectDir: string;
-    parallel: number;
-    /** Unique edge keys in the discovered graph (block names). */
-    edgesTotal: number;
-    /** Graph edges successfully walked this suite (after instance normalize). */
-    edgesHit: number;
-    /** edgesHit / edgesTotal (0 when total is 0). */
-    ratio: number;
-    /** Optional suite gate that was applied (0-1). */
-    minEdgeCoverage?: number;
-    /** true when minEdgeCoverage was set and ratio met it. */
-    coveragePass?: boolean;
-    /** Sorted graph edge keys that were hit. */
-    hit: string[];
-    /** Sorted graph edge keys never walked. */
-    missed: string[];
-    /** Raw worker hit keys (may include block::instanceId). */
-    rawHit?: string[];
-    workers?: Array<{
-        traverseId: string;
-        exitCode: number;
-        steps: number;
-        edgesHit: number;
-        leaf?: string;
-    }>;
-}
-/** Static graph edge key = Block runtime name. */
-export declare function edgeKeyFromGraphEdge(edge: {
-    block: string;
-}): string;
-/** Collect unique edge keys from a WaygraphGraph-like edges list. */
-export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
-    block: string;
-}>): string[];
-/**
- * Map a worker hit key onto the static graph key it covers.
- * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
- */
-export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<string>): string | null;
-/**
- * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
- * Returns 0-1 fraction, or null when unset/invalid.
- */
-export declare function parseMinEdgeCoverage(raw: unknown): number | null;
-export declare function buildCoverageReport(opts: {
-    projectDir: string;
-    parallel: number;
-    allEdgeKeys: readonly string[];
-    hitKeys: ReadonlySet<string> | readonly string[];
-    minEdgeCoverage?: number | null;
-    workers?: TraverseCoverageReport["workers"];
-}): TraverseCoverageReport;
-/** Greppable one-liner for agents/CI. */
-export declare function formatCoverageLine(report: TraverseCoverageReport): string;
-export declare function defaultCoverageOutPath(projectDir: string): string;
-export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse-coverage.js

@@ -1,127 +0,0 @@
-/**
- * Phase E: traverse edge coverage report + suite gate.
- * Coverage is independent of leaf PASS - a green leaf can still fail CI
- * when --min-edge-coverage is set and ratio is too low.
- *
- * Denominator = unique static graph edge block names (FF inners stay as their
- * own graph edges when discovered; RFC open Q deferred - no covered-via-prefix yet).
- * A hit of `block::instanceId` counts as covering `block`.
- */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-/** Static graph edge key = Block runtime name. */
-export function edgeKeyFromGraphEdge(edge) {
-    return edge.block;
-}
-/** Collect unique edge keys from a WaygraphGraph-like edges list. */
-export function collectGraphEdgeKeys(edges) {
-    const set = new Set();
-    for (const e of edges)
-        set.add(edgeKeyFromGraphEdge(e));
-    return [...set].sort();
-}
-/**
- * Map a worker hit key onto the static graph key it covers.
- * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
- */
-export function normalizeHitKey(hitKey, graphKeys) {
-    if (graphKeys.has(hitKey))
-        return hitKey;
-    const base = hitKey.includes("::") ? hitKey.slice(0, hitKey.indexOf("::")) : hitKey;
-    if (graphKeys.has(base))
-        return base;
-    return null;
-}
-/**
- * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
- * Returns 0-1 fraction, or null when unset/invalid.
- */
-export function parseMinEdgeCoverage(raw) {
-    if (raw === undefined || raw === null || raw === "")
-        return null;
-    if (typeof raw === "number" && Number.isFinite(raw)) {
-        if (raw < 0)
-            return null;
-        if (raw <= 1)
-            return raw;
-        if (raw <= 100)
-            return raw / 100;
-        return null;
-    }
-    if (typeof raw !== "string")
-        return null;
-    const t = raw.trim().toLowerCase();
-    if (!t)
-        return null;
-    if (t.endsWith("%")) {
-        const n = Number(t.slice(0, -1));
-        if (!Number.isFinite(n) || n < 0 || n > 100)
-            return null;
-        return n / 100;
-    }
-    const n = Number(t);
-    if (!Number.isFinite(n) || n < 0)
-        return null;
-    if (n <= 1)
-        return n;
-    if (n <= 100)
-        return n / 100;
-    return null;
-}
-export function buildCoverageReport(opts) {
-    const all = [...new Set(opts.allEdgeKeys)].sort();
-    const graphSet = new Set(all);
-    const rawList = Array.isArray(opts.hitKeys) ? [...opts.hitKeys] : [...opts.hitKeys];
-    const covered = new Set();
-    for (const raw of rawList) {
-        const n = normalizeHitKey(raw, graphSet);
-        if (n)
-            covered.add(n);
-    }
-    const hit = all.filter((k) => covered.has(k));
-    const missed = all.filter((k) => !covered.has(k));
-    const edgesTotal = all.length;
-    const edgesHit = hit.length;
-    const ratio = edgesTotal === 0 ? 0 : edgesHit / edgesTotal;
-    const min = opts.minEdgeCoverage != null && Number.isFinite(opts.minEdgeCoverage)
-        ? Math.min(1, Math.max(0, opts.minEdgeCoverage))
-        : undefined;
-    const coveragePass = min === undefined ? undefined : ratio + 1e-12 >= min;
-    const coverageExtra = min !== undefined && coveragePass !== undefined
-        ? { minEdgeCoverage: min, coveragePass }
-        : {};
-    return {
-        version: 1,
-        generatedAt: new Date().toISOString(),
-        projectDir: opts.projectDir,
-        parallel: opts.parallel,
-        edgesTotal,
-        edgesHit,
-        ratio: Math.round(ratio * 10000) / 10000,
-        ...coverageExtra,
-        hit,
-        missed,
-        rawHit: [...new Set(rawList)].sort(),
-        ...(opts.workers ? { workers: opts.workers } : {}),
-    };
-}
-/** Greppable one-liner for agents/CI. */
-export function formatCoverageLine(report) {
-    const pct = (report.ratio * 100).toFixed(1);
-    const minPart = report.minEdgeCoverage !== undefined
-        ? ` min=${(report.minEdgeCoverage * 100).toFixed(1)}%` +
-            (report.coveragePass === false
-                ? " FAIL"
-                : report.coveragePass === true
-                    ? " PASS"
-                    : "")
-        : "";
-    return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
-}
-export function defaultCoverageOutPath(projectDir) {
-    return join(projectDir, ".waygraph-traverse", "coverage.json");
-}
-export function writeCoverageReport(path, report) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");
-}