waygraph 0.15.42 → 0.15.44

package/dist/analysis/coverage-gap.d.ts

@@ -0,0 +1,11 @@
+import type { BlockEntry } from "../auto-explore.js";
+/** Collect selector strings from NavClick blocks and Block/*Sel source files. */
+export declare function collectKnownInteractionSelectors(projectDir: string, library: {
+    navBlocks: BlockEntry[];
+}, inject?: string[]): string[];
+export interface UnmappedInteractionPayload {
+    knownPathnames: string[];
+    knownSelectors: string[];
+}
+/** Page-side: warn once per unmapped same-origin href or visible button. */
+export declare function unmappedInteractionsPageScript(payload: UnmappedInteractionPayload): void;

package/dist/analysis/coverage-gap.js

@@ -0,0 +1,119 @@
+/**
+ * Runtime coverage-gap helpers: detect live page links/buttons with no Block
+ * selector or NavBlock URL in the loaded library (surfaced via console.warn →
+ * `auto console`, same channel as unmapped href detection).
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { exploreRoots } from "../block-inject.js";
+const SELECTOR_LITERAL = /(?:locator|visible|click|fill|press|selector|getByRole)\(\s*['"`]([^'"`]+)['"`]/g;
+const HASH_ID = /#([a-zA-Z][\w-]*)/g;
+const DATA_TEST = /\[data-test(?:-id)?(?:=["'`][^"'`]+["'`])?\]/g;
+function walkBlockAndSelFiles(dir, acc = []) {
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        try {
+            const st = statSync(p);
+            if (st.isDirectory()) {
+                if (name === "node_modules" || name === "dist" || name.startsWith("."))
+                    continue;
+                walkBlockAndSelFiles(p, acc);
+            }
+            else if (/\.(block|sel)\.ts$/.test(name)) {
+                acc.push(p);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return acc;
+}
+/** Collect selector strings from NavClick blocks and Block/*Sel source files. */
+export function collectKnownInteractionSelectors(projectDir, library, inject) {
+    const out = new Set();
+    for (const entry of library.navBlocks) {
+        const click = entry.block
+            .__waygraphNavClick;
+        if (typeof click === "string")
+            out.add(click);
+    }
+    for (const root of exploreRoots(projectDir, inject)) {
+        for (const file of walkBlockAndSelFiles(root)) {
+            const src = readFileSync(file, "utf-8");
+            for (const re of [SELECTOR_LITERAL, HASH_ID, DATA_TEST]) {
+                re.lastIndex = 0;
+                let m;
+                while ((m = re.exec(src))) {
+                    const sel = m[0].startsWith("#") || m[0].startsWith("[") ? m[0] : (m[1] ?? m[0]);
+                    if (sel.startsWith("#") || sel.includes("data-test") || sel.includes("[")) {
+                        out.add(sel.startsWith("#") || sel.startsWith("[") ? sel : `#${sel}`);
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(out);
+}
+/** Page-side: warn once per unmapped same-origin href or visible button. */
+export function unmappedInteractionsPageScript(payload) {
+    const w = window;
+    w.__wgWarnedPaths ??= new Set();
+    w.__wgWarnedButtons ??= new Set();
+    const matchesKnown = (el, selectors) => {
+        for (const sel of selectors) {
+            try {
+                if (el.matches(sel))
+                    return true;
+                if (document.querySelector(sel) === el)
+                    return true;
+            }
+            catch {
+                /* invalid selector in library — skip */
+            }
+        }
+        return false;
+    };
+    const seenPaths = new Set();
+    for (const a of Array.from(document.querySelectorAll("a[href]"))) {
+        let url;
+        try {
+            url = new URL(a.getAttribute("href") || "", location.href);
+        }
+        catch {
+            continue;
+        }
+        if (url.origin !== location.origin)
+            continue;
+        const path = url.pathname;
+        if (seenPaths.has(path) || payload.knownPathnames.includes(path) || w.__wgWarnedPaths.has(path)) {
+            continue;
+        }
+        seenPaths.add(path);
+        w.__wgWarnedPaths.add(path);
+        console.warn(`[waygraph] unmapped nav link on this page: ${path} - no NavBlock covers this URL; add defineNavBlock`);
+    }
+    const buttonLike = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"]')).filter((el) => {
+        const style = window.getComputedStyle(el);
+        return style.visibility !== "hidden" && style.display !== "none";
+    });
+    for (const el of buttonLike) {
+        const id = el.id;
+        const dt = el.getAttribute("data-test") ?? el.getAttribute("data-testid");
+        const name = el.getAttribute("name");
+        const label = id
+            ? `#${id}`
+            : dt
+                ? `[data-test="${dt}"]`
+                : name
+                    ? `[name="${name}"]`
+                    : el.textContent?.trim().slice(0, 40) || el.tagName.toLowerCase();
+        const key = `${el.tagName}:${label}`;
+        if (w.__wgWarnedButtons.has(key))
+            continue;
+        if (matchesKnown(el, payload.knownSelectors))
+            continue;
+        w.__wgWarnedButtons.add(key);
+        console.warn(`[waygraph] unmapped button on this page: ${label} - no Method/NavClick Block selector matches; consider defineMethodBlock or defineNavClickBlock`);
+    }
+}

package/dist/analysis/graph.d.ts

@@ -0,0 +1,92 @@
+import { type BlocksSelect } from "../blocks-select.js";
+/**
+ * The state-machine shape `waygraph auto` discovers from a project's own
+ * Blocks - Checkpoints are nodes, Blocks are edges. Kept as plain data (not
+ * classes/functions) so it's trivially JSON-serializable for a script/agent
+ * reading `waygraph auto`'s stdout.
+ */
+export interface WaygraphNode {
+    checkpoint: string;
+}
+export interface WaygraphEdge {
+    /** The Block's own runtime `.name`. */
+    block: string;
+    /** Path the Block was discovered in, relative to the project root. */
+    file: string;
+    /** `"*"` for a NavBlock - reachable from anywhere, by design. */
+    from: string;
+    to: string;
+    kind: "nav" | "action";
+}
+export interface SkippedBlock {
+    block: string;
+    file: string;
+    reason: string;
+}
+export interface WaygraphGraph {
+    nodes: WaygraphNode[];
+    edges: WaygraphEdge[];
+    /** Blocks whose Out tag couldn't be statically resolved - not a crash, just excluded. */
+    skipped: SkippedBlock[];
+}
+/** A Block export that no `.flow.ts` defineFlow array references yet. */
+export interface OrphanBlock {
+    /** Export identifier in the `.block.ts` file. */
+    exportName: string;
+    /** Runtime Block `.name` when import succeeds; else derived from export. */
+    block: string;
+    /** Path relative to the project root. */
+    file: string;
+}
+/**
+ * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
+ * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
+ * renders as Mermaid's own `[*]` start marker, matching how a NavBlock's
+ * `from` already means "reachable from anywhere."
+ * @example console.log(toMermaid(graph))
+ */
+export declare function toMermaid(graph: WaygraphGraph): string;
+/**
+ * Blocks present on disk but never wired into a `.flow.ts` defineFlow array.
+ * Required before `chain auto` can build a path from the discovered graph -
+ * orphan Blocks are intentionally excluded from auto shorthand. Arrival-only
+ * Page hubs and Blocks listed on a Page's `methods` are not orphans.
+ */
+export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBlock[]>;
+/**
+ * Shortest Block-name path between two Checkpoint tags using `discoverGraph`
+ * edges. NavBlocks (`from: "*"`) count from any state.
+ */
+export declare function findBlockPath(graph: WaygraphGraph, fromTag: string, toTag: string): string[] | null;
+export interface BlockPathStep {
+    block: string;
+    /** The specific Checkpoint this hop's edge targets - NOT re-derivable by
+     * looking up `block` by name afterward, since a union-Out Block (e.g.
+     * "Union Out tags create duplicate edges for the same Block", see
+     * `discoverGraph`'s own comment above) can have several edges with the
+     * same `block` name but different `to` tags; only the specific edge BFS
+     * actually routed through here is correct. */
+    to: string;
+}
+/**
+ * Same BFS as `findBlockPath`, but returns each hop's specific edge (block
+ * name + the Checkpoint it targets), not just the block name - needed by any
+ * caller that must verify a step actually landed where the route intended,
+ * not just re-guess it afterward. `findBlockPath` itself is unchanged and
+ * still used wherever only the block-name sequence matters.
+ */
+export declare function findBlockPathDetailed(graph: WaygraphGraph, fromTag: string, toTag: string): BlockPathStep[] | null;
+/**
+ * Walks every `*.block.ts` file under `projectDir` and builds the app's own
+ * state graph. Shares the same in-process-import limitation `waygraph
+ * check` already has: a target project whose own `waygraph`/`playwright`
+ * are genuinely separate installs (not symlinked into this same
+ * node_modules resolution) can crash Playwright's own "second copy" guard
+ * on import - acceptable for an introspection command the same way it
+ * already is for `check`, unlike `chain`, which spawns a child process
+ * specifically because it also EXECUTES Blocks, not just imports them.
+ */
+export declare function discoverGraph(projectDir: string, opts?: {
+    blocksSelect?: BlocksSelect;
+    inject?: string[];
+}): Promise<WaygraphGraph>;