@mapled/cli 0.1.0 → 0.2.0

package/dist/scan.js

@@ -0,0 +1,1295 @@
+import { createRequire } from "node:module";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { targetFor } from "./manifest.js";
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".astro",
+    ".vercel",
+    ".turbo",
+    ".cache",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "storybook-static",
+    "public",
+]);
+const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".astro", ".svelte", ".vue"]);
+const TEST_FILE = /\.(test|spec|stories)\.[cm]?[jt]sx?$|(^|\/)__(tests|mocks)__\//;
+export const SDK_METHODS = new Set(["getRecords", "getRecord", "getRecordBySlug", "getSingle"]);
+const APP_METHODS = new Set(["list", "get"]);
+/** The repository's TypeScript, when it has one; the CLI ships none. */
+export function loadTypeScript(dir) {
+    try {
+        const req = createRequire(path.join(dir, "package.json"));
+        return req(req.resolve("typescript"));
+    }
+    catch {
+        return null;
+    }
+}
+async function listFiles(dir, max) {
+    const files = [];
+    let truncated = false;
+    const walk = async (rel) => {
+        if (files.length >= max) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(path.join(dir, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const e of entries) {
+            const next = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name) || (e.name.startsWith(".") && e.name !== "."))
+                    continue;
+                await walk(next);
+            }
+            else if (e.isFile()) {
+                if (!CODE_EXT.has(path.extname(e.name)) || e.name.endsWith(".d.ts") || TEST_FILE.test(next))
+                    continue;
+                if (files.length >= max) {
+                    truncated = true;
+                    return;
+                }
+                files.push(next);
+            }
+        }
+    };
+    await walk("");
+    return { files, truncated };
+}
+const PAGE_EXT = /\.(tsx|jsx|ts|js|mjs|mdx|md|astro|svelte|vue)$/;
+/** Next.js App Router segments: groups and slots vanish, params keep
+    the [param] form the manifest uses. */
+function appRoute(segments) {
+    const kept = [];
+    for (const s of segments) {
+        if (s.startsWith("_"))
+            return null;
+        if (s.startsWith("(") && s.endsWith(")"))
+            continue;
+        if (s.startsWith("@"))
+            continue;
+        kept.push(s);
+    }
+    return "/" + kept.join("/");
+}
+/** Pages Router / Astro / Nuxt style: index files name the directory. */
+function fileRoute(segments, file) {
+    const name = file.replace(PAGE_EXT, "");
+    if (name.startsWith("_"))
+        return null;
+    const parts = [...segments, ...(name === "index" ? [] : [name])];
+    if (parts.some((p) => p.startsWith("_")))
+        return null;
+    return "/" + parts.join("/");
+}
+/** Remix / React Router flat routes: dots nest, $param → [param]. */
+function remixRoute(file) {
+    const name = file.replace(PAGE_EXT, "");
+    if (name.startsWith("_") && name !== "_index")
+        return null;
+    if (name === "_index")
+        return "/";
+    const parts = name
+        .split(".")
+        .filter((p) => p !== "_index" && !(p.startsWith("_") && !p.startsWith("$")))
+        .map((p) => p.replace(/^\$(.+)$/, "[$1]").replace(/^\$$/, "[...splat]"));
+    return "/" + parts.join("/");
+}
+export function detectRoutes(files, framework) {
+    const pages = new Map();
+    const layouts = new Map();
+    const any = !framework;
+    for (const file of files) {
+        const parts = file.split("/");
+        const base = parts[parts.length - 1];
+        const dirs = parts.slice(0, -1);
+        const under = (root) => {
+            const i = dirs.indexOf(root);
+            if (i === -1 || (i > 0 && !(i === 1 && dirs[0] === "src")))
+                return null;
+            return dirs.slice(i + 1);
+        };
+        if (any || framework === "nextjs") {
+            const app = under("app");
+            if (app && /^page\.(tsx|jsx|ts|js|mdx|md)$/.test(base)) {
+                const route = appRoute(app);
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+            if (app && /^layout\.(tsx|jsx|ts|js)$/.test(base)) {
+                const route = appRoute(app);
+                if (route)
+                    layouts.set(file, route);
+                continue;
+            }
+            const pg = under("pages");
+            if (pg && !pg.includes("api") && pg[0] !== "api" && PAGE_EXT.test(base) && !/^_/.test(base)) {
+                if (dirs.includes("app") && !dirs.includes("pages"))
+                    continue;
+                const route = fileRoute(pg, base);
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+        }
+        if (any || framework === "astro") {
+            const i = dirs.indexOf("pages");
+            if (dirs[0] === "src" && i === 1 && /\.(astro|md|mdx|ts|js)$/.test(base)) {
+                const route = fileRoute(dirs.slice(2), base);
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+        }
+        if (any || framework === "sveltekit") {
+            if (dirs[0] === "src" && dirs[1] === "routes" && /^\+page\.(svelte|ts|js|server\.ts|server\.js)$/.test(base)) {
+                const route = appRoute(dirs.slice(2));
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+            if (dirs[0] === "src" && dirs[1] === "routes" && /^\+layout\./.test(base)) {
+                const route = appRoute(dirs.slice(2));
+                if (route)
+                    layouts.set(file, route);
+                continue;
+            }
+        }
+        if (any || framework === "nuxt") {
+            const i = dirs.indexOf("pages");
+            if ((i === 0 || (i === 1 && dirs[0] === "app")) && base.endsWith(".vue")) {
+                const route = fileRoute(dirs.slice(i + 1), base);
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+        }
+        if (any || framework === "remix") {
+            if (dirs[0] === "app" && dirs[1] === "routes" && dirs.length === 2 && /\.(tsx|jsx|ts|js)$/.test(base)) {
+                const route = remixRoute(base);
+                if (route)
+                    pages.set(file, route);
+                continue;
+            }
+        }
+    }
+    return { pages, layouts };
+}
+function stripJsonComments(text) {
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|[^:"'\\])\/\/.*$/gm, "$1")
+        .replace(/,(\s*[}\]])/g, "$1");
+}
+async function readAliases(dir) {
+    for (const name of ["tsconfig.json", "jsconfig.json"]) {
+        let raw;
+        try {
+            raw = await readFile(path.join(dir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        try {
+            const cfg = JSON.parse(stripJsonComments(raw));
+            const base = cfg.compilerOptions?.baseUrl ?? ".";
+            const out = [];
+            for (const [pattern, targets] of Object.entries(cfg.compilerOptions?.paths ?? {})) {
+                out.push({
+                    prefix: pattern.replace(/\*$/, ""),
+                    targets: targets.map((t) => path.posix.join(base, t.replace(/\*$/, ""))),
+                });
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+const RESOLVE_EXT = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs", ".mts", ".astro", ".svelte", ".vue"];
+function resolveImport(spec, fromFile, files, aliases) {
+    const candidates = [];
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+        candidates.push(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec)));
+    }
+    else if (spec.startsWith("/")) {
+        return null;
+    }
+    else {
+        for (const a of aliases) {
+            if (spec.startsWith(a.prefix)) {
+                for (const t of a.targets)
+                    candidates.push(path.posix.normalize(path.posix.join(t, spec.slice(a.prefix.length))));
+            }
+        }
+        if (candidates.length === 0 && spec.startsWith("@/")) {
+            candidates.push(path.posix.join("src", spec.slice(2)), spec.slice(2));
+        }
+        if (candidates.length === 0 && spec.startsWith("~/")) {
+            candidates.push(path.posix.join("src", spec.slice(2)), spec.slice(2));
+        }
+    }
+    for (const c of candidates) {
+        const clean = c.replace(/^\.\//, "");
+        if (files.has(clean))
+            return clean;
+        for (const ext of RESOLVE_EXT) {
+            if (files.has(clean + ext))
+                return clean + ext;
+            if (files.has(`${clean}/index${ext}`))
+                return `${clean}/index${ext}`;
+        }
+        const stripped = clean.replace(/\.(js|jsx|mjs)$/, "");
+        if (stripped !== clean) {
+            for (const ext of [".ts", ".tsx", ".mts"])
+                if (files.has(stripped + ext))
+                    return stripped + ext;
+        }
+    }
+    return null;
+}
+/* ---- the source of a file as TypeScript ---- */
+/** Script blocks of framework files, so the same parser reads them. */
+function scriptOf(file, text) {
+    const ext = path.extname(file);
+    if (ext === ".astro") {
+        const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+        return m ? m[1] : "";
+    }
+    if (ext === ".svelte" || ext === ".vue") {
+        const blocks = [];
+        const re = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
+        let m;
+        while ((m = re.exec(text)))
+            blocks.push(m[1]);
+        return blocks.join("\n");
+    }
+    return text;
+}
+class Analyzer {
+    ts;
+    operational;
+    constructor(ts, schema) {
+        this.ts = ts;
+        this.operational = new Set(schema.collections.filter((c) => c.mode === "operational").map((c) => c.key));
+    }
+    analyze(file, text) {
+        const ts = this.ts;
+        const kind = /\.(tsx|jsx|astro|svelte|vue)$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+        const source = ts.createSourceFile(file, scriptOf(file, text), ts.ScriptTarget.Latest, true, kind);
+        const a = {
+            file,
+            imports: new Map(),
+            specifiers: [],
+            reads: [],
+            wrappers: new Map(),
+            components: new Map(),
+            exports: new Map(),
+            source,
+            parseFailed: source.parseDiagnostics?.length ? true : false,
+        };
+        this.collectImports(a);
+        this.collectFunctions(a);
+        this.collectReads(a);
+        return a;
+    }
+    collectImports(a) {
+        const ts = this.ts;
+        for (const st of a.source.statements) {
+            if (ts.isImportDeclaration(st) && ts.isStringLiteral(st.moduleSpecifier)) {
+                const from = st.moduleSpecifier.text;
+                a.specifiers.push(from);
+                const clause = st.importClause;
+                if (!clause)
+                    continue;
+                if (clause.name)
+                    a.imports.set(clause.name.text, { from, name: "default" });
+                if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+                    for (const el of clause.namedBindings.elements) {
+                        a.imports.set(el.name.text, { from, name: (el.propertyName ?? el.name).text });
+                    }
+                }
+            }
+            else if (ts.isExportDeclaration(st) && st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier)) {
+                a.specifiers.push(st.moduleSpecifier.text);
+            }
+        }
+        const visit = (n) => {
+            if (ts.isCallExpression(n)) {
+                const callee = n.expression;
+                if ((callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === "require")) &&
+                    n.arguments[0] &&
+                    ts.isStringLiteralLike(n.arguments[0])) {
+                    a.specifiers.push(n.arguments[0].text);
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(a.source);
+    }
+    /** Top-level functions and arrow consts, with their export names. */
+    collectFunctions(a) {
+        const ts = this.ts;
+        const isExported = (n) => (ts.getCombinedModifierFlags(n) & ts.ModifierFlags.Export) !== 0;
+        for (const st of a.source.statements) {
+            if (ts.isFunctionDeclaration(st) && st.name) {
+                a.components.set(st.name.text, st);
+                if (isExported(st)) {
+                    a.exports.set((ts.getCombinedModifierFlags(st) & ts.ModifierFlags.Default) !== 0 ? "default" : st.name.text, st.name.text);
+                }
+            }
+            else if (ts.isVariableStatement(st)) {
+                for (const d of st.declarationList.declarations) {
+                    if (!ts.isIdentifier(d.name) || !d.initializer)
+                        continue;
+                    const init = unwrap(ts, d.initializer);
+                    if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+                        a.components.set(d.name.text, init);
+                        if (isExported(st))
+                            a.exports.set(d.name.text, d.name.text);
+                    }
+                }
+            }
+            else if (ts.isExportAssignment(st) && !st.isExportEquals) {
+                const expr = unwrap(ts, st.expression);
+                if (ts.isIdentifier(expr))
+                    a.exports.set("default", expr.text);
+                else if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
+                    a.components.set("default", expr);
+                    a.exports.set("default", "default");
+                }
+                else if (ts.isCallExpression(expr)) {
+                    // export default memo(Component) / dynamic(...) — take the first identifier argument
+                    const inner = expr.arguments.find((x) => ts.isIdentifier(x));
+                    if (inner && ts.isIdentifier(inner))
+                        a.exports.set("default", inner.text);
+                }
+            }
+            else if (ts.isExportDeclaration(st) && st.exportClause && ts.isNamedExports(st.exportClause) && !st.moduleSpecifier) {
+                for (const el of st.exportClause.elements)
+                    a.exports.set(el.name.text, (el.propertyName ?? el.name).text);
+            }
+        }
+    }
+    collectReads(a) {
+        const ts = this.ts;
+        const visit = (n) => {
+            if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+                const method = n.expression.name.text;
+                const arg = n.arguments[0];
+                const literal = arg && ts.isStringLiteralLike(arg) ? arg.text : null;
+                const isSdk = SDK_METHODS.has(method);
+                const isApp = APP_METHODS.has(method) && literal !== null && this.operational.has(literal);
+                if (isSdk || isApp) {
+                    if (literal === null) {
+                        a.reads.push(this.dynamicRead(a, method, n));
+                    }
+                    else {
+                        a.reads.push(this.traceRead(a, method, literal, n));
+                    }
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(a.source);
+    }
+    dynamicRead(a, method, call) {
+        const outer = outermostFunction(this.ts, call);
+        return {
+            method,
+            collection: "",
+            fields: new Set(),
+            fieldSites: new Map(),
+            component: functionName(this.ts, outer),
+            file: a.file,
+            bySlug: false,
+            wrapper: null,
+            handoffs: [],
+        };
+    }
+    traceRead(a, method, collection, call) {
+        const outer = outermostFunction(this.ts, call);
+        const read = {
+            method,
+            collection,
+            fields: new Set(),
+            fieldSites: new Map(),
+            component: functionName(this.ts, outer),
+            file: a.file,
+            bySlug: method === "getRecordBySlug",
+            wrapper: null,
+            handoffs: [],
+        };
+        const shape = method === "getRecords" || method === "list" ? "list-result" : "record";
+        const tracer = new Tracer(this.ts, a, read);
+        tracer.traceValue(call, shape);
+        // a helper that returns the read hands it to its callers
+        const outerName = functionName(this.ts, outer);
+        if (outer && outerName && tracer.returned) {
+            a.wrappers.set(outerName, { read, shape: tracer.returned });
+            read.wrapper = outerName;
+        }
+        return read;
+    }
+}
+function enclosingFunction(ts, n) {
+    let cur = n.parent;
+    while (cur) {
+        if (ts.isFunctionDeclaration(cur) || ts.isArrowFunction(cur) || ts.isFunctionExpression(cur) || ts.isMethodDeclaration(cur)) {
+            return cur;
+        }
+        cur = cur.parent;
+    }
+    return null;
+}
+/** The name a function is known by: its own, or the variable it is assigned to. */
+function functionName(ts, fn) {
+    if (!fn)
+        return null;
+    if ((ts.isFunctionDeclaration(fn) || ts.isFunctionExpression(fn) || ts.isMethodDeclaration(fn)) && fn.name && ts.isIdentifier(fn.name)) {
+        return fn.name.text;
+    }
+    let cur = fn.parent;
+    while (cur && (ts.isParenthesizedExpression(cur) || ts.isCallExpression(cur) || ts.isAsExpression(cur) || ts.isSatisfiesExpression(cur))) {
+        cur = cur.parent;
+    }
+    if (cur && ts.isVariableDeclaration(cur) && ts.isIdentifier(cur.name))
+        return cur.name.text;
+    if (cur && ts.isPropertyAssignment(cur) && ts.isIdentifier(cur.name))
+        return cur.name.text;
+    return null;
+}
+/** The top-level function a node sits in (a page component, a helper). */
+function outermostFunction(ts, n) {
+    let fn = enclosingFunction(ts, n);
+    let outer = fn;
+    while (fn) {
+        outer = fn;
+        fn = enclosingFunction(ts, fn);
+    }
+    return outer;
+}
+function unwrap(ts, n) {
+    let cur = n;
+    for (;;) {
+        if (ts.isParenthesizedExpression(cur) || ts.isAsExpression(cur) || ts.isNonNullExpression(cur) || ts.isSatisfiesExpression(cur) || ts.isTypeAssertionExpression(cur)) {
+            cur = cur.expression;
+        }
+        else if (ts.isAwaitExpression(cur)) {
+            cur = cur.expression;
+        }
+        else
+            return cur;
+    }
+}
+/** Follows a value of a known shape through the function it lives in:
+    variables, destructuring, `.data.field`, list callbacks, JSX props. */
+class Tracer {
+    ts;
+    a;
+    read;
+    returned = null;
+    budget = 400;
+    constructor(ts, a, read) {
+        this.ts = ts;
+        this.a = a;
+        this.read = read;
+    }
+    /** `expr` produces a value of `shape`: look at how it is used. */
+    traceValue(expr, shape, depth = 0) {
+        if (depth > 12 || this.budget-- <= 0)
+            return;
+        const ts = this.ts;
+        let node = expr;
+        // climb through await/parens/casts to the expression that uses it
+        while (node.parent &&
+            (ts.isAwaitExpression(node.parent) ||
+                ts.isParenthesizedExpression(node.parent) ||
+                ts.isAsExpression(node.parent) ||
+                ts.isNonNullExpression(node.parent) ||
+                ts.isSatisfiesExpression(node.parent) ||
+                ts.isTypeAssertionExpression(node.parent))) {
+            node = node.parent;
+        }
+        const parent = node.parent;
+        if (!parent)
+            return;
+        if (ts.isVariableDeclaration(parent) && parent.initializer && unwrapIs(ts, parent.initializer, node)) {
+            this.traceBinding(parent.name, shape, depth + 1);
+            return;
+        }
+        if (ts.isReturnStatement(parent) || (ts.isArrowFunction(parent) && parent.body === node)) {
+            this.returned = this.returned ?? shape;
+            return;
+        }
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === node) {
+            this.traceAccess(parent, parent.name.text, shape, depth + 1);
+            return;
+        }
+        if (ts.isElementAccessExpression(parent) && parent.expression === node && ts.isStringLiteralLike(parent.argumentExpression)) {
+            this.traceAccess(parent, parent.argumentExpression.text, shape, depth + 1);
+            return;
+        }
+        if (ts.isElementAccessExpression(parent) && parent.expression === node && shape === "records") {
+            this.traceValue(parent, "record", depth + 1);
+            return;
+        }
+        if (ts.isJsxExpression(parent) && parent.parent && ts.isJsxAttribute(parent.parent)) {
+            this.handoff(parent.parent, shape);
+            return;
+        }
+        if (ts.isJsxSpreadAttribute(parent)) {
+            this.handoff(parent, shape);
+            return;
+        }
+        if (ts.isSpreadAssignment(parent) && shape === "data") {
+            // { ...post.data } — the fields flow into an object we don't follow
+            return;
+        }
+        if (ts.isBinaryExpression(parent) && (parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || parent.operatorToken.kind === ts.SyntaxKind.BarBarToken) && parent.left === node) {
+            this.traceValue(parent, shape, depth + 1);
+            return;
+        }
+        if (ts.isConditionalExpression(parent) && parent.condition !== node) {
+            this.traceValue(parent, shape, depth + 1);
+            return;
+        }
+        if (ts.isForOfStatement(parent) && parent.expression === node && shape === "records") {
+            if (ts.isVariableDeclarationList(parent.initializer) && parent.initializer.declarations[0]) {
+                this.traceBinding(parent.initializer.declarations[0].name, "record", depth + 1);
+            }
+            return;
+        }
+        if (ts.isCallExpression(parent) && parent.expression === node)
+            return;
+        if (ts.isCallExpression(parent) && parent.arguments.includes(node)) {
+            // passed to a local helper: follow its parameter
+            const callee = unwrap(ts, parent.expression);
+            if (ts.isIdentifier(callee)) {
+                const fn = this.a.components.get(callee.text);
+                const index = parent.arguments.indexOf(node);
+                const param = fn?.parameters[index];
+                if (fn && param)
+                    this.traceBinding(param.name, shape, depth + 1);
+            }
+            return;
+        }
+    }
+    traceAccess(access, name, shape, depth) {
+        switch (shape) {
+            case "list-result":
+                if (name === "records")
+                    this.traceValue(access, "records", depth);
+                return;
+            case "records":
+                if (name === "map" || name === "forEach" || name === "filter" || name === "flatMap" || name === "some" || name === "every" || name === "find" || name === "findLast") {
+                    const call = access.parent;
+                    if (this.ts.isCallExpression(call) && call.expression === access) {
+                        const cb = call.arguments[0] ? unwrap(this.ts, call.arguments[0]) : undefined;
+                        if (cb && (this.ts.isArrowFunction(cb) || this.ts.isFunctionExpression(cb)) && cb.parameters[0]) {
+                            this.traceBinding(cb.parameters[0].name, "record", depth);
+                        }
+                        if ((name === "find" || name === "findLast") && call)
+                            this.traceValue(call, "record", depth);
+                        if (name === "filter")
+                            this.traceValue(call, "records", depth);
+                    }
+                }
+                if (name === "at") {
+                    const call = access.parent;
+                    if (this.ts.isCallExpression(call))
+                        this.traceValue(call, "record", depth);
+                }
+                return;
+            case "record":
+                if (name === "data")
+                    this.traceValue(access, "data", depth);
+                return;
+            case "data":
+                this.field(name);
+                return;
+        }
+    }
+    field(name) {
+        this.read.fields.add(name);
+        if (!this.read.fieldSites.has(name))
+            this.read.fieldSites.set(name, { component: this.read.component, file: this.read.file });
+    }
+    /** A variable or parameter now holds a value of `shape`. */
+    traceBinding(name, shape, depth) {
+        const ts = this.ts;
+        if (depth > 12 || this.budget-- <= 0)
+            return;
+        if (ts.isIdentifier(name)) {
+            this.traceIdentifier(name, shape, depth);
+            return;
+        }
+        if (ts.isObjectBindingPattern(name)) {
+            for (const el of name.elements) {
+                if (el.dotDotDotToken)
+                    continue;
+                const prop = el.propertyName ? propName(ts, el.propertyName) : ts.isIdentifier(el.name) ? el.name.text : null;
+                if (prop === null)
+                    continue;
+                switch (shape) {
+                    case "list-result":
+                        if (prop === "records")
+                            this.traceBinding(el.name, "records", depth + 1);
+                        break;
+                    case "record":
+                        if (prop === "data")
+                            this.traceBinding(el.name, "data", depth + 1);
+                        break;
+                    case "data":
+                        this.field(prop);
+                        break;
+                    case "records":
+                        break;
+                }
+            }
+            return;
+        }
+        if (ts.isArrayBindingPattern(name) && shape === "records") {
+            for (const el of name.elements)
+                if (ts.isBindingElement(el))
+                    this.traceBinding(el.name, "record", depth + 1);
+        }
+    }
+    traceIdentifier(id, shape, depth) {
+        const ts = this.ts;
+        const scope = scopeOf(ts, id);
+        const visit = (n) => {
+            if (this.budget <= 0)
+                return;
+            if (ts.isIdentifier(n) && n !== id && n.text === id.text && !isDeclarationName(ts, n) && !isPropertyName(ts, n)) {
+                this.traceValue(n, shape, depth + 1);
+                return;
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(scope);
+    }
+    handoff(attr, shape) {
+        const ts = this.ts;
+        const element = attr.parent.parent;
+        let tagName = null;
+        if (ts.isJsxOpeningElement(element) || ts.isJsxSelfClosingElement(element))
+            tagName = element.tagName;
+        if (!tagName || !ts.isIdentifier(tagName))
+            return;
+        const first = tagName.text.charAt(0);
+        if (first === first.toLowerCase())
+            return; // an HTML element: nothing to trace into
+        const prop = ts.isJsxAttribute(attr) ? propName(ts, attr.name) : null;
+        this.read.handoffs.push({ component: tagName.text, prop, shape });
+    }
+}
+function unwrapIs(ts, expr, node) {
+    let cur = expr;
+    for (;;) {
+        if (cur === node)
+            return true;
+        if (ts.isAwaitExpression(cur) || ts.isParenthesizedExpression(cur) || ts.isAsExpression(cur) || ts.isNonNullExpression(cur) || ts.isSatisfiesExpression(cur) || ts.isTypeAssertionExpression(cur)) {
+            cur = cur.expression;
+        }
+        else
+            return false;
+    }
+}
+function propName(ts, n) {
+    if (ts.isIdentifier(n) || ts.isPrivateIdentifier(n))
+        return n.text;
+    if (ts.isStringLiteralLike(n) || ts.isNumericLiteral(n))
+        return n.text;
+    if (ts.isJsxNamespacedName(n))
+        return n.name.text;
+    return null;
+}
+function isDeclarationName(ts, id) {
+    const p = id.parent;
+    return ((ts.isVariableDeclaration(p) && p.name === id) ||
+        (ts.isParameter(p) && p.name === id) ||
+        (ts.isBindingElement(p) && p.name === id) ||
+        (ts.isFunctionDeclaration(p) && p.name === id) ||
+        ts.isImportSpecifier(p) ||
+        ts.isImportClause(p));
+}
+function isPropertyName(ts, id) {
+    const p = id.parent;
+    return ((ts.isPropertyAccessExpression(p) && p.name === id) ||
+        (ts.isPropertyAssignment(p) && p.name === id) ||
+        (ts.isBindingElement(p) && p.propertyName === id) ||
+        (ts.isJsxAttribute(p) && p.name === id) ||
+        (ts.isPropertySignature(p) && p.name === id));
+}
+/** The function body (or the file) an identifier is visible in. */
+function scopeOf(ts, id) {
+    let cur = id.parent;
+    while (cur) {
+        if (ts.isFunctionDeclaration(cur) || ts.isArrowFunction(cur) || ts.isFunctionExpression(cur) || ts.isMethodDeclaration(cur)) {
+            // a parameter or a variable of this function is visible in its body
+            return cur.body ?? cur;
+        }
+        if (ts.isSourceFile(cur))
+            return cur;
+        cur = cur.parent;
+    }
+    return id.getSourceFile();
+}
+/** JavaScript tokens: identifiers, string literals and punctuation, with
+    comments and template bodies dropped. A regex literal after an
+    operator is skipped; JSX text is read as code, so an apostrophe in
+    prose can swallow a stretch — a false negative, never a crash. */
+export function tokenize(text) {
+    const out = [];
+    let i = 0;
+    const n = text.length;
+    const REGEX_BEFORE = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "return", "typeof", "=>"]);
+    while (i < n) {
+        const c = text[i];
+        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            i++;
+            continue;
+        }
+        if (c === "/" && text[i + 1] === "/") {
+            while (i < n && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? n : end + 2;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`") {
+            let j = i + 1;
+            let value = "";
+            while (j < n && text[j] !== c) {
+                if (text[j] === "\\") {
+                    value += text[j + 1] ?? "";
+                    j += 2;
+                    continue;
+                }
+                if (c === "`" && text[j] === "$" && text[j + 1] === "{") {
+                    // a substitution: skip to its closing brace (one level)
+                    let depth = 1;
+                    j += 2;
+                    while (j < n && depth > 0) {
+                        if (text[j] === "{")
+                            depth++;
+                        else if (text[j] === "}")
+                            depth--;
+                        j++;
+                    }
+                    value += "${}";
+                    continue;
+                }
+                if (c !== "`" && text[j] === "\n")
+                    break;
+                value += text[j];
+                j++;
+            }
+            out.push({ kind: "string", value: c === "`" && value.includes("${}") ? "${}" : value });
+            i = j + 1;
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(c)) {
+            let j = i + 1;
+            while (j < n && /[A-Za-z0-9_$]/.test(text[j]))
+                j++;
+            out.push({ kind: "ident", value: text.slice(i, j) });
+            i = j;
+            continue;
+        }
+        if (c === "/") {
+            const prev = out[out.length - 1];
+            if (!prev || (prev.kind === "punct" && REGEX_BEFORE.has(prev.value)) || (prev.kind === "ident" && REGEX_BEFORE.has(prev.value))) {
+                let j = i + 1;
+                let inClass = false;
+                while (j < n && (inClass || text[j] !== "/") && text[j] !== "\n") {
+                    if (text[j] === "\\")
+                        j++;
+                    else if (text[j] === "[")
+                        inClass = true;
+                    else if (text[j] === "]")
+                        inClass = false;
+                    j++;
+                }
+                j++;
+                while (j < n && /[a-z]/.test(text[j]))
+                    j++; // flags
+                i = j;
+                continue;
+            }
+        }
+        if (c === "=" && text[i + 1] === ">") {
+            out.push({ kind: "punct", value: "=>" });
+            i += 2;
+            continue;
+        }
+        out.push({ kind: "punct", value: c });
+        i++;
+    }
+    return out;
+}
+function analyzeTokens(file, text, operational) {
+    const tokens = tokenize(scriptOf(file, text));
+    const specifiers = [];
+    const reads = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.kind === "ident" && (t.value === "from" || t.value === "import" || t.value === "require")) {
+            const next = tokens[i + 1];
+            const after = tokens[i + 2];
+            if (next?.kind === "string")
+                specifiers.push(next.value);
+            else if (next?.kind === "punct" && next.value === "(" && after?.kind === "string")
+                specifiers.push(after.value);
+            continue;
+        }
+        if (t.kind === "punct" && t.value === "." && tokens[i + 1]?.kind === "ident" && tokens[i + 2]?.kind === "punct" && tokens[i + 2].value === "(") {
+            const method = tokens[i + 1].value;
+            const arg = tokens[i + 3];
+            const isSdk = SDK_METHODS.has(method);
+            const literal = arg?.kind === "string" && arg.value !== "${}" ? arg.value : null;
+            const isApp = APP_METHODS.has(method) && literal !== null && operational.has(literal);
+            if (!isSdk && !isApp)
+                continue;
+            reads.push({
+                method,
+                collection: literal ?? "",
+                fields: new Set(),
+                fieldSites: new Map(),
+                component: null,
+                file,
+                bySlug: method === "getRecordBySlug",
+                wrapper: null,
+                handoffs: [],
+            });
+        }
+    }
+    return { file, specifiers, reads };
+}
+/* ---- putting it together ---- */
+export function routeKey(route) {
+    const stripped = route.replace(/^\/+/, "");
+    const key = stripped === "" ? "index" : stripped;
+    return /^[A-Za-z0-9]/.test(key) ? key : `p${key}`;
+}
+const isSitePage = (route) => route.startsWith("/");
+export async function scanRepository(dir, opts) {
+    const notes = [];
+    const max = opts.maxFiles ?? 4000;
+    const { files, truncated } = await listFiles(dir, max);
+    if (truncated)
+        notes.push(`Only the first ${max} source files were read.`);
+    const fileSet = new Set(files);
+    const aliases = await readAliases(dir);
+    const framework = opts.framework ?? null;
+    const routes = detectRoutes(files, framework);
+    const schemaIndex = new Map(opts.schema.collections.map((c) => [c.key, c]));
+    const operational = new Set(opts.schema.collections.filter((c) => c.mode === "operational").map((c) => c.key));
+    // parse
+    const analyses = new Map();
+    const tokenAnalyses = new Map();
+    const importsOf = new Map();
+    let parseFailures = 0;
+    const analyzer = opts.ts ? new Analyzer(opts.ts, opts.schema) : null;
+    for (const file of files) {
+        let text;
+        try {
+            text = await readFile(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (text.length > 2_000_000)
+            continue;
+        let specifiers;
+        if (analyzer) {
+            const a = analyzer.analyze(file, text);
+            if (a.parseFailed)
+                parseFailures++;
+            analyses.set(file, a);
+            specifiers = a.specifiers;
+        }
+        else {
+            const a = analyzeTokens(file, text, operational);
+            tokenAnalyses.set(file, a);
+            specifiers = a.specifiers;
+        }
+        const resolved = [];
+        for (const spec of specifiers) {
+            const target = resolveImport(spec, file, fileSet, aliases);
+            if (target && target !== file)
+                resolved.push(target);
+        }
+        importsOf.set(file, [...new Set(resolved)]);
+    }
+    if (parseFailures > 0)
+        notes.push(`${parseFailures} file${parseFailures === 1 ? "" : "s"} had syntax errors and may be incomplete.`);
+    // pages that reach a file through imports
+    const importers = new Map();
+    for (const [file, targets] of importsOf) {
+        for (const t of targets) {
+            if (!importers.has(t))
+                importers.set(t, []);
+            importers.get(t).push(file);
+        }
+    }
+    const pagesOfCache = new Map();
+    const routesUnder = (prefix) => {
+        const all = [...routes.pages.values()].filter((r) => r === prefix || r.startsWith(prefix === "/" ? "/" : `${prefix}/`));
+        return all.length > 0 ? all : [prefix];
+    };
+    const pagesOf = (file) => {
+        const cached = pagesOfCache.get(file);
+        if (cached)
+            return cached;
+        const out = new Set();
+        const seen = new Set();
+        const queue = [[file, 0]];
+        while (queue.length > 0) {
+            const [f, depth] = queue.shift();
+            if (seen.has(f))
+                continue;
+            seen.add(f);
+            const page = routes.pages.get(f);
+            if (page)
+                out.add(page);
+            const layout = routes.layouts.get(f);
+            if (layout)
+                for (const r of routesUnder(layout))
+                    out.add(r);
+            if (page || layout || depth >= 8)
+                continue;
+            for (const importer of importers.get(f) ?? [])
+                queue.push([importer, depth + 1]);
+        }
+        pagesOfCache.set(file, out);
+        return out;
+    };
+    // resolve JSX handoffs into components (one file hop at a time)
+    const resolveComponent = (a, name) => {
+        const imp = a.imports.get(name);
+        if (!imp) {
+            const local = a.components.get(name);
+            return local ? { file: a.file, analysis: a, fn: local } : null;
+        }
+        const target = resolveImport(imp.from, a.file, fileSet, aliases);
+        const analysis = target ? analyses.get(target) : undefined;
+        if (!analysis)
+            return null;
+        const localName = analysis.exports.get(imp.name);
+        const fn = localName ? analysis.components.get(localName) : undefined;
+        return fn ? { file: analysis.file, analysis, fn } : null;
+    };
+    const unresolved = [];
+    const looksLocal = (spec) => spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("@/") || spec.startsWith("~/") || aliases.some((al) => spec.startsWith(al.prefix));
+    const followHandoffs = (read, a, depth, visited) => {
+        if (!opts.ts || depth > 4)
+            return;
+        for (const h of read.handoffs.splice(0)) {
+            const target = resolveComponent(a, h.component);
+            if (!target) {
+                const imp = a.imports.get(h.component);
+                if (imp && looksLocal(imp.from))
+                    unresolved.push(`${h.component} in ${a.file} (import "${imp.from}" not found)`);
+                continue;
+            }
+            const stamp = `${target.file}#${h.component}#${h.prop ?? "*"}`;
+            if (visited.has(stamp))
+                continue;
+            visited.add(stamp);
+            const param = target.fn.parameters[0];
+            if (!param)
+                continue;
+            const sub = { ...read, component: h.component, file: target.file, handoffs: [] };
+            const tracer = new Tracer(opts.ts, target.analysis, sub);
+            const ts = opts.ts;
+            if (h.prop === null) {
+                // {...record} or {...record.data}: the props are the record (or its fields)
+                tracer.traceBinding(param.name, h.shape, 0);
+            }
+            else if (ts.isObjectBindingPattern(param.name)) {
+                for (const el of param.name.elements) {
+                    const prop = el.propertyName ? propName(ts, el.propertyName) : ts.isIdentifier(el.name) ? el.name.text : null;
+                    if (prop === h.prop)
+                        tracer.traceBinding(el.name, h.shape, 0);
+                }
+            }
+            else if (ts.isIdentifier(param.name)) {
+                // props.post.data.title
+                const propsName = param.name.text;
+                const body = target.fn.body;
+                if (body) {
+                    const visit = (n) => {
+                        if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === propsName && n.name.text === h.prop) {
+                            tracer.traceValue(n, h.shape, 0);
+                            return;
+                        }
+                        ts.forEachChild(n, visit);
+                    };
+                    visit(body);
+                }
+            }
+            for (const f of sub.fields) {
+                read.fields.add(f);
+                if (!read.fieldSites.has(f))
+                    read.fieldSites.set(f, sub.fieldSites.get(f) ?? { component: h.component, file: target.file });
+            }
+            followHandoffs(sub, target.analysis, depth + 1, visited);
+            for (const f of sub.fields) {
+                read.fields.add(f);
+                if (!read.fieldSites.has(f))
+                    read.fieldSites.set(f, sub.fieldSites.get(f) ?? { component: h.component, file: target.file });
+            }
+        }
+    };
+    // wrapper calls: a call to an imported (or local) helper that returns a read is a read here
+    const wrapperReads = [];
+    const usedWrappers = new Set();
+    if (opts.ts) {
+        const ts = opts.ts;
+        for (const a of analyses.values()) {
+            const visit = (n) => {
+                if (ts.isCallExpression(n)) {
+                    const callee = unwrap(ts, n.expression);
+                    if (ts.isIdentifier(callee)) {
+                        let info;
+                        let origin;
+                        const imp = a.imports.get(callee.text);
+                        let wrapperId = null;
+                        if (imp) {
+                            const target = resolveImport(imp.from, a.file, fileSet, aliases);
+                            origin = target ? analyses.get(target) : undefined;
+                            const localName = origin?.exports.get(imp.name);
+                            info = localName ? origin?.wrappers.get(localName) : undefined;
+                            if (info && origin && localName)
+                                wrapperId = `${origin.file}#${localName}`;
+                        }
+                        else {
+                            const local = a.wrappers.get(callee.text);
+                            if (local && local.read.wrapper !== null) {
+                                // a call to the helper from another function of the same file
+                                const outerName = functionName(ts, outermostFunction(ts, n));
+                                if (outerName !== callee.text) {
+                                    info = local;
+                                    origin = a;
+                                    wrapperId = `${a.file}#${callee.text}`;
+                                }
+                            }
+                        }
+                        if (info && origin) {
+                            if (wrapperId)
+                                usedWrappers.add(wrapperId);
+                            const outer = outermostFunction(ts, n);
+                            const read = {
+                                method: info.read.method,
+                                collection: info.read.collection,
+                                fields: new Set(info.read.fields),
+                                fieldSites: new Map(info.read.fieldSites),
+                                component: functionName(ts, outer),
+                                file: a.file,
+                                bySlug: info.read.bySlug,
+                                wrapper: null,
+                                handoffs: [],
+                            };
+                            const tracer = new Tracer(ts, a, read);
+                            tracer.traceValue(n, info.shape, 0);
+                            if (tracer.returned && outer) {
+                                const name = functionName(ts, outer);
+                                if (name) {
+                                    a.wrappers.set(name, { read, shape: tracer.returned });
+                                    read.wrapper = name;
+                                }
+                            }
+                            followHandoffs(read, a, 0, new Set());
+                            wrapperReads.push(read);
+                        }
+                    }
+                }
+                ts.forEachChild(n, visit);
+            };
+            visit(a.source);
+        }
+    }
+    const placed = [];
+    let dynamic = 0;
+    let unreached = [];
+    const allReads = [];
+    for (const a of analyses.values()) {
+        for (const r of a.reads) {
+            if (r.collection === "") {
+                dynamic++;
+                continue;
+            }
+            followHandoffs(r, a, 0, new Set());
+            allReads.push(r);
+        }
+    }
+    for (const a of tokenAnalyses.values()) {
+        for (const r of a.reads) {
+            if (r.collection === "") {
+                dynamic++;
+                continue;
+            }
+            allReads.push(r);
+        }
+    }
+    allReads.push(...wrapperReads);
+    for (const r of allReads) {
+        if (r.wrapper !== null) {
+            // reached through its callers; a helper nobody calls is noted
+            if (!usedWrappers.has(`${r.file}#${r.wrapper}`))
+                unreached.push(`${r.wrapper} (${r.file})`);
+            continue;
+        }
+        const pages = [...pagesOf(r.file)].filter(isSitePage).sort();
+        if (pages.length === 0) {
+            unreached.push(r.component ? `${r.component} (${r.file})` : r.file);
+            continue;
+        }
+        placed.push({ read: r, pages });
+    }
+    if (dynamic > 0)
+        notes.push(`${dynamic} read${dynamic === 1 ? "" : "s"} with a computed collection name ${dynamic === 1 ? "was" : "were"} skipped.`);
+    const missing = [...new Set(unresolved)];
+    if (missing.length > 0) {
+        notes.push(`Couldn't follow ${missing.length === 1 ? "a component prop" : `${missing.length} component props`}: ${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""}.`);
+    }
+    unreached = [...new Set(unreached)];
+    if (unreached.length > 0) {
+        notes.push(`No page reaches ${unreached.length === 1 ? "this read" : "these reads"}: ${unreached.slice(0, 5).join(", ")}${unreached.length > 5 ? ", …" : ""}.`);
+    }
+    // bindings
+    const bindings = new Map();
+    const add = (b) => {
+        if (!bindings.has(b.key))
+            bindings.set(b.key, b);
+    };
+    const relFile = (f) => f;
+    for (const { read, pages } of placed) {
+        const collection = schemaIndex.get(read.collection);
+        const fieldTypes = new Map((collection?.fields ?? []).map((f) => [f.key, f.type]));
+        const slugField = collection?.fields.find((f) => f.type === "slug")?.key;
+        for (const page of pages) {
+            const rk = routeKey(page);
+            const isList = read.method === "getRecords" || read.method === "list";
+            if (isList || read.fields.size === 0) {
+                add({
+                    key: `${rk}:${read.collection}`,
+                    page,
+                    ...(read.component ? { component: read.component } : {}),
+                    file: relFile(read.file),
+                    collection: read.collection,
+                    target: "collection",
+                });
+            }
+            if (read.bySlug && /\[[^\]]+\]/.test(page)) {
+                add({
+                    key: `${rk}:${read.collection}[route]`,
+                    page,
+                    ...(read.component ? { component: read.component } : {}),
+                    file: relFile(read.file),
+                    collection: read.collection,
+                    ...(slugField ? { field: slugField } : {}),
+                    target: "route_param",
+                });
+            }
+            for (const field of [...read.fields].sort()) {
+                const site = read.fieldSites.get(field) ?? { component: read.component, file: read.file };
+                add({
+                    key: `${rk}:${read.collection}.${field}`,
+                    page,
+                    ...(site.component ? { component: site.component } : {}),
+                    file: relFile(site.file),
+                    collection: read.collection,
+                    field,
+                    target: targetFor(fieldTypes.get(field)),
+                });
+            }
+        }
+    }
+    const pages = [...routes.pages.entries()]
+        .map(([file, route]) => ({ route, file }))
+        .sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : a.file < b.file ? -1 : 1));
+    // one entry per route: the first file wins (route groups can collide)
+    const seenRoutes = new Set();
+    const uniquePages = pages.filter((p) => (seenRoutes.has(p.route) ? false : (seenRoutes.add(p.route), true)));
+    const sortedBindings = [...bindings.values()].sort((a, b) => a.page < b.page ? -1 : a.page > b.page ? 1 : a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+    if (!opts.ts) {
+        notes.push("TypeScript isn't installed in this repository, so fields weren't traced (collections only) — npm install -D typescript and scan again.");
+    }
+    return {
+        framework,
+        parser: opts.ts ? "typescript" : "tokens",
+        files: files.length,
+        pages: uniquePages,
+        bindings: sortedBindings,
+        notes,
+    };
+}
+/** The scan's bindings replace the ones with the same key; bindings the
+    scanner can't see (an agent's, hand-written) stay unless pruned. */
+export function mergeManifest(existing, scan, opts) {
+    const scanned = new Map(scan.bindings.map((b) => [b.key, b]));
+    const added = [];
+    const changed = [];
+    const unchanged = [];
+    const kept = [];
+    const dropped = [];
+    const out = [];
+    const existingByKey = new Map((existing?.bindings ?? []).map((b) => [b.key, b]));
+    for (const b of existing?.bindings ?? []) {
+        const s = scanned.get(b.key);
+        if (s) {
+            const same = s.page === b.page &&
+                s.collection === b.collection &&
+                (s.field ?? null) === (b.field ?? null) &&
+                s.target === b.target &&
+                (s.component ?? null) === (b.component ?? null) &&
+                (s.file ?? null) === (b.file ?? null);
+            (same ? unchanged : changed).push(b.key);
+            out.push({ ...s, ...(b.required !== undefined ? { required: b.required } : {}) });
+        }
+        else if (opts.prune)
+            dropped.push(b.key);
+        else {
+            kept.push(b.key);
+            out.push(b);
+        }
+    }
+    for (const s of scan.bindings) {
+        if (!existingByKey.has(s.key)) {
+            added.push(s.key);
+            out.push(s);
+        }
+    }
+    out.sort((a, b) => (a.page < b.page ? -1 : a.page > b.page ? 1 : a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const manifest = {
+        ...(scan.framework ? { framework: scan.framework } : existing?.framework ? { framework: existing.framework } : {}),
+        ...(existing?.integrationMode ? { integrationMode: existing.integrationMode } : {}),
+        pages: scan.pages,
+        bindings: out,
+        ...(existing?.notes && existing.notes.length > 0 ? { notes: existing.notes } : {}),
+    };
+    return { manifest, added, changed, unchanged, kept, dropped };
+}