waygraph 0.15.53 → 0.16.0

package/README.md

@@ -6,11 +6,12 @@ worked - so a whole app becomes something you (or an AI agent) can walk, check,
 
 ```typescript
 // One Block = one action.  It says: start on LoginPage, end on LoggedIn, and prove it.
-export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoggedIn>({
+export const SubmitLoginBlock = defineMethodBlock({
   name: "submit-login",
+  from: LoginPage,
+  to: LoggedIn,
   instruction: {
     async act(page) { await page.locator(LoginSel.button).click(); },
-    resolve: () => checkpoint("LoggedIn"),
     verify: [Trait.url({ pathname: "/inventory.html" })],
   },
 });
@@ -107,7 +108,8 @@ names) still works and is fine for small projects, but the Map is where the tool
 ## Learn more
 
 - **[Docs site](https://deviate-dv8.github.io/waygraph/)** - guides and walkthroughs
-- **[Full reference](./docs/REFERENCE.md)** - every feature in detail (long)
+- **[Reference](./docs/reference/index.md)** - every feature in detail, one topic per page
+- **[Environment variables](./docs/env.md)** - every `WAYGRAPH_*` variable · **[Removed in 0.16.0](./docs/deprecated.md)** - each old form and what replaces it (`waygraph upgrade --codemod flows|checkpoints` converts a project)
 - **[Sauce Demo walkthrough](https://deviate-dv8.github.io/waygraph/saucedemo/)** - a worked example
 - Agent skills: `waygraph --skill` prints them (pilot, blind-pilot, convention)
 
@@ -119,4 +121,7 @@ npm install && npm run build
 npm run typecheck && npm test        # unit + Playwright suites
 ```
 
+Working on waygraph: [`AGENTS.md`](./AGENTS.md) (the rules, how to verify) and
+[`src/ARCHITECTURE.md`](./src/ARCHITECTURE.md) (where the code starts).
+
 MIT

package/bin/waygraph

@@ -6,7 +6,7 @@
  *   - macOS BSD `readlink` has no `-f` (GNU) -> "illegal option -- f" / broken bin
  *   - Windows npm expects a Node shebang for `.cmd` shims
  *
- * Still registers `tsx/esm` before `dist/cli.js` so consumer `.block.ts` /
+ * Still registers `tsx/esm` before `dist/cli/cli.js` so consumer `.block.ts` /
  * `.flow.ts` dynamic imports resolve the same as the old shell wrapper.
  */
 import { spawn } from "node:child_process";
@@ -28,7 +28,7 @@ try {
   process.exit(1);
 }
 
