@facilis.dev/analyze 0.0.0-stage → 0.1.1

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: [],
+    },
+  };
+}

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

@@ -0,0 +1,213 @@
+/**
+ * `fileLinks(parent, { table, column })` -> the synthetic link table it generates (D-053).
+ *
+ * The call is framework DSL rather than a `pgTable(...)` literal, so the table pass cannot
+ * see the link table it returns. The options come from the static subset and the parent
+ * table from the declaring file's own drafts; a value the interpreter cannot read becomes an
+ * explicit unknown instead of aborting the pass.
+ */
+
+import { callArguments, identifierName, unwrapExpression, type AstNode } from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { StaticContext } from "../static-eval.ts";
+import type { Diagnostic, SourceRef, TableFact, UnknownFact } from "../types.ts";
+import { optionsOf } from "./schema-column-types.ts";
+import type { ColumnReference } from "./schema-columns.ts";
+import {
+  createDslResolver,
+  nodeRef,
+  schemaDiagnostics,
+  schemaUnknown,
+  topLevelDeclarators,
+} from "./schema-dsl.ts";
+import {
+  FACILIS_FILES_BINDING,
+  facilisFilesDraft,
+  linkColumns,
+  linkPolicies,
+} from "./schema-file-links-ddl.ts";
+import type { TableDraft } from "./schema-tables.ts";
+
+const DB_PACKAGE = "facilis-db";
+const FILE_LINKS = "fileLinks";
+const DEFAULT_PARENT_COLUMN = "parent_id";
+
+export interface FileLinkScan {
+  readonly drafts: readonly TableDraft[];
+  readonly diagnostics: readonly Diagnostic[];
+  /** Lookup-only targets of the generated FKs; see `facilisFilesDraft`. */
+  readonly externalTables: readonly TableDraft[];
+}
+
+interface LinkOptions {
+  /** null when the name is not a static non-empty string. */
+  readonly table: string | null;
+  readonly parentColumn: string;
+  readonly unknowns: readonly UnknownFact[];
+}
+
+function readOptions(
+  call: AstNode,
+  binding: string | null,
+  context: StaticContext,
+  source: SourceRef,
+): LinkOptions {
+  const label = binding ?? "unknown";
+  const options = optionsOf(callArguments(call)[1], context);
+  const unknowns: UnknownFact[] = [];
+  if (options === null) {
+    unknowns.push(
+      schemaUnknown('fileLinks options of "' + label + '" are not a static object', source),
+    );
+    return { table: null, parentColumn: DEFAULT_PARENT_COLUMN, unknowns };
+  }
+  const rawTable = options["table"];
+  let table: string | null = null;
+  if (typeof rawTable === "string" && rawTable.length > 0) {
+    table = rawTable;
+  } else {
+    unknowns.push(
+      schemaUnknown('fileLinks table name of "' + label + '" is not a static string', source),
+    );
+  }
+  const rawColumn = options["column"];
+  let parentColumn = DEFAULT_PARENT_COLUMN;
+  if (rawColumn !== undefined) {
+    if (typeof rawColumn === "string" && rawColumn.length > 0) {
+      parentColumn = rawColumn;
+    } else {
+      unknowns.push(
+        schemaUnknown('fileLinks column name of "' + label + '" is not a static string', source),
+      );
+    }
+  }
+  return { table, parentColumn, unknowns };
+}
+
+interface ParentTarget {
+  readonly binding: string;
+  readonly property: string;
+}
+
+function readParent(
+  call: AstNode,
+  drafts: readonly TableDraft[],
+  binding: string | null,
+  source: SourceRef,
+): { target: ParentTarget | null; unknowns: readonly UnknownFact[] } {
+  const label = binding ?? "unknown";
+  const parentNode = unwrapExpression(callArguments(call)[0]);
+  const parentBinding = parentNode?.type === "Identifier" ? identifierName(parentNode) : undefined;
+  if (parentBinding === undefined) {
+    return {
+      target: null,
+      unknowns: [schemaUnknown('fileLinks parent of "' + label + '" is not an identifier', source)],
+    };
+  }
+  const draft = drafts.find((entry) => entry.binding === parentBinding);
+  if (draft === undefined) {
+    return {
+      target: null,
+      unknowns: [
+        schemaUnknown(
+          'fileLinks parent "' + parentBinding + '" is not a table declared in this file',
+          source,
+        ),
+      ],
+    };
+  }
+  const key = draft.fact.primaryKey[0];
+  if (draft.fact.primaryKey.length !== 1 || key === undefined) {
+    return {
+      target: null,
+      unknowns: [
+        schemaUnknown(
+          'fileLinks parent "' + parentBinding + '" needs a single-column primary key',
+          source,
+        ),
+      ],
+    };
+  }
+  return { target: { binding: parentBinding, property: key }, unknowns: [] };
+}
+
+function buildLinkDraft(input: {
+  readonly call: AstNode;
+  readonly binding: string | null;
+  readonly drafts: readonly TableDraft[];
+  readonly context: StaticContext;
+  readonly source: SourceRef;
+}): { draft: TableDraft; external: TableDraft; unknowns: readonly UnknownFact[] } {
+  const { call, binding, drafts, context, source } = input;
+  const options = readOptions(call, binding, context, source);
+  const parent = readParent(call, drafts, binding, source);
+  const references: ColumnReference[] = [];
+  if (parent.target !== null) {
+    references.push({
+      column: "parentId",
+      target: {
+        binding: parent.target.binding,
+        property: parent.target.property,
+        onDelete: "cascade",
+        onUpdate: null,
+        source,
+      },
+    });
+  }
+  // The generated fileId column references facilis_files regardless of how the parent reads.
+  references.push({
+    column: "fileId",
+    target: {
+      binding: FACILIS_FILES_BINDING,
+      property: "id",
+      onDelete: "cascade",
+      onUpdate: null,
+      source,
+    },
+  });
+  const unknowns: UnknownFact[] = [...options.unknowns, ...parent.unknowns];
+  const fact: TableFact = {
+    name: options.table ?? binding ?? "unknown",
+    binding,
+    columns: linkColumns(options.parentColumn, source),
+    primaryKey: ["id"],
+    foreignKeys: [],
+    policies: linkPolicies(source),
+    rlsEnabled: true,
+    scope: { column: "tenantId", kind: "tenant" },
+    source,
+    unknown: unknowns,
+  };
+  return { draft: { fact, binding, references }, external: facilisFilesDraft(source), unknowns };
+}
+
+/** Read the top-level `fileLinks(...)` declarators of one schema file into table drafts. */
+export function collectFileLinkDrafts(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  drafts: readonly TableDraft[],
+): FileLinkScan {
+  const resolver = createDslResolver(graph, file);
+  const context: StaticContext = { graph, file: file.path };
+  const links: TableDraft[] = [];
+  const externalTables: TableDraft[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const declarator of topLevelDeclarators(file.program)) {
+    const binding = identifierName(declarator.id) ?? null;
+    const init = unwrapExpression(declarator.init);
+    if (init?.type !== "CallExpression") continue;
+    const symbol = resolver(init.callee);
+    if (symbol?.pkg !== DB_PACKAGE || symbol.name !== FILE_LINKS) continue;
+    const result = buildLinkDraft({
+      call: init,
+      binding,
+      drafts,
+      context,
+      source: nodeRef(file, init),
+    });
+    links.push(result.draft);
+    externalTables.push(result.external);
+    diagnostics.push(...schemaDiagnostics(result.unknowns));
+  }
+  return { drafts: links, externalTables, diagnostics };
+}

