@facilis.dev/analyze 0.0.0-stage → 0.1.0

package/src/passes/config.ts

@@ -0,0 +1,278 @@
+/**
+ * `facilis.config.ts` -> ConfigFacts (docs/findings/ast-dsl-contract.md §3.2).
+ *
+ * The config is the project's security contract, so a value outside the static subset is an
+ * explicit unknown plus a diagnostic, never a silent default. Defaults mirror
+ * packages/core/src/config.ts exactly: the runtime and the analyzer must agree on what
+ * "absent" means, and only the analyzer may report a wrong value instead of throwing.
+ */
+
+import { callArguments, identifierName, unwrapExpression, type AstNode } from "../ast/node.ts";
+import { error } from "../diagnostics.ts";
+import { defaultExportDeclaration } from "../module-info.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { StaticContext } from "../static-eval.ts";
+import type { ConfigFacts, Diagnostic, SourceRef, UnknownFact } from "../types.ts";
+import {
+  defaultExportExpression,
+  isLocallyDeclared,
+  isRecord,
+  projectPath,
+  readStaticObject,
+  refOf,
+  sortDiagnostics,
+  type StaticObject,
+} from "./static-read.ts";
+
+const CONFIG_FILE = "facilis.config.ts";
+const CORE_SPECIFIER = "@facilis.dev/core";
+// Mirrors packages/core/src/config.ts. The analyzer is browser-safe and must not import the
+// server package, so the defaults are restated here and covered by a test.
+const DEFAULT_MIGRATIONS_DIR = "./drizzle";
+const DEFAULT_TENANT_COLUMNS = ["tenantId"];
+const DEFAULT_OWNER_COLUMNS = ["ownerId"];
+const DEFAULT_LOCALE = "en";
+const DEFAULT_LOCALES = ["en"];
+
+export interface ConfigResult {
+  readonly facts: ConfigFacts;
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function configDefaults(): ConfigFacts {
+  return {
+    parsed: false,
+    source: null,
+    permissions: [],
+    roles: {},
+    defaultRole: null,
+    defaultLocale: DEFAULT_LOCALE,
+    locales: [...DEFAULT_LOCALES],
+    migrationsDir: DEFAULT_MIGRATIONS_DIR,
+    tenantColumns: [...DEFAULT_TENANT_COLUMNS],
+    ownerColumns: [...DEFAULT_OWNER_COLUMNS],
+    unknown: [],
+  };
+}
+
+export function emptyConfigFacts(): ConfigFacts {
+  return configDefaults();
+}
+
+function stringField(
+  section: Record<string, unknown>,
+  key: string,
+  fallback: string | null,
+  unknown: UnknownFact[],
+  at: SourceRef,
+): string | null {
+  if (!Object.hasOwn(section, key)) return fallback;
+  if (typeof section[key] === "string") return section[key];
+  unknown.push({ code: "config-static", reason: key + " must be a string", source: at });
+  return fallback;
+}
+
+function stringArrayField(
+  section: Record<string, unknown>,
+  key: string,
+  fallback: readonly string[],
+  unknown: UnknownFact[],
+  at: SourceRef,
+): readonly string[] {
+  if (!Object.hasOwn(section, key)) return fallback;
+  const value = section[key];
+  if (Array.isArray(value) && value.every((item): item is string => typeof item === "string")) {
+    return [...value];
+  }
+  unknown.push({ code: "config-static", reason: key + " must be a string[]", source: at });
+  return fallback;
+}
+
+function rolesField(
+  section: Record<string, unknown>,
+  unknown: UnknownFact[],
+  at: SourceRef,
+): Readonly<Record<string, readonly string[]>> {
+  if (!Object.hasOwn(section, "roles")) return {};
+  const value = section.roles;
+  if (!isRecord(value)) {
+    unknown.push({ code: "config-static", reason: "roles must be an object", source: at });
+    return {};
+  }
+  const roles: Record<string, readonly string[]> = {};
+  for (const [role, permissions] of Object.entries(value)) {
+    if (Array.isArray(permissions) && permissions.every((item) => typeof item === "string")) {
+      roles[role] = [...(permissions as string[])];
+    } else {
+      unknown.push({
+        code: "config-static",
+        reason: 'roles["' + role + '"] must be a string[]',
+        source: at,
+      });
+    }
+  }
+  return roles;
+}
+
+function readSection(
+  root: StaticObject,
+  name: string,
+  context: StaticContext,
+  unknown: UnknownFact[],
+): Record<string, unknown> | null {
+  const field = root.fields.get(name);
+  if (field === undefined) return null;
+  if (field.ok && isRecord(field.value)) return field.value;
+  const nested = readStaticObject(field.node, context, { code: "config-static", report: true });
+  unknown.push(...nested.unknown);
+  if (field.ok && nested.fields.size === 0) {
+    unknown.push({
+      code: "config-static",
+      reason: name + " must be an object",
+      source: refOf(context, field.node),
+    });
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of nested.fields) if (value.ok) out[key] = value.value;
+  return out;
+}
+
+/** The default export must be a `defineConfig(...)` call of the @facilis.dev/core named import. */
+function resolveDefineConfig(file: ProjectFile): { call: AstNode | null; reason: string | null } {
+  const expression = defaultExportExpression(file);
+  if (expression === undefined) {
+    return { call: null, reason: "facilis.config.ts has no default export" };
+  }
+  if (expression.type !== "CallExpression") {
+    return { call: null, reason: "the default export is not a defineConfig() call" };
+  }
+  const callee = unwrapExpression(expression.callee);
+  const name = callee?.type === "Identifier" ? identifierName(callee) : undefined;
+  if (name === undefined) return { call: null, reason: "defineConfig must be called by name" };
+  if (isLocallyDeclared(file, name)) {
+    return { call: null, reason: 'defineConfig "' + name + '" is shadowed by a local declaration' };
+  }
+  const imported = file.module.imports.find((entry) => entry.local === name);
+  if (imported === undefined) {
+    return { call: null, reason: "defineConfig is not imported from @facilis.dev/core" };
+  }
+  if (imported.specifier !== CORE_SPECIFIER || imported.imported !== "defineConfig") {
+    return { call: null, reason: "defineConfig must be the named import from @facilis.dev/core" };
+  }
+  return { call: expression, reason: null };
+}
+
+function validationIssues(
+  facts: ConfigFacts,
+  authMissing: boolean,
+): {
+  auth: string[];
+  i18n: string[];
+} {
+  const auth: string[] = [];
+  if (authMissing) auth.push("auth is required in facilis.config.ts");
+  if (facts.permissions.includes("*")) auth.push('"*" is only valid inside auth.roles');
+  const seenPermissions = new Set<string>();
+  for (const permission of facts.permissions) {
+    if (seenPermissions.has(permission)) auth.push('duplicate permission "' + permission + '"');
+    seenPermissions.add(permission);
+  }
+  for (const [role, permissions] of Object.entries(facts.roles)) {
+    const seen = new Set<string>();
+    for (const permission of permissions) {
+      if (permission !== "*" && !seenPermissions.has(permission)) {
+        auth.push('role "' + role + '" references undeclared permission "' + permission + '"');
+      }
+      if (seen.has(permission)) auth.push('role "' + role + '" repeats "' + permission + '"');
+      seen.add(permission);
+    }
+  }
+  if (facts.defaultRole === null) {
+    if (!authMissing) auth.push("auth.defaultRole is required");
+  } else if (!Object.hasOwn(facts.roles, facts.defaultRole)) {
+    auth.push('defaultRole "' + facts.defaultRole + '" is not a key of auth.roles');
+  }
+  const i18n: string[] = [];
+  if (!facts.locales.includes(facts.defaultLocale ?? "")) {
+    i18n.push('defaultLocale "' + (facts.defaultLocale ?? "") + '" must be listed in i18n.locales');
+  }
+  return { auth, i18n };
+}
+
+export function buildConfigFacts(graph: ModuleGraph): ConfigResult {
+  const file = graph.file(projectPath(graph.root, CONFIG_FILE));
+  if (file === undefined) {
+    return {
+      facts: emptyConfigFacts(),
+      diagnostics: [
+        error(
+          "config-missing",
+          CONFIG_FILE + " was not found; the project config is required",
+          null,
+        ),
+      ],
+    };
+  }
+  const context: StaticContext = { graph, file: file.path };
+  const at = sourceRef(file.path, file.source, defaultExportDeclaration(file.program)?.start ?? 0);
+  const resolved = resolveDefineConfig(file);
+  if (resolved.call === null) {
+    const reason = resolved.reason ?? "defineConfig() could not be resolved";
+    return {
+      facts: {
+        ...configDefaults(),
+        source: at,
+        unknown: [{ code: "config-static", reason, source: at }],
+      },
+      diagnostics: [error("config-static", reason, at)],
+    };
+  }
+
+  const root = readStaticObject(callArguments(resolved.call)[0], context, {
+    code: "config-static",
+    report: false,
+  });
+  const unknown: UnknownFact[] = [...root.unknown];
+  const auth = readSection(root, "auth", context, unknown);
+  const i18n = readSection(root, "i18n", context, unknown);
+  const db = readSection(root, "db", context, unknown);
+  const authRef = refOf(context, root.fields.get("auth")?.node);
+  const i18nRef = refOf(context, root.fields.get("i18n")?.node);
+  const base = configDefaults();
+  const facts: ConfigFacts = {
+    parsed: true,
+    source: at,
+    permissions: auth === null ? [] : stringArrayField(auth, "permissions", [], unknown, authRef),
+    roles: auth === null ? {} : rolesField(auth, unknown, authRef),
+    defaultRole: auth === null ? null : stringField(auth, "defaultRole", null, unknown, authRef),
+    defaultLocale:
+      i18n === null
+        ? base.defaultLocale
+        : stringField(i18n, "defaultLocale", base.defaultLocale, unknown, i18nRef),
+    locales:
+      i18n === null
+        ? base.locales
+        : stringArrayField(i18n, "locales", base.locales, unknown, i18nRef),
+    migrationsDir:
+      db === null
+        ? base.migrationsDir
+        : (stringField(db, "migrationsDir", base.migrationsDir, unknown, at) ?? base.migrationsDir),
+    tenantColumns:
+      db === null
+        ? base.tenantColumns
+        : stringArrayField(db, "tenantColumns", base.tenantColumns, unknown, at),
+    ownerColumns:
+      db === null
+        ? base.ownerColumns
+        : stringArrayField(db, "ownerColumns", base.ownerColumns, unknown, at),
+    unknown,
+  };
+  const issues = validationIssues(facts, auth === null);
+  const diagnostics = [
+    ...unknown.map((fact) => error(fact.code, fact.reason, fact.source)),
+    ...issues.auth.map((message) => error("config-invalid", message, authRef)),
+    ...issues.i18n.map((message) => error("config-invalid", message, i18nRef)),
+  ];
+  return { facts, diagnostics: sortDiagnostics(diagnostics) };
+}

package/src/passes/file-facts.ts

@@ -0,0 +1,142 @@
+/**
+ * Per-file module facts: imports, re-exports, dynamic imports/requires and literal `t()`
+ * keys (docs/findings/ast-dsl-contract.md §3.6).
+ *
+ * These are the AST replacement for the patch validator's tolerant text scans: the rules
+ * need the module graph edges and the translation keys of a source file, and they must be
+ * readable without executing the project. The parser produced the structure; this pass only
+ * reads it, so a construct outside the static subset is simply absent rather than guessed.
+ */
+
+import { identifierName, literalString, nodeArray, type AstNode } from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { CallFact, FileFacts, ImportFact, SourceRef, TranslationCallFact } from "../types.ts";
+
+function refOf(file: ProjectFile, node: AstNode): SourceRef {
+  const offset = typeof node.start === "number" ? node.start : 0;
+  return sourceRef(file.path, file.source, offset);
+}
+
+function push(
+  imports: ImportFact[],
+  specifier: string,
+  kind: ImportFact["kind"],
+  local: string | null,
+  imported: string | null,
+  source: SourceRef,
+): void {
+  imports.push({ specifier, kind, local, imported, source });
+}
+
+function declarationImports(file: ProjectFile): ImportFact[] {
+  const imports: ImportFact[] = [];
+  for (const statement of nodeArray(file.program, "body")) {
+    if (statement.type === "ImportDeclaration") {
+      const specifier = literalString(statement.source);
+      if (specifier === undefined) continue;
+      const source = refOf(file, statement);
+      const specifiers = nodeArray(statement, "specifiers");
+      if (specifiers.length === 0) {
+        push(imports, specifier, "side-effect", null, null, source);
+        continue;
+      }
+      for (const item of specifiers) {
+        const local = identifierName(item.local);
+        if (local === undefined) continue;
+        if (item.type === "ImportDefaultSpecifier") {
+          push(imports, specifier, "default", local, "default", source);
+        } else if (item.type === "ImportNamespaceSpecifier") {
+          push(imports, specifier, "namespace", local, null, source);
+        } else if (item.type === "ImportSpecifier") {
+          const imported = identifierName(item.imported) ?? literalString(item.imported);
+          if (imported !== undefined) push(imports, specifier, "named", local, imported, source);
+        }
+      }
+      continue;
+    }
+    if (
+      statement.type === "ExportAllDeclaration" ||
+      (statement.type === "ExportNamedDeclaration" && statement.source !== null)
+    ) {
+      const specifier = literalString(statement.source);
+      if (specifier !== undefined) {
+        push(imports, specifier, "export-from", null, null, refOf(file, statement));
+      }
+    }
+  }
+  return imports;
+}
+
+function expressionImports(file: ProjectFile): ImportFact[] {
+  const imports: ImportFact[] = [];
+  walk(file.program, (node) => {
+    if (node.type === "ImportExpression") {
+      const specifier = literalString(node.source);
+      if (specifier !== undefined)
+        push(imports, specifier, "dynamic", null, null, refOf(file, node));
+      return;
+    }
+    if (node.type === "CallExpression" && identifierName(node.callee) === "require") {
+      const specifier = literalString(nodeArray(node, "arguments")[0]);
+      if (specifier !== undefined)
+        push(imports, specifier, "require", null, null, refOf(file, node));
+    }
+  });
+  return imports;
+}
+
+function templateString(node: AstNode | undefined): string | undefined {
+  if (node === undefined || node.type !== "TemplateLiteral") return undefined;
+  const quasis = nodeArray(node, "quasis");
+  if (quasis.length !== 1) return undefined;
+  const value = quasis[0]?.value;
+  if (typeof value !== "object" || value === null) return undefined;
+  const cooked = (value as { cooked?: unknown }).cooked;
+  if (typeof cooked === "string") return cooked;
+  const raw = (value as { raw?: unknown }).raw;
+  return typeof raw === "string" ? raw : undefined;
+}
+
+function translationCalls(file: ProjectFile): TranslationCallFact[] {
+  const calls: TranslationCallFact[] = [];
+  walk(file.program, (node) => {
+    if (node.type !== "CallExpression" || identifierName(node.callee) !== "t") return;
+    const argument = nodeArray(node, "arguments")[0];
+    const key = literalString(argument) ?? templateString(argument);
+    if (key !== undefined) calls.push({ key, source: refOf(file, node) });
+  });
+  return calls;
+}
+
+function bareCalls(file: ProjectFile): CallFact[] {
+  const calls: CallFact[] = [];
+  walk(file.program, (node) => {
+    if (node.type !== "CallExpression") return;
+    const name = identifierName(node.callee);
+    if (name !== undefined) calls.push({ name, source: refOf(file, node) });
+  });
+  return calls;
+}
+
+function byPosition(left: ImportFact, right: ImportFact): number {
+  return (
+    left.source.line - right.source.line ||
+    left.specifier.localeCompare(right.specifier) ||
+    left.kind.localeCompare(right.kind)
+  );
+}
+
+/** Read the module facts of every parsed source file, in path order. */
+export function buildFileFacts(graph: ModuleGraph): readonly FileFacts[] {
+  const files = [...graph.files.values()].toSorted((left, right) =>
+    left.path.localeCompare(right.path),
+  );
+  return files.map((file) => ({
+    path: file.path,
+    imports: [...declarationImports(file), ...expressionImports(file)].toSorted(byPosition),
+    translationCalls: translationCalls(file),
+    calls: bareCalls(file),
+  }));
+}

package/src/passes/i18n.ts

@@ -0,0 +1,66 @@
+/**
+ * Locale catalogs: every `locales/*.json` in the file map (docs/findings/ast-dsl-contract.md
+ * §3.5). A missing `locales/` directory is fine (catalogs are optional); malformed JSON is a
+ * warning and the catalog is skipped, because i18n completeness is a gate concern but a broken
+ * file must never stop the rest of the analysis.
+ */
+
+import { warning } from "../diagnostics.ts";
+import type { ModuleGraph } from "../module-graph.ts";
+import type { Diagnostic, LocaleCatalogs } from "../types.ts";
+import { isRecord, relativePath, sortDiagnostics } from "./static-read.ts";
+
+const LOCALES_DIR = "locales/";
+const JSON_EXTENSION = ".json";
+
+export interface LocaleResult {
+  readonly locales: LocaleCatalogs;
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+function parseCatalog(source: string): Record<string, string> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source) as unknown;
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  const catalog: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value === "string") catalog[key] = value;
+  }
+  return catalog;
+}
+
+/** Read the locale JSON files from the project file map. */
+export function readLocaleCatalogs(graph: ModuleGraph): LocaleResult {
+  const files = [...graph.allFiles.entries()]
+    .filter(([path]) => {
+      const relative = relativePath(graph.root, path);
+      if (!relative.startsWith(LOCALES_DIR)) return false;
+      const name = relative.slice(LOCALES_DIR.length);
+      return (
+        !name.includes("/") && name.endsWith(JSON_EXTENSION) && name.length > JSON_EXTENSION.length
+      );
+    })
+    .toSorted(([left], [right]) => left.localeCompare(right));
+  const locales: Record<string, Readonly<Record<string, string>>> = {};
+  const diagnostics: Diagnostic[] = [];
+  for (const [path, source] of files) {
+    const relative = relativePath(graph.root, path);
+    const name = relative.slice(LOCALES_DIR.length, -JSON_EXTENSION.length);
+    const catalog = parseCatalog(source);
+    if (catalog === null) {
+      diagnostics.push(
+        warning("i18n-catalog", "locale catalog " + relative + " is not a JSON object", {
+          file: path,
+          line: 1,
+        }),
+      );
+      continue;
+    }
+    locales[name] = catalog;
+  }
+  return { locales, diagnostics: sortDiagnostics(diagnostics) };
+}

