@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/route-config.js

@@ -0,0 +1,152 @@
+/**
+ * The wrapper config subset: permission/crossSite/dbTables/dbColumns/description/input.
+ *
+ * Split from routes.ts so both modules stay under the 300-line limit; every failure is an
+ * explicit unknown (never an empty value) and a diagnostic, as in the rest of the analyzer.
+ */
+import { callArguments } from "../ast/node.js";
+import { error, warning } from "../diagnostics.js";
+import { descriptionDiagnostics } from "./route-description.js";
+import { readStaticObject, refOf } from "./static-read.js";
+const MISSING_PERMISSION = "permission is missing";
+const MISSING_TABLES = "dbTables is missing; declare an array ([] means no DB)";
+function stringArrayValue(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((item) => typeof item === "string") ? [...value] : null;
+}
+function permissionValue(value) {
+    return typeof value === "string" ? [value] : stringArrayValue(value);
+}
+function addUnknown(list, code, reason, source) {
+    list.push({ code, reason, source });
+}
+function unreadable(field, entry) {
+    return field + " cannot be read statically: " + (entry.reason ?? "unsupported expression");
+}
+/** Read the wrapper config from the static subset; every failure is explicit. */
+export function routeConfigFacts(graph, file, call, config) {
+    const context = { graph, file: file.path };
+    const ref = refOf(context, call);
+    // Input schemas (body/query/params) are read for presence only: a Zod expression there is
+    // expected, so only the security/display fields below report a static-read failure.
+    const object = readStaticObject(callArguments(call)[0], context, {
+        code: "route-config-static",
+        report: false,
+    });
+    const unknown = [...object.unknown];
+    const field = (name) => object.fields.get(name);
+    const permissionField = field("permission");
+    let permission = null;
+    if (permissionField === undefined) {
+        addUnknown(unknown, "route-config-static", MISSING_PERMISSION, ref);
+    }
+    else if (!permissionField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("permission", permissionField), ref);
+    }
+    else {
+        permission = permissionValue(permissionField.value);
+        if (permission === null) {
+            addUnknown(unknown, "route-config-static", "permission must be a string or string[]", ref);
+        }
+    }
+    const crossSiteField = field("crossSite");
+    let crossSite = false;
+    if (crossSiteField !== undefined && !crossSiteField.ok) {
+        crossSite = null;
+        addUnknown(unknown, "route-config-static", unreadable("crossSite", crossSiteField), ref);
+    }
+    else if (crossSiteField !== undefined) {
+        if (typeof crossSiteField.value === "boolean")
+            crossSite = crossSiteField.value;
+        else {
+            crossSite = null;
+            addUnknown(unknown, "route-config-static", "crossSite must be a boolean", ref);
+        }
+    }
+    const rawSqlField = field("rawSql");
+    let rawSql = false;
+    if (rawSqlField !== undefined && !rawSqlField.ok) {
+        rawSql = null;
+        addUnknown(unknown, "route-config-static", unreadable("rawSql", rawSqlField), ref);
+    }
+    else if (rawSqlField !== undefined) {
+        if (typeof rawSqlField.value === "boolean")
+            rawSql = rawSqlField.value;
+        else {
+            // An unreadable derogation is never assumed: db.execute then fails closed (D-157).
+            rawSql = null;
+            addUnknown(unknown, "route-config-static", "rawSql must be a boolean", ref);
+        }
+    }
+    const tablesField = field("dbTables");
+    let dbTables = null;
+    if (tablesField === undefined) {
+        addUnknown(unknown, "db-tables-present", MISSING_TABLES, ref);
+    }
+    else if (!tablesField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("dbTables", tablesField), ref);
+    }
+    else {
+        dbTables = stringArrayValue(tablesField.value);
+        if (dbTables === null) {
+            addUnknown(unknown, "route-config-static", "dbTables must be a string[]", ref);
+        }
+    }
+    const columnsField = field("dbColumns");
+    let dbColumns = columnsField === undefined ? [] : null;
+    if (columnsField !== undefined && !columnsField.ok) {
+        dbColumns = null;
+        addUnknown(unknown, "route-config-static", unreadable("dbColumns", columnsField), ref);
+    }
+    else if (columnsField !== undefined) {
+        dbColumns = stringArrayValue(columnsField.value);
+        if (dbColumns === null) {
+            addUnknown(unknown, "route-config-static", "dbColumns must be a string[]", ref);
+        }
+    }
+    const descriptionField = field("description");
+    let description = null;
+    if (descriptionField !== undefined && !descriptionField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("description", descriptionField), ref);
+    }
+    else if (descriptionField !== undefined) {
+        if (typeof descriptionField.value === "string")
+            description = descriptionField.value;
+        else
+            addUnknown(unknown, "route-config-static", "description must be a string", ref);
+    }
+    const input = {
+        body: field("body") !== undefined,
+        form: field("form") !== undefined,
+        query: field("query") !== undefined,
+        params: field("params") !== undefined,
+    };
+    const diagnostics = [
+        ...unknown.map((item) => error(item.code, item.reason, item.source)),
+        ...descriptionDiagnostics(description, ref),
+    ];
+    if (permission !== null) {
+        for (const name of permission) {
+            if (!config.permissions.includes(name)) {
+                diagnostics.push(error("permission-declared", 'permission "' + name + '" is not declared in config.auth.permissions', ref));
+            }
+        }
+    }
+    // v3a: crossSite + a non-empty permission is legal now (the route is reached with a Bearer
+    // token); the warning only reminds the author that a session cookie never crosses origins.
+    if (crossSite === true && permission !== null && permission.length > 0) {
+        diagnostics.push(warning("route-cross-site-authenticated", "crossSite route requires a Bearer token: session cookies never cross origins", ref));
+    }
+    return {
+        permission,
+        crossSite,
+        rawSql,
+        dbTables,
+        dbColumns,
+        description,
+        input,
+        unknown,
+        diagnostics,
+    };
+}

