@vantageos/backend-doctor 0.1.0

package/dist/detectors/standard/r46-returns-validator.js

@@ -0,0 +1,474 @@
+// R-46 — a read path's returns validator is DERIVED from its table's schema,
+// never a hand-written restatement. §16 line 445 (backend standard @ a9d7877b):
+// "the returns validator's field set, derived from `schema.ts`, equals the
+//  schema's writable field set, or a shortfall carries a written projection
+//  reason (red: a schema field writable by some path, absent from the returns
+//  validator, with no projection reason; or a validator authored as a literal
+//  list rather than derived)."
+//
+// THE CLASS THE FLEET PAID FOR (2026-08-19 get_task P0, origin e9a6a7e): a
+// Convex `returns:` validator that enumerates a stored document (declares
+// `_id: v.id("<table>")`) but OMITS a field the table's schema.ts declares. Any
+// row carrying that field throws ReturnsValidationError at runtime — the row is
+// unreadable through that path while still writable and still readable through
+// others. Nothing in the platform compares a returns validator to the schema it
+// claims to describe; THIS detector is that comparison.
+//
+// This is the LIFT of vantage-peers' returnsValidatorSchemaCoverage.test.ts out
+// of one repository into the instrument, so R-46 is measured on EVERY backend
+// the doctor is pointed at, not rediscovered per repo at production cost. The
+// four traps this lift refuses (each one the fleet already paid for):
+//
+//   1. The field set is DERIVED from the TARGET backend's schema.ts at analysis
+//      time — never a list this detector carries. A carried list is the
+//      hand-written restatement R-46 itself forbids, one layer up; it rots the
+//      first time a field is added. deriveSchemaFields re-reads the target's
+//      schema every run.
+//   2. Every document-returning validator in scope is ANALYSED (COVERS) or
+//      SKIPPED-with-a-written-reason (a `returns-projection:` marker IN THE
+//      TARGET SOURCE) — no third state. What is neither analysed nor
+//      exempted-in-writing FAILS. The exemption is read from the target, not an
+//      allowlist the detector keeps about itself (that allowlist is the very
+//      thing that does not travel to a second backend).
+//   3. A file that cannot be parsed is a FINDING (could-not-judge naming it),
+//      never a silent pass — "did not look" and "found nothing" must not both
+//      return green.
+//   4. The engine's existing four-state exit contract is honoured
+//      (non-conforming / could-not-judge / present / absent) — no fifth state,
+//      no second mechanism: the detector reads the tree the engine hands it.
+import * as ts from "typescript";
+/** The standard this detector is pinned against (the re-pinned instrument pin). */
+export const R46_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §16 R-46";
+// ---------------------------------------------------------------------------
+// tree → text. The engine split each file on "\n"; join reproduces it exactly.
+// We parse the TARGET the engine loaded — never re-read the filesystem (that is
+// the second-mechanism trap). Reconstructing from tree.files keeps R-46 on the
+// engine contract, and lets the mutation probe inject a synthetic tree.
+// ---------------------------------------------------------------------------
+export function fileText(f) {
+    return f.lines.map((l) => l.raw).join("\n");
+}
+function parseText(name, text) {
+    return ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+/** basename of a `rel` path, lower-cased. */
+function base(rel) {
+    return (rel.split("/").pop() ?? rel).toLowerCase();
+}
+/** a file we should judge — never a test or generated file. (The engine already
+ * drops *.test.ts; this also drops _generated and non-.ts.) */
+function isJudgeable(f) {
+    const b = base(f.rel);
+    return (b.endsWith(".ts") &&
+        !b.endsWith(".test.ts") &&
+        !f.rel.includes("__tests__") &&
+        !f.rel.includes("_generated/"));
+}
+/** the schema-definition file of the target backend, if present. */
+function isSchemaFile(f) {
+    return /(^|\/)schema\.ts$/.test(f.rel) && isJudgeable(f);
+}
+// ---------------------------------------------------------------------------
+// 1. Derive { tableName -> Set<fieldName> } from the target's schema.ts by
+//    parsing defineSchema({ ...defineTable({...}) }) with the TS compiler API.
+//    Re-read every run — add a field to schema.ts and this picks it up with zero
+//    edits here.
+// ---------------------------------------------------------------------------
+function objectLiteralKeys(obj) {
+    const keys = [];
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop) ||
+            ts.isShorthandPropertyAssignment(prop)) {
+            const name = prop.name;
+            if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+                keys.push(name.text);
+        }
+    }
+    return keys;
+}
+export function deriveSchemaFields(schemaText) {
+    const sf = parseText("schema.ts", schemaText);
+    const result = new Map();
+    function visit(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "defineSchema") {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    if (!ts.isPropertyAssignment(prop))
+                        continue;
+                    const nameNode = prop.name;
+                    const tableName = ts.isIdentifier(nameNode)
+                        ? nameNode.text
+                        : ts.isStringLiteral(nameNode)
+                            ? nameNode.text
+                            : undefined;
+                    if (!tableName)
+                        continue;
+                    // value is a `defineTable({...}).index(...).index(...)` chain — walk
+                    // down to the defineTable(...) call.
+                    let expr = prop.initializer;
+                    let defineTableCall;
+                    while (true) {
+                        if (ts.isCallExpression(expr) &&
+                            ts.isIdentifier(expr.expression) &&
+                            expr.expression.text === "defineTable") {
+                            defineTableCall = expr;
+                            break;
+                        }
+                        if (ts.isCallExpression(expr) &&
+                            ts.isPropertyAccessExpression(expr.expression)) {
+                            expr = expr.expression.expression;
+                            continue;
+                        }
+                        break;
+                    }
+                    if (defineTableCall) {
+                        const shape = defineTableCall.arguments[0];
+                        if (shape && ts.isObjectLiteralExpression(shape)) {
+                            result.set(tableName, new Set(objectLiteralKeys(shape)));
+                        }
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sf);
+    return result;
+}
+const QUERY_LIKE = new Set([
+    "query",
+    "mutation",
+    "internalQuery",
+    "internalMutation",
+]);
+/** Resolve `v.id("table")` -> "table" if node matches that shape. */
+function idTableName(node) {
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "id") {
+        const arg = node.arguments[0];
+        if (arg && ts.isStringLiteral(arg))
+            return arg.text;
+    }
+    return undefined;
+}
+export function extractDocMatches(name, text) {
+    const sf = parseText(name, text);
+    const matches = [];
+    const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+    const constMap = new Map();
+    function collectConsts(node) {
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer) {
+                    constMap.set(decl.name.text, decl.initializer);
+                }
+            }
+        }
+        ts.forEachChild(node, collectConsts);
+    }
+    collectConsts(sf);
+    function resolve(expr, depth = 0) {
+        if (depth > 10)
+            return expr;
+        if (ts.isIdentifier(expr) && constMap.has(expr.text)) {
+            return resolve(constMap.get(expr.text), depth + 1);
+        }
+        return expr;
+    }
+    function walkForDocObjects(expr, out, exportName, alias, span, depth = 0) {
+        if (depth > 20)
+            return;
+        const nextAlias = ts.isIdentifier(expr) ? expr.text : alias;
+        const resolved = resolve(expr);
+        if (ts.isCallExpression(resolved) &&
+            ts.isPropertyAccessExpression(resolved.expression)) {
+            const method = resolved.expression.name.text;
+            if (method === "object") {
+                const objArg = resolved.arguments[0];
+                if (objArg && ts.isObjectLiteralExpression(objArg)) {
+                    let table;
+                    for (const prop of objArg.properties) {
+                        if (ts.isPropertyAssignment(prop) &&
+                            ts.isIdentifier(prop.name) &&
+                            prop.name.text === "_id") {
+                            table = idTableName(resolve(prop.initializer));
+                        }
+                    }
+                    if (table) {
+                        out.push({
+                            exportName,
+                            alias: nextAlias,
+                            table,
+                            declaredKeys: new Set(objectLiteralKeys(objArg)),
+                            line: lineOf(objArg.getStart(sf)),
+                            exportStartLine: span.start,
+                            exportEndLine: span.end,
+                        });
+                    }
+                    for (const prop of objArg.properties) {
+                        if (ts.isPropertyAssignment(prop)) {
+                            walkForDocObjects(prop.initializer, out, exportName, undefined, span, depth + 1);
+                        }
+                    }
+                }
+                return;
+            }
+            if (method === "union" || method === "array" || method === "optional") {
+                for (const arg of resolved.arguments) {
+                    walkForDocObjects(arg, out, exportName, nextAlias, span, depth + 1);
+                }
+                return;
+            }
+        }
+    }
+    function visit(node) {
+        if (ts.isVariableStatement(node) &&
+            node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+            const span = {
+                start: lineOf(node.getStart(sf)),
+                end: lineOf(node.getEnd()),
+            };
+            for (const decl of node.declarationList.declarations) {
+                if (!ts.isIdentifier(decl.name) || !decl.initializer)
+                    continue;
+                const exportName = decl.name.text;
+                const init = decl.initializer;
+                if (ts.isCallExpression(init) &&
+                    ts.isIdentifier(init.expression) &&
+                    QUERY_LIKE.has(init.expression.text)) {
+                    const configArg = init.arguments[0];
+                    if (configArg && ts.isObjectLiteralExpression(configArg)) {
+                        for (const prop of configArg.properties) {
+                            if (ts.isPropertyAssignment(prop) &&
+                                ts.isIdentifier(prop.name) &&
+                                prop.name.text === "returns") {
+                                walkForDocObjects(prop.initializer, matches, exportName, undefined, span);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sf);
+    return matches;
+}
+// ---------------------------------------------------------------------------
+// 3. The projection exemption — read from the TARGET SOURCE, never an allowlist
+//    the detector carries. A shortfall is SKIPPED-with-a-written-reason iff a
+//    `returns-projection: <reason>` marker appears within the enclosing export's
+//    line span (a comment the author wrote, verified against the handler). The
+//    reason must be substantive (a bare marker is not a written reason).
+// ---------------------------------------------------------------------------
+const PROJECTION_MARKER = /returns-projection\s*:\s*(\S.*\S|\S)/i;
+const MIN_REASON_LEN = 12;
+export function projectionReason(rawLines, startLine, endLine) {
+    for (let n = startLine; n <= endLine && n <= rawLines.length; n++) {
+        const m = PROJECTION_MARKER.exec(rawLines[n - 1] ?? "");
+        if (m && m[1].trim().length >= MIN_REASON_LEN)
+            return m[1].trim();
+    }
+    return undefined;
+}
+/** Classify every document-returning validator in the target tree against the
+ * schema the target itself declares. */
+export function scanR46(files) {
+    const inventory = [];
+    const findings = [];
+    // Derive the schema field sets from the target's schema.ts (may be several,
+    // merged). A tree with no schema.ts yields no tables → schemaFound false.
+    const schemaFields = new Map();
+    let schemaFound = false;
+    for (const f of files) {
+        if (!isSchemaFile(f))
+            continue;
+        try {
+            const derived = deriveSchemaFields(fileText(f));
+            for (const [table, fset] of derived)
+                schemaFields.set(table, fset);
+            if (derived.size > 0)
+                schemaFound = true;
+        }
+        catch (e) {
+            findings.push({
+                rel: f.rel,
+                line: 1,
+                note: `schema.ts could not be parsed (${e.message}) — the field set cannot be derived; NOT a silent pass`,
+            });
+        }
+    }
+    for (const f of files) {
+        if (!isJudgeable(f) || isSchemaFile(f))
+            continue;
+        const moduleName = base(f.rel).replace(/\.ts$/, "");
+        let matches;
+        try {
+            matches = extractDocMatches(f.rel, fileText(f));
+        }
+        catch (e) {
+            findings.push({
+                rel: f.rel,
+                line: 1,
+                note: `module could not be parsed (${e.message}) — a validator here may go unchecked; NOT a silent pass`,
+            });
+            continue;
+        }
+        const rawLines = f.lines.map((l) => l.raw);
+        for (const m of matches) {
+            const label = m.alias
+                ? `${moduleName}.${m.exportName}#${m.alias}`
+                : `${moduleName}.${m.exportName}`;
+            const declared = schemaFields.get(m.table);
+            if (!declared) {
+                // A validator declares v.id("<table>") for a table the schema does not
+                // define — cannot judge coverage; a finding, never a silent pass.
+                findings.push({
+                    rel: f.rel,
+                    line: m.line,
+                    note: `${label} returns a document of "${m.table}", a table not found in the target schema — coverage cannot be derived`,
+                });
+                continue;
+            }
+            const missing = [...declared].filter((k) => !m.declaredKeys.has(k));
+            if (missing.length === 0) {
+                inventory.push({
+                    rel: f.rel,
+                    line: m.line,
+                    label,
+                    table: m.table,
+                    status: "COVERS",
+                    missing: [],
+                });
+                continue;
+            }
+            // include the contiguous leading-comment block above the export — the
+            // natural place a `returns-projection:` reason is written for the read path.
+            let leadStart = m.exportStartLine;
+            while (leadStart > 1) {
+                const prev = (rawLines[leadStart - 2] ?? "").trim();
+                if (prev.startsWith("//") ||
+                    prev.startsWith("*") ||
+                    prev.startsWith("/*")) {
+                    leadStart -= 1;
+                }
+                else
+                    break;
+            }
+            const reason = projectionReason(rawLines, leadStart, m.exportEndLine);
+            if (reason) {
+                inventory.push({
+                    rel: f.rel,
+                    line: m.line,
+                    label,
+                    table: m.table,
+                    status: "PROJECTION",
+                    missing,
+                    reason,
+                });
+            }
+            else {
+                inventory.push({
+                    rel: f.rel,
+                    line: m.line,
+                    label,
+                    table: m.table,
+                    status: "MISSING",
+                    missing,
+                });
+            }
+        }
+    }
+    return { inventory, findings, schemaFound };
+}
+// ---------------------------------------------------------------------------
+// decide — the four-state contract, with the COVERAGE INVENTORY rendered.
+//   non-conforming  a MISSING validator (a schema field absent, no written
+//                   projection reason) — the live R-46 defect class.
+//   could-not-judge a parse/schema finding, OR no schema found, OR zero
+//                   validators (an instrument that matched nothing has NOT
+//                   certified a clean bill).
+//   present         every validator ANALYSED (COVERS) or SKIPPED (PROJECTION).
+// ---------------------------------------------------------------------------
+const R46_ID = "R-46 returns validator derived from the schema, never restated";
+const R46_CHECK = "every document-returning `returns:` validator declares the schema's field set for its table, or a shortfall carries a written `returns-projection:` reason";
+function renderInventory(cov) {
+    const rows = cov.inventory.map((e) => {
+        if (e.status === "COVERS")
+            return `  ANALYSED COVERS     ${e.label} -> ${e.table} @ ${e.rel}:${e.line}`;
+        if (e.status === "PROJECTION")
+            return `  SKIPPED  PROJECTION ${e.label} -> ${e.table} @ ${e.rel}:${e.line} (omits ${e.missing.join(", ")}) reason: ${e.reason}`;
+        return `  ANALYSED MISSING    ${e.label} -> ${e.table} @ ${e.rel}:${e.line} missing: ${e.missing.join(", ")}`;
+    });
+    const finds = cov.findings.map((x) => `  FINDING             ${x.note} @ ${x.rel}:${x.line}`);
+    return [...rows, ...finds].join("\n");
+}
+export function decideR46(cov) {
+    const missing = cov.inventory.filter((e) => e.status === "MISSING");
+    const covers = cov.inventory.filter((e) => e.status === "COVERS");
+    const projections = cov.inventory.filter((e) => e.status === "PROJECTION");
+    const breakdown = `[analysed=${covers.length} projection=${projections.length} missing=${missing.length} findings=${cov.findings.length}]`;
+    const inventory = renderInventory(cov);
+    if (!cov.schemaFound) {
+        const reason = `R-46: no parseable schema.ts with a defineTable in the target tree — the field set cannot be DERIVED (${R46_CHECK}). NOT a clean bill: "did not look" is not "found nothing". ${breakdown}${cov.findings.length ? `\n${inventory}` : ""}`;
+        return {
+            id: R46_ID,
+            anchor: "target:no-schema",
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (missing.length > 0) {
+        const first = missing[0];
+        return {
+            id: R46_ID,
+            anchor: `${first.rel}:${first.line}`,
+            state: "non-conforming",
+            verdict: `R-46: ${missing.length} returns validator(s) enumerate a stored document but OMIT a schema-declared field with NO written projection reason (${R46_CHECK}). ${breakdown}\n=== coverage inventory ===\n${inventory}\n=== end inventory ===`,
+        };
+    }
+    if (cov.findings.length > 0) {
+        const first = cov.findings[0];
+        const reason = `R-46: static half clean (${covers.length} COVERS, ${projections.length} written projections, 0 MISSING) but ${cov.findings.length} file/validator could not be judged — a finding is never a silent pass. ${breakdown}\n=== coverage inventory ===\n${inventory}\n=== end inventory ===`;
+        return {
+            id: R46_ID,
+            anchor: `${first.rel}:${first.line}`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (cov.inventory.length === 0) {
+        const reason = `R-46: a schema was found but ZERO document-returning validators were matched in the target tree — the check would pass vacuously. NOT a clean bill. ${breakdown}`;
+        return {
+            id: R46_ID,
+            anchor: "target:no-validator",
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    const first = covers[0] ?? projections[0];
+    return {
+        id: R46_ID,
+        anchor: `${first.rel}:${first.line}`,
+        state: "present",
+        verdict: `R-46: all ${cov.inventory.length} document-returning validator(s) ANALYSED — ${covers.length} COVER the schema, ${projections.length} are SKIPPED as written projections; 0 MISSING (${R46_CHECK}). ${breakdown}\n=== coverage inventory ===\n${inventory}\n=== end inventory ===`,
+    };
+}
+/** The R-46 detector — reads the TARGET tree the engine hands it (never the
+ * vendored standard, never the filesystem directly), derives the field set from
+ * that target's schema, and classifies every document-returning validator. */
+export const R46 = {
+    id: R46_ID,
+    run: (tree) => decideR46(scanR46(tree.files)),
+};
+/** In a form the orchestrator spreads into REGISTRY. */
+export const STANDARD_SOURCE_DETECTORS = [
+    { detector: R46, ruleId: "R-46", standardPin: R46_STANDARD_PIN },
+];

package/dist/detectors/standard/standard-doc.d.ts

@@ -0,0 +1,12 @@
+import type { Detector } from "../../engine-types.js";
+import { type DocLine, type DocScan, type StandardDocEntry } from "./_doc.js";
+export declare function scanR42(lines: DocLine[]): DocScan;
+export declare function scanR15(lines: DocLine[]): DocScan;
+export declare function scanR32(lines: DocLine[]): DocScan;
+export declare function scanR39(lines: DocLine[]): DocScan;
+export declare const R42: Detector;
+export declare const R15: Detector;
+export declare const R32: Detector;
+export declare const R39: Detector;
+/** The four, in a form the orchestrator spreads into REGISTRY. */
+export declare const STANDARD_DOC_DETECTORS: StandardDocEntry[];