@topogram/cli 0.3.63 → 0.3.65

package/src/workflows/import-app/shared.js

@@ -0,0 +1,218 @@
+// @ts-check
+import fs from "node:fs";
+import path from "node:path";
+
+import { relativeTo } from "../../path-helpers.js";
+import { canonicalCandidateTerm, idHintify } from "../../text-helpers.js";
+import { listFilesRecursive } from "../shared.js";
+
+export const IMPORT_TRACKS = new Set(["db", "api", "ui", "workflows", "verification"]);
+export const SCALAR_FIELD_TYPES = new Set([
+  "bigint",
+  "boolean",
+  "bytes",
+  "datetime",
+  "decimal",
+  "float",
+  "int",
+  "json",
+  "string",
+  "text",
+  "uuid"
+]);
+
+/** @param {any} fromValue @returns {any} */
+export function parseImportTracks(fromValue) {
+  if (!fromValue) {
+    return ["db", "api"];
+  }
+  const tracks = String(fromValue)
+    .split(",")
+    .map((/** @type {any} */ track) => track.trim().toLowerCase())
+    .filter(Boolean);
+  if (tracks.length === 0) {
+    throw new Error("Expected --from to include at least one import track");
+  }
+  const invalid = tracks.filter((/** @type {any} */ track) => !IMPORT_TRACKS.has(track));
+  if (invalid.length > 0) {
+    throw new Error(`Unsupported import track(s): ${invalid.join(", ")}`);
+  }
+  return [...new Set(tracks)];
+}
+
+/** @param {WorkspacePaths} paths @returns {any} */
+export function importSearchRoots(paths) {
+  return [...new Set([paths.workspaceRoot, paths.topogramRoot].filter(Boolean))];
+}
+
+/** @param {WorkspacePaths} paths @param {string} filePath @returns {any} */
+export function normalizeImportRelativePath(paths, filePath) {
+  return relativeTo(paths.repoRoot, filePath);
+}
+
+/** @param {WorkspacePaths} paths @param {string} filePath @param {string} kind @returns {any} */
+export function canonicalSourceRank(paths, filePath, kind) {
+  const relativePath = normalizeImportRelativePath(paths, filePath);
+  const normalizedPath = relativePath.replaceAll(path.sep, "/");
+  const penalties = [
+    { pattern: /\/apps\/local-stack\//, weight: 80 },
+    { pattern: /\/artifacts\/environment\//, weight: 60 },
+    { pattern: /\/artifacts\/deploy\//, weight: 60 },
+    { pattern: /\/artifacts\/compile-check\//, weight: 50 },
+    { pattern: /\/artifacts\/db-lifecycle\//, weight: 50 },
+    { pattern: /\/artifacts\/migrations\//, weight: 40 }
+  ];
+
+  let rank = 100;
+  if (kind === "prisma") {
+    if (/\/prisma\/schema\.prisma$/i.test(normalizedPath) && !normalizedPath.includes("/artifacts/")) {
+      rank = 0;
+    } else if (/\/apps\/backend\/prisma\/schema\.prisma$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/artifacts\/prisma\/schema\.prisma$/i.test(normalizedPath)) {
+      rank = 10;
+    }
+  } else if (kind === "sql") {
+    if (/\/db\/schema\.sql$/i.test(normalizedPath) || /\/schema\.sql$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/artifacts\/db\/.+\.sql$/i.test(normalizedPath)) {
+      rank = 10;
+    } else if (/migration/i.test(path.basename(normalizedPath))) {
+      rank = 30;
+    }
+  } else if (kind === "openapi") {
+    if (/\/artifacts\/openapi\/openapi\.(json|ya?ml)$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/openapi\.(json|ya?ml)$/i.test(normalizedPath) || /\/swagger\.(json|ya?ml)$/i.test(normalizedPath)) {
+      rank = 10;
+    }
+  }
+
+  for (const penalty of penalties) {
+    if (penalty.pattern.test(normalizedPath)) {
+      rank += penalty.weight;
+    }
+  }
+  return rank;
+}
+
+/** @param {WorkspacePaths} paths @param {any[]} files @param {string} kind @returns {any} */
+export function selectPreferredImportFiles(paths, files, kind) {
+  if (files.length === 0) {
+    return [];
+  }
+  const rankedFiles = files.map((/** @type {any} */ filePath) => ({
+    filePath,
+    rank: canonicalSourceRank(paths, filePath, kind)
+  }));
+  const bestRank = Math.min(...rankedFiles.map((/** @type {any} */ entry) => entry.rank));
+  return rankedFiles
+    .filter((/** @type {any} */ entry) => entry.rank === bestRank)
+    .map((/** @type {any} */ entry) => entry.filePath)
+    .sort();
+}
+
+/** @param {WorkspacePaths} paths @param {any} predicate @returns {any} */
+export function findImportFiles(paths, predicate) {
+  const files = new Set();
+  for (const rootDir of importSearchRoots(paths)) {
+    for (const filePath of listFilesRecursive(rootDir, predicate)) {
+      if (
+        filePath.includes(`${path.sep}candidates${path.sep}`) ||
+        filePath.includes(`${path.sep}docs-generated${path.sep}`) ||
+        filePath.includes(`${path.sep}topogram${path.sep}tests${path.sep}fixtures${path.sep}expected${path.sep}`)
+      ) {
+        continue;
+      }
+      files.add(filePath);
+    }
+  }
+  return [...files].sort();
+}
+
+/** @param {WorkflowRecord} input @returns {CandidateRecord} */
+export function makeCandidateRecord({
+  kind,
+  idHint,
+  label,
+  confidence = "medium",
+  sourceKind,
+  sourceOfTruth = "imported",
+  provenance,
+  track = null,
+  ...payload
+}) {
+  const inferredTrack =
+    track ||
+    (["entity", "enum", "relation", "index"].includes(kind)
+      ? "db"
+      : kind === "capability"
+        ? "api"
+        : null);
+  return {
+    kind,
+    id_hint: idHint,
+    label,
+    confidence,
+    source_kind: sourceKind,
+    source_of_truth: sourceOfTruth,
+    provenance: Array.isArray(provenance) ? provenance : [provenance].filter(Boolean),
+    track: inferredTrack,
+    ...payload
+  };
+}
+
+/** @param {any[]} records @param {any} keyFn @returns {any} */
+export function dedupeCandidateRecords(records, keyFn) {
+  const seen = new Map();
+  for (const record of records) {
+    const key = keyFn(record);
+    const recordProvenance = Array.isArray(record.provenance) ? record.provenance : [record.provenance].filter(Boolean);
+    if (!seen.has(key)) {
+      seen.set(key, { ...record, provenance: recordProvenance });
+      continue;
+    }
+    const current = seen.get(key);
+    const currentProvenance = Array.isArray(current.provenance) ? current.provenance : [current.provenance].filter(Boolean);
+    current.provenance = [...new Set([...currentProvenance, ...recordProvenance])];
+  }
+  return [...seen.values()];
+}
+
+/** @param {string} pathValue @returns {any} */
+export function normalizeOpenApiPath(pathValue) {
+  return String(pathValue || "")
+    .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}")
+    .replace(/\/+$/, "") || "/";
+}
+
+/** @param {string} pathValue @returns {any} */
+export function normalizeEndpointPathForMatch(pathValue) {
+  const normalizedPath = normalizeOpenApiPath(pathValue);
+  const segments = normalizedPath
+    .split("/")
+    .filter(Boolean)
+    .map((/** @type {any} */ segment) => {
+      if (/^\{[^}]+\}$/.test(segment)) {
+        return "{}";
+      }
+      return segment
+        .split("-")
+        .map((/** @type {any} */ part) => canonicalCandidateTerm(part))
+        .join("-");
+    });
+  return `/${segments.join("/")}`.replace(/\/+$/, "") || "/";
+}
+
+/** @param {WorkflowRecord} record @returns {any} */
+export function inferCapabilityEntityId(record) {
+  if (record.entity_id) {
+    return record.entity_id;
+  }
+  const pathSegments = normalizeEndpointPathForMatch(record.endpoint?.path || "")
+    .split("/")
+    .filter(Boolean)
+    .filter((/** @type {any} */ segment) => segment !== "{}");
+  const resourceSegment = pathSegments[0] || record.id_hint.replace(/^cap_(create|update|delete|get|list)_/, "");
+  return `entity_${idHintify(canonicalCandidateTerm(resourceSegment))}`;
+}

package/src/workflows/import-app/ui.js

@@ -0,0 +1,443 @@
+// @ts-check
+import fs from "node:fs";
+import path from "node:path";
+
+import { relativeTo } from "../../path-helpers.js";
+import { canonicalCandidateTerm, idHintify, titleCase } from "../../text-helpers.js";
+import { listFilesRecursive, readTextIfExists } from "../shared.js";
+import { dedupeCandidateRecords, makeCandidateRecord } from "./shared.js";
+
+/** @param {string} rootDir @returns {any} */
+export function inferSvelteRoutes(rootDir) {
+  const routesRoot = path.join(rootDir, "src", "routes");
+  if (!fs.existsSync(routesRoot)) {
+    return [];
+  }
+  const files = listFilesRecursive(routesRoot, (/** @type {any} */ child) => child.endsWith("+page.svelte") || child.endsWith("+page.ts") || child.endsWith("+page.server.ts"));
+  const routes = new Set();
+  for (const filePath of files) {
+    const relative = relativeTo(routesRoot, filePath)
+      .replace(/(^|\/)\+page(\.server|)\.(svelte|ts)$/, "")
+      .replace(/\[(.+?)\]/g, ":$1")
+      .replace(/^$/, "/");
+    routes.add(relative.startsWith("/") ? relative : `/${relative}`);
+  }
+  return [...routes].sort();
+}
+
+/** @param {string} rootDir @returns {any} */
+export function inferReactRoutes(rootDir) {
+  const appPath = path.join(rootDir, "src", "App.tsx");
+  const text = readTextIfExists(appPath);
+  if (!text) {
+    return [];
+  }
+  const routes = new Set();
+  for (const match of text.matchAll(/path:\s*"([^"]+)"/g)) {
+    routes.add(match[1]);
+  }
+  for (const match of text.matchAll(/path="([^"]+)"/g)) {
+    routes.add(match[1]);
+  }
+  return [...routes].sort();
+}
+
+/** @param {string} rootDir @returns {any} */
+export function inferNextAppRoutes(rootDir) {
+  const appDir = path.join(rootDir, "app");
+  if (!fs.existsSync(appDir)) {
+    return [];
+  }
+  const routeFiles = listFilesRecursive(
+    appDir,
+    (/** @type {any} */ child) =>
+      /\/page\.(tsx|ts|jsx|js|mdx)$/.test(child) ||
+      /\/route\.(tsx|ts|jsx|js)$/.test(child)
+  );
+  /** @type {any[]} */
+  const routes = [];
+  for (const filePath of routeFiles) {
+    const relative = relativeTo(appDir, filePath);
+    const isPage = /\/page\.(tsx|ts|jsx|js|mdx)$/.test(`/${relative}`) || /^page\.(tsx|ts|jsx|js|mdx)$/.test(relative);
+    const normalizedPath = `/${relative}`
+      .replace(/\/page\.(tsx|ts|jsx|js|mdx)$/, "")
+      .replace(/\/route\.(tsx|ts|jsx|js)$/, "")
+      .replace(/\[(\.\.\.)?([^\]]+)\]/g, (/** @type {any} */ _match, /** @type {any} */ catchAll, /** @type {any} */ name) => catchAll ? `:${name}*` : `:${name}`)
+      .replace(/\/index$/, "")
+      .replace(/^\/$/, "/");
+    routes.push({
+      path: normalizedPath === "" ? "/" : normalizedPath,
+      kind: isPage ? "page" : "route",
+      file: filePath
+    });
+  }
+  return routes.sort((/** @type {any} */ a, /** @type {any} */ b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind));
+}
+
+/** @param {string} routePath @returns {any} */
+export function nextScreenKindForRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (/\/(login|register|setup)$/.test(normalized)) {
+    return "flow";
+  }
+  return screenKindForRoute(routePath);
+}
+
+/** @param {string} routePath @returns {any} */
+export function nextScreenIdForRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") {
+    return "home";
+  }
+  if (/\/login$/.test(normalized)) {
+    return "login";
+  }
+  if (/\/register$/.test(normalized)) {
+    return "register";
+  }
+  if (/\/setup$/.test(normalized)) {
+    return "setup";
+  }
+  return screenIdForRoute(routePath);
+}
+
+/** @param {string} routePath @returns {any} */
+export function entityIdForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (/^\/posts(\/|$)/.test(normalized)) {
+    return "entity_post";
+  }
+  if (/^\/users(\/|$)/.test(normalized)) {
+    return "entity_user";
+  }
+  return null;
+}
+
+/** @param {string} routePath @returns {any} */
+export function conceptIdForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") {
+    return "surface_home";
+  }
+  if (/\/login$/.test(normalized)) {
+    return "flow_login";
+  }
+  if (/\/register$/.test(normalized)) {
+    return "flow_register";
+  }
+  if (/\/setup$/.test(normalized)) {
+    return "flow_setup";
+  }
+  return entityIdForNextRoute(routePath) || entityIdForRoute(routePath);
+}
+
+/** @param {string} routePath @returns {any} */
+export function uiCapabilityHintsForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") {
+    return { load: null, submit: null, primary_action: null };
+  }
+  if (/\/login$/.test(normalized)) {
+    return { load: null, submit: "cap_sign_in_user", primary_action: "cap_sign_in_user" };
+  }
+  if (/\/register$/.test(normalized)) {
+    return { load: null, submit: "cap_register_user", primary_action: "cap_register_user" };
+  }
+  if (/\/setup$/.test(normalized)) {
+    return { load: null, submit: null, primary_action: null };
+  }
+  if (/^\/posts\/new$/.test(normalized)) {
+    return { load: null, submit: "cap_create_post", primary_action: "cap_create_post" };
+  }
+  if (/^\/posts\/:id$/.test(normalized) || /^\/posts\/:[^/]+$/.test(normalized)) {
+    return { load: "cap_get_post", submit: null, primary_action: "cap_update_post" };
+  }
+  if (/^\/posts$/.test(normalized)) {
+    return { load: "cap_list_posts", submit: null, primary_action: "cap_create_post" };
+  }
+  if (/^\/users\/new$/.test(normalized)) {
+    return { load: null, submit: "cap_create_user", primary_action: "cap_create_user" };
+  }
+  return uiCapabilityHintsForRoute(routePath);
+}
+
+/** @param {string} routePath @returns {any} */
+export function routeSegments(routePath) {
+  return String(routePath || "")
+    .split("/")
+    .filter(Boolean)
+    .map((/** @type {any} */ segment) => segment.replace(/^:/, ""));
+}
+
+/** @param {string} routePath @returns {any} */
+export function screenKindForRoute(routePath) {
+  const normalized = String(routePath || "");
+  const segments = routeSegments(normalized);
+  if (/\/new$/.test(normalized)) {
+    return "form";
+  }
+  if (/\/:?[A-Za-z0-9_]+\/edit$/.test(normalized)) {
+    return "form";
+  }
+  if (segments.length >= 2 && !/\/new$/.test(normalized) && !/\/edit$/.test(normalized)) {
+    return "detail";
+  }
+  return "list";
+}
+
+/** @param {string} routePath @returns {any} */
+export function screenIdForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  const resource = canonicalCandidateTerm(segments[0] || "home");
+  const kind = screenKindForRoute(routePath);
+  if (kind === "form" && /\/new$/.test(routePath)) {
+    return `${resource}_create`;
+  }
+  if (kind === "form" && /\/edit$/.test(routePath)) {
+    return `${resource}_edit`;
+  }
+  if (kind === "detail") {
+    return `${resource}_detail`;
+  }
+  return `${resource}_list`;
+}
+
+/** @param {string} routePath @returns {any} */
+export function uiCapabilityHintsForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  const resource = canonicalCandidateTerm(segments[0] || "item");
+  const idSegment = segments[1] || null;
+  if (/\/new$/.test(routePath)) {
+    return { load: null, submit: `cap_create_${resource}`, primary_action: `cap_create_${resource}` };
+  }
+  if (/\/edit$/.test(routePath)) {
+    return { load: `cap_get_${resource}`, submit: `cap_update_${resource}`, primary_action: `cap_update_${resource}` };
+  }
+  if (idSegment && !/new|edit/.test(idSegment)) {
+    return { load: `cap_get_${resource}`, submit: null, primary_action: `cap_update_${resource}` };
+  }
+  return { load: `cap_list_${resource}s`, submit: null, primary_action: `cap_create_${resource}` };
+}
+
+/** @param {string} routePath @returns {any} */
+export function entityIdForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  return `entity_${canonicalCandidateTerm(segments[0] || "item")}`;
+}
+
+/** @param {WorkspacePaths} paths @returns {any} */
+export function collectUiImport(paths) {
+  /** @type {any[]} */
+  const findings = [];
+  /** @type {WorkflowRecord} */
+  const candidates = {
+    screens: [],
+    routes: [],
+    actions: [],
+    stacks: []
+  };
+
+  const reactRoots = [
+    path.join(paths.workspaceRoot, "apps", "web"),
+    path.join(paths.workspaceRoot, "examples", "maintained", "proof-app")
+  ];
+  const svelteRoots = [
+    path.join(paths.workspaceRoot, "apps", "web-sveltekit"),
+    path.join(paths.workspaceRoot, "apps", "local-stack", "web")
+  ];
+  const nextRoots = [paths.workspaceRoot];
+
+  for (const rootDir of reactRoots) {
+    const routes = inferReactRoutes(rootDir);
+    if (routes.length === 0) {
+      continue;
+    }
+    const provenance = relativeTo(paths.repoRoot, path.join(rootDir, "src", "App.tsx"));
+    findings.push({
+      kind: "react_screen_routes",
+      file: provenance,
+      routes
+    });
+    candidates.stacks.push("react_web");
+    for (const routePath of routes) {
+      const screenId = screenIdForRoute(routePath);
+      const screenKind = screenKindForRoute(routePath);
+      const capabilityHints = uiCapabilityHintsForRoute(routePath);
+      candidates.screens.push(
+        makeCandidateRecord({
+          kind: "screen",
+          idHint: screenId,
+          label: titleCase(screenId),
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: `${provenance}#${routePath}`,
+          track: "ui",
+          entity_id: entityIdForRoute(routePath),
+          screen_kind: screenKind,
+          route_path: routePath,
+          capability_hints: capabilityHints
+        })
+      );
+      candidates.routes.push(
+        makeCandidateRecord({
+          kind: "ui_route",
+          idHint: `${screenId}_route`,
+          label: routePath,
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: `${provenance}#${routePath}`,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityIdForRoute(routePath),
+          path: routePath
+        })
+      );
+      if (capabilityHints.primary_action) {
+        candidates.actions.push(
+          makeCandidateRecord({
+            kind: "ui_action",
+            idHint: `${screenId}_${idHintify(capabilityHints.primary_action)}`,
+            label: capabilityHints.primary_action,
+            confidence: "low",
+            sourceKind: "route_code",
+            provenance: `${provenance}#${routePath}`,
+            track: "ui",
+            screen_id: screenId,
+            entity_id: entityIdForRoute(routePath),
+            capability_hint: capabilityHints.primary_action,
+            prominence: screenKind === "list" ? "primary" : "secondary"
+          })
+        );
+      }
+    }
+  }
+
+  for (const rootDir of svelteRoots) {
+    const routes = inferSvelteRoutes(rootDir);
+    if (routes.length === 0) {
+      continue;
+    }
+    const provenance = relativeTo(paths.repoRoot, path.join(rootDir, "src", "routes"));
+    findings.push({
+      kind: "sveltekit_screen_routes",
+      file: provenance,
+      routes
+    });
+    candidates.stacks.push("sveltekit_web");
+    for (const routePath of routes) {
+      const screenId = screenIdForRoute(routePath);
+      const screenKind = screenKindForRoute(routePath);
+      const capabilityHints = uiCapabilityHintsForRoute(routePath);
+      candidates.screens.push(
+        makeCandidateRecord({
+          kind: "screen",
+          idHint: screenId,
+          label: titleCase(screenId),
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: `${provenance}#${routePath}`,
+          track: "ui",
+          entity_id: entityIdForRoute(routePath),
+          screen_kind: screenKind,
+          route_path: routePath,
+          capability_hints: capabilityHints
+        })
+      );
+      candidates.routes.push(
+        makeCandidateRecord({
+          kind: "ui_route",
+          idHint: `${screenId}_route`,
+          label: routePath,
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: `${provenance}#${routePath}`,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityIdForRoute(routePath),
+          path: routePath
+        })
+      );
+    }
+  }
+
+  for (const rootDir of nextRoots) {
+    const routes = inferNextAppRoutes(rootDir);
+    if (routes.length === 0) {
+      continue;
+    }
+    const provenanceRoot = relativeTo(paths.repoRoot, path.join(rootDir, "app"));
+    findings.push({
+      kind: "next_app_routes",
+      file: provenanceRoot,
+      routes: routes.map((/** @type {any} */ route) => route.path)
+    });
+    candidates.stacks.push("next_app_router");
+    for (const route of routes) {
+      if (route.kind !== "page") {
+        continue;
+      }
+      const routeProvenance = `${relativeTo(paths.repoRoot, route.file)}#${route.path}`;
+      const screenId = nextScreenIdForRoute(route.path);
+      const screenKind = nextScreenKindForRoute(route.path);
+      const capabilityHints = uiCapabilityHintsForNextRoute(route.path);
+      const entityId = entityIdForNextRoute(route.path);
+      const conceptId = conceptIdForNextRoute(route.path);
+      candidates.screens.push(
+        makeCandidateRecord({
+          kind: "screen",
+          idHint: screenId,
+          label: titleCase(screenId),
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: routeProvenance,
+          track: "ui",
+          entity_id: entityId,
+          concept_id: conceptId,
+          screen_kind: screenKind,
+          route_path: route.path,
+          capability_hints: capabilityHints
+        })
+      );
+      candidates.routes.push(
+        makeCandidateRecord({
+          kind: "ui_route",
+          idHint: `${screenId}_route`,
+          label: route.path,
+          confidence: "medium",
+          sourceKind: "route_code",
+          provenance: routeProvenance,
+          track: "ui",
+          screen_id: screenId,
+          entity_id: entityId,
+          concept_id: conceptId,
+          path: route.path
+        })
+      );
+      if (capabilityHints.primary_action) {
+        candidates.actions.push(
+          makeCandidateRecord({
+            kind: "ui_action",
+            idHint: `${screenId}_${idHintify(capabilityHints.primary_action)}`,
+            label: capabilityHints.primary_action,
+            confidence: "low",
+            sourceKind: "route_code",
+            provenance: routeProvenance,
+            track: "ui",
+            screen_id: screenId,
+            entity_id: entityId,
+            concept_id: conceptId,
+            capability_hint: capabilityHints.primary_action,
+            prominence: screenKind === "list" ? "primary" : "secondary"
+          })
+        );
+      }
+    }
+  }
+
+  candidates.screens = dedupeCandidateRecords(candidates.screens, (/** @type {any} */ record) => record.id_hint);
+  candidates.routes = dedupeCandidateRecords(candidates.routes, (/** @type {any} */ record) => record.id_hint);
+  candidates.actions = dedupeCandidateRecords(candidates.actions, (/** @type {any} */ record) => record.id_hint);
+  candidates.stacks = [...new Set(candidates.stacks)].sort();
+
+  return { findings, candidates };
+}