@facilis.dev/analyze 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,98 @@
+/**
+ * Shared state of the route-relations walk (D-157): the mutable relation-usage accumulators
+ * and the per-frame scope. Kept in one module so the walk and the follow helpers agree on
+ * their shape without importing each other.
+ */
+
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type {
+  RouteElevationUsage,
+  RouteRelationUse,
+  RouteRelationsFact,
+} from "../types-relations.ts";
+import type { ElevationKind, SourceRef } from "../types.ts";
+import type { DbClient, RelationIndex } from "./route-relation-resolve.ts";
+
+export interface MutableElevation {
+  readonly kind: ElevationKind;
+  readonly source: SourceRef;
+  readonly tables: readonly string[];
+  readonly tablesUnknown: boolean;
+  readonly used: Map<string, SourceRef>;
+  readonly unresolved: SourceRef[];
+  opaque: boolean;
+}
+
+export interface MutableUsage {
+  readonly used: Map<string, SourceRef>;
+  readonly unresolved: SourceRef[];
+  readonly rawSql: SourceRef[];
+  opaque: boolean;
+  readonly elevations: MutableElevation[];
+}
+
+/** One handler or project-local helper call frame. */
+export interface RelationScope {
+  readonly graph: ModuleGraph;
+  readonly index: RelationIndex;
+  readonly file: ProjectFile;
+  readonly env: Map<string, DbClient>;
+  readonly aliases: Map<string, string>;
+  readonly elevationFns: Map<string, ElevationKind>;
+  readonly contextName: string | null;
+  /**
+   * Whether the scanned body can elevate (`ctx.sudo`/`ctx.system`). Jobs already run
+   * system-scoped, so their pass has no elevation dimension (D-157).
+   */
+  readonly elevations: boolean;
+  /** Elevation bucket of the current callback; null is the route's own ctx.db. */
+  readonly elevation: number | null;
+  readonly depth: number;
+  readonly stack: ReadonlySet<string>;
+  readonly usage: MutableUsage;
+}
+
+export function createUsage(): MutableUsage {
+  return { used: new Map(), unresolved: [], rawSql: [], opaque: false, elevations: [] };
+}
+
+function bucket(scope: RelationScope): MutableElevation | MutableUsage {
+  const index = scope.elevation;
+  return index === null ? scope.usage : (scope.usage.elevations[index] ?? scope.usage);
+}
+
+export function addUse(scope: RelationScope, name: string, source: SourceRef): void {
+  const target = bucket(scope);
+  if (!target.used.has(name)) target.used.set(name, source);
+}
+
+export function addUnresolved(scope: RelationScope, source: SourceRef): void {
+  bucket(scope).unresolved.push(source);
+}
+
+export function markOpaque(scope: RelationScope): void {
+  bucket(scope).opaque = true;
+}
+
+function freezeElevation(elevation: MutableElevation): RouteElevationUsage {
+  const used: RouteRelationUse[] = [...elevation.used].map(([name, source]) => ({ name, source }));
+  return {
+    kind: elevation.kind,
+    source: elevation.source,
+    tables: [...elevation.tables],
+    used,
+    unresolved: [...elevation.unresolved],
+    tablesUnknown: elevation.tablesUnknown,
+    opaque: elevation.opaque,
+  };
+}
+
+export function freezeUsage(usage: MutableUsage): RouteRelationsFact {
+  return {
+    used: [...usage.used].map(([name, source]) => ({ name, source })),
+    unresolved: [...usage.unresolved],
+    rawSql: [...usage.rawSql],
+    opaque: usage.opaque,
+    elevations: usage.elevations.map(freezeElevation),
+  };
+}

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;
+}