@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/passes/path-expression.ts

@@ -0,0 +1,297 @@
+/**
+ * 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,
+  type AstNode,
+} from "../ast/node.ts";
+import { defaultExportDeclaration, localInitializer } from "../module-info.ts";
+import { evaluateStatic, type StaticContext } from "../static-eval.ts";
+import type { HttpMethod, PathKind, RouteFact, UnknownFact } from "../types.ts";
+import { routeFactId } from "./route-location.ts";
+import { findDeclaration, refOf } from "./static-read.ts";
+
+const MAX_RESOLVE_DEPTH = 8;
+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[];
+}
+interface PartialPrefix {
+  readonly prefix: string;
+  readonly complete: boolean;
+}
+
+function sourceText(source: string, node: AstNode | undefined): string {
+  if (node === undefined || typeof node.start !== "number" || typeof node.end !== "number") {
+    return "";
+  }
+  return source.slice(node.start, node.end).trim();
+}
+
+function cookedString(quasi: AstNode | undefined): string {
+  // 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 as Record<string, unknown>).cooked;
+  return typeof cooked === "string" ? cooked : "";
+}
+
+function evaluatePrimitive(node: AstNode, context: StaticContext): string | null {
+  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: AstNode | undefined,
+  context: StaticContext,
+  depth = 0,
+): PartialPrefix | null {
+  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: AstNode): AstNode | undefined {
+  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: AstNode): AstNode | undefined {
+  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: AstNode, context: StaticContext): PartialPrefix | null {
+  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: AstNode | undefined,
+  context: StaticContext,
+  call: AstNode,
+  code: string,
+): ExtractedPath {
+  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: UnknownFact[] = [];
+  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: string): string[] {
+  const base = path.split("?")[0] ?? "";
+  return (base.split("#")[0] ?? "").split("/").filter(Boolean);
+}
+
+function isDynamicSegment(segment: string): boolean {
+  return segment.startsWith("{") && segment.endsWith("}");
+}
+
+function templateMatches(template: readonly string[], segments: readonly string[]): boolean {
+  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: readonly string[],
+  prefixSegments: readonly string[],
+  trailingSlash: boolean,
+): boolean {
+  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: string,
+  path: string | null,
+  staticPrefix: string | null,
+): boolean {
+  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: readonly RouteFact[],
+  path: string | null,
+  staticPrefix: string | null,
+  method: HttpMethod,
+): string[] {
+  if (path === null && staticPrefix === null) return [];
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  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/src/passes/route-config.ts

@@ -0,0 +1,188 @@
+/**
+ * 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, type AstNode } from "../ast/node.ts";
+import { error, warning } from "../diagnostics.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { StaticContext } from "../static-eval.ts";
+import type { ConfigFacts, Diagnostic, RouteInputFact, SourceRef, UnknownFact } from "../types.ts";
+import { descriptionDiagnostics } from "./route-description.ts";
+import { readStaticObject, refOf, type StaticField } from "./static-read.ts";
+
+const MISSING_PERMISSION = "permission is missing";
+const MISSING_TABLES = "dbTables is missing; declare an array ([] means no DB)";
+
+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[];
+}
+
+function stringArrayValue(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((item): item is string => typeof item === "string") ? [...value] : null;
+}
+
+function permissionValue(value: unknown): string[] | null {
+  return typeof value === "string" ? [value] : stringArrayValue(value);
+}
+
+function addUnknown(list: UnknownFact[], code: string, reason: string, source: SourceRef): void {
+  list.push({ code, reason, source });
+}
+
+function unreadable(field: string, entry: StaticField): string {
+  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: ModuleGraph,
+  file: ProjectFile,
+  call: AstNode,
+  config: ConfigFacts,
+): RouteConfigFacts {
+  const context: StaticContext = { 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: UnknownFact[] = [...object.unknown];
+  const field = (name: string): StaticField | undefined => object.fields.get(name);
+
+  const permissionField = field("permission");
+  let permission: string[] | null = 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: boolean | null = 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: boolean | null = 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: string[] | null = 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: string[] | null = 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: string | null = 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: RouteInputFact = {
+    body: field("body") !== undefined,
+    form: field("form") !== undefined,
+    query: field("query") !== undefined,
+    params: field("params") !== undefined,
+  };
+
+  const diagnostics: Diagnostic[] = [
+    ...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/src/passes/route-description.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.ts";
+import type { Diagnostic, SourceRef } from "../types.ts";
+
+/** 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: string | null,
+  source: SourceRef | null,
+): readonly Diagnostic[] {
+  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/src/passes/route-elevation.ts

@@ -0,0 +1,161 @@
+/**
+ * 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,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { ElevationFact, ElevationKind, SourceRef, UnknownFact } from "../types.ts";
+import { readStaticObject } from "./static-read.ts";
+
+export interface ElevationScan {
+  readonly facts: readonly ElevationFact[];
+  readonly unknown: readonly UnknownFact[];
+}
+
+function refOf(file: ProjectFile, node: AstNode): SourceRef {
+  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: string | undefined): ElevationKind | null {
+  if (name === "sudo" || name === "system") return name;
+  return null;
+}
+
+interface HandlerBindings {
+  readonly locals: ReadonlyMap<string, ElevationKind>;
+  readonly contextName: string | null;
+}
+
+/** Local identifier -> elevation kind for `{ sudo }` / `{ sudo: elevate }`. */
+function handlerBindings(handler: AstNode): HandlerBindings {
+  const locals = new Map<string, ElevationKind>();
+  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: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((entry): entry is string => typeof entry === "string") ? [...value] : null;
+}
+
+/** Scan one `defineAuthorizedHandler` call's handler for audited elevations. */
+export function scanElevations(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  wrapperCall: AstNode,
+): ElevationScan {
+  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: ElevationFact[] = [];
+  const unknown: UnknownFact[] = [];
+  walk(handlerNode, (node) => {
+    if (node.type !== "CallExpression") return;
+    const callee = unwrapExpression(node.callee);
+    if (callee === undefined) return;
+    let kind: ElevationKind | null = 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: UnknownFact[] = [...options.unknown];
+    const tablesField = options.fields.get("tables");
+    let tables: string[] = [];
+    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 };
+}