waygraph 0.15.53 → 0.16.0

package/dist/analysis/graph.js

@@ -1,7 +1,5 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, dirname, relative, resolve } from "node:path";
-import { matchBlocksSelect, } from "../blocks-select.js";
-import { exploreRoots, injectTaggedFile } from "../session/block-inject.js";
+import { relative } from "node:path";
+import { scanProject } from "../manifest/project.js";
 /**
  * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
  * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
@@ -17,127 +15,32 @@ export function toMermaid(graph) {
     }
     return lines.join("\n");
 }
-// ---------------------------------------------------------------------------
-// Discovery - deliberately self-contained (no import from cli.ts): cli.ts
-// runs its own main() unconditionally at module load, so it can't safely be
-// imported from a test (or from here) without also running the whole CLI.
-// These are small, stable duplicates of cli.ts's own discoverBlocks/
-// isBlockLike/isNavBlockMarked/importModule, not a shared abstraction -
-// simpler and lower-risk than a circular import between the two modules.
-// ---------------------------------------------------------------------------
-function walkDir(dir, pattern) {
-    const results = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
-                continue;
-            results.push(...walkDir(full, pattern));
-        }
-        else if (pattern.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-function discoverBlocks(projectDir) {
-    return walkDir(projectDir, /\.block\.ts$/);
-}
-function discoverFlows(projectDir) {
-    return walkDir(projectDir, /\.flow\.ts$/);
-}
-/** Block export ids a flow file uses: every identifier outside its import lines (a Block can sit in the array or in a local like `const AddShown = AddBlock.stubAfter(...)`). */
-function extractFlowBlockRefs(flowSrc) {
-    const body = flowSrc.replace(/^\s*import[\s\S]*?;\s*$/gm, "").replace(/\/\/.*$/gm, "");
-    return body.match(/[A-Za-z_$][\w$]*/g) ?? [];
-}
-function exportNameToBlockName(exportName) {
-    const base = exportName.replace(/Block$/, "");
-    return base
-        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
-        .toLowerCase();
-}
 /**
- * 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 async function findOrphanBlocks(projectDir) {
-    const blockFiles = discoverBlocks(projectDir);
-    const flowFiles = discoverFlows(projectDir);
-    const referenced = new Set();
-    for (const flowFile of flowFiles) {
-        for (const ref of extractFlowBlockRefs(readFileSync(flowFile, "utf-8"))) {
-            referenced.add(ref);
+    const scan = await scanProject(projectDir, { maps: false });
+    const used = new Set();
+    for (const { flow } of scan.flows) {
+        for (const info of flow.blocks()) {
+            used.add(info.name);
+            for (const target of Object.values(info.routes ?? {}))
+                if (target)
+                    used.add(target);
         }
     }
-    const pageMethodNames = new Set();
-    for (const file of blockFiles) {
-        let mod;
-        try {
-            mod = await importModule(file);
-        }
-        catch {
+    for (const b of scan.blocks) {
+        if (b.kind !== "page")
             continue;
-        }
-        for (const exported of Object.values(mod)) {
-            if (!exported || typeof exported !== "object")
-                continue;
-            if (exported.__waygraphKind !== "page")
-                continue;
-            const names = exported.__waygraphMethods;
-            if (Array.isArray(names)) {
-                for (const n of names)
-                    pageMethodNames.add(n);
-            }
-        }
+        for (const name of b.block.__waygraphMethods ?? [])
+            used.add(name);
     }
-    const orphans = [];
-    for (const file of blockFiles) {
-        const relFile = relative(projectDir, file);
-        const src = readFileSync(file, "utf-8");
-        const exportRe = /export\s+const\s+([A-Za-z_$][\w]*)\s*=/g;
-        let m;
-        while ((m = exportRe.exec(src)) !== null) {
-            const exportName = m[1];
-            if (referenced.has(exportName))
-                continue;
-            if (!/defineBlock|defineMethodBlock|defineActionBlock|definePageBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineNavClickBlock|defineMemNavBlock/.test(src))
-                continue;
-            // Arrival-only Page hubs are never orphans (even if import fails without tsx).
-            const assignSlice = src.slice(m.index, m.index + exportName.length + 80);
-            if (/=\s*definePageBlock\b/.test(assignSlice))
-                continue;
-            let block = exportNameToBlockName(exportName);
-            try {
-                const mod = await importModule(file);
-                const exported = mod[exportName];
-                if (isBlockLike(exported))
-                    block = exported.name;
-                if (exported &&
-                    typeof exported === "object" &&
-                    exported.__waygraphKind === "page") {
-                    continue;
-                }
-                if (pageMethodNames.has(block))
-                    continue;
-            }
-            catch {
-                // import may fail in partial projects - keep derived name
-            }
-            orphans.push({ exportName, block, file: relFile });
-        }
-    }
-    return orphans.sort((a, b) => a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName));
+    return scan.blocks
+        .filter((b) => b.kind !== "page" && !used.has(b.name))
+        .map((b) => ({ exportName: b.exportName, block: b.name, file: relative(projectDir, b.absFile) }))
+        .sort((a, b) => a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName));
 }
 /**
  * Shortest Block-name path between two Checkpoint tags using `discoverGraph`
@@ -193,270 +96,44 @@ export function findBlockPathDetailed(graph, fromTag, toTag) {
     return null;
 }
 /**
- * Same real, confirmed reload-caching bug `auto-explore.ts`'s own copy of
- * this function fixes (see its own comment) - `discoverGraph` (used for
- * `this.graph`/path-finding) and `loadBlockLibrary` (used for `this.library`/
- * the live menu) are two independent importers, each with their own
- * duplicate `importModule`, so each needed the same mtime-based cache-bust
- * fix separately - fixing only one left the other still serving a session's
- * `reloadLibrary()` a stale (or, for a brand-new file only ever discovered
- * through THIS path, silently absent) graph.
- */
-async function importModule(filePath) {
-    const resolved = resolve(filePath);
-    const url = new URL(`file://${resolved}`);
-    const mtimeMs = statSync(resolved).mtimeMs;
-    url.searchParams.set("t", String(mtimeMs));
-    return (await import(url.href));
-}
-function isBlockLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    if (typeof obj.name !== "string")
-        return false;
-    const instruction = obj.instruction;
-    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
-}
-/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
-function isNavBlockMarked(val) {
-    const kind = val.__waygraphKind;
-    return kind === "nav" || kind === "page";
-}
-/** Set by `defineAssertBlock` (non-enumerable) - see src/core.ts. */
-function isAssertBlockMarked(val) {
-    return val.__waygraphKind === "assert";
-}
-/**
- * Resolves `typeName` to every literal Checkpoint tag it can mean, within
- * one `*.states.ts` file's own source text - `type X = Checkpoint<"Tag">`
- * directly, or `type X = A | B | Checkpoint<"C">` (a union of other type
- * names and/or inline Checkpoint literals) recursively. A cycle or unknown
- * identifier just contributes no tags, rather than throwing - callers treat
- * an empty result as "couldn't resolve," not a crash.
- */
-function resolveCheckpointTags(statesSrc, typeName, seen = new Set()) {
-    if (seen.has(typeName))
-        return [];
-    seen.add(typeName);
-    const direct = new RegExp(`type\\s+${typeName}\\s*=\\s*Checkpoint<"([^"]+)">`).exec(statesSrc);
-    if (direct)
-        return [direct[1]];
-    const aliased = new RegExp(`type\\s+${typeName}\\s*=\\s*([^;]+);`).exec(statesSrc);
-    if (!aliased)
-        return [];
-    const tags = [];
-    for (const member of aliased[1].split("|").map((s) => s.trim()).filter(Boolean)) {
-        const inline = /^Checkpoint<"([^"]+)">$/.exec(member);
-        if (inline) {
-            tags.push(inline[1]);
-        }
-        else if (/^[A-Za-z_$][\w]*$/.test(member)) {
-            tags.push(...resolveCheckpointTags(statesSrc, member, seen));
-        }
-    }
-    return tags;
-}
-/**
- * Finds which file `blockFilePath`'s own `import type { ... }` statements
- * say `typeName` comes from, resolved to a real path on disk (`.js` ->
- * `.ts`, matching this project's own NodeNext import convention). Only
- * follows relative imports - `typeName` imported from a package (e.g.
- * `waygraph` itself, for `Checkpoint`) has no project file to read.
- */
-function findTypeSourceFile(blockFilePath, typeName) {
-    const src = readFileSync(blockFilePath, "utf-8");
-    const importRe = /import\s+type\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
-    let m;
-    while ((m = importRe.exec(src)) !== null) {
-        const names = m[1].split(",").map((s) => s.trim());
-        if (!names.includes(typeName))
-            continue;
-        const importPath = m[2];
-        if (!importPath.startsWith("."))
-            continue;
-        const resolved = join(dirname(blockFilePath), importPath.replace(/\.js$/, ".ts"));
-        if (existsSync(resolved))
-            return resolved;
-    }
-    return null;
-}
-/** `findTypeSourceFile` + `resolveCheckpointTags`, chained - `[]` on any failure along the way. */
-function resolveTypeToTags(blockFilePath, typeName) {
-    const statesFile = findTypeSourceFile(blockFilePath, typeName);
-    if (!statesFile)
-        return [];
-    return resolveCheckpointTags(readFileSync(statesFile, "utf-8"), typeName);
-}
-/**
- * Resolves one `defineBlock<In, Out>` generic argument, as captured by
- * `extractDefineBlockGenerics` - either a plain type identifier (goes
- * through `resolveTypeToTags`), an inline `Checkpoint<"Tag">` literal, or
- * the documented wildcard forms `Checkpoint<string>`/`Checkpoint<any>` (a
- * Block reused across several entry points, e.g. this project's own
- * `AddToCartBlock` - reachable from anywhere, same as a NavBlock's own `"*"`).
- */
-function resolveGenericArg(blockFilePath, arg) {
-    if (arg === "Checkpoint<string>" || arg === "Checkpoint<any>")
-        return ["*"];
-    const inline = /^Checkpoint<"([^"]+)">$/.exec(arg);
-    if (inline)
-        return [inline[1]];
-    return resolveTypeToTags(blockFilePath, arg);
-}
-/** Every `defineBlock` / `defineEffectBlock` / `defineMemEffectBlock` `<In, Out>` call site. */
-function extractDefineBlockGenerics(src) {
-    // Each argument is either a plain identifier or an inline `Checkpoint<...>`
-    // (its own angle brackets, so the outer defineX<...> pair alone won't
-    // balance correctly against a naive greedy match) - captured as a single
-    // alternation so both shapes come out of the same two capture groups.
-    // Effect helpers are TypeScript salt over defineBlock - same In/Out edges.
-    const arg = String.raw `(Checkpoint<[^>]*>|[A-Za-z_$][\w]*)`;
-    const re = new RegExp(String.raw `define(?:(?:Mem)?Effect|Method|Action)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
-    // Matches: defineBlock | defineMethodBlock | defineActionBlock | defineEffectBlock |
-    // defineMemEffectBlock (Nav / NavClick / Page use runtime markers, not this regex.)
-    const calls = [];
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        calls.push({ in: m[1], out: m[2] });
-    }
-    return calls;
-}
-/**
- * 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 async function discoverGraph(projectDir, opts) {
-    const select = opts?.blocksSelect;
+    const scan = await scanProject(projectDir, { blocksSelect: opts?.blocksSelect, inject: opts?.inject, flows: false });
+    return graphFromScan(scan);
+}
+/** The graph of an existing scan. */
+export function graphFromScan(scan) {
     const nodeTags = new Set();
     const edges = [];
-    const skipped = [];
-    const edgeSeen = new Set();
-    for (const root of exploreRoots(projectDir, opts?.inject)) {
-        let files = discoverBlocks(root);
-        // Glob/bare: drop files early. Regex needs block names — filter per export below.
-        if (select && select.kind !== "regex") {
-            files = files.filter((file) => matchBlocksSelect(select, {
-                relFile: relative(root, file).replace(/\\/g, "/"),
-            }));
+    const seen = new Set();
+    for (const b of scan.blocks) {
+        if (b.to.length === 0)
+            continue;
+        // Arrival-only Page hubs register the Checkpoint but are not a way to get there; a deep-linking Page is.
+        if (b.kind === "page" && b.block.__waygraphPageDeepLink !== true) {
+            for (const to of b.to)
+                nodeTags.add(to);
+            continue;
         }
-        for (const file of files) {
-            const relFile = injectTaggedFile(projectDir, root, relative(root, file).replace(/\\/g, "/"));
-            let mod;
-            try {
-                mod = await importModule(file);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                // Dual @playwright/test installs fail here - surface instead of empty graph.
-                if (/second time|playwright/i.test(msg)) {
-                    console.error(`waygraph graph: skip ${relFile}: ${msg.split("\n")[0]}`);
-                }
-                continue;
-            }
-            const src = readFileSync(file, "utf-8");
-            // Assumes source order matches export-object iteration order - true for
-            // this codebase's own convention of one Block per file; a file with
-            // several regular Blocks in an unusual order is a known edge case, not
-            // handled specially here.
-            const calls = extractDefineBlockGenerics(src);
-            let callIndex = 0;
-            for (const exported of Object.values(mod)) {
-                if (!isBlockLike(exported))
-                    continue;
-                const blockName = exported.name;
-                if (select &&
-                    !matchBlocksSelect(select, {
-                        relFile: relFile.replace(/\\/g, "/"),
-                        blockName,
-                    })) {
-                    continue;
-                }
-                if (isAssertBlockMarked(exported)) {
-                    try {
-                        // Same input-independent resolve() shape Nav/Page Blocks already
-                        // get this shortcut for - defineAssertBlock's own resolve() is
-                        // always `() => checkpoint(options.checkpoint)`, so no <In, Out>
-                        // generic needs to appear in source text for this to be found.
-                        const resolveFn = exported.instruction.resolve;
-                        const resolved = await resolveFn(undefined);
-                        const to = resolved.__state;
-                        nodeTags.add(to);
-                        // Self-loop by construction (defineAssertBlock is self-loop-only).
-                        edges.push({ block: blockName, file: relFile, from: to, to, kind: "action" });
-                    }
-                    catch {
-                        skipped.push({ block: blockName, file: relFile, reason: "assertBlock resolve() threw" });
-                    }
-                    continue;
-                }
-                if (isNavBlockMarked(exported)) {
-                    try {
-                        // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).
-                        const resolveFn = exported.instruction.resolve;
-                        const resolved = await resolveFn(undefined);
-                        const to = resolved.__state;
-                        nodeTags.add(to);
-                        // Arrival-only Page hubs register the Checkpoint node but do not emit
-                        // a Start-here edge (no deep link). Methods own the action edges.
-                        const isPage = exported.__waygraphKind === "page";
-                        const deepLink = !isPage ||
-                            exported.__waygraphPageDeepLink === true;
-                        if (deepLink) {
-                            // `from: [...]` on the Nav = only those Checkpoints; otherwise reachable from anywhere.
-                            const navFrom = exported.__waygraphNavFrom;
-                            for (const from of navFrom ?? ["*"]) {
-                                if (from !== "*")
-                                    nodeTags.add(from);
-                                edges.push({ block: blockName, file: relFile, from, to, kind: "nav" });
-                            }
-                        }
-                    }
-                    catch {
-                        skipped.push({ block: blockName, file: relFile, reason: "NavBlock/PageBlock resolve() threw" });
-                    }
-                    continue;
-                }
-                const call = calls[callIndex++];
-                if (!call) {
-                    skipped.push({
-                        block: blockName,
-                        file: relFile,
-                        reason: "no defineBlock/defineMethodBlock/defineEffectBlock<In, Out> generic call found",
-                    });
-                    continue;
-                }
-                const fromTags = resolveGenericArg(file, call.in);
-                const toTags = resolveGenericArg(file, call.out);
-                if (fromTags.length === 0 || toTags.length === 0) {
-                    const badName = fromTags.length === 0 ? call.in : call.out;
-                    skipped.push({ block: blockName, file: relFile, reason: `couldn't resolve "${badName}" to a Checkpoint tag` });
+        const kind = b.kind === "nav" || b.kind === "page" ? "nav" : "action";
+        for (const from of b.from) {
+            for (const to of b.to) {
+                if (from !== "*")
+                    nodeTags.add(from);
+                nodeTags.add(to);
+                const key = `${b.name}\0${from}\0${to}`;
+                if (seen.has(key))
                     continue;
-                }
-                for (const from of fromTags) {
-                    for (const to of toTags) {
-                        if (from !== "*")
-                            nodeTags.add(from);
-                        nodeTags.add(to);
-                        const key = `${blockName}\0${from}\0${to}`;
-                        if (edgeSeen.has(key))
-                            continue;
-                        edgeSeen.add(key);
-                        edges.push({ block: blockName, file: relFile, from, to, kind: "action" });
-                    }
-                }
+                seen.add(key);
+                edges.push({ block: b.name, file: b.file, from, to, kind });
             }
         }
     }
     return {
         nodes: [...nodeTags].sort().map((checkpoint) => ({ checkpoint })),
         edges,
-        skipped,
+        skipped: scan.skipped,
     };
 }