package/dist/passes/route-description.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Route description rules (D-129).
+ *
+ * The description is source documentation: one English sentence stored in the
+ * defineAuthorizedHandler config, shown under the route node and in the OpenAPI document.
+ * Two lines is its useful maximum, so the analyzer reports a warning when it runs long.
+ * The patch validator imports the same limit, so the AI and the user see one number.
+ */
+import type { Diagnostic, SourceRef } from "../types.js";
+/** About two lines in the route definition and in the graph card. */
+export declare const ROUTE_DESCRIPTION_MAX_CHARS = 120;
+/** A warning when the description exceed the two-line budget; nothing to report otherwise. */
+export declare function descriptionDiagnostics(description: string | null, source: SourceRef | null): readonly Diagnostic[];

package/dist/passes/route-description.js

@@ -0,0 +1,23 @@
+/**
+ * Route description rules (D-129).
+ *
+ * The description is source documentation: one English sentence stored in the
+ * defineAuthorizedHandler config, shown under the route node and in the OpenAPI document.
+ * Two lines is its useful maximum, so the analyzer reports a warning when it runs long.
+ * The patch validator imports the same limit, so the AI and the user see one number.
+ */
+import { warning } from "../diagnostics.js";
+/** About two lines in the route definition and in the graph card. */
+export const ROUTE_DESCRIPTION_MAX_CHARS = 120;
+/** A warning when the description exceed the two-line budget; nothing to report otherwise. */
+export function descriptionDiagnostics(description, source) {
+    if (description === null || description.length <= ROUTE_DESCRIPTION_MAX_CHARS)
+        return [];
+    return [
+        warning("route-description-length", "description is " +
+            description.length +
+            " characters; keep it to " +
+            ROUTE_DESCRIPTION_MAX_CHARS +
+            " (about two lines)", source),
+    ];
+}

package/dist/passes/route-elevation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Audited elevation facts from a route handler (D-099): `ctx.sudo` and `ctx.system`.
+ *
+ * Only the handler's own context can elevate: a destructured `{ sudo }`/`{ system }` binding
+ * or a member call on the context parameter. Any other identifier named `sudo` is ignored, so
+ * the graph cannot be colored by a local helper with the same name. The tables and operation
+ * are read through the bounded static subset; when that fails the fact is explicit (unknown
+ * plus an empty table list), never guessed.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ElevationFact, UnknownFact } from "../types.js";
+export interface ElevationScan {
+    readonly facts: readonly ElevationFact[];
+    readonly unknown: readonly UnknownFact[];
+}
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export declare function scanElevations(graph: ModuleGraph, file: ProjectFile, wrapperCall: AstNode): ElevationScan;

