@facilis.dev/analyze 0.0.0-stage → 0.1.1

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

package/src/passes/schema-column-types.ts

@@ -0,0 +1,62 @@
+import type { AstNode } from "../ast/node.ts";
+import { isRecord } from "../json.ts";
+import { evaluateStatic, type StaticContext } from "../static-eval.ts";
+import type { ColumnDefaultFact } from "../types.ts";
+
+/** Static object argument of a builder/method, e.g. `{ withTimezone: true }`. */
+export function optionsOf(
+  node: AstNode | undefined,
+  context: StaticContext,
+): Record<string, unknown> | null {
+  if (node === undefined) return null;
+  const evaluated = evaluateStatic(node, context);
+  return evaluated.ok && isRecord(evaluated.value) ? evaluated.value : null;
+}
+
+/** Display type derived from the builder and its static arguments (never a rendered SQL type). */
+export function displayType(
+  name: string,
+  args: readonly AstNode[],
+  context: StaticContext,
+): string {
+  switch (name) {
+    case "varchar": {
+      const length = optionsOf(args[1], context)?.["length"];
+      return typeof length === "number" ? "varchar(" + length + ")" : "varchar";
+    }
+    case "timestamp": {
+      const options = optionsOf(args[1], context);
+      const precision = options?.["precision"];
+      const base = typeof precision === "number" ? "timestamp(" + precision + ")" : "timestamp";
+      return options?.["withTimezone"] === true ? base + " with time zone" : base;
+    }
+    case "numeric": {
+      const options = optionsOf(args[1], context);
+      const precision = options?.["precision"];
+      if (typeof precision !== "number") return "numeric";
+      const scale = options?.["scale"];
+      return typeof scale === "number"
+        ? "numeric(" + precision + ", " + scale + ")"
+        : "numeric(" + precision + ")";
+    }
+    case "doublePrecision":
+      return "double precision";
+    case "tenantColumn":
+      return "uuid";
+    default:
+      return name;
+  }
+}
+
+/** `.default(value)`: only primitives are facts; a SQL expression is an explicit unknown. */
+export function readDefault(node: AstNode | undefined, context: StaticContext): ColumnDefaultFact {
+  if (node === undefined) return { kind: "unknown", value: null };
+  const evaluated = evaluateStatic(node, context);
+  if (!evaluated.ok) return { kind: "unknown", value: null };
+  const value = evaluated.value;
+  if (value === null) return { kind: "literal", value: "null" };
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return { kind: "literal", value: String(value) };
+  }
+  return { kind: "unknown", value: null };
+}

package/src/passes/schema-columns.ts