-const cli = join(pkgRoot, "dist", "cli.js");
+const cli = join(pkgRoot, "dist", "cli", "cli.js");
 const child = spawn(
   process.execPath,
   ["--import", tsxEsm, cli, ...process.argv.slice(2)],

package/dist/analysis/check.d.ts

@@ -0,0 +1,38 @@
+import type { PracticeWarning } from "./practices-check.js";
+import type { MapImportProblem } from "../manifest/map-imports.js";
+export interface FlowInfo {
+    file: string;
+    name: string;
+    valid: boolean;
+    error?: string;
+}
+export declare function validateFlows(projectDir: string): Promise<FlowInfo[]>;
+export interface CheckWarning {
+    file: string;
+    blockName: string;
+    exportName: string;
+}
+export interface SelWarning {
+    file: string;
+    blockName: string;
+    exportName: string;
+}
+/**
+ * Walks every `*.block.ts` file under `projectDir`, imports each to find its
+ * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
+ * that file's own source text for a navigation call. Warning only - never
+ * throws, never changes the caller's exit code on its own account (a Block
+ * file that fails to import for unrelated reasons is silently skipped here;
+ * `validate` is the command that reports import failures).
+ */
+export declare function checkProject(projectDir: string, opts?: {
+    noPractices?: boolean;
+}): Promise<{
+    navWarnings: CheckWarning[];
+    selWarnings: SelWarning[];
+    practiceWarnings: PracticeWarning[];
+}>;
+/** Imports in each packable map group that reach outside it (see `manifest/maps.ts`). */
+export declare function checkMapGroups(projectDir: string): (MapImportProblem & {
+    group: string;
+})[];

package/dist/analysis/check.js

@@ -0,0 +1,87 @@
+// `waygraph validate` and `waygraph check`: does every Flow file load, and do Blocks keep navigation and selectors where
+// they belong. Warnings only.
+import { basename, relative } from "node:path";
+import { importFresh, isBlockLike, walkDir } from "../manifest/scan.js";
+import { calls, parseSource } from "../manifest/source.js";
+import { collectPracticeWarnings } from "./practices-check.js";
+import { mapGroups } from "../manifest/maps.js";
+import { reportImportError } from "../manifest/project.js";
+import { mapGroupImportProblems } from "../manifest/map-imports.js";
+/** Anything runnable counts for `validate` (looser than the manifest, which also wants `.blocks()`). */
+function isFlowLike(val) {
+    return val !== null && typeof val === "object" && typeof val.run === "function";
+}
+/** Set by `defineNavBlock` (non-enumerable) - see engine/block/kinds/nav.ts. */
+function isNavBlockMarked(val) {
+    return val.__waygraphKind === "nav";
+}
+const NAV_METHODS = new Set(["page.goto", "page.reload", "page.goBack", "page.goForward"]);
+/**
+ * Selector-taking Trait factories. Called with a string literal (`Trait.visible("#some-id")`) instead of a Sel
+ * (`Trait.visible(SomeSel.thing)`) is an inline selector. `Trait.url(...)` takes a URLPatternInit, never a selector.
+ */
+const SELECTOR_TRAITS = new Set(["Trait.visible", "Trait.text", "textEquals", "visible"]);
+export async function validateFlows(projectDir) {
+    const files = walkDir(projectDir, /\.flow\.ts$/);
+    const results = [];
+    for (const file of files) {
+        try {
+            const mod = await importFresh(file);
+            for (const [exportName, exported] of Object.entries(mod)) {
+                if (isFlowLike(exported)) {
+                    results.push({ file, name: exportName, valid: true });
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ file, name: basename(file, ".ts"), valid: false, error: msg });
+        }
+    }
+    return results;
+}
+/**
+ * Walks every `*.block.ts` file under `projectDir`, imports each to find its
+ * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
+ * that file's own source text for a navigation call. Warning only - never
+ * throws, never changes the caller's exit code on its own account (a Block
+ * file that fails to import for unrelated reasons is silently skipped here;
+ * `validate` is the command that reports import failures).
+ */
+export async function checkProject(projectDir, opts) {
+    const files = walkDir(projectDir, /\.block\.ts$/);
+    const navWarnings = [];
+    const selWarnings = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await importFresh(file);
+        }
+        catch (err) {
+            reportImportError(relative(projectDir, file), err);
+            continue;
+        }
+        // The calls in the Block's own file, read from the AST: a comment or a string that mentions page.goto doesn't count.
+        const fileCalls = calls(parseSource(file));
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            // Nav-escape: NavBlocks are exempt (their generated act() is the one legitimate goto/click call site).
+            if (!isNavBlockMarked(exported) && fileCalls.some((c) => NAV_METHODS.has(c.callee))) {
+                navWarnings.push({ file, blockName: exported.name, exportName });
+            }
+            // Inline selector: every Block kind, NavBlocks too - a Nav's own `verify` array can inline a selector.
+            if (fileCalls.some((c) => c.literalFirstArg && SELECTOR_TRAITS.has(c.callee))) {
+                selWarnings.push({ file, blockName: exported.name, exportName });
+            }
+        }
+    }
+    const practiceWarnings = collectPracticeWarnings(projectDir, walkDir, {
+        disabled: opts?.noPractices === true,
+    });
+    return { navWarnings, selWarnings, practiceWarnings };
+}
+/** Imports in each packable map group that reach outside it (see `manifest/maps.ts`). */
+export function checkMapGroups(projectDir) {
+    return mapGroups(projectDir).flatMap((g) => mapGroupImportProblems(g).map((p) => ({ ...p, group: g.group })));
+}

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