package/dist/analysis/map-check.js

@@ -13,46 +13,11 @@
  * Self-contained (no import from cli.ts), same reasoning as graph.ts's own
  * header comment: cli.ts runs main() unconditionally at module load.
  */
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join, dirname, relative, sep } from "node:path";
-import { pathToFileURL } from "node:url";
-function walkBlockFiles(dir) {
-    const results = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
-                continue;
-            results.push(...walkBlockFiles(full));
-        }
-        else if (/\.block\.ts$/.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-function isBlockLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    if (typeof obj.name !== "string")
-        return false;
-    const instruction = obj.instruction;
-    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
-}
-async function importModule(filePath) {
-    const url = pathToFileURL(filePath);
-    const mtimeMs = statSync(filePath).mtimeMs;
-    url.searchParams.set("t", String(mtimeMs));
-    return (await import(url.href));
-}
+import { importFresh, isBlockLike, walkDir } from "../manifest/scan.js";
+const walkBlockFiles = (dir) => walkDir(dir, /\.block\.ts$/);
+const importModule = importFresh;
 /**
  * `(group)` segments never appear in the real URL (Next.js route-group
  * convention this whole system is explicitly modeled on) - excluded from

package/dist/analysis/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
+export type PracticeKind = "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/analysis/practices-check.js

@@ -5,31 +5,29 @@
  */
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, relative } from "node:path";
-/** Every define*Block<In, Out> / <Out> generic list - args may themselves be Checkpoint<...>. */
-const BLOCK_GENERICS = /\bdefine(?:Method|Effect|MemEffect|Page|Nav|MemNav|NavClick|Action)Block\s*<\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*(?:,\s*((?:Checkpoint\s*<[^>]*>|[^,<>])+?)\s*)?>/g;
-/**
- * A wildcard Out (the Block's result is untyped). A wildcard In is fine - it's the documented
- * "reachable from anywhere" form (graph.ts treats it like a NavBlock's "*").
- */
-function hasWildcardOut(src) {
-    for (const m of src.matchAll(BLOCK_GENERICS)) {
-        const out = (m[2] ?? m[1]).trim();
-        if (/^Checkpoint\s*<\s*string\s*>$/.test(out))
-            return true;
-    }
-    return false;
-}
-/** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
-const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
+import { Node, SyntaxKind } from "ts-morph";
+import { parseSource } from "../manifest/source.js";
 /** 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*>/;
+/** A Method/Effect's route as written (`from: LoginPage, to: LoggedIn`), from the AST - a transition when they differ. */
+function routeAsWritten(file) {
+    const sf = parseSource(file);
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!/^define(Method|Effect)Block$/.test(call.getExpression().getText()))
+            continue;
+        const options = call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(options))
+            continue;
+        const text = (name) => {
+            const prop = options.getProperty(name);
+            return Node.isPropertyAssignment(prop) ? prop.getInitializerOrThrow().getText() : undefined;
+        };
+        const to = text("to");
+        if (to)
+            return { from: text("from") ?? "*", to };
+    }
+    return undefined;
+}
 /** `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. */
