@fourier-labs/harbour 0.1.27 → 0.1.28

package/dist/packages/harbour-cli/src/flow-coverage.js

@@ -1,490 +0,0 @@
-import { createServer, request as httpRequest } from "node:http";
-import { connect } from "node:net";
-import { readdir, readFile } from "node:fs/promises";
-import { extname, join, relative, sep } from "node:path";
-/**
- * The pipeline's operation-coverage gate, run locally.
- *
- * The deployment pipeline replays `.harbour/checks/` against a real App Gateway
- * and then refuses the deployment (`flow.check-failed`) unless every database
- * operation the browser code performs, and every capability the kit lane
- * derives from that code, was actually exercised while those checks ran. Before
- * this module `harbour check` ran the same journey scripts but asserted nothing
- * about what they exercised, so an app whose checks never touched a converted
- * operation passed locally and failed in the pipeline — the parity gap this
- * closes.
- *
- * The inventory and the wording below deliberately mirror the data plane's
- * packages/toolkit/transformbuild (write_probe.go `inventorySDKTableVerbs`,
- * local_operation_coverage.go `requireOperationCoverage`) so a local failure
- * reads exactly like the pipeline's.
- */
-/** Capabilities the coverage gate demands evidence for, in the pipeline's order. */
-export const COVERED_CAPABILITIES = ["data", "files", "actions", "telemetry", "realtime"];
-/** Every capability the kit lane derives from the browser SDK surface. */
-const SDK_CAPABILITIES = ["data", "files", "actions", "realtime", "telemetry", "integrations"];
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
-const SKIPPED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "build", ".harbour"]);
-/**
- * TypeScript call sites carry explicit type arguments between a method name and
- * its call — `harbour.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");
-/** Records the gateway operations observed while the retained checks ran. */
-export class CoverageLedger {
-    seen = new Set();
-    /** capability -> the retained checks that asked the gateway for it. */
-    asked = new Map();
-    running;
-    add(key) { this.seen.add(key); }
-    has(key) { return this.seen.has(key); }
-    keys() { return [...this.seen].sort(); }
-    /**
-     * Names the retained check whose gateway traffic follows. The journeys run
-     * one at a time, so a request the proxy sees between this call and the next
-     * belongs to this check — which is how a refusal can name the file to delete.
-     */
-    nowRunning(check) { this.running = check; }
-    /**
-     * One request the running check sent at a capability-gated path, recorded
-     * whatever the answer was. The deployed gateway resolves the capability
-     * BEFORE any handler runs and answers 404 when the app did not declare it
-     * (appgateway/resolver.go "capability is not declared"), so the request
-     * itself — not its local success — is what decides the check's fate there.
-     */
-    askedFor(path) {
-        const capability = capabilityForRequest(path);
-        if (!capability || !this.running)
-            return;
-        const checks = this.asked.get(capability) ?? new Set();
-        checks.add(this.running);
-        this.asked.set(capability, checks);
-    }
-    /** capability -> the checks that asked for it, for the reverse coverage question. */
-    capabilitiesAsked() { return this.asked; }
-    /**
-     * The gateway's data boundary. A write that changed no row proves nothing, so
-     * only a select — or a mutation that returned rows — counts (observeData in
-     * local_operation_coverage.go).
-     */
-    observeData(table, operation, rows) {
-        if (operation !== "select" && rows === 0)
-            return;
-        this.add("data");
-        this.add(`data:${table}:${operation}`);
-    }
-}
-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(() => "")));
-    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: `harbour.files.list(`, `client().files.list(`,
- * `(harbour 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. Where it errs it errs by staying quiet: a
- * commented-out call still counts here, and the pipeline masks comments.
- */
-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 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([...text.matchAll(CAPABILITY_CALL)].map(match => match[1]));
-}
-/**
- * The gateway's own path -> capability map (appgateway/gateway.go
- * `capabilityForRequest`). Every one of these paths is resolved against the
- * app's declared capability set before it is served.
- */
-export function capabilityForRequest(path) {
-    if (path === "/_harbour/realtime")
-        return "realtime";
-    if (path.startsWith("/_harbour/files"))
-        return "files";
-    if (path.startsWith("/_harbour/actions/"))
-        return "actions";
-    if (path === "/_harbour/telemetry")
-        return "telemetry";
-    if (path.startsWith("/_harbour/integrations/"))
-        return "integrations";
-    if (path.startsWith("/_harbour/data/"))
-        return "data";
-    return undefined;
-}
-/**
- * The other direction, and the one that let a real deploy fail twice: a
- * retained check exercising a capability the app does not have any more.
- *
- * A builder's agent replaced the starter's notes schema and deleted the
- * "Private files" section but left `.harbour/checks/files-journey.mjs` behind.
- * The kit lane derives `.harbour/app-capabilities.json` from the browser SDK
- * surface, the cell's App Gateway serves only what that file declares, and the
- * journey's first `harbour.files.*` call came back 404 — `flow.check-failed …
- * files-journey.mjs: exit status 1`, twice, 2m23s and 2m12s. Locally the check
- * was green: `harbour dev` hard-codes data/files/realtime/telemetry
- * (local-runtime.ts `gatewayConfig`) and always provisions MinIO, so the
- * orphaned journey passed on its own terms.
- *
- * This reproduces the pipeline's refusal rather than inventing a second
- * opinion, at the pipeline's own granularity — the capability, not the table.
- * The pipeline does have a table-level reverse check
- * (`rejectServerTierOperationsDrivenFromTheBrowser`), but it is scoped to apps
- * that declare a workload directory; a kit app has none, so a check that reads
- * a table the browser no longer reads is served there and must be served here.
- */
-export function orphanedChecks(surface, ledger) {
-    const orphaned = [];
-    for (const [capability, checks] of ledger.capabilitiesAsked()) {
-        if (surface.has(capability))
-            continue;
-        for (const check of checks) {
-            orphaned.push(`${check}: exercises the ${capability} capability, which no code in this app calls any more. ` +
-                `The deployed gateway serves only the capabilities the kit lane derives from the source, so it refuses this check as ` +
-                `flow.check-failed: ${check}: exit status 1. Delete .harbour/checks/${check}, or restore the harbour.${capability}.* feature it was written for.`);
-        }
-    }
-    return orphaned.sort();
-}
-/** The `flow` check's detail, in the pipeline's words, for both directions. */
-export function flowDetail(missing, orphaned) {
-    const parts = [];
-    if (missing.length)
-        parts.push(`${missing.join("; ")}. Exercise the converted application operations with source-valid inputs and assertions; an unrelated passing check is insufficient.`);
-    if (orphaned.length)
-        parts.push(orphaned.join("; "));
-    if (!parts.length)
-        return "every operation the app performs and every capability it declares was exercised by a retained check, and no retained check exercises a capability the app no longer has";
-    return `${parts.join(" ")} The pipeline refuses this deployment as kit.check-failed: flow.check-failed.`;
-}
-/**
- * What the pipeline would refuse, in its own words: an inventoried operation or
- * a declared capability with no successful observation while the checks ran.
- */
-export function missingFlowOperations(inventory, capabilities, ledger) {
-    const missing = [];
-    for (const [table, verbs] of inventory) {
-        for (const verb of verbs) {
-            if (!ledger.has(`data:${table}:${verb}`))
-                missing.push(`${table} ${verb.toUpperCase()}: no successful converted application operation observed`);
-        }
-    }
-    for (const capability of COVERED_CAPABILITIES) {
-        if (capabilities.has(capability) && !ledger.has(capability))
-            missing.push(`${capability}: retained checks did not exercise this declared component`);
-    }
-    return missing.sort();
-}
-const HOP_HEADERS = new Set(["connection", "keep-alive", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", "host", "content-length"]);
-/**
- * A loopback reverse proxy in front of the running `harbour dev` origin that
- * records what the retained checks exercise. The pipeline observes the same
- * boundary from inside its own gateway; observing it here needs no second
- * gateway and no change to the checks, which keep using HARBOUR_APP_URL.
- */
-export function createCoverageProxy(origin, ledger) {
-    const target = new URL(origin);
-    const port = Number(target.port || 80);
-    const host = target.hostname;
-    const upstreamOrigin = target.origin;
-    const server = createServer((incoming, response) => {
-        const path = (incoming.url ?? "/").split("?")[0];
-        // Before the answer: the deployed gateway refuses an undeclared capability
-        // at this path whatever the handler would have said, so what the check
-        // asked for is the evidence the reverse gate needs.
-        ledger.askedFor(path);
-        const chunks = [];
-        incoming.on("data", chunk => { if (chunks.length < 64)
-            chunks.push(chunk); });
-        const upstream = httpRequest({ host, port, method: incoming.method, path: incoming.url, headers: forwardable(incoming.headers, upstreamOrigin) }, upstreamResponse => {
-            const body = [];
-            upstreamResponse.on("data", chunk => { if (body.length < 64)
-                body.push(chunk); });
-            upstreamResponse.on("end", () => {
-                const status = upstreamResponse.statusCode ?? 0;
-                if (status >= 200 && status < 300)
-                    record(ledger, path, incoming.method ?? "GET", Buffer.concat(chunks).toString("utf8"), Buffer.concat(body).toString("utf8"));
-            });
-            response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
-            upstreamResponse.pipe(response);
-        });
-        upstream.on("error", () => { if (!response.headersSent)
-            response.writeHead(502); response.end(); });
-        incoming.pipe(upstream);
-    });
-    // Realtime is a WebSocket: the proxy tunnels it untouched and reads the
-    // server's frames as they pass. Only a delivered event counts — the gateway
-    // fires OnRealtimeDelivery for postgres_changes, broadcast and presence, and
-    // never for the `subscribed` acknowledgement, so a check that subscribes and
-    // receives nothing does not clear the capability here either.
-    server.on("upgrade", (incoming, socket, head) => {
-        const path = (incoming.url ?? "/").split("?")[0];
-        ledger.askedFor(path);
-        const upstream = connect(port, host, () => {
-            const headers = Object.entries({ ...forwardable(incoming.headers, upstreamOrigin), host: `${host}:${port}`, connection: "Upgrade", upgrade: "websocket" })
-                .map(([key, value]) => `${key}: ${value}`);
-            upstream.write(`${incoming.method} ${incoming.url} HTTP/1.1\r\n${headers.join("\r\n")}\r\n\r\n`);
-            if (head?.length)
-                upstream.write(head);
-            if (path === "/_harbour/realtime") {
-                const frames = websocketTextFrames();
-                upstream.on("data", (chunk) => { for (const message of frames(chunk))
-                    if (isRealtimeDelivery(message))
-                        ledger.add("realtime"); });
-            }
-            upstream.pipe(socket);
-            socket.pipe(upstream);
-        });
-        upstream.on("error", () => socket.destroy());
-        socket.on("error", () => upstream.destroy());
-    });
-    return {
-        listen: () => new Promise((resolve, reject) => {
-            server.on("error", reject);
-            server.listen(0, "127.0.0.1", () => resolve(`http://127.0.0.1:${server.address().port}`));
-        }),
-        close: () => new Promise(resolve => { server.closeAllConnections?.(); server.close(() => resolve()); })
-    };
-}
-/**
-  * `harbour dev` serves one origin and refuses anything that does not carry it,
-  * so the proxy presents the upstream's own Host and Origin. Forwarding its own
-  * address instead is what made the realtime upgrade fail before this: the
-  * forwarder dropped the socket and the channel never subscribed.
-  */
-function forwardable(headers, origin) {
-    const result = {};
-    for (const [key, value] of Object.entries(headers)) {
-        if (HOP_HEADERS.has(key.toLowerCase()) || value === undefined)
-            continue;
-        result[key] = key.toLowerCase() === "origin" ? origin : Array.isArray(value) ? value.join(", ") : value;
-    }
-    return result;
-}
-/** One successful gateway request, classified exactly as the pipeline's coverage handler does. */
-export function record(ledger, path, method, requestBody, responseBody) {
-    const data = /^\/_harbour\/data\/([A-Za-z0-9_]+)\/query$/.exec(path);
-    if (data) {
-        const operation = String(readJson(requestBody)?.operation ?? "");
-        if (!operation)
-            return;
-        const envelope = readJson(responseBody)?.data;
-        const rows = Array.isArray(envelope?.data) ? envelope.data.length : envelope?.count ?? 0;
-        if (operation === "rpc") {
-            ledger.add("data");
-            ledger.add(`rpc:${data[1]}`);
-            return;
-        }
-        ledger.observeData(data[1], operation, rows);
-        return;
-    }
-    if (path.startsWith("/_harbour/actions/")) {
-        ledger.add("actions");
-        ledger.add(`action:${path.slice("/_harbour/actions/".length)}`);
-        return;
-    }
-    if (path === "/_harbour/files/uploads/complete") {
-        ledger.add("files");
-        ledger.add("files:upload");
-        return;
-    }
-    if (path === "/_harbour/files" && method === "GET") {
-        ledger.add("files");
-        ledger.add("files:list");
-        return;
-    }
-    if (path === "/_harbour/files/remove") {
-        ledger.add("files");
-        ledger.add("files:remove");
-        return;
-    }
-    if (path === "/_harbour/telemetry")
-        ledger.add("telemetry");
-}
-/** The event types the gateway counts as a delivery (appgateway/realtime.go). */
-export function isRealtimeDelivery(message) {
-    const type = readJson(message)?.type;
-    return type === "postgres_changes" || type === "broadcast" || type === "presence";
-}
-/**
- * Reads complete text frames out of a server-to-client WebSocket byte stream.
- * Server frames are never masked, so the payload is the bytes themselves; the
- * head of the stream is the HTTP 101 response, which carries no frame.
- */
-export function websocketTextFrames() {
-    let buffer = Buffer.alloc(0);
-    let started = false;
-    return chunk => {
-        buffer = Buffer.concat([buffer, chunk]);
-        if (!started) {
-            const end = buffer.indexOf("\r\n\r\n");
-            if (end < 0)
-                return [];
-            buffer = buffer.subarray(end + 4);
-            started = true;
-        }
-        const messages = [];
-        for (;;) {
-            if (buffer.length < 2)
-                break;
-            const opcode = buffer[0] & 0x0f;
-            const masked = (buffer[1] & 0x80) !== 0;
-            let length = buffer[1] & 0x7f;
-            let offset = 2;
-            if (length === 126) {
-                if (buffer.length < 4)
-                    break;
-                length = buffer.readUInt16BE(2);
-                offset = 4;
-            }
-            else if (length === 127) {
-                if (buffer.length < 10)
-                    break;
-                length = Number(buffer.readBigUInt64BE(2));
-                offset = 10;
-            }
-            if (masked)
-                offset += 4;
-            if (buffer.length < offset + length)
-                break;
-            if (opcode === 1 && !masked)
-                messages.push(buffer.subarray(offset, offset + length).toString("utf8"));
-            buffer = buffer.subarray(offset + length);
-        }
-        return messages;
-    };
-}
-function readJson(body) {
-    try {
-        const value = JSON.parse(body);
-        return value && typeof value === "object" ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}