@vantageos/backend-doctor 0.1.14 → 0.3.0

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

@@ -0,0 +1,134 @@
+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;
+};
+/**
+ * SCOPE REFINERS, by name: a call `await R(ctx, <scope>, …)` whose result is
+ * scope-derived exactly when the scope it is handed (at `argIndex`) is. The
+ * refiner returns that scope unchanged, or rebuilds it from a SERVER-SIDE row
+ * after refusing every transport but the fleet service account — vantage-peers
+ * `convex/lib/personPrincipal.ts::resolveVerifiedPerson` (the `verifiedPerson`
+ * proof is believed from the service account only and the person's scope is
+ * re-read from `oauth_access_tokens`). The other arguments it is handed (a
+ * proof, a door name, an asserted name) never become its return.
+ *
+ * Trusted by NAME, on the same footing as `withOrgScope` in isIdentityRead: the
+ * flow walk cannot model "a scope rebuilt from a stored row" as the identity.
+ * The trust is narrow — the result is pure only when the scope argument itself
+ * is pure; a refiner handed anything else confers nothing.
+ */
+export declare const SCOPE_REFINERS: Readonly<Record<string, {
+    argIndex: number;
+}>>;
+/** 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;
+    }[];
+}
+/** The block body of the `handler` of `const <handlerName> = <builder>({ … })`
+ * at the top level of `sf` (arrow, function expression or method); undefined
+ * when it cannot be located. */
+export declare function handlerBodyOf(sf: ts.SourceFile, handlerName: string): ts.Block | undefined;
+/** 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[];