@topogram/cli 0.3.77 → 0.3.79

package/src/generator/context/shared/summaries.js

@@ -97,6 +97,30 @@ export function summarizeJourneyDoc(doc) {
   };
 }
 
+/**
+ * @param {import("./types.d.ts").ContextStatement} journey
+ * @returns {any}
+ */
+export function summarizeJourney(journey) {
+  return {
+    id: journey.id,
+    kind: journey.kind,
+    name: journey.name || journey.id,
+    description: journey.description || null,
+    status: journey.status || null,
+    goal: journey.goal || null,
+    actors: stableSortedStrings(journey.actors || []),
+    relatedCapabilities: stableSortedStrings(journey.relatedCapabilities || []),
+    relatedWorkflows: stableSortedStrings(journey.relatedWorkflows || []),
+    relatedProjections: stableSortedStrings(journey.relatedProjections || []),
+    relatedWidgets: stableSortedStrings(journey.relatedWidgets || []),
+    stepCount: (journey.steps || []).length,
+    alternateCount: (journey.alternates || []).length,
+    reviewBoundary: reviewBoundaryForJourneyDocPolicy(journey),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
 /**
  * @param {import("./types.d.ts").ContextStatement} statement
  * @returns {any}
@@ -163,6 +187,8 @@ export function summarizeStatement(statement) {
       };
     case "widget":
       return summarizeComponent(statement);
+    case "journey":
+      return summarizeJourney(statement);
     case "shape":
       return {
         id: statement.id,

package/src/generator/context/shared.d.ts

@@ -34,6 +34,7 @@ export function summarizeById(...args: any[]): any;
 export function summarizeDocsByIds(...args: any[]): any;
 export function summarizeDocument(...args: any[]): any;
 export function summarizeDomain(...args: any[]): any;
+export function summarizeJourneyLikeByIds(...args: any[]): any;
 export function summarizePitch(...args: any[]): any;
 export function summarizePlan(...args: any[]): any;
 export function summarizeProjection(...args: any[]): any;

package/src/generator/context/shared.js

@@ -20,6 +20,7 @@ export {
   summarizeById,
   summarizeStatementsByIds,
   summarizeDocsByIds,
+  summarizeJourneyLikeByIds,
   workspaceInventory
 } from "./shared/relationships.js";
 export {

package/src/generator/context/slice/core.js

@@ -20,6 +20,7 @@ import {
   relatedWorkflowDocsForCapability,
   summarizeById,
   summarizeDocsByIds,
+  summarizeJourneyLikeByIds,
   summarizeProjection,
   summarizeStatementsByIds,
   verificationIdsForTarget,
@@ -87,7 +88,7 @@ function capabilitySlice(graph, capabilityId) {
       entities: summarizeStatementsByIds(graph, entities),
       rules: summarizeStatementsByIds(graph, rules),
       workflows: summarizeDocsByIds(graph, workflows),
-      journeys: summarizeDocsByIds(graph, journeys),
+      journeys: summarizeJourneyLikeByIds(graph, journeys),
       projections: summarizeStatementsByIds(graph, projections)
     },
     verification: summarizeStatementsByIds(graph, verifications),
@@ -118,9 +119,12 @@ function workflowSlice(graph, workflowId) {
     ];
   }))].sort();
   const rules = [...new Set(capabilities.flatMap(/** @param {string} capabilityId */ (capabilityId) => relatedRulesForTarget(graph, capabilityId)))].sort();
-  const journeys = (graph.docs || [])
-    .filter(/** @param {any} doc */ (doc) => doc.kind === "journey" && (doc.relatedWorkflows || []).includes(workflowId))
-    .map(/** @param {any} doc */ (doc) => doc.id)
+  const journeys = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter(/** @param {any} doc */ (doc) => doc.kind === "journey")
+  ]
+    .filter(/** @param {any} journey */ (journey) => (journey.relatedWorkflows || []).includes(workflowId))
+    .map(/** @param {any} journey */ (journey) => journey.id)
     .sort();
   const verifications = verificationIdsForTarget(graph, [...capabilities, ...entities, workflowId]);
 
