@facilis.dev/analyze 0.0.0-stage → 0.1.0

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

package/src/passes/schema-file-links-ddl.ts

@@ -0,0 +1,125 @@
+/**
+ * The DDL `@facilis.dev/db`'s `fileLinks` expands to, expressed as analyzer facts (D-053).
+ *
+ * Kept apart from the call-site scan: this module mirrors the framework's fixed table shape,
+ * while `schema-file-links.ts` interprets the project's arguments.
+ */
+
+import type { ColumnDefaultFact, ColumnFact, PolicyFact, SourceRef } from "../types.ts";
+import type { TableDraft } from "./schema-tables.ts";
+
+const FACILIS_FILES = "facilis_files";
+export const FACILIS_FILES_BINDING = "facilisFiles";
+
+interface ColumnInput {
+  readonly property: string;
+  readonly name: string;
+  readonly builder: string;
+  readonly type: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly default: ColumnDefaultFact | null;
+  readonly source: SourceRef;
+}
+
+function column(input: ColumnInput): ColumnFact {
+  return { ...input, unique: false, unknown: [] };
+}
+
+/** The generated link table's columns; `parentColumn` is the `column` option. */
+export function linkColumns(parentColumn: string, source: SourceRef): ColumnFact[] {
+  return [
+    column({
+      property: "id",
+      name: "id",
+      builder: "uuid",
+      type: "uuid",
+      notNull: true,
+      primaryKey: true,
+      default: { kind: "random", value: null },
+      source,
+    }),
+    column({
+      property: "parentId",
+      name: parentColumn,
+      builder: "uuid",
+      type: "uuid",
+      notNull: true,
+      primaryKey: false,
+      default: null,
+      source,
+    }),
+    column({
+      property: "fileId",
+      name: "file_id",
+      builder: "uuid",
+      type: "uuid",
+      notNull: true,
+      primaryKey: false,
+      default: null,
+      source,
+    }),
+    column({
+      property: "tenantId",
+      name: "tenant_id",
+      builder: "tenantColumn",
+      type: "uuid",
+      notNull: true,
+      primaryKey: false,
+      default: null,
+      source,
+    }),
+    column({
+      property: "createdAt",
+      name: "created_at",
+      builder: "timestamp",
+      type: "timestamp with time zone",
+      notNull: true,
+      primaryKey: false,
+      default: { kind: "now", value: null },
+      source,
+    }),
+  ];
+}
+
+export function linkPolicies(source: SourceRef): PolicyFact[] {
+  return [
+    { name: "tenant_isolation", command: "ALL", restrictive: true, source, unknown: [] },
+    { name: "parent_access", command: "ALL", restrictive: false, source, unknown: [] },
+  ];
+}
+
+/**
+ * `facilis_files` as an FK target only. The link DDL references it, but a release-ref map
+ * does not carry `@facilis.dev/db`'s source, so this lookup-only draft lets the FK resolve; it is
+ * never emitted as one of the project's tables.
+ */
+export function facilisFilesDraft(source: SourceRef): TableDraft {
+  return {
+    binding: FACILIS_FILES_BINDING,
+    references: [],
+    fact: {
+      name: FACILIS_FILES,
+      binding: FACILIS_FILES_BINDING,
+      columns: [
+        column({
+          property: "id",
+          name: "id",
+          builder: "uuid",
+          type: "uuid",
+          notNull: true,
+          primaryKey: true,
+          default: { kind: "random", value: null },
+          source,
+        }),
+      ],
+      primaryKey: ["id"],
+      foreignKeys: [],
+      policies: [],
+      rlsEnabled: false,
+      scope: null,
+      source,
+      unknown: [],
+    },
+  };
+}