@facilis.dev/analyze 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,144 @@
+/**
+ * `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 } from "../ast/node.js";
+import { optionsOf } from "./schema-column-types.js";
+import { createDslResolver, nodeRef, schemaDiagnostics, schemaUnknown, topLevelDeclarators, } from "./schema-dsl.js";
+import { FACILIS_FILES_BINDING, facilisFilesDraft, linkColumns, linkPolicies, } from "./schema-file-links-ddl.js";
+const DB_PACKAGE = "facilis-db";
+const FILE_LINKS = "fileLinks";
+const DEFAULT_PARENT_COLUMN = "parent_id";
+function readOptions(call, binding, context, source) {
+    const label = binding ?? "unknown";
+    const options = optionsOf(callArguments(call)[1], context);
+    const unknowns = [];
+    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 = 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 };
+}
+function readParent(call, drafts, binding, source) {
+    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) {
+    const { call, binding, drafts, context, source } = input;
+    const options = readOptions(call, binding, context, source);
+    const parent = readParent(call, drafts, binding, source);
+    const references = [];
+    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 = [...options.unknowns, ...parent.unknowns];
+    const fact = {
+        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, file, drafts) {
+    const resolver = createDslResolver(graph, file);
+    const context = { graph, file: file.path };
+    const links = [];
+    const externalTables = [];
+    const diagnostics = [];
+    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/dist/passes/schema-foreign-keys.d.ts

@@ -0,0 +1,21 @@
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, TableFact } from "../types.js";
+import type { TableDraft } from "./schema-tables.js";
+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 declare function buildTableLookup(drafts: readonly TableDraft[]): TableLookup;
+/**
+ * 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 declare function withFrameworkTables(lookup: TableLookup, tables: readonly TableDraft[]): TableLookup;
+/** Resolve a table identifier used in the DSL (local const or any project/framework import). */
+export declare function resolveTableBinding(graph: ModuleGraph, filePath: string, local: string, lookup: TableLookup): string | null;
+export declare function finalizeTables(graph: ModuleGraph, drafts: readonly TableDraft[], lookup: TableLookup): {
+    tables: TableFact[];
+    diagnostics: Diagnostic[];
+};

package/dist/passes/schema-foreign-keys.js

@@ -0,0 +1,80 @@
+import { diagnostic } from "../diagnostics.js";
+export function buildTableLookup(drafts) {
+    const byBinding = new Map();
+    const byName = new Map();
+    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, tables) {
+    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, filePath, local, lookup) {
+    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, drafts, lookup) {
+    const tables = [];
+    const diagnostics = [];
+    for (const draft of drafts) {
+        const foreignKeys = [];
+        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 };
+}

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

@@ -0,0 +1,15 @@
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic, PolicyFact } from "../types.js";
+import { type DslResolver } from "./schema-dsl.js";
+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[];
+}
+export declare function buildPolicyFacts(input: PolicyInput): PolicyScan;

package/dist/passes/schema-policies.js

@@ -0,0 +1,201 @@
+import { callArguments, identifierName, memberName, nodeArray, unwrapExpression, } from "../ast/node.js";
+import { staticString } from "../static-eval.js";
+import { optionsOf } from "./schema-column-types.js";
+import { callbackExpression, nodeRef, schemaDiagnostics, schemaUnknown, } from "./schema-dsl.js";
+const COMMANDS = {
+    select: "SELECT",
+    insert: "INSERT",
+    update: "UPDATE",
+    delete: "DELETE",
+    all: "ALL",
+};
+function scan(policies) {
+    return {
+        policies,
+        diagnostics: schemaDiagnostics(policies.flatMap((policy) => policy.unknown)),
+    };
+}
+function fixedPolicy(name, command, restrictive, source, unknown = []) {
+    return { name, command, restrictive, source, unknown };
+}
+function unknownPolicyScan(name, reason, source) {
+    const unknown = schemaUnknown(reason, source);
+    return {
+        policies: [{ name, command: "ALL", restrictive: false, source, unknown: [unknown] }],
+        diagnostics: schemaDiagnostics([unknown]),
+    };
+}
+function calleeLabel(callee) {
+    const node = unwrapExpression(callee);
+    if (node === undefined)
+        return "policy";
+    return identifierName(node) ?? memberName(node) ?? "policy";
+}
+function readPgPolicy(call, context, file) {
+    const source = nodeRef(file, call);
+    const args = callArguments(call);
+    const unknowns = [];
+    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 = "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, context, file) {
+    const source = nodeRef(file, call);
+    const args = callArguments(call);
+    let options = {};
+    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 = [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, context, file, resolver) {
+    if (node === undefined)
+        return null;
+    let call;
+    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 = resolver(call.callee);
+    if (symbol?.pkg !== "facilis-db" ||
+        (symbol.name !== "rlsForTable" && symbol.name !== "withRls")) {
+        return null;
+    }
+    return expandRlsTable(call, context, file);
+}
+function readPolicyEntry(element, context, file, resolver) {
+    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 = [];
+            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, context, file, resolver) {
+    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 = [];
+        const diagnostics = [];
+        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) {
+    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 = { graph: input.graph, file: input.file.path };
+    return readPolicies(expression, context, input.file, input.resolver);
+}

package/dist/passes/schema-re-exports.d.ts

@@ -0,0 +1,5 @@
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ConfigFacts } from "../types.js";
+import { type TableScan } from "./schema-tables.js";
+/** Merge the tables of `export { users } from "@facilis.dev/auth"` (framework source, recursively). */
+export declare function collectReExportedDrafts(graph: ModuleGraph, file: ProjectFile, config: ConfigFacts, seenNames: Set<string>, visitedFiles: Set<string>): TableScan;

package/dist/passes/schema-re-exports.js

@@ -0,0 +1,77 @@
+import { diagnostic } from "../diagnostics.js";
+import { identifierName, literalString, nodeArray } from "../ast/node.js";
+import { nodeRef } from "./schema-dsl.js";
+import { collectTableDrafts } from "./schema-tables.js";
+/** Merge the tables of `export { users } from "@facilis.dev/auth"` (framework source, recursively). */
+export function collectReExportedDrafts(graph, file, config, seenNames, visitedFiles) {
+    const drafts = [];
+    const diagnostics = [];
+    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/dist/passes/schema-relations.d.ts

@@ -0,0 +1,8 @@
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic, RelationFact } from "../types.js";
+import { type TableLookup } from "./schema-foreign-keys.js";
+export interface RelationScan {
+    readonly relations: readonly RelationFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function buildRelationFacts(graph: ModuleGraph, files: readonly ProjectFile[], lookup: TableLookup): RelationScan;