@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/route-relations-walk.ts

@@ -0,0 +1,255 @@
+/**
+ * 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,
+  type AstNode,
+} from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { RouteRelationsFact } from "../types-relations.ts";
+import type { ElevationKind, SourceRef } from "../types.ts";
+import { followFunction, handleElevation } from "./route-relations-follow.ts";
+import {
+  createUsage,
+  freezeUsage,
+  addUnresolved,
+  addUse,
+  markOpaque,
+  type MutableUsage,
+  type RelationScope,
+} from "./route-relations-usage.ts";
+import {
+  carriesClient,
+  chainClient,
+  clientOf,
+  resolveLocalFunction,
+  ROUTE_CLIENT,
+  type DbClient,
+  type RelationIndex,
+} from "./route-relation-resolve.ts";
+
+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"]);
+
+/**
+ * How a scanned function receives its db client. Route handlers are `(event, ctx)` and may
+ * elevate; a job's `run` is `(ctx)` and already runs system-scoped, so it has no elevations.
+ */
+export interface UsageSeed {
+  /** Index of the parameter that carries the db context (route: 1, job run: 0). */
+  readonly contextParam: number;
+  /** Route handlers may call ctx.sudo/ctx.system; jobs may not (D-157). */
+  readonly elevations: boolean;
+}
+
+const ROUTE_SEED: UsageSeed = { contextParam: 1, elevations: true };
+
+function elevationKind(name: string | undefined): ElevationKind | null {
+  return name === "sudo" || name === "system" ? name : null;
+}
+
+function refOf(scope: RelationScope, node: AstNode): SourceRef {
+  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: AstNode | undefined,
+  scope: RelationScope,
+): ElevationKind | null {
+  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: AstNode, scope: RelationScope): void {
+  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: AstNode, scope: RelationScope): void {
+  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: RelationScope, node: AstNode | undefined): void {
+  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: AstNode, scope: RelationScope): boolean {
+  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: AstNode, scope: RelationScope): void {
+  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) as AstNode, scope);
+      continue;
+    }
+    const child = asNode(value);
+    if (child !== undefined) visit(child, scope);
+  }
+}
+
+function functionScope(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  fn: AstNode,
+  index: RelationIndex,
+  usage: MutableUsage,
+  seed: UsageSeed,
+): RelationScope {
+  const env = new Map<string, DbClient>();
+  const elevationFns = new Map<string, ElevationKind>();
+  let contextName: string | null = 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: ModuleGraph,
+  file: ProjectFile,
+  fn: AstNode,
+  index: RelationIndex,
+  seed: UsageSeed,
+): RouteRelationsFact {
+  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: ModuleGraph,
+  file: ProjectFile,
+  handler: AstNode,
+  index: RelationIndex,
+): RouteRelationsFact {
+  return scanFunctionUsage(graph, file, handler, index, ROUTE_SEED);
+}

