@codeyam/codeyam-cli 0.1.21 → 0.1.23

package/analyzer-template/.build-info.json

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-03-23T18:15:43.332Z",
-  "buildTime": 1774289743332,
-  "gitCommit": "56a7e07b8443b0a3e64a46dc6ba44404297a9a2e",
+  "buildTimestamp": "2026-03-25T14:20:38.638Z",
+  "buildTime": 1774448438638,
+  "gitCommit": "c7c95ab59975fd59b8a33c1299058ba1fca32a62",
   "nodeVersion": "v20.20.1",
-  "contentHash": "6c4394ec0578dec94ea4076bc8417fa3e6c6cbcad956c30ed107dcaeaa37e131",
-  "buildNumber": 1193,
-  "semanticVersion": "0.1.1193",
-  "version": "0.1.1193 (2026-03-23T18:15+6c4394e)"
+  "contentHash": "1ef6e4857c54ba0e5ddecacacdd26bdc64e7a25cd41e9f154b5ea6e3cd5525dc",
+  "buildNumber": 1223,
+  "semanticVersion": "0.1.1223",
+  "version": "0.1.1223 (2026-03-25T14:20+1ef6e48)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[3/23/2026, 6:15:43 PM] > codeyam-combo@1.0.0 mergeDependencies
-[3/23/2026, 6:15:43 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[3/25/2026, 2:20:38 PM] > codeyam-combo@1.0.0 mergeDependencies
+[3/25/2026, 2:20:38 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[3/23/2026, 6:15:43 PM] Merged dependencies into root package.json
+[3/25/2026, 2:20:38 PM] Merged dependencies into root package.json
 

package/analyzer-template/packages/ai/src/lib/astScopes/methodSemantics.ts

@@ -895,6 +895,132 @@ export class UseStateSemantics implements MethodSemantics {
   }
 }
 
+// ─── Set/Map method semantics ──────────────────────────────────────────
+//
+// Set/Map membership operations (.has, .delete, .add, .get, .set, .clear)
+// don't create data flow equivalencies — they're membership checks or
+// mutations, not transformations that propagate schema structure.
+// Without these semantics, code like `filterRatings.has(articleId)` creates
+// spurious equivalencies (332 entries in the Margo LibraryPage case).
+
+/**
+ * Set.has() / Map.has() — membership check, returns boolean
+ */
+export class CollectionHasSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'boolean';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    _sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    context.addType(methodCallPath, 'boolean');
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Set.delete() / Map.delete() — removal, returns boolean
+ */
+export class CollectionDeleteSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'boolean';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    _sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    context.addType(methodCallPath, 'boolean');
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Set.add() — adds an element, returns the Set (for chaining)
+ */
+export class SetAddSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'object'; // Returns the Set itself
+  }
+
+  addEquivalences(
+    _methodCallPath: StructuredPath,
+    _sourcePath: StructuredPath,
+    _context: AnalysisContext,
+  ): void {
+    // No equivalencies — add() doesn't create data flow
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Set.clear() / Map.clear() — removes all elements, returns void
+ */
+export class CollectionClearSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'void';
+  }
+
+  addEquivalences(): void {
+    // No equivalencies
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Map.get() — retrieves a value by key, returns unknown (value type)
+ */
+export class MapGetSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'unknown';
+  }
+
+  addEquivalences(
+    _methodCallPath: StructuredPath,
+    _sourcePath: StructuredPath,
+    _context: AnalysisContext,
+  ): void {
+    // No equivalencies — the return value type depends on the map contents
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Map.set() — sets a key-value pair, returns the Map (for chaining)
+ */
+export class MapSetSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'object'; // Returns the Map itself
+  }
+
+  addEquivalences(): void {
+    // No equivalencies
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
 /**
  * Create and populate the registry with method semantics
  */
@@ -930,6 +1056,15 @@ export function createMethodRegistry(): MethodSemanticsRegistry {
   registry.register('useState', new UseStateSemantics(), 'React');
   registry.register('useMemo', new UseMemoSemantics(), 'React');
 
+  // Register Set/Map collection methods.
+  // Only .has() and .delete() are safe to register by method name — they always
+  // return boolean regardless of the collection type (Set, Map, WeakSet, WeakMap,
+  // FormData, URLSearchParams, etc.).
+  // .add(), .clear(), .get(), .set() are too ambiguous across different types
+  // and can't be registered until the lookup code supports class-aware resolution.
+  registry.register('has', new CollectionHasSemantics());
+  registry.register('delete', new CollectionDeleteSemantics());
+
   return registry;
 }
 

package/analyzer-template/packages/ai/src/lib/astScopes/nodeToSource.ts

@@ -54,6 +54,25 @@ export function nodeToSource(
   //   return serializeBindingElement(node, sourceFile, options);
   // }
 
+  // Object/array/function literals should be marked as literal paths.
+  // This prevents them from creating sourceEquivalencies when used as
+  // function call arguments (e.g., setUndoEntry({ label: '...', undo: ... })).
+  // Without this, the full source text of the literal (300-500 chars for complex
+  // objects) gets embedded in path strings, creating expensive-to-parse
+  // equivalency entries that don't contribute useful schema information.
+  if (ts.isObjectLiteralExpression(node)) {
+    return StructuredPath.createLiteralPath(node.getText(sourceFile), 'object');
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return StructuredPath.createLiteralPath(node.getText(sourceFile), 'array');
+  }
+  if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+    return StructuredPath.createLiteralPath(
+      node.getText(sourceFile),
+      'function',
+    );
+  }
+
   // Fallback for unsupported node types
   return StructuredPath.fromBase(node.getText(sourceFile));
 }

