@vantageos/backend-doctor 0.2.0 → 0.4.0

package/dist/detectors/source/readbudget.js

@@ -80,6 +80,289 @@ function readBoundFor(all, n, end) {
     }
     return undefined;
 }
+// ---- the CALLER-DRIVEN drain ------------------------------------------------
+//
+// A second drain shape R-31 can judge statically: the mutation reads exactly ONE
+// page with `.paginate(...)` and returns that page's continuation to its caller —
+// BOTH the cursor (`continueCursor`, under any field name) and the done flag
+// (`isDone`, under any field name) — and the caller re-invokes it with the cursor
+// until done. Each page is one transaction, visible and resumable from its cursor
+// (vantage-peers `convex/migrations/backfill_org_stamp.ts`). It conforms only when
+// the page result flows to ONE return statement carrying both fields; a dropped
+// cursor, a missing done flag, or the two split across different returns stay
+// could-not-judge. A `.take(n)` has no continuation and is never this shape.
+const PAGINATE = /\.paginate\s*\(/;
+const IDENT = "[A-Za-z_$][\\w$]*";
+// `const page = await ….paginate(` — the whole page result bound to one local.
+const PAGINATE_BIND = new RegExp(`\\b(?:const|let|var)\\s+(${IDENT})\\s*=\\s*(?:await\\s+)?[^;{]*\\.paginate\\s*\\(`);
+// `const { page, isDone, continueCursor: cur } = await ….paginate(`.
+const PAGINATE_DESTRUCT = /\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?[^;{]*\.paginate\s*\(/;
+// `return [await] ctx.db.query(…)….paginate(` — the page result returned whole.
+const PAGINATE_RETURNED = new RegExp(`\\breturn\\s+(?:await\\s+)?${IDENT}[^;{]*\\.paginate\\s*\\(`);
+const escapeRe = (x) => x.replace(/[$]/g, "\\$");
+/** A bare reference to local `name` in `text`: not a member (`x.name`), not part
+ * of a longer identifier, and not an object KEY (`{ name: …`, `, name: …`). */
+function refersTo(text, name) {
+    const re = new RegExp(`(?<![.\\w$])${escapeRe(name)}(?![\\w$])`, "g");
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+        const before = text.slice(0, m.index).trimEnd();
+        const after = text.slice(m.index + name.length).trimStart();
+        const keyPos = (before.endsWith("{") || before.endsWith(",")) &&
+            after.startsWith(":") &&
+            !after.startsWith("::");
+        if (!keyPos)
+            return true;
+    }
+    return false;
+}
+// `(…) {` opens a block, not a function body, after these keywords.
+const BLOCK_PAREN_KEYWORDS = new Set([
+    "if",
+    "for",
+    "while",
+    "switch",
+    "catch",
+    "with",
+]);
+/** The handler's OWN returns in a mutation block (origin: Argus REVISE #54, P1).
+ * A `return` inside a nested arrow function, `function`, or method body belongs to
+ * that function — a callback's return is not what the mutation hands its caller.
+ * Braces are classified while walking the block's code (strings and comments
+ * skipped): a `{` after `=>`, after the `)` of a parameter list (not an
+ * `if`/`for`/`while`/`switch`/`catch` head), or after a `function` keyword opens a
+ * FUNCTION body. The first function body is the handler; a return counts only when
+ * exactly one function body encloses it. */
+function handlerReturns(lines) {
+    let text = "";
+    const lineAt = [];
+    for (const l of lines) {
+        if (!code(l))
+            continue;
+        for (const ch of `${l.raw}\n`) {
+            text += ch;
+            lineAt.push(l.n);
+        }
+    }
+    // blank comments; mark string bodies as non-structural.
+    const chars = text.split("");
+    const quoted = new Uint8Array(chars.length);
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (ch === "/" && chars[i + 1] === "/") {
+            while (i < chars.length && chars[i] !== "\n")
+                chars[i++] = " ";
+        }
+        else if (ch === "/" && chars[i + 1] === "*") {
+            while (i < chars.length && !(chars[i] === "*" && chars[i + 1] === "/")) {
+                if (chars[i] !== "\n")
+                    chars[i] = " ";
+                i++;
+            }
+            if (i < chars.length)
+                chars[i] = " ";
+            if (i + 1 < chars.length)
+                chars[++i] = " ";
+        }
+        else if (ch === '"' || ch === "'" || ch === "`") {
+            for (i++; i < chars.length && chars[i] !== ch; i++) {
+                quoted[i] = 1;
+                if (chars[i] === "\\")
+                    quoted[++i] = 1;
+            }
+        }
+    }
+    const clean = chars.join("");
+    /** From the `return` at `at`, its text up to the `;` closing it or the brace
+     * closing its block, whichever comes first. */
+    const sliceReturn = (at) => {
+        let nest = 0;
+        let i = at;
+        for (; i < clean.length; i++) {
+            if (quoted[i])
+                continue;
+            const ch = clean[i];
+            if (ch === "(" || ch === "{" || ch === "[")
+                nest += 1;
+            else if (ch === ")" || ch === "}" || ch === "]") {
+                if (nest === 0)
+                    break;
+                nest -= 1;
+            }
+            else if (ch === ";" && nest === 0) {
+                i += 1;
+                break;
+            }
+        }
+        return clean.slice(at, i).replace(/\s+/g, " ").trim();
+    };
+    const out = [];
+    const braces = []; // true = a function body
+    const parens = []; // the word before each open `(`
+    let fnDepth = 0;
+    let prev = ""; // the previous significant token
+    let closedParenWord = "";
+    let pendingFunction = false;
+    let returnType = false; // a `)` of a parameter list followed by `:` — a typed signature
+    let lastWord = "";
+    for (let i = 0; i < clean.length; i++) {
+        if (quoted[i])
+            continue;
+        const ch = clean[i];
+        if (/\s/.test(ch))
+            continue;
+        if (/[A-Za-z_$]/.test(ch)) {
+            let j = i;
+            while (j < clean.length && !quoted[j] && /[\w$]/.test(clean[j]))
+                j++;
+            const word = clean.slice(i, j);
+            const isMember = i > 0 && clean[i - 1] === ".";
+            if (!isMember && word === "function")
+                pendingFunction = true;
+            if (!isMember && word === "return" && fnDepth === 1) {
+                out.push({ line: lineAt[i], text: sliceReturn(i) });
+            }
+            lastWord = word;
+            prev = "word";
+            i = j - 1;
+            continue;
+        }
+        if (ch === "(") {
+            parens.push(prev === "word" ? lastWord : "");
+            prev = "(";
+        }
+        else if (ch === ")") {
+            closedParenWord = parens.pop() ?? "";
+            prev = ")";
+        }
+        else if (ch === "{") {
+            const fn = prev === "=>" ||
+                pendingFunction ||
+                returnType ||
+                (prev === ")" && !BLOCK_PAREN_KEYWORDS.has(closedParenWord));
+            returnType = false;
+            if (fn) {
+                pendingFunction = false;
+                fnDepth += 1;
+            }
+            braces.push(fn);
+            prev = "{";
+        }
+        else if (ch === "}") {
+            if (braces.pop())
+                fnDepth -= 1;
+            prev = "}";
+        }
+        else if (ch === "=" && clean[i + 1] === ">") {
+            prev = "=>";
+            returnType = false;
+            i += 1;
+        }
+        else if (ch === ":" && prev === ")" && !BLOCK_PAREN_KEYWORDS.has(closedParenWord)) {
+            returnType = true;
+            prev = ch;
+        }
+        else if (ch === ";") {
+            returnType = false;
+            prev = ch;
+        }
+        else {
+            prev = ch;
+        }
+    }
+    return out;
+}
+/** The handler's own returns that start inside the given statements. */
+function returnsOf(stmts, own) {
+    return own
+        .filter((r) => stmts.some((st) => r.line >= st.n && r.line <= st.end))
+        .map((r) => r.text);
+}
+// A call that runs another function INSIDE this transaction.
+// `ctx.runMutation(`, `ctx["runMutation"](`, or a destructured `runMutation(`.
+const RUN_IN_TXN = /\brun(?:Mutation|Action)["'`]?\s*\]?\s*\(/;
+/** True when a statement after the read hands the page's cursor to, or names the
+ * mutation itself in, a `ctx.runMutation` / `ctx.runAction` call (origin: Argus
+ * REVISE #54, P3). That walks the pages inside ONE transaction — the drain is not
+ * caller-driven, whatever the mutation returns afterwards. */
+function selfDrains(later, self, carriesCursor) {
+    const selfRef = new RegExp(`\\.\\s*${escapeRe(self)}(?![\\w$])`);
+    // a local bound to the cursor carries it too: `const next = page.continueCursor`
+    const aliases = [];
+    for (const x of later) {
+        const d = /^\s*(?:const|let|var)\s+([\w$]+)\s*=/.exec(x.text);
+        if (d && carriesCursor(x.text.slice(d[0].length)))
+            aliases.push(d[1]);
+    }
+    const carries = (t) => carriesCursor(t) || aliases.some((a) => new RegExp(`(?<![\\w$.])${escapeRe(a)}(?![\\w$])`).test(t));
+    return later.some((x) => {
+        const m = RUN_IN_TXN.exec(x.text);
+        if (!m)
+            return false;
+        const call = x.text.slice(m.index);
+        return selfRef.test(call) || carries(call);
+    });
+}
+/** True when the paginated read in `st` flows to a return statement (among the
+ * statements after it in the mutation) carrying BOTH its continuation cursor and
+ * its done flag. */
+function returnsContinuation(st, later, own, self) {
+    if (!PAGINATE.test(st.text))
+        return false;
+    if (PAGINATE_RETURNED.test(st.text)) {
+        // the read itself is the handler's own return, never a callback's.
+        return (own.some((r) => r.line >= st.n && r.line <= st.end) &&
+            !selfDrains(later, self, () => false));
+    }
+    // the returns this read can reach: up to the next statement that re-declares
+    // one of its locals (a second `const page = …` in another branch is another read).
+    const until = (locals) => {
+        const names = locals.filter((x) => x !== undefined);
+        const cut = later.findIndex((x) => names.some((nm) => new RegExp(`\\b(?:const|let|var)\\s*(?:\\{[^}]*)?(?<![\\w$])${escapeRe(nm)}(?![\\w$])`).test(x.text)));
+        return returnsOf(cut < 0 ? later : later.slice(0, cut), own);
+    };
+    const bound = PAGINATE_BIND.exec(st.text)?.[1];
+    if (bound !== undefined) {
+        const rets = until([bound]);
+        const b = escapeRe(bound);
+        const cursor = new RegExp(`(?<![.\\w$])${b}\\s*\\.\\s*continueCursor\\b`);
+        const done = new RegExp(`(?<![.\\w$])${b}\\s*\\.\\s*isDone\\b`);
+        const whole = new RegExp(`^return\\s+${b}\\s*;?\\s*$|\\.\\.\\.\\s*${b}(?![\\w$]|\\s*[.[])`);
+        if (selfDrains(later, self, (t) => cursor.test(t)))
+            return false;
+        return rets.some((r) => whole.test(r.trim()) || (cursor.test(r) && done.test(r)));
+    }
+    const destruct = PAGINATE_DESTRUCT.exec(st.text)?.[1];
+    if (destruct !== undefined) {
+        let cursorLocal;
+        let doneLocal;
+        let rest;
+        for (const part of destruct.split(",")) {
+            const p = part.trim();
+            if (p.startsWith("...")) {
+                rest = p.slice(3).trim();
+                continue;
+            }
+            const m = new RegExp(`^(${IDENT})\\s*(?::\\s*(${IDENT}))?`).exec(p);
+            if (!m)
+                continue;
+            const local = m[2] ?? m[1];
+            if (m[1] === "continueCursor")
+                cursorLocal = local;
+            if (m[1] === "isDone")
+                doneLocal = local;
+        }
+        const rets = until([cursorLocal, doneLocal, rest]);
+        const carries = (r, local, field) => local !== undefined
+            ? refersTo(r, local)
+            : rest !== undefined &&
+                new RegExp(`(?<![.\\w$])${escapeRe(rest)}\\s*\\.\\s*${field}\\b`).test(r);
+        if (selfDrains(later, self, (t) => carries(t, cursorLocal, "continueCursor")))
+            return false;
+        return rets.some((r) => carries(r, cursorLocal, "continueCursor") &&
+            carries(r, doneLocal, "isDone"));
+    }
+    return false;
+}
 /** From the mutation opener at index `i`, delimit its body by matching braces.
  * Returns the block's lines and whether it closed cleanly. */
 function mutationBlock(lines, i) {
@@ -136,6 +419,7 @@ export function scanR31(files) {
                 .map((l) => l.raw)
                 .join("\n");
             const reschedules = RESCHEDULE.test(blockText);
+            const own = handlerReturns(block.lines);
             for (const st of stmts) {
                 if (COLLECT.test(st.text) && !BOUNDED.test(st.text)) {
                     const table = QUERY_TABLE.exec(st.text)?.[1] ?? "<unknown table>";
@@ -176,6 +460,13 @@ export function scanR31(files) {
                             note: `${fn}: bounded read on "${table}" via \`.take(n)\`/\`.paginate\` with a \`ctx.scheduler.runAfter\` self-reschedule — the read stays within the per-transaction read budget across the drain (R-31 conforming)`,
                         });
                     }
+                    else if (returnsContinuation(st, stmts.filter((x) => x.n > st.n), own, fn)) {
+                        scan.conform.push({
+                            rel: f.rel,
+                            n: st.n,
+                            note: `${fn}: bounded read on "${table}" via \`.paginate\` — caller-driven drain: the page's continuation (cursor + isDone) is returned to the caller, which re-invokes the mutation with the cursor until done; each page is one transaction, visible and resumable (R-31 conforming)`,
+                        });
+                    }
                     else {
                         scan.cnj.push({
                             rel: f.rel,

package/dist/detectors/source/recipient-by-id.d.ts

@@ -0,0 +1,40 @@
+import { type FnDef, type Parsed } from "./_ast.js";
+/** Argument fields that NAME the recipient / target agent of a write. */
+export declare const RECIPIENT_ARGS: ReadonlySet<string>;
+/** Stored fields that ROUTE a row to its recipient. */
+export declare const ROUTING_FIELDS: ReadonlySet<string>;
+/** Argument fields that NAME the reader / owner whose data a door selects. */
+export declare const READER_ARGS: ReadonlySet<string>;
+/** Stored agent-identity fields: keying or matching one with a typed value
+ * SELECTS an agent's data by name, whatever the argument is called. */
+export declare const SELECTOR_FIELDS: ReadonlySet<string>;
+/** Fields that route (or select an agent) only on a named table — the bare
+ * word is an author elsewhere (`diary.orchestrator`), so it is declared here
+ * and never added to the global sets. */
+export declare const ROUTING_BY_TABLE: ReadonlyMap<string, ReadonlySet<string>>;
+export interface RecipientSite {
+    rel: string;
+    n: number;
+    note: string;
+}
+export declare class RecipientFlow {
+    private readonly parsed;
+    private readonly fns;
+    private readonly relOf;
+    private readonly done;
+    private readonly queue;
+    readonly sites: Map<string, RecipientSite>;
+    constructor(parsed: Parsed[], fns: Map<string, FnDef[]>);
+    run(): RecipientSite[];
+    private key;
+    /** Analyse one function under seeded parameters; returns its return taint. */
+    private analyse;
+    /** A field of an obj taint: a door's recipient argument, or a carried name. */
+    private field;
+    /** A function declared INSIDE `unit` (shares its environment). */
+    private localFn;
+    /** Module-level definitions a callee names: same file first, else by name. */
+    private defsFor;
+}
+/** Every recipient-by-name site reachable from a convex/ write door. */
+export declare function recipientByNameSites(parsed: Parsed[], fns: Map<string, FnDef[]>): RecipientSite[];