package/src/passes/job-relations-diagnostics.ts

@@ -0,0 +1,60 @@
+/**
+ * D-157 diagnostics for a job's static db usage. The rules mirror the route ones
+ * (`route-relations-diagnostics.ts`) with job codes; jobs have no elevation dimension, so the
+ * only suppression of the unused warning is an opaque helper or an allowed `db.execute`.
+ */
+
+import { error, warning } from "../diagnostics.ts";
+import type { Diagnostic } from "../types.ts";
+import type { JobFact, JobRelationsFact } from "../types-jobs.ts";
+
+function unusedSuppressed(usage: JobRelationsFact): boolean {
+  return usage.opaque || usage.rawSql.length > 0;
+}
+
+/** Every diagnostic the relation pass derives from one job's usage fact. */
+export function jobRelationDiagnostics(job: JobFact, usage: JobRelationsFact): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const declared = job.dbTables === null ? null : new Set(job.dbTables);
+  if (declared !== null) {
+    for (const use of usage.used) {
+      if (declared.has(use.name)) continue;
+      diagnostics.push(
+        error(
+          "job-table-undeclared",
+          'relation "' + use.name + '" is used through the job db but not declared in dbTables',
+          use.source,
+        ),
+      );
+    }
+  }
+  for (const source of usage.unresolved) {
+    diagnostics.push(
+      error(
+        "job-table-unresolved",
+        "a relation used through the job db cannot be resolved statically",
+        source,
+      ),
+    );
+  }
+  for (const source of usage.rawSql) {
+    if (job.rawSql === true) continue;
+    diagnostics.push(
+      error("job-raw-sql", "db.execute() requires rawSql: true on the job definition", source),
+    );
+  }
+  if (declared !== null && !unusedSuppressed(usage)) {
+    const used = new Set(usage.used.map((use) => use.name));
+    for (const name of job.dbTables ?? []) {
+      if (used.has(name)) continue;
+      diagnostics.push(
+        warning(
+          "job-table-unused",
+          'dbTables declares "' + name + '" but the job never uses it',
+          job.source,
+        ),
+      );
+    }
+  }
+  return diagnostics;
+}

