@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/route-relation-resolve.js

@@ -0,0 +1,172 @@
+/**
+ * Name resolution for the route-relations pass (D-157). Split from route-relations.ts so both
+ * files stay under the 300-line limit.
+ *
+ * Two questions are answered here, without executing project code:
+ * - which relation (table or view) an expression denotes, following same-file consts, project
+ *   imports, re-exports and namespace members;
+ * - which db client an expression denotes, so a use can be attributed to `ctx.db` or to one
+ *   audited elevation callback.
+ *
+ * Anything outside the static subset is explicit: "opaque" means a package binding we cannot
+ * inspect (no error, the runtime guard is the authority), "unresolved" means dynamic project
+ * code (an error, D-157: route-table-unresolved).
+ */
+import { callArguments, identifierName, memberName, unwrapExpression, } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { localInitializer } from "../module-info.js";
+import { findDeclaration } from "./static-read.js";
+export const ROUTE_CLIENT = { elevation: null };
+const UNRESOLVED = { kind: "unresolved" };
+const OPAQUE = { kind: "opaque" };
+/** Table and view bindings, keyed by declaring file + binding (D-157). */
+export function createRelationIndex(tables, views) {
+    const byBinding = new Map();
+    const names = new Set();
+    for (const table of tables) {
+        names.add(table.name);
+        if (table.binding !== null)
+            byBinding.set(table.source.file + "#" + table.binding, table.name);
+    }
+    for (const view of views) {
+        names.add(view.name);
+        if (view.binding !== null)
+            byBinding.set(view.source.file + "#" + view.binding, view.name);
+    }
+    const lookup = { byBinding, names };
+    return {
+        names,
+        resolve: (graph, file, node, aliases, depth = 0) => resolveRelation(graph, file, node, aliases, lookup, depth),
+    };
+}
+const MAX_RELATION_DEPTH = 8;
+function resolveRelation(graph, file, node, aliases, lookup, depth) {
+    const expression = unwrapExpression(node);
+    if (expression === undefined || depth > MAX_RELATION_DEPTH)
+        return UNRESOLVED;
+    if (expression.type === "Identifier") {
+        const local = identifierName(expression);
+        if (local === undefined)
+            return UNRESOLVED;
+        const alias = aliases.get(local);
+        if (alias !== undefined)
+            return { kind: "resolved", name: alias };
+        const initializer = localInitializer(file.program, local);
+        if (initializer !== undefined) {
+            return resolveRelation(graph, file, initializer, aliases, lookup, depth + 1);
+        }
+        const binding = graph.resolveBinding(file.path, local);
+        if (binding === null) {
+            // Framework/package sources are often absent from the file map (the browser IDE's VFS
+            // carries project files only): an imported binding we cannot inspect is opaque, so the
+            // runtime guard stays the authority instead of a false "unresolved" error (D-157).
+            if (file.module.imports.some((entry) => entry.local === local))
+                return OPAQUE;
+            // A project file map may still omit a framework source: fall back to the SQL name.
+            return lookup.names.has(local) ? { kind: "resolved", name: local } : UNRESOLVED;
+        }
+        const direct = lookup.byBinding.get(binding.file + "#" + binding.name);
+        if (direct !== undefined)
+            return { kind: "resolved", name: direct };
+        return binding.file.startsWith("node_modules/") ? OPAQUE : UNRESOLVED;
+    }
+    if (expression.type === "MemberExpression") {
+        const property = memberName(expression);
+        const object = unwrapExpression(expression.object);
+        if (property === undefined || object?.type !== "Identifier")
+            return UNRESOLVED;
+        const namespace = identifierName(object);
+        if (namespace === undefined)
+            return UNRESOLVED;
+        const imported = file.module.imports.find((entry) => entry.local === namespace);
+        if (imported === undefined || imported.kind !== "namespace")
+            return UNRESOLVED;
+        const target = graph.resolve(file.path, imported.specifier);
+        if (target === null)
+            return OPAQUE;
+        const name = lookup.byBinding.get(target + "#" + property);
+        return name === undefined ? UNRESOLVED : { kind: "resolved", name };
+    }
+    if (expression.type === "CallExpression") {
+        // alias(todos, "t") and similar wrappers: the relation is the first argument that resolves.
+        for (const argument of callArguments(expression)) {
+            const resolution = resolveRelation(graph, file, argument, aliases, lookup, depth + 1);
+            if (resolution.kind !== "unresolved")
+                return resolution;
+        }
+        return UNRESOLVED;
+    }
+    return UNRESOLVED;
+}
+/** The db client an expression denotes directly (a local binding or `ctx.db`), if any. */
+export function clientOf(node, env, contextName) {
+    const expression = unwrapExpression(node);
+    if (expression === undefined)
+        return null;
+    if (expression.type === "Identifier") {
+        const local = identifierName(expression);
+        return local === undefined ? null : (env.get(local) ?? null);
+    }
+    if (expression.type === "MemberExpression" && memberName(expression) === "db") {
+        const object = unwrapExpression(expression.object);
+        if (object?.type === "Identifier" && identifierName(object) === contextName)
+            return ROUTE_CLIENT;
+    }
+    return null;
+}
+/** The client at the root of a fluent chain (`db.select()`, `db.query.todos`). */
+export function chainClient(node, env, contextName) {
+    const expression = unwrapExpression(node);
+    if (expression === undefined)
+        return null;
+    const direct = clientOf(expression, env, contextName);
+    if (direct !== null)
+        return direct;
+    if (expression.type === "CallExpression")
+        return chainClient(expression.callee, env, contextName);
+    if (expression.type === "MemberExpression")
+        return chainClient(expression.object, env, contextName);
+    return null;
+}
+/** True when a callee argument carries a db client anywhere (opaque callee detection). */
+export function carriesClient(node, env, contextName) {
+    let found = false;
+    walk(node, (candidate) => {
+        if (!found && clientOf(candidate, env, contextName) !== null)
+            found = true;
+    });
+    return found;
+}
+const FUNCTION_TYPES = new Set([
+    "FunctionExpression",
+    "FunctionDeclaration",
+    "ArrowFunctionExpression",
+]);
+function functionNode(node) {
+    const candidate = unwrapExpression(node);
+    return candidate !== undefined && FUNCTION_TYPES.has(candidate.type) ? candidate : undefined;
+}
+/** A project-local function (never a package one: package calls stay opaque, D-157). */
+export function resolveLocalFunction(graph, file, callee) {
+    const expression = unwrapExpression(callee);
+    if (expression?.type !== "Identifier")
+        return null;
+    const name = identifierName(expression);
+    if (name === undefined)
+        return null;
+    const declared = functionNode(localInitializer(file.program, name)) ??
+        functionNode(findDeclaration(file.program, name));
+    if (declared !== undefined)
+        return { key: file.path + "#" + name, file, node: declared };
+    const binding = graph.resolveBinding(file.path, name);
+    if (binding === null || binding.file.startsWith("node_modules/"))
+        return null;
+    const target = graph.file(binding.file);
+    if (target === undefined)
+        return null;
+    const found = functionNode(localInitializer(target.program, binding.name)) ??
+        functionNode(findDeclaration(target.program, binding.name));
+    if (found === undefined)
+        return null;
+    return { key: target.path + "#" + binding.name, file: target, node: found };
+}

