@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/schema-relations.ts

@@ -0,0 +1,239 @@
+import {
+  callArguments,
+  identifierName,
+  memberName,
+  nodeArray,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { Diagnostic, RelationFact, UnknownFact } from "../types.ts";
+import {
+  callbackExpression,
+  createDslResolver,
+  nodeRef,
+  schemaDiagnostics,
+  schemaUnknown,
+  topLevelDeclarators,
+  type DslResolver,
+} from "./schema-dsl.ts";
+import { resolveTableBinding, type TableLookup } from "./schema-foreign-keys.ts";
+
+export interface RelationScan {
+  readonly relations: readonly RelationFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+interface HelperBindings {
+  readonly one: ReadonlySet<string>;
+  readonly many: ReadonlySet<string>;
+}
+
+/** Map the callback's destructured `one`/`many` helpers to their local names. */
+function helperBindings(callback: AstNode | undefined): HelperBindings | null {
+  const fn = unwrapExpression(callback);
+  if (fn === undefined) return null;
+  if (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression") return null;
+  const param = unwrapExpression(nodeArray(fn, "params")[0]);
+  if (param?.type !== "ObjectPattern") return null;
+  const one = new Set<string>();
+  const many = new Set<string>();
+  for (const property of objectEntries(param)) {
+    if (property.type === "SpreadElement") continue;
+    const key = propertyName(property);
+    const local = identifierName(propertyValue(property));
+    if (local === undefined) continue;
+    if (key === "one") one.add(local);
+    if (key === "many") many.add(local);
+  }
+  return { one, many };
+}
+
+function readColumnList(
+  options: AstNode | undefined,
+  file: ProjectFile,
+  unknowns: UnknownFact[],
+): { fields: string[]; references: string[] } {
+  const empty = { fields: [] as string[], references: [] as string[] };
+  if (options === undefined) return empty;
+  const node = unwrapExpression(options);
+  if (node?.type !== "ObjectExpression") {
+    unknowns.push(
+      schemaUnknown("relation options are not an object literal", nodeRef(file, options)),
+    );
+    return empty;
+  }
+  const readList = (key: string): string[] => {
+    const property = objectEntries(node).find((entry) => propertyName(entry) === key);
+    if (property === undefined) return [];
+    const value = unwrapExpression(propertyValue(property));
+    if (value?.type !== "ArrayExpression") {
+      unknowns.push(
+        schemaUnknown("relation " + key + " is not an array literal", nodeRef(file, property)),
+      );
+      return [];
+    }
+    const columns: string[] = [];
+    for (const element of nodeArray(value, "elements")) {
+      const item = unwrapExpression(element);
+      const name = item?.type === "MemberExpression" ? memberName(item) : identifierName(item);
+      if (name === undefined) {
+        unknowns.push(
+          schemaUnknown(
+            "relation " + key + " entry is not a column reference",
+            nodeRef(file, item),
+          ),
+        );
+        continue;
+      }
+      columns.push(name);
+    }
+    return columns;
+  };
+  return { fields: readList("fields"), references: readList("references") };
+}
+
+function readRelationEntry(input: {
+  readonly entry: AstNode;
+  readonly from: string;
+  readonly graph: ModuleGraph;
+  readonly file: ProjectFile;
+  readonly lookup: TableLookup;
+  readonly helpers: HelperBindings;
+}): { relation: RelationFact | null; diagnostics: readonly Diagnostic[] } {
+  const { entry, from, graph, file, lookup, helpers } = input;
+  const unknowns: UnknownFact[] = [];
+  const value = unwrapExpression(propertyValue(entry));
+  const source = nodeRef(file, entry);
+  if (value?.type !== "CallExpression") {
+    return {
+      relation: null,
+      diagnostics: schemaDiagnostics([
+        schemaUnknown("relations() entry is not a one()/many() call", source),
+      ]),
+    };
+  }
+  const calleeLocal = identifierName(unwrapExpression(value.callee));
+  const cardinality =
+    calleeLocal !== undefined && helpers.one.has(calleeLocal)
+      ? "one"
+      : calleeLocal !== undefined && helpers.many.has(calleeLocal)
+        ? "many"
+        : null;
+  if (cardinality === null) {
+    return {
+      relation: null,
+      diagnostics: schemaDiagnostics([
+        schemaUnknown("relations() entry is not a one()/many() call", source),
+      ]),
+    };
+  }
+  const args = callArguments(value);
+  const targetLocal = identifierName(unwrapExpression(args[0]));
+  const targetTable =
+    targetLocal === undefined ? null : resolveTableBinding(graph, file.path, targetLocal, lookup);
+  if (targetTable === null) {
+    unknowns.push(schemaUnknown("relation target table is not resolvable statically", source));
+  }
+  const columns = readColumnList(args[1], file, unknowns);
+  const relation: RelationFact = {
+    from,
+    to: targetTable ?? targetLocal ?? "unknown",
+    cardinality,
+    fields: columns.fields,
+    references: columns.references,
+    source,
+    unknown: unknowns,
+  };
+  return { relation, diagnostics: schemaDiagnostics(unknowns) };
+}
+
+function readRelations(input: {
+  readonly graph: ModuleGraph;
+  readonly file: ProjectFile;
+  readonly call: AstNode;
+  readonly lookup: TableLookup;
+}): RelationScan {
+  const { graph, file, call, lookup } = input;
+  const source = nodeRef(file, call);
+  const args = callArguments(call);
+  const fromLocal = identifierName(unwrapExpression(args[0]));
+  const fromTable =
+    fromLocal === undefined ? null : resolveTableBinding(graph, file.path, fromLocal, lookup);
+  const from = fromTable ?? fromLocal ?? "unknown";
+  const callback = args[1];
+  const body = callbackExpression(callback);
+  const helpers = helperBindings(callback);
+  if (body?.type !== "ObjectExpression" || helpers === null) {
+    return {
+      relations: [],
+      diagnostics: schemaDiagnostics([
+        schemaUnknown("relations() callback is not a destructured one/many callback", source),
+      ]),
+    };
+  }
+  const relations: RelationFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  if (fromTable === null) {
+    const unknown = schemaUnknown("relation source table is not resolvable statically", source);
+    diagnostics.push(...schemaDiagnostics([unknown]));
+  }
+  for (const entry of objectEntries(body)) {
+    if (propertyName(entry) === undefined) {
+      diagnostics.push(
+        ...schemaDiagnostics([
+          schemaUnknown("computed relation key is outside the DSL", nodeRef(file, entry)),
+        ]),
+      );
+      continue;
+    }
+    const result = readRelationEntry({ entry, from, graph, file, lookup, helpers });
+    if (result.relation !== null) relations.push(result.relation);
+    diagnostics.push(...result.diagnostics);
+  }
+  return { relations, diagnostics };
+}
+
+export function buildRelationFacts(
+  graph: ModuleGraph,
+  files: readonly ProjectFile[],
+  lookup: TableLookup,
+): RelationScan {
+  const relations: RelationFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const file of files) {
+    const resolver: DslResolver = createDslResolver(graph, file);
+    for (const declarator of topLevelDeclarators(file.program)) {
+      const call = unwrapExpression(declarator.init);
+      if (call?.type !== "CallExpression") continue;
+      const symbol = resolver(call.callee);
+      if (symbol?.pkg !== "drizzle-orm" || symbol.name !== "relations") continue;
+      const scan = readRelations({ graph, file, call, lookup });
+      relations.push(...scan.relations);
+      diagnostics.push(...scan.diagnostics);
+    }
+  }
+  return { relations: dedupeRelations(relations), diagnostics };
+}
+
+/** Duplicate declarations (e.g. split files) must not duplicate edges. */
+function dedupeRelations(relations: readonly RelationFact[]): RelationFact[] {
+  const seen = new Set<string>();
+  const out: RelationFact[] = [];
+  for (const relation of relations) {
+    const key = [
+      relation.from,
+      relation.to,
+      relation.cardinality,
+      relation.fields.join(","),
+      relation.references.join(","),
+    ].join("|");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(relation);
+  }
+  return out;
+}

package/src/passes/schema-scope.ts

@@ -0,0 +1,29 @@
+import type { ColumnFact, ConfigFacts, ScopeFact } from "../types.ts";
+
+export interface ScopedColumn {
+  readonly column: ColumnFact;
+  readonly tenant: boolean;
+}
+
+function normalized(value: string): string {
+  return value.replaceAll("_", "").replaceAll("-", "").toLowerCase();
+}
+
+function matchesConfig(column: ColumnFact, names: readonly string[]): boolean {
+  const property = normalized(column.property);
+  const sqlName = normalized(column.name);
+  return names.some((candidate) => {
+    const value = normalized(candidate);
+    return value === property || value === sqlName;
+  });
+}
+
+/** Tenant scope wins over owner scope: both can be declared on the same table. */
+export function scopeOf(columns: readonly ScopedColumn[], config: ConfigFacts): ScopeFact | null {
+  const tenant =
+    columns.find((entry) => entry.tenant) ??
+    columns.find((entry) => matchesConfig(entry.column, config.tenantColumns));
+  if (tenant !== undefined) return { column: tenant.column.property, kind: "tenant" };
+  const owner = columns.find((entry) => matchesConfig(entry.column, config.ownerColumns));
+  return owner === undefined ? null : { column: owner.column.property, kind: "owner" };
+}

package/src/passes/schema-tables.ts

@@ -0,0 +1,216 @@
+import {
+  callArguments,
+  identifierName,
+  memberName,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { diagnostic } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { staticString } from "../static-eval.ts";
+import type { ConfigFacts, Diagnostic, TableFact, UnknownFact } from "../types.ts";
+import { buildColumnFact, type ColumnReference } from "./schema-columns.ts";
+import { scopeOf, type ScopedColumn } from "./schema-scope.ts";
+import {
+  createDslResolver,
+  nodeRef,
+  schemaDiagnostics,
+  schemaUnknown,
+  topLevelDeclarators,
+  type DslResolver,
+} from "./schema-dsl.ts";
+import { buildPolicyFacts } from "./schema-policies.ts";
+
+export interface TableDraft {
+  readonly fact: TableFact;
+  readonly binding: string | null;
+  readonly references: readonly ColumnReference[];
+}
+
+export interface TableScan {
+  readonly drafts: readonly TableDraft[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+interface TableCall {
+  readonly call: AstNode;
+  readonly methods: readonly string[];
+}
+
+/** Local `pgEnum("name", values)` consts; a column built from one is a known enum builder. */
+function collectEnumBindings(
+  file: ProjectFile,
+  resolver: DslResolver,
+  graph: ModuleGraph,
+): Map<string, string> {
+  const enums = new Map<string, string>();
+  for (const declarator of topLevelDeclarators(file.program)) {
+    const binding = identifierName(declarator.id);
+    const init = unwrapExpression(declarator.init);
+    if (binding === undefined || init?.type !== "CallExpression") continue;
+    const symbol = resolver(init.callee);
+    if (symbol?.pkg !== "pg-core" || symbol.name !== "pgEnum") continue;
+    const name = staticString(callArguments(init)[0], { graph, file: file.path });
+    enums.set(binding, name.ok ? name.value : binding);
+  }
+  return enums;
+}
+
+/** The `pgTable` call inside `pgTable(...).enableRLS()`, plus the chain methods after it. */
+function findTableCall(init: unknown, resolver: DslResolver): TableCall | null {
+  let current = unwrapExpression(init);
+  const methods: string[] = [];
+  let guard = 0;
+  while (current?.type === "CallExpression" && guard < 32) {
+    guard += 1;
+    const callee = unwrapExpression(current.callee);
+    if (callee === undefined) return null;
+    if (callee.type === "MemberExpression") {
+      const name = memberName(callee);
+      if (name === undefined) return null;
+      methods.unshift(name);
+      current = unwrapExpression(callee.object);
+      continue;
+    }
+    const symbol = resolver(callee);
+    if (symbol?.pkg !== "pg-core" || symbol.name !== "pgTable") return null;
+    return { call: current, methods };
+  }
+  return null;
+}
+
+function buildTableDraft(input: {
+  readonly graph: ModuleGraph;
+  readonly file: ProjectFile;
+  readonly resolver: DslResolver;
+  readonly enums: ReadonlyMap<string, string>;
+  readonly config: ConfigFacts;
+  readonly binding: string | null;
+  readonly tableCall: TableCall;
+}): { draft: TableDraft; diagnostics: readonly Diagnostic[] } {
+  const { graph, file, resolver, enums, config, binding, tableCall } = input;
+  const source = nodeRef(file, tableCall.call);
+  const args = callArguments(tableCall.call);
+  const unknowns: UnknownFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  const nameResult = staticString(args[0], { graph, file: file.path });
+  let name: string;
+  if (nameResult.ok && nameResult.value.length > 0) {
+    name = nameResult.value;
+  } else {
+    name = binding ?? "unknown";
+    unknowns.push(schemaUnknown('table name of "' + name + '" is not a static string', source));
+  }
+
+  const columns: ScopedColumn[] = [];
+  const references: ColumnReference[] = [];
+  const columnsArgument = unwrapExpression(args[1]);
+  if (columnsArgument?.type !== "ObjectExpression") {
+    unknowns.push(
+      schemaUnknown('columns of table "' + name + '" are not an object literal', source),
+    );
+  } else {
+    for (const entry of objectEntries(columnsArgument)) {
+      if (entry.type === "SpreadElement") {
+        unknowns.push(
+          schemaUnknown(
+            'spread columns in table "' + name + '" are outside the DSL',
+            nodeRef(file, entry),
+          ),
+        );
+        continue;
+      }
+      const property = propertyName(entry);
+      if (property === undefined) {
+        unknowns.push(
+          schemaUnknown(
+            'computed column key in table "' + name + '" is outside the DSL',
+            nodeRef(file, entry),
+          ),
+        );
+        continue;
+      }
+      const result = buildColumnFact({
+        property,
+        expression: propertyValue(entry),
+        propertyNode: entry,
+        file,
+        graph,
+        resolver,
+        enums,
+      });
+      diagnostics.push(...result.diagnostics);
+      if (result.reference !== null) {
+        references.push({ column: property, target: result.reference });
+      }
+      columns.push({ column: result.column, tenant: result.tenant });
+    }
+  }
+
+  const policyScan = buildPolicyFacts({
+    extras: args[2],
+    file,
+    graph,
+    resolver,
+  });
+  diagnostics.push(...policyScan.diagnostics);
+  const rlsEnabled = tableCall.methods.includes("enableRLS");
+  const scope = scopeOf(columns, config);
+  const fact: TableFact = {
+    name,
+    binding,
+    columns: columns.map((entry) => entry.column),
+    primaryKey: columns
+      .filter((entry) => entry.column.primaryKey)
+      .map((entry) => entry.column.property),
+    foreignKeys: [],
+    policies: policyScan.policies,
+    rlsEnabled,
+    scope,
+    source,
+    unknown: unknowns,
+  };
+  diagnostics.push(...schemaDiagnostics(unknowns));
+  if (scope !== null && (!rlsEnabled || policyScan.policies.length === 0)) {
+    diagnostics.push(
+      diagnostic(
+        "rls-on-scoped-table",
+        "error",
+        'scoped table "' + name + '" must call .enableRLS() and declare a policy',
+        source,
+      ),
+    );
+  }
+  return { draft: { fact, binding, references }, diagnostics };
+}
+
+export function collectTableDrafts(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  config: ConfigFacts,
+): TableScan {
+  const resolver = createDslResolver(graph, file);
+  const enums = collectEnumBindings(file, resolver, graph);
+  const drafts: TableDraft[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const declarator of topLevelDeclarators(file.program)) {
+    const binding = identifierName(declarator.id) ?? null;
+    const tableCall = findTableCall(declarator.init, resolver);
+    if (tableCall === null) continue;
+    const result = buildTableDraft({
+      graph,
+      file,
+      resolver,
+      enums,
+      config,
+      binding,
+      tableCall,
+    });
+    drafts.push(result.draft);
+    diagnostics.push(...result.diagnostics);
+  }
+  return { drafts, diagnostics };
+}

package/src/passes/schema.ts

@@ -0,0 +1,67 @@
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { ConfigFacts, Diagnostic, RelationFact, TableFact } from "../types.ts";
+import { isSchemaFile } from "./schema-dsl.ts";
+import { collectFileLinkDrafts } from "./schema-file-links.ts";
+import { buildTableLookup, finalizeTables, withFrameworkTables } from "./schema-foreign-keys.ts";
+import { collectTableDrafts, type TableDraft } from "./schema-tables.ts";
+import { collectReExportedDrafts } from "./schema-re-exports.ts";
+import { buildRelationFacts } from "./schema-relations.ts";
+
+export interface SchemaResult {
+  readonly tables: readonly TableFact[];
+  readonly relations: readonly RelationFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function schemaFiles(graph: ModuleGraph): ProjectFile[] {
+  return [...graph.files.values()]
+    .filter((file) => isSchemaFile(graph, file.path))
+    .toSorted((left, right) => left.path.localeCompare(right.path));
+}
+
+/** Tables declared twice (invalid TS, but analyzable) keep the first declaration. */
+function dedupeDrafts(drafts: readonly TableDraft[]): TableDraft[] {
+  const seen = new Set<string>();
+  const out: TableDraft[] = [];
+  for (const draft of drafts) {
+    if (seen.has(draft.fact.name)) continue;
+    seen.add(draft.fact.name);
+    out.push(draft);
+  }
+  return out;
+}
+
+/** Interpret the Drizzle DSL under `db/**`, including framework tables reached by re-export. */
+export function buildSchemaFacts(graph: ModuleGraph, config: ConfigFacts): SchemaResult {
+  const files = schemaFiles(graph);
+  const collected: TableDraft[] = [];
+  const externalTables: TableDraft[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const file of files) {
+    const scan = collectTableDrafts(graph, file, config);
+    collected.push(...scan.drafts);
+    diagnostics.push(...scan.diagnostics);
+    // Generated link tables follow the file's own declarations, which is their source order:
+    // `const todoFiles = fileLinks(todos, ...)` comes after the `todos` it references.
+    const links = collectFileLinkDrafts(graph, file, scan.drafts);
+    collected.push(...links.drafts);
+    externalTables.push(...links.externalTables);
+    diagnostics.push(...links.diagnostics);
+  }
+
+  const seenNames = new Set(collected.map((draft) => draft.fact.name));
+  const visitedFiles = new Set(files.map((file) => file.path));
+  for (const file of files) {
+    const scan = collectReExportedDrafts(graph, file, config, seenNames, visitedFiles);
+    collected.push(...scan.drafts);
+    diagnostics.push(...scan.diagnostics);
+  }
+
+  const drafts = dedupeDrafts(collected);
+  const lookup = withFrameworkTables(buildTableLookup(drafts), externalTables);
+  const finalized = finalizeTables(graph, drafts, lookup);
+  diagnostics.push(...finalized.diagnostics);
+  const relations = buildRelationFacts(graph, files, lookup);
+  diagnostics.push(...relations.diagnostics);
+  return { tables: finalized.tables, relations: relations.relations, diagnostics };
+}