waygraph 0.15.43 → 0.15.45

package/dist/analysis/graph.js

@@ -0,0 +1,467 @@
+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";
+/**
+ * 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 function toMermaid(graph) {
+    const lines = ["stateDiagram-v2"];
+    for (const edge of graph.edges) {
+        const from = edge.from === "*" ? "[*]" : edge.from;
+        lines.push(`  ${from} --> ${edge.to} : ${edge.block}`);
+    }
+    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 listed inside any `defineFlow([...])` array in flow files. */
+function extractFlowBlockRefs(flowSrc) {
+    const refs = [];
+    const re = /defineFlow(?:<[\s\S]*?>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/g;
+    let m;
+    while ((m = re.exec(flowSrc)) !== null) {
+        for (const part of m[1].split(",")) {
+            const trimmed = part.trim().replace(/\/\/.*$/, "").trim();
+            const id = trimmed.split(/\s+/)[0];
+            if (!id || id === "start" || id === "end")
+                continue;
+            refs.push(id);
+        }
+    }
+    return refs;
+}
+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.
+ */
+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 pageMethodNames = new Set();
+    for (const file of blockFiles) {
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            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);
+            }
+        }
+    }
+    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));
+}
+/**
+ * Shortest Block-name path between two Checkpoint tags using `discoverGraph`
+ * edges. NavBlocks (`from: "*"`) count from any state.
+ */
+export function findBlockPath(graph, fromTag, toTag) {
+    if (fromTag === toTag)
+        return [];
+    const queue = [{ tag: fromTag, path: [] }];
+    const visited = new Set([fromTag]);
+    while (queue.length > 0) {
+        const { tag, path } = queue.shift();
+        for (const edge of graph.edges) {
+            if (edge.from !== tag && edge.from !== "*")
+                continue;
+            const nextPath = [...path, edge.block];
+            if (edge.to === toTag)
+                return nextPath;
+            if (!visited.has(edge.to)) {
+                visited.add(edge.to);
+                queue.push({ tag: edge.to, path: nextPath });
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 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 function findBlockPathDetailed(graph, fromTag, toTag) {
+    if (fromTag === toTag)
+        return [];
+    const queue = [{ tag: fromTag, path: [] }];
+    const visited = new Set([fromTag]);
+    while (queue.length > 0) {
+        const { tag, path } = queue.shift();
+        for (const edge of graph.edges) {
+            if (edge.from !== tag && edge.from !== "*")
+                continue;
+            const nextPath = [...path, { block: edge.block, to: edge.to }];
+            if (edge.to === toTag)
+                return nextPath;
+            if (!visited.has(edge.to)) {
+                visited.add(edge.to);
+                queue.push({ tag: edge.to, path: nextPath });
+            }
+        }
+    }
+    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/engine.ts. */
+function isNavBlockMarked(val) {
+    const kind = val.__waygraphKind;
+    return kind === "nav" || kind === "page";
+}
+/** Set by `defineAssertBlock` (non-enumerable) - see src/engine.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.
+ */
+export async function discoverGraph(projectDir, opts) {
+    const select = opts?.blocksSelect;
+    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, "/"),
+            }));
+        }
+        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) {
+                            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` });
+                    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" });
+                    }
+                }
+            }
+        }
+    }
+    return {
+        nodes: [...nodeTags].sort().map((checkpoint) => ({ checkpoint })),
+        edges,
+        skipped,
+    };
+}

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

@@ -0,0 +1,18 @@
+export interface MapViolation {
+    file: string;
+    block: string;
+    reason: string;
+}
+export interface MapNode {
+    block: string;
+    checkpoint: string | undefined;
+    file: string;
+    kind: "nav" | "page" | "other";
+}
+export interface MapCheckResult {
+    mapRoot: string;
+    hasMapDir: boolean;
+    nodes: MapNode[];
+    violations: MapViolation[];
+}
+export declare function checkMap(projectDir: string): Promise<MapCheckResult>;

package/dist/analysis/map-check.js

@@ -0,0 +1,140 @@
+/**
+ * `waygraph map` - enforcement for the Waygraph Map folder convention.
+ * Real, direct user correction: this is not just a naming preference, it's
+ * a forced structure. Requires `src/map/` to exist, and for every Nav/Page
+ * Block whose `url` is a plain string, the folder path (relative to
+ * `src/map/`, with `(group)` segments excluded - those are intentionally
+ * invisible in the real URL, same as Next.js route groups) must verbatim
+ * match the URL's own real pathname segments, in order. Catches exactly
+ * the class of bug a live session found: `(auth)/signin/` grouping a page
+ * whose real URL is `/signin`, not `/auth/signin` - a fabricated grouping
+ * that never matched the real site.
+ *
+ * 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 { 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));
+}
+/**
+ * `(group)` segments never appear in the real URL (Next.js route-group
+ * convention this whole system is explicitly modeled on) - excluded from
+ * the comparison, not just cosmetically ignored by discoverGraph.
+ *
+ * A leading-underscore segment (`_methods/`, same as Next.js's own private-
+ * folder convention) is the fixed machinery belonging to ONE endpoint - not
+ * a route segment of its own - excluded from the comparison for the same
+ * reason `(group)` is: real direct request answering "so i have clear
+ * distinction of endpoints vs block folders" - a bare (non-underscore,
+ * non-parenthesized) folder name always means a real child Checkpoint/URL
+ * segment, no exceptions, so `_methods/foo.block.ts` never gets mistaken
+ * for a sibling endpoint the way a bare `methods/` folder structurally
+ * could be.
+ */
+function realSegments(relPath) {
+    return dirname(relPath)
+        .split(sep)
+        .filter((s) => s !== "." && s !== "" && !/^\(.*\)$/.test(s) && !s.startsWith("_"));
+}
+export async function checkMap(projectDir) {
+    const mapRoot = join(projectDir, "src", "map");
+    if (!existsSync(mapRoot)) {
+        return { mapRoot, hasMapDir: false, nodes: [], violations: [] };
+    }
+    const files = walkBlockFiles(mapRoot);
+    const nodes = [];
+    const violations = [];
+    for (const file of files) {
+        const relFile = relative(projectDir, file);
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch (err) {
+            violations.push({
+                file: relFile,
+                block: "(import failed)",
+                reason: err instanceof Error ? err.message.split("\n")[0] : String(err),
+            });
+            continue;
+        }
+        for (const exported of Object.values(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            const waygraphKind = exported.__waygraphKind;
+            const kind = waygraphKind === "nav" ? "nav" : waygraphKind === "page" ? "page" : "other";
+            const navUrl = exported.__waygraphNavUrl;
+            let checkpoint;
+            const instruction = exported.instruction;
+            if (instruction?.resolve && typeof instruction.resolve === "function") {
+                try {
+                    const out = (await instruction.resolve(undefined));
+                    checkpoint = out?.__state;
+                }
+                catch {
+                    /* resolve() needing real input (a Method Block) - not position-defining, skip */
+                }
+            }
+            nodes.push({ block: exported.name, checkpoint, file: relFile, kind });
+            if (typeof navUrl !== "string")
+                continue; // only statically-urled Nav/Page Blocks are checkable
+            let pathname;
+            try {
+                pathname = new URL(navUrl).pathname;
+            }
+            catch {
+                continue; // a relative/templated URL - not verbatim-checkable
+            }
+            const urlSegments = pathname.split("/").filter(Boolean);
+            const folderSegments = realSegments(relative(mapRoot, file));
+            const matches = urlSegments.length === folderSegments.length && urlSegments.every((s, i) => s === folderSegments[i]);
+            if (!matches) {
+                violations.push({
+                    file: relFile,
+                    block: exported.name,
+                    reason: `folder path "${folderSegments.join("/")}" doesn't verbatim-match the real URL path ` +
+                        `"${urlSegments.join("/")}" (${navUrl}) - (group) segments are excluded from this comparison, ` +
+                        "everything else must match exactly, same as Next.js file-based routing",
+                });
+            }
+        }
+    }
+    return { mapRoot, hasMapDir: true, nodes, violations };
+}

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

@@ -0,0 +1,14 @@
+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[];