@vantageos/backend-doctor 0.1.1 → 0.1.2

package/dist/detectors/source/isolation.js

@@ -1,10 +1,122 @@
 import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
-// A PUBLIC reactive read opener. `\bquery\(` does NOT match `internalQuery(`
-// (the 'query' there is preceded by a word char, so the \b fails) nor `mutation(`.
-const PUBLIC_QUERY_OPEN = /\bquery\s*\(/;
-// exclude the httpAction/action openers and internal variants explicitly for safety.
-const NON_QUERY_OPEN = /\b(?:internalQuery|internalMutation|mutation|action|httpAction)\s*\(/;
-const EXPORT_NAME = /export\s+const\s+([A-Za-z0-9_]+)\s*=/;
+// A public reactive read is DEFINED, not read. R-50 governs a query DEFINITION —
+// `export const NAME = <builder>({ ... })` — never a `ctx.db.query(...)` table READ
+// inside a handler (the pre-fix opener `/\bquery\(/` matched `.query(` reads
+// incidentally, naming a helper's internal read as the site while missing the real
+// subscribed queries — Eta k170q03p). The builder is `query` OR a `customQuery`
+// wrapper the tree declares (the standard Convex idiom: `export const authedQuery =
+// customQuery(query, ...)`, then `export const summary = authedQuery({...})`). A
+// rule about subscribed reads that matches only the bare `query` builder is blind on
+// most real Convex codebases, so R-50 DISCOVERS the builders first, and REFUSES
+// (could-not-judge naming the file) when a builder's base cannot be resolved rather
+// than return a green obtained by not looking.
+// `export const X = customQuery(` — the wrapper opener. The BASE identifier may sit
+// on the SAME line or a FOLLOWING one (the idiom often breaks the call across lines:
+// `customQuery(\n  query,\n  …)`), so the base is resolved by a short look-ahead, not
+// captured here.
+const CUSTOM_QUERY_OPEN = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customQuery\s*\(/;
+// the first identifier token — used to read the BASE after a `customQuery(` opener.
+const FIRST_IDENT = /([A-Za-z_][A-Za-z0-9_]*)/;
+// `export const X = customMutation(...)` — a write builder, never an R-50 subject.
+const CUSTOM_MUTATION_DEF = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customMutation\s*\(/;
+// the base builders the platform ships. `query` is the only public read base.
+const BASE_PUBLIC_QUERY = "query";
+const BASE_INTERNAL_QUERY = "internalQuery";
+// An auth/org GATE helper a customQuery customCtx runs before the handler — a
+// require*/ensure*/assert* access check (requireReadAccess, requireWorkspaceId,
+// ensureCurrentOrg, …). Its presence in the wrapper means the wrapper, not the
+// handler, owns the no-org disposition of every query built from it.
+const GATE_HELPER = /\b(?:require|ensure|assert)[A-Z][A-Za-z0-9_]*\s*\(/;
+/** Discover the query/mutation builders a tree declares BEFORE classifying any
+ *  definition — `query` is always a public read base; a `customQuery(query,…)`
+ *  wrapper is public; a `customQuery(internalQuery,…)` wrapper is non-subject; any
+ *  other base is ambiguous (refuse). */
+function discoverBuilders(files) {
+    const b = {
+        publicQuery: new Set([BASE_PUBLIC_QUERY]),
+        nonSubject: new Set([
+            BASE_INTERNAL_QUERY,
+            "mutation",
+            "internalMutation",
+            "action",
+            "internalAction",
+            "httpAction",
+        ]),
+        gated: new Map(),
+        ambiguous: [],
+    };
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        const codeLines = f.lines.filter(code);
+        // full-block text (comments included) for the marker check on a builder region.
+        const allLines = f.lines;
+        for (let i = 0; i < codeLines.length; i++) {
+            const l = codeLines[i];
+            const cm = CUSTOM_MUTATION_DEF.exec(l.raw);
+            if (cm) {
+                b.nonSubject.add(cm[1]);
+                continue;
+            }
+            const cq = CUSTOM_QUERY_OPEN.exec(l.raw);
+            if (!cq)
+                continue;
+            const name = cq[1];
+            // the BASE is the first identifier AFTER `customQuery(` — on this line's
+            // remainder, else on the following code lines (the call is often wrapped).
+            const afterOpen = l.raw.slice((cq.index ?? 0) + cq[0].length);
+            let base = FIRST_IDENT.exec(afterOpen)?.[1];
+            for (let j = i + 1; !base && j < codeLines.length && j <= i + 4; j++) {
+                base = FIRST_IDENT.exec(codeLines[j].raw)?.[1];
+            }
+            if (base === BASE_PUBLIC_QUERY) {
+                b.publicQuery.add(name);
+                // Does the wrapper's customCtx run an auth/org gate that can throw, with
+                // no documented contract? The builder region is the opener line plus the
+                // following few CODE lines (the customCtx body is short). The marker is a
+                // comment, so check it against the raw region INCLUDING comments.
+                const codeRegion = codeLines
+                    .slice(i, i + 10)
+                    .map((x) => x.raw)
+                    .join("\n");
+                const startAbs = allLines.indexOf(l);
+                // include up to 3 lines ABOVE the opener: a builder's isolation-contract
+                // marker is conventionally the comment immediately above its declaration.
+                const rawRegion = startAbs >= 0
+                    ? allLines
+                        .slice(Math.max(0, startAbs - 3), startAbs + 14)
+                        .map((x) => x.raw)
+                        .join("\n")
+                    : codeRegion;
+                const gates = ORG_THROW.test(codeRegion) ||
+                    ORG_THROW_HELPER.test(codeRegion) ||
+                    GATE_HELPER.test(codeRegion);
+                if (gates && !CONTRACT_MARKER.test(rawRegion))
+                    b.gated.set(name, { rel: f.rel, n: l.n });
+            }
+            else if (base === BASE_INTERNAL_QUERY)
+                b.nonSubject.add(name);
+            else
+                b.ambiguous.push({
+                    rel: f.rel,
+                    n: l.n,
+                    name,
+                    base: base ?? "<unresolved>",
+                });
+        }
+    }
+    return b;
+}
+/** `export const NAME = <builder>(` for a builder in `set`. A DEFINITION opener,
+ *  never a `.query(` read (there is no `const NAME =` before a `ctx.db.query(`). */
+function definitionOpener(raw, set) {
+    // longest builder names first so `authedQuery` wins over a `query` substring.
+    const names = [...set].sort((a, z) => z.length - a.length);
+    const alt = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const re = new RegExp(`(?:export\\s+)?const\\s+([A-Za-z0-9_]+)\\s*=\\s*(${alt})\\s*\\(`);
+    const m = re.exec(raw);
+    return m ? { name: m[1], builder: m[2] } : null;
+}
 // An ORG-ISOLATION THROW: a throw keyed on the caller having no org/identity, or a
 // helper that throws on the missing-org path. This is the behaviour a subscribed
 // client receives as an uncaught Server Error.
@@ -40,6 +152,44 @@ function queryBlock(lines, i) {
 }
 export function scanR50(files) {
     const scan = emptyScan();
+    // Pass 1: discover the tree's query/mutation builders so a customQuery wrapper
+    // (authedQuery, orgQuery, …) is recognised, not just the bare `query` base.
+    const builders = discoverBuilders(files);
+    // A customQuery wrapper whose base is neither query nor internalQuery leaves the
+    // public-query surface unknowable — REFUSE (could-not-judge), never a silent green.
+    for (const a of builders.ambiguous) {
+        scan.cnj.push({
+            rel: a.rel,
+            n: a.n,
+            note: `builder "${a.name}" = customQuery(${a.base}, …) — its base "${a.base}" resolves to neither \`query\` (public) nor \`internalQuery\`, so whether definitions using it are subscribed queries cannot be enumerated; R-50 refuses rather than certify a surface it cannot see (never a silent green)`,
+        });
+    }
+    // A GATED public customQuery builder: its customCtx runs an auth/org gate that can
+    // throw, so every subscribed query built from it inherits that throw in the shared
+    // wrapper — invisible to a per-handler scan. REFUSE per builder (could-not-judge),
+    // naming it and counting its dependent subscribed queries, so a customQuery
+    // codebase never reads "R-50 clean" by the opener simply not looking into the
+    // wrapper. (The remedy a human confirms: the wrapper returns a typed empty/unauth
+    // context on the no-org path, or documents an isolation-contract on the builder.)
+    for (const [name, at] of builders.gated) {
+        let deps = 0;
+        for (const f of files) {
+            if (!isJudgeable(f))
+                continue;
+            for (const l of f.lines) {
+                if (!code(l))
+                    continue;
+                const o = definitionOpener(l.raw, new Set([name]));
+                if (o)
+                    deps += 1;
+            }
+        }
+        scan.cnj.push({
+            rel: at.rel,
+            n: at.n,
+            note: `customQuery builder "${name}" gates every query built from it in its customCtx (an auth/org require*/throw), and ${deps} subscribed query(ies) route through it — whether that wrapper THROWS into a subscription or returns a typed empty/unauthorized context on the no-org path is not decidable from the query surface. R-50 refuses (a human confirms the wrapper's no-org shape, or the builder carries an isolation-contract marker) — never a silent green obtained by not looking into the wrapper`,
+        });
+    }
     for (const f of files) {
         if (!isJudgeable(f))
             continue;
@@ -47,15 +197,23 @@ export function scanR50(files) {
         for (let i = 0; i < lines.length; i++) {
             if (!code(lines[i]))
                 continue;
-            if (!PUBLIC_QUERY_OPEN.test(lines[i].raw))
+            // R-50's subject is a public-query DEFINITION: `const NAME = <publicBuilder>(`.
+            // This never matches a `ctx.db.query(...)` read (no `const NAME =` there) nor
+            // an internal/mutation/action definition (those builders are not in the set).
+            const opener = definitionOpener(lines[i].raw, builders.publicQuery);
+            if (!opener)
                 continue;
-            // a line whose only match is a non-query opener (mutation/action/internal*)
-            // is not R-50's subject — skip it even if it also contains "query" prose.
-            if (NON_QUERY_OPEN.test(lines[i].raw) && !/\bquery\s*\(/.test(lines[i].raw.replace(NON_QUERY_OPEN, "")))
+            // A query declared through a GATED customQuery builder inherits its no-org
+            // disposition from the shared customCtx wrapper (an auth/org gate that can
+            // throw), NOT from this handler — so a per-handler scan cannot see it. The
+            // builder-level refusal below covers these; skip the per-handler pass here.
+            if (builders.gated.has(opener.builder))
                 continue;
-            const fn = EXPORT_NAME.exec(lines[i].raw)?.[1] ??
-                (i > 0 ? EXPORT_NAME.exec(lines[i - 1].raw)?.[1] : undefined) ??
-                "<anonymous>";
+            // exclude the builder DEFINITION line itself (`const authedQuery = query(`?
+            // no — customQuery defs use `customQuery(`, filtered above; but guard a
+            // `const x = query(` that is a re-export, not a `query({config})`): require
+            // the block to open a config object, handled by queryBlock below).
+            const fn = opener.name;
             const block = queryBlock(lines, i);
             i += block.lines.length - 1;
             if (block.unterminated) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/backend-doctor",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A conformance instrument that measures the VantagePeers backend against the pinned backend standard. The THIRD doctor built ON the @vantageos/mcp-doctor engine — never a third engine. It consumes runDoctor/renderTable and adds only detectors.",
   "type": "module",
   "main": "./dist/cli.js",