@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/screens.ts

@@ -0,0 +1,291 @@
+/**
+ * Static screen facts for the project graph: route-table paths, a bounded component preview
+ * per page and explicit page-to-page navigation links.
+ *
+ * Only explicit client navigation counts (react-router `Link`, `NavLink`, `useNavigate`).
+ * Guards and `<Navigate>` redirects are intentionally out of scope for the graph: they are
+ * conditional control flow, not a link the page declares.
+ */
+
+import { asNode, nodeArray, unwrapExpression, type AstNode } from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { evaluateStatic } from "../static-eval.ts";
+import type { PageFact, PageLink, PagePreview, ScreenFacts } from "../types.ts";
+import { elementName, jsxAttribute, jsxAttributeValue } from "./jsx.ts";
+import { buildRouteTable, type RouteEntry } from "./route-table.ts";
+import { buildPagePreview, pageComponentName, type PreviewRoot } from "./screen-preview.ts";
+
+function resolvePage(graph: ModuleGraph, originFile: string, name: string): string | null {
+  const local = name.includes(".") ? name.slice(0, name.indexOf(".")) : name;
+  const binding = graph.resolveBinding(originFile, local);
+  if (binding === null) return null;
+  const file = graph.file(binding.file);
+  return file !== undefined && file.path.startsWith("src/pages/") ? file.path : null;
+}
+
+/** First component in a route element that resolves to a file under src/pages/. */
+function pagePathOfElement(
+  graph: ModuleGraph,
+  originFile: string,
+  element: AstNode,
+): string | null {
+  let found: string | null = null;
+  walk(element, (node) => {
+    if (found !== null || node.type !== "JSXElement") return;
+    const name = elementName(node);
+    if (name === null || name[0] === name[0]?.toLowerCase()) return;
+    found = resolvePage(graph, originFile, name);
+  });
+  return found;
+}
+
+function appFileOf(graph: ModuleGraph): ProjectFile | null {
+  const direct = graph.file("src/app.tsx");
+  if (direct !== undefined) return direct;
+  for (const file of graph.files.values()) {
+    if (!file.path.startsWith("src/")) continue;
+    if (buildRouteTable(graph, file).length > 0) return file;
+  }
+  return null;
+}
+
+/** Only page/layout/app components own page links; providers and guards are shared chrome. */
+function isLinkSourceFile(file: string): boolean {
+  if (file.startsWith("src/components/ui/")) return false;
+  return (
+    file.startsWith("src/pages/") ||
+    file.startsWith("src/layouts/") ||
+    file.startsWith("src/components/")
+  );
+}
+
+interface PageRoute {
+  readonly index: number;
+  readonly path: string;
+}
+
+function routesByPage(
+  graph: ModuleGraph,
+  appFile: ProjectFile,
+  entries: readonly RouteEntry[],
+): Map<string, PageRoute[]> {
+  const byPage = new Map<string, PageRoute[]>();
+  entries.forEach((entry, index) => {
+    if (entry.element === null) return;
+    const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+    if (pagePath === null) return;
+    const list = byPage.get(pagePath) ?? [];
+    list.push({ index, path: entry.path });
+    byPage.set(pagePath, list);
+  });
+  return byPage;
+}
+
+function previewRoot(
+  entries: readonly RouteEntry[],
+  pageEntry: number,
+  appPath: string,
+): PreviewRoot | null {
+  let root: PreviewRoot | null = null;
+  let current: number | null = pageEntry;
+  while (current !== null) {
+    const entry: RouteEntry | undefined = entries[current];
+    if (entry === undefined) break;
+    if (entry.element !== null) {
+      root = { element: entry.element, originFile: appPath, outletChild: root };
+    }
+    current = entry.parentIndex;
+  }
+  return root;
+}
+
+function pathSegments(path: string): string[] {
+  return path.split("/").filter(Boolean);
+}
+
+function pathMatches(pattern: string, target: string): boolean {
+  if (pattern === target) return true;
+  if (pattern === "*") return false;
+  const patternParts = pathSegments(pattern);
+  const targetParts = pathSegments(target);
+  if (patternParts.length !== targetParts.length) return false;
+  return patternParts.every((part, index) => {
+    if (part === "*") return true;
+    if (part.startsWith(":") || (part.startsWith("{") && part.endsWith("}"))) return true;
+    return part === targetParts[index];
+  });
+}
+
+function targetPathOf(
+  node: AstNode | undefined,
+  graph: ModuleGraph,
+  file: ProjectFile,
+): string | null {
+  if (node === undefined) return null;
+  const evaluated = evaluateStatic(node, { graph, file: file.path });
+  if (!evaluated.ok) return null;
+  const value = evaluated.value;
+  if (typeof value === "string") return value;
+  if (typeof value === "object" && value !== null && "pathname" in value) {
+    const pathname = (value as { pathname?: unknown }).pathname;
+    return typeof pathname === "string" ? pathname : null;
+  }
+  return null;
+}
+
+function stripLocation(path: string): string {
+  const cut = path.search(/[?#]/);
+  return cut === -1 ? path : path.slice(0, cut);
+}
+
+interface LinkBindings {
+  readonly links: ReadonlyMap<string, "link" | "navlink">;
+  readonly navigate: ReadonlySet<string>;
+}
+
+function linkBindings(file: ProjectFile): LinkBindings {
+  const links = new Map<string, "link" | "navlink">();
+  const useNavigate = new Set<string>();
+  for (const imported of file.module.imports) {
+    if (imported.specifier !== "react-router-dom") continue;
+    if (imported.imported === "Link") links.set(imported.local, "link");
+    if (imported.imported === "NavLink") links.set(imported.local, "navlink");
+    if (imported.imported === "useNavigate") useNavigate.add(imported.local);
+  }
+  const navigate = new Set<string>();
+  if (useNavigate.size === 0) return { links, navigate };
+  walk(file.program, (node) => {
+    if (node.type !== "VariableDeclarator") return;
+    const id = asNode(node.id);
+    const init = unwrapExpression(asNode(node.init));
+    if (id === undefined || typeof id.name !== "string" || init === undefined) return;
+    if (init.type !== "CallExpression") return;
+    const callee = unwrapExpression(init.callee);
+    if (
+      callee?.type === "Identifier" &&
+      useNavigate.has(typeof callee.name === "string" ? callee.name : "")
+    ) {
+      navigate.add(id.name);
+    }
+  });
+  return { links, navigate };
+}
+
+function linksInFile(
+  graph: ModuleGraph,
+  file: ProjectFile,
+): { to: string; kind: "link" | "navlink" | "navigate"; source: { file: string; line: number } }[] {
+  const bindings = linkBindings(file);
+  if (bindings.links.size === 0 && bindings.navigate.size === 0) return [];
+  const found: {
+    to: string;
+    kind: "link" | "navlink" | "navigate";
+    source: { file: string; line: number };
+  }[] = [];
+  walk(file.program, (node) => {
+    if (node.type === "JSXElement") {
+      const name = elementName(node);
+      const kind = name === null ? undefined : bindings.links.get(name);
+      if (kind === undefined) return;
+      const value = jsxAttributeValue(jsxAttribute(node, "to"));
+      const to = targetPathOf(value, graph, file);
+      if (to !== null) {
+        found.push({ to, kind, source: lineOf(file, node) });
+      }
+      return;
+    }
+    if (node.type !== "CallExpression") return;
+    const callee = unwrapExpression(node.callee);
+    if (callee?.type !== "Identifier" || typeof callee.name !== "string") return;
+    if (!bindings.navigate.has(callee.name)) return;
+    const to = targetPathOf(nodeArray(node, "arguments")[0], graph, file);
+    if (to !== null) found.push({ to, kind: "navigate", source: lineOf(file, node) });
+  });
+  return found;
+}
+
+function lineOf(file: ProjectFile, node: AstNode): { file: string; line: number } {
+  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 };
+}
+
+/** Build route paths, page previews and explicit page links from the project snapshot. */
+export function buildScreens(graph: ModuleGraph, pages: readonly PageFact[]): ScreenFacts {
+  const appFile = appFileOf(graph);
+  const entries = appFile === null ? [] : buildRouteTable(graph, appFile);
+  const byPage =
+    appFile === null ? new Map<string, PageRoute[]>() : routesByPage(graph, appFile, entries);
+  const pathToPage = new Map<string, string>();
+  for (const entry of entries) {
+    if (entry.element === null || appFile === null) continue;
+    const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+    if (pagePath !== null && !pathToPage.has(entry.path)) pathToPage.set(entry.path, pagePath);
+  }
+  const resolveTarget = (target: string): string | null => {
+    const path = stripLocation(target);
+    if (!path.startsWith("/") && path !== "*") return null;
+    const exact = pathToPage.get(path);
+    if (exact !== undefined) return exact;
+    for (const entry of entries) {
+      if (!pathMatches(entry.path, path)) continue;
+      if (entry.element === null || appFile === null) continue;
+      const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+      if (pagePath !== null) return pagePath;
+    }
+    return null;
+  };
+
+  const previews: Record<string, PagePreview> = {};
+  for (const page of pages) {
+    if (page.kind !== "page") continue;
+    const pageRoutes = byPage.get(page.path) ?? [];
+    const first = pageRoutes[0];
+    const root =
+      appFile === null || first === undefined
+        ? null
+        : previewRoot(entries, first.index, appFile.path);
+    previews[page.path] = buildPagePreview({
+      graph,
+      pagePath: page.path,
+      root,
+      pageName: root === null ? pageComponentName(graph, page.path) : null,
+      routePaths: pageRoutes.map((entry) => entry.path),
+    });
+  }
+
+  const links: PageLink[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    if (page.kind !== "page") continue;
+    const preview = previews[page.path];
+    const files = new Set<string>([page.path]);
+    for (const node of preview?.nodes ?? []) {
+      if (node.file !== null && isLinkSourceFile(node.file)) files.add(node.file);
+    }
+    for (const filePath of files) {
+      const file = graph.file(filePath);
+      if (file === undefined) continue;
+      for (const link of linksInFile(graph, file)) {
+        const target = resolveTarget(link.to);
+        if (target === null || target === page.path) continue;
+        const key = page.path + "\u0000" + target + "\u0000" + link.kind + "\u0000" + link.to;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        links.push({
+          from: page.path,
+          to: target,
+          toPath: stripLocation(link.to),
+          kind: link.kind,
+          source: link.source,
+        });
+      }
+    }
+  }
+
+  return { previews, links };
+}

package/src/passes/static-read.ts

@@ -0,0 +1,196 @@
+/**
+ * Helpers shared by the analyzer passes: the static object reader (§4 of the AST DSL
+ * contract) and deterministic diagnostic ordering.
+ *
+ * The reader is deliberately partial: every property is evaluated on its own so one computed
+ * value cannot hide its siblings. It never executes project code and it never defaults an
+ * unreadable value - the caller decides whether the unknown is a security error.
+ */
+
+import {
+  identifierName,
+  objectEntries,
+  propertyName,
+  propertyValue,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { declarationNames, defaultExportDeclaration, localInitializer } from "../module-info.ts";
+import type { ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import { evaluateStatic, type StaticContext } from "../static-eval.ts";
+import type { Diagnostic, SourceRef, UnknownFact } from "../types.ts";
+
+export interface StaticField {
+  readonly value: unknown;
+  readonly ok: boolean;
+  readonly node: AstNode | undefined;
+  /** Why the value is not static; null when ok. */
+  readonly reason: string | null;
+}
+
+export interface StaticObject {
+  readonly fields: ReadonlyMap<string, StaticField>;
+  readonly unknown: readonly UnknownFact[];
+}
+
+export interface StaticReadOptions {
+  /** Diagnostic/unknown code recorded for constructs outside the static subset. */
+  readonly code: string;
+  /** Whether a field that fails to evaluate is reported (sections re-read for detail). */
+  readonly report: boolean;
+}
+
+const MAX_RESOLVE_DEPTH = 8;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function projectPath(root: string, path: string): string {
+  return root.length === 0 ? path : root + "/" + path;
+}
+
+/** Project-relative path with the graph root stripped (the opposite of projectPath). */
+export function relativePath(root: string, path: string): string {
+  return root.length === 0 || !path.startsWith(root + "/") ? path : path.slice(root.length + 1);
+}
+
+export function refOf(context: StaticContext, node: AstNode | undefined): SourceRef {
+  const file = context.graph.file(context.file);
+  const offset = node !== undefined && typeof node.start === "number" ? node.start : 0;
+  return sourceRef(context.file, file?.source ?? "", offset);
+}
+
+function objectLiteral(
+  node: AstNode | undefined,
+  context: StaticContext,
+  depth = 0,
+): AstNode | undefined {
+  if (node === undefined || depth > MAX_RESOLVE_DEPTH) return undefined;
+  const unwrapped = unwrapExpression(node);
+  if (unwrapped === undefined) return undefined;
+  if (unwrapped.type === "ObjectExpression") return unwrapped;
+  const file = context.graph.file(context.file);
+  const name = identifierName(unwrapped);
+  if (file === undefined || name === undefined) return undefined;
+  return objectLiteral(localInitializer(file.program, name), context, depth + 1);
+}
+
+/** Partial, non-executing reader for object literals in the static subset. */
+export function readStaticObject(
+  node: AstNode | undefined,
+  context: StaticContext,
+  options: StaticReadOptions,
+): StaticObject {
+  const fields = new Map<string, StaticField>();
+  const unknown: UnknownFact[] = [];
+  if (node === undefined) return { fields, unknown };
+  const record = (reason: string, at: AstNode | undefined, structural: boolean): void => {
+    if (structural || options.report) {
+      unknown.push({ code: options.code, reason, source: refOf(context, at) });
+    }
+  };
+
+  const literal = objectLiteral(node, context);
+  if (literal !== undefined) {
+    for (const entry of objectEntries(literal)) {
+      if (entry.type === "SpreadElement") {
+        record("spread in an object literal cannot be read statically", entry, true);
+        continue;
+      }
+      const key = propertyName(entry);
+      if (key === undefined) {
+        record("computed object key cannot be read statically", entry, true);
+        continue;
+      }
+      const valueNode = propertyValue(entry);
+      const evaluated = evaluateStatic(valueNode, context);
+      if (evaluated.ok) {
+        fields.set(key, { value: evaluated.value, ok: true, node: valueNode, reason: null });
+      } else {
+        fields.set(key, { value: undefined, ok: false, node: valueNode, reason: evaluated.reason });
+        record(evaluated.reason, valueNode ?? entry, false);
+      }
+    }
+    return { fields, unknown };
+  }
+
+  const evaluated = evaluateStatic(node, context);
+  if (evaluated.ok && isRecord(evaluated.value)) {
+    for (const [key, value] of Object.entries(evaluated.value)) {
+      fields.set(key, { value, ok: true, node: undefined, reason: null });
+    }
+    return { fields, unknown };
+  }
+  record(evaluated.ok ? "value is not an object" : evaluated.reason, node, true);
+  return { fields, unknown };
+}
+
+/**
+ * The default export, unwrapped and resolved through a same-file const or a
+ * `export { handler as default }` statement.
+ */
+export function defaultExportExpression(file: ProjectFile): AstNode | undefined {
+  const declaration = defaultExportDeclaration(file.program);
+  if (declaration !== undefined) {
+    const unwrapped = unwrapExpression(declaration);
+    const name = unwrapped?.type === "Identifier" ? identifierName(unwrapped) : undefined;
+    return name === undefined ? unwrapped : unwrapExpression(localInitializer(file.program, name));
+  }
+  const entry = file.module.exports.find(
+    (item) => item.exported === "default" && item.local !== null,
+  );
+  if (entry === undefined || entry.local === null) return undefined;
+  return unwrapExpression(localInitializer(file.program, entry.local));
+}
+
+/** A top-level function/class declaration by name (localInitializer covers variables only). */
+export function findDeclaration(program: AstNode, name: string): AstNode | undefined {
+  for (const raw of Array.isArray(program.body) ? program.body : []) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const statement = raw as AstNode;
+    const declaration =
+      statement.type === "ExportNamedDeclaration" &&
+      statement.declaration !== null &&
+      typeof statement.declaration === "object"
+        ? (statement.declaration as AstNode)
+        : statement;
+    if (
+      (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") &&
+      identifierName(declaration.id) === name
+    ) {
+      return declaration;
+    }
+  }
+  return undefined;
+}
+
+/** True when the module declares the name itself: a local shadow invalidates an import. */
+export function isLocallyDeclared(file: ProjectFile, name: string): boolean {
+  const body = Array.isArray(file.program.body) ? file.program.body : [];
+  for (const raw of body) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const statement = raw as AstNode;
+    const declaration =
+      statement.type === "ExportNamedDeclaration" &&
+      statement.declaration !== null &&
+      typeof statement.declaration === "object"
+        ? (statement.declaration as AstNode)
+        : statement;
+    if (declarationNames(declaration).includes(name)) return true;
+  }
+  return false;
+}
+
+/** Stable diagnostic order (file, line, code, message) so snapshots never flap. */
+export function sortDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[] {
+  return [...diagnostics].toSorted((left, right) => {
+    const fileOrder = (left.source?.file ?? "").localeCompare(right.source?.file ?? "");
+    if (fileOrder !== 0) return fileOrder;
+    const lineOrder = (left.source?.line ?? 0) - (right.source?.line ?? 0);
+    if (lineOrder !== 0) return lineOrder;
+    const codeOrder = left.code.localeCompare(right.code);
+    return codeOrder !== 0 ? codeOrder : left.message.localeCompare(right.message);
+  });
+}

package/src/passes/views.ts

@@ -0,0 +1,125 @@
+/**
+ * `db/views/**` -> ViewFacts (D-157, SPEC §11.2).
+ *
+ * A view is declared one per file with `defineView({ name, columns, query, tables?,
+ * permission? })` from @facilis.dev/db (D-097/D-098). The route-relations pass resolves a view
+ * object used in `from(...)` to this fact, so a route declares the view's SQL name in
+ * `dbTables` instead of its base tables. D-160 adds the view nodes and their edges to the
+ * project graph; this pass stays facts-only.
+ *
+ * The declaration is read through the bounded static subset; an unreadable name/tables/
+ * permission is an explicit unknown, never a guessed value.
+ */
+
+import { callArguments, identifierName, unwrapExpression, type AstNode } from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { Diagnostic, UnknownFact, ViewFact } from "../types.ts";
+import {
+  createDslResolver,
+  isViewFile,
+  nodeRef,
+  schemaDiagnostics,
+  topLevelDeclarators,
+  type DslResolver,
+} from "./schema-dsl.ts";
+import { readStaticObject } from "./static-read.ts";
+
+export interface ViewScan {
+  readonly views: readonly ViewFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function viewUnknown(reason: string, source: ViewFact["source"]): UnknownFact {
+  return { code: "view-static", reason, source };
+}
+
+function stringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((entry): entry is string => typeof entry === "string") ? [...value] : null;
+}
+
+/** The `defineView(...)` call an initializer holds, when it is the @facilis.dev/db DSL. */
+function viewCall(init: unknown, resolver: DslResolver): AstNode | null {
+  const expression = unwrapExpression(init);
+  if (expression?.type !== "CallExpression") return null;
+  const symbol = resolver(expression.callee);
+  return symbol?.pkg === "facilis-db" && symbol.name === "defineView" ? expression : null;
+}
+
+function buildViewDraft(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  declarator: AstNode,
+  call: AstNode,
+): { view: ViewFact; diagnostics: readonly Diagnostic[] } {
+  const source = nodeRef(file, call);
+  const binding = identifierName(declarator.id) ?? null;
+  const unknowns: UnknownFact[] = [];
+  const options = readStaticObject(
+    callArguments(call)[0],
+    { graph, file: file.path },
+    { code: "view-static", report: false },
+  );
+  unknowns.push(...options.unknown);
+
+  const nameField = options.fields.get("name");
+  let name = binding ?? "unknown";
+  if (nameField !== undefined && nameField.ok && typeof nameField.value === "string") {
+    if (nameField.value.length > 0) name = nameField.value;
+    else unknowns.push(viewUnknown("view name is not a static string", source));
+  } else if (nameField !== undefined && !nameField.ok) {
+    unknowns.push(viewUnknown("view name is missing or not statically readable", source));
+  } else {
+    unknowns.push(viewUnknown("view name is missing or not a static string", source));
+  }
+
+  let tables: string[] = [];
+  const tablesField = options.fields.get("tables");
+  if (tablesField !== undefined) {
+    const read = tablesField.ok ? stringArray(tablesField.value) : null;
+    if (read === null) {
+      unknowns.push(viewUnknown("view tables are not a static string[]", source));
+    } else {
+      tables = read;
+    }
+  }
+
+  const permissionField = options.fields.get("permission");
+  let permission: string | null = null;
+  let access: ViewFact["access"] = "invoker";
+  if (permissionField !== undefined) {
+    if (permissionField.ok && typeof permissionField.value === "string") {
+      permission = permissionField.value;
+      access = "definer";
+    } else {
+      // We cannot tell an invoker declaration from a definer one: keep the mode unknown.
+      access = null;
+      unknowns.push(viewUnknown("view permission is not a static string", source));
+    }
+  }
+
+  return {
+    view: { name, binding, tables, permission, access, source, unknown: unknowns },
+    diagnostics: schemaDiagnostics(unknowns),
+  };
+}
+
+/** Read `db/views/**` into view facts. */
+export function buildViewFacts(graph: ModuleGraph): ViewScan {
+  const files = [...graph.files.values()]
+    .filter((file) => isViewFile(graph, file.path))
+    .toSorted((left, right) => left.path.localeCompare(right.path));
+  const views: ViewFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const file of files) {
+    const resolver = createDslResolver(graph, file);
+    for (const declarator of topLevelDeclarators(file.program)) {
+      const call = viewCall(declarator.init, resolver);
+      if (call === null) continue;
+      const draft = buildViewDraft(graph, file, declarator, call);
+      views.push(draft.view);
+      diagnostics.push(...draft.diagnostics);
+    }
+  }
+  return { views, diagnostics };
+}

package/src/passes/workflow-tables.ts

@@ -0,0 +1,87 @@
+/**
+ * Workflow table surface, derived from the jobs its steps reference (user decision: derived,
+ * never declared). A workflow declares no tables of its own: the union of the referenced jobs'
+ * `dbTables` is what the workflow can reach, and the runtime inherits each job's guard.
+ *
+ * Approval steps contribute nothing. A referenced job with an unreadable `dbTables` makes the
+ * union explicitly unknown; a referenced job with no definition keeps its name visible in
+ * `unknownJobs` and is a warning, never a silent hole.
+ */
+
+import { warning } from "../diagnostics.ts";
+import type { Diagnostic, SourceRef, WorkflowFact } from "../types.ts";
+import type { JobFact } from "../types-jobs.ts";
+import type { WorkflowTablesFact } from "../types-workflows.ts";
+import { sortDiagnostics } from "./static-read.ts";
+
+export interface WorkflowTablesResult {
+  readonly facts: readonly WorkflowTablesFact[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+/** One job definition per name; the manifest enforces uniqueness, first wins here. */
+function jobRegistry(jobs: readonly JobFact[]): Map<string, JobFact> {
+  const byName = new Map<string, JobFact>();
+  for (const job of jobs) {
+    if (!byName.has(job.name)) byName.set(job.name, job);
+  }
+  return byName;
+}
+
+/** Derive every workflow's table surface from its job steps. */
+export function buildWorkflowTableFacts(
+  workflows: readonly WorkflowFact[],
+  jobs: readonly JobFact[],
+): WorkflowTablesResult {
+  const registry = jobRegistry(jobs);
+  const facts: WorkflowTablesFact[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const workflow of workflows) {
+    const tables = new Set<string>();
+    const unknownJobs = new Set<string>();
+    const missingAt = new Map<string, SourceRef>();
+    let unknown = false;
+    for (const step of workflow.steps) {
+      if (step.kind !== "job") continue;
+      // A job step whose name is unreadable is already a workflow-definition unknown, but the
+      // derived surface must not pretend it is complete.
+      if (step.name === null) {
+        unknown = true;
+        continue;
+      }
+      const job = registry.get(step.name);
+      if (job === undefined) {
+        unknownJobs.add(step.name);
+        if (!missingAt.has(step.name)) missingAt.set(step.name, step.source);
+        continue;
+      }
+      if (job.dbTables === null) {
+        unknown = true;
+        continue;
+      }
+      for (const table of job.dbTables) tables.add(table);
+    }
+    for (const name of [...unknownJobs].toSorted()) {
+      diagnostics.push(
+        warning(
+          "workflow-job-unknown",
+          'workflow "' +
+            workflow.name +
+            '" references job "' +
+            name +
+            '" but no definition exists in server/jobs',
+          missingAt.get(name) ?? workflow.source,
+        ),
+      );
+    }
+    facts.push({
+      name: workflow.name,
+      sourceFile: workflow.sourceFile,
+      source: workflow.source,
+      tables: [...tables].toSorted(),
+      unknownJobs: [...unknownJobs].toSorted(),
+      unknown,
+    });
+  }
+  return { facts, diagnostics: sortDiagnostics(diagnostics) };
+}