package/dist/passes/route-elevation.js

@@ -0,0 +1,136 @@
+/**
+ * Audited elevation facts from a route handler (D-099): `ctx.sudo` and `ctx.system`.
+ *
+ * Only the handler's own context can elevate: a destructured `{ sudo }`/`{ system }` binding
+ * or a member call on the context parameter. Any other identifier named `sudo` is ignored, so
+ * the graph cannot be colored by a local helper with the same name. The tables and operation
+ * are read through the bounded static subset; when that fails the fact is explicit (unknown
+ * plus an empty table list), never guessed.
+ */
+import { callArguments, identifierName, memberName, nodeArray, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { readStaticObject } from "./static-read.js";
+function refOf(file, node) {
+    const offset = typeof node.start === "number" ? node.start : 0;
+    let line = 1;
+    for (let index = 0; index < offset && index < file.source.length; index += 1) {
+        if (file.source.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return { file: file.path, line };
+}
+function elevationKind(name) {
+    if (name === "sudo" || name === "system")
+        return name;
+    return null;
+}
+/** Local identifier -> elevation kind for `{ sudo }` / `{ sudo: elevate }`. */
+function handlerBindings(handler) {
+    const locals = new Map();
+    const context = nodeArray(handler, "params")[1];
+    if (context === undefined)
+        return { locals, contextName: null };
+    if (context.type === "Identifier") {
+        return { locals, contextName: identifierName(context) ?? null };
+    }
+    if (context.type !== "ObjectPattern")
+        return { locals, contextName: null };
+    for (const entry of objectEntries(context)) {
+        if (entry.type !== "Property")
+            continue;
+        const kind = elevationKind(propertyName(entry));
+        if (kind === null)
+            continue;
+        let value = propertyValue(entry);
+        if (value !== undefined && value.type === "AssignmentPattern") {
+            value = unwrapExpression(value.left);
+        }
+        const local = identifierName(unwrapExpression(value));
+        if (local !== undefined)
+            locals.set(local, kind);
+    }
+    return { locals, contextName: null };
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((entry) => typeof entry === "string") ? [...value] : null;
+}
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export function scanElevations(graph, file, wrapperCall) {
+    const handler = callArguments(wrapperCall)[1];
+    if (handler === undefined)
+        return { facts: [], unknown: [] };
+    const handlerNode = unwrapExpression(handler);
+    if (handlerNode === undefined ||
+        (handlerNode.type !== "ArrowFunctionExpression" && handlerNode.type !== "FunctionExpression")) {
+        return { facts: [], unknown: [] };
+    }
+    const bindings = handlerBindings(handlerNode);
+    const facts = [];
+    const unknown = [];
+    walk(handlerNode, (node) => {
+        if (node.type !== "CallExpression")
+            return;
+        const callee = unwrapExpression(node.callee);
+        if (callee === undefined)
+            return;
+        let kind = null;
+        if (callee.type === "Identifier") {
+            kind = bindings.locals.get(identifierName(callee) ?? "") ?? null;
+        }
+        else if (callee.type === "MemberExpression") {
+            const name = memberName(callee);
+            const object = unwrapExpression(callee.object);
+            if (name !== undefined &&
+                object?.type === "Identifier" &&
+                identifierName(object) === bindings.contextName) {
+                kind = elevationKind(name);
+            }
+        }
+        if (kind === null)
+            return;
+        const source = refOf(file, node);
+        const options = readStaticObject(callArguments(node)[0], { graph, file: file.path }, {
+            code: "route-elevation-static",
+            report: true,
+        });
+        const factUnknown = [...options.unknown];
+        const tablesField = options.fields.get("tables");
+        let tables = [];
+        if (tablesField === undefined) {
+            factUnknown.push({
+                code: "route-elevation-static",
+                reason: "elevation tables are missing",
+                source,
+            });
+        }
+        else if (!tablesField.ok) {
+            factUnknown.push({
+                code: "route-elevation-static",
+                reason: "elevation tables cannot be read statically",
+                source,
+            });
+        }
+        else {
+            const read = stringArray(tablesField.value);
+            if (read === null) {
+                factUnknown.push({
+                    code: "route-elevation-static",
+                    reason: "elevation tables must be a string[]",
+                    source,
+                });
+            }
+            else {
+                tables = read;
+            }
+        }
+        const operationField = options.fields.get("operation");
+        const operation = operationField !== undefined && operationField.ok && typeof operationField.value === "string"
+            ? operationField.value
+            : null;
+        unknown.push(...factUnknown);
+        facts.push({ kind, tables, operation, source, unknown: factUnknown });
+    });
+    return { facts, unknown };
+}

package/dist/passes/route-handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Facts read from a route handler expression (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * The security rules need to know whether a handler reads the request input — the JSON body
+ * or the multipart form: the fact must come from the AST, not from a comment or a string, so
+ * a route cannot look validated by mentioning `body`/`form` in prose.
+ *
+ * The same reasoning drives the direct-DB warning: a handler that reaches the raw client
+ * through `event.context.facilis.db` or imports the `createDb` factory bypasses the
+ * policy-scoped client, and only the AST can tell a real access from a string mention.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ProjectFile } from "../module-graph.js";
+import type { Diagnostic, SourceRef } from "../types.js";
+/** Warning text for raw/direct DB access in a route file. */
+export declare const ROUTE_DIRECT_DB_MESSAGE = "Direct DB access bypasses the policy-scoped client; use ctx.db for user-scoped work and ctx.system/ctx.sudo for audited system operations (not recommended).";
+/** True when the handler reads `.body` or destructures a `{ body }` pattern. */
+export declare function handlerReadsBody(call: AstNode): boolean;
+/** True when the handler reads `.form` or destructures a `{ form }` pattern (D-053). */
+export declare function handlerReadsForm(call: AstNode): boolean;
+/**
+ * Warnings for raw/direct DB access in a route file: `event.context.facilis.db` bypasses
+ * the policy-scoped client, and importing the `createDb` factory is the raw-client path.
+ * The source points at the offending node (or the route when a node has no position), so
+ * the IDE can jump to it.
+ */
+export declare function directDbWarnings(file: ProjectFile, fallback: SourceRef): Diagnostic[];

package/dist/passes/route-handler.js

@@ -0,0 +1,87 @@
+/**
+ * Facts read from a route handler expression (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * The security rules need to know whether a handler reads the request input — the JSON body
+ * or the multipart form: the fact must come from the AST, not from a comment or a string, so
+ * a route cannot look validated by mentioning `body`/`form` in prose.
+ *
+ * The same reasoning drives the direct-DB warning: a handler that reaches the raw client
+ * through `event.context.facilis.db` or imports the `createDb` factory bypasses the
+ * policy-scoped client, and only the AST can tell a real access from a string mention.
+ */
+import { asNode, callArguments, memberName, objectEntries, propertyName, unwrapExpression, } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { warning } from "../diagnostics.js";
+import { sourceRef } from "../source.js";
+const RAW_DB_SPECIFIER = "@facilis.dev/db";
+const RAW_DB_FACTORY = "createDb";
+/** Warning text for raw/direct DB access in a route file. */
+export const ROUTE_DIRECT_DB_MESSAGE = "Direct DB access bypasses the policy-scoped client; use ctx.db for user-scoped work and ctx.system/ctx.sudo for audited system operations (not recommended).";
+function nodeRef(file, node, fallback) {
+    return typeof node.start === "number" ? sourceRef(file.path, file.source, node.start) : fallback;
+}
+/** True when the object chain of `node` contains a `.facilis` property. */
+function touchesFacilisContext(node) {
+    let current = node;
+    while (current !== undefined && current.type === "MemberExpression") {
+        if (memberName(current) === "facilis")
+            return true;
+        current = asNode(unwrapExpression(current.object));
+    }
+    return false;
+}
+/** `event.context.facilis.db` (or any `*.facilis.db` access): the raw policy-free client. */
+function isDirectDbMember(node) {
+    if (node.type !== "MemberExpression" || memberName(node) !== "db")
+        return false;
+    const object = asNode(unwrapExpression(node.object));
+    return object !== undefined && touchesFacilisContext(object);
+}
+/** True when the handler reads `name` off the request: member access or destructuring. */
+function handlerReads(call, name) {
+    const handler = callArguments(call)[1];
+    if (handler === undefined)
+        return false;
+    let found = false;
+    walk(handler, (node) => {
+        if (found)
+            return;
+        if (node.type === "MemberExpression" && memberName(node) === name) {
+            found = true;
+            return;
+        }
+        if (node.type === "ObjectPattern" &&
+            objectEntries(node).some((entry) => entry.type === "Property" && propertyName(entry) === name)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/** True when the handler reads `.body` or destructures a `{ body }` pattern. */
+export function handlerReadsBody(call) {
+    return handlerReads(call, "body");
+}
+/** True when the handler reads `.form` or destructures a `{ form }` pattern (D-053). */
+export function handlerReadsForm(call) {
+    return handlerReads(call, "form");
+}
+/**
+ * Warnings for raw/direct DB access in a route file: `event.context.facilis.db` bypasses
+ * the policy-scoped client, and importing the `createDb` factory is the raw-client path.
+ * The source points at the offending node (or the route when a node has no position), so
+ * the IDE can jump to it.
+ */
+export function directDbWarnings(file, fallback) {
+    const refs = [];
+    walk(file.program, (node) => {
+        if (isDirectDbMember(node))
+            refs.push(nodeRef(file, node, fallback));
+    });
+    for (const imported of file.module.imports) {
+        if (imported.specifier === RAW_DB_SPECIFIER && imported.imported === RAW_DB_FACTORY) {
+            refs.push(imported.source);
+        }
+    }
+    refs.sort((left, right) => left.line - right.line);
+    return refs.map((source) => warning("route-direct-db", ROUTE_DIRECT_DB_MESSAGE, source));
+}

package/dist/passes/route-location.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Route file name -> method/path (Nitro's file router, SPEC §4.2).
+ *
+ * Kept apart from the route pass so the filename rules are testable and the pass stays within
+ * the file-length limit. Two deliberate extensions over @facilis.dev/nitro's route-path: every
+ * HTTP method is recognized, and a method-less file serves ALL methods (Nitro's behavior).
+ */
+import type { HttpMethod, RouteFact } from "../types.js";
+export interface RouteLocation {
+    readonly method: HttpMethod;
+    readonly path: string;
+}
+/** Derive the route location from its file name relative to the routes directory. */
+export declare function routeLocationFromFile(relativeRouteFile: string): RouteLocation | undefined;
+/** Stable route id shared by facts and the project graph. */
+export declare function routeFactId(route: Pick<RouteFact, "method" | "path">): string;

package/dist/passes/route-location.js

@@ -0,0 +1,58 @@
+/**
+ * Route file name -> method/path (Nitro's file router, SPEC §4.2).
+ *
+ * Kept apart from the route pass so the filename rules are testable and the pass stays within
+ * the file-length limit. Two deliberate extensions over @facilis.dev/nitro's route-path: every
+ * HTTP method is recognized, and a method-less file serves ALL methods (Nitro's behavior).
+ */
+const METHOD_SUFFIX = /\.(get|post|put|patch|delete|head|options|trace|connect)$/;
+const ENV_SUFFIX = /\.(dev|prod|prerender)$/;
+const SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?)$/;
+function toOpenApiSegment(segment) {
+    // Optional params `[[id]]` and catch-all `[...slug]` keep their special form; named
+    // params become OpenAPI templates, matching the spec Nitro generates.
+    const optional = /^\[\[(.+)\]\]$/.exec(segment);
+    if (optional?.[1] !== undefined)
+        return "{" + optional[1] + "}";
+    const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+    if (catchAll?.[1] !== undefined)
+        return "{*" + catchAll[1] + "}";
+    const named = /^\[(.+)\]$/.exec(segment);
+    if (named?.[1] !== undefined)
+        return "{" + named[1] + "}";
+    return segment.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+function parseRouteSegment(segment) {
+    let name = segment;
+    const env = name.match(ENV_SUFFIX);
+    if (env !== null)
+        name = name.slice(0, -env[0].length);
+    let method = "ALL";
+    const methodMatch = name.match(METHOD_SUFFIX);
+    if (methodMatch?.[1] !== undefined) {
+        method = methodMatch[1].toUpperCase();
+        name = name.slice(0, -methodMatch[0].length);
+    }
+    return name.length === 0 ? undefined : { name, method };
+}
+/** Derive the route location from its file name relative to the routes directory. */
+export function routeLocationFromFile(relativeRouteFile) {
+    const normalized = relativeRouteFile.replace(/\\/g, "/").replace(SOURCE_EXTENSION, "");
+    const segments = normalized.split("/").filter(Boolean);
+    const last = segments.length - 1;
+    if (last < 0)
+        return undefined;
+    const parsed = parseRouteSegment(segments[last] ?? "");
+    if (parsed === undefined)
+        return undefined;
+    if (parsed.name === "index")
+        segments.pop();
+    else
+        segments[last] = parsed.name;
+    const path = segments.filter((segment) => !/^\(.+\)$/.test(segment)).map(toOpenApiSegment);
+    return { method: parsed.method, path: path.length === 0 ? "/" : "/" + path.join("/") };
+}
+/** Stable route id shared by facts and the project graph. */
+export function routeFactId(route) {
+    return "route:" + route.method + " " + route.path;
+}

package/dist/passes/route-relation-resolve.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Name resolution for the route-relations pass (D-157). Split from route-relations.ts so both
+ * files stay under the 300-line limit.
+ *
+ * Two questions are answered here, without executing project code:
+ * - which relation (table or view) an expression denotes, following same-file consts, project
+ *   imports, re-exports and namespace members;
+ * - which db client an expression denotes, so a use can be attributed to `ctx.db` or to one
+ *   audited elevation callback.
+ *
+ * Anything outside the static subset is explicit: "opaque" means a package binding we cannot
+ * inspect (no error, the runtime guard is the authority), "unresolved" means dynamic project
+ * code (an error, D-157: route-table-unresolved).
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { TableFact, ViewFact } from "../types.js";
+export interface DbClient {
+    /** Elevation index in RouteRelationsFact.elevations; null is the route's ctx.db. */
+    readonly elevation: number | null;
+}
+export declare const ROUTE_CLIENT: DbClient;
+export type ClientEnv = ReadonlyMap<string, DbClient>;
+export type RelationResolution = {
+    readonly kind: "resolved";
+    readonly name: string;
+} | {
+    readonly kind: "unresolved";
+} | {
+    readonly kind: "opaque";
+};
+export interface RelationIndex {
+    readonly names: ReadonlySet<string>;
+    resolve(graph: ModuleGraph, file: ProjectFile, node: AstNode | undefined, aliases: ReadonlyMap<string, string>, depth?: number): RelationResolution;
+}
+/** Table and view bindings, keyed by declaring file + binding (D-157). */
+export declare function createRelationIndex(tables: readonly TableFact[], views: readonly ViewFact[]): RelationIndex;
+/** The db client an expression denotes directly (a local binding or `ctx.db`), if any. */
+export declare function clientOf(node: unknown, env: ClientEnv, contextName: string | null): DbClient | null;
+/** The client at the root of a fluent chain (`db.select()`, `db.query.todos`). */
+export declare function chainClient(node: unknown, env: ClientEnv, contextName: string | null): DbClient | null;
+/** True when a callee argument carries a db client anywhere (opaque callee detection). */
+export declare function carriesClient(node: AstNode, env: ClientEnv, contextName: string | null): boolean;
+export interface LocalFunction {
+    /** Stable identity for the call stack (cycle guard). */
+    readonly key: string;
+    readonly file: ProjectFile;
+    readonly node: AstNode;
+}
+/** A project-local function (never a package one: package calls stay opaque, D-157). */
+export declare function resolveLocalFunction(graph: ModuleGraph, file: ProjectFile, callee: unknown): LocalFunction | null;