@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/dist/passes/job-relations.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Job `run(ctx)` -> relation usage (D-157 applied to jobs). A job's `db` is the
+ * system-scoped client, so its usage has no elevation bucket: it is the route walk with the
+ * `{ db }` seed on the first parameter and elevations disabled. The walk and the name
+ * resolution are the route ones (`route-relations-walk.ts` / `route-relation-resolve.ts`),
+ * so the two passes cannot drift.
+ */
+import type { ModuleGraph } from "../module-graph.js";
+import type { Diagnostic, TableFact, ViewFact } from "../types.js";
+import type { JobFact, JobRelationsFact } from "../types-jobs.js";
+export interface JobRelationsScan {
+    readonly jobs: readonly JobFact[];
+    /** Usage per job, keyed by the job name (unique across the project). */
+    readonly relations: Readonly<Record<string, JobRelationsFact>>;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** Attach relation-usage facts to every scannable job and derive the D-157 diagnostics. */
+export declare function buildJobRelationFacts(graph: ModuleGraph, jobs: readonly JobFact[], tables: readonly TableFact[], views: readonly ViewFact[]): JobRelationsScan;

package/dist/passes/job-relations.js

@@ -0,0 +1,52 @@
+/**
+ * Job `run(ctx)` -> relation usage (D-157 applied to jobs). A job's `db` is the
+ * system-scoped client, so its usage has no elevation bucket: it is the route walk with the
+ * `{ db }` seed on the first parameter and elevations disabled. The walk and the name
+ * resolution are the route ones (`route-relations-walk.ts` / `route-relation-resolve.ts`),
+ * so the two passes cannot drift.
+ */
+import { callArguments, unwrapExpression } from "../ast/node.js";
+import { EMPTY_JOB_RELATIONS } from "../types-jobs.js";
+import { createRelationIndex } from "./route-relation-resolve.js";
+import { scanFunctionUsage } from "./route-relations-walk.js";
+import { jobRelationDiagnostics } from "./job-relations-diagnostics.js";
+import { resolveJobCall } from "./jobs.js";
+import { readStaticObject, sortDiagnostics } from "./static-read.js";
+/** A job runs as `facilis_system`: `run`'s first parameter is the context, no elevations. */
+const JOB_SEED = { contextParam: 0, elevations: false };
+/** The function expression of the definition's `run` property, when inspectable. */
+function runFunction(graph, file, call) {
+    const object = readStaticObject(callArguments(call)[0], { graph, file: file.path }, { code: "job-definition-static", report: false });
+    const value = unwrapExpression(object.fields.get("run")?.node);
+    return value?.type === "ArrowFunctionExpression" || value?.type === "FunctionExpression"
+        ? value
+        : undefined;
+}
+function toJobRelations(usage) {
+    return {
+        used: usage.used,
+        unresolved: usage.unresolved,
+        rawSql: usage.rawSql,
+        opaque: usage.opaque,
+    };
+}
+/** Attach relation-usage facts to every scannable job and derive the D-157 diagnostics. */
+export function buildJobRelationFacts(graph, jobs, tables, views) {
+    const index = createRelationIndex(tables, views);
+    const relations = {};
+    const diagnostics = [];
+    for (const job of jobs) {
+        const file = graph.file(job.sourceFile);
+        const call = file === undefined ? null : resolveJobCall(file);
+        const run = file !== undefined && call !== null ? runFunction(graph, file, call) : undefined;
+        if (file === undefined || run === undefined) {
+            // The definition warning is the finding; an empty usage avoids a false unused warning.
+            relations[job.name] = EMPTY_JOB_RELATIONS;
+            continue;
+        }
+        const usage = toJobRelations(scanFunctionUsage(graph, file, run, index, JOB_SEED));
+        relations[job.name] = usage;
+        diagnostics.push(...jobRelationDiagnostics(job, usage));
+    }
+    return { jobs, relations, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/jobs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `server/jobs/**` definitions -> JobFacts (D-157 applied to jobs).
+ *
+ * One default export per file: a `defineJob()` call from `@facilis.dev/core`. A file that is not
+ * a valid definition is a warning, not an error: jobs are optional, so a broken file must not
+ * hide the rest of the project. `dbTables` is the declaration the runtime guard enforces, so
+ * an unreadable one is explicit (null) and its warning keeps the jobs gate red.
+ */
+import { type AstNode } from "../ast/node.js";
+import type { ModuleGraph, ProjectFile } from "../module-graph.js";
+import type { Diagnostic } from "../types.js";
+import type { JobFact } from "../types-jobs.js";
+export interface JobResult {
+    readonly jobs: readonly JobFact[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** The `defineJob(...)` call of a valid definition, for later passes (D-157). */
+export declare function resolveJobCall(file: ProjectFile): AstNode | null;
+/** Read every job module under `server/jobs/` into facts (test files are skipped). */
+export declare function buildJobFacts(graph: ModuleGraph): JobResult;

package/dist/passes/jobs.js

@@ -0,0 +1,133 @@
+/**
+ * `server/jobs/**` definitions -> JobFacts (D-157 applied to jobs).
+ *
+ * One default export per file: a `defineJob()` call from `@facilis.dev/core`. A file that is not
+ * a valid definition is a warning, not an error: jobs are optional, so a broken file must not
+ * hide the rest of the project. `dbTables` is the declaration the runtime guard enforces, so
+ * an unreadable one is explicit (null) and its warning keeps the jobs gate red.
+ */
+import { callArguments, identifierName, unwrapExpression } from "../ast/node.js";
+import { warning } from "../diagnostics.js";
+import { defaultExportExpression, isLocallyDeclared, readStaticObject, refOf, relativePath, sortDiagnostics, } from "./static-read.js";
+const CORE_SPECIFIER = "@facilis.dev/core";
+const JOBS_DIR = "server/jobs/";
+const STATIC_CODE = "job-definition-static";
+/** The default export must be a `defineJob(...)` call of the core import. */
+function resolveDefinition(file) {
+    const expression = defaultExportExpression(file);
+    if (expression === undefined) {
+        return { call: null, reason: "the job file has no default export" };
+    }
+    if (expression.type !== "CallExpression") {
+        return { call: null, reason: "the default export is not a defineJob() call" };
+    }
+    const callee = unwrapExpression(expression.callee);
+    const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+    if (name === undefined)
+        return { call: null, reason: "the defineJob callee cannot be resolved" };
+    if (isLocallyDeclared(file, name)) {
+        return { 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 !== "defineJob") {
+        return {
+            call: null,
+            reason: "the default export is not the defineJob import from @facilis.dev/core",
+        };
+    }
+    return { call: expression, reason: "" };
+}
+/** The `defineJob(...)` call of a valid definition, for later passes (D-157). */
+export function resolveJobCall(file) {
+    return resolveDefinition(file).call;
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((entry) => typeof entry === "string") ? [...value] : null;
+}
+function scanFile(graph, file) {
+    const context = { graph, file: file.path };
+    const definition = resolveDefinition(file);
+    const ref = refOf(context, definition.call ?? defaultExportExpression(file));
+    if (definition.call === null) {
+        return { job: null, diagnostics: [warning("job-definition", definition.reason, ref)] };
+    }
+    const object = readStaticObject(callArguments(definition.call)[0], context, {
+        code: STATIC_CODE,
+        report: false,
+    });
+    // A structural read failure (spread/computed key) makes the whole definition suspect: keep
+    // it visible as an unknown and as a warning, as the route config reader does.
+    const unknown = [...object.unknown];
+    const diagnostics = object.unknown.map((item) => warning(item.code, item.reason, item.source));
+    const note = (reason, at) => {
+        const source = refOf(context, at);
+        unknown.push({ code: STATIC_CODE, reason, source });
+        diagnostics.push(warning(STATIC_CODE, reason, source));
+    };
+    const nameField = object.fields.get("name");
+    let name = null;
+    if (nameField !== undefined &&
+        nameField.ok &&
+        typeof nameField.value === "string" &&
+        nameField.value.length > 0) {
+        name = nameField.value;
+    }
+    if (name === null) {
+        diagnostics.push(warning("job-definition", "the job name cannot be read statically", refOf(context, nameField?.node)));
+        return { job: null, diagnostics };
+    }
+    const tablesField = object.fields.get("dbTables");
+    let dbTables = null;
+    if (tablesField === undefined) {
+        note("dbTables is missing; declare the relations the job touches ([] means none)", undefined);
+    }
+    else if (!tablesField.ok) {
+        note("dbTables cannot be read statically: " + (tablesField.reason ?? "unsupported"), tablesField.node);
+    }
+    else {
+        dbTables = stringArray(tablesField.value);
+        if (dbTables === null)
+            note("dbTables must be a string[]", tablesField.node);
+    }
+    const rawSqlField = object.fields.get("rawSql");
+    let rawSql = false;
+    if (rawSqlField !== undefined && !rawSqlField.ok) {
+        rawSql = null;
+        note("rawSql cannot be read statically: " + (rawSqlField.reason ?? "unsupported"), rawSqlField.node);
+    }
+    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;
+            note("rawSql must be a boolean", rawSqlField.node);
+        }
+    }
+    return {
+        job: { name, sourceFile: file.path, source: ref, dbTables, rawSql, unknown },
+        diagnostics,
+    };
+}
+/** Read every job module under `server/jobs/` into facts (test files are skipped). */
+export function buildJobFacts(graph) {
+    const files = [...graph.files.values()]
+        .filter((file) => {
+        const relative = relativePath(graph.root, file.path);
+        return relative.startsWith(JOBS_DIR) && !relative.endsWith(".test.ts");
+    })
+        .toSorted((left, right) => left.path.localeCompare(right.path));
+    const jobs = [];
+    const diagnostics = [];
+    for (const file of files) {
+        const scanned = scanFile(graph, file);
+        if (scanned.job !== null)
+            jobs.push(scanned.job);
+        diagnostics.push(...scanned.diagnostics);
+    }
+    return { jobs, diagnostics: sortDiagnostics(diagnostics) };
+}

package/dist/passes/jsx.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Small ESTree/JSX helpers shared by the route-table and page-preview passes.
+ *
+ * The analyzer's parser contract is parser-independent ESTree, so these helpers only read
+ * structural keys (`openingElement.name`, `attributes`, `children`, `expression`); they never
+ * execute project code and never depend on oxc-specific node types.
+ */
+import { type AstNode } from "../ast/node.js";
+/** `JSXIdentifier` / `JSXMemberExpression` / `JSXNamespacedName` -> display name. */
+export declare function jsxName(node: AstNode | undefined): string | null;
+export declare function openingElement(node: AstNode): AstNode | undefined;
+export declare function elementName(node: AstNode): string | null;
+export declare function jsxChildren(node: AstNode): AstNode[];
+export declare function jsxAttributes(node: AstNode): AstNode[];
+/** The first attribute with this name, or undefined. */
+export declare function jsxAttribute(node: AstNode, name: string): AstNode | undefined;
+/** The value expression of an attribute, unwrapped from `JSXExpressionContainer`. */
+export declare function jsxAttributeValue(attribute: AstNode | undefined): AstNode | undefined;
+/** A JSX element/fragment value, when the expression is one. */
+export declare function jsxElementValue(value: AstNode | undefined): AstNode | undefined;
+export declare function isJsxElement(node: AstNode | undefined): node is AstNode;
+export declare function isSectionIntrinsic(name: string): boolean;

package/dist/passes/jsx.js

@@ -0,0 +1,89 @@
+/**
+ * Small ESTree/JSX helpers shared by the route-table and page-preview passes.
+ *
+ * The analyzer's parser contract is parser-independent ESTree, so these helpers only read
+ * structural keys (`openingElement.name`, `attributes`, `children`, `expression`); they never
+ * execute project code and never depend on oxc-specific node types.
+ */
+import { asNode, nodeArray } from "../ast/node.js";
+/** `JSXIdentifier` / `JSXMemberExpression` / `JSXNamespacedName` -> display name. */
+export function jsxName(node) {
+    if (node === undefined)
+        return null;
+    if (node.type === "JSXIdentifier")
+        return typeof node.name === "string" ? node.name : null;
+    if (node.type === "JSXMemberExpression") {
+        const object = jsxName(asNode(node.object));
+        const property = jsxName(asNode(node.property));
+        return object === null || property === null ? null : object + "." + property;
+    }
+    if (node.type === "JSXNamespacedName") {
+        const namespace = jsxName(asNode(node.namespace));
+        const name = jsxName(asNode(node.name));
+        return namespace === null || name === null ? null : namespace + ":" + name;
+    }
+    return null;
+}
+export function openingElement(node) {
+    return node.type === "JSXElement" ? asNode(node.openingElement) : undefined;
+}
+export function elementName(node) {
+    return jsxName(asNode(openingElement(node)?.name));
+}
+export function jsxChildren(node) {
+    return nodeArray(node, "children");
+}
+export function jsxAttributes(node) {
+    const opening = openingElement(node);
+    return opening === undefined ? [] : nodeArray(opening, "attributes");
+}
+/** The first attribute with this name, or undefined. */
+export function jsxAttribute(node, name) {
+    for (const attribute of jsxAttributes(node)) {
+        if (attribute.type !== "JSXAttribute")
+            continue;
+        if (jsxName(asNode(attribute.name)) === name)
+            return attribute;
+    }
+    return undefined;
+}
+/** The value expression of an attribute, unwrapped from `JSXExpressionContainer`. */
+export function jsxAttributeValue(attribute) {
+    if (attribute === undefined)
+        return undefined;
+    const value = asNode(attribute.value);
+    if (value === undefined)
+        return undefined;
+    if (value.type === "JSXExpressionContainer")
+        return asNode(value.expression);
+    return value;
+}
+/** A JSX element/fragment value, when the expression is one. */
+export function jsxElementValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.type === "JSXElement" || value.type === "JSXFragment")
+        return value;
+    return undefined;
+}
+export function isJsxElement(node) {
+    return node !== undefined && (node.type === "JSXElement" || node.type === "JSXFragment");
+}
+/** JSX elements that carry a page section (`<div>`/`<span>` are flattened away). */
+const SECTION_INTRINSICS = new Set([
+    "header",
+    "main",
+    "section",
+    "nav",
+    "aside",
+    "footer",
+    "form",
+    "table",
+    "ul",
+    "h1",
+    "h2",
+    "h3",
+]);
+export function isSectionIntrinsic(name) {
+    return SECTION_INTRINSICS.has(name);
+}

package/dist/passes/path-expression.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 { type AstNode } from "../ast/node.js";
+import { type StaticContext } from "../static-eval.js";
+import type { HttpMethod, PathKind, RouteFact, UnknownFact } from "../types.js";
+export interface ExtractedPath {
+    readonly kind: PathKind;
+    /** Source text of the argument, for the inspector. */
+    readonly expression: string;
+    /** Leading static text; null when the path has no readable static part. */
+    readonly staticPrefix: string | null;
+    /** Fully static path, when the whole expression is known. */
+    readonly path: string | null;
+    readonly unknown: readonly UnknownFact[];
+}
+/** Extract the path of one client call; failures stay in the unknown channel. */
+export declare function extractPathExpression(argument: AstNode | undefined, context: StaticContext, call: AstNode, code: string): ExtractedPath;
+/** Route ids whose template can produce the call path for the given method. */
+export declare function matchRouteIds(routes: readonly RouteFact[], path: string | null, staticPrefix: string | null, method: HttpMethod): string[];

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;