@@ -143,7 +147,7 @@ function workflowSlice(graph, workflowId) {
       capabilities: summarizeStatementsByIds(graph, capabilities),
       entities: summarizeStatementsByIds(graph, entities),
       rules: summarizeStatementsByIds(graph, rules),
-      journeys: summarizeDocsByIds(graph, journeys)
+      journeys: summarizeJourneyLikeByIds(graph, journeys)
     },
     verification: summarizeStatementsByIds(graph, verifications),
     verification_targets: recommendedVerificationTargets(graph, [...capabilities, ...entities, workflowId], {

package/src/generator/context/slice/sdlc.js

@@ -49,9 +49,16 @@ import {
 export function journeySlice(graph, journeyId) {
   const journey = getJourneyDoc(graph, journeyId);
   const capabilities = [...(journey.relatedCapabilities || [])].sort();
+  const entities = [...(journey.relatedEntities || [])].sort();
+  const rules = [...(journey.relatedRules || [])].sort();
   const workflows = [...(journey.relatedWorkflows || [])].sort();
   const projections = [...(journey.relatedProjections || [])].sort();
-  const verifications = verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, journeyId]);
+  const widgets = [...(journey.relatedWidgets || [])].sort();
+  const declaredVerifications = [...(journey.relatedVerifications || [])].sort();
+  const verifications = [...new Set([
+    ...declaredVerifications,
+    ...verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, ...widgets, journeyId])
+  ])].sort();
 
   return {
     type: "context_slice",
@@ -63,14 +70,36 @@ export function journeySlice(graph, journeyId) {
     summary: summarizeById(graph, journeyId),
     depends_on: {
       capabilities,
+      entities,
+      rules,
       workflows,
       projections,
+      widgets,
       verifications
     },
+    steps: (journey.steps || []).map(/** @param {any} step */ (step) => ({
+      id: step.id,
+      intent: step.intent,
+      commands: [...(step.commands || [])],
+      expects: [...(step.expects || [])],
+      after: [...(step.after || [])],
+      notes: step.notes || null
+    })),
+    alternates: (journey.alternates || []).map(/** @param {any} alternate */ (alternate) => ({
+      id: alternate.id,
+      from: alternate.from,
+      condition: alternate.condition,
+      commands: [...(alternate.commands || [])],
+      expects: [...(alternate.expects || [])],
+      notes: alternate.notes || null
+    })),
     related: {
       capabilities: summarizeStatementsByIds(graph, capabilities),
+      entities: summarizeStatementsByIds(graph, entities),
+      rules: summarizeStatementsByIds(graph, rules),
       workflows: summarizeDocsByIds(graph, workflows),
-      projections: summarizeStatementsByIds(graph, projections)
+      projections: summarizeStatementsByIds(graph, projections),
+      widgets: summarizeStatementsByIds(graph, widgets)
     },
     verification: summarizeStatementsByIds(graph, verifications),
     verification_targets: recommendedVerificationTargets(graph, [...capabilities, ...workflows, ...projections, journeyId], {

package/src/generator/context/task-mode.js

@@ -325,7 +325,7 @@ function importAdoptMode(graph, options = {}) {
   return {
     type: "context_task_mode",
     version: 1,
-    mode: "import-adopt",
+    mode: "extract-adopt",
     summary: {
       focus: "Proposal review and adoption planning",
       preferred_start: "adoption-plan.agent.json",
@@ -450,7 +450,7 @@ function verificationMode(graph, options = {}) {
 export function generateContextTaskMode(graph, options = {}) {
   const mode = String(options.modeId || "").trim();
   if (!mode) {
-    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>");
+    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|extract-adopt|diff-review|verification>");
   }
 
   if (mode === "modeling") {
@@ -459,7 +459,7 @@ export function generateContextTaskMode(graph, options = {}) {
   if (mode === "maintained-app-edit") {
     return maintainedAppEditMode(graph, options);
   }
-  if (mode === "import-adopt") {
+  if (mode === "extract-adopt") {
     return importAdoptMode(graph, options);
   }
   if (mode === "diff-review") {

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

@@ -17,12 +17,12 @@ export function reportMarkdown(track, candidates) {
       `  - 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`
+      `# DB Extract 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`
     );
   }
   if (track === "api") {
     return ensureTrailingNewline(
-      `# API Import Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# API Extract Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
     );
   }
   if (track === "ui") {
@@ -36,7 +36,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${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- 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`
+      `# UI Extract 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 extract plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -44,7 +44,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${command.command_id || command.id_hint}\` usage \`${command.usage || "unknown"}\` effects ${(command.effects || []).map((/** @type {any} */ effect) => `\`${effect}\``).join(", ") || "_none_"}`
     );
     return ensureTrailingNewline(
-      `# CLI Import Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
+      `# CLI Extract Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "verification") {

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

@@ -107,7 +107,7 @@ export function classifyImportSourcePath(paths, filePath) {
   if (/(^|\/)(\.tmp|tmp|temp|dist|build|coverage|out|generated|docs-generated|snapshots?)(\/|$)/i.test(relativePath)) {
     return "generated_output";
   }
-  if (/(^|\/)[^/]*templates?[^/]*(\/|$)/i.test(relativePath)) {
+  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)) {
@@ -213,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)) {
@@ -226,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.js

@@ -24,7 +24,8 @@ export {
   isPrimaryImportSource,
   canonicalSourceRank,
   selectPreferredImportFiles,
-  findImportFiles
+  findImportFiles,
+  findPrimaryImportFiles
 } from "./shared/files.js";
 export {
   normalizeOpenApiPath,

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)
     );

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

@@ -2,7 +2,7 @@ import path from "node:path";
 
 import {
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   inferApiCapabilityIdFromOperation,
   inferApiEntityIdFromPath,
   makeCandidateRecord,
@@ -263,8 +263,8 @@ export const fastifyExtractor = {
   id: "api.fastify",
   track: "api",
   detect(context) {
-    const routeFiles = findImportFiles(context.paths, (filePath) => /src\/routes\/api\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
-    const packageJsonFiles = findImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath));
+    const routeFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/api\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const packageJsonFiles = findPrimaryImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath));
     const hasFastifyDependency = packageJsonFiles.some((filePath) => /"fastify"\s*:/.test(context.helpers.readTextIfExists(filePath) || ""));
     return {
       score: routeFiles.length > 0 && hasFastifyDependency ? 86 : 0,
@@ -272,16 +272,16 @@ export const fastifyExtractor = {
     };
   },
   extract(context) {
-    const apiRoutesRoot = findImportFiles(context.paths, (filePath) => /src\/routes\/api\/index\.(ts|js|mjs|cjs)$/i.test(filePath))[0]
-      ? path.join(path.dirname(findImportFiles(context.paths, (filePath) => /src\/routes\/api\/index\.(ts|js|mjs|cjs)$/i.test(filePath))[0]))
+    const apiRoutesRoot = findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/api\/index\.(ts|js|mjs|cjs)$/i.test(filePath))[0]
+      ? path.join(path.dirname(findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/api\/index\.(ts|js|mjs|cjs)$/i.test(filePath))[0]))
       : null;
     if (!apiRoutesRoot) {
       return { findings: [], candidates: { capabilities: [], routes: [], stacks: [] } };
     }
 
-    const routeFiles = findImportFiles(context.paths, (filePath) => /src\/routes\/api\/.+\.(ts|js|mjs|cjs)$/i.test(filePath))
+    const routeFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/routes\/api\/.+\.(ts|js|mjs|cjs)$/i.test(filePath))
       .filter((filePath) => !/\/autohooks\.(ts|js|mjs|cjs)$/i.test(filePath));
-    const schemaFiles = findImportFiles(context.paths, (filePath) => /src\/schemas\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
+    const schemaFiles = findPrimaryImportFiles(context.paths, (filePath) => /src\/schemas\/.+\.(ts|js|mjs|cjs)$/i.test(filePath));
     const namedSchemas = parseNamedTypeboxSchemas(schemaFiles, context.helpers.readTextIfExists);
 
     const routes = [];

package/src/import/extractors/api/flutter-dio.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   makeCandidateRecord,
   pluralizeCandidateTerm,
   relativeTo,
@@ -31,7 +31,7 @@ function capabilityIdFor(featureStem, methodName, httpMethod) {
 }
 
 function extractApiConfigPaths(context) {
-  const configFile = findImportFiles(context.paths, (filePath) => /\/lib\/common\/network\/api_config\.dart$/i.test(filePath))[0];
+  const configFile = findPrimaryImportFiles(context.paths, (filePath) => /\/lib\/common\/network\/api_config\.dart$/i.test(filePath))[0];
   const mapping = new Map();
   if (!configFile) return mapping;
   const text = context.helpers.readTextIfExists(configFile) || "";
@@ -87,7 +87,7 @@ export const flutterDioExtractor = {
   id: "api.flutter-dio",
   track: "api",
   detect(context) {
-    const files = findImportFiles(
+    const files = findPrimaryImportFiles(
       context.paths,
       (filePath) => /\/lib\/features\/.+\/data\/datasources\/.+_remote_data_source\.dart$/i.test(filePath)
     );
@@ -98,7 +98,7 @@ export const flutterDioExtractor = {
     };
   },
   extract(context) {
-    const files = findImportFiles(
+    const files = findPrimaryImportFiles(
       context.paths,
       (filePath) => /\/lib\/features\/.+\/data\/datasources\/.+_remote_data_source\.dart$/i.test(filePath)
     );

package/src/import/extractors/api/generic-route-fallback.js

@@ -1,4 +1,4 @@
-import { findImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
+import { findPrimaryImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
 
 function extractHandlerContext(text, handlerName) {
   if (!handlerName) return "";
@@ -15,7 +15,7 @@ function extractHandlerContext(text, handlerName) {
 
 function inferServerRoutes(context) {
   const routes = [];
-  const routeFiles = findImportFiles(
+  const routeFiles = findPrimaryImportFiles(
     context.paths,
     (filePath) =>
       /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) &&

package/src/import/extractors/api/graphql-code-first.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
   makeCandidateRecord,
   pluralizeCandidateTerm,
@@ -464,7 +464,7 @@ export const graphQlCodeFirstExtractor = {
   id: "api.graphql-code-first",
   track: "api",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => /(\/src\/.+|\/pages\/api\/.+)\.(ts|tsx|js|jsx)$/i.test(filePath));
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /(\/src\/.+|\/pages\/api\/.+)\.(ts|tsx|js|jsx)$/i.test(filePath));
     const hasNestResolvers = files.some((filePath) => {
       const text = readTextIfExists(filePath) || "";
       return /@nestjs\/graphql/.test(text) && /@(Query|Mutation)\s*\(/.test(text);
@@ -489,7 +489,7 @@ export const graphQlCodeFirstExtractor = {
     };
   },
   extract(context) {
-    const files = findImportFiles(context.paths, (filePath) => /(\/src\/.+|\/pages\/api\/.+)\.(ts|tsx|js|jsx)$/i.test(filePath)).filter((filePath) => !/\.test\./i.test(filePath));
+    const files = findPrimaryImportFiles(context.paths, (filePath) => /(\/src\/.+|\/pages\/api\/.+)\.(ts|tsx|js|jsx)$/i.test(filePath)).filter((filePath) => !/\.test\./i.test(filePath));
     const nestTypes = parseNestTypes(files);
     const pothosTypes = parsePothosTypes(files);
     const nexusTypes = parseNexusTypes(files);

package/src/import/extractors/api/graphql-sdl.js

@@ -1,7 +1,7 @@
 import {
   canonicalCandidateTerm,
   dedupeCandidateRecords,
-  findImportFiles,
+  findPrimaryImportFiles,
   idHintify,
   makeCandidateRecord,
   pluralizeCandidateTerm,
@@ -174,7 +174,7 @@ function inferEndpointPath(context, graphqlFiles) {
       return endpointMatch[1];
     }
   }
-  const packageJsonPath = findImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath))[0];
+  const packageJsonPath = findPrimaryImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath))[0];
   const packageText = packageJsonPath ? readTextIfExists(packageJsonPath) : null;
   if (packageText && /graphql-yoga|apollo-server|@apollo\/server/.test(packageText)) {
     return "/graphql";
@@ -183,7 +183,7 @@ function inferEndpointPath(context, graphqlFiles) {
 }
 
 function extractGraphqlSchemaSources(context) {
-  const files = findImportFiles(
+  const files = findPrimaryImportFiles(
     context.paths,
     (filePath) =>
       /\/src\/.+\.(ts|tsx|js|jsx)$/i.test(filePath) ||
@@ -210,7 +210,7 @@ export const graphQlSdlExtractor = {
   detect(context) {
     const schemaSources = extractGraphqlSchemaSources(context);
     const hasOperations = schemaSources.some(({ schema }) => /\btype\s+Query\b|\btype\s+Mutation\b/.test(schema));
-    const packageJsonPath = findImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath))[0];
+    const packageJsonPath = findPrimaryImportFiles(context.paths, (filePath) => /package\.json$/i.test(filePath))[0];
     const packageText = packageJsonPath ? readTextIfExists(packageJsonPath) : "";
     const hasGraphqlRuntime = /graphql-yoga|graphql|apollo-server|@apollo\/server/.test(packageText || "");
     return {
@@ -220,7 +220,7 @@ export const graphQlSdlExtractor = {
   },
   extract(context) {
     const schemaSources = extractGraphqlSchemaSources(context);
-    const endpointPath = inferEndpointPath(context, findImportFiles(context.paths, (filePath) => /\/src\/.+\.(ts|tsx|js|jsx)$/i.test(filePath)));
+    const endpointPath = inferEndpointPath(context, findPrimaryImportFiles(context.paths, (filePath) => /\/src\/.+\.(ts|tsx|js|jsx)$/i.test(filePath)));
     const mergedSchema = schemaSources.map(({ schema }) => schema).join("\n\n");
     const blocks = parseGraphqlSchemaBlocks(mergedSchema);
     const inputTypes = new Map([...blocks.entries()].filter(([, block]) => block.kind === "input"));