@@ -1,4 +1,4 @@
-import type { BlockEntry } from "../session/auto-explore.js";
+import type { BlockEntry } from "../manifest/project.js";
 /** Collect selector strings from NavClick blocks and Block/*Sel source files. */
 export declare function collectKnownInteractionSelectors(projectDir: string, library: {
     navBlocks: BlockEntry[];

package/dist/analysis/coverage-gap.js

@@ -3,31 +3,16 @@
  * 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 "../session/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;
+import { exploreRoots } from "../manifest/roots.js";
+import { walkDir } from "../manifest/scan.js";
+import { parseSource, stringLiterals } from "../manifest/source.js";
+/** A colour like `{ color: "#fde68a" }` is not a selector. */
+const STYLE_PROPERTY = /colou?r|background|fill|stroke|border|shadow/i;
+/** A string that reads as a CSS selector for an element waygraph can find: an id, an attribute, or a data-test hook. */
+function isSelectorLiteral(value, property) {
+    if (property && STYLE_PROPERTY.test(property))
+        return false;
+    return value.includes("#") || value.startsWith("[") || value.includes("data-test");
 }
 /** Collect selector strings from NavClick blocks and Block/*Sel source files. */
 export function collectKnownInteractionSelectors(projectDir, library, inject) {
@@ -39,18 +24,10 @@ export function collectKnownInteractionSelectors(projectDir, library, inject) {
             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}`);
-                    }
-                }
-            }
+        for (const file of walkDir(root, /\.(block|sel)\.ts$/)) {
+            for (const { value, property } of stringLiterals(parseSource(file)))
+                if (isSelectorLiteral(value, property))
+                    out.add(value);
         }
     }
     return Array.from(out);

package/dist/analysis/flow-source.d.ts

@@ -0,0 +1,9 @@
+export declare function extractFlowNames(filePath: string): string[];
+/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
+export declare function blockExportToLabel(exportId: string): string;
+/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
+export declare function parseBlockImports(filePath: string): string[];
+/** Every `page.goto("...")` URL in a file, in source order. */
+export declare function extractGotos(filePath: string): string[];
+/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
+export declare function extractUrlTraits(filePath: string): string[];

package/dist/analysis/flow-source.js

@@ -0,0 +1,25 @@
+// What `waygraph list` / `nav` print, read from each file's AST without importing it.
+import { exportedNames, namedImportsFrom, objectArgProperty, parseSource, stringArgs } from "../manifest/source.js";
+export function extractFlowNames(filePath) {
+    return exportedNames(parseSource(filePath));
+}
+/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
+export function blockExportToLabel(exportId) {
+    const base = exportId.replace(/Block$/, "");
+    return base
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
+export function parseBlockImports(filePath) {
+    return namedImportsFrom(parseSource(filePath), (spec) => /\.block(\.js)?$/.test(spec));
+}
+/** Every `page.goto("...")` URL in a file, in source order. */
+export function extractGotos(filePath) {
+    return stringArgs(parseSource(filePath), (callee) => callee.endsWith(".goto"));
+}
+/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
+export function extractUrlTraits(filePath) {
+    return objectArgProperty(parseSource(filePath), (callee) => callee === "Trait.url", "pathname");
+}

package/dist/analysis/graph.d.ts

@@ -1,4 +1,5 @@
-import { type BlocksSelect } from "../blocks-select.js";
+import type { BlocksSelect } from "../manifest/select.js";
+import type { ProjectScan } from "../manifest/project.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
@@ -8,6 +9,7 @@ import { type BlocksSelect } from "../blocks-select.js";
 export interface WaygraphNode {
     checkpoint: string;
 }
+/** A move in the graph: a Block from one Checkpoint tag to another. */
 export interface WaygraphEdge {
     /** The Block's own runtime `.name`. */
     block: string;
@@ -18,18 +20,20 @@ export interface WaygraphEdge {
     to: string;
     kind: "nav" | "action";
 }
+/** A Block `waygraph graph` found but could not place in the graph, with the reason. */
 export interface SkippedBlock {
     block: string;
     file: string;
     reason: string;
 }
+/** The static graph of a project: Checkpoint nodes, Block edges, skipped and orphan Blocks. */
 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. */
+/** A Block export that no `.flow.ts` uses yet. */
 export interface OrphanBlock {
     /** Export identifier in the `.block.ts` file. */
     exportName: string;
@@ -47,10 +51,9 @@ export interface OrphanBlock {
  */
 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.
+ * Blocks the project exports but no flow plays. Read at runtime: every flow's `blocks()` (nested flows flattened, plus
+ * the Blocks a `branch()` routes to) against every scanned Block. Page hubs and the Blocks a Page lists as its
+ * `methods` are not orphans.
  */
 export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBlock[]>;
 /**
@@ -77,16 +80,12 @@ export interface BlockPathStep {
  */
 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.
+ * The project's state graph: Checkpoints are nodes, Blocks are edges. Built from the manifest scan, which reads each Block's
+ * route at runtime.
  */
 export declare function discoverGraph(projectDir: string, opts?: {
     blocksSelect?: BlocksSelect;
     inject?: string[];
 }): Promise<WaygraphGraph>;
+/** The graph of an existing scan. */
+export declare function graphFromScan(scan: ProjectScan): WaygraphGraph;