@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/dist/passes/path-expression.js

@@ -0,0 +1,265 @@
+/**
+ * Client path expressions -> static prefixes and route matches (§3.4 of the AST DSL
+ * contract).
+ *
+ * A path is read as a static prefix plus a dynamic tail: literal strings and const strings
+ * are exact, while concatenations and templates keep the leading static segments. One hop of
+ * a path-builder function is inlined (the builder's return expression); anything deeper is
+ * dynamic, not guessed.
+ */
+import { asNode, identifierName, isAstNode, nodeArray, unwrapExpression, } from "../ast/node.js";
+import { defaultExportDeclaration, localInitializer } from "../module-info.js";
+import { evaluateStatic } from "../static-eval.js";
+import { routeFactId } from "./route-location.js";
+import { findDeclaration, refOf } from "./static-read.js";
+const MAX_RESOLVE_DEPTH = 8;
+function sourceText(source, node) {
+    if (node === undefined || typeof node.start !== "number" || typeof node.end !== "number") {
+        return "";
+    }
+    return source.slice(node.start, node.end).trim();
+}
+function cookedString(quasi) {
+    // TemplateElement.value is a plain { raw, cooked } record, not an AST node (asNode rejects it).
+    const value = quasi?.value;
+    if (typeof value !== "object" || value === null)
+        return "";
+    const cooked = value.cooked;
+    return typeof cooked === "string" ? cooked : "";
+}
+function evaluatePrimitive(node, context) {
+    const evaluated = evaluateStatic(node, context);
+    const value = evaluated.ok ? evaluated.value : undefined;
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? String(value)
+        : null;
+}
+/** Leading static text of a literal, template or `+` chain, plus whether it is whole. */
+function partialStaticPrefix(node, context, depth = 0) {
+    if (node === undefined || depth > MAX_RESOLVE_DEPTH)
+        return null;
+    const unwrapped = unwrapExpression(node);
+    if (unwrapped === undefined)
+        return null;
+    if (unwrapped.type === "Literal") {
+        return typeof unwrapped.value === "string" ? { prefix: unwrapped.value, complete: true } : null;
+    }
+    if (unwrapped.type === "TemplateLiteral") {
+        const quasis = nodeArray(unwrapped, "quasis");
+        const expressions = nodeArray(unwrapped, "expressions");
+        let prefix = "";
+        for (const [index, quasi] of quasis.entries()) {
+            prefix += cookedString(quasi);
+            const expression = expressions[index];
+            if (expression === undefined)
+                continue;
+            const value = evaluatePrimitive(expression, context);
+            if (value === null)
+                return { prefix, complete: false };
+            prefix += value;
+        }
+        return { prefix, complete: true };
+    }
+    if (unwrapped.type === "BinaryExpression" && unwrapped.operator === "+") {
+        const left = partialStaticPrefix(asNode(unwrapped.left), context, depth + 1);
+        if (left === null)
+            return null;
+        if (!left.complete)
+            return left;
+        const right = partialStaticPrefix(asNode(unwrapped.right), context, depth + 1);
+        return right === null
+            ? { prefix: left.prefix, complete: false }
+            : { prefix: left.prefix + right.prefix, complete: right.complete };
+    }
+    const value = evaluatePrimitive(unwrapped, context);
+    return value === null ? null : { prefix: value, complete: true };
+}
+function firstReturn(node) {
+    if (node.type === "ReturnStatement")
+        return asNode(node.argument);
+    for (const key of Object.keys(node)) {
+        if (key === "type" || key === "start" || key === "end")
+            continue;
+        const value = node[key];
+        const children = (Array.isArray(value) ? value : [value]).filter(isAstNode);
+        for (const child of children) {
+            // A nested function owns its return statements; only this function's count.
+            if (child.type.endsWith("FunctionExpression") || child.type === "FunctionDeclaration") {
+                continue;
+            }
+            const found = firstReturn(child);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+function functionReturnExpression(fn) {
+    const body = asNode(fn.body);
+    if (body === undefined)
+        return undefined;
+    return body.type === "BlockStatement" ? firstReturn(body) : body;
+}
+/** Inline one hop of an imported path-builder function (its return expression). */
+function resolvePathBuilder(call, context) {
+    const callee = unwrapExpression(call.callee);
+    const name = identifierName(callee);
+    const file = context.graph.file(context.file);
+    if (name === undefined || file === undefined)
+        return null;
+    const imported = file.module.imports.find((entry) => entry.local === name);
+    if (imported === undefined)
+        return null;
+    const target = context.graph.resolve(context.file, imported.specifier);
+    if (target === null || target.startsWith("node_modules/"))
+        return null;
+    const binding = context.graph.resolveExport(target, imported.imported ?? "default");
+    if (binding === null)
+        return null;
+    const module = context.graph.file(binding.file);
+    if (module === undefined)
+        return null;
+    const initializer = binding.name === "default"
+        ? defaultExportDeclaration(module.program)
+        : (localInitializer(module.program, binding.name) ??
+            findDeclaration(module.program, binding.name));
+    const fn = unwrapExpression(initializer);
+    if (fn === undefined || !/Function/.test(fn.type))
+        return null;
+    const returned = functionReturnExpression(fn);
+    if (returned === undefined)
+        return null;
+    return partialStaticPrefix(returned, { graph: context.graph, file: module.path });
+}
+/** Extract the path of one client call; failures stay in the unknown channel. */
+export function extractPathExpression(argument, context, call, code) {
+    const file = context.graph.file(context.file);
+    const source = file?.source ?? "";
+    const callRef = refOf(context, call);
+    const argumentNode = unwrapExpression(argument);
+    const expression = sourceText(source, argumentNode) || sourceText(source, call);
+    if (argumentNode === undefined) {
+        return {
+            kind: "dynamic",
+            expression,
+            staticPrefix: null,
+            path: null,
+            unknown: [{ code, reason: "the call has no path argument", source: callRef }],
+        };
+    }
+    const unknown = [];
+    if (argumentNode.type === "CallExpression") {
+        const builder = resolvePathBuilder(argumentNode, context);
+        if (builder !== null) {
+            return {
+                kind: "builder",
+                expression,
+                staticPrefix: builder.prefix.length === 0 ? null : builder.prefix,
+                path: builder.complete ? builder.prefix : null,
+                unknown,
+            };
+        }
+        unknown.push({
+            code,
+            reason: "the path builder could not be resolved statically",
+            source: callRef,
+        });
+        return { kind: "unknown", expression, staticPrefix: null, path: null, unknown };
+    }
+    if (argumentNode.type === "TemplateLiteral" || argumentNode.type === "BinaryExpression") {
+        const partial = partialStaticPrefix(argumentNode, context);
+        if (partial !== null) {
+            return {
+                kind: argumentNode.type === "TemplateLiteral" ? "template" : "concat",
+                expression,
+                staticPrefix: partial.prefix.length === 0 ? null : partial.prefix,
+                path: partial.complete ? partial.prefix : null,
+                unknown,
+            };
+        }
+    }
+    const evaluated = evaluateStatic(argumentNode, context);
+    if (evaluated.ok && typeof evaluated.value === "string") {
+        return {
+            kind: "literal",
+            expression,
+            staticPrefix: evaluated.value.length === 0 ? null : evaluated.value,
+            path: evaluated.value,
+            unknown,
+        };
+    }
+    unknown.push({
+        code,
+        reason: evaluated.ok ? "the path is not a string" : evaluated.reason,
+        source: callRef,
+    });
+    return { kind: "dynamic", expression, staticPrefix: null, path: null, unknown };
+}
+function pathSegments(path) {
+    const base = path.split("?")[0] ?? "";
+    return (base.split("#")[0] ?? "").split("/").filter(Boolean);
+}
+function isDynamicSegment(segment) {
+    return segment.startsWith("{") && segment.endsWith("}");
+}
+function templateMatches(template, segments) {
+    let index = 0;
+    for (; index < template.length; index += 1) {
+        const templateSegment = template[index] ?? "";
+        if (templateSegment.startsWith("{*"))
+            return segments.length > index;
+        if (isDynamicSegment(templateSegment)) {
+            if (index >= segments.length)
+                return false;
+            continue;
+        }
+        if (segments[index] !== templateSegment)
+            return false;
+    }
+    return segments.length === index;
+}
+function prefixMatches(template, prefixSegments, trailingSlash) {
+    for (const [index, prefixSegment] of prefixSegments.entries()) {
+        const templateSegment = template[index];
+        if (templateSegment === undefined)
+            return false;
+        if (templateSegment.startsWith("{*"))
+            return false;
+        if (isDynamicSegment(templateSegment))
+            continue;
+        if (templateSegment !== prefixSegment)
+            return false;
+    }
+    const rest = template.slice(prefixSegments.length);
+    // A trailing slash means at least one more (dynamic) segment at the call site.
+    if (trailingSlash && rest.length === 0)
+        return false;
+    return rest.every((segment) => isDynamicSegment(segment));
+}
+function routeMatches(routePath, path, staticPrefix) {
+    const template = pathSegments(routePath);
+    if (path !== null)
+        return templateMatches(template, pathSegments(path));
+    if (staticPrefix === null)
+        return false;
+    return prefixMatches(template, pathSegments(staticPrefix), staticPrefix.endsWith("/"));
+}
+/** Route ids whose template can produce the call path for the given method. */
+export function matchRouteIds(routes, path, staticPrefix, method) {
+    if (path === null && staticPrefix === null)
+        return [];
+    const ids = [];
+    const seen = new Set();
+    for (const route of routes) {
+        if (route.method !== "ALL" && route.method !== method)
+            continue;
+        if (!routeMatches(route.path, path, staticPrefix))
+            continue;
+        const id = routeFactId(route);
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        ids.push(id);
+    }
+    return ids;
+}

package/dist/passes/route-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The wrapper config subset: permission/crossSite/dbTables/dbColumns/description/input.
+ *
+ * Split from routes.ts so both modules stay under the 300-line limit; every failure is an
+ * explicit unknown (never an empty value) and a diagnostic, as in the rest of the analyzer.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ConfigFacts, Diagnostic, RouteInputFact, UnknownFact } from "../types.js";
+export interface RouteConfigFacts {
+    readonly permission: readonly string[] | null;
+    /** True when the wrapper opts the route into cross-origin calls; null when unreadable. */
+    readonly crossSite: boolean | null;
+    /** rawSql: true allows `db.execute` (D-157); false when absent; null when unreadable. */
+    readonly rawSql: boolean | null;
+    readonly dbTables: readonly string[] | null;
+    readonly dbColumns: readonly string[] | null;
+    readonly description: string | null;
+    readonly input: RouteInputFact;
+    readonly unknown: readonly UnknownFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Read the wrapper config from the static subset; every failure is explicit. */
+export declare function routeConfigFacts(graph: ModuleGraph, file: ProjectFile, call: AstNode, config: ConfigFacts): RouteConfigFacts;

package/dist/passes/route-config.js

@@ -0,0 +1,152 @@
+/**
+ * The wrapper config subset: permission/crossSite/dbTables/dbColumns/description/input.
+ *
+ * Split from routes.ts so both modules stay under the 300-line limit; every failure is an
+ * explicit unknown (never an empty value) and a diagnostic, as in the rest of the analyzer.
+ */
+import { callArguments } from "../ast/node.js";
+import { error, warning } from "../diagnostics.js";
+import { descriptionDiagnostics } from "./route-description.js";
+import { readStaticObject, refOf } from "./static-read.js";
+const MISSING_PERMISSION = "permission is missing";
+const MISSING_TABLES = "dbTables is missing; declare an array ([] means no DB)";
+function stringArrayValue(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((item) => typeof item === "string") ? [...value] : null;
+}
+function permissionValue(value) {
+    return typeof value === "string" ? [value] : stringArrayValue(value);
+}
+function addUnknown(list, code, reason, source) {
+    list.push({ code, reason, source });
+}
+function unreadable(field, entry) {
+    return field + " cannot be read statically: " + (entry.reason ?? "unsupported expression");
+}
+/** Read the wrapper config from the static subset; every failure is explicit. */
+export function routeConfigFacts(graph, file, call, config) {
+    const context = { graph, file: file.path };
+    const ref = refOf(context, call);
+    // Input schemas (body/query/params) are read for presence only: a Zod expression there is
+    // expected, so only the security/display fields below report a static-read failure.
+    const object = readStaticObject(callArguments(call)[0], context, {
+        code: "route-config-static",
+        report: false,
+    });
+    const unknown = [...object.unknown];
+    const field = (name) => object.fields.get(name);
+    const permissionField = field("permission");
+    let permission = null;
+    if (permissionField === undefined) {
+        addUnknown(unknown, "route-config-static", MISSING_PERMISSION, ref);
+    }
+    else if (!permissionField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("permission", permissionField), ref);
+    }
+    else {
+        permission = permissionValue(permissionField.value);
+        if (permission === null) {
+            addUnknown(unknown, "route-config-static", "permission must be a string or string[]", ref);
+        }
+    }
+    const crossSiteField = field("crossSite");
+    let crossSite = false;
+    if (crossSiteField !== undefined && !crossSiteField.ok) {
+        crossSite = null;
+        addUnknown(unknown, "route-config-static", unreadable("crossSite", crossSiteField), ref);
+    }
+    else if (crossSiteField !== undefined) {
+        if (typeof crossSiteField.value === "boolean")
+            crossSite = crossSiteField.value;
+        else {
+            crossSite = null;
+            addUnknown(unknown, "route-config-static", "crossSite must be a boolean", ref);
+        }
+    }
+    const rawSqlField = field("rawSql");
+    let rawSql = false;
+    if (rawSqlField !== undefined && !rawSqlField.ok) {
+        rawSql = null;
+        addUnknown(unknown, "route-config-static", unreadable("rawSql", rawSqlField), ref);
+    }
+    else if (rawSqlField !== undefined) {
+        if (typeof rawSqlField.value === "boolean")
+            rawSql = rawSqlField.value;
+        else {
+            // An unreadable derogation is never assumed: db.execute then fails closed (D-157).
+            rawSql = null;
+            addUnknown(unknown, "route-config-static", "rawSql must be a boolean", ref);
+        }
+    }
+    const tablesField = field("dbTables");
+    let dbTables = null;
+    if (tablesField === undefined) {
+        addUnknown(unknown, "db-tables-present", MISSING_TABLES, ref);
+    }
+    else if (!tablesField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("dbTables", tablesField), ref);
+    }
+    else {
+        dbTables = stringArrayValue(tablesField.value);
+        if (dbTables === null) {
+            addUnknown(unknown, "route-config-static", "dbTables must be a string[]", ref);
+        }
+    }
+    const columnsField = field("dbColumns");
+    let dbColumns = columnsField === undefined ? [] : null;
+    if (columnsField !== undefined && !columnsField.ok) {
+        dbColumns = null;
+        addUnknown(unknown, "route-config-static", unreadable("dbColumns", columnsField), ref);
+    }
+    else if (columnsField !== undefined) {
+        dbColumns = stringArrayValue(columnsField.value);
+        if (dbColumns === null) {
+            addUnknown(unknown, "route-config-static", "dbColumns must be a string[]", ref);
+        }
+    }
+    const descriptionField = field("description");
+    let description = null;
+    if (descriptionField !== undefined && !descriptionField.ok) {
+        addUnknown(unknown, "route-config-static", unreadable("description", descriptionField), ref);
+    }
+    else if (descriptionField !== undefined) {
+        if (typeof descriptionField.value === "string")
+            description = descriptionField.value;
+        else
+            addUnknown(unknown, "route-config-static", "description must be a string", ref);
+    }
+    const input = {
+        body: field("body") !== undefined,
+        form: field("form") !== undefined,
+        query: field("query") !== undefined,
+        params: field("params") !== undefined,
+    };
+    const diagnostics = [
+        ...unknown.map((item) => error(item.code, item.reason, item.source)),
+        ...descriptionDiagnostics(description, ref),
+    ];
+    if (permission !== null) {
+        for (const name of permission) {
+            if (!config.permissions.includes(name)) {
+                diagnostics.push(error("permission-declared", 'permission "' + name + '" is not declared in config.auth.permissions', ref));
+            }
+        }
+    }
+    // v3a: crossSite + a non-empty permission is legal now (the route is reached with a Bearer
+    // token); the warning only reminds the author that a session cookie never crosses origins.
+    if (crossSite === true && permission !== null && permission.length > 0) {
+        diagnostics.push(warning("route-cross-site-authenticated", "crossSite route requires a Bearer token: session cookies never cross origins", ref));
+    }
+    return {
+        permission,
+        crossSite,
+        rawSql,
+        dbTables,
+        dbColumns,
+        description,
+        input,
+        unknown,
+        diagnostics,
+    };
+}

package/dist/passes/route-description.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Route description rules (D-129).
+ *
+ * The description is source documentation: one English sentence stored in the
+ * defineAuthorizedHandler config, shown under the route node and in the OpenAPI document.
+ * Two lines is its useful maximum, so the analyzer reports a warning when it runs long.
+ * The patch validator imports the same limit, so the AI and the user see one number.
+ */
+import type { Diagnostic, SourceRef } from "../types.js";
+/** About two lines in the route definition and in the graph card. */
+export declare const ROUTE_DESCRIPTION_MAX_CHARS = 120;
+/** A warning when the description exceed the two-line budget; nothing to report otherwise. */
+export declare function descriptionDiagnostics(description: string | null, source: SourceRef | null): readonly Diagnostic[];

package/dist/passes/route-description.js

@@ -0,0 +1,23 @@
+/**
+ * Route description rules (D-129).
+ *
+ * The description is source documentation: one English sentence stored in the
+ * defineAuthorizedHandler config, shown under the route node and in the OpenAPI document.
+ * Two lines is its useful maximum, so the analyzer reports a warning when it runs long.
+ * The patch validator imports the same limit, so the AI and the user see one number.
+ */
+import { warning } from "../diagnostics.js";
+/** About two lines in the route definition and in the graph card. */
+export const ROUTE_DESCRIPTION_MAX_CHARS = 120;
+/** A warning when the description exceed the two-line budget; nothing to report otherwise. */
+export function descriptionDiagnostics(description, source) {
+    if (description === null || description.length <= ROUTE_DESCRIPTION_MAX_CHARS)
+        return [];
+    return [
+        warning("route-description-length", "description is " +
+            description.length +
+            " characters; keep it to " +
+            ROUTE_DESCRIPTION_MAX_CHARS +
+            " (about two lines)", source),
+    ];
+}

package/dist/passes/route-elevation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Audited elevation facts from a route handler (D-099): `ctx.sudo` and `ctx.system`.
+ *
+ * Only the handler's own context can elevate: a destructured `{ sudo }`/`{ system }` binding
+ * or a member call on the context parameter. Any other identifier named `sudo` is ignored, so
+ * the graph cannot be colored by a local helper with the same name. The tables and operation
+ * are read through the bounded static subset; when that fails the fact is explicit (unknown
+ * plus an empty table list), never guessed.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { ElevationFact, UnknownFact } from "../types.js";
+export interface ElevationScan {
+    readonly facts: readonly ElevationFact[];
+    readonly unknown: readonly UnknownFact[];
+}
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export declare function scanElevations(graph: ModuleGraph, file: ProjectFile, wrapperCall: AstNode): ElevationScan;

package/dist/passes/route-elevation.js

@@ -0,0 +1,136 @@
+/**
+ * Audited elevation facts from a route handler (D-099): `ctx.sudo` and `ctx.system`.
+ *
+ * Only the handler's own context can elevate: a destructured `{ sudo }`/`{ system }` binding
+ * or a member call on the context parameter. Any other identifier named `sudo` is ignored, so
+ * the graph cannot be colored by a local helper with the same name. The tables and operation
+ * are read through the bounded static subset; when that fails the fact is explicit (unknown
+ * plus an empty table list), never guessed.
+ */
+import { callArguments, identifierName, memberName, nodeArray, objectEntries, propertyName, propertyValue, unwrapExpression, } from "../ast/node.js";
+import { walk } from "../ast/walk.js";
+import { readStaticObject } from "./static-read.js";
+function refOf(file, node) {
+    const offset = typeof node.start === "number" ? node.start : 0;
+    let line = 1;
+    for (let index = 0; index < offset && index < file.source.length; index += 1) {
+        if (file.source.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return { file: file.path, line };
+}
+function elevationKind(name) {
+    if (name === "sudo" || name === "system")
+        return name;
+    return null;
+}
+/** Local identifier -> elevation kind for `{ sudo }` / `{ sudo: elevate }`. */
+function handlerBindings(handler) {
+    const locals = new Map();
+    const context = nodeArray(handler, "params")[1];
+    if (context === undefined)
+        return { locals, contextName: null };
+    if (context.type === "Identifier") {
+        return { locals, contextName: identifierName(context) ?? null };
+    }
+    if (context.type !== "ObjectPattern")
+        return { locals, contextName: null };
+    for (const entry of objectEntries(context)) {
+        if (entry.type !== "Property")
+            continue;
+        const kind = elevationKind(propertyName(entry));
+        if (kind === null)
+            continue;
+        let value = propertyValue(entry);
+        if (value !== undefined && value.type === "AssignmentPattern") {
+            value = unwrapExpression(value.left);
+        }
+        const local = identifierName(unwrapExpression(value));
+        if (local !== undefined)
+            locals.set(local, kind);
+    }
+    return { locals, contextName: null };
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((entry) => typeof entry === "string") ? [...value] : null;
+}
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export function scanElevations(graph, file, wrapperCall) {
+    const handler = callArguments(wrapperCall)[1];
+    if (handler === undefined)
+        return { facts: [], unknown: [] };
+    const handlerNode = unwrapExpression(handler);
+    if (handlerNode === undefined ||
+        (handlerNode.type !== "ArrowFunctionExpression" && handlerNode.type !== "FunctionExpression")) {
+        return { facts: [], unknown: [] };
+    }
+    const bindings = handlerBindings(handlerNode);
+    const facts = [];
+    const unknown = [];
+    walk(handlerNode, (node) => {
+        if (node.type !== "CallExpression")
+            return;
+        const callee = unwrapExpression(node.callee);
+        if (callee === undefined)
+            return;
+        let kind = null;
+        if (callee.type === "Identifier") {
+            kind = bindings.locals.get(identifierName(callee) ?? "") ?? null;
+        }
+        else if (callee.type === "MemberExpression") {
+            const name = memberName(callee);
+            const object = unwrapExpression(callee.object);
+            if (name !== undefined &&
+                object?.type === "Identifier" &&
+                identifierName(object) === bindings.contextName) {
+                kind = elevationKind(name);
+            }
+        }
+        if (kind === null)
+            return;
+        const source = refOf(file, node);
+        const options = readStaticObject(callArguments(node)[0], { graph, file: file.path }, {
+            code: "route-elevation-static",
+            report: true,
+        });
+        const factUnknown = [...options.unknown];
+        const tablesField = options.fields.get("tables");
+        let tables = [];
+        if (tablesField === undefined) {
+            factUnknown.push({
+                code: "route-elevation-static",
+                reason: "elevation tables are missing",
+                source,
+            });
+        }
+        else if (!tablesField.ok) {
+            factUnknown.push({
+                code: "route-elevation-static",
+                reason: "elevation tables cannot be read statically",
+                source,
+            });
+        }
+        else {
+            const read = stringArray(tablesField.value);
+            if (read === null) {
+                factUnknown.push({
+                    code: "route-elevation-static",
+                    reason: "elevation tables must be a string[]",
+                    source,
+                });
+            }
+            else {
+                tables = read;
+            }
+        }
+        const operationField = options.fields.get("operation");
+        const operation = operationField !== undefined && operationField.ok && typeof operationField.value === "string"
+            ? operationField.value
+            : null;
+        unknown.push(...factUnknown);
+        facts.push({ kind, tables, operation, source, unknown: factUnknown });
+    });
+    return { facts, unknown };
+}

package/dist/passes/route-handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Facts read from a route handler expression (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * The security rules need to know whether a handler reads the request input — the JSON body
+ * or the multipart form: the fact must come from the AST, not from a comment or a string, so
+ * a route cannot look validated by mentioning `body`/`form` in prose.
+ *
+ * The same reasoning drives the direct-DB warning: a handler that reaches the raw client
+ * through `event.context.facilis.db` or imports the `createDb` factory bypasses the
+ * policy-scoped client, and only the AST can tell a real access from a string mention.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ProjectFile } from "../module-graph.js";
+import type { Diagnostic, SourceRef } from "../types.js";
+/** Warning text for raw/direct DB access in a route file. */
+export declare const ROUTE_DIRECT_DB_MESSAGE = "Direct DB access bypasses the policy-scoped client; use ctx.db for user-scoped work and ctx.system/ctx.sudo for audited system operations (not recommended).";
+/** True when the handler reads `.body` or destructures a `{ body }` pattern. */
+export declare function handlerReadsBody(call: AstNode): boolean;
+/** True when the handler reads `.form` or destructures a `{ form }` pattern (D-053). */
+export declare function handlerReadsForm(call: AstNode): boolean;
+/**
+ * Warnings for raw/direct DB access in a route file: `event.context.facilis.db` bypasses
+ * the policy-scoped client, and importing the `createDb` factory is the raw-client path.
+ * The source points at the offending node (or the route when a node has no position), so
+ * the IDE can jump to it.
+ */
+export declare function directDbWarnings(file: ProjectFile, fallback: SourceRef): Diagnostic[];