@isomorph.ai/cli 0.4.2 → 0.5.1

package/dist/packages/harbour-cli/src/source-inventory.js

@@ -1,239 +0,0 @@
-import { readdir, readFile } from "node:fs/promises";
-import { extname, join, relative, sep } from "node:path";
-/**
- * What the app's own source performs, read the way the pipeline reads it.
- *
- * Two inventories: every `<table> <verb>` the browser code performs
- * (write_probe.go `inventorySDKTableVerbs`) and every SDK capability it calls
- * (the kit lane's derivation). They are what the kit gate demands evidence
- * for, so `retained-checks.ts` generates the retained journeys from exactly
- * them — a generated journey can then only ever cover what the gate asks
- * about, with no template in between.
- *
- * The gate itself — operation coverage in both directions, the cross-user
- * denial, the database gate — is not here. It is the data plane's
- * `transformbuild.RunKitGate`, and `isomorph check` runs it (check.ts) in the
- * app's local session through the pinned gateway image's `gate` subcommand.
- */
-/** Capabilities the kit gate demands evidence for, in the pipeline's order. */
-export const COVERED_CAPABILITIES = ["data", "files", "actions", "telemetry", "realtime", "ai"];
-/** Every capability the kit lane derives from the browser SDK surface. */
-const SDK_CAPABILITIES = ["data", "files", "actions", "realtime", "telemetry", "integrations", "ai"];
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
-const SKIPPED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "build", ".isomorph"]);
-/**
- * TypeScript call sites carry explicit type arguments between a method name and
- * its call — `isomorph.data.from<Note>("notes")`, `.select<Row>(` — and the
- * starter's own list is one of them. Matching only the bare `.from(` made every
- * typed call site invisible, so a freshly generated starter inventoried
- * `notes: delete, insert, update` with no SELECT: the gate was reading the
- * starter's own capabilities wrong. This is the pipeline's own
- * `appSDKTypeArguments` (transformbuild/source_inspection.go), one nesting
- * level of generics, so both scanners see the same call sites.
- */
-const TYPE_ARGUMENTS = String.raw `(?:<[^<>()]*(?:<[^<>()]*>[^<>()]*)*>)?\s*`;
-const TABLE_CHAIN_SOURCE = String.raw `\.from${TYPE_ARGUMENTS}\(\s*["'\`]([A-Za-z0-9_]+)["'\`]\s*\)`;
-const TABLE_CHAIN = new RegExp(TABLE_CHAIN_SOURCE, "g");
-/** The same chain, unanchored and non-global: where THIS chain's verbs stop. */
-const NEXT_TABLE_CHAIN = new RegExp(TABLE_CHAIN_SOURCE);
-const VERB_CALL = new RegExp(String.raw `\.(select|insert|update|delete|upsert)\s*${TYPE_ARGUMENTS}\(`, "g");
-/** `createClient()` bindings name the identifier a capability call must be made on. */
-const CLIENT_BINDING = /(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?::[^=]+)?=\s*(?:await\s+)?createClient\s*\(/g;
-/** `<anything>.<namespace>.<method>(` — the receiver is deliberately not constrained; see capabilityCallSurface. */
-const CAPABILITY_CALL = new RegExp(String.raw `\.\s*(${SDK_CAPABILITIES.join("|")})\s*\.\s*[A-Za-z_$][A-Za-z0-9_$]*\s*${TYPE_ARGUMENTS}\(`, "g");
-async function sourceFiles(root) {
-    const found = [];
-    const walk = async (directory) => {
-        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
-        for (const entry of entries) {
-            const path = join(directory, entry.name);
-            if (entry.isDirectory()) {
-                if (!SKIPPED_DIRECTORIES.has(entry.name))
-                    await walk(path);
-                continue;
-            }
-            if (SOURCE_EXTENSIONS.has(extname(entry.name)))
-                found.push(path);
-        }
-    };
-    await walk(root);
-    return found.sort();
-}
-/**
- * Every `<table> <verb>` the browser code performs, with the files performing
- * it. The verb chain is what follows THIS `.from(...)` up to the end of its
- * statement or the next `.from(` — never a later chain's verbs.
- *
- * This reading is what the gate demands evidence for, so `retained-checks.ts`
- * generates from exactly it: a generated journey can then only ever cover what
- * the gate asks about, in both directions, with no template in between.
- */
-export async function sourceTableUsage(root) {
-    const inventory = new Map();
-    for (const path of await sourceFiles(root)) {
-        const text = await readFile(path, "utf8");
-        for (const match of text.matchAll(TABLE_CHAIN)) {
-            const start = match.index ?? 0;
-            if (text.slice(0, start).trimEnd().endsWith(".storage"))
-                continue;
-            let tail = text.slice(start + match[0].length);
-            const semicolon = tail.indexOf(";");
-            if (/[;\n]/.test(tail) && semicolon >= 0)
-                tail = tail.slice(0, semicolon);
-            const next = tail.search(NEXT_TABLE_CHAIN);
-            if (next > 0)
-                tail = tail.slice(0, next);
-            tail = tail.slice(0, 200);
-            const table = match[1];
-            const usage = inventory.get(table) ?? { verbs: new Set(), files: [] };
-            for (const verb of tail.matchAll(VERB_CALL))
-                usage.verbs.add(verb[1]);
-            const file = appPath(root, path);
-            if (!usage.files.includes(file))
-                usage.files.push(file);
-            inventory.set(table, usage);
-        }
-    }
-    return inventory;
-}
-/** `<table> <verb>` alone, as the coverage gate compares it. */
-export async function sourceTableVerbs(root) {
-    return new Map([...await sourceTableUsage(root)].map(([table, usage]) => [table, usage.verbs]));
-}
-/**
- * The capabilities the kit lane declares for this app, with the files declaring
- * them: a namespace called as `<client>.<namespace>.<method>(` on an identifier
- * bound to `createClient()`. TypeScript type arguments may sit between the
- * method and its call.
- */
-export async function capabilityUsage(root) {
-    const files = await sourceFiles(root);
-    const texts = (await Promise.all(files.map(path => readFile(path, "utf8").catch(() => "")))).map(maskNonCode);
-    const clients = new Set();
-    for (const text of texts)
-        for (const match of text.matchAll(CLIENT_BINDING))
-            clients.add(match[1]);
-    const used = new Map();
-    if (!clients.size)
-        return used;
-    const namespaces = SDK_CAPABILITIES.join("|");
-    for (const client of clients) {
-        const call = new RegExp(`\\b${client}\\s*\\.\\s*(${namespaces})\\s*\\.\\s*[A-Za-z_$][A-Za-z0-9_$]*\\s*(?:<[^<>()]*>\\s*)?\\(`, "g");
-        for (const [index, text] of texts.entries()) {
-            const file = appPath(root, files[index]);
-            for (const match of text.matchAll(call)) {
-                const seen = used.get(match[1]) ?? [];
-                if (!seen.includes(file))
-                    seen.push(file);
-                used.set(match[1], seen);
-            }
-        }
-    }
-    return used;
-}
-/** The capability names alone, as the coverage gate compares them. */
-export async function declaredCapabilities(root) {
-    return new Set((await capabilityUsage(root)).keys());
-}
-/** A source file as the app itself names it: relative to the root, `/`-separated on every platform. */
-const appPath = (root, path) => relative(root, path).split(sep).join("/");
-/**
- * Every capability namespace the app's own source calls a method on, whatever
- * object the call is made on: `isomorph.files.list(`, `client().files.list(`,
- * `(isomorph as {files: F}).files.list(`.
- *
- * This is deliberately looser than `declaredCapabilities`, and the two answer
- * different questions. The forward gate asks "was this capability exercised?"
- * and must be precise about what the app really uses. The reverse gate below
- * asks "is this check exercising something the app no longer has?" — a
- * question whose wrong answer refuses a good app — so it needs a lower bound on
- * what is unused, never an upper bound on what is used.
- *
- * The pipeline's own evidence for a capability is `<client>.<namespace>.<method>(`
- * with the client traced through the module graph (transformbuild
- * analyzeAppSDKClientCalls / analyzeAppSDKNamespaceWrappers). Dropping the
- * receiver makes this a superset of that set — every call site the pipeline can
- * trace, plus ones it cannot — so a capability this cannot see is one the kit
- * lane cannot declare either, and the reverse gate refuses only trees the
- * pipeline already refuses. Comments and string bodies are masked first,
- * exactly as the pipeline masks them, so a quoted example never counts.
- */
-export async function capabilityCallSurface(root) {
-    const surface = new Set();
-    for (const path of await sourceFiles(root))
-        for (const capability of capabilitiesCalled(await readFile(path, "utf8").catch(() => "")))
-            surface.add(capability);
-    return surface;
-}
-/**
- * The pipeline's reading masks comments and string bodies before it looks for
- * call shapes (transformbuild maskJavaScriptNonCode); this reading does the
- * same, so a call shape quoted in a comment — the starter's own examples —
- * or inside a string never counts as a use. Offsets are preserved (masked
- * bytes become spaces), so nothing that reports a position drifts.
- */
-export function maskNonCode(source) {
-    const out = source.split("");
-    let state = "code";
-    for (let i = 0; i < source.length; i += 1) {
-        const c = source[i], n = source[i + 1];
-        if (state === "code") {
-            if (c === "/" && n === "/") {
-                state = "line";
-                out[i] = " ";
-                continue;
-            }
-            if (c === "/" && n === "*") {
-                state = "block";
-                out[i] = " ";
-                continue;
-            }
-            if (c === "'")
-                state = "single";
-            else if (c === "\"")
-                state = "double";
-            else if (c === "`")
-                state = "template";
-            continue;
-        }
-        if (state === "line") {
-            if (c === "\n")
-                state = "code";
-            else
-                out[i] = " ";
-            continue;
-        }
-        if (state === "block") {
-            if (c === "*" && n === "/") {
-                state = "code";
-                out[i] = " ";
-                out[i + 1] = " ";
-                i += 1;
-            }
-            else if (c !== "\n")
-                out[i] = " ";
-            continue;
-        }
-        // A string body: keep the quotes (the shape around them stays readable), mask what is inside.
-        const quote = state === "single" ? "'" : state === "double" ? "\"" : "`";
-        if (c === "\\") {
-            out[i] = " ";
-            if (n !== undefined && n !== "\n") {
-                out[i + 1] = " ";
-                i += 1;
-            }
-            continue;
-        }
-        if (c === quote) {
-            state = "code";
-            continue;
-        }
-        if (c !== "\n")
-            out[i] = " ";
-    }
-    return out.join("");
-}
-/** The same reading of one piece of text, so a retained check is judged by exactly the rule the app's own source is read with (retained-checks.ts). */
-export function capabilitiesCalled(text) {
-    return new Set([...maskNonCode(text).matchAll(CAPABILITY_CALL)].map(match => match[1]));
-}