package/dist/passes/route-relations-diagnostics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * D-157 diagnostics derived from a route's relation-usage fact:
+ *
+ * - route-table-undeclared (error): used and not declared in dbTables;
+ * - route-table-unused (warning): declared and not used — suppressed when a project-external
+ *   callee received the client or db.execute is present, where the declaration stays
+ *   authoritative (the runtime guard is the enforcement);
+ * - route-table-unresolved (error): dynamic/unresolvable relation expression;
+ * - route-raw-sql (error): db.execute without rawSql: true;
+ * - route-elevation-undeclared (error): used inside an elevation outside its tables option.
+ */
+import type { RouteRelationsFact } from "../types-relations.js";
+import type { Diagnostic, RouteFact } from "../types.js";
+/** Every diagnostic the relation pass derives from one route's usage fact. */
+export declare function routeRelationDiagnostics(route: RouteFact, usage: RouteRelationsFact): Diagnostic[];

package/dist/passes/route-relations-diagnostics.js

@@ -0,0 +1,79 @@
+/**
+ * D-157 diagnostics derived from a route's relation-usage fact:
+ *
+ * - route-table-undeclared (error): used and not declared in dbTables;
+ * - route-table-unused (warning): declared and not used — suppressed when a project-external
+ *   callee received the client or db.execute is present, where the declaration stays
+ *   authoritative (the runtime guard is the enforcement);
+ * - route-table-unresolved (error): dynamic/unresolvable relation expression;
+ * - route-raw-sql (error): db.execute without rawSql: true;
+ * - route-elevation-undeclared (error): used inside an elevation outside its tables option.
+ */
+import { error, warning } from "../diagnostics.js";
+function usedNames(usage) {
+    const names = new Set(usage.used.map((use) => use.name));
+    for (const elevation of usage.elevations) {
+        for (const use of elevation.used)
+            names.add(use.name);
+    }
+    return names;
+}
+function unusedSuppressed(usage) {
+    return (usage.opaque ||
+        usage.rawSql.length > 0 ||
+        usage.elevations.some((elevation) => elevation.opaque || elevation.tablesUnknown));
+}
+function undeclared(usage, declarations) {
+    const diagnostics = [];
+    for (const use of usage.used) {
+        if (declarations.has(use.name))
+            continue;
+        diagnostics.push(error("route-table-undeclared", 'relation "' + use.name + '" is used through the route db but not declared in dbTables', use.source));
+    }
+    for (const elevation of usage.elevations) {
+        for (const use of elevation.used) {
+            if (declarations.has(use.name))
+                continue;
+            diagnostics.push(error("route-table-undeclared", 'relation "' + use.name + '" is used inside an elevation but not declared in dbTables', use.source));
+        }
+    }
+    return diagnostics;
+}
+/** Every diagnostic the relation pass derives from one route's usage fact. */
+export function routeRelationDiagnostics(route, usage) {
+    const diagnostics = [];
+    const declared = route.dbTables === null ? null : new Set(route.dbTables);
+    if (declared !== null)
+        diagnostics.push(...undeclared(usage, declared));
+    for (const source of usage.unresolved) {
+        diagnostics.push(error("route-table-unresolved", "a relation used through the route db cannot be resolved statically", source));
+    }
+    for (const source of usage.rawSql) {
+        if (route.rawSql === true)
+            continue;
+        diagnostics.push(error("route-raw-sql", "db.execute() requires rawSql: true on the route config", source));
+    }
+    for (const elevation of usage.elevations) {
+        if (elevation.tablesUnknown || elevation.opaque)
+            continue;
+        const tables = new Set(elevation.tables);
+        for (const use of elevation.used) {
+            if (tables.has(use.name))
+                continue;
+            diagnostics.push(error("route-elevation-undeclared", 'relation "' +
+                use.name +
+                '" is used inside a "' +
+                elevation.kind +
+                '" elevation but not declared in its tables option', use.source));
+        }
+    }
+    if (declared !== null && !unusedSuppressed(usage)) {
+        const used = usedNames(usage);
+        for (const name of route.dbTables ?? []) {
+            if (used.has(name))
+                continue;
+            diagnostics.push(warning("route-table-unused", 'dbTables declares "' + name + '" but the route never uses it', route.source));
+        }
+    }
+    return diagnostics;
+}

