@topogram/cli 0.3.76 → 0.3.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.76",
+  "version": "0.3.78",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/adoption/plan/index.js

@@ -741,7 +741,18 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
     mapping_suggestions: [{
       type: "manual_project_config_review",
       id: seam.id_hint || seam.seam_id,
-      reason: "Review the inferred database migration strategy before editing topogram.project.json."
+      reason: "Review the inferred database migration strategy before editing topogram.project.json.",
+      project_config_target: seam.project_config_target || {
+        file: "topogram.project.json",
+        path: "topology.runtimes[].migration"
+      },
+      proposed_runtime_migration: seam.proposed_runtime_migration || null,
+      missing_decisions: seam.missing_decisions || [],
+      evidence: seam.evidence || seam.provenance || [],
+      manual_next_steps: seam.manual_next_steps || [
+        "Review evidence and missing decisions.",
+        "Manually copy the accepted migration strategy into topogram.project.json."
+      ]
     }],
     available_actions: ADOPTION_STATE_VOCABULARY
   }));

package/src/cli/commands/import/workspace.js

@@ -115,6 +115,7 @@ export function importCandidateCounts(summary) {
     apiRoutes: candidates.api?.routes?.length || 0,
     uiScreens: candidates.ui?.screens?.length || 0,
     uiRoutes: candidates.ui?.routes?.length || 0,
+    uiFlows: candidates.ui?.flows?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
     uiShapes: candidates.ui?.shapes?.length || 0,
     cliCommands: candidates.cli?.commands?.length || 0,

package/src/cli.js

@@ -63,18 +63,18 @@ const inputPath = commandArgs && Object.prototype.hasOwnProperty.call(commandArg
 const cliOptions = parseCliOptions(args, commandArgs);
 
 try {
-  process.exit(await runCliDispatch({
+  process.exitCode = await runCliDispatch({
     args,
     commandArgs,
     inputPath,
     cliOptions,
     executablePath: path.resolve(process.argv[1] || fileURLToPath(import.meta.url))
-  }));
+  });
 } catch (error) {
   if (error.validation) {
     console.error(formatValidationErrors(error.validation));
   } else {
     console.error(error.message);
   }
-  process.exit(1);
+  process.exitCode = 1;
 }

package/src/import/core/runner/candidates.js

@@ -284,6 +284,7 @@ export function normalizeCandidatesForTrack(track, candidates) {
       screens: dedupeCandidateRecords(candidates.screens || [], idHint),
       routes: dedupeCandidateRecords(candidates.routes || [], idHint),
       actions: dedupeCandidateRecords(candidates.actions || [], idHint),
+      flows: dedupeCandidateRecords(candidates.flows || [], idHint),
       widgets,
       shapes: dedupeCandidateRecords([...(candidates.shapes || []), ...eventShapes], idHint),
       stacks: [...new Set(candidates.stacks || [])].sort()
@@ -330,6 +331,7 @@ export function enrichUiWidgetDataSources(uiCandidates, allCandidates) {
   const { components, ...canonicalCandidates } = uiCandidates;
   return {
     ...canonicalCandidates,
+    flows: dedupeCandidateRecords(canonicalCandidates.flows || [], (/** @type {any} */ flow) => flow.id_hint),
     widgets: widgets.map((widget) => {
       const dataSource = inferredDataSourceForWidget(widget, allCandidates);
       const dataProp = widget.data_prop || "rows";

package/src/import/core/runner/reports.js

@@ -10,9 +10,12 @@ import { uiWidgetCandidates } from "./candidates.js";
  */
 export function reportMarkdown(track, candidates) {
   if (track === "db") {
-    const seamLines = (candidates.maintained_seams || []).map((/** @type {any} */ seam) =>
-      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`
-    );
+    const seamLines = (candidates.maintained_seams || []).flatMap((/** @type {any} */ seam) => [
+      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`,
+      `  - project config target: \`${seam.project_config_target?.path || "topology.runtimes[].migration"}\``,
+      `  - evidence: ${(seam.evidence || []).slice(0, 3).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+      `  - manual next: ${(seam.manual_next_steps || []).slice(0, 2).join(" ")}`
+    ]);
     return ensureTrailingNewline(
       `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
@@ -25,11 +28,15 @@ export function reportMarkdown(track, candidates) {
   if (track === "ui") {
     const widgets = uiWidgetCandidates(candidates);
     const shapes = candidates.shapes || [];
+    const flows = candidates.flows || [];
     const widgetLines = widgets.map((widget) =>
       `- \`${widget.id_hint}\` confidence ${widget.confidence || "unknown"} pattern \`${widget.pattern || widget.inferred_pattern || "unknown"}\` region \`${widget.region || widget.inferred_region || "unknown"}\` events ${(widget.inferred_events || []).length} evidence ${(widget.evidence || widget.provenance || []).length} missing decisions ${(widget.missing_decisions || []).length}`
     );
+    const flowLines = flows.map((/** @type {any} */ flow) =>
+      `- \`${flow.id_hint}\` type \`${flow.flow_type}\` confidence ${flow.confidence || "unknown"} routes ${(flow.route_paths || []).map((/** @type {string} */ route) => `\`${route}\``).join(", ") || "_none_"} missing decisions ${(flow.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -57,6 +64,6 @@ export function reportMarkdown(track, candidates) {
  */
 export function appReportMarkdown(candidates, tracks) {
   return ensureTrailingNewline(
-    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Flow candidates: ${candidates.ui?.flows?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
   );
 }

package/src/import/core/runner/tracks.js

@@ -102,7 +102,7 @@ function initialCandidatesForTrack(track) {
     return { capabilities: [], routes: [], stacks: [] };
   }
   if (track === "ui") {
-    return { screens: [], routes: [], actions: [], stacks: [] };
+    return { screens: [], routes: [], actions: [], flows: [], stacks: [] };
   }
   if (track === "cli") {
     return { commands: [], capabilities: [], surfaces: [] };

package/src/import/core/shared/files.js

@@ -6,12 +6,17 @@ import { relativeTo } from "../../../path-helpers.js";
 export const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
   ".next",
+  ".tmp",
   ".turbo",
   ".yarn",
+  ".cache",
+  ".parcel-cache",
+  ".svelte-kit",
   "build",
   "coverage",
   "dist",
   "node_modules",
+  "out",
   "tmp"
 ]);
 
@@ -82,6 +87,54 @@ export function normalizeImportRelativePath(paths, filePath) {
   return relativeTo(paths.repoRoot, filePath);
 }
 
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function importSourcePathRelativeToWorkspace(paths, filePath) {
+  return relativeTo(paths.workspaceRoot, filePath).replaceAll(path.sep, "/");
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {"runtime_source"|"parser_config"|"docs"|"tests"|"fixtures"|"generated_output"}
+ */
+export function classifyImportSourcePath(paths, filePath) {
+  const relativePath = importSourcePathRelativeToWorkspace(paths, filePath);
+  const basename = path.basename(relativePath).toLowerCase();
+  if (/(^|\/)(\.tmp|tmp|temp|dist|build|coverage|out|generated|docs-generated|snapshots?)(\/|$)/i.test(relativePath)) {
+    return "generated_output";
+  }
+  if (/^(template|templates|[^/]+-templates|[^/]+_templates)(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(test|tests|__tests__|spec|specs|mocks?)(\/|$)|\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs)$/i.test(relativePath)) {
+    return "tests";
+  }
+  if (/(^|\/)(fixture|fixtures|examples?)(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(doc|docs|documentation|guides?)(\/|$)|^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(relativePath) || /^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(basename)) {
+    return "docs";
+  }
+  if (/(^|\/)(package\.json|openapi\.(json|ya?ml)|swagger\.(json|ya?ml)|drizzle\.config\.(ts|js|mjs|cjs)|tsconfig\.json)$/i.test(relativePath)) {
+    return "parser_config";
+  }
+  return "runtime_source";
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isPrimaryImportSource(paths, filePath) {
+  const sourceType = classifyImportSourcePath(paths, filePath);
+  return sourceType === "runtime_source" || sourceType === "parser_config";
+}
+
 /**
  * @param {import("./types.d.ts").ImportPaths} paths
  * @param {string} filePath
@@ -130,6 +183,9 @@ export function canonicalSourceRank(paths, filePath, kind) {
       rank += penalty.weight;
     }
   }
+  if (!isPrimaryImportSource(paths, filePath)) {
+    rank += 1000;
+  }
   return rank;
 }
 
@@ -157,9 +213,10 @@ export function selectPreferredImportFiles(paths, files, kind) {
 /**
  * @param {import("./types.d.ts").ImportPaths} paths
  * @param {any} predicate
+ * @param {{ primaryOnly?: boolean }} [options]
  * @returns {any}
  */
-export function findImportFiles(paths, predicate) {
+export function findImportFiles(paths, predicate, options = {}) {
   const files = new Set();
   for (const rootDir of importSearchRoots(paths)) {
     for (const filePath of listFilesRecursive(rootDir, predicate)) {
@@ -170,8 +227,26 @@ export function findImportFiles(paths, predicate) {
       ) {
         continue;
       }
+      if (options.primaryOnly && !isPrimaryImportSource(paths, filePath)) {
+        continue;
+      }
       files.add(filePath);
     }
   }
   return [...files].sort();
 }
+
+/**
+ * Find files that are eligible to create primary import candidates.
+ *
+ * Docs, tests, fixture/template roots, generated output, and cache output may
+ * still support evidence elsewhere, but candidate-producing extractors should
+ * start from this helper so the primary-source rule is one API boundary.
+ *
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {any} predicate
+ * @returns {any}
+ */
+export function findPrimaryImportFiles(paths, predicate) {
+  return findImportFiles(paths, predicate, { primaryOnly: true });
+}

package/src/import/core/shared/next-app.js

@@ -10,7 +10,7 @@ import {
   normalizeEndpointPathForMatch,
   normalizeOpenApiPath
 } from "./api-routes.js";
-import { entityIdForRoute, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
+import { entityIdForRoute, inferNonResourceUiFlow, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
 
 /**
  * @param {string} rootDir
@@ -48,7 +48,7 @@ export function inferNextAppRoutes(rootDir) {
  */
 export function nextScreenKindForRoute(routePath) {
   const normalized = String(routePath || "");
-  if (/\/(login|register|setup)$/.test(normalized)) return "flow";
+  if (inferNonResourceUiFlow(normalized) || /\/(login|register|setup)$/.test(normalized)) return "flow";
   return screenKindForRoute(routePath);
 }
 

package/src/import/core/shared/ui-routes.js

@@ -5,6 +5,51 @@ import { relativeTo } from "../../../path-helpers.js";
 import { canonicalCandidateTerm } from "./candidates.js";
 import { listFilesRecursive, readTextIfExists } from "./files.js";
 
+const NON_RESOURCE_FLOW_DEFINITIONS = [
+  {
+    flow_type: "auth",
+    concept_id: "flow_auth",
+    pattern: /\/(login|log-in|signin|sign-in|sign_in|logout|log-out|register|signup|sign-up|forgot-password|reset-password|password-reset)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm auth provider and session lifecycle", "confirm success and failure destinations"]
+  },
+  {
+    flow_type: "onboarding_wizard",
+    concept_id: "flow_onboarding",
+    pattern: /\/(onboarding|setup|welcome|get-started|getting-started|wizard|stepper)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm step order and completion criteria", "confirm resumability and exit behavior"]
+  },
+  {
+    flow_type: "settings_preferences",
+    concept_id: "flow_settings",
+    pattern: /\/(settings|preferences|profile|account|billing|security)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm settings ownership boundary", "confirm save, validation, and permission behavior"]
+  },
+  {
+    flow_type: "dashboard_reporting",
+    concept_id: "flow_dashboard",
+    pattern: /\/(dashboard|reports|reporting|analytics|insights|metrics)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm reporting data sources", "confirm refresh cadence and empty states"]
+  },
+  {
+    flow_type: "search_filter",
+    concept_id: "flow_search",
+    pattern: /\/(search|results|explore|browse|discover)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm searchable resources", "confirm filter, sorting, and pagination behavior"]
+  },
+  {
+    flow_type: "bulk_review",
+    concept_id: "flow_bulk_review",
+    pattern: /\/(review|reviews|approvals|approval|moderation|queue|bulk)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm bulk action eligibility", "confirm review outcomes and audit requirements"]
+  }
+];
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -23,12 +68,72 @@ export function routeSegments(routePath) {
 export function screenKindForRoute(routePath) {
   const normalized = String(routePath || "");
   const segments = routeSegments(normalized);
+  if (inferNonResourceUiFlow(normalized)) return "flow";
   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 inferNonResourceUiFlow(routePath) {
+  const normalized = String(routePath || "");
+  for (const definition of NON_RESOURCE_FLOW_DEFINITIONS) {
+    if (definition.pattern.test(normalized)) {
+      return {
+        flow_type: definition.flow_type,
+        concept_id: definition.concept_id,
+        confidence: definition.confidence,
+        missing_decisions: definition.missing_decisions
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @returns {any}
+ */
+export function uiFlowIdForRoute(routePath, screenId) {
+  const flow = inferNonResourceUiFlow(routePath);
+  if (!flow) return null;
+  return `flow_${canonicalCandidateTerm(screenId || flow.flow_type).replace(/-/g, "_")}`;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @param {string} screenKind
+ * @returns {any}
+ */
+export function proposedUiContractAdditionsForFlow(routePath, screenId, screenKind) {
+  return {
+    projection_type: "ui_contract",
+    screens: [
+      {
+        id: screenId,
+        kind: screenKind || "flow",
+        title: screenId
+      }
+    ],
+    screen_routes: [
+      {
+        screen: screenId,
+        path: routePath
+      }
+    ],
+    notes: [
+      "Review-only flow recovery proposal.",
+      "Promote into the shared UI contract only after confirming behavior, state, and ownership decisions."
+    ]
+  };
+}
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -37,6 +142,7 @@ export function screenIdForRoute(routePath) {
   const segments = routeSegments(routePath);
   const resource = canonicalCandidateTerm(segments[0] || "home");
   const kind = screenKindForRoute(routePath);
+  if (kind === "flow") return canonicalCandidateTerm(segments.join("_") || "home").replace(/-/g, "_");
   if (kind === "form" && /\/new$/.test(routePath)) return `${resource}_create`;
   if (kind === "form" && /\/edit$/.test(routePath)) return `${resource}_edit`;
   if (kind === "detail") return `${resource}_detail`;

package/src/import/core/shared.js

@@ -19,9 +19,13 @@ export {
   listFilesRecursive,
   importSearchRoots,
   normalizeImportRelativePath,
+  importSourcePathRelativeToWorkspace,
+  classifyImportSourcePath,
+  isPrimaryImportSource,
   canonicalSourceRank,
   selectPreferredImportFiles,
-  findImportFiles
+  findImportFiles,
+  findPrimaryImportFiles
 } from "./shared/files.js";
 export {
   normalizeOpenApiPath,
@@ -38,6 +42,9 @@ export {
   screenIdForRoute,
   uiCapabilityHintsForRoute,
   entityIdForRoute,
+  inferNonResourceUiFlow,
+  uiFlowIdForRoute,
+  proposedUiContractAdditionsForFlow,
   inferReactRoutes,
   inferSvelteRoutes,
   inferNavigationStructure,

package/src/import/enrichers/django-rest.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { findImportFiles, readTextIfExists } from "../core/shared.js";
+import { findPrimaryImportFiles, readTextIfExists } from "../core/shared.js";
 
 function splitClassBlocks(text) {
   const lines = String(text || "").split(/\r?\n/);
@@ -51,7 +51,7 @@ function splitClassBlocks(text) {
 }
 
 function buildSerializerIndex(paths) {
-  const files = findImportFiles(paths, (filePath) => /\/serializers\.py$/i.test(filePath));
+  const files = findPrimaryImportFiles(paths, (filePath) => /\/serializers\.py$/i.test(filePath));
   const index = new Map();
 
   for (const filePath of files) {
@@ -89,7 +89,7 @@ function buildSerializerIndex(paths) {
 }
 
 function buildViewIndex(paths) {
-  const files = findImportFiles(paths, (filePath) => /\/views\.py$/i.test(filePath));
+  const files = findPrimaryImportFiles(paths, (filePath) => /\/views\.py$/i.test(filePath));
   const index = new Map();
 
   for (const filePath of files) {
@@ -182,7 +182,7 @@ export const djangoRestEnricher = {
   applies(context, candidates) {
     if ((candidates.capabilities || []).length === 0) return false;
     return (candidates.stacks || []).includes("django") ||
-      findImportFiles(context.paths, (filePath) => /\/serializers\.py$/i.test(filePath)).length > 0;
+      findPrimaryImportFiles(context.paths, (filePath) => /\/serializers\.py$/i.test(filePath)).length > 0;
   },
   enrich(context, candidates) {
     const serializerIndex = buildSerializerIndex(context.paths);

package/src/import/enrichers/rails-controllers.js

@@ -1,9 +1,9 @@
 import path from "node:path";
 
-import { findImportFiles, readTextIfExists } from "../core/shared.js";
+import { findPrimaryImportFiles, readTextIfExists } from "../core/shared.js";
 
 function buildControllerIndex(paths) {
-  const files = findImportFiles(paths, (filePath) => /app\/controllers\/.+_controller\.rb$/i.test(filePath));
+  const files = findPrimaryImportFiles(paths, (filePath) => /app\/controllers\/.+_controller\.rb$/i.test(filePath));
   const index = new Map();
   for (const filePath of files) {
     const text = readTextIfExists(filePath) || "";
@@ -186,7 +186,7 @@ export const railsControllerEnricher = {
   applies(context, candidates) {
     if ((candidates.capabilities || []).length === 0) return false;
     return (candidates.stacks || []).includes("rails") ||
-      findImportFiles(context.paths, (filePath) => /app\/controllers\/.+_controller\.rb$/i.test(filePath)).length > 0;
+      findPrimaryImportFiles(context.paths, (filePath) => /app\/controllers\/.+_controller\.rb$/i.test(filePath)).length > 0;
   },
   enrich(context, candidates) {
     const controllers = buildControllerIndex(context.paths);

package/src/import/enrichers/rails-models.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { findImportFiles, readTextIfExists } from "../core/shared.js";
+import { findPrimaryImportFiles, readTextIfExists } from "../core/shared.js";
 
 function modelClassNameForEntity(entityId) {
   const stem = String(entityId || "")
@@ -13,7 +13,7 @@ function modelClassNameForEntity(entityId) {
 }
 
 function buildModelIndex(paths) {
-  const modelFiles = findImportFiles(paths, (filePath) => /app\/models\/.+\.rb$/i.test(filePath));
+  const modelFiles = findPrimaryImportFiles(paths, (filePath) => /app\/models\/.+\.rb$/i.test(filePath));
   const index = new Map();
   for (const filePath of modelFiles) {
     const text = readTextIfExists(filePath) || "";
@@ -93,7 +93,7 @@ export const railsModelEnricher = {
   track: "db",
   applies(context, candidates) {
     if ((candidates.entities || []).length === 0) return false;
-    return findImportFiles(context.paths, (filePath) => /app\/models\/.+\.rb$/i.test(filePath)).length > 0;
+    return findPrimaryImportFiles(context.paths, (filePath) => /app\/models\/.+\.rb$/i.test(filePath)).length > 0;
   },
   enrich(context, candidates) {
     const modelIndex = buildModelIndex(context.paths);

package/src/import/extractors/api/aspnet-core.js

@@ -1,6 +1,6 @@
 import {
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   inferApiEntityIdFromPath,
   inferRouteCapabilityId,
   makeCandidateRecord,
@@ -22,7 +22,7 @@ function parsePublicProperties(text) {
 }
 
 function buildDotnetFileIndex(paths) {
-  const files = findImportFiles(paths, (filePath) => /\.cs$/i.test(filePath));
+  const files = findPrimaryImportFiles(paths, (filePath) => /\.cs$/i.test(filePath));
   const index = new Map();
   for (const filePath of files) {
     index.set(relativeTo(paths.repoRoot, filePath), readTextIfExists(filePath) || "");
@@ -239,8 +239,8 @@ export const aspNetCoreExtractor = {
   id: "api.aspnet-core",
   track: "api",
   detect(context) {
-    const controllerFiles = findImportFiles(context.paths, (filePath) => /Controller\.cs$/i.test(filePath));
-    const programFiles = findImportFiles(context.paths, (filePath) => /Program\.cs$/i.test(filePath));
+    const controllerFiles = findPrimaryImportFiles(context.paths, (filePath) => /Controller\.cs$/i.test(filePath));
+    const programFiles = findPrimaryImportFiles(context.paths, (filePath) => /Program\.cs$/i.test(filePath));
     const score = controllerFiles.length > 0 && programFiles.some((filePath) => /WebApplication\.CreateBuilder|AddSwaggerGen|AddMvc/.test(readTextIfExists(filePath) || "")) ? 88 : 0;
     return {
       score,
@@ -248,7 +248,7 @@ export const aspNetCoreExtractor = {
     };
   },
   extract(context) {
-    const controllerFiles = findImportFiles(context.paths, (filePath) => /Controller\.cs$/i.test(filePath));
+    const controllerFiles = findPrimaryImportFiles(context.paths, (filePath) => /Controller\.cs$/i.test(filePath));
     const featureFiles = buildDotnetFileIndex(context.paths).files.map((filePath) => ({ filePath, text: readTextIfExists(filePath) || "" }));
     const findings = [];
     const candidates = { capabilities: [], routes: [], stacks: [] };

package/src/import/extractors/api/django-routes.js

@@ -2,7 +2,7 @@ import path from "node:path";
 
 import {
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   inferApiEntityIdFromPath,
   inferRouteCapabilityId,
   makeCandidateRecord,
@@ -90,7 +90,7 @@ function permissionAuthHint(permissionText, method) {
 }
 
 function buildViewIndex(paths) {
-  const viewFiles = findImportFiles(paths, (filePath) => /\/views\.py$/i.test(filePath));
+  const viewFiles = findPrimaryImportFiles(paths, (filePath) => /\/views\.py$/i.test(filePath));
   const index = new Map();
 
   for (const filePath of viewFiles) {
@@ -250,8 +250,8 @@ export const djangoRoutesExtractor = {
   id: "api.django-routes",
   track: "api",
   detect(context) {
-    const manageFiles = findImportFiles(context.paths, (filePath) => /\/manage\.py$/i.test(filePath));
-    const urlFiles = findImportFiles(context.paths, (filePath) => /\/urls\.py$/i.test(filePath));
+    const manageFiles = findPrimaryImportFiles(context.paths, (filePath) => /\/manage\.py$/i.test(filePath));
+    const urlFiles = findPrimaryImportFiles(context.paths, (filePath) => /\/urls\.py$/i.test(filePath));
     const score = manageFiles.length > 0 && urlFiles.length > 0 ? 90 : 0;
     return {
       score,
@@ -259,7 +259,7 @@ export const djangoRoutesExtractor = {
     };
   },
   extract(context) {
-    const urlFiles = findImportFiles(context.paths, (filePath) => /\/urls\.py$/i.test(filePath));
+    const urlFiles = findPrimaryImportFiles(context.paths, (filePath) => /\/urls\.py$/i.test(filePath));
     const moduleMap = new Map(urlFiles.map((filePath) => [moduleNameForFile(context.paths.repoRoot, filePath), filePath]));
     const viewIndex = buildViewIndex(context.paths);
     const rootFiles = urlFiles.filter((filePath) => !/\/apps\//.test(filePath));

package/src/import/extractors/api/express.js

@@ -2,7 +2,7 @@ import path from "node:path";
 
 import {
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   inferApiEntityIdFromPath,
   inferRouteAuthHint,
   inferRouteCapabilityId,
@@ -94,18 +94,18 @@ export const expressExtractor = {
   id: "api.express",
   track: "api",
   detect(context) {
-    const routeFiles = findImportFiles(context.paths, (filePath) => /src\/routes\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const routeFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
     return {
       score: routeFiles.length > 0 ? 85 : 0,
       reasons: routeFiles.length > 0 ? ["Found Express route modules"] : []
     };
   },
   extract(context) {
-    const permissionsFile = findImportFiles(context.paths, (filePath) => /src\/helpers\/permissions\.(ts|js|mjs|cjs)$/i.test(filePath))[0];
+    const permissionsFile = findPrimaryImportFiles(context.paths, (filePath) => /src\/helpers\/permissions\.(ts|js|mjs|cjs)$/i.test(filePath))[0];
     const permissionsText = permissionsFile ? context.helpers.readTextIfExists(permissionsFile) || "" : "";
     const apiRoutes = parseApiRoutesMap(permissionsText);
     const permissionMeta = parsePermissionsMetadata(permissionsText);
-    const routeFiles = findImportFiles(context.paths, (filePath) => /src\/routes\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const routeFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
     const routes = routeFiles.flatMap((filePath) =>
       parseExpressRouteCalls(filePath, context.helpers.readTextIfExists(filePath) || "", apiRoutes, permissionMeta)
     );