@cairnvibe/indexer 0.1.0

package/dist/init.js

@@ -0,0 +1,173 @@
+"use strict";
+// `cairn init` — scaffolds what it safely can, prints the rest. Only ever
+// writes NEW files (never touches an existing file, e.g. a layout the
+// user already has) — auto-editing arbitrary existing project files is
+// not something a generic CLI should do blind.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const ENV_TEMPLATE = `# Pick one LLM provider:
+ANTHROPIC_API_KEY=
+# or:
+# GROQ_API_KEYS=
+
+# Optional — voice (transcription/spoken answers/realtime conversation):
+DEEPGRAM_API_KEY=
+
+# Which "do" actions this deployment allows (comma-separated, empty = none):
+CAIRN_REGISTERED_ACTIONS=
+
+# Optional — caps what the agent can do regardless of registered actions:
+# explain | guide | act (default act) — see README.md's Voice & conversation section
+CAIRN_CAPABILITY=
+CAIRN_PERSONA=
+`;
+function writeIfAbsent(filePath, content, result) {
+    if (node_fs_1.default.existsSync(filePath)) {
+        result.filesSkipped.push(filePath);
+        return;
+    }
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    node_fs_1.default.writeFileSync(filePath, content);
+    result.filesWritten.push(filePath);
+}
+function runInit(dir) {
+    const absDir = node_path_1.default.resolve(dir);
+    const pkgPath = node_path_1.default.join(absDir, "package.json");
+    let pkg = {};
+    if (node_fs_1.default.existsSync(pkgPath)) {
+        try {
+            pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf8"));
+        }
+        catch {
+            // malformed package.json — fall through to the generic (non-Next) path
+        }
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const isNext = !!deps.next;
+    const hasAppDir = node_fs_1.default.existsSync(node_path_1.default.join(absDir, "app"));
+    const result = {
+        framework: !isNext ? "other" : hasAppDir ? "next-app-router" : "next-pages-router",
+        filesWritten: [],
+        filesSkipped: [],
+        nextSteps: [],
+    };
+    writeIfAbsent(node_path_1.default.join(absDir, ".env.example"), ENV_TEMPLATE, result);
+    if (result.framework === "next-app-router") {
+        writeIfAbsent(node_path_1.default.join(absDir, "app", "api", "copilot", "route.ts"), NEXT_APP_ROUTE, result);
+        result.nextSteps.push("1. cp .env.example .env and fill in your key(s).", "2. Add the widget to app/layout.tsx:", '   import { Copilot } from "@cairnvibe/sdk";', '   <Copilot registeredActions={[]} onDo={(action, target) => { /* run it */ }} />', "3. npx cairn build .   (scans this Next.js app's source)", "4. npm run dev, then ask it a question.");
+    }
+    else if (result.framework === "next-pages-router") {
+        writeIfAbsent(node_path_1.default.join(absDir, "pages", "api", "copilot.ts"), NEXT_PAGES_API_ROUTE, result);
+        result.nextSteps.push("1. cp .env.example .env and fill in your key(s).", "2. Add the widget to pages/_app.tsx:", '   import { Copilot } from "@cairnvibe/sdk";', '   <Copilot registeredActions={[]} onDo={(action, target) => { /* run it */ }} />', "3. npx cairn build .   (scans this Next.js app's source)", "4. npm run dev, then ask it a question.");
+    }
+    else {
+        writeIfAbsent(node_path_1.default.join(absDir, "cairn-server.cjs"), STANDALONE_SERVER, result);
+        result.nextSteps.push("1. cp .env.example .env and fill in your key(s).", "2. npm install express @cairnvibe/sdk @cairnvibe/core   (@cairnvibe/sdk isn't on npm yet — see README.md's Quick start for the file: install path)", "3. Start your app, then: npx cairn build http://localhost:PORT   (crawls the running app — works for any framework)", "4. node cairn-server.cjs   (the copilot backend, separate from your app's own server)", "5. Add this to your HTML, pointed at wherever cairn-server.cjs is running:", '   <script src="/cairn-widget.js"></script>', '   <cairn-widget endpoint="http://localhost:4000/api/copilot"></cairn-widget>', "   (copy node_modules/@cairnvibe/sdk/dist/cairn-widget.js into your app's static assets as cairn-widget.js)");
+    }
+    return result;
+}
+const NEXT_APP_ROUTE = `import fs from "node:fs";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { createCopilotHandler } from "@cairnvibe/sdk/server";
+import { ManifestSchema, type Manifest } from "@cairnvibe/core";
+
+function loadManifest(): Manifest {
+  const manifestPath = path.join(process.cwd(), "ui-manifest.json");
+  if (fs.existsSync(manifestPath)) {
+    return ManifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+  }
+  console.warn("[cairn] no ui-manifest.json — run \`npx cairn build .\` first. Serving an empty manifest.");
+  return { version: "1", commit: "unbuilt", generatedAt: new Date().toISOString(), pages: [], dead: [], conflicts: [] };
+}
+
+export async function POST(request: Request) {
+  const handler = createCopilotHandler(loadManifest(), {
+    provider: process.env.CAIRN_RUNTIME_PROVIDER === "anthropic" ? "anthropic" : "groq",
+    registeredActions: (process.env.CAIRN_REGISTERED_ACTIONS ?? "").split(",").map((a) => a.trim()).filter(Boolean),
+    capability: (process.env.CAIRN_CAPABILITY as "explain" | "guide" | "act" | undefined) ?? "act",
+    persona: process.env.CAIRN_PERSONA || undefined,
+  });
+  const body = await request.json().catch(() => null);
+  const result = await handler(body);
+  return NextResponse.json(result.body, { status: result.status });
+}
+`;
+const NEXT_PAGES_API_ROUTE = `import fs from "node:fs";
+import path from "node:path";
+import type { NextApiRequest, NextApiResponse } from "next";
+import { createCopilotHandler } from "@cairnvibe/sdk/server";
+import { ManifestSchema, type Manifest } from "@cairnvibe/core";
+
+function loadManifest(): Manifest {
+  const manifestPath = path.join(process.cwd(), "ui-manifest.json");
+  if (fs.existsSync(manifestPath)) {
+    return ManifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+  }
+  console.warn("[cairn] no ui-manifest.json — run \`npx cairn build .\` first. Serving an empty manifest.");
+  return { version: "1", commit: "unbuilt", generatedAt: new Date().toISOString(), pages: [], dead: [], conflicts: [] };
+}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== "POST") return res.status(405).end();
+  const copilotHandler = createCopilotHandler(loadManifest(), {
+    provider: process.env.CAIRN_RUNTIME_PROVIDER === "anthropic" ? "anthropic" : "groq",
+    registeredActions: (process.env.CAIRN_REGISTERED_ACTIONS ?? "").split(",").map((a) => a.trim()).filter(Boolean),
+    capability: (process.env.CAIRN_CAPABILITY as "explain" | "guide" | "act" | undefined) ?? "act",
+    persona: process.env.CAIRN_PERSONA || undefined,
+  });
+  const result = await copilotHandler(req.body);
+  res.status(result.status).json(result.body);
+}
+`;
+const STANDALONE_SERVER = `// cairn-server.cjs — generated by \`cairn init\`. Any backend framework
+// works here (createCopilotHandler is plain Node) — this is just the
+// simplest one to scaffold. Run: node cairn-server.cjs
+require("dotenv").config();
+const express = require("express");
+const fs = require("node:fs");
+const path = require("node:path");
+const { createCopilotHandler } = require("@cairnvibe/sdk/server");
+const { ManifestSchema } = require("@cairnvibe/core");
+
+function loadManifest() {
+  const manifestPath = path.join(__dirname, "ui-manifest.json");
+  if (fs.existsSync(manifestPath)) {
+    return ManifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+  }
+  console.warn("[cairn] no ui-manifest.json — run \`npx cairn build <your-app-url>\` first. Serving an empty manifest.");
+  return { version: "1", commit: "unbuilt", generatedAt: new Date().toISOString(), pages: [], dead: [], conflicts: [] };
+}
+
+const app = express();
+app.use(express.json());
+
+app.post("/api/copilot", async (req, res) => {
+  const handler = createCopilotHandler(loadManifest(), {
+    provider: process.env.CAIRN_RUNTIME_PROVIDER === "anthropic" ? "anthropic" : "groq",
+    registeredActions: (process.env.CAIRN_REGISTERED_ACTIONS ?? "").split(",").map((a) => a.trim()).filter(Boolean),
+    capability: process.env.CAIRN_CAPABILITY ?? "act",
+    persona: process.env.CAIRN_PERSONA || undefined,
+  });
+  const result = await handler(req.body);
+  res.status(result.status).json(result.body);
+});
+
+if (process.env.DEEPGRAM_API_KEY) {
+  const { createSpeakHandler } = require("@cairnvibe/sdk/speak-server");
+  const speak = createSpeakHandler({ apiKey: process.env.DEEPGRAM_API_KEY });
+  app.post("/api/copilot/speak", async (req, res) => {
+    const result = await speak(req.body?.text ?? "");
+    if ("error" in result.body) return res.status(result.status).json(result.body);
+    res.status(result.status).type(result.body.contentType).send(Buffer.from(result.body.audio));
+  });
+}
+
+const port = process.env.PORT || 4000;
+app.listen(port, () => console.log(\`Cairn backend listening on http://localhost:\${port}\`));
+`;

package/dist/key-rotator.js

@@ -0,0 +1,30 @@
+"use strict";
+// Round-robins across a comma-separated list of API keys (e.g. `GROQ_API_KEYS`)
+// so a batch of L3 describe calls can spread across several free-tier rate
+// limits instead of hammering a single key.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyRotator = void 0;
+class KeyRotator {
+    keys;
+    next = 0;
+    constructor(keys) {
+        if (keys.length === 0)
+            throw new Error("KeyRotator: at least one key is required");
+        this.keys = keys;
+    }
+    static fromEnvList(value) {
+        if (!value)
+            return null;
+        const keys = value
+            .split(",")
+            .map((k) => k.trim())
+            .filter(Boolean);
+        return keys.length > 0 ? new KeyRotator(keys) : null;
+    }
+    take() {
+        const key = this.keys[this.next % this.keys.length];
+        this.next += 1;
+        return key;
+    }
+}
+exports.KeyRotator = KeyRotator;

package/dist/l1-scan.js

@@ -0,0 +1,317 @@
+"use strict";
+// L1 — pure AST facts extraction. No LLM, no interpretation, no timestamps.
+// Same source in must produce byte-identical `RawFacts` out (see
+// scripts/check-determinism.sh). Every collection here is explicitly sorted
+// before being returned so directory-listing order can never leak in.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanL1 = scanL1;
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const routes_1 = require("./routes");
+const INTERACTIVE_TAGS = new Set(["button", "a", "form", "input"]);
+const DEFAULT_ROOTS = ["app", "components", "lib", "pages"];
+// Files the framework invokes directly rather than a page importing them —
+// they must count as reachability roots too, or L2 would flag every layout,
+// API route handler, and _app/_document as dead code.
+const APP_ROUTER_SPECIAL_FILE_RE = /^(layout|loading|error|not-found|template|default|route)\.(tsx|ts|jsx|js)$/;
+const PAGES_ROUTER_SPECIAL_FILE_RE = /^(_app|_document|_error|404|500)\.(tsx|ts|jsx|js)$/;
+// Custom components matching this convention (e.g. <PrimaryButton onClick=...>)
+// are treated as buttons — a heuristic, not real component resolution.
+const BUTTON_LIKE_COMPONENT_RE = /Button$/;
+function isFrameworkSpecialFile(absRoot, filePath) {
+    const rel = toPosix(node_path_1.default.relative(absRoot, filePath));
+    if (rel.startsWith("pages/api/"))
+        return true;
+    const base = node_path_1.default.basename(filePath);
+    if (rel.startsWith("pages/") && PAGES_ROUTER_SPECIAL_FILE_RE.test(base))
+        return true;
+    return APP_ROUTER_SPECIAL_FILE_RE.test(base);
+}
+/** Which route (if any) a source file defines, and via which router convention. Null for anything that isn't a page. */
+function deriveRoute(absRoot, filePath) {
+    const rel = toPosix(node_path_1.default.relative(absRoot, filePath));
+    if (rel.startsWith("app/")) {
+        return /(^|\/)page\.(tsx|ts)$/.test(rel) ? (0, routes_1.routeFromPagePath)(absRoot, filePath) : null;
+    }
+    if (rel.startsWith("pages/")) {
+        if (isFrameworkSpecialFile(absRoot, filePath))
+            return null;
+        return (0, routes_1.routeFromPagesRouterPath)(absRoot, filePath);
+    }
+    return null;
+}
+function isRelevant(filePath) {
+    return (!filePath.endsWith(".d.ts") &&
+        !/\.(test|spec)\.(ts|tsx)$/.test(filePath));
+}
+function toPosix(p) {
+    return p.split(node_path_1.default.sep).join("/");
+}
+function scanL1(rootDir) {
+    const absRoot = node_path_1.default.resolve(rootDir);
+    const project = new ts_morph_1.Project({
+        useInMemoryFileSystem: false,
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: {
+            jsx: ts_morph_1.ts.JsxEmit.ReactJSX,
+            allowJs: true,
+            esModuleInterop: true,
+            target: ts_morph_1.ts.ScriptTarget.ES2022,
+        },
+    });
+    const patterns = DEFAULT_ROOTS.map((dir) => toPosix(node_path_1.default.join(absRoot, dir, "**/*.{ts,tsx}")));
+    project.addSourceFilesAtPaths(patterns);
+    const allScannedFiles = project
+        .getSourceFiles()
+        .map((sf) => toPosix(node_path_1.default.relative(absRoot, sf.getFilePath())))
+        .filter(isRelevant)
+        .sort();
+    const pageFiles = project
+        .getSourceFiles()
+        .filter((sf) => isRelevant(sf.getFilePath()) && deriveRoute(absRoot, sf.getFilePath()) !== null);
+    const pages = pageFiles.map((pageFile) => {
+        const reachable = new Set();
+        const elements = [];
+        walkImports(pageFile, absRoot, reachable, elements, new Set());
+        return {
+            route: deriveRoute(absRoot, pageFile.getFilePath()),
+            file: toPosix(node_path_1.default.relative(absRoot, pageFile.getFilePath())),
+            reachableFiles: Array.from(reachable).sort(),
+            elements: elements.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file))),
+        };
+    });
+    pages.sort((a, b) => a.route.localeCompare(b.route));
+    const specialFiles = project
+        .getSourceFiles()
+        .filter((sf) => isRelevant(sf.getFilePath()) && isFrameworkSpecialFile(absRoot, sf.getFilePath()));
+    const frameworkReachable = new Set();
+    const frameworkElements = [];
+    const frameworkVisited = new Set();
+    for (const sf of specialFiles) {
+        // Framework files (layout.tsx, _app.tsx, ...) can have their own
+        // interactive elements — e.g. a nav bar — that render on every page but
+        // aren't reachable from any single page.tsx. Collected separately so L3
+        // can describe them once and the manifest can attach them to every page.
+        walkImports(sf, absRoot, frameworkReachable, frameworkElements, frameworkVisited);
+    }
+    return {
+        version: "1",
+        pages,
+        allScannedFiles,
+        frameworkReachableFiles: Array.from(frameworkReachable).sort(),
+        frameworkElements: frameworkElements.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file))),
+    };
+}
+function walkImports(sf, absRoot, reachableRel, elements, visitedAbs) {
+    const abs = sf.getFilePath();
+    if (visitedAbs.has(abs) || !isRelevant(abs))
+        return;
+    visitedAbs.add(abs);
+    const rel = toPosix(node_path_1.default.relative(absRoot, abs));
+    reachableRel.add(rel);
+    elements.push(...findInteractiveElements(sf, rel));
+    for (const imp of sf.getImportDeclarations()) {
+        const target = imp.getModuleSpecifierSourceFile();
+        if (!target)
+            continue; // unresolved: node_modules / path-alias we don't chase
+        if (target.getFilePath().includes("node_modules"))
+            continue;
+        walkImports(target, absRoot, reachableRel, elements, visitedAbs);
+    }
+}
+function findInteractiveElements(sf, relFile) {
+    const results = [];
+    const nodes = [
+        ...sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxOpeningElement),
+        ...sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxSelfClosingElement),
+    ];
+    for (const node of nodes) {
+        const rawTag = node.getTagNameNode().getText();
+        const lowerTag = rawTag.toLowerCase();
+        const attrs = node.getAttributes();
+        const onClickInit = getAttrInitializerNode(attrs, "onClick");
+        const onSubmitInit = getAttrInitializerNode(attrs, "onSubmit");
+        // Literal HTML elements first; then a couple of documented heuristics
+        // for common component conventions (next/link, *Button wrappers) — not
+        // full component resolution, see LATER.md.
+        let bucket = null;
+        if (INTERACTIVE_TAGS.has(lowerTag)) {
+            bucket = lowerTag;
+        }
+        else if (rawTag === "Link") {
+            bucket = "a";
+        }
+        else if (BUTTON_LIKE_COMPONENT_RE.test(rawTag) && onClickInit) {
+            bucket = "button";
+        }
+        if (!bucket)
+            continue;
+        const dataAi = getAttrStringValue(attrs, "data-ai");
+        const ariaLabel = getAttrStringValue(attrs, "aria-label");
+        const text = node.getKind() === ts_morph_1.SyntaxKind.JsxOpeningElement ? getElementText(node) : null;
+        let handlerCall = resolveHandlerCall(sf, onClickInit ?? onSubmitInit);
+        if (!handlerCall && rawTag === "Link") {
+            const href = getAttrStringValue(attrs, "href");
+            if (href)
+                handlerCall = `navigate ${href}`;
+        }
+        const line = node.getStartLineNumber();
+        // Raw text/aria-label, NOT slugified, when there's no data-ai — the
+        // runtime widget's findElement() ladder (element-ladder.ts) matches
+        // aria-label and text exactly as they appear on the element (case/
+        // whitespace-normalized, but never hyphenated). A slugified id like
+        // "new-invoice" would never match a button whose actual text is "New
+        // Invoice" — this was a real, live latent gap: crawl.ts's runtime-DOM
+        // analyzer never had it (built after this one, with the ladder's real
+        // matching rules in mind), and this fix brings the source-reading path
+        // in line with it. Only the last-resort synthetic fallback (no data-ai,
+        // no aria-label, no text at all — an icon-only button with no
+        // accessible name) still gets slugified; that case was already
+        // unfindable via the ladder regardless of formatting, so slugifying it
+        // doesn't make anything newly broken, just keeps the id readable.
+        const id = dataAi ?? text ?? ariaLabel ?? slugify(`${bucket}-${line}`);
+        results.push({
+            id,
+            tag: bucket,
+            dataAi,
+            ariaLabel,
+            text,
+            handlerCall,
+            file: relFile,
+            line,
+        });
+    }
+    return results;
+}
+function getAttrStringValue(attrs, name) {
+    for (const attr of attrs) {
+        if (!ts_morph_1.Node.isJsxAttribute(attr) || attr.getNameNode().getText() !== name)
+            continue;
+        const init = attr.getInitializer();
+        if (!init)
+            return "true";
+        if (ts_morph_1.Node.isStringLiteral(init))
+            return init.getLiteralText();
+        if (ts_morph_1.Node.isJsxExpression(init)) {
+            const inner = init.getExpression();
+            if (inner && ts_morph_1.Node.isStringLiteral(inner))
+                return inner.getLiteralText();
+        }
+    }
+    return null;
+}
+function getAttrInitializerNode(attrs, name) {
+    for (const attr of attrs) {
+        if (ts_morph_1.Node.isJsxAttribute(attr) && attr.getNameNode().getText() === name) {
+            return attr.getInitializer();
+        }
+    }
+    return undefined;
+}
+function getElementText(opening) {
+    const parent = opening.getParentIfKind(ts_morph_1.SyntaxKind.JsxElement);
+    if (!parent)
+        return null;
+    const texts = [];
+    for (const child of parent.getJsxChildren()) {
+        if (ts_morph_1.Node.isJsxText(child)) {
+            const t = child.getText().trim().replace(/\s+/g, " ");
+            if (t)
+                texts.push(t);
+        }
+    }
+    const joined = texts.join(" ").trim();
+    return joined.length > 0 ? joined : null;
+}
+function resolveHandlerCall(sf, initializer) {
+    if (!initializer)
+        return null;
+    let expr = initializer;
+    if (ts_morph_1.Node.isJsxExpression(expr)) {
+        expr = expr.getExpression();
+    }
+    if (!expr)
+        return null;
+    let target = expr;
+    if (ts_morph_1.Node.isIdentifier(expr)) {
+        const fn = findNamedFunctionLike(sf, expr.getText());
+        if (!fn)
+            return null;
+        target = fn;
+    }
+    return findApiCallIn(target);
+}
+/** Finds a function/arrow-function declared anywhere in the file (not just top-level — most handlers are nested inside the component). */
+function findNamedFunctionLike(sf, name) {
+    for (const fn of sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.FunctionDeclaration)) {
+        if (fn.getName() === name)
+            return fn;
+    }
+    for (const decl of sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration)) {
+        if (decl.getName() === name)
+            return decl;
+    }
+    return undefined;
+}
+function findApiCallIn(node) {
+    for (const call of node.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+        const calleeExpr = call.getExpression();
+        const exprText = calleeExpr.getText();
+        if (exprText === "fetch") {
+            const result = describeFetchCall(call);
+            if (result)
+                return result;
+        }
+        else if (ts_morph_1.Node.isPropertyAccessExpression(calleeExpr) && exprText.startsWith("axios.")) {
+            const result = describeAxiosCall(call);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+}
+function describeFetchCall(call) {
+    if (!ts_morph_1.Node.isCallExpression(call))
+        return null;
+    const args = call.getArguments();
+    const urlArg = args[0];
+    if (!urlArg)
+        return null;
+    const url = ts_morph_1.Node.isStringLiteral(urlArg) ? urlArg.getLiteralText() : urlArg.getText();
+    let method = "GET";
+    const optsArg = args[1];
+    if (optsArg && ts_morph_1.Node.isObjectLiteralExpression(optsArg)) {
+        const methodProp = optsArg.getProperty("method");
+        if (methodProp && ts_morph_1.Node.isPropertyAssignment(methodProp)) {
+            const init = methodProp.getInitializer();
+            if (init && ts_morph_1.Node.isStringLiteral(init))
+                method = init.getLiteralText().toUpperCase();
+        }
+    }
+    return `${method} ${url}`;
+}
+function describeAxiosCall(call) {
+    if (!ts_morph_1.Node.isCallExpression(call))
+        return null;
+    const calleeExpr = call.getExpression();
+    if (!ts_morph_1.Node.isPropertyAccessExpression(calleeExpr))
+        return null;
+    const method = calleeExpr.getName().toUpperCase();
+    const args = call.getArguments();
+    const urlArg = args[0];
+    if (!urlArg)
+        return null;
+    const url = ts_morph_1.Node.isStringLiteral(urlArg) ? urlArg.getLiteralText() : urlArg.getText();
+    return `${method} ${url}`;
+}
+function slugify(s) {
+    const slug = s
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, "");
+    return slug || "element";
+}

package/dist/l2-reachability.js

@@ -0,0 +1,116 @@
+"use strict";
+// L2 — reachability + conflict adjudication. Deterministic graph walk over
+// what L1 already found; the only non-source-derived input is git recency,
+// used purely as a tertiary tiebreaker (never changes the L1 `scan` output,
+// so it doesn't affect the determinism regression test).
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeL2 = computeL2;
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const ts_morph_1 = require("ts-morph");
+function computeL2(rootDir, facts) {
+    const absRoot = node_path_1.default.resolve(rootDir);
+    const reachable = new Set();
+    for (const page of facts.pages) {
+        for (const f of page.reachableFiles)
+            reachable.add(f);
+    }
+    for (const f of facts.frameworkReachableFiles)
+        reachable.add(f);
+    const dead = facts.allScannedFiles.filter((f) => !reachable.has(f)).sort();
+    const conflicts = findConflicts(absRoot, facts.allScannedFiles, reachable);
+    return { dead, conflicts };
+}
+function baseName(file) {
+    const name = node_path_1.default.basename(file).replace(/\.(tsx|ts)$/, "");
+    return name.replace(/(V\d+|Copy|Old)$/i, "").toLowerCase();
+}
+function isRoutingFile(file) {
+    return /^(page|layout|route|loading|error|not-found|template)\.(tsx|ts)$/.test(node_path_1.default.basename(file));
+}
+function findConflicts(absRoot, allFiles, reachable) {
+    const groups = new Map();
+    for (const f of allFiles) {
+        if (isRoutingFile(f))
+            continue;
+        const key = baseName(f);
+        const list = groups.get(key) ?? [];
+        list.push(f);
+        groups.set(key, list);
+    }
+    const inboundCounts = countInboundImports(absRoot, allFiles);
+    const conflicts = [];
+    for (const candidates of groups.values()) {
+        if (candidates.length < 2)
+            continue;
+        const scored = [...candidates].sort().map((file) => ({
+            file,
+            reachable: reachable.has(file),
+            inbound: inboundCounts.get(file) ?? 0,
+            recency: gitRecency(absRoot, file),
+        }));
+        scored.sort((a, b) => {
+            if (a.reachable !== b.reachable)
+                return a.reachable ? -1 : 1;
+            if (a.inbound !== b.inbound)
+                return b.inbound - a.inbound;
+            if (a.recency !== b.recency)
+                return b.recency - a.recency;
+            return a.file.localeCompare(b.file);
+        });
+        const winner = scored[0];
+        const loser = scored[1];
+        const reasonParts = [
+            winner.reachable ? "reachable from router" : "not reachable from router",
+            `${winner.inbound} inbound import(s)`,
+        ];
+        if (loser && !loser.reachable && loser.inbound === 0) {
+            reasonParts.push("other candidate has zero inbound imports and is unreachable");
+        }
+        conflicts.push({
+            candidates: scored.map((s) => s.file),
+            chose: winner.file,
+            reason: reasonParts.join("; "),
+            confidence: winner.reachable && winner.inbound > 0 ? 0.9 : winner.reachable ? 0.75 : 0.5,
+        });
+    }
+    conflicts.sort((a, b) => a.chose.localeCompare(b.chose));
+    return conflicts;
+}
+function countInboundImports(absRoot, allFiles) {
+    const project = new ts_morph_1.Project({
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { jsx: ts_morph_1.ts.JsxEmit.ReactJSX, allowJs: true, esModuleInterop: true },
+    });
+    for (const f of allFiles) {
+        project.addSourceFileAtPath(node_path_1.default.join(absRoot, f));
+    }
+    const counts = new Map(allFiles.map((f) => [f, 0]));
+    for (const sf of project.getSourceFiles()) {
+        for (const imp of sf.getImportDeclarations()) {
+            const target = imp.getModuleSpecifierSourceFile();
+            if (!target)
+                continue;
+            const rel = node_path_1.default.relative(absRoot, target.getFilePath()).split(node_path_1.default.sep).join("/");
+            if (counts.has(rel))
+                counts.set(rel, (counts.get(rel) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+function gitRecency(absRoot, file) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)("git", ["log", "-1", "--format=%ct", "--", file], {
+            cwd: absRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out ? parseInt(out, 10) : 0;
+    }
+    catch {
+        return 0;
+    }
+}