package/src/passes/job-relations.ts

@@ -0,0 +1,76 @@
+/**
+ * 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, type AstNode } from "../ast/node.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { Diagnostic, TableFact, ViewFact } from "../types.ts";
+import type { JobFact, JobRelationsFact } from "../types-jobs.ts";
+import { EMPTY_JOB_RELATIONS } from "../types-jobs.ts";
+import { createRelationIndex } from "./route-relation-resolve.ts";
+import { scanFunctionUsage, type UsageSeed } from "./route-relations-walk.ts";
+import { jobRelationDiagnostics } from "./job-relations-diagnostics.ts";
+import { resolveJobCall } from "./jobs.ts";
+import { readStaticObject, sortDiagnostics } from "./static-read.ts";
+
+/** A job runs as `facilis_system`: `run`'s first parameter is the context, no elevations. */
+const JOB_SEED: UsageSeed = { contextParam: 0, elevations: false };
+
+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[];
+}
+
+/** The function expression of the definition's `run` property, when inspectable. */
+function runFunction(graph: ModuleGraph, file: ProjectFile, call: AstNode): AstNode | undefined {
+  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: ReturnType<typeof scanFunctionUsage>): JobRelationsFact {
+  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: ModuleGraph,
+  jobs: readonly JobFact[],
+  tables: readonly TableFact[],
+  views: readonly ViewFact[],
+): JobRelationsScan {
+  const index = createRelationIndex(tables, views);
+  const relations: Record<string, JobRelationsFact> = {};
+  const diagnostics: Diagnostic[] = [];
+  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) };
+}