@@ -86,21 +84,6 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
         const rel = relative(projectDir, file).replace(/\\/g, "/");
         const src = readFileSync(file, "utf-8");
         const ignore = ignoredKindsForFile(src);
-        if (!isIgnored("wildcard-checkpoint", ignore) && hasWildcardOut(src)) {
-            warnings.push({
-                kind: "wildcard-checkpoint",
-                file: rel,
-                detail: "the Block's output is Checkpoint<string>, so its result is untyped — use a typed Checkpoint from " +
-                    "src/states/ (e.g. defineMethodBlock<LoginPage, LoggedIn>); a wildcard input is fine",
-            });
-        }
-        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);
@@ -119,15 +102,15 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                     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];
+            const route = routeAsWritten(file);
+            const isTransition = !!route && route.from !== route.to;
             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 ` +
+                    detail: `transition Block (${route.from} → ${route.to}) 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",
                 });
@@ -173,10 +156,6 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
 }
 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":

package/dist/cli/args.d.ts

@@ -0,0 +1,23 @@
+import { parseArgs } from "node:util";
+export interface OptionSpec {
+    type: "boolean" | "string";
+    multiple?: boolean;
+    /** How the value reads in the help: `<url>`, `N`. */
+    value?: string;
+    help: string;
+}
+export type OptionTable = Readonly<Record<string, OptionSpec>>;
+/** What a table parses to: a boolean, a string, or (multiple) a list, per flag; absent when not given. */
+export type ParsedOptions<T extends OptionTable> = {
+    [K in keyof T]?: T[K]["type"] extends "boolean" ? boolean : T[K] extends {
+        multiple: true;
+    } ? string[] : string;
+};
+export interface ParsedCommand<T extends OptionTable> {
+    values: ParsedOptions<T>;
+    positionals: string[];
+    tokens: ReturnType<typeof parseArgs>["tokens"] & {};
+}
+export declare function parseCommand<T extends OptionTable>(command: string, table: T, argv: string[]): ParsedCommand<T>;
+/** The table as aligned help lines (`--name <value>  help`). */
+export declare function helpLines(table: OptionTable, indent?: number): string;