package/dist/passes/route-relations-follow.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Interprocedural part of the route-relations pass (D-157): follow a project-local function
+ * with argument mapping, and enter an audited elevation callback with its elevated client.
+ *
+ * Package calls stay opaque: the runtime guard is the authority there. Following is bounded
+ * by MAX_DEPTH (walk) and guarded by `scope.stack`, so recursion with a db client terminates.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ElevationKind } from "../types.js";
+import type { LocalFunction } from "./route-relation-resolve.js";
+import type { RelationScope } from "./route-relations-usage.js";
+export type Visit = (node: AstNode, scope: RelationScope) => void;
+/** Follow a project-local call, mapping db clients, elevation handlers and relation bindings. */
+export declare function followFunction(visit: Visit, node: AstNode, scope: RelationScope, local: LocalFunction): void;
+/** Enter an elevation callback with its elevated client bound to the first parameter. */
+export declare function handleElevation(visit: Visit, node: AstNode, scope: RelationScope, kind: ElevationKind): boolean;

package/dist/passes/route-relations-follow.js

@@ -0,0 +1,116 @@
+/**
+ * Interprocedural part of the route-relations pass (D-157): follow a project-local function
+ * with argument mapping, and enter an audited elevation callback with its elevated client.
+ *
+ * Package calls stay opaque: the runtime guard is the authority there. Following is bounded
+ * by MAX_DEPTH (walk) and guarded by `scope.stack`, so recursion with a db client terminates.
+ */
+import { asNode, callArguments, identifierName, memberName, nodeArray, unwrapExpression, } from "../ast/node.js";
+import { sourceRef } from "../source.js";
+import { clientOf } from "./route-relation-resolve.js";
+import { readStaticObject } from "./static-read.js";
+function refOf(scope, node) {
+    return sourceRef(scope.file.path, scope.file.source, typeof node.start === "number" ? node.start : 0);
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((entry) => typeof entry === "string") ? [...value] : null;
+}
+/** Follow a project-local call, mapping db clients, elevation handlers and relation bindings. */
+export function followFunction(visit, node, scope, local) {
+    if (scope.stack.has(local.key))
+        return;
+    const args = callArguments(node);
+    // Usage inside the arguments belongs to the caller (e.g. a query handed to a helper).
+    for (const argument of args)
+        visit(argument, scope);
+    const env = new Map(scope.env);
+    const aliases = new Map(scope.aliases);
+    const elevationFns = new Map(scope.elevationFns);
+    for (const [position, param] of nodeArray(local.node, "params").entries()) {
+        const name = identifierName(param);
+        const argument = args[position];
+        if (name === undefined || argument === undefined)
+            continue;
+        const client = clientOf(argument, scope.env, scope.contextName);
+        if (client !== null) {
+            env.set(name, client);
+            continue;
+        }
+        const kind = elevationKindOf(argument, scope);
+        if (kind !== null) {
+            elevationFns.set(name, kind);
+            continue;
+        }
+        const resolution = scope.index.resolve(scope.graph, scope.file, argument, scope.aliases);
+        if (resolution.kind === "resolved")
+            aliases.set(name, resolution.name);
+    }
+    const body = asNode(local.node.body);
+    if (body === undefined)
+        return;
+    visit(body, {
+        ...scope,
+        file: local.file,
+        env,
+        aliases,
+        elevationFns,
+        contextName: null,
+        depth: scope.depth + 1,
+        stack: new Set([...scope.stack, local.key]),
+    });
+}
+/** An argument that denotes `ctx.sudo`/`ctx.system` (destructured or forwarded). */
+function elevationKindOf(argument, scope) {
+    const expression = unwrapExpression(argument);
+    if (expression?.type === "Identifier") {
+        return scope.elevationFns.get(identifierName(expression) ?? "") ?? null;
+    }
+    if (expression?.type !== "MemberExpression")
+        return null;
+    const name = memberName(expression);
+    const kind = name === "sudo" || name === "system" ? name : null;
+    if (kind === null)
+        return null;
+    const object = unwrapExpression(expression.object);
+    return object?.type === "Identifier" && identifierName(object) === scope.contextName
+        ? kind
+        : null;
+}
+/** Enter an elevation callback with its elevated client bound to the first parameter. */
+export function handleElevation(visit, node, scope, kind) {
+    const options = readStaticObject(callArguments(node)[0], { graph: scope.graph, file: scope.file.path }, { code: "route-relations-static", report: false });
+    const field = options.fields.get("tables");
+    const read = field !== undefined && field.ok ? stringArray(field.value) : null;
+    const tables = read ?? [];
+    const tablesUnknown = read === null;
+    const elevation = {
+        kind,
+        source: refOf(scope, node),
+        tables,
+        tablesUnknown,
+        used: new Map(),
+        unresolved: [],
+        opaque: false,
+    };
+    const index = scope.usage.elevations.push(elevation) - 1;
+    const callback = unwrapExpression(callArguments(node)[1]);
+    if (callback === undefined ||
+        (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression")) {
+        // A callback we cannot inspect leaves the elevated usage unknown, never guessed.
+        elevation.opaque = true;
+        return false;
+    }
+    const body = asNode(callback.body);
+    if (body === undefined) {
+        elevation.opaque = true;
+        return false;
+    }
+    const env = new Map(scope.env);
+    const param = identifierName(nodeArray(callback, "params")[0]);
+    if (param !== undefined)
+        env.set(param, { elevation: index });
+    visit(body, { ...scope, env, elevation: index, depth: scope.depth + 1 });
+    return true;
+}

package/dist/passes/route-relations-usage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared state of the route-relations walk (D-157): the mutable relation-usage accumulators
+ * and the per-frame scope. Kept in one module so the walk and the follow helpers agree on
+ * their shape without importing each other.
+ */
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { RouteRelationsFact } from "../types-relations.js";
+import type { ElevationKind, SourceRef } from "../types.js";
+import type { DbClient, RelationIndex } from "./route-relation-resolve.js";
+export interface MutableElevation {
+    readonly kind: ElevationKind;
+    readonly source: SourceRef;
+    readonly tables: readonly string[];
+    readonly tablesUnknown: boolean;
+    readonly used: Map<string, SourceRef>;
+    readonly unresolved: SourceRef[];
+    opaque: boolean;
+}
+export interface MutableUsage {
+    readonly used: Map<string, SourceRef>;
+    readonly unresolved: SourceRef[];
+    readonly rawSql: SourceRef[];
+    opaque: boolean;
+    readonly elevations: MutableElevation[];
+}
+/** One handler or project-local helper call frame. */
+export interface RelationScope {
+    readonly graph: ModuleGraph;
+    readonly index: RelationIndex;
+    readonly file: ProjectFile;
+    readonly env: Map<string, DbClient>;
+    readonly aliases: Map<string, string>;
+    readonly elevationFns: Map<string, ElevationKind>;
+    readonly contextName: string | null;
+    /**
+     * Whether the scanned body can elevate (`ctx.sudo`/`ctx.system`). Jobs already run
+     * system-scoped, so their pass has no elevation dimension (D-157).
+     */
+    readonly elevations: boolean;
+    /** Elevation bucket of the current callback; null is the route's own ctx.db. */
+    readonly elevation: number | null;
+    readonly depth: number;
+    readonly stack: ReadonlySet<string>;
+    readonly usage: MutableUsage;
+}
+export declare function createUsage(): MutableUsage;
+export declare function addUse(scope: RelationScope, name: string, source: SourceRef): void;
+export declare function addUnresolved(scope: RelationScope, source: SourceRef): void;
+export declare function markOpaque(scope: RelationScope): void;
+export declare function freezeUsage(usage: MutableUsage): RouteRelationsFact;

package/dist/passes/route-relations-usage.js

@@ -0,0 +1,44 @@
+/**
+ * Shared state of the route-relations walk (D-157): the mutable relation-usage accumulators
+ * and the per-frame scope. Kept in one module so the walk and the follow helpers agree on
+ * their shape without importing each other.
+ */
+export function createUsage() {
+    return { used: new Map(), unresolved: [], rawSql: [], opaque: false, elevations: [] };
+}
+function bucket(scope) {
+    const index = scope.elevation;
+    return index === null ? scope.usage : (scope.usage.elevations[index] ?? scope.usage);
+}
+export function addUse(scope, name, source) {
+    const target = bucket(scope);
+    if (!target.used.has(name))
+        target.used.set(name, source);
+}
+export function addUnresolved(scope, source) {
+    bucket(scope).unresolved.push(source);
+}
+export function markOpaque(scope) {
+    bucket(scope).opaque = true;
+}
+function freezeElevation(elevation) {
+    const used = [...elevation.used].map(([name, source]) => ({ name, source }));
+    return {
+        kind: elevation.kind,
+        source: elevation.source,
+        tables: [...elevation.tables],
+        used,
+        unresolved: [...elevation.unresolved],
+        tablesUnknown: elevation.tablesUnknown,
+        opaque: elevation.opaque,
+    };
+}
+export function freezeUsage(usage) {
+    return {
+        used: [...usage.used].map(([name, source]) => ({ name, source })),
+        unresolved: [...usage.unresolved],
+        rawSql: [...usage.rawSql],
+        opaque: usage.opaque,
+        elevations: usage.elevations.map(freezeElevation),
+    };
+}

package/dist/passes/route-relations-walk.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The route-relations walker (D-157): starts at the route handler, tracks db clients and
+ * relation bindings through local declarations, records `from/join/insert/update/delete`,
+ * `db.query.<relation>` and `db.execute`, and hands the interprocedural cases to
+ * route-relations-follow.ts. Everything outside the static subset is explicit (opaque or
+ * unresolved), never guessed.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { RouteRelationsFact } from "../types-relations.js";
+import { type RelationIndex } from "./route-relation-resolve.js";
+/**
+ * How a scanned function receives its db client. Route handlers are `(event, ctx)` and may
+ * elevate; a job's `run` is `(ctx)` and already runs system-scoped, so it has no elevations.
+ */
+export interface UsageSeed {
+    /** Index of the parameter that carries the db context (route: 1, job run: 0). */
+    readonly contextParam: number;
+    /** Route handlers may call ctx.sudo/ctx.system; jobs may not (D-157). */
+    readonly elevations: boolean;
+}
+/** Scan one route handler or job run function into its relation-usage fact. */
+export declare function scanFunctionUsage(graph: ModuleGraph, file: ProjectFile, fn: AstNode, index: RelationIndex, seed: UsageSeed): RouteRelationsFact;
+/** Scan one valid route handler into its relation-usage fact. */
+export declare function scanHandlerUsage(graph: ModuleGraph, file: ProjectFile, handler: AstNode, index: RelationIndex): RouteRelationsFact;