package/src/passes/schema-foreign-keys.ts

@@ -0,0 +1,121 @@
+import { diagnostic } from "../diagnostics.ts";
+import type { ModuleGraph } from "../module-graph.ts";
+import type { Diagnostic, ForeignKeyFact, TableFact } from "../types.ts";
+import type { TableDraft } from "./schema-tables.ts";
+
+export interface TableLookup {
+  /** `file#binding` -> table name; the key keeps same-named bindings in different modules apart. */
+  readonly byBinding: ReadonlyMap<string, string>;
+  readonly byName: ReadonlyMap<string, TableDraft>;
+}
+
+export function buildTableLookup(drafts: readonly TableDraft[]): TableLookup {
+  const byBinding = new Map<string, string>();
+  const byName = new Map<string, TableDraft>();
+  for (const draft of drafts) {
+    if (draft.binding !== null) {
+      byBinding.set(draft.fact.source.file + "#" + draft.binding, draft.fact.name);
+    }
+    byName.set(draft.fact.name, draft);
+  }
+  return { byBinding, byName };
+}
+
+/**
+ * Add lookups for tables a DSL call expands to but the analysis does not emit: a generated
+ * `fileLinks` FK points at the framework's `facilis_files`, whose source is absent from a
+ * release-ref map. The extra tables resolve FK targets only; they never reach `tables`.
+ */
+export function withFrameworkTables(
+  lookup: TableLookup,
+  tables: readonly TableDraft[],
+): TableLookup {
+  if (tables.length === 0) return lookup;
+  const byBinding = new Map(lookup.byBinding);
+  const byName = new Map(lookup.byName);
+  for (const table of tables) {
+    if (!byName.has(table.fact.name)) byName.set(table.fact.name, table);
+    if (table.binding === null) continue;
+    const key = table.fact.source.file + "#" + table.binding;
+    if (!byBinding.has(key)) byBinding.set(key, table.fact.name);
+  }
+  return { byBinding, byName };
+}
+
+/** Resolve a table identifier used in the DSL (local const or any project/framework import). */
+export function resolveTableBinding(
+  graph: ModuleGraph,
+  filePath: string,
+  local: string,
+  lookup: TableLookup,
+): string | null {
+  const binding = graph.resolveBinding(filePath, local);
+  if (binding !== null) {
+    const table = lookup.byBinding.get(binding.file + "#" + binding.name);
+    if (table !== undefined) return table;
+  }
+  return lookup.byBinding.get(filePath + "#" + local) ?? null;
+}
+
+export function finalizeTables(
+  graph: ModuleGraph,
+  drafts: readonly TableDraft[],
+  lookup: TableLookup,
+): { tables: TableFact[]; diagnostics: Diagnostic[] } {
+  const tables: TableFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const draft of drafts) {
+    const foreignKeys: ForeignKeyFact[] = [];
+    for (const reference of draft.references) {
+      const table = draft.fact.name;
+      const targetTable = resolveTableBinding(
+        graph,
+        draft.fact.source.file,
+        reference.target.binding,
+        lookup,
+      );
+      if (targetTable === null) {
+        diagnostics.push(
+          diagnostic(
+            "fk-target-known",
+            "warning",
+            'table "' + table + '" references unknown table "' + reference.target.binding + '"',
+            reference.target.source,
+          ),
+        );
+        continue;
+      }
+      const targetDraft = lookup.byName.get(targetTable);
+      const knownColumn = targetDraft?.fact.columns.some(
+        (column) => column.property === reference.target.property,
+      );
+      if (knownColumn !== true) {
+        diagnostics.push(
+          diagnostic(
+            "fk-target-known",
+            "warning",
+            'table "' +
+              table +
+              '" references unknown column "' +
+              targetTable +
+              "." +
+              reference.target.property +
+              '"',
+            reference.target.source,
+          ),
+        );
+        continue;
+      }
+      foreignKeys.push({
+        columns: [reference.column],
+        targetTable,
+        targetColumns: [reference.target.property],
+        onDelete: reference.target.onDelete,
+        onUpdate: reference.target.onUpdate,
+        source: reference.target.source,
+      });
+    }
+    tables.push({ ...draft.fact, foreignKeys });
+  }
+  return { tables, diagnostics };
+}