@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/tally.js

@@ -12,14 +12,13 @@
 import { computeExitCode } from "@vantageos/mcp-doctor";
 import { deriveRuleIds } from "./coverage.js";
 import { deriveSeverityMap } from "./severity.js";
-/** The four states, in worst-first order — the reduction picks the worst. */
-const STATE_RANK = {
-    "non-conforming": 3,
-    "could-not-judge": 2,
-    absent: 1,
-    present: 0,
-};
-const ALL_STATES = ["present", "non-conforming", "could-not-judge", "absent"];
+import { STATE_RANK } from "./state-rank.js";
+const ALL_STATES = [
+    "present",
+    "non-conforming",
+    "could-not-judge",
+    "absent",
+];
 /** Extract the ruleId (`R-N`) a result belongs to, from its leading id token. */
 export function ruleIdOf(result) {
     const m = /^(R-\d+)\b/.exec(result.id);
@@ -143,6 +142,75 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
         summary,
     };
 }
+/**
+ * The HANDLER-SURFACE rules — the source/*-isolation detectors that judge the
+ * public query/mutation surface (R-50 read-isolation, R-51 write-isolation).
+ * Reported APART from the document/oracle/process rules (R-32, R-37, R-40,
+ * R-48, …) so the handler-surface could-not-judge count is visible on its own
+ * and can be driven to 0 without conflating it with honest human-gate CNJ.
+ * Laurent doctrine: an instrument that cannot go red protects nothing — the
+ * handler-surface CNJ must reach 0 except genuine parse-fail / marker-borne /
+ * ambiguous-domination sites.
+ */
+export const HANDLER_SURFACE_RULES = ["R-50", "R-51"];
+// The per-rule breakdown token every source detect() emits: `could-not-judge=N`.
+// The site figure is the sum of N across the handler-surface rules' results — the
+// same N that names the sites under decide()'s CNJ label, never a re-derivation.
+const CNJ_SITES_IN_VERDICT = /could-not-judge=(\d+)/;
+/**
+ * The handler-surface slice of the tally, computed over HANDLER_SURFACE_RULES
+ * only. Reduces each rule to its worst result state (same reduction as `tally`)
+ * so a rule with any non-conforming result reads non-conforming, and surfaces a
+ * distinct handler-surface could-not-judge count the CLI prints separately.
+ */
+export function handlerSurfaceStats(results, handlerRules = HANDLER_SURFACE_RULES) {
+    const set = new Set(handlerRules);
+    const ruleState = new Map();
+    // Sites abstaining is summed over the RAW results (before the rule reduction),
+    // so a non-conforming rule's abstaining sites are still counted — one entry per
+    // rule's single reduced result here, but robust to multi-result rules.
+    const cnjSitesByRule = new Map();
+    for (const r of results) {
+        const id = ruleIdOf(r);
+        if (!set.has(id))
+            continue;
+        const prev = ruleState.get(id);
+        if (prev === undefined || STATE_RANK[r.state] > STATE_RANK[prev]) {
+            ruleState.set(id, r.state);
+        }
+        const m = CNJ_SITES_IN_VERDICT.exec(r.verdict);
+        if (m)
+            cnjSitesByRule.set(id, (cnjSitesByRule.get(id) ?? 0) + Number(m[1]));
+    }
+    const byState = {
+        present: 0,
+        "non-conforming": 0,
+        "could-not-judge": 0,
+        absent: 0,
+    };
+    for (const s of ruleState.values())
+        byState[s] += 1;
+    let sitesAbstaining = 0;
+    for (const n of cnjSitesByRule.values())
+        sitesAbstaining += n;
+    return {
+        byState,
+        ruleState,
+        couldNotJudge: byState["could-not-judge"],
+        sitesAbstaining,
+    };
+}
+/** The one-line handler-surface tally string the CLI prints, apart from the
+ *  document/oracle/process rules. */
+export function handlerSurfaceLine(s) {
+    const ids = [...s.ruleState.entries()]
+        .map(([id, st]) => `${id}=${st}`)
+        .join(", ");
+    return (`HANDLER-SURFACE TALLY (${HANDLER_SURFACE_RULES.join("+")}, reported apart from doc/oracle/process rules): ` +
+        `present=${s.byState.present} non-conforming=${s.byState["non-conforming"]} ` +
+        `could-not-judge=${s.byState["could-not-judge"]} absent=${s.byState.absent}` +
+        `${ids ? ` [${ids}]` : ""} | rules abstaining=${s.couldNotJudge} | sites abstaining=${s.sitesAbstaining}`);
+}
 /** The one-line machine tally string the CLI prints. */
 export function tallyLine(t) {
     return (`TALLY (by rule, ${t.ruleTotal} rules from ${t.resultTotal} results): ` +

package/dist/target.d.ts

@@ -0,0 +1,32 @@
+import type { Detector, Tree } from "./engine-types.js";
+export interface TargetScope {
+    /** the argument as given, resolved to an absolute path. */
+    input: string;
+    /** the repository root every `rel` is computed against. */
+    repoRoot: string;
+    /** which marker made `repoRoot` the root. */
+    repoRootBy: "package.json" | ".git" | "no marker (argument used as-is)";
+    /** the convex functions dir, or undefined when the repository has none. */
+    convexDir: string | undefined;
+    /** the directories actually walked, absolute, in order. */
+    scanRoots: string[];
+}
+/** Resolve a CLI argument to the backend it names. Pure over the filesystem. */
+export declare function resolveTarget(arg: string): TargetScope;
+/** The ONE tree every detector judges: the scan roots' files, `rel` relative to
+ * the repository root, `root` = the repository root. */
+export declare function loadScopedTree(scope: TargetScope): Tree;
+/** Files scanned per top-level directory (two segments under the repo root), so a
+ * reader sees WHAT was judged — an empty or surprising surface is visible. */
+export declare function coverageInventory(tree: Tree): Map<string, number>;
+export declare function describeScope(scope: TargetScope, tree: Tree): string;
+/** Wrap detectors so each judges the scoped tree instead of the engine's
+ * per-argument tree. runDoctor still owns the loud-fail contract. */
+export declare function onScopedTree(tree: Tree, detectors: Detector[]): Detector[];
+/** Absolute convex dir for a scoped tree (tree.root = repo root) or for a tree
+ * rooted AT a convex dir (direct detector tests). `prefix` is what the tree's
+ * rels carry in front of a convex-relative path. */
+export declare function convexRootOf(tree: Tree): {
+    dir: string;
+    prefix: string;
+};

package/dist/target.js

@@ -0,0 +1,173 @@
+// TARGET RESOLUTION — the run judges the same backend whichever path names it.
+//
+// The defect this closes: the engine's loadTree computes every file's `rel`
+// relative to the path the CLI was given, so the SAME repository produced two
+// different trees under the two documented invocations:
+//   - `backend-doctor <repo>/convex` → rels `messages.ts` (no `convex/` segment)
+//   - `backend-doctor <repo>`        → rels `convex/messages.ts`, PLUS every other
+//     `.ts` file in the repository, including archived copies such as
+//     `_archive-v0.2/<shell>/convex/*.ts` that a `(^|/)convex/` predicate then
+//     judged as live backend source.
+// Detectors keyed on the `convex/` prefix skipped every file in the first form and
+// over-counted in the second; R-36 looked for the lockfile beside `convex/`; CR-1
+// looked for `_generated/api.d.ts` beside the repository root. Measured on vCRM
+// d47a6d4: R-16 2 vs 50 violations, R-6 could-not-judge vs 19 violations.
+//
+// The fix is ONE normalisation at the entry, never a per-detector patch:
+//   repoRoot   nearest ancestor-or-self holding package.json or .git (a `convex`
+//              dir itself is never the repo root, even when it holds a package.json)
+//   convexDir  the `convex` segment the argument names, else <repoRoot>/convex
+//   scanRoots  convexDir and <repoRoot>/mcp-server/src (the two source surfaces the
+//              detectors' own predicates name), each loaded by the ENGINE's loader
+//   rel        relative to repoRoot, so every convex file carries `convex/`
+//   tree.root  repoRoot, so repository co-artifacts (lockfile, workflows) are found
+// Both invocations therefore reduce to the same (repoRoot, convexDir, files) triple.
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { runDoctor } from "@vantageos/mcp-doctor";
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function hasRepoMarker(dir) {
+    return existsSync(join(dir, "package.json")) || existsSync(join(dir, ".git"));
+}
+/** The `convex` dir the argument is (or sits inside), found walking UP from it and
+ * stopping at the first repository marker — so a repository that merely lives
+ * under some `/…/convex/…` host path is never mistaken for a convex dir. */
+function namedConvexDir(p) {
+    for (let dir = p;; dir = dirname(dir)) {
+        if (basename(dir) === "convex")
+            return dir;
+        if (hasRepoMarker(dir) || dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** Resolve a CLI argument to the backend it names. Pure over the filesystem. */
+export function resolveTarget(arg) {
+    const input = resolve(arg);
+    const named = namedConvexDir(input);
+    const start = named ? dirname(named) : input;
+    let repoRoot = start;
+    let repoRootBy = "no marker (argument used as-is)";
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json"))) {
+            repoRoot = dir;
+            repoRootBy = "package.json";
+            break;
+        }
+        if (existsSync(join(dir, ".git"))) {
+            repoRoot = dir;
+            repoRootBy = ".git";
+            break;
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    const convexDir = named && isDir(named)
+        ? named
+        : isDir(join(repoRoot, "convex"))
+            ? join(repoRoot, "convex")
+            : undefined;
+    const scanRoots = [];
+    if (convexDir) {
+        scanRoots.push(convexDir);
+        const mcpSrc = join(repoRoot, "mcp-server", "src");
+        if (isDir(mcpSrc))
+            scanRoots.push(mcpSrc);
+    }
+    else {
+        // No convex dir anywhere: judge exactly what was named, never a guess.
+        scanRoots.push(input);
+    }
+    return { input, repoRoot, repoRootBy, convexDir, scanRoots };
+}
+/** Load one directory through the ENGINE's own loader (never a second traversal
+ * with its own skip list): a capture detector receives the tree runDoctor built. */
+function engineTree(root) {
+    let captured;
+    runDoctor(root, [
+        {
+            id: "target-capture",
+            run: (tree) => {
+                captured = tree;
+                return {
+                    id: "target-capture",
+                    anchor: root,
+                    state: "present",
+                    verdict: "captured",
+                };
+            },
+        },
+    ]);
+    if (captured === undefined) {
+        throw new Error(`backend-doctor: the engine loaded no tree for ${root} — refusing to judge a surface that was never read`);
+    }
+    return captured;
+}
+/** The ONE tree every detector judges: the scan roots' files, `rel` relative to
+ * the repository root, `root` = the repository root. */
+export function loadScopedTree(scope) {
+    const files = [];
+    let packageJson = null;
+    for (const root of scope.scanRoots) {
+        const t = engineTree(root);
+        packageJson ??= t.packageJson;
+        for (const f of t.files) {
+            const rel = relative(scope.repoRoot, f.path);
+            files.push({ ...f, rel: rel === "" ? basename(f.path) : rel });
+        }
+    }
+    return { root: scope.repoRoot, files, packageJson };
+}
+/** Files scanned per top-level directory (two segments under the repo root), so a
+ * reader sees WHAT was judged — an empty or surprising surface is visible. */
+export function coverageInventory(tree) {
+    const inv = new Map();
+    for (const f of tree.files) {
+        const parts = f.rel.split("/");
+        const key = parts.length > 2
+            ? `${parts[0]}/${parts[1]}`
+            : parts.length === 2
+                ? parts[0]
+                : ".";
+        inv.set(key, (inv.get(key) ?? 0) + 1);
+    }
+    return new Map([...inv.entries()].sort((a, b) => a[0].localeCompare(b[0])));
+}
+export function describeScope(scope, tree) {
+    const lines = [
+        `TARGET: ${scope.input}`,
+        `  repo root: ${scope.repoRoot} (by ${scope.repoRootBy})`,
+        `  convex dir: ${scope.convexDir ?? "NONE — no convex/ dir under the repo root; judging the argument as given"}`,
+        `COVERAGE INVENTORY (files scanned per dir, rel to repo root; ${tree.files.length} total):`,
+    ];
+    const inv = coverageInventory(tree);
+    if (inv.size === 0)
+        lines.push("  scanned NOTHING — every source rule below abstains on an empty scan");
+    for (const [dir, n] of inv)
+        lines.push(`  scanned ${dir}: ${n}`);
+    return lines.join("\n");
+}
+/** Wrap detectors so each judges the scoped tree instead of the engine's
+ * per-argument tree. runDoctor still owns the loud-fail contract. */
+export function onScopedTree(tree, detectors) {
+    return detectors.map((d) => ({ ...d, run: () => d.run(tree) }));
+}
+/** Absolute convex dir for a scoped tree (tree.root = repo root) or for a tree
+ * rooted AT a convex dir (direct detector tests). `prefix` is what the tree's
+ * rels carry in front of a convex-relative path. */
+export function convexRootOf(tree) {
+    if (existsSync(join(tree.root, "_generated")) ||
+        basename(tree.root) === "convex") {
+        return { dir: tree.root, prefix: "" };
+    }
+    const dir = join(tree.root, "convex");
+    if (isDir(dir))
+        return { dir, prefix: "convex/" };
+    return { dir: tree.root, prefix: "" };
+}

package/fixtures/cr1-classes/_generated/api.d.ts

@@ -0,0 +1,24 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility — a MINIMAL, hand-kept replica of the shape
+ * `npx convex dev` emits, so CR-1's population parser is exercised on the real
+ * artefact shape (the `import type * as` map plus the `fullApi` member list) without
+ * this repository depending on the Convex CLI. See fixtures/cr1-classes/surface.ts.
+ * @module
+ */
+
+import type * as surface from "../surface.js";
+
+declare const fullApi: ApiFromModules<{
+  surface: typeof surface;
+}>;
+
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;

package/fixtures/cr1-classes/surface.ts

@@ -0,0 +1,206 @@
+// CR-1's BIPOLAR PER-CLASS fixture. One member of each of the four classes, plus one
+// `internalQuery` whose exclusion CR-1 must prove from the builder token at its own
+// site. Every member is deliberately minimal: exactly one discriminator distinguishes
+// it from its neighbouring class, so tests/caller-resolution.test.ts can delete that
+// one discriminator and watch the member MIGRATE. Do not "tidy" this file — each line
+// that looks redundant is a pole.
+
+// ─── the tree's own helpers, which CR-1 derives (never a name list) ───────────
+
+/** A GATE: consults the verified principal and REFUSES on its absent path. */
+async function requireCaller(ctx: Ctx): Promise<void> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (!identity) {
+		throw new Error("RBAC_DENIED: no verified principal.");
+	}
+}
+
+/** A RESOLVER: consults the principal and RETURNS a scope; the absent path is a
+ *  typed empty scope, so the handler that calls it must use what it returns. */
+async function resolveScope(ctx: Ctx): Promise<{ orgSlug: string | null }> {
+	const identity = await ctx.auth.getUserIdentity();
+	if (!identity) {
+		return { orgSlug: null };
+	}
+	return { orgSlug: String(identity.organizationSlug) };
+}
+
+// ─── RESOLVES — a gate refuses on the absent-identity path before any read ────
+
+export const resolvesMember = query({
+	args: {},
+	handler: async (ctx) => {
+		await requireCaller(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── FAIL-OPEN — the resolver's result is bound and never read again ──────────
+
+export const failOpenMember = query({
+	args: {},
+	handler: async (ctx) => {
+		// biome-ignore lint/correctness/noUnusedVariables: the UNUSED binding IS the pole —
+		// this fixture member exists to be a resolved principal that is then discarded.
+		// Renaming it `_scope` would delete the discriminator the FAIL-OPEN class is about.
+		const scope = await resolveScope(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── NO-IDENTITY — serves data, consults no principal, no justification ──────
+
+export const noIdentityMember = query({
+	args: {},
+	handler: async (ctx) => {
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── NO-DATA — touches no data, and says why, in this source ──────────────────
+
+// allow-no-caller-resolution: returns the deployment's build constant only; it
+// reads no table, no storage and no other function, so there is no caller-scoped
+// datum for a principal to scope.
+export const noDataMember = query({
+	args: {},
+	handler: async () => {
+		return { build: "fixture" };
+	},
+});
+
+// ─── RESOLVES through a DECLARE-THEN-ASSIGN gate, the shape a reviewer's ──────
+// ─── probe caught the matcher failing to read ─────────────────────────────────
+//
+// ORIGIN, cited rather than invented: this is the shape of
+// `requireServiceAccount` in vantageos-agency/vantage-peers
+// convex/oauth.ts @ 40c71cb55721d99d3bed17058fdc10281103b158 — the local is
+// DECLARED on its own line precisely so the resolution can sit inside a `try`
+// and re-raise naming its own door, then the authority test follows.
+//
+// The matcher originally required the `=` to follow the declarator on one
+// statement, so every gate written this way read as ABSENT and SEVEN correctly
+// service-account-gated oauth handlers were classed FAIL-OPEN. Measured on that
+// same tree: FAIL-OPEN 11 -> 4 and RESOLVES 139 -> 146 once the shape is read,
+// with the classified total unchanged at 179.
+//
+// This site asserts RESOLVES. It is a fixture rather than a unit assertion
+// because the defect was in the POPULATION-wide read, not in one predicate.
+
+export const resolvesViaDeclareThenAssignGate = query({
+	args: {},
+	handler: async (ctx) => {
+		await requireServiceAccountShim(ctx, "fixture:resolvesViaDeclareThenAssignGate");
+		// It must TOUCH DATA, or CR-1 classes it NO-DATA and the gate question is
+		// moot — which is what happened on the first draft of this fixture, and
+		// is itself the instrument behaving correctly.
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+async function requireServiceAccountShim(
+	ctx: Ctx,
+	registration: string,
+): Promise<void> {
+	let scope: { isMaster: boolean } | undefined;
+	try {
+		scope = await resolveScopeShim(ctx);
+	} catch (err: unknown) {
+		throw new Error(`RBAC_DENIED: "${registration}" unresolved-caller`);
+	}
+	if (!scope?.isMaster) {
+		throw new Error(`RBAC_DENIED: "${registration}" not-the-service-account`);
+	}
+}
+
+async function resolveScopeShim(ctx: Ctx): Promise<{ isMaster: boolean }> {
+	const identity = await ctx.auth.getUserIdentity();
+	return { isMaster: identity !== null };
+}
+
+// ─── FAIL-OPEN in the SAME declare-then-assign shape — the WIDENING pole ──────
+//
+// WHY THIS EXISTS, and it is the pole that decides whether the shape above is a
+// fix or a hole. `resolvesViaDeclareThenAssignGate` proves the matcher READS
+// declare-then-assign. It does NOT prove the matcher still REFUSES when such a
+// binding is never tested. A reviewer's mutant made every declare-then-assign
+// binding count as a gate regardless of any refusal, and it SURVIVED the whole
+// suite — 465/465, and the real-tree FAIL-OPEN count unmoved at 4. So
+//   let s; s = await resolver(ctx); return ctx.db…
+// with no test of `s` would have read as RESOLVES.
+//
+// The widening direction of a security detector is the direction that hides a
+// leak, and it was the untested one. This site is identical to its sibling in
+// SHAPE and differs only in the thing that matters: the resolved value decides
+// NOTHING before the data is served. It must class FAIL-OPEN and appear in
+// violations().
+
+export const failsOpenViaDeclareThenAssignNoTest = query({
+	args: {},
+	handler: async (ctx) => {
+		// Declared on its own line, assigned inside a try — the shape the matcher
+		// now reads — and then the binding is simply never consulted.
+		let scope: { isMaster: boolean } | undefined;
+		try {
+			scope = await resolveScopeShim(ctx);
+		} catch {
+			// swallowed: not a refusal. The caller is resolved and discarded.
+		}
+		void scope;
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── the pole that actually kills the widening mutant ─────────────────────────
+//
+// WHY THE PREVIOUS POLE WAS NOT ENOUGH, measured rather than guessed. The
+// reviewer's mutant W makes any declare-then-assign binding count as a REFUSAL,
+// which promotes the enclosing function to a GATE. `failsOpenViaDeclareThenAssign
+// NoTest` above is classed FAIL-OPEN on its own body and stays FAIL-OPEN under W,
+// so it does not bite: W's damage lands on whoever TRUSTS a wrongly-promoted
+// gate, not on the promoted function itself.
+//
+// So the pole has to be the site that DELEGATES its authority to such a helper.
+// `pretendGateDeclareThenAssignNoTest` below is in the declare-then-assign shape
+// and never tests what it resolved — it is not a gate. A registration whose only
+// authority is that helper is therefore FAIL-OPEN. Under W the helper is promoted
+// and the registration reads RESOLVES: a leak classified as safe, which is the
+// single outcome a security detector must never produce.
+
+export const failsOpenBehindAPretendGate = query({
+	args: {},
+	handler: async (ctx) => {
+		await pretendGateDeclareThenAssignNoTest(ctx);
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+async function pretendGateDeclareThenAssignNoTest(ctx: Ctx): Promise<void> {
+	// Declared on its own line, assigned inside a try — the shape the matcher now
+	// reads — and then NEVER consulted. Resolving is not refusing.
+	let scope: { isMaster: boolean } | undefined;
+	try {
+		scope = await resolveScopeShim(ctx);
+	} catch {
+		// swallowed on purpose: there is no refusal anywhere in this function.
+	}
+	void scope;
+}
+
+// ─── excluded — and the exclusion is proven by the builder token on THIS line ──
+
+export const internalMember = internalQuery({
+	args: {},
+	handler: async (ctx) => {
+		return await ctx.db.query("rows").collect();
+	},
+});
+
+// ─── minimal ambient shims so this fixture is readable TypeScript on its own ──
+
+interface Ctx {
+	auth: { getUserIdentity: () => Promise<Record<string, unknown> | null> };
+	db: { query: (t: string) => { collect: () => Promise<unknown[]> } };
+}
+declare function query<T>(config: T): T;
+declare function internalQuery<T>(config: T): T;

package/fixtures/cr1-empty/nothing.ts

@@ -0,0 +1 @@
+export const nothing = 1;

package/fixtures/cr1-refusal-on-resolved/_generated/api.d.ts

@@ -0,0 +1,24 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility — a MINIMAL, hand-kept replica of the shape
+ * `npx convex dev` emits (see fixtures/cr1-classes/_generated/api.d.ts). Only
+ * `doors` is listed: `lib/auth.ts` registers no public function, exactly as the
+ * product tree's `lib/auth` exposes none to CR-1's population.
+ * @module
+ */
+
+import type * as doors from "../doors.js";
+
+declare const fullApi: ApiFromModules<{
+  doors: typeof doors;
+}>;
+
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;