@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/passes/routes.js

@@ -0,0 +1,152 @@
+/**
+ * Route files -> RouteFacts (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * A route is listed even when it does not use the wrapper: the graph is also the integrity
+ * view, so an invalid route is reported instead of omitted. The filename is the only source
+ * of method/path (Nitro's file router); the default export is the only source of the config.
+ */
+import { identifierName, unwrapExpression } from "../ast/node.js";
+import { error, info, warning } from "../diagnostics.js";
+import { defaultExportDeclaration } from "../module-info.js";
+import { sourceRef } from "../source.js";
+import { EMPTY_ROUTE_RELATIONS } from "../types-relations.js";
+import { routeConfigFacts } from "./route-config.js";
+import { scanElevations } from "./route-elevation.js";
+import { directDbWarnings, handlerReadsBody, handlerReadsForm } from "./route-handler.js";
+import { routeLocationFromFile } from "./route-location.js";
+import { defaultExportExpression, isLocallyDeclared, relativePath, sortDiagnostics, } from "./static-read.js";
+const CORE_SPECIFIER = "@facilis.dev/core";
+const ROUTE_DIRS = ["server/routes/", "server/api/"];
+/** The default export must be a `defineAuthorizedHandler(...)` call of the core import. */
+function resolveWrapper(file) {
+    const expression = defaultExportExpression(file);
+    if (expression === undefined) {
+        return { state: "invalid", call: null, reason: "the route file has no default export" };
+    }
+    if (expression.type !== "CallExpression") {
+        return {
+            state: "invalid",
+            call: null,
+            reason: "the default export is not a defineAuthorizedHandler() call",
+        };
+    }
+    const callee = unwrapExpression(expression.callee);
+    const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+    if (name === undefined) {
+        return { state: "unknown", call: null, reason: "the handler callee cannot be resolved" };
+    }
+    if (isLocallyDeclared(file, name)) {
+        return {
+            state: "invalid",
+            call: null,
+            reason: '"' + name + '" is shadowed by a local declaration',
+        };
+    }
+    const imported = file.module.imports.find((entry) => entry.local === name);
+    if (imported === undefined ||
+        imported.specifier !== CORE_SPECIFIER ||
+        imported.imported !== "defineAuthorizedHandler") {
+        return {
+            state: "invalid",
+            call: null,
+            reason: "the default export is not the defineAuthorizedHandler import from @facilis.dev/core",
+        };
+    }
+    return { state: "valid", call: expression, reason: "" };
+}
+function scanRoute(graph, file, config) {
+    const relative = relativePath(graph.root, file.path);
+    const dir = ROUTE_DIRS.find((candidate) => relative.startsWith(candidate));
+    const declaration = defaultExportDeclaration(file.program);
+    const anchor = declaration?.start ?? 0;
+    if (dir === undefined)
+        return { route: null, diagnostics: [] };
+    const location = routeLocationFromFile(relative.slice(dir.length));
+    if (location === undefined) {
+        return {
+            route: null,
+            diagnostics: [
+                info("unknown", "cannot derive a route method/path from the route file name", sourceRef(file.path, file.source, anchor)),
+            ],
+        };
+    }
+    const wrapper = resolveWrapper(file);
+    const ref = sourceRef(file.path, file.source, wrapper.call?.start ?? anchor);
+    if (wrapper.state !== "valid" || wrapper.call === null) {
+        return {
+            route: {
+                method: location.method,
+                path: location.path,
+                sourceFile: file.path,
+                source: ref,
+                wrapper: wrapper.state,
+                permission: null,
+                crossSite: null,
+                dbTables: null,
+                dbColumns: null,
+                rawSql: null,
+                relations: EMPTY_ROUTE_RELATIONS,
+                description: null,
+                input: { body: false, form: false, query: false, params: false },
+                handlerBodyRead: false,
+                handlerFormRead: false,
+                elevations: [],
+                unknown: [{ code: "route-wrapper", reason: wrapper.reason, source: ref }],
+            },
+            diagnostics: [error("route-wrapper", wrapper.reason, ref)],
+        };
+    }
+    const facts = routeConfigFacts(graph, file, wrapper.call, config);
+    const elevation = scanElevations(graph, file, wrapper.call);
+    return {
+        route: {
+            method: location.method,
+            path: location.path,
+            sourceFile: file.path,
+            source: ref,
+            wrapper: "valid",
+            permission: facts.permission,
+            crossSite: facts.crossSite,
+            dbTables: facts.dbTables,
+            dbColumns: facts.dbColumns,
+            rawSql: facts.rawSql,
+            relations: EMPTY_ROUTE_RELATIONS,
+            description: facts.description,
+            input: facts.input,
+            handlerBodyRead: handlerReadsBody(wrapper.call),
+            handlerFormRead: handlerReadsForm(wrapper.call),
+            elevations: elevation.facts,
+            unknown: [...facts.unknown, ...elevation.unknown],
+        },
+        diagnostics: [
+            ...facts.diagnostics,
+            ...elevation.unknown.map((item) => 
+            // An unreadable elevation cannot be shown in the graph; warn without blocking the route.
+            warning(item.code, item.reason, item.source)),
+            ...directDbWarnings(file, ref),
+        ],
+    };
+}
+/** The `defineAuthorizedHandler(...)` call of a valid wrapper, for later passes (D-157). */
+export function resolveWrapperCall(file) {
+    const wrapper = resolveWrapper(file);
+    return wrapper.state === "valid" ? wrapper.call : null;
+}
+/** Read `server/routes/**` and `server/api/**` into route facts. */
+export function buildRouteFacts(graph, config) {
+    const files = [...graph.files.values()]
+        .filter((file) => ROUTE_DIRS.some((dir) => relativePath(graph.root, file.path).startsWith(dir)))
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+    const routes = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const scanned = scanRoute(graph, file, config);
+        if (scanned.route !== null)
+            routes.push(scanned.route);
+        diagnostics.push(...scanned.diagnostics);
+    }
+    routes.sort((left, right) => left.path.localeCompare(right.path) ||
+        left.method.localeCompare(right.method) ||
+        left.sourceFile.localeCompare(right.sourceFile));
+    return { routes, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/schema-column-types.d.ts

@@ -0,0 +1,9 @@
+import type { AstNode } from "../ast/node.js";
+import { type StaticContext } from "../static-eval.js";
+import type { ColumnDefaultFact } from "../types.js";
+/** Static object argument of a builder/method, e.g. `{ withTimezone: true }`. */
+export declare function optionsOf(node: AstNode | undefined, context: StaticContext): Record<string, unknown> | null;
+/** Display type derived from the builder and its static arguments (never a rendered SQL type). */
+export declare function displayType(name: string, args: readonly AstNode[], context: StaticContext): string;
+/** `.default(value)`: only primitives are facts; a SQL expression is an explicit unknown. */
+export declare function readDefault(node: AstNode | undefined, context: StaticContext): ColumnDefaultFact;

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;