@@ -0,0 +1,287 @@
+import {
+  callArguments,
+  identifierName,
+  literalString,
+  memberName,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { staticString, type StaticContext } from "../static-eval.ts";
+import type {
+  ColumnDefaultFact,
+  ColumnFact,
+  Diagnostic,
+  SourceRef,
+  UnknownFact,
+} from "../types.ts";
+import {
+  callbackExpression,
+  nodeRef,
+  schemaDiagnostics,
+  schemaUnknown,
+  type DslResolver,
+  type DslSymbol,
+} from "./schema-dsl.ts";
+import { displayType, optionsOf, readDefault } from "./schema-column-types.ts";
+
+/** A `.references(() => table.column, opts)` target; the table name is resolved after every draft exists. */
+export interface ForeignKeyTarget {
+  readonly binding: string;
+  readonly property: string;
+  readonly onDelete: string | null;
+  readonly onUpdate: string | null;
+  readonly source: SourceRef;
+}
+
+export interface ColumnReference {
+  readonly column: string;
+  readonly target: ForeignKeyTarget;
+}
+
+export interface ColumnResult {
+  readonly column: ColumnFact;
+  readonly reference: ForeignKeyTarget | null;
+  /** True when the builder is `tenantColumn()`; the table pass turns it into a scope fact. */
+  readonly tenant: boolean;
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+export interface ColumnInput {
+  readonly property: string;
+  readonly expression: unknown;
+  /** Property node: the source line when the value is unreadable. */
+  readonly propertyNode: AstNode;
+  readonly file: ProjectFile;
+  readonly graph: ModuleGraph;
+  readonly resolver: DslResolver;
+  /** Local `pgEnum` const bindings, local name -> enum name. */
+  readonly enums: ReadonlyMap<string, string>;
+}
+
+interface MethodCall {
+  readonly name: string;
+  readonly args: readonly AstNode[];
+  readonly node: AstNode;
+}
+
+interface BuilderChain {
+  readonly builder: DslSymbol | null;
+  readonly calleeName: string;
+  readonly args: readonly AstNode[];
+  readonly methods: readonly MethodCall[];
+  readonly enumType: string | null;
+}
+
+const PG_BUILDERS = new Set([
+  "uuid",
+  "text",
+  "boolean",
+  "timestamp",
+  "varchar",
+  "integer",
+  "bigint",
+  "numeric",
+  "date",
+  "jsonb",
+  "json",
+  "serial",
+  "bigserial",
+  "real",
+  "doublePrecision",
+]);
+
+function isKnownBuilder(symbol: DslSymbol): boolean {
+  if (symbol.pkg === "pg-core") return PG_BUILDERS.has(symbol.name);
+  return symbol.pkg === "facilis-db" && symbol.name === "tenantColumn";
+}
+
+/** Split `uuid("id").primaryKey().defaultRandom()` into its builder call and chained methods. */
+function readBuilderChain(
+  expression: unknown,
+  resolver: DslResolver,
+  enums: ReadonlyMap<string, string>,
+): BuilderChain | null {
+  let current = unwrapExpression(expression);
+  const methods: MethodCall[] = [];
+  let guard = 0;
+  while (current !== undefined && guard < 32) {
+    guard += 1;
+    if (current.type !== "CallExpression") return null;
+    const callee = unwrapExpression(current.callee);
+    if (callee === undefined) return null;
+    const args = callArguments(current);
+    if (callee.type === "MemberExpression") {
+      const name = memberName(callee);
+      if (name === undefined) return null;
+      methods.unshift({ name, args, node: current });
+      current = unwrapExpression(callee.object);
+      continue;
+    }
+    const calleeName = identifierName(callee);
+    if (calleeName === undefined) return null;
+    const enumType = enums.get(calleeName);
+    if (enumType !== undefined) {
+      return { builder: null, calleeName, args, methods, enumType };
+    }
+    return { builder: resolver(callee), calleeName, args, methods, enumType: null };
+  }
+  return null;
+}
+
+function optionString(
+  options: Record<string, unknown>,
+  key: string,
+  source: SourceRef,
+  unknowns: UnknownFact[],
+): string | null {
+  if (!Object.hasOwn(options, key)) return null;
+  const value = options[key];
+  if (typeof value === "string") return value;
+  unknowns.push(schemaUnknown('references() option "' + key + '" is not a string', source));
+  return null;
+}
+
+function readReference(
+  method: MethodCall,
+  context: StaticContext,
+  file: ProjectFile,
+): { target: ForeignKeyTarget | null; unknowns: UnknownFact[] } {
+  const source = nodeRef(file, method.node);
+  const target = callbackExpression(method.args[0]);
+  const binding =
+    target?.type === "MemberExpression"
+      ? identifierName(unwrapExpression(target.object))
+      : undefined;
+  const property = target?.type === "MemberExpression" ? memberName(target) : undefined;
+  if (binding === undefined || property === undefined) {
+    return {
+      target: null,
+      unknowns: [
+        schemaUnknown("references() target is not a static table.column reference", source),
+      ],
+    };
+  }
+  const unknowns: UnknownFact[] = [];
+  let onDelete: string | null = null;
+  let onUpdate: string | null = null;
+  if (method.args[1] !== undefined) {
+    const options = optionsOf(method.args[1], context);
+    if (options === null) {
+      unknowns.push(schemaUnknown("references() options are not static", source));
+    } else {
+      onDelete = optionString(options, "onDelete", source, unknowns);
+      onUpdate = optionString(options, "onUpdate", source, unknowns);
+    }
+  }
+  return { target: { binding, property, onDelete, onUpdate, source }, unknowns };
+}
+
+export function buildColumnFact(input: ColumnInput): ColumnResult {
+  const context: StaticContext = { graph: input.graph, file: input.file.path };
+  const valueNode = unwrapExpression(input.expression);
+  const source = nodeRef(input.file, valueNode ?? input.propertyNode);
+  const chain = readBuilderChain(input.expression, input.resolver, input.enums);
+  const unknowns: UnknownFact[] = [];
+  let builder = "unknown";
+  let type = "unknown";
+  let name = input.property;
+  let tenant = false;
+  let reference: ForeignKeyTarget | null = null;
+
+  if (chain === null) {
+    unknowns.push(
+      schemaUnknown('column "' + input.property + '" is not a column builder call', source),
+    );
+  } else if (chain.enumType !== null) {
+    builder = chain.calleeName;
+    type = chain.enumType;
+    name = literalString(chain.args[0]) ?? input.property;
+  } else if (chain.builder !== null && isKnownBuilder(chain.builder)) {
+    builder = chain.builder.name;
+    type = displayType(chain.builder.name, chain.args, context);
+    tenant = chain.builder.pkg === "facilis-db" && chain.builder.name === "tenantColumn";
+    const first = chain.args[0];
+    if (first === undefined) {
+      // `tenantColumn()` defaults its SQL name to tenant_id in @facilis.dev/db; other builders use the property key.
+      name = tenant ? "tenant_id" : input.property;
+    } else {
+      const evaluated = staticString(first, context);
+      if (evaluated.ok) {
+        name = evaluated.value;
+      } else {
+        unknowns.push(
+          schemaUnknown('SQL name of column "' + input.property + '" is not static', source),
+        );
+      }
+    }
+  } else {
+    builder = chain.builder?.name ?? chain.calleeName;
+    name = literalString(chain.args[0]) ?? input.property;
+    unknowns.push(
+      schemaUnknown('column builder "' + builder + '" is outside the documented DSL', source),
+    );
+  }
+
+  let notNull = false;
+  let primaryKey = false;
+  let unique = false;
+  let columnDefault: ColumnDefaultFact | null = null;
+  let array = false;
+  if (chain !== null) {
+    for (const method of chain.methods) {
+      switch (method.name) {
+        case "notNull":
+          notNull = true;
+          break;
+        case "primaryKey":
+          primaryKey = true;
+          break;
+        case "unique":
+          unique = true;
+          break;
+        case "default":
+          columnDefault = readDefault(method.args[0], context);
+          break;
+        case "defaultRandom":
+          columnDefault = { kind: "random", value: null };
+          break;
+        case "defaultNow":
+          columnDefault = { kind: "now", value: null };
+          break;
+        case "array":
+          array = true;
+          break;
+        case "references": {
+          const result = readReference(method, context, input.file);
+          reference = result.target;
+          unknowns.push(...result.unknowns);
+          break;
+        }
+        default:
+          unknowns.push(
+            schemaUnknown(
+              'column method ".' + method.name + '" is outside the documented DSL',
+              nodeRef(input.file, method.node),
+            ),
+          );
+          break;
+      }
+    }
+  }
+  if (array && type !== "unknown") type += "[]";
+
+  const column: ColumnFact = {
+    property: input.property,
+    name,
+    builder,
+    type,
+    notNull,
+    primaryKey,
+    unique,
+    default: columnDefault,
+    source,
+    unknown: unknowns,
+  };
+  return { column, reference, tenant, diagnostics: schemaDiagnostics(unknowns) };
+}

package/src/passes/schema-dsl.ts

@@ -0,0 +1,136 @@
+import {
+  identifierName,
+  isAstNode,
+  memberName,
+  nodeArray,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { diagnostic } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { Diagnostic, Severity, SourceRef, UnknownFact } from "../types.ts";
+
+/** Package a DSL symbol came from; calls are classified by import specifier, never by name. */
+export type DslPackage = "pg-core" | "drizzle-orm" | "facilis-db";
+
+export interface DslSymbol {
+  readonly name: string;
+  readonly pkg: DslPackage;
+}
+
+/** Resolves a callee expression to a whitelisted DSL symbol imported from a known package. */
+export type DslResolver = (callee: unknown) => DslSymbol | null;
+
+function packageOf(specifier: string): DslPackage | null {
+  if (specifier === "drizzle-orm/pg-core" || specifier.startsWith("drizzle-orm/pg-core/")) {
+    return "pg-core";
+  }
+  if (specifier === "drizzle-orm" || specifier.startsWith("drizzle-orm/")) return "drizzle-orm";
+  if (specifier === "@facilis.dev/db" || specifier.startsWith("@facilis.dev/db/")) return "facilis-db";
+  return null;
+}
+
+/** Package classification for an aliased specifier that resolved into an installed package. */
+function packageOfResolved(path: string): DslPackage | null {
+  if (path.includes("node_modules/drizzle-orm/pg-core/")) return "pg-core";
+  if (path.includes("node_modules/drizzle-orm/")) return "drizzle-orm";
+  if (path.includes("node_modules/@facilis.dev/db/")) return "facilis-db";
+  return null;
+}
+
+export function createDslResolver(graph: ModuleGraph, file: ProjectFile): DslResolver {
+  const named = new Map<string, DslSymbol>();
+  const namespaces = new Map<string, DslPackage>();
+  for (const imported of file.module.imports) {
+    let pkg = packageOf(imported.specifier);
+    if (pkg === null) {
+      const resolved = graph.resolve(file.path, imported.specifier);
+      if (resolved !== null) pkg = packageOfResolved(resolved);
+    }
+    if (pkg === null) continue;
+    if (imported.kind === "namespace") {
+      namespaces.set(imported.local, pkg);
+      continue;
+    }
+    if (imported.kind !== "named" || imported.imported === null) continue;
+    named.set(imported.local, { name: imported.imported, pkg });
+  }
+  return (callee) => {
+    const node = unwrapExpression(callee);
+    if (node === undefined) return null;
+    if (node.type === "Identifier") {
+      const local = identifierName(node);
+      return local === undefined ? null : (named.get(local) ?? null);
+    }
+    if (node.type !== "MemberExpression" || node.computed === true) return null;
+    const namespace = identifierName(unwrapExpression(node.object));
+    const pkg = namespace === undefined ? undefined : namespaces.get(namespace);
+    const name = memberName(node);
+    if (pkg === undefined || name === undefined) return null;
+    return { name, pkg };
+  };
+}
+
+/** Variable declarators at module top level, including `export const ...`. */
+export function topLevelDeclarators(program: AstNode): AstNode[] {
+  const out: AstNode[] = [];
+  for (const statement of nodeArray(program, "body")) {
+    const declaration =
+      statement.type === "VariableDeclaration"
+        ? statement
+        : statement.type === "ExportNamedDeclaration" && isAstNode(statement.declaration)
+          ? statement.declaration
+          : undefined;
+    if (declaration === undefined || declaration.type !== "VariableDeclaration") continue;
+    out.push(...nodeArray(declaration, "declarations"));
+  }
+  return out;
+}
+
+/** The expression a callback returns; supports `() => x` and `() => { return x; }`. */
+export function callbackExpression(callback: AstNode | undefined): AstNode | undefined {
+  const fn = unwrapExpression(callback);
+  if (fn === undefined) return undefined;
+  if (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression") return undefined;
+  const body = unwrapExpression(fn.body);
+  if (body === undefined || body.type !== "BlockStatement") return body;
+  const returns = nodeArray(body, "body").filter(
+    (statement) => statement.type === "ReturnStatement",
+  );
+  const statement = returns.length === 1 ? returns[0] : undefined;
+  return statement === undefined ? undefined : unwrapExpression(statement.argument);
+}
+
+export function nodeRef(file: ProjectFile, node: AstNode | undefined): SourceRef {
+  return sourceRef(file.path, file.source, typeof node?.start === "number" ? node.start : 0);
+}
+
+/** Schema DSL files live under the project's `db/` directory (root-aware). */
+export function isSchemaFile(graph: ModuleGraph, path: string): boolean {
+  const prefix = graph.root.length === 0 ? "db/" : graph.root + "/db/";
+  return path.startsWith(prefix);
+}
+
+/** View declarations live under `db/views/` (SPEC §11.2, D-157). */
+export function isViewFile(graph: ModuleGraph, path: string): boolean {
+  const prefix = graph.root.length === 0 ? "db/views/" : graph.root + "/db/views/";
+  return path.startsWith(prefix);
+}
+
+export function schemaUnknown(reason: string, source: SourceRef): UnknownFact {
+  return { code: "schema-static", reason, source };
+}
+
+function severityOf(code: string): Severity {
+  if (code === "fk-target-known") return "warning";
+  if (code === "unknown") return "info";
+  return "error";
+}
+
+/** Unknowns are also diagnostics: the fact model never hides what the interpreter could not read. */
+export function schemaDiagnostics(unknowns: readonly UnknownFact[]): Diagnostic[] {
+  return unknowns.map((unknown) =>
+    diagnostic(unknown.code, severityOf(unknown.code), unknown.reason, unknown.source),
+  );
+}