@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/cli.js

@@ -5,16 +5,22 @@
 // DISTINCTLY. The target is a real directory so the engine's loadTree succeeds;
 // the first-wave detectors ignore the tree and consult the oracle.
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderTable, runDoctor } from "@vantageos/mcp-doctor";
+import { parseArgs, USAGE } from "./args.js";
+import { checkDistFreshness } from "./build-stamp.js";
+import { CR1_ID, callerResolutionResult, callerResolutionSection, violations as crViolations, scanCallerResolution, } from "./caller-resolution.js";
 import { coverage, coverageSummary } from "./coverage.js";
+import { crudCoverageSection, extractReactRouterPaths, scanCrudCoverage, } from "./crud-coverage.js";
 import { checkStandardReadable } from "./detectors/standard/_doc.js";
-import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults } from "./not-checkable.js";
+import { NOT_MECHANICALLY_CHECKABLE, notCheckableResults, } from "./not-checkable.js";
+import { activateOracle, describeOracle, resolveOracle } from "./oracle.js";
 import { REGISTRY } from "./registry.js";
 import { writeReport } from "./report.js";
-import { tally, tallyLine, verdict } from "./tally.js";
+import { handlerSurfaceLine, handlerSurfaceStats, tally, tallyLine, verdict, } from "./tally.js";
+import { describeScope, loadScopedTree, onScopedTree, resolveTarget, } from "./target.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** `git -C <target> rev-parse HEAD`, or "not a git repo" when it is not one. */
 function targetCommit(target) {
@@ -42,8 +48,154 @@ function toolVersion() {
     const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
     return pkg.version;
 }
+/** Recursively collect files under `dir` whose basename matches `pred`, as paths
+ * relative to `base`. Silently skips node_modules/.git and unreadable dirs. */
+function collectFiles(dir, base, pred, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name === "node_modules" || name === ".git")
+            continue;
+        const full = join(dir, name);
+        let isDir;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            collectFiles(full, base, pred, out);
+        else {
+            const rel = relative(base, full);
+            if (pred(rel))
+                out.push(rel);
+        }
+    }
+    return out;
+}
+/** Read the convex tree + the schema + probe an app routes dir, then render the
+ * CRUD coverage section. The target is the convex dir; the app routes dir is a
+ * sibling probe (`../src/app`, `../app`, `../src/routes`). */
+function scanCrudCoverageForCli(target) {
+    const convexRels = collectFiles(target, target, (rel) => rel.endsWith(".ts") && !rel.endsWith(".test.ts"));
+    const files = [];
+    let schemaText;
+    for (const rel of convexRels) {
+        let text;
+        try {
+            text = readFileSync(join(target, rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        files.push({ rel, text });
+        if (/(^|\/)schema\.ts$/.test(rel))
+            schemaText = text;
+    }
+    return scanCrudCoverage(schemaText, files, probeRoutes(target));
+}
+/** Probe the app-route surface as a sibling of the convex `target` dir. Reports
+ * BOTH whether a candidate app/src routes dir EXISTS and the route paths found in
+ * it, so the scan can tell "no routes dir" (n/a) from "dir exists, no router
+ * convention recognised" (could-not-judge) — Eta REVISE blocker 3. Recognises
+ * Next/SvelteKit convention files AND a react-router `<Route path>` /
+ * `createBrowserRouter` router in App.tsx/main.tsx/a routes file. */
+function probeRoutes(target) {
+    const ROUTE_FILE = /(^|\/)(page\.tsx|route\.tsx?|\+page\.svelte)$/;
+    const appRoot = resolve(target, "..");
+    let candidateDir;
+    const routePaths = [];
+    // (a) Next/SvelteKit convention dirs (a sibling of the convex target).
+    for (const candidate of ["src/app", "app", "src/routes"]) {
+        const routeRoot = join(appRoot, candidate);
+        let isDir = false;
+        try {
+            isDir = statSync(routeRoot).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir)
+            continue;
+        if (candidateDir === undefined)
+            candidateDir = candidate;
+        routePaths.push(...collectFiles(routeRoot, routeRoot, (rel) => ROUTE_FILE.test(rel)));
+    }
+    // (b) react-router (Vite SPA): parse the router source for its route paths.
+    for (const rel of [
+        "src/App.tsx",
+        "src/main.tsx",
+        "src/routes.tsx",
+        "src/router.tsx",
+        "App.tsx",
+        "main.tsx",
+    ]) {
+        const full = join(appRoot, rel);
+        let text;
+        try {
+            text = readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // the src dir hosting the router is a candidate app dir, even if its own
+        // route-path extraction turns up empty (→ could-not-judge, never n/a).
+        if (candidateDir === undefined)
+            candidateDir = dirname(rel) || rel;
+        routePaths.push(...extractReactRouterPaths(text));
+    }
+    return { candidateDir, routePaths };
+}
 function main() {
-    const target = resolve(process.argv[2] ?? process.cwd());
+    // Refuse to judge from a dist/ compiled from other source than this checkout's
+    // (src/build-stamp.ts). Runs before anything is read, so no verdict is printed.
+    // Flags first: --version/--help answer without reading a target, and an unknown
+    // flag is a usage error — never a path handed to the filesystem (an `-v` used to
+    // become `<cwd>/-v` and die on an uncaught ENOENT stack).
+    const args = parseArgs(process.argv.slice(2));
+    if (args.kind === "version") {
+        console.log(toolVersion());
+        process.exit(0);
+    }
+    if (args.kind === "help") {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    if (args.kind === "usage-error") {
+        console.error(`backend-doctor: ${args.message}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    const fresh = checkDistFreshness(here);
+    if (!fresh.ok) {
+        console.error(`backend-doctor: REFUSING TO RUN — ${fresh.reason}`);
+        process.exit(2);
+    }
+    const target = resolve(args.positional[0] ?? process.cwd());
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        console.error(`backend-doctor: target ${target} is not a readable directory — could not judge.\n\n${USAGE}`);
+        process.exit(2);
+    }
+    // ONE normalisation (src/target.ts): `convex` and `.` resolve to the same repo
+    // root, convex dir and file set, so every rule sees the same rels either way.
+    const scope = resolveTarget(target);
+    const tree = loadScopedTree(scope);
+    console.log(describeScope(scope, tree));
+    // The oracle is DERIVED from the target (never from this tool's own install
+    // directory) and the run says which file it used and where that came from.
+    // Absent => the oracle-backed rules refuse to judge (could-not-judge).
+    const oracleSel = resolveOracle(target, {
+        oracle: args.flags.oracle,
+        vrOracle: args.flags["vr-oracle"],
+        writerTier: args.flags["writer-tier"],
+    });
+    activateOracle(oracleSel);
+    console.log(describeOracle(oracleSel));
     // Instrument self-check, BEFORE any judging: a backend-doctor run reads its
     // pinned standard fixture as material. If that fixture is absent/unreadable the
     // tool cannot judge — REFUSE with exit 2 (could-not-judge) naming what it could
@@ -58,10 +210,43 @@ function main() {
     // pending detector) — so the tally's rule total equals the 48 derived rules and
     // nothing is silently dropped.
     const results = [
-        ...runDoctor(target, REGISTRY.map((e) => e.detector)),
+        ...runDoctor(scope.repoRoot, onScopedTree(tree, REGISTRY.map((e) => e.detector))),
         ...notCheckableResults(),
     ];
-    console.log(renderTable("backend-doctor (VantagePeers oracle @ day158)", results));
+    console.log(renderTable("backend-doctor (oracle derived from target)", results));
+    // CRUD COVERAGE — an inventory/coverage report DIMENSION (not a numbered rule
+    // in the pinned 50-rule standard). Rows are EVERY defineTable table derived
+    // from the target schema at run time; the union of rows MUST equal the schema
+    // table set or the run is RED (fail-closed).
+    console.log("");
+    const crud = scanCrudCoverageForCli(scope.convexDir ?? target);
+    console.log(crudCoverageSection(crud));
+    const crudDefect = crud.status === "unreadable" || !crud.unionEqualsSchema;
+    // CALLER RESOLUTION (CR-1) — a DOCTOR-OWNED CRITICAL control, reported in its own
+    // section for the same reason CRUD coverage is: the pinned standard numbers
+    // R-1..R-51 and does not define it, so putting it in REGISTRY would make
+    // coverage.ts report a phantom rule and would forge the standard's pin. It is run
+    // through the engine's OWN loader (never a second tree traversal) and its
+    // violations drive the exit code — an unjustified NO-IDENTITY or a FAIL-OPEN
+    // registration is mechanical, so the gate refuses on it.
+    console.log("");
+    let crScan;
+    runDoctor(scope.repoRoot, onScopedTree(tree, [
+        {
+            id: CR1_ID,
+            run: (t) => {
+                crScan = scanCallerResolution(t);
+                return callerResolutionResult(crScan);
+            },
+        },
+    ]));
+    if (crScan === undefined) {
+        console.error("CR-1: the engine did not run the caller-resolution detector — refusing to report a surface that was never scanned.");
+        process.exit(2);
+    }
+    console.log(callerResolutionSection(crScan));
+    const crResult = callerResolutionResult(crScan);
+    const crDefect = crViolations(crScan).length > 0;
     console.log("");
     const cov = coverage();
     console.log(coverageSummary(cov));
@@ -82,6 +267,11 @@ function main() {
     const v = verdict(t, results);
     console.log("");
     console.log(tallyLine(t));
+    // The handler-surface slice (R-50/R-51) reported APART from the doc/oracle/
+    // process rules, so its could-not-judge count is visible on its own and can be
+    // driven to 0 (Laurent: an instrument that cannot go red protects nothing).
+    console.log(handlerSurfaceLine(handlerSurfaceStats(results)));
+    console.log(`CALLER-RESOLUTION TALLY (CR-1, doctor-owned, outside the pinned rule set): state=${crResult.state} violations=${crViolations(crScan).length} | ${crResult.verdict.split("\n")[0]}`);
     console.log(v.summary);
     if (v.criticalViolations > 0) {
         console.log(`  critical violations: ${v.violations.critical.join(", ")}`);
@@ -93,18 +283,35 @@ function main() {
     // the git facts are gathered HERE (a real process) and handed to the pure writer.
     const ctx = {
         target,
-        targetCommit: targetCommit(target),
+        targetCommit: targetCommit(scope.repoRoot),
         toolVersion: toolVersion(),
         dateISO: new Date().toISOString().slice(0, 10),
-        treeStatus: treeStatus(target),
+        treeStatus: treeStatus(scope.repoRoot),
+        oracle: describeOracle(oracleSel),
     };
     const reportDir = join(here, "..", "reports");
-    const path = writeReport(ctx, results, t, v, reportDir);
+    const path = writeReport(ctx, results, t, v, reportDir, undefined, [
+        callerResolutionSection(crScan),
+    ]);
     console.log(`\nreport written: ${path}`);
     if (!cov.ok) {
         console.log("\nNOTE: coverage is INCOMPLETE — a rule is in neither bucket. See the summary above.");
         process.exit(1);
     }
+    // The CRUD coverage self-check is fail-closed: an unreadable schema or a rows
+    // union that does not cover the schema tables is a DOCTOR DEFECT → RED, never a
+    // silent pass. (ABSENT cells are honest reported gaps, NOT a defect.)
+    if (crudDefect) {
+        console.log("\nNOTE: CRUD coverage self-check FAILED — the rows do not cover every schema table (or the schema is unreadable). See the CRUD COVERAGE section above.");
+        process.exit(1);
+    }
+    // CR-1 is CRITICAL: a FAIL-OPEN or unjustified NO-IDENTITY public registration is
+    // a mechanical violation, so the gate refuses on it even when every numbered rule
+    // is satisfied. Reported BEFORE the numbered-rule exit so the reason is legible.
+    if (crDefect) {
+        console.log(`\nNOTE: CR-1 (caller resolution) FAILED — ${crViolations(crScan).length} public registration(s) serve or write data without resolving their caller. CRITICAL, no bypass. See the CALLER RESOLUTION section above; every member is named there.`);
+        process.exit(1);
+    }
     process.exit(v.exitCode);
 }
 main();

package/dist/coverage-cli.js

@@ -2,8 +2,16 @@
 // Prints the coverage proof over the TWO buckets — CHECKED and
 // NOT_MECHANICALLY_CHECKABLE. Exits non-zero only if the union does not equal
 // the derived rule ids (a rule in no bucket, in two, or a stale bucket entry).
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkDistFreshness } from "./build-stamp.js";
 import { coverage, coverageSummary } from "./coverage.js";
 import { NOT_MECHANICALLY_CHECKABLE } from "./not-checkable.js";
+const fresh = checkDistFreshness(dirname(fileURLToPath(import.meta.url)));
+if (!fresh.ok) {
+    console.error(`backend-doctor --coverage: REFUSING TO RUN — ${fresh.reason}`);
+    process.exit(2);
+}
 const r = coverage();
 console.log(coverageSummary(r));
 console.log("");

package/dist/crud-coverage.d.ts

@@ -0,0 +1,81 @@
+/** A convex source file, reconstructed as text — the unit the scanner reads. */
+export interface SourceFile {
+    rel: string;
+    text: string;
+}
+/** Each cell is exactly one of these. `n/a: <reason>` (a MEASURED absence — there
+ *  is genuinely no candidate routes dir) and `could-not-judge: <reason>` (a
+ *  candidate dir EXISTS but no router convention was recognised, so presence was
+ *  NOT measured) are DISTINCT — `n/a` must never stand for an unmeasured cell. */
+export type Cell = "present" | "ABSENT" | `n/a: ${string}` | `could-not-judge: ${string}`;
+/**
+ * The app-route probe the CLI gathers from the filesystem and hands to the scan.
+ * It carries the two facts the cell disposition turns on: whether a candidate
+ * app/src routes dir EXISTS at all, and the normalized route paths recognised in
+ * it (Next/SvelteKit convention file rels AND react-router `<Route path>` /
+ * `createBrowserRouter` paths). The distinction closes Eta REVISE blocker 3:
+ * `n/a` asserts absence, but the pre-fix probe only knew its OWN matcher found
+ * nothing — a full react-router dir rendered n/a, a false assertion of absence.
+ */
+export interface RouteProbe {
+    /** a candidate app/src routes dir that EXISTS on disk, named — undefined iff
+     *  there is genuinely no candidate routes dir at all (the only `n/a` case). */
+    candidateDir?: string;
+    /** normalized route path strings — Next/SvelteKit file rels OR react-router
+     *  paths. Non-empty means a router WAS recognised and cells are judged. */
+    routePaths: string[];
+}
+/** Extract react-router route paths from a router source (App.tsx / main.tsx /
+ *  a routes file): both the `<Route path="…">` element form and the
+ *  `createBrowserRouter([{ path: "…" }])` object form. Deduped. */
+export declare function extractReactRouterPaths(text: string): string[];
+export interface TableRow {
+    table: string;
+    create: Cell;
+    get: Cell;
+    update: Cell;
+    remove: Cell;
+    list: Cell;
+    detail: Cell;
+    edit: Cell;
+}
+export interface AbsentCell {
+    table: string;
+    column: string;
+}
+export interface CrudCoverage {
+    status: "ok" | "unreadable";
+    /** set when status === "unreadable" — names what could not be read. */
+    reason?: string;
+    rows: TableRow[];
+    rowCount: number;
+    schemaTableCount: number;
+    unionEqualsSchema: boolean;
+    absentCells: AbsentCell[];
+}
+export declare function deriveTableNames(schemaText: string): string[];
+/** One public query/mutation, with the three attribution inputs: the file it
+ * lives in, its export name, its `args:` validator text (for `v.id("<table>")`)
+ * and its handler body text (for the `ctx.db.*` op it performs). */
+export interface Handler {
+    /** module basename, lower-cased, no `.ts` (e.g. `tasks`). */
+    fileBase: string;
+    /** the export name (e.g. `get`, `update`, `remove`). */
+    exportName: string;
+    /** the `args:` object literal source text (may be ""). */
+    argsText: string;
+    /** the `handler:` function source text (may be ""). */
+    body: string;
+}
+/** Every PUBLIC query/mutation exported from one module, with its attribution
+ * inputs. Non-exported / internal* builders are excluded. */
+export declare function publicHandlers(name: string, text: string): Handler[];
+export declare function scanCrudCoverage(schemaText: string | undefined, files: SourceFile[], routeFiles: string[] | RouteProbe): CrudCoverage;
+export declare function coverageUnionOk(schemaTables: string[], rows: {
+    table: string;
+}[]): {
+    ok: boolean;
+    missing: string[];
+};
+export declare function crudCoverageSection(cov: CrudCoverage): string;
+export declare function crudCoverageLine(cov: CrudCoverage): string;