@vantageos/backend-doctor 0.1.13 → 0.2.0

package/dist/detectors/shared.js

@@ -1,4 +1,4 @@
-import { isInventoryRow, readOracle } from "../oracle.js";
+import { isInventoryRow, oracleLabel, readOracle, refuseWithoutOracle, } from "../oracle.js";
 /** Run a predicate over a row set, tallying per-kind. */
 export function tally(spec, rows) {
     const t = { conform: 0, violate: 0, cnj: 0, na: 0, violations: [], unjudged: [] };
@@ -52,7 +52,7 @@ export function evaluate(spec, rows) {
             .join("; ")}. This is NOT a clean bill. ${breakdown}`;
         return {
             id: spec.id,
-            anchor: anchorFor(t.unjudged, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.unjudged, oracleLabel()),
             state: "could-not-judge",
             verdict: reason,
             reason,
@@ -65,14 +65,14 @@ export function evaluate(spec, rows) {
             .join("; ");
         return {
             id: spec.id,
-            anchor: anchorFor(t.violations, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.violations, oracleLabel()),
             state: "non-conforming",
             verdict: `${spec.ruleId}: ${t.violate} of ${applicable} applicable oracle rows VIOLATE (${spec.check}). ${breakdown} Examples: ${examples}.`,
         };
     }
     return {
         id: spec.id,
-        anchor: "oracle:vp-by-tool-day158.csv",
+        anchor: oracleLabel(),
         state: "present",
         verdict: `${spec.ruleId}: ${t.conform} applicable oracle rows conform (${spec.check}); 0 violations. ${breakdown}`,
     };
@@ -85,7 +85,7 @@ export function evaluate(spec, rows) {
 export function makeOracleDetector(spec, rowsProvider = readOracle) {
     return {
         id: spec.id,
-        run: () => evaluate(spec, rowsProvider()),
+        run: () => refuseWithoutOracle(spec.id, () => evaluate(spec, rowsProvider())),
     };
 }
 // ---- small shared classifiers over oracle vocabulary --------------------

package/dist/detectors/source/_scan.js

@@ -40,11 +40,16 @@ export function decide(ruleId, id, check, scan, emptyReason) {
         .map((x) => `${x.rel}:${x.n} (${x.note})`)
         .join("; ");
     if (nV > 0) {
+        // A non-conforming verdict must NAME its could-not-judge sites, not drop them
+        // to a bare integer in the breakdown — the one disposition that owes a human
+        // verdict is otherwise the only one printed without an address (Eta REVISE
+        // blocker 1: R-51 CRM could-not-judge=1 was counted but never located). The
+        // data is already in scan.cnj; list it under its own label whenever non-empty.
         return {
             id,
             anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
             state: "non-conforming",
-            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`,
+            verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}${nJ ? ` could-not-judge sites (human verdict owed): ${fmt(scan.cnj)}.` : ""}`,
         };
     }
     if (nJ > 0) {

package/dist/detectors/source/backfill.js

@@ -73,7 +73,15 @@ export function derivedStructures(files) {
             if (FIELD_LINE.test(l.raw))
                 fields += 1;
             const id = ID_REF.exec(l.raw);
-            if (id && !fkTarget)
+            // A SYSTEM table (`_storage`, `_scheduled_functions` — Convex reserves the
+            // leading underscore) is not a source a migration can backfill FROM: its
+            // rows are platform objects, not domain rows, and there is no
+            // `ctx.db.query("_storage")` that enumerates what the write path would
+            // have bound. A table whose only foreign key points at a system table
+            // (a TOFU ownership binding of uploaded blobs, kbUploads) is therefore
+            // not a derived structure in R-44's sense. The first NON-system FK is
+            // the source; a table with none is skipped.
+            if (id && !fkTarget && !id[1].startsWith("_"))
                 fkTarget = id[1];
             if (HAS_INDEX.test(l.raw))
                 hasIndex = true;

package/dist/detectors/source/guard-helper-flow.d.ts

@@ -0,0 +1,112 @@
+import * as ts from "typescript";
+export type GuardHelperKind = "binds-arg" | "master-only";
+export type HelperVerdict = {
+    verdict: "honoured";
+} | {
+    verdict: "refused";
+    why: string;
+} | {
+    verdict: "could-not-judge";
+    why: string;
+};
+/** A callee name, as seen from the function being judged, resolved to its
+ * definition in the tree (and to a resolver for names seen from THAT file). */
+export type CallResolver = (name: string) => {
+    fn: ts.FunctionLikeDeclaration;
+    key: string;
+    resolve: CallResolver;
+} | undefined;
+/** Judge one helper function on its control flow. */
+export declare function judgeHelperFunction(fn: ts.FunctionLikeDeclaration, kind: GuardHelperKind): HelperVerdict;
+export interface FoundHelper {
+    name: string;
+    line: number;
+    exported: boolean;
+    judgement: HelperVerdict;
+}
+/** Every definition, in `source`, of a helper named in `kinds`. */
+export declare function findHelperDefinitions(fileName: string, source: string, kinds: Readonly<Record<string, GuardHelperKind>>): FoundHelper[];
+/** The arguments of each `await <helper>(…)` that is a DIRECT statement of the
+ * handler `name` (`export const name = mutation({ handler: … })`) and starts
+ * before `beforeLine`. A helper call nested in a branch, a try, or a closure of
+ * the handler is not a statement every path runs, so it is not returned.
+ * `null` = the handler's body could not be located in the file. */
+export declare function topLevelHelperCalls(fileName: string, source: string, handlerName: string, 
+/** `null` = any identifier callee (judged by the caller on its body). */
+helpers: ReadonlySet<string> | null, beforeLine: number): {
+    name: string;
+    args: string;
+    argNodes: readonly ts.Expression[];
+    line: number;
+}[] | null;
+export interface TopLevelFunction {
+    name: string;
+    line: number;
+    exported: boolean;
+    fn: ts.FunctionLikeDeclaration;
+}
+/** Every top-level function declaration and `const f = (…) => {…}` /
+ * `function (…) {…}` of a file. */
+export declare function topLevelFunctions(fileName: string, source: string): TopLevelFunction[];
+/** Judge a function as an IDENTITY RESOLVER (shape 1 above). */
+export declare function judgeResolverFunction(fn: ts.FunctionLikeDeclaration): HelperVerdict;
+export type ValidatorSummary = {
+    ok: false;
+    why: string;
+} | {
+    ok: true;
+    /** every normal exit binds the target parameter (or is the master's) */
+    exitsBound: boolean;
+    /** every normal exit is the fleet master's */
+    exitsMaster: boolean;
+    /** no normal exit at all: it refuses every caller */
+    never: boolean;
+};
+export declare function summarizeValidator(fn: ts.FunctionLikeDeclaration, o: {
+    /** the parameter whose binding is asked; undefined = master-only asked */
+    boundIdx: number | undefined;
+    /** the parameter receiving the caller's verified scope, if any */
+    identityIdx: number | undefined;
+    /** the call's arguments (object literals become constants) */
+    callArgs: readonly ts.Expression[];
+    resolve: CallResolver;
+    key: string;
+    depth: number;
+}): ValidatorSummary;
+/** Judge a function as a REFUSING PREDICATE (shape 2 above): parameter
+ * `identityIdx` receives the caller's verified scope, `boundIdx` the value the
+ * caller then writes. */
+export declare function judgePredicateFunction(fn: ts.FunctionLikeDeclaration, identityIdx: number, boundIdx: number): HelperVerdict;
+/** What a mutation handler's own body declares and refuses before `beforeLine`. */
+export interface HandlerGuards {
+    /** Top-level `const` locals: whether bound straight to an identity read, or
+     * to `await <callee>(…)` (the callee is then judged by the caller). */
+    consts: Map<string, {
+        identityRead: boolean;
+        awaitedCallee?: string;
+    }>;
+    /** `if (!P(a, b, …)) { …throw }` statements: the predicate and its args. */
+    refusals: {
+        predicate: string;
+        args: {
+            text: string;
+            ident?: string;
+            memberBase?: string;
+        }[];
+        line: number;
+    }[];
+}
+/** Read the direct statements of handler `name` before `beforeLine`. `null`
+ * when the handler's body cannot be located. */
+export declare function readHandlerGuards(fileName: string, source: string, handlerName: string, beforeLine: number): HandlerGuards | null;
+/** A CONDITIONAL boundary value at a write site (`orgId: c ? a : b`): which arm
+ * reads the caller's `args`, and whether the condition is a positive
+ * `<local>.isMaster` test (the fleet carve-out, which may write what the
+ * master names). Read with the TypeScript parser on the write-site text. */
+export interface ConditionalBoundary {
+    field: string;
+    masterBase?: string;
+    trueReadsArgs: boolean;
+    falseReadsArgs: boolean;
+}
+export declare function conditionalBoundaries(text: string, fields: ReadonlySet<string>): ConditionalBoundary[];