@codeyam/codeyam-cli 0.1.0-staging.4c0c3c9 → 0.1.0-staging.5370992

package/analyzer-template/packages/ai/src/lib/generateEntityScenarioData.ts

@@ -19,6 +19,8 @@ import convertNullToUndefinedBySchema from './dataStructure/helpers/convertNullT
 import convertTypeAnnotationsToValues from './dataStructure/helpers/convertTypeAnnotationsToValues';
 import fixNullIdsBySchema from './dataStructure/helpers/fixNullIdsBySchema';
 import coerceObjectsToPrimitivesBySchema from './dataStructure/helpers/coerceObjectsToPrimitivesBySchema';
+import coercePrimitivesToArraysBySchema from './dataStructure/helpers/coercePrimitivesToArraysBySchema';
+import stripNullableMarkers from './dataStructure/helpers/stripNullableMarkers';
 import { JsonTypeDefinition } from '~codeyam/types';
 import { deepMerge } from '~codeyam/generate';
 import {
@@ -172,6 +174,46 @@ function findKeyPath(
   return null;
 }
 
+/**
+ * Strip primitive values from `source` when the `destination` already has an
+ * array or object at the same key. Returns a cleaned copy of source (or null
+ * if nothing remains after stripping).
+ *
+ * This prevents misplaced LLM data (e.g., `{ webapps: true }`) from
+ * overwriting correct complex values (e.g., `{ webapps: [...] }`) during
+ * deep merge in relocateMisplacedNestedKeys.
+ */
+function stripPrimitivesOverwritingComplexValues(
+  destination: Record<string, unknown>,
+  source: unknown,
+): Record<string, unknown> | null {
+  if (typeof source !== 'object' || source === null || Array.isArray(source)) {
+    return null;
+  }
+
+  const result: Record<string, unknown> = {};
+  let hasKeys = false;
+
+  for (const key of Object.keys(source as Record<string, unknown>)) {
+    const srcVal = (source as Record<string, unknown>)[key];
+    const dstVal = destination[key];
+
+    // If destination has an array or object but source has a primitive, skip it
+    if (
+      typeof dstVal === 'object' &&
+      dstVal !== null &&
+      typeof srcVal !== 'object'
+    ) {
+      continue;
+    }
+
+    result[key] = srcVal;
+    hasKeys = true;
+  }
+
+  return hasKeys ? result : null;
+}
+
 /**
  * Relocate misplaced nested keys in mockData to their correct position
  * based on the dataForMocks structure.
@@ -233,12 +275,22 @@ function relocateMisplacedNestedKeys(
     }
 
     // Deep merge the value into the correct location
-    // Use deep merge to preserve existing data at that location
+    // Use deep merge to preserve existing data at that location.
+    // Before merging, strip primitives from the misplaced value that would
+    // overwrite arrays/objects at the destination. The misplaced data is lower
+    // quality — the LLM put it in the wrong place — so primitives like `true`
+    // should not overwrite correct complex values like arrays.
     if (current[key] !== undefined && typeof current[key] === 'object') {
-      current[key] = deepMerge(
+      const safeValue = stripPrimitivesOverwritingComplexValues(
         current[key] as Record<string, unknown>,
         value as Record<string, unknown>,
       );
+      if (safeValue !== null) {
+        current[key] = deepMerge(
+          current[key] as Record<string, unknown>,
+          safeValue,
+        );
+      }
     } else {
       current[key] = value;
     }
@@ -1063,6 +1115,18 @@ export async function generateDataForScenario({
     );
   }
 
+  // Strip _nullable markers from LLM-generated mock data.
+  // The _nullable marker is an internal CodeYam concept used in type definitions
+  // to indicate that a field can be null/undefined. The LLM sometimes includes
+  // these markers in its generated data, which causes runtime errors when code
+  // iterates over object keys (e.g., Object.keys(importedBy) picks up "_nullable",
+  // then Object.keys(importedBy["_nullable"]) calls Object.keys(null) and throws).
+  if (fullScenarioData.data.mockData) {
+    stripNullableMarkers(
+      fullScenarioData.data.mockData as Record<string, unknown>,
+    );
+  }
+
   // Relocate misplaced nested keys to their correct position.
   // The LLM sometimes places nested keys at root level instead of inside their
   // parent object (e.g., 'fastener' at root instead of inside 'trpc').
@@ -1098,6 +1162,18 @@ export async function generateDataForScenario({
     );
   }
 
+  // Coerce primitives to empty arrays when the schema expects an array.
+  // The LLM sometimes generates a primitive (e.g., `webapps: true`) where the
+  // schema expects an array (e.g., `webapps: [{ name: "string" }]`).
+  // This causes runtime errors like "TypeError: config.webapps?.forEach is not a function".
+  // Must run AFTER coerceObjectsToPrimitivesBySchema and BEFORE convertCommaSeparatedStringsToArrays.
+  if (structure.dataForMocks && fullScenarioData.data.mockData) {
+    coercePrimitivesToArraysBySchema(
+      fullScenarioData.data.mockData,
+      structure.dataForMocks,
+    );
+  }
+
   // Convert comma-separated strings to arrays when appropriate.
   // The LLM sometimes generates strings like "color,size" instead of arrays
   // like ["color", "size"] when the schema type is incorrectly inferred as

package/analyzer-template/packages/ai/src/lib/generateExecutionFlows.ts

@@ -32,6 +32,30 @@ import resolvePathToControllable from './resolvePathToControllable';
 import { AI } from '~codeyam/ai';
 import type { JsxRenderingUsage, ConditionalUsage } from './astScopes/types';
 
+/**
+ * Patterns that indicate a child component is a modal/overlay/blocking element.
+ * Same patterns used in generateExecutionFlowsFromConditionalEffects.ts for
+ * state variable names — here applied to child component names.
+ */
+const BLOCKING_CHILD_PATTERNS = [
+  /modal/i,
+  /overlay/i,
+  /dialog/i,
+  /popup/i,
+  /drawer/i,
+  /sheet/i,
+  /lightbox/i,
+  /backdrop/i,
+];
+
+/**
+ * Check if a child component name suggests it's a blocking/modal element.
+ * Exported for testing.
+ */
+export function isBlockingChildComponent(componentName: string): boolean {
+  return BLOCKING_CHILD_PATTERNS.some((pattern) => pattern.test(componentName));
+}
+
 interface GenerateExecutionFlowsArgs {
   entity: Pick<Entity, 'sha' | 'name' | 'filePath' | 'code' | 'metadata'>;
   mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>;
@@ -105,19 +129,6 @@ export default function generateExecutionFlows({
     fullToShortPathMap[fullPath] = shortPath;
   }
 
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: attributesMap has ${Object.keys(resolvedAttributesMap).length} keys, fullToShortPathMap has ${Object.keys(fullToShortPathMap).length} entries`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: attributesMap keys: [${Object.keys(resolvedAttributesMap).join(', ')}]`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: fullToShortPathMap: ${JSON.stringify(fullToShortPathMap)}`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: equivalentSignatureVariables: ${JSON.stringify(equivalentSignatureVariables)}`,
-  );
-
   // Get pre-computed conditional data from metadata
   const conditionalUsages: Record<string, ConditionalUsage[]> =
     entity.metadata?.isolatedDataStructure?.conditionalUsages ?? {};
@@ -162,26 +173,6 @@ export default function generateExecutionFlows({
     }
   }
 
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: conditionalUsages keys: [${Object.keys(conditionalUsages).join(', ')}]`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: conditionalUsages sourceDataPaths: ${JSON.stringify(
-      Object.fromEntries(
-        Object.entries(conditionalUsages).map(([k, v]) => [
-          k,
-          (v as any[]).map((u: any) => u.sourceDataPath ?? '(none)'),
-        ]),
-      ),
-    )}`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: compoundConditionals count: ${compoundConditionals.length}`,
-  );
-  console.log(
-    `[generateExecutionFlows] ${entity.name}: sourceEquivalencies keys count: ${Object.keys(mergedDataStructure.sourceEquivalencies ?? {}).length}`,
-  );
-
   const conditionalsBasedFlows = generateExecutionFlowsFromConditionals({
     conditionalUsages,
     compoundConditionals,
@@ -273,6 +264,11 @@ export default function generateExecutionFlows({
     calculateFlowPriority(flow, gatingPathToChildren);
   }
 
+  // Assign exclusiveGroup for truthy/falsy flow pairs that control child components.
+  // When the same gating path produces both a truthy flow (show component) and a
+  // falsy flow (hide component), they are mutually exclusive and should be grouped.
+  assignExclusiveGroupsForGatingPairs(allFlows);
+
   // Sort flows by priority (highest first)
   allFlows.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 
@@ -361,6 +357,60 @@ function buildGatingPathToChildrenMap(
   return gatingPathToChildren;
 }
 
+/**
+ * Assign exclusiveGroup for truthy/falsy flow pairs that control child components.
+ *
+ * When the same attribute path produces both a truthy and falsy flow (e.g.,
+ * {diffView && <DiffModal/>}), they are mutually exclusive — only one can be
+ * active at a time. Grouping them ensures the scenario generator treats them
+ * as alternative states rather than combining them.
+ */
+function assignExclusiveGroupsForGatingPairs(flows: ExecutionFlow[]): void {
+  // Build a map: attributePath -> flows with truthy or falsy comparison for that path
+  const pathToFlows = new Map<
+    string,
+    { truthy: ExecutionFlow[]; falsy: ExecutionFlow[] }
+  >();
+
+  for (const flow of flows) {
+    // Only consider flows that control child components
+    if (!flow.childComponentsControlled?.length) continue;
+
+    for (const rv of flow.requiredValues) {
+      if (rv.comparison === 'truthy' || rv.comparison === 'falsy') {
+        if (!pathToFlows.has(rv.attributePath)) {
+          pathToFlows.set(rv.attributePath, { truthy: [], falsy: [] });
+        }
+        pathToFlows.get(rv.attributePath)![rv.comparison].push(flow);
+      }
+    }
+  }
+
+  // Also check falsy flows that DON'T have childComponentsControlled —
+  // they still pair with truthy flows that do
+  for (const flow of flows) {
+    if (flow.childComponentsControlled?.length) continue; // Already processed
+
+    for (const rv of flow.requiredValues) {
+      if (rv.comparison === 'falsy' && pathToFlows.has(rv.attributePath)) {
+        pathToFlows.get(rv.attributePath)!.falsy.push(flow);
+      }
+    }
+  }
+
+  // Assign exclusiveGroup where both truthy and falsy flows exist
+  for (const [attributePath, { truthy, falsy }] of pathToFlows) {
+    if (truthy.length > 0 && falsy.length > 0) {
+      const groupName = `gating:${attributePath}`;
+      for (const flow of [...truthy, ...falsy]) {
+        if (!flow.exclusiveGroup) {
+          flow.exclusiveGroup = groupName;
+        }
+      }
+    }
+  }
+}
+
 /**
  * Calculate priority and childComponentsControlled for a flow.
  *
@@ -415,6 +465,19 @@ function calculateFlowPriority(
     if (flow.impact !== 'high') {
       flow.impact = 'high';
     }
+
+    // Check if any controlled child component is a modal/dialog/overlay.
+    // Only truthy flows (which SHOW the component) should be marked as blocking.
+    // Falsy flows (which HIDE the component) should not be blocking.
+    const isTruthyFlow = flow.requiredValues.some(
+      (rv) => rv.comparison === 'truthy' || rv.comparison === 'equals',
+    );
+    if (
+      isTruthyFlow &&
+      Array.from(childComponentsControlled).some(isBlockingChildComponent)
+    ) {
+      flow.blocksOtherFlows = true;
+    }
   }
 
   // Calculate priority score

package/analyzer-template/packages/analyze/index.ts

@@ -36,7 +36,10 @@ export { getAllEntityNodes } from './src/lib/asts/sourceFiles/getAllEntityNodes'
 export { default as fileAnalyzerFromCode } from './src/lib/files/fileAnalyzerFromCode';
 
 export { default as isolateDataStructure } from './src/lib/files/scenarios/isolateDataStructure';
-export { default as mergeInDependentDataStructure } from './src/lib/files/scenarios/mergeInDependentDataStructure';
+export {
+  default as mergeInDependentDataStructure,
+  DataStructureTimeoutError,
+} from './src/lib/files/scenarios/mergeInDependentDataStructure';
 export { default as mergeValidatedDataStructures } from './src/lib/files/scenarios/mergeValidatedDataStructures';
 
 export { discoverDirectDependencies } from './src/lib/files/analyze/dependencyResolver';

package/analyzer-template/packages/analyze/src/lib/ProjectAnalyzer.ts

@@ -46,6 +46,12 @@ export class ProjectAnalyzer {
       lib.asts.createProgramFromTsConfigPath(configPath, excludePatterns),
     );
 
+    if (this.programs.length === 0) {
+      throw new Error(
+        'No TypeScript programs could be created — no tsconfig.json found',
+      );
+    }
+
     // Primary program is the first one (usually root) for backward compatibility
     this.program = this.programs[0];
     this.typeChecker = this.program.getTypeChecker();
@@ -334,17 +340,23 @@ export class ProjectAnalyzer {
    * Refresh the TypeScript program to pick up file changes
    */
   refreshProgram(): void {
-    // Memory logging: Capture state before refresh
-    const memBefore = process.memoryUsage();
-
     // Apply the same unapprovedPaths filtering when refreshing
     const excludePatterns =
       this.project.metadata?.unapprovedPaths?.filter(Boolean) || [];
 
-    // Refresh all programs
-    this.programs = this.tsConfigPaths.map((configPath) =>
-      lib.asts.createProgramFromTsConfigPath(configPath, excludePatterns),
-    );
+    // Release old programs and caches BEFORE creating new ones to reduce peak memory.
+    // Without this, both old (~1.7GB) and new (~1.7GB) programs coexist during creation,
+    // causing OOM on monorepos with multiple tsconfigs.
+    this.programs = [];
+    this.sourceFileByPath.clear();
+    this.typeCheckerByPath.clear();
+
+    // Create programs one at a time so each old program can be GC'd before the next
+    for (const configPath of this.tsConfigPaths) {
+      this.programs.push(
+        lib.asts.createProgramFromTsConfigPath(configPath, excludePatterns),
+      );
+    }
 
     // Update primary program for backward compatibility
     this.program = this.programs[0];

package/analyzer-template/packages/analyze/src/lib/asts/index.ts

@@ -95,8 +95,13 @@ export function createProgramFromTsConfigPath(
     throw new Error('Could not parse tsconfig.json');
   }
 
-  // Filter file names based on exclude patterns to reduce memory usage
-  let fileNames = parsedCommandLine.fileNames;
+  // Always filter out node_modules from root files to prevent OOM on large projects.
+  // This only removes them as root compilation targets — TypeScript's module resolution
+  // still follows imports into node_modules for type info when processing source files.
+  let fileNames = parsedCommandLine.fileNames.filter(
+    (f) => !f.includes('/node_modules/'),
+  );
+
   if (excludePatterns && excludePatterns.length > 0) {
     const regexPatterns = excludePatterns
       .map((pattern) => {

package/analyzer-template/packages/analyze/src/lib/asts/nodes/getNodeType.ts

@@ -39,6 +39,7 @@ export function getNodeType(node: ts.Node, sourceFile: ts.SourceFile) {
     case 'StringLiteral':
     case 'NumericLiteral':
     case 'ObjectLiteralExpression':
+    case 'ArrayLiteralExpression':
       nodeType = 'data';
       break;
     case 'TypeAliasDeclaration':

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities/prepareDataStructures.ts

@@ -289,18 +289,44 @@ export default async function prepareEntityDataStructures(
     skipWorkerPool();
   }
 
+  awsLogDebugLevel(
+    1,
+    `Preparing data structures for ${entities.length} entities (${entitiesNeedingGeneration} need generation)...`,
+  );
+  const startTime = Date.now();
+  let completedCount = 0;
+
+  // Wrap processEntity to track progress
+  const processEntityWithProgress = async (entity: Entity) => {
+    await processEntity(entity);
+    completedCount++;
+    // Emit progress every 10 entities
+    if (completedCount % 10 === 0) {
+      awsLogDebugLevel(
+        1,
+        `Preparing data structures... (${completedCount}/${entities.length})`,
+      );
+    }
+  };
+
   const sequential =
     DEBUG_SEQUENTIAL_EXECUTION || options.sequentialDataStructurePrep;
 
   if (sequential) {
     // Sequential execution for debugging - process one entity at a time
     for (const entity of entities) {
-      await processEntity(entity);
+      await processEntityWithProgress(entity);
     }
   } else {
     // Parallel execution for speed
-    await Promise.all(entities.map(processEntity));
+    await Promise.all(entities.map(processEntityWithProgress));
   }
+
+  const elapsed = Date.now() - startTime;
+  awsLogDebugLevel(
+    1,
+    `Data structure preparation complete: ${entities.length} entities in ${elapsed}ms`,
+  );
 }
 
 /**

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities.ts

@@ -8,13 +8,11 @@ import {
 import { transformationTracer } from '../scenarios/TransformationTracer';
 import { getFileByPathSafe } from '../../utils/getFileByPath';
 import trackEntityCircularDependencies from './trackEntityCircularDependencies';
-import validateDependencyAnalyses from './validateDependencyAnalyses';
 import extractClassMethods from './analyzeEntities/extractClassMethods';
 import prepareDataStructures from './analyzeEntities/prepareDataStructures';
 import { strategies, asyncComplex } from './analyzeEntities/strategies';
 import {
   updateCommitMetadata,
-  updateFreshAnalysisMetadata,
   updateFreshAnalysisStatus,
   upsertAnalyses,
   upsertEntities,
@@ -263,40 +261,11 @@ export default async function analyzeEntities({
     }
   }
 
-  awsLog(`CodeYam: analyzeEntities: Running patch-up dependency validation`);
-  for (const analysis of analyses) {
-    if (!analysis.entity) {
-      throw new Error(
-        `CodeYam: analyzeEntities: Internal error: Analysis entity is missing for ${analysis.filePath}:${analysis.entityName}.`,
-      );
-    }
-
-    // Validate dependencies, which modifies analysis.metadata.dependentAnalyses
-    validateDependencyAnalyses({ analysis, entity: analysis.entity, context });
-
-    // Carefully update only the metadata field
-    if (analysis.id) {
-      const updatedMetadata = await updateFreshAnalysisMetadata(
-        analysis.id,
-        (metadata) => {
-          metadata.dependentAnalyses =
-            analysis.metadata?.dependentAnalyses || [];
-        },
-      );
-
-      if (updatedMetadata) {
-        analysis.metadata = updatedMetadata;
-      } else {
-        console.warn(
-          `CodeYam: analyzeEntities: Failed to update metadata for analysis ${analysis.id}`,
-        );
-      }
-    } else {
-      console.warn(
-        `CodeYam: analyzeEntities: Analysis ${analysis.filePath}:${analysis.entityName} has no ID, skipping metadata update`,
-      );
-    }
-  }
+  // NOTE: patch-up dependency validation loop was removed here.
+  // analysis.metadata.dependentAnalyses is already populated by validateDependencyAnalyses
+  // inside analyzeEntity() (Call #1) and persisted via upsertAnalysesWithScenarios at the
+  // end of analyzeEntity, then again by upsertAnalyses in analyzeOneEntityKey. Re-validating
+  // every analysis from scratch was redundant work — especially costly for large projects.
 
   const newlyReady = await updateReadyAnalyses();
   if (newlyReady.length > 0) {
@@ -310,7 +279,15 @@ export default async function analyzeEntities({
   );
 
   // Flush transformation trace if tracing is enabled
-  transformationTracer.flush();
+  // Wrapped in try/catch because trace data can exceed V8's max string length
+  // for large projects, and we must not crash the analysis process over tracing.
+  try {
+    transformationTracer.flush();
+  } catch (e) {
+    console.warn(
+      `CodeYam Warning: Failed to flush transformation trace: ${e.message}`,
+    );
+  }
 
   return analyses;
 

package/analyzer-template/packages/analyze/src/lib/files/analyze/dependencyResolver.ts

@@ -100,12 +100,6 @@ export function getCandidatesReadyForCapture(
       continue;
     }
 
-    // Skip notExported entities - they can't be imported into the simulation
-    // environment and will always fail capture. Don't mark them as ready.
-    if (candidate.entity?.metadata?.notExported) {
-      continue;
-    }
-
     // Get all transitive dependencies
     const candidateKey = `${candidate.filePath}:${candidate.entityName}`;
     const { missingDependencies } = getTransitiveDependencies(

package/analyzer-template/packages/analyze/src/lib/files/analyze/findOrCreateEntity.ts

@@ -94,12 +94,15 @@ export default async function findOrCreateEntity({
   try {
     code = fileAnalyzer.getEntityCode(localEntityName);
   } catch (e) {
-    console.log('CodeYam Error: could not get entity code', {
-      filePath: file.path,
-      localEntityName,
-      entityName,
-      error: e,
-    });
+    console.log(
+      `CodeYam Error: Could not extract code for "${localEntityName}" from ${file.path} — export not found in file, may have been moved or renamed during refactoring`,
+      {
+        filePath: file.path,
+        localEntityName,
+        entityName,
+        error: String(e),
+      },
+    );
     return null;
   }
   const sha = generateSha(file.path, entityName, code);
@@ -108,6 +111,7 @@ export default async function findOrCreateEntity({
     entity = await loadEntity({
       projectId: project.id,
       sha,
+      silent: true, // Entity not existing yet is the normal path — we create it below
     });
   }
 
@@ -138,6 +142,18 @@ export default async function findOrCreateEntity({
           break;
         }
       }
+
+      // Mark previous versions as superseded
+      const entitiesToSupersede = previousEntities.filter(
+        (e) => !e.metadata?.isSuperseded,
+      );
+      if (entitiesToSupersede.length > 0) {
+        for (const prev of entitiesToSupersede) {
+          prev.metadata = prev.metadata || {};
+          prev.metadata.isSuperseded = true;
+        }
+        await upsertEntities(entitiesToSupersede);
+      }
     }
 
     entity = {

package/analyzer-template/packages/analyze/src/lib/files/analyze/gatherEntityMap.ts

@@ -111,18 +111,15 @@ export default async function gatherEntityMap({
       });
 
       if (!importedEntity) {
-        console.log(
-          `CodeYam Error: Entity not found while gathering entity map: ${importedFile.path}: ${importedExportName}`,
-          {
-            entityName: entity.name,
-            entityFilePath: entity.filePath,
-            importedFilePath: importedFile.path,
-            importedExportName: importedExportName,
-          },
-        );
-        throw new Error(
-          `Entity not found while gathering entity map: ${importedFile.path}: ${importedExport.name}`,
-        );
+        const msg = [
+          `Entity not found: "${importedExportName}" in ${importedFile.path}`,
+          `  While analyzing dependencies of: ${entity.name} (${entity.filePath})`,
+          `  This usually means "${importedExportName}" was moved or renamed but`,
+          `  ${entity.filePath} still has stale import metadata referencing the old location.`,
+          `  Fix: Update or re-analyze ${entity.filePath} so its importedExports reflect current code.`,
+        ].join('\n');
+        console.log(`CodeYam Error: ${msg}`);
+        throw new Error(msg);
       }
 
       // Add newly created entity to context

package/analyzer-template/packages/analyze/src/lib/files/analyze/trackEntityCircularDependencies.ts

@@ -1,5 +1,6 @@
 import type { Entity } from '~codeyam/types';
 import { AnalysisContext } from '../../analysisContext';
+import { awsLogDebugLevel } from '~codeyam/utils';
 
 /**
  * Optimized version that processes multiple root entities in a single traversal.
@@ -16,6 +17,8 @@ export default function trackEntityCircularDependencies(
   try {
     const allEntities = new Set<Entity>();
     const globalVisited = new Set<string>(); // Track by SHA to avoid duplicate traversals
+    let circularCount = 0;
+    const startTime = Date.now();
 
     // Process each root entity, but skip if already processed
     for (const rootEntity of rootEntities) {
@@ -32,8 +35,26 @@ export default function trackEntityCircularDependencies(
         globalVisited,
         allEntities,
       );
+
+      // Emit periodic progress for large projects
+      if (allEntities.size % 100 === 0 && allEntities.size > 0) {
+        awsLogDebugLevel(
+          1,
+          `Mapping dependencies... (${allEntities.size} entities discovered)`,
+        );
+      }
     }
 
+    const elapsed = Date.now() - startTime;
+    // Count circular deps
+    for (const entity of allEntities) {
+      if (entity.metadata?.hasCircularDependency) circularCount++;
+    }
+    awsLogDebugLevel(
+      1,
+      `Dependency mapping complete: ${allEntities.size} entities, ${circularCount} circular, ${elapsed}ms`,
+    );
+
     return allEntities;
   } catch (e) {
     console.log(