@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/route-config.ts

@@ -0,0 +1,188 @@
+/**
+ * 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, type AstNode } from "../ast/node.ts";
+import { error, warning } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { StaticContext } from "../static-eval.ts";
+import type { ConfigFacts, Diagnostic, RouteInputFact, SourceRef, UnknownFact } from "../types.ts";
+import { descriptionDiagnostics } from "./route-description.ts";
+import { readStaticObject, refOf, type StaticField } from "./static-read.ts";
+
+const MISSING_PERMISSION = "permission is missing";
+const MISSING_TABLES = "dbTables is missing; declare an array ([] means no DB)";
+
+export interface RouteConfigFacts {
+  readonly permission: readonly string[] | null;
+  /** True when the wrapper opts the route into cross-origin calls; null when unreadable. */
+  readonly crossSite: boolean | null;
+  /** rawSql: true allows `db.execute` (D-157); false when absent; null when unreadable. */
+  readonly rawSql: boolean | null;
+  readonly dbTables: readonly string[] | null;
+  readonly dbColumns: readonly string[] | null;
+  readonly description: string | null;
+  readonly input: RouteInputFact;
+  readonly unknown: readonly UnknownFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function stringArrayValue(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((item): item is string => typeof item === "string") ? [...value] : null;
+}
+
+function permissionValue(value: unknown): string[] | null {
+  return typeof value === "string" ? [value] : stringArrayValue(value);
+}
+
+function addUnknown(list: UnknownFact[], code: string, reason: string, source: SourceRef): void {
+  list.push({ code, reason, source });
+}
+
+function unreadable(field: string, entry: StaticField): string {
+  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: ModuleGraph,
+  file: ProjectFile,
+  call: AstNode,
+  config: ConfigFacts,
+): RouteConfigFacts {
+  const context: StaticContext = { 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: UnknownFact[] = [...object.unknown];
+  const field = (name: string): StaticField | undefined => object.fields.get(name);
+
+  const permissionField = field("permission");
+  let permission: string[] | null = 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: boolean | null = 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: boolean | null = 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: string[] | null = 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: string[] | null = 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: string | null = 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: RouteInputFact = {
+    body: field("body") !== undefined,
+    form: field("form") !== undefined,
+    query: field("query") !== undefined,
+    params: field("params") !== undefined,
+  };
+
+  const diagnostics: Diagnostic[] = [
+    ...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/src/passes/route-description.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.ts";
+import type { Diagnostic, SourceRef } from "../types.ts";
+
+/** 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: string | null,
+  source: SourceRef | null,
+): readonly Diagnostic[] {
+  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/src/passes/route-elevation.ts

@@ -0,0 +1,161 @@
+/**
+ * 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,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { ElevationFact, ElevationKind, SourceRef, UnknownFact } from "../types.ts";
+import { readStaticObject } from "./static-read.ts";
+
+export interface ElevationScan {
+  readonly facts: readonly ElevationFact[];
+  readonly unknown: readonly UnknownFact[];
+}
+
+function refOf(file: ProjectFile, node: AstNode): SourceRef {
+  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: string | undefined): ElevationKind | null {
+  if (name === "sudo" || name === "system") return name;
+  return null;
+}
+
+interface HandlerBindings {
+  readonly locals: ReadonlyMap<string, ElevationKind>;
+  readonly contextName: string | null;
+}
+
+/** Local identifier -> elevation kind for `{ sudo }` / `{ sudo: elevate }`. */
+function handlerBindings(handler: AstNode): HandlerBindings {
+  const locals = new Map<string, ElevationKind>();
+  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: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((entry): entry is string => typeof entry === "string") ? [...value] : null;
+}
+
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export function scanElevations(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  wrapperCall: AstNode,
+): ElevationScan {
+  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: ElevationFact[] = [];
+  const unknown: UnknownFact[] = [];
+  walk(handlerNode, (node) => {
+    if (node.type !== "CallExpression") return;
+    const callee = unwrapExpression(node.callee);
+    if (callee === undefined) return;
+    let kind: ElevationKind | null = 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: UnknownFact[] = [...options.unknown];
+    const tablesField = options.fields.get("tables");
+    let tables: string[] = [];
+    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/src/passes/route-handler.ts

@@ -0,0 +1,105 @@
+/**
+ * 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,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import { warning } from "../diagnostics.ts";
+import type { ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { Diagnostic, SourceRef } from "../types.ts";
+
+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: ProjectFile, node: AstNode, fallback: SourceRef): SourceRef {
+  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: AstNode): boolean {
+  let current: AstNode | undefined = 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: AstNode): boolean {
+  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: AstNode, name: string): boolean {
+  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: AstNode): boolean {
+  return handlerReads(call, "body");
+}
+
+/** True when the handler reads `.form` or destructures a `{ form }` pattern (D-053). */
+export function handlerReadsForm(call: AstNode): boolean {
+  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: ProjectFile, fallback: SourceRef): Diagnostic[] {
+  const refs: SourceRef[] = [];
+  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/src/passes/route-location.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.ts";
+
+export interface RouteLocation {
+  readonly method: HttpMethod;
+  readonly path: string;
+}
+
+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: string): string {
+  // 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: string): { name: string; method: HttpMethod } | undefined {
+  let name = segment;
+  const env = name.match(ENV_SUFFIX);
+  if (env !== null) name = name.slice(0, -env[0].length);
+  let method: HttpMethod = "ALL";
+  const methodMatch = name.match(METHOD_SUFFIX);
+  if (methodMatch?.[1] !== undefined) {
+    method = methodMatch[1].toUpperCase() as HttpMethod;
+    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: string): RouteLocation | undefined {
+  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: Pick<RouteFact, "method" | "path">): string {
+  return "route:" + route.method + " " + route.path;
+}