package/src/passes/route-relations.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.ts";
+import type { ModuleGraph } from "../module-graph.ts";
+import type { RouteFact, TableFact, ViewFact, Diagnostic } from "../types.ts";
+import { EMPTY_ROUTE_RELATIONS, type RouteRelationsFact } from "../types-relations.ts";
+import { createRelationIndex } from "./route-relation-resolve.ts";
+import { routeRelationDiagnostics } from "./route-relations-diagnostics.ts";
+import { scanHandlerUsage } from "./route-relations-walk.ts";
+import { resolveWrapperCall } from "./routes.ts";
+
+export interface RouteRelationsScan {
+  readonly routes: readonly RouteFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function handlerOf(
+  call: ReturnType<typeof resolveWrapperCall>,
+): ReturnType<typeof unwrapExpression> {
+  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: ModuleGraph,
+  routes: readonly RouteFact[],
+  tables: readonly TableFact[],
+  views: readonly ViewFact[],
+): RouteRelationsScan {
+  const index = createRelationIndex(tables, views);
+  const enriched: RouteFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  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: RouteRelationsFact = 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/src/passes/route-table.ts

@@ -0,0 +1,123 @@
+/**
+ * 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, type AstNode } from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import { evaluateStatic } from "../static-eval.ts";
+import type { SourceRef } from "../types.ts";
+import { elementName, jsxAttribute, jsxAttributeValue, jsxChildren } from "./jsx.ts";
+
+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;
+}
+
+function normalizePath(value: string): string {
+  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: string | null, child: string): string {
+  if (child.startsWith("/") || child === "*") return normalizePath(child);
+  const base = parent === null || parent === "/" ? "" : parent.replace(/\/+$/, "");
+  return normalizePath(base + "/" + child);
+}
+
+function stringAttribute(
+  node: AstNode,
+  name: string,
+  graph: ModuleGraph,
+  file: ProjectFile,
+): string | null {
+  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: ProjectFile, imported: "Routes" | "Route"): ReadonlySet<string> {
+  const names = new Set<string>();
+  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: ProjectFile, locals: ReadonlySet<string>): AstNode | null {
+  let found: AstNode | null = 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: ModuleGraph, file: ProjectFile): readonly RouteEntry[] {
+  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: RouteEntry[] = [];
+
+  const parseRoute = (
+    node: AstNode,
+    parentIndex: number | null,
+    parentPath: string | null,
+  ): void => {
+    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/src/passes/route-tables.ts

@@ -0,0 +1,50 @@
+import { warning } from "../diagnostics.ts";
+import type { Diagnostic, RouteFact, TableFact } from "../types.ts";
+
+/**
+ * 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: readonly RouteFact[],
+  tables: readonly TableFact[],
+): readonly Diagnostic[] {
+  const byName = new Map<string, TableFact>();
+  for (const table of tables) {
+    if (!byName.has(table.name)) byName.set(table.name, table);
+  }
+  const diagnostics: Diagnostic[] = [];
+  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: RouteFact): ReadonlySet<string> {
+  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/src/passes/routes.ts

@@ -0,0 +1,188 @@
+/**
+ * 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, type AstNode } from "../ast/node.ts";
+import { error, info, warning } from "../diagnostics.ts";
+import { defaultExportDeclaration } from "../module-info.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import { EMPTY_ROUTE_RELATIONS } from "../types-relations.ts";
+import type { ConfigFacts, Diagnostic, RouteFact, WrapperState } from "../types.ts";
+import { routeConfigFacts } from "./route-config.ts";
+import { scanElevations } from "./route-elevation.ts";
+import { directDbWarnings, handlerReadsBody, handlerReadsForm } from "./route-handler.ts";
+import { routeLocationFromFile } from "./route-location.ts";
+import {
+  defaultExportExpression,
+  isLocallyDeclared,
+  relativePath,
+  sortDiagnostics,
+} from "./static-read.ts";
+
+const CORE_SPECIFIER = "@facilis.dev/core";
+const ROUTE_DIRS = ["server/routes/", "server/api/"];
+
+export interface RouteResult {
+  readonly routes: readonly RouteFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+interface WrapperResolution {
+  readonly state: WrapperState;
+  readonly call: AstNode | null;
+  readonly reason: string;
+}
+
+/** The default export must be a `defineAuthorizedHandler(...)` call of the core import. */
+function resolveWrapper(file: ProjectFile): WrapperResolution {
+  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: ModuleGraph,
+  file: ProjectFile,
+  config: ConfigFacts,
+): { route: RouteFact | null; diagnostics: readonly Diagnostic[] } {
+  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: ProjectFile): AstNode | null {
+  const wrapper = resolveWrapper(file);
+  return wrapper.state === "valid" ? wrapper.call : null;
+}
+
+/** Read `server/routes/**` and `server/api/**` into route facts. */
+export function buildRouteFacts(graph: ModuleGraph, config: ConfigFacts): RouteResult {
+  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: RouteFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  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) };
+}