@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/schema-column-types.js

@@ -0,0 +1,55 @@
+import { isRecord } from "../json.js";
+import { evaluateStatic } from "../static-eval.js";
+/** Static object argument of a builder/method, e.g. `{ withTimezone: true }`. */
+export function optionsOf(node, context) {
+    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, args, context) {
+    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, context) {
+    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/dist/passes/schema-columns.d.ts

@@ -0,0 +1,35 @@
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ColumnFact, Diagnostic, SourceRef } from "../types.js";
+import { type DslResolver } from "./schema-dsl.js";
+/** 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>;
+}
+export declare function buildColumnFact(input: ColumnInput): ColumnResult;

package/dist/passes/schema-columns.js

@@ -0,0 +1,197 @@
+import { callArguments, identifierName, literalString, memberName, unwrapExpression, } from "../ast/node.js";
+import { staticString } from "../static-eval.js";
+import { callbackExpression, nodeRef, schemaDiagnostics, schemaUnknown, } from "./schema-dsl.js";
+import { displayType, optionsOf, readDefault } from "./schema-column-types.js";
+const PG_BUILDERS = new Set([
+    "uuid",
+    "text",
+    "boolean",
+    "timestamp",
+    "varchar",
+    "integer",
+    "bigint",
+    "numeric",
+    "date",
+    "jsonb",
+    "json",
+    "serial",
+    "bigserial",
+    "real",
+    "doublePrecision",
+]);
+function isKnownBuilder(symbol) {
+    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, resolver, enums) {
+    let current = unwrapExpression(expression);
+    const methods = [];
+    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, key, source, unknowns) {
+    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, context, file) {
+    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 = [];
+    let onDelete = null;
+    let onUpdate = 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) {
+    const context = { 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 = [];
+    let builder = "unknown";
+    let type = "unknown";
+    let name = input.property;
+    let tenant = false;
+    let reference = 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 = 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 = {
+        property: input.property,
+        name,
+        builder,
+        type,
+        notNull,
+        primaryKey,
+        unique,
+        default: columnDefault,
+        source,
+        unknown: unknowns,
+    };
+    return { column, reference, tenant, diagnostics: schemaDiagnostics(unknowns) };
+}

package/dist/passes/schema-dsl.d.ts

@@ -0,0 +1,24 @@
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic, SourceRef, UnknownFact } from "../types.js";
+/** 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;
+export declare function createDslResolver(graph: ModuleGraph, file: ProjectFile): DslResolver;
+/** Variable declarators at module top level, including `export const ...`. */
+export declare function topLevelDeclarators(program: AstNode): AstNode[];
+/** The expression a callback returns; supports `() => x` and `() => { return x; }`. */
+export declare function callbackExpression(callback: AstNode | undefined): AstNode | undefined;
+export declare function nodeRef(file: ProjectFile, node: AstNode | undefined): SourceRef;
+/** Schema DSL files live under the project's `db/` directory (root-aware). */
+export declare function isSchemaFile(graph: ModuleGraph, path: string): boolean;
+/** View declarations live under `db/views/` (SPEC §11.2, D-157). */
+export declare function isViewFile(graph: ModuleGraph, path: string): boolean;
+export declare function schemaUnknown(reason: string, source: SourceRef): UnknownFact;
+/** Unknowns are also diagnostics: the fact model never hides what the interpreter could not read. */
+export declare function schemaDiagnostics(unknowns: readonly UnknownFact[]): Diagnostic[];

package/dist/passes/schema-dsl.js

@@ -0,0 +1,117 @@
+import { identifierName, isAstNode, memberName, nodeArray, unwrapExpression, } from "../ast/node.js";
+import { diagnostic } from "../diagnostics.js";
+import { sourceRef } from "../source.js";
+function packageOf(specifier) {
+    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) {
+    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, file) {
+    const named = new Map();
+    const namespaces = new Map();
+    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) {
+    const out = [];
+    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) {
+    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, node) {
+    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, path) {
+    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, path) {
+    const prefix = graph.root.length === 0 ? "db/views/" : graph.root + "/db/views/";
+    return path.startsWith(prefix);
+}
+export function schemaUnknown(reason, source) {
+    return { code: "schema-static", reason, source };
+}
+function severityOf(code) {
+    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) {
+    return unknowns.map((unknown) => diagnostic(unknown.code, severityOf(unknown.code), unknown.reason, unknown.source));
+}

package/dist/passes/schema-file-links-ddl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { ColumnFact, PolicyFact, SourceRef } from "../types.js";
+import type { TableDraft } from "./schema-tables.js";
+export declare const FACILIS_FILES_BINDING = "facilisFiles";
+/** The generated link table's columns; `parentColumn` is the `column` option. */
+export declare function linkColumns(parentColumn: string, source: SourceRef): ColumnFact[];
+export declare function linkPolicies(source: SourceRef): PolicyFact[];
+/**
+ * `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 declare function facilisFilesDraft(source: SourceRef): TableDraft;

package/dist/passes/schema-file-links-ddl.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+const FACILIS_FILES = "facilis_files";
+export const FACILIS_FILES_BINDING = "facilisFiles";
+function column(input) {
+    return { ...input, unique: false, unknown: [] };
+}
+/** The generated link table's columns; `parentColumn` is the `column` option. */
+export function linkColumns(parentColumn, source) {
+    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) {
+    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) {
+    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/dist/passes/schema-file-links.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `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 type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic } from "../types.js";
+import type { TableDraft } from "./schema-tables.js";
+export interface FileLinkScan {
+    readonly drafts: readonly TableDraft[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** Lookup-only targets of the generated FKs; see `facilisFilesDraft`. */
+    readonly externalTables: readonly TableDraft[];
+}
+/** Read the top-level `fileLinks(...)` declarators of one schema file into table drafts. */
+export declare function collectFileLinkDrafts(graph: ModuleGraph, file: ProjectFile, drafts: readonly TableDraft[]): FileLinkScan;