package/analyzer-template/packages/ai/src/lib/astScopes/paths.ts

@@ -406,11 +406,18 @@ export class StructuredPath {
           } else {
             // Convert each argument to its string representation
             const argsStr = funcSegment.args
-              .map((arg) =>
-                arg.toStringWithSegments(arg.base, arg.segments, {
+              .map((arg) => {
+                // For literal arguments (object/array/function literals),
+                // use a compact placeholder instead of the full source text.
+                // This prevents 300-500 char inline objects from being embedded
+                // in call signature paths, which creates expensive equivalencies.
+                if (arg.isLiteral()) {
+                  return `{...}`;
+                }
+                return arg.toStringWithSegments(arg.base, arg.segments, {
                   withReturnValues: doRenderNestedFunctionCallReturnValue,
-                }),
-              )
+                });
+              })
               .join(', ');
             result += `(${argsStr})`;
           }

package/analyzer-template/packages/ai/src/lib/dataStructure/ScopeDataStructure.ts

@@ -398,6 +398,7 @@ const SILENTLY_IGNORED_EQUIVALENCY_REASONS = new Set([
   'transformed non-object function equivalency - Array.from() equivalency',
   'Spread operator equivalency key update: Explicit array deconstruction equivalency value',
   // 'transformed non-object function equivalency - Explicit array deconstruction equivalency value',
+  'useState setter call equivalency (direct)',
 ]);
 
 export class ScopeDataStructure {
@@ -1048,6 +1049,31 @@ export class ScopeDataStructure {
     equivalencyValueChain?: EquivalencyValueChainItem[],
     traceId?: number,
   ) {
+    // Fast early exits that don't count toward the limit.
+    // These are "no-op" calls that would be caught further below anyway,
+    // but checking them first prevents counter inflation from redundant calls
+    // generated by managers and followEquivalencies during scope processing.
+
+    // Skip silently-ignored reasons before counting
+    if (SILENTLY_IGNORED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
+      return;
+    }
+
+    // Skip exact duplicates before counting (Phase 1 only — Phase 2 needs
+    // to process duplicates for database chain tracking)
+    if (this.onlyEquivalencies) {
+      const existing = scopeNode.equivalencies[path];
+      if (
+        existing?.some(
+          (v) =>
+            v.schemaPath === equivalentPath &&
+            v.scopeNodeName === equivalentScopeName,
+        )
+      ) {
+        return;
+      }
+    }
+
     addEquivalencyCallCount++;
 
     const limit =
@@ -1069,14 +1095,11 @@ export class ScopeDataStructure {
     }
     // Filter equivalency reasons - use pre-computed Sets for O(1) lookup
     if (!ALLOWED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
-      if (SILENTLY_IGNORED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
-        return;
-      } else {
-        // Log and skip - if an equivalency reason isn't in ALLOWED or SILENTLY_IGNORED,
-        // it shouldn't be stored (was previously missing the return)
-        console.info('Not tracked equivalency reason', { equivalencyReason });
-        return;
-      }
+      // Silently-ignored reasons already handled above
+      // Log and skip - if an equivalency reason isn't in ALLOWED or SILENTLY_IGNORED,
+      // it shouldn't be stored (was previously missing the return)
+      console.info('Not tracked equivalency reason', { equivalencyReason });
+      return;
     }
 
     // Skip self-referential equivalencies that would create infinite loops.

package/analyzer-template/packages/ai/src/lib/dataStructure/equivalencyManagers/ParentScopeManager.ts

@@ -97,6 +97,16 @@ export default class ParentScopeManager implements EquivalencyManager {
       }
 
       if (instantiatedInParent || returnValueFromChildScope) {
+        // Skip if we've already propagated this variable to the parent scope.
+        // Without this guard, nested scopes trigger redundant addEquivalency calls
+        // for the same variable on every addToSchema pass (e.g., 'a' and 'b' in sort
+        // callbacks get propagated 30+ times per scope instead of once).
+        this.addedToParent[scopeNode.name] ||= new Set<string>();
+        if (this.addedToParent[scopeNode.name].has(rootPath)) {
+          return false;
+        }
+        this.addedToParent[scopeNode.name].add(rootPath);
+
         if (traceId && debugLevel > 0) {
           console.info(
             'Debug Propagation: parentScope executed',
@@ -114,9 +124,6 @@ export default class ParentScopeManager implements EquivalencyManager {
           );
         }
 
-        this.addedToParent[scopeNode.name] ||= new Set<string>();
-        this.addedToParent[scopeNode.name].add(rootPath);
-
         scopeDataStructure.addEquivalency(
           rootPath,
           rootPath,

package/analyzer-template/packages/ai/src/lib/dataStructure/helpers/cleanKnownObjectFunctions.ts

@@ -6,7 +6,7 @@ import { ScopeNode, ScopeDataStructure } from '../ScopeDataStructure';
 
 type PrimitiveKind = 'array' | 'string' | 'number' | 'boolean' | 'date';
 
-const IGNORE_CLASSES_AND_OBJECTS = [
+const IGNORE_CLASSES_AND_OBJECTS_SET = new Set([
   'Math',
   'JSON',
   'Reflect',
@@ -22,7 +22,7 @@ const IGNORE_CLASSES_AND_OBJECTS = [
   'useContext',
   'useReducer',
   'useLayoutEffect',
-];
+]);
 
 /** cache the tokenised representation of every path we touch */
 const partsCache = new Map<string, string[]>();
@@ -147,16 +147,26 @@ function scrub(
   rootTable: Map<string, PrimitiveKind>,
   onRemove: (key: string) => void,
 ): void {
-  const sortedKeys = Object.keys(mapping).sort((a, b) => a.localeCompare(b));
+  // Early exit: if no primitive types exist in the schema, there are no
+  // built-in methods to clean. Saves sorting + walking 10K+ keys.
+  if (rootTable.size === 0) return;
+
+  // Use direct comparison instead of localeCompare (3-5x faster for large arrays)
+  const sortedKeys = Object.keys(mapping).sort((a, b) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  );
 
   for (const keyPath of sortedKeys) {
     const keyParts = getParts(keyPath);
     const prefixParts = buildPrefixParts(keyParts);
 
+    const firstPart = keyParts[0];
+    const firstPartBase = firstPart.includes('(')
+      ? firstPart.split('(')[0]
+      : firstPart;
     if (
-      IGNORE_CLASSES_AND_OBJECTS.find(
-        (m) => keyParts[0] === m || keyParts[0].startsWith(`${m}(`),
-      )
+      IGNORE_CLASSES_AND_OBJECTS_SET.has(firstPart) ||
+      IGNORE_CLASSES_AND_OBJECTS_SET.has(firstPartBase)
     ) {
       delete mapping[keyPath];
       continue;

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/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) {

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(