@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/route-relations-walk.js

@@ -0,0 +1,199 @@
+/**
+ * The route-relations walker (D-157): starts at the route handler, tracks db clients and
+ * relation bindings through local declarations, records `from/join/insert/update/delete`,
+ * `db.query.<relation>` and `db.execute`, and hands the interprocedural cases to
+ * route-relations-follow.ts. Everything outside the static subset is explicit (opaque or
+ * unresolved), never guessed.
+ */
+import { asNode, callArguments, identifierName, memberName, nodeArray, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { sourceRef } from "../source.js";
+import { followFunction, handleElevation } from "./route-relations-follow.js";
+import { createUsage, freezeUsage, addUnresolved, addUse, markOpaque, } from "./route-relations-usage.js";
+import { carriesClient, chainClient, clientOf, resolveLocalFunction, ROUTE_CLIENT, } from "./route-relation-resolve.js";
+const MAX_DEPTH = 6;
+const RELATION_METHODS = new Set(["from", "innerJoin", "leftJoin", "rightJoin", "fullJoin"]);
+const WRITE_METHODS = new Set(["insert", "update", "delete"]);
+const SKIPPED_KEYS = new Set(["type", "start", "end", "range"]);
+const ROUTE_SEED = { contextParam: 1, elevations: true };
+function elevationKind(name) {
+    return name === "sudo" || name === "system" ? name : null;
+}
+function refOf(scope, node) {
+    return sourceRef(scope.file.path, scope.file.source, typeof node.start === "number" ? node.start : 0);
+}
+/** A callee that is `ctx.sudo`/`ctx.system` or a destructured/forwarded elevation handler. */
+function calleeElevationKind(callee, scope) {
+    if (!scope.elevations)
+        return null;
+    const expression = unwrapExpression(callee);
+    if (expression === undefined)
+        return null;
+    if (expression.type === "Identifier") {
+        return scope.elevationFns.get(identifierName(expression) ?? "") ?? null;
+    }
+    if (expression.type !== "MemberExpression")
+        return null;
+    const kind = elevationKind(memberName(expression));
+    if (kind === null)
+        return null;
+    const object = unwrapExpression(expression.object);
+    return object?.type === "Identifier" && identifierName(object) === scope.contextName
+        ? kind
+        : null;
+}
+/** `db.query.<relation>`: a static property name the runtime guard resolves to a relation. */
+function trackQueryMember(node, scope) {
+    const property = memberName(node);
+    const object = unwrapExpression(node.object);
+    if (property === undefined || object?.type !== "MemberExpression")
+        return;
+    if (memberName(object) !== "query")
+        return;
+    if (clientOf(object.object, scope.env, scope.contextName) === null)
+        return;
+    if (scope.index.names.has(property))
+        addUse(scope, property, refOf(scope, node));
+    else
+        addUnresolved(scope, refOf(scope, node));
+}
+/** `const scoped = ctx.db` / `const rows = todos`: aliases the walk keeps resolving. */
+function trackDeclaration(node, scope) {
+    if (node.type !== "VariableDeclarator")
+        return;
+    const name = identifierName(node.id);
+    if (name === undefined)
+        return;
+    const client = clientOf(node.init, scope.env, scope.contextName);
+    if (client !== null) {
+        scope.env.set(name, client);
+        return;
+    }
+    const resolution = scope.index.resolve(scope.graph, scope.file, asNode(node.init), scope.aliases);
+    if (resolution.kind === "resolved")
+        scope.aliases.set(name, resolution.name);
+}
+function recordRelation(scope, node) {
+    if (node === undefined)
+        return;
+    const resolution = scope.index.resolve(scope.graph, scope.file, node, scope.aliases);
+    if (resolution.kind === "resolved")
+        addUse(scope, resolution.name, refOf(scope, node));
+    else if (resolution.kind === "unresolved")
+        addUnresolved(scope, refOf(scope, node));
+    else
+        markOpaque(scope);
+}
+function handleCall(node, scope) {
+    const callee = unwrapExpression(node.callee);
+    const kind = calleeElevationKind(callee, scope);
+    if (kind !== null)
+        return handleElevation(visit, node, scope, kind);
+    if (callee?.type === "MemberExpression") {
+        const name = memberName(callee);
+        const object = unwrapExpression(callee.object);
+        if (name === "execute" && chainClient(object, scope.env, scope.contextName) !== null) {
+            scope.usage.rawSql.push(refOf(scope, node));
+            return false;
+        }
+        if (name !== undefined &&
+            RELATION_METHODS.has(name) &&
+            chainClient(object, scope.env, scope.contextName) !== null) {
+            recordRelation(scope, callArguments(node)[0]);
+            return false;
+        }
+        if (name !== undefined &&
+            WRITE_METHODS.has(name) &&
+            clientOf(object, scope.env, scope.contextName) !== null) {
+            recordRelation(scope, callArguments(node)[0]);
+            return false;
+        }
+    }
+    const local = resolveLocalFunction(scope.graph, scope.file, callee);
+    if (local !== null) {
+        followFunction(visit, node, scope, local);
+        return true;
+    }
+    // A project-external callee that receives the client makes the usage opaque: the runtime
+    // guard is the authority, so the pass must not raise a false undeclared/unused error.
+    if (callArguments(node).some((argument) => carriesClient(argument, scope.env, scope.contextName))) {
+        markOpaque(scope);
+    }
+    return false;
+}
+function visit(node, scope) {
+    if (scope.depth > MAX_DEPTH)
+        return;
+    trackDeclaration(node, scope);
+    if (node.type === "MemberExpression")
+        trackQueryMember(node, scope);
+    if (node.type === "CallExpression" && handleCall(node, scope))
+        return;
+    for (const key of Object.keys(node)) {
+        if (SKIPPED_KEYS.has(key))
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const child of value)
+                if (asNode(child) !== undefined)
+                    visit(asNode(child), scope);
+            continue;
+        }
+        const child = asNode(value);
+        if (child !== undefined)
+            visit(child, scope);
+    }
+}
+function functionScope(graph, file, fn, index, usage, seed) {
+    const env = new Map();
+    const elevationFns = new Map();
+    let contextName = null;
+    const context = unwrapExpression(nodeArray(fn, "params")[seed.contextParam]);
+    if (context?.type === "Identifier")
+        contextName = identifierName(context) ?? null;
+    else if (context?.type === "ObjectPattern") {
+        for (const entry of objectEntries(context)) {
+            if (entry.type !== "Property")
+                continue;
+            const name = propertyName(entry);
+            let value = propertyValue(entry);
+            if (value?.type === "AssignmentPattern")
+                value = unwrapExpression(value.left);
+            const local = identifierName(unwrapExpression(value));
+            if (local === undefined)
+                continue;
+            if (name === "db")
+                env.set(local, ROUTE_CLIENT);
+            else if (seed.elevations) {
+                const kind = elevationKind(name);
+                if (kind !== null)
+                    elevationFns.set(local, kind);
+            }
+        }
+    }
+    return {
+        graph,
+        index,
+        file,
+        env,
+        aliases: new Map(),
+        elevationFns,
+        contextName,
+        elevations: seed.elevations,
+        elevation: null,
+        depth: 0,
+        stack: new Set(),
+        usage,
+    };
+}
+/** Scan one route handler or job run function into its relation-usage fact. */
+export function scanFunctionUsage(graph, file, fn, index, seed) {
+    const body = asNode(fn.body);
+    const usage = createUsage();
+    if (body !== undefined)
+        visit(body, functionScope(graph, file, fn, index, usage, seed));
+    return freezeUsage(usage);
+}
+/** Scan one valid route handler into its relation-usage fact. */
+export function scanHandlerUsage(graph, file, handler, index) {
+    return scanFunctionUsage(graph, file, handler, index, ROUTE_SEED);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Route handler -> relation usage (D-157), the pass that makes `dbTables` an applied
+ * declaration: what a route reaches through `ctx.db` and the audited `ctx.sudo`/`ctx.system`
+ * callback clients is compared with what it declares, tables and views alike.
+ *
+ * The walk lives in route-relations-walk.ts / route-relations-follow.ts and the diagnostics in
+ * route-relations-diagnostics.ts (300-line split). A route with an invalid wrapper keeps an
+ * explicitly empty usage: the wrapper error is the finding, not a guessed relation set.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { RouteFact, TableFact, ViewFact, Diagnostic } from "../types.js";
+export interface RouteRelationsScan {
+    readonly routes: readonly RouteFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Attach relation-usage facts to every scannable route and derive the D-157 diagnostics. */
+export declare function buildRouteRelationFacts(graph: ModuleGraph, routes: readonly RouteFact[], tables: readonly TableFact[], views: readonly ViewFact[]): RouteRelationsScan;

package/dist/passes/route-relations.js

@@ -0,0 +1,43 @@
+/**
+ * Route handler -> relation usage (D-157), the pass that makes `dbTables` an applied
+ * declaration: what a route reaches through `ctx.db` and the audited `ctx.sudo`/`ctx.system`
+ * callback clients is compared with what it declares, tables and views alike.
+ *
+ * The walk lives in route-relations-walk.ts / route-relations-follow.ts and the diagnostics in
+ * route-relations-diagnostics.ts (300-line split). A route with an invalid wrapper keeps an
+ * explicitly empty usage: the wrapper error is the finding, not a guessed relation set.
+ */
+import { callArguments, unwrapExpression } from "../ast/node.js";
+import { EMPTY_ROUTE_RELATIONS } from "../types-relations.js";
+import { createRelationIndex } from "./route-relation-resolve.js";
+import { routeRelationDiagnostics } from "./route-relations-diagnostics.js";
+import { scanHandlerUsage } from "./route-relations-walk.js";
+import { resolveWrapperCall } from "./routes.js";
+function handlerOf(call) {
+    if (call === null)
+        return undefined;
+    return unwrapExpression(callArguments(call)[1]);
+}
+/** Attach relation-usage facts to every scannable route and derive the D-157 diagnostics. */
+export function buildRouteRelationFacts(graph, routes, tables, views) {
+    const index = createRelationIndex(tables, views);
+    const enriched = [];
+    const diagnostics = [];
+    for (const route of routes) {
+        const file = graph.file(route.sourceFile);
+        const handler = file === undefined || route.wrapper !== "valid"
+            ? undefined
+            : handlerOf(resolveWrapperCall(file));
+        if (file === undefined ||
+            handler === undefined ||
+            (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")) {
+            const relations = EMPTY_ROUTE_RELATIONS;
+            enriched.push({ ...route, relations });
+            continue;
+        }
+        const relations = scanHandlerUsage(graph, file, handler, index);
+        enriched.push({ ...route, relations });
+        diagnostics.push(...routeRelationDiagnostics(route, relations));
+    }
+    return { routes: enriched, diagnostics };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The explicit react-router route table (`src/app.tsx`): URL paths and their element trees.
+ *
+ * The generated frontend contract keeps routing in one file with no file-based magic
+ * (docs/FRONTEND.md §2), so the table can be read statically. Only <Route>/<Routes> imported
+ * from react-router-dom count; a local component with the same name is not routing.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { SourceRef } from "../types.js";
+export interface RouteEntry {
+    /** Normalized URL path; "*" for a catch-all route. */
+    readonly path: string;
+    /** The route's element JSX, when it is a JSX element rather than a component reference. */
+    readonly element: AstNode | null;
+    /** Index of the parent route entry (pathless layout routes are entries too). */
+    readonly parentIndex: number | null;
+    readonly source: SourceRef;
+}
+/** Read the route table from the project's app file (empty when absent or unreadable). */
+export declare function buildRouteTable(graph: ModuleGraph, file: ProjectFile): readonly RouteEntry[];

package/dist/passes/route-table.js

@@ -0,0 +1,104 @@
+/**
+ * The explicit react-router route table (`src/app.tsx`): URL paths and their element trees.
+ *
+ * The generated frontend contract keeps routing in one file with no file-based magic
+ * (docs/FRONTEND.md §2), so the table can be read statically. Only <Route>/<Routes> imported
+ * from react-router-dom count; a local component with the same name is not routing.
+ */
+import { asNode } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { sourceRef } from "../source.js";
+import { evaluateStatic } from "../static-eval.js";
+import { elementName, jsxAttribute, jsxAttributeValue, jsxChildren } from "./jsx.js";
+function normalizePath(value) {
+    if (value === "*")
+        return "*";
+    const withSlash = value.startsWith("/") ? value : "/" + value;
+    const collapsed = withSlash.replace(/\/{2,}/g, "/");
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+function joinPath(parent, child) {
+    if (child.startsWith("/") || child === "*")
+        return normalizePath(child);
+    const base = parent === null || parent === "/" ? "" : parent.replace(/\/+$/, "");
+    return normalizePath(base + "/" + child);
+}
+function stringAttribute(node, name, graph, file) {
+    const value = jsxAttributeValue(jsxAttribute(node, name));
+    if (value === undefined)
+        return null;
+    const evaluated = evaluateStatic(value, { graph, file: file.path });
+    return evaluated.ok && typeof evaluated.value === "string" ? evaluated.value : null;
+}
+function importedLocals(file, imported) {
+    const names = new Set();
+    for (const entry of file.module.imports) {
+        if (entry.specifier !== "react-router-dom")
+            continue;
+        if ((entry.imported ?? "default") !== imported)
+            continue;
+        names.add(entry.local);
+    }
+    return names;
+}
+function findRoutesElement(file, locals) {
+    let found = null;
+    walk(file.program, (node) => {
+        if (found !== null || node.type !== "JSXElement")
+            return;
+        const name = elementName(node);
+        if (name !== null && locals.has(name))
+            found = node;
+    });
+    return found;
+}
+/** Read the route table from the project's app file (empty when absent or unreadable). */
+export function buildRouteTable(graph, file) {
+    const routesLocals = importedLocals(file, "Routes");
+    const routeLocals = importedLocals(file, "Route");
+    if (routesLocals.size === 0 || routeLocals.size === 0)
+        return [];
+    const routes = findRoutesElement(file, routesLocals);
+    if (routes === null)
+        return [];
+    const entries = [];
+    const parseRoute = (node, parentIndex, parentPath) => {
+        const pathValue = stringAttribute(node, "path", graph, file);
+        const isIndex = jsxAttribute(node, "index") !== undefined;
+        const path = pathValue === null ? (parentPath ?? "/") : joinPath(parentPath, pathValue);
+        const finalPath = isIndex ? (parentPath ?? "/") : path;
+        const element = asNode(jsxAttributeValue(jsxAttribute(node, "element")));
+        const index = entries.length;
+        entries.push({
+            path: finalPath,
+            element: element !== undefined && element.type === "JSXElement" ? element : null,
+            parentIndex,
+            source: sourceRef(file.path, file.source, typeof node.start === "number" ? node.start : 0),
+        });
+        for (const child of jsxChildren(node)) {
+            if (child.type === "JSXElement" && routeLocals.has(elementName(child) ?? "")) {
+                parseRoute(child, index, finalPath);
+            }
+            else if (child.type === "JSXFragment") {
+                for (const nested of jsxChildren(child)) {
+                    if (nested.type === "JSXElement" && routeLocals.has(elementName(nested) ?? "")) {
+                        parseRoute(nested, index, finalPath);
+                    }
+                }
+            }
+        }
+    };
+    for (const child of jsxChildren(routes)) {
+        if (child.type === "JSXElement" && routeLocals.has(elementName(child) ?? "")) {
+            parseRoute(child, null, null);
+        }
+        else if (child.type === "JSXFragment") {
+            for (const nested of jsxChildren(child)) {
+                if (nested.type === "JSXElement" && routeLocals.has(elementName(nested) ?? "")) {
+                    parseRoute(nested, null, null);
+                }
+            }
+        }
+    }
+    return entries;
+}

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

@@ -0,0 +1,10 @@
+import type { Diagnostic, RouteFact, TableFact } from "../types.js";
+/**
+ * D-137: a route cannot declare a **system-only** table in its wrapper config. By D-136 that
+ * table has no privilege for `facilis_app`, so a query on the route's `ctx.db` fails closed
+ * with `permission denied`; the only legal access is the audited `ctx.sudo`/`ctx.system`
+ * elevation. A table that appears among the route's elevation `tables` is therefore excluded,
+ * and the diagnostic is a warning, not a gate error: an elevation whose table list is dynamic
+ * (`tables: loadTables()`) is recorded as unknown, and a warning must not fail that route's CI.
+ */
+export declare function routeSystemTableDiagnostics(routes: readonly RouteFact[], tables: readonly TableFact[]): readonly Diagnostic[];

package/dist/passes/route-tables.js

@@ -0,0 +1,42 @@
+import { warning } from "../diagnostics.js";
+/**
+ * D-137: a route cannot declare a **system-only** table in its wrapper config. By D-136 that
+ * table has no privilege for `facilis_app`, so a query on the route's `ctx.db` fails closed
+ * with `permission denied`; the only legal access is the audited `ctx.sudo`/`ctx.system`
+ * elevation. A table that appears among the route's elevation `tables` is therefore excluded,
+ * and the diagnostic is a warning, not a gate error: an elevation whose table list is dynamic
+ * (`tables: loadTables()`) is recorded as unknown, and a warning must not fail that route's CI.
+ */
+export function routeSystemTableDiagnostics(routes, tables) {
+    const byName = new Map();
+    for (const table of tables) {
+        if (!byName.has(table.name))
+            byName.set(table.name, table);
+    }
+    const diagnostics = [];
+    for (const route of routes) {
+        const declared = declaredTables(route);
+        if (declared.size === 0)
+            continue;
+        const elevated = new Set(route.elevations.flatMap((elevation) => elevation.tables));
+        for (const name of declared) {
+            const table = byName.get(name);
+            if (table === undefined || table.rlsEnabled || elevated.has(name))
+                continue;
+            diagnostics.push(warning("route-system-table", 'table "' +
+                name +
+                '" is system-only (no RLS); reach it through ctx.sudo/ctx.system, not the route db', route.source));
+        }
+    }
+    return diagnostics;
+}
+/** Every table the wrapper config names: `dbTables` plus the table side of `dbColumns`. */
+function declaredTables(route) {
+    const names = new Set(route.dbTables ?? []);
+    for (const entry of route.dbColumns ?? []) {
+        const separator = entry.indexOf(".");
+        if (separator > 0)
+            names.add(entry.slice(0, separator));
+    }
+    return names;
+}

package/dist/passes/routes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Route files -> RouteFacts (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * A route is listed even when it does not use the wrapper: the graph is also the integrity
+ * view, so an invalid route is reported instead of omitted. The filename is the only source
+ * of method/path (Nitro's file router); the default export is the only source of the config.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ConfigFacts, Diagnostic, RouteFact } from "../types.js";
+export interface RouteResult {
+    readonly routes: readonly RouteFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** The `defineAuthorizedHandler(...)` call of a valid wrapper, for later passes (D-157). */
+export declare function resolveWrapperCall(file: ProjectFile): AstNode | null;
+/** Read `server/routes/**` and `server/api/**` into route facts. */
+export declare function buildRouteFacts(graph: ModuleGraph, config: ConfigFacts): RouteResult;

package/dist/passes/routes.js

@@ -0,0 +1,152 @@
+/**
+ * Route files -> RouteFacts (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * A route is listed even when it does not use the wrapper: the graph is also the integrity
+ * view, so an invalid route is reported instead of omitted. The filename is the only source
+ * of method/path (Nitro's file router); the default export is the only source of the config.
+ */
+import { identifierName, unwrapExpression } from "../ast/node.js";
+import { error, info, warning } from "../diagnostics.js";
+import { defaultExportDeclaration } from "../module-info.js";
+import { sourceRef } from "../source.js";
+import { EMPTY_ROUTE_RELATIONS } from "../types-relations.js";
+import { routeConfigFacts } from "./route-config.js";
+import { scanElevations } from "./route-elevation.js";
+import { directDbWarnings, handlerReadsBody, handlerReadsForm } from "./route-handler.js";
+import { routeLocationFromFile } from "./route-location.js";
+import { defaultExportExpression, isLocallyDeclared, relativePath, sortDiagnostics, } from "./static-read.js";
+const CORE_SPECIFIER = "@facilis.dev/core";
+const ROUTE_DIRS = ["server/routes/", "server/api/"];
+/** The default export must be a `defineAuthorizedHandler(...)` call of the core import. */
+function resolveWrapper(file) {
+    const expression = defaultExportExpression(file);
+    if (expression === undefined) {
+        return { state: "invalid", call: null, reason: "the route file has no default export" };
+    }
+    if (expression.type !== "CallExpression") {
+        return {
+            state: "invalid",
+            call: null,
+            reason: "the default export is not a defineAuthorizedHandler() call",
+        };
+    }
+    const callee = unwrapExpression(expression.callee);
+    const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+    if (name === undefined) {
+        return { state: "unknown", call: null, reason: "the handler callee cannot be resolved" };
+    }
+    if (isLocallyDeclared(file, name)) {
+        return {
+            state: "invalid",
+            call: null,
+            reason: '"' + name + '" is shadowed by a local declaration',
+        };
+    }
+    const imported = file.module.imports.find((entry) => entry.local === name);
+    if (imported === undefined ||
+        imported.specifier !== CORE_SPECIFIER ||
+        imported.imported !== "defineAuthorizedHandler") {
+        return {
+            state: "invalid",
+            call: null,
+            reason: "the default export is not the defineAuthorizedHandler import from @facilis.dev/core",
+        };
+    }
+    return { state: "valid", call: expression, reason: "" };
+}
+function scanRoute(graph, file, config) {
+    const relative = relativePath(graph.root, file.path);
+    const dir = ROUTE_DIRS.find((candidate) => relative.startsWith(candidate));
+    const declaration = defaultExportDeclaration(file.program);
+    const anchor = declaration?.start ?? 0;
+    if (dir === undefined)
+        return { route: null, diagnostics: [] };
+    const location = routeLocationFromFile(relative.slice(dir.length));
+    if (location === undefined) {
+        return {
+            route: null,
+            diagnostics: [
+                info("unknown", "cannot derive a route method/path from the route file name", sourceRef(file.path, file.source, anchor)),
+            ],
+        };
+    }
+    const wrapper = resolveWrapper(file);
+    const ref = sourceRef(file.path, file.source, wrapper.call?.start ?? anchor);
+    if (wrapper.state !== "valid" || wrapper.call === null) {
+        return {
+            route: {
+                method: location.method,
+                path: location.path,
+                sourceFile: file.path,
+                source: ref,
+                wrapper: wrapper.state,
+                permission: null,
+                crossSite: null,
+                dbTables: null,
+                dbColumns: null,
+                rawSql: null,
+                relations: EMPTY_ROUTE_RELATIONS,
+                description: null,
+                input: { body: false, form: false, query: false, params: false },
+                handlerBodyRead: false,
+                handlerFormRead: false,
+                elevations: [],
+                unknown: [{ code: "route-wrapper", reason: wrapper.reason, source: ref }],
+            },
+            diagnostics: [error("route-wrapper", wrapper.reason, ref)],
+        };
+    }
+    const facts = routeConfigFacts(graph, file, wrapper.call, config);
+    const elevation = scanElevations(graph, file, wrapper.call);
+    return {
+        route: {
+            method: location.method,
+            path: location.path,
+            sourceFile: file.path,
+            source: ref,
+            wrapper: "valid",
+            permission: facts.permission,
+            crossSite: facts.crossSite,
+            dbTables: facts.dbTables,
+            dbColumns: facts.dbColumns,
+            rawSql: facts.rawSql,
+            relations: EMPTY_ROUTE_RELATIONS,
+            description: facts.description,
+            input: facts.input,
+            handlerBodyRead: handlerReadsBody(wrapper.call),
+            handlerFormRead: handlerReadsForm(wrapper.call),
+            elevations: elevation.facts,
+            unknown: [...facts.unknown, ...elevation.unknown],
+        },
+        diagnostics: [
+            ...facts.diagnostics,
+            ...elevation.unknown.map((item) => 
+            // An unreadable elevation cannot be shown in the graph; warn without blocking the route.
+            warning(item.code, item.reason, item.source)),
+            ...directDbWarnings(file, ref),
+        ],
+    };
+}
+/** The `defineAuthorizedHandler(...)` call of a valid wrapper, for later passes (D-157). */
+export function resolveWrapperCall(file) {
+    const wrapper = resolveWrapper(file);
+    return wrapper.state === "valid" ? wrapper.call : null;
+}
+/** Read `server/routes/**` and `server/api/**` into route facts. */
+export function buildRouteFacts(graph, config) {
+    const files = [...graph.files.values()]
+        .filter((file) => ROUTE_DIRS.some((dir) => relativePath(graph.root, file.path).startsWith(dir)))
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+    const routes = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const scanned = scanRoute(graph, file, config);
+        if (scanned.route !== null)
+            routes.push(scanned.route);
+        diagnostics.push(...scanned.diagnostics);
+    }
+    routes.sort((left, right) => left.path.localeCompare(right.path) ||
+        left.method.localeCompare(right.method) ||
+        left.sourceFile.localeCompare(right.sourceFile));
+    return { routes, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/schema-column-types.d.ts

@@ -0,0 +1,9 @@
+import type { AstNode } from "../ast/node.js";
+import { type StaticContext } from "../static-eval.js";
+import type { ColumnDefaultFact } from "../types.js";
+/** Static object argument of a builder/method, e.g. `{ withTimezone: true }`. */
+export declare function optionsOf(node: AstNode | undefined, context: StaticContext): Record<string, unknown> | null;
+/** Display type derived from the builder and its static arguments (never a rendered SQL type). */
+export declare function displayType(name: string, args: readonly AstNode[], context: StaticContext): string;
+/** `.default(value)`: only primitives are facts; a SQL expression is an explicit unknown. */
+export declare function readDefault(node: AstNode | undefined, context: StaticContext): ColumnDefaultFact;