@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/passes/schema-policies.ts

@@ -0,0 +1,270 @@
+import {
+  callArguments,
+  identifierName,
+  memberName,
+  nodeArray,
+  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 { Diagnostic, PolicyCommand, PolicyFact, SourceRef, UnknownFact } from "../types.ts";
+import { optionsOf } from "./schema-column-types.ts";
+import {
+  callbackExpression,
+  nodeRef,
+  schemaDiagnostics,
+  schemaUnknown,
+  type DslResolver,
+  type DslSymbol,
+} from "./schema-dsl.ts";
+
+export interface PolicyInput {
+  readonly extras: AstNode | undefined;
+  readonly file: ProjectFile;
+  readonly graph: ModuleGraph;
+  readonly resolver: DslResolver;
+}
+
+export interface PolicyScan {
+  readonly policies: readonly PolicyFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+const COMMANDS: Readonly<Record<string, PolicyCommand>> = {
+  select: "SELECT",
+  insert: "INSERT",
+  update: "UPDATE",
+  delete: "DELETE",
+  all: "ALL",
+};
+
+function scan(policies: readonly PolicyFact[]): PolicyScan {
+  return {
+    policies,
+    diagnostics: schemaDiagnostics(policies.flatMap((policy) => policy.unknown)),
+  };
+}
+
+function fixedPolicy(
+  name: string,
+  command: PolicyCommand,
+  restrictive: boolean,
+  source: SourceRef,
+  unknown: readonly UnknownFact[] = [],
+): PolicyFact {
+  return { name, command, restrictive, source, unknown };
+}
+
+function unknownPolicyScan(name: string, reason: string, source: SourceRef): PolicyScan {
+  const unknown = schemaUnknown(reason, source);
+  return {
+    policies: [{ name, command: "ALL", restrictive: false, source, unknown: [unknown] }],
+    diagnostics: schemaDiagnostics([unknown]),
+  };
+}
+
+function calleeLabel(callee: unknown): string {
+  const node = unwrapExpression(callee);
+  if (node === undefined) return "policy";
+  return identifierName(node) ?? memberName(node) ?? "policy";
+}
+
+function readPgPolicy(call: AstNode, context: StaticContext, file: ProjectFile): PolicyScan {
+  const source = nodeRef(file, call);
+  const args = callArguments(call);
+  const unknowns: UnknownFact[] = [];
+  let name = "unknown";
+  const nameResult = staticString(args[0], context);
+  if (nameResult.ok) {
+    name = nameResult.value;
+  } else {
+    unknowns.push(schemaUnknown("pgPolicy name is not a static string", source));
+  }
+  let command: PolicyCommand = "ALL";
+  let restrictive = false;
+  if (args[1] !== undefined) {
+    const options = optionsOf(args[1], context);
+    if (options === null) {
+      unknowns.push(schemaUnknown("pgPolicy options are not static", source));
+    } else {
+      const rawFor = options["for"];
+      if (rawFor !== undefined) {
+        const parsed = typeof rawFor === "string" ? (COMMANDS[rawFor.toLowerCase()] ?? null) : null;
+        if (parsed === null) {
+          unknowns.push(schemaUnknown('pgPolicy "for" is not a policy command', source));
+        } else {
+          command = parsed;
+        }
+      }
+      const rawAs = options["as"];
+      if (rawAs === "restrictive") {
+        restrictive = true;
+      } else if (rawAs !== undefined && rawAs !== "permissive") {
+        unknowns.push(schemaUnknown('pgPolicy "as" is not restrictive or permissive', source));
+      }
+    }
+  }
+  return scan([fixedPolicy(name, command, restrictive, source, unknowns)]);
+}
+
+/** `rlsForTable({...})` expands to the same policy set `@facilis.dev/db` builds at runtime. */
+function expandRlsTable(call: AstNode, context: StaticContext, file: ProjectFile): PolicyScan {
+  const source = nodeRef(file, call);
+  const args = callArguments(call);
+  let options: Record<string, unknown> = {};
+  if (args[0] !== undefined) {
+    const evaluated = optionsOf(args[0], context);
+    if (evaluated === null) {
+      const unknown = schemaUnknown("rlsForTable options are not static", source);
+      return {
+        policies: [fixedPolicy("tenant_isolation", "ALL", true, source, [unknown])],
+        diagnostics: schemaDiagnostics([unknown]),
+      };
+    }
+    options = evaluated;
+  }
+  const policies: PolicyFact[] = [fixedPolicy("tenant_isolation", "ALL", true, source)];
+  const ownerColumn = options["ownerColumn"];
+  if (Object.hasOwn(options, "ownerColumn")) {
+    const unknown =
+      typeof ownerColumn === "string"
+        ? []
+        : [schemaUnknown("rlsForTable ownerColumn is not a string", source)];
+    policies.push(fixedPolicy("owner_isolation", "ALL", false, source, unknown));
+  }
+  const rolesColumn = options["rolesColumn"];
+  if (Object.hasOwn(options, "rolesColumn")) {
+    const unknown =
+      typeof rolesColumn === "string"
+        ? []
+        : [schemaUnknown("rlsForTable rolesColumn is not a string", source)];
+    policies.push(fixedPolicy("role_access", "ALL", false, source, unknown));
+  }
+  return scan(policies);
+}
+
+function readRlsExpansion(
+  node: AstNode | undefined,
+  context: StaticContext,
+  file: ProjectFile,
+  resolver: DslResolver,
+): PolicyScan | null {
+  if (node === undefined) return null;
+  let call: AstNode | undefined;
+  if (node.type === "CallExpression") {
+    call = node;
+  } else if (node.type === "MemberExpression" && memberName(node) === "policies") {
+    const object = unwrapExpression(node.object);
+    if (object?.type === "CallExpression") call = object;
+  }
+  if (call === undefined) return null;
+  const symbol: DslSymbol | null = resolver(call.callee);
+  if (
+    symbol?.pkg !== "facilis-db" ||
+    (symbol.name !== "rlsForTable" && symbol.name !== "withRls")
+  ) {
+    return null;
+  }
+  return expandRlsTable(call, context, file);
+}
+
+function readPolicyEntry(
+  element: AstNode,
+  context: StaticContext,
+  file: ProjectFile,
+  resolver: DslResolver,
+): PolicyScan {
+  const node = unwrapExpression(element);
+  const source = nodeRef(file, node ?? element);
+  const expansion = readRlsExpansion(node, context, file, resolver);
+  if (expansion !== null) return expansion;
+  if (node?.type !== "CallExpression") {
+    return unknownPolicyScan("policy", "table extras entry is not a policy call", source);
+  }
+  const symbol = resolver(node.callee);
+  if (symbol?.pkg === "facilis-db") {
+    if (symbol.name === "tenantIsolationPolicy") {
+      return scan([fixedPolicy("tenant_isolation", "ALL", true, source)]);
+    }
+    if (symbol.name === "ownerIsolationPolicy") {
+      return scan([fixedPolicy("owner_isolation", "ALL", false, source)]);
+    }
+    if (symbol.name === "rolePolicy") {
+      const args = callArguments(node);
+      const unknowns: UnknownFact[] = [];
+      let name = "role_access";
+      if (args[1] !== undefined) {
+        const evaluated = staticString(args[1], context);
+        if (evaluated.ok) {
+          name = evaluated.value;
+        } else {
+          unknowns.push(schemaUnknown("rolePolicy name is not a static string", source));
+        }
+      }
+      return scan([fixedPolicy(name, "ALL", false, source, unknowns)]);
+    }
+  }
+  if (symbol?.pkg === "pg-core" && symbol.name === "pgPolicy") {
+    return readPgPolicy(node, context, file);
+  }
+  return unknownPolicyScan(
+    calleeLabel(node.callee),
+    'policy helper "' + calleeLabel(node.callee) + '" is outside the documented DSL',
+    source,
+  );
+}
+
+function readPolicies(
+  expression: AstNode,
+  context: StaticContext,
+  file: ProjectFile,
+  resolver: DslResolver,
+): PolicyScan {
+  const node = unwrapExpression(expression);
+  if (node === undefined) {
+    return unknownPolicyScan(
+      "policy",
+      "table extras are not a policy expression",
+      nodeRef(file, expression),
+    );
+  }
+  if (node.type === "ArrayExpression") {
+    const policies: PolicyFact[] = [];
+    const diagnostics: Diagnostic[] = [];
+    for (const element of nodeArray(node, "elements")) {
+      const spreadArgument =
+        element.type === "SpreadElement" ? unwrapExpression(element.argument) : undefined;
+      const nested =
+        element.type === "SpreadElement"
+          ? spreadArgument === undefined
+            ? unknownPolicyScan(
+                "policy",
+                "spread policy entry is not an expression",
+                nodeRef(file, element),
+              )
+            : readPolicies(spreadArgument, context, file, resolver)
+          : readPolicyEntry(element, context, file, resolver);
+      policies.push(...nested.policies);
+      diagnostics.push(...nested.diagnostics);
+    }
+    return { policies, diagnostics };
+  }
+  const expansion = readRlsExpansion(node, context, file, resolver);
+  if (expansion !== null) return expansion;
+  return readPolicyEntry(node, context, file, resolver);
+}
+
+export function buildPolicyFacts(input: PolicyInput): PolicyScan {
+  if (input.extras === undefined) return { policies: [], diagnostics: [] };
+  const expression = callbackExpression(input.extras);
+  if (expression === undefined) {
+    return unknownPolicyScan(
+      "policy",
+      "table extras are not a readable callback",
+      nodeRef(input.file, input.extras),
+    );
+  }
+  const context: StaticContext = { graph: input.graph, file: input.file.path };
+  return readPolicies(expression, context, input.file, input.resolver);
+}

package/src/passes/schema-re-exports.ts

@@ -0,0 +1,95 @@
+import { diagnostic } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { identifierName, literalString, nodeArray } from "../ast/node.ts";
+import type { Diagnostic, ConfigFacts } from "../types.ts";
+import { nodeRef } from "./schema-dsl.ts";
+import { collectTableDrafts, type TableDraft, type TableScan } from "./schema-tables.ts";
+
+/** Merge the tables of `export { users } from "@facilis.dev/auth"` (framework source, recursively). */
+export function collectReExportedDrafts(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  config: ConfigFacts,
+  seenNames: Set<string>,
+  visitedFiles: Set<string>,
+): TableScan {
+  const drafts: TableDraft[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const statement of nodeArray(file.program, "body")) {
+    const hasSource =
+      statement.type === "ExportNamedDeclaration" || statement.type === "ExportAllDeclaration";
+    const specifier = hasSource ? literalString(statement.source) : undefined;
+    if (specifier === undefined) continue;
+    const targetPath = graph.resolve(file.path, specifier);
+    const target = targetPath === null ? undefined : graph.file(targetPath);
+    if (target === undefined) {
+      diagnostics.push(
+        diagnostic(
+          "unknown",
+          "info",
+          'cannot resolve re-exported module "' + specifier + '"',
+          nodeRef(file, statement),
+        ),
+      );
+      continue;
+    }
+    if (visitedFiles.has(target.path)) continue;
+    visitedFiles.add(target.path);
+    const local = collectTableDrafts(graph, target, config);
+    diagnostics.push(...local.diagnostics);
+    for (const draft of local.drafts) {
+      if (seenNames.has(draft.fact.name)) continue;
+      seenNames.add(draft.fact.name);
+      drafts.push(draft);
+    }
+    const nested = collectReExportedDrafts(graph, target, config, seenNames, visitedFiles);
+    drafts.push(...nested.drafts);
+    diagnostics.push(...nested.diagnostics);
+  }
+
+  // The example project imports framework tables and re-exports the local bindings:
+  //   import { users } from "@facilis.dev/auth"; export { users };
+  // Follow the import, keep only the tables whose binding was re-exported.
+  for (const statement of nodeArray(file.program, "body")) {
+    if (
+      statement.type !== "ExportNamedDeclaration" ||
+      literalString(statement.source) !== undefined
+    )
+      continue;
+    for (const item of nodeArray(statement, "specifiers")) {
+      if (item.type !== "ExportSpecifier") continue;
+      const local = identifierName(item.local);
+      if (local === undefined) continue;
+      const imported = file.module.imports.find((entry) => entry.local === local);
+      if (imported === undefined) continue;
+      const targetPath = graph.resolve(file.path, imported.specifier);
+      const target = targetPath === null ? undefined : graph.file(targetPath);
+      if (target === undefined) {
+        diagnostics.push(
+          diagnostic(
+            "unknown",
+            "info",
+            'cannot resolve re-exported module "' + imported.specifier + '"',
+            nodeRef(file, item),
+          ),
+        );
+        continue;
+      }
+      if (visitedFiles.has(target.path)) continue;
+      visitedFiles.add(target.path);
+      const localScan = collectTableDrafts(graph, target, config);
+      diagnostics.push(...localScan.diagnostics);
+      for (const draft of localScan.drafts) {
+        const importedName = imported.imported ?? local;
+        if (draft.binding !== importedName && draft.fact.name !== importedName) continue;
+        if (seenNames.has(draft.fact.name)) continue;
+        seenNames.add(draft.fact.name);
+        drafts.push(draft);
+      }
+      const nested = collectReExportedDrafts(graph, target, config, seenNames, visitedFiles);
+      drafts.push(...nested.drafts);
+      diagnostics.push(...nested.diagnostics);
+    }
+  }
+  return { drafts, diagnostics };
+}

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