@codeyam/codeyam-cli 0.1.0-staging.6e699e5 → 0.1.0-staging.79ef713

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-01-27T18:35:02.170Z",
-  "buildTime": 1769538902170,
-  "gitCommit": "6e699e56ee4e2c0efa0086ccf7268b040394c2c2",
+  "buildTimestamp": "2026-02-09T23:40:32.703Z",
+  "buildTime": 1770680432703,
+  "gitCommit": "79ef713db8aedbd08bf0e42c7aa8b6f99117bbdb",
   "nodeVersion": "v20.20.0",
-  "contentHash": "cce7c765a7074dbbc87cc66ff68e4de45336dce2e768af7373c978f5db3afe4d",
-  "buildNumber": 522,
-  "semanticVersion": "0.1.522",
-  "version": "0.1.522 (2026-01-27T18:35+cce7c76)"
+  "contentHash": "aaa0ef29735f956b90bfc57d268b877db2ba758456e586a28cc3af7e44ea35f1",
+  "buildNumber": 598,
+  "semanticVersion": "0.1.598",
+  "version": "0.1.598 (2026-02-09T23:40+aaa0ef2)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[1/27/2026, 6:35:02 PM] > codeyam-combo@1.0.0 mergeDependencies
-[1/27/2026, 6:35:02 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[2/9/2026, 11:40:32 PM] > codeyam-combo@1.0.0 mergeDependencies
+[2/9/2026, 11:40:32 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[1/27/2026, 6:35:02 PM] Merged dependencies into root package.json
+[2/9/2026, 11:40:32 PM] Merged dependencies into root package.json
 

package/analyzer-template/package.json

@@ -7,7 +7,7 @@
     "build": "tsc && node ./scripts/postbuild.cjs"
   },
   "dependencies": {
-    "@aws-sdk/client-cloudwatch-logs": "^3.966.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.980.0",
     "@aws-sdk/client-cloudfront": "^3.966.0",
     "@aws-sdk/client-codebuild": "^3.948.0",
     "@aws-sdk/client-dynamodb": "^3.956.0",
@@ -30,25 +30,25 @@
     "jest": "^30.2.0",
     "jsdom": "^27.4.0",
     "jsonc-parser": "^3.2.1",
-    "lru-cache": "^11.2.4",
+    "lru-cache": "^11.2.5",
     "openai": "^6.16.0",
     "p-queue": "^8.1.0",
     "p-retry": "^7.1.1",
     "piscina": "^5.1.4",
     "pixelmatch": "^5.3.0",
-    "playwright": "^1.56.1",
+    "playwright": "1.58.0",
     "sharp": "^0.34.5",
     "simple-git": "^3.28.0",
-    "undici": "^7.16.0",
+    "undici": "^7.18.2",
     "uuid": "^11.1.0",
     "pluralize": "^8.0.0",
     "yargs": "^18.0.0",
     "json5": "^2.2.3",
-    "@anthropic-ai/sdk": "^0.71.0",
+    "@anthropic-ai/sdk": "^0.74.0",
     "@aws-sdk/s3-request-presigner": "^3.940.0",
     "better-sqlite3": "^12.4.1",
     "fetch-retry": "^6.0.0",
-    "kysely": "^0.28.5",
+    "kysely": "^0.28.11",
     "pg": "^8.16.3",
     "@octokit/request": "^10.0.3",
     "lucide-react": "^0.556.0",
@@ -64,7 +64,7 @@
     "@types/jest": "^30.0.0",
     "@types/pg": "^8.15.5",
     "@types/ws": "^8.18.1",
-    "@octokit/types": "^15.0.0",
+    "@octokit/types": "^16.0.0",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@types/react-resizable": "^3.0.7",

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

@@ -40,7 +40,10 @@ export { default as describeCodeChange } from './src/lib/describeCodeChange';
 export { default as validateTypeStructure } from './src/lib/validateTypeStructure';
 export { default as validateDataStructure } from './src/lib/validateDataStructure';
 export { default as isolateScopes } from './src/lib/isolateScopes';
-export { default as analyzeScope } from './src/lib/analyzeScope';
+export {
+  default as analyzeScope,
+  destroyWorkerPool,
+} from './src/lib/analyzeScope';
 export { default as logOrderedMap } from './src/lib/logOrderedMap';
 export {
   default as splitOutsideParentheses,
@@ -54,8 +57,13 @@ export {
   removeDuplicateFunctionCalls,
 } from './src/lib/dataStructure/helpers/cleanNonObjectFunctions';
 export { default as convertDotNotation } from './src/lib/dataStructure/helpers/convertDotNotation';
+export { default as convertTypeAnnotationsToValues } from './src/lib/dataStructure/helpers/convertTypeAnnotationsToValues';
 export { default as cleanOutBoundary } from './src/lib/cleanOutBoundary';
-export { fillInDirectSchemaGapsAndUnknowns } from './src/lib/dataStructure/helpers/fillInSchemaGapsAndUnknowns';
+export {
+  fillInDirectSchemaGapsAndUnknowns,
+  buildSchemaIndexes,
+  type SchemaIndexes,
+} from './src/lib/dataStructure/helpers/fillInSchemaGapsAndUnknowns';
 export { default as deduplicateFunctionSchemas } from './src/lib/dataStructure/helpers/deduplicateFunctionSchemas';
 export { default as getConditionalUsagesFromCode } from './src/lib/getConditionalUsagesFromCode';
 export type {

package/analyzer-template/packages/ai/package.json

@@ -9,12 +9,12 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.0",
+    "@anthropic-ai/sdk": "^0.74.0",
     "jsdom": "^27.4.0",
     "p-queue": "^8.1.0",
     "p-retry": "^7.1.1",
     "piscina": "^5.1.4",
-    "lru-cache": "^11.2.4"
+    "lru-cache": "^11.2.5"
   },
   "devDependencies": {
     "@types/jsdom": "^27.0.0"

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

@@ -49,6 +49,7 @@ let workerPool: Piscina<
   AnalyzeScopeWorkerInput,
   AnalyzeScopeWorkerOutput
 > | null = null;
+let workerPoolDestroyed = false;
 
 /**
  * Check if we're in Node.js main thread
@@ -65,11 +66,48 @@ function getIsMainThread(): boolean {
   return isMainThread;
 }
 
+/**
+ * Destroy the worker pool, freeing its ~2GB heap.
+ * Called after data structure preparation completes (the producing phase transition).
+ * The worker is not needed after this point — subsequent calls to ensureWorkerPool() will throw.
+ */
+export async function destroyWorkerPool() {
+  if (workerPool) {
+    const memBefore = process.memoryUsage();
+    console.log('CodeYam: Destroying worker pool...', {
+      rssBefore: `${Math.round(memBefore.rss / 1024 / 1024)}MB`,
+      heapBefore: `${Math.round(memBefore.heapUsed / 1024 / 1024)}MB`,
+    });
+
+    await workerPool.destroy();
+    workerPool = null;
+
+    // Force GC if available to reclaim worker memory faster
+    if (global.gc) {
+      global.gc();
+    }
+
+    const memAfter = process.memoryUsage();
+    console.log('CodeYam: Worker pool destroyed', {
+      rssAfter: `${Math.round(memAfter.rss / 1024 / 1024)}MB`,
+      heapAfter: `${Math.round(memAfter.heapUsed / 1024 / 1024)}MB`,
+      rssDelta: `${Math.round((memAfter.rss - memBefore.rss) / 1024 / 1024)}MB`,
+    });
+  }
+  workerPoolDestroyed = true;
+}
+
 /**
  * Lazy initialization of worker pool.
  * Called on first use to ensure environment variables are set.
  */
 function ensureWorkerPool() {
+  if (workerPoolDestroyed) {
+    throw new Error(
+      'CodeYam: Worker pool was destroyed (post-producing phase). ' +
+        'analyzeScope should not be called after data structure preparation completes.',
+    );
+  }
   if (workerPool !== null) return;
 
   // Only initialize worker pool in Node.js environment
@@ -85,10 +123,17 @@ function ensureWorkerPool() {
   // Note: WORKER_PATH is null when __mocks__/analyzeScope.ts is active
   const { WORKER_PATH } = analyzeScopeWorkerPaths();
 
+  // Disable workers when tracing is enabled - we need access to ScopeDataStructure
+  // instance in the main thread to capture pre-serialization state
+  const tracingEnabled =
+    process.env.CODEYAM_TRACE_TRANSFORMS === '1' ||
+    process.env.CODEYAM_TRACE_TRANSFORMS === 'true';
+
   if (
     process.env.USE_WORKER_THREADS &&
     WORKER_PATH &&
-    fs.existsSync(WORKER_PATH)
+    fs.existsSync(WORKER_PATH) &&
+    !tracingEnabled
   ) {
     console.log('CodeYam: Using worker threads for analyzeScope', {
       WORKER_PATH,
@@ -121,6 +166,7 @@ function ensureWorkerPool() {
       WORKER_PATH,
       workerExists: WORKER_PATH ? fs.existsSync(WORKER_PATH) : false,
       USE_WORKER_THREADS: process.env.USE_WORKER_THREADS,
+      tracingEnabled,
     });
     workerPool = null; // Explicitly set to indicate "no workers"
   }
@@ -334,7 +380,7 @@ export async function analyzeScopeLocal({
             }
 
             for (const mapping of [structure, equivalentVariables]) {
-              for (let [key, value] of Object.entries(mapping)) {
+              for (let [key, rawValue] of Object.entries(mapping)) {
                 for (const [childScopeId, childScope] of sortedEntries) {
                   const scopeText = fileAnalyzer.sourceFile.text.slice(
                     childScope.start,
@@ -354,27 +400,49 @@ export async function analyzeScopeLocal({
                     return text;
                   };
 
-                  if (value.includes(scopeText)) {
-                    // DEBUG: Log when replacement happens
-                    if (key.includes('Fetcher') || key.includes('fetcher')) {
-                      console.log(
-                        'CodeYam DEBUG value replacement:',
-                        JSON.stringify({
-                          key,
-                          oldValue: value,
-                          childScopeId,
-                          scopeTextPreview: scopeText.slice(0, 50),
-                        }),
-                      );
+                  // Handle both string and string[] values (for OR expressions)
+                  const processValue = (value: string): string => {
+                    if (value.includes(scopeText)) {
+                      // DEBUG: Log when replacement happens
+                      if (key.includes('Fetcher') || key.includes('fetcher')) {
+                        console.log(
+                          'CodeYam DEBUG value replacement:',
+                          JSON.stringify({
+                            key,
+                            oldValue: value,
+                            childScopeId,
+                            scopeTextPreview: scopeText.slice(0, 50),
+                          }),
+                        );
+                      }
+                      return replaceChildScopeId(value);
+                    }
+                    return value;
+                  };
+
+                  if (Array.isArray(rawValue)) {
+                    const newValues = rawValue.map(processValue);
+                    (mapping as Record<string, string | string[]>)[key] =
+                      newValues;
+                    rawValue = newValues;
+                  } else if (typeof rawValue === 'string') {
+                    const newValue = processValue(rawValue);
+                    if (newValue !== rawValue) {
+                      (mapping as Record<string, string | string[]>)[key] =
+                        newValue;
+                      rawValue = newValue;
                     }
-                    value = replaceChildScopeId(value);
-                    mapping[key] = value;
                   }
+
                   if (key.includes(scopeText)) {
                     const oldKey = key;
                     key = replaceChildScopeId(key);
-                    mapping[key] = mapping[oldKey];
-                    delete mapping[oldKey];
+                    (mapping as Record<string, string | string[]>)[key] = (
+                      mapping as Record<string, string | string[]>
+                    )[oldKey];
+                    delete (mapping as Record<string, string | string[]>)[
+                      oldKey
+                    ];
                   }
                 }
               }

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

@@ -102,7 +102,7 @@ import { ThrowStatementHandler } from './patterns/throwStatementHandler';
  */
 export class ASTScopeAnalyzer {
   private structure: Record<string, string> = {};
-  private equivalentVariables: Record<string, string> = {};
+  private equivalentVariables: Record<string, string | string[]> = {};
   private environmentVariables: string[] = [];
   private conditionalUsages: Record<string, ConditionalUsage[]> = {};
   private compoundConditionals: CompoundConditional[] = [];
@@ -235,6 +235,8 @@ export class ASTScopeAnalyzer {
       typeChecker: this.fileAnalyzer.typeChecker,
       addEquivalence: (leftSide, rightSide) =>
         this.addEquivalence(leftSide, rightSide),
+      addMultipleEquivalencies: (leftSide, rightSides) =>
+        this.addMultipleEquivalencies(leftSide, rightSides),
       addType: (path, type) => this.addType(path, type),
       addEnvironmentVariable: (variablePath) =>
         this.addEnvironmentVariable(variablePath),
@@ -592,7 +594,9 @@ export class ASTScopeAnalyzer {
   }
 
   /**
-   * Adds an equivalence relationship between two variable paths
+   * Adds an equivalence relationship between two variable paths.
+   * Uses overwrite semantics - if an equivalence already exists, the new value replaces it
+   * (unless the new value is 'undefined' or 'null').
    */
   private addEquivalence(
     leftSide: StructuredPath,
@@ -622,6 +626,44 @@ export class ASTScopeAnalyzer {
     }
   }
 
+  /**
+   * Adds multiple equivalence relationships for a single variable path.
+   * Used for OR expressions like `x = a || b` where x is equivalent to both a and b.
+   * The values are stored as an array to track all possible sources.
+   */
+  private addMultipleEquivalencies(
+    leftSide: StructuredPath,
+    rightSides: StructuredPath[],
+  ): void {
+    if (leftSide?.isLiteral()) {
+      return;
+    }
+
+    const leftSideStr = leftSide?.toLeftHandSideString();
+    if (!leftSideStr) return;
+
+    // Filter out invalid paths and convert to strings
+    const validRightSides = rightSides
+      .map((r) => r?.toRightHandSideString())
+      .filter((r): r is string => !!r && r !== leftSideStr);
+
+    // Remove duplicates while preserving order
+    const uniqueRightSides = [...new Set(validRightSides)];
+
+    // Filter out 'undefined' and 'null' unless they're the only values
+    const meaningfulValues = uniqueRightSides.filter(
+      (v) => v !== 'undefined' && v !== 'null',
+    );
+    const finalValues =
+      meaningfulValues.length > 0 ? meaningfulValues : uniqueRightSides;
+
+    if (finalValues.length === 0) return;
+
+    // Store as single value if only one, otherwise as array
+    this.equivalentVariables[leftSideStr] =
+      finalValues.length === 1 ? finalValues[0] : finalValues;
+  }
+
   /**
    * Adds a type for a variable path
    */
@@ -785,22 +827,38 @@ export class ASTScopeAnalyzer {
     // Update the type for the given path
     this.structure[pathStr] = newType;
 
-    // Also update the type for any equivalent path
+    // Also update the type for any equivalent path(s)
     // e.g., if "state" -> "signature[0]", update "signature[0]" as well
-    const equivalentPath = this.equivalentVariables[pathStr];
-    if (equivalentPath) {
-      this.structure[equivalentPath] = newType;
+    const rawEquivalentPath = this.equivalentVariables[pathStr];
+    const equivalentPaths = Array.isArray(rawEquivalentPath)
+      ? rawEquivalentPath
+      : rawEquivalentPath
+        ? [rawEquivalentPath]
+        : [];
+    for (const equivalentPath of equivalentPaths) {
+      if (typeof equivalentPath === 'string') {
+        this.structure[equivalentPath] = newType;
+      }
     }
 
     // For property paths like "data.status", check if the base has an equivalence
     // e.g., if "data" -> "signature[0]", transform "data.status" to "signature[0].status"
-    for (const [varPath, equivalence] of Object.entries(
+    for (const [varPath, rawEquivalence] of Object.entries(
       this.equivalentVariables,
     )) {
       if (pathStr.startsWith(varPath + '.')) {
+        const equivalences = Array.isArray(rawEquivalence)
+          ? rawEquivalence
+          : rawEquivalence
+            ? [rawEquivalence]
+            : [];
         const suffix = pathStr.slice(varPath.length);
-        const transformedPath = equivalence + suffix;
-        this.structure[transformedPath] = newType;
+        for (const equivalence of equivalences) {
+          if (typeof equivalence === 'string') {
+            const transformedPath = equivalence + suffix;
+            this.structure[transformedPath] = newType;
+          }
+        }
       }
     }
   }

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

@@ -329,11 +329,17 @@ export class ArrayReduceSemantics implements MethodSemantics {
 /**
  * Array concat method semantics
  *
- * concat() returns a new array combining the original array and additional items
+ * concat() returns a new array/string combining the original and additional items
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .concat() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
  */
 export class ArrayConcatSemantics implements MethodSemantics {
   getReturnType(): string {
-    return 'array';
+    return 'unknown'; // Could be array or string depending on source
   }
 
   addEquivalences(
@@ -341,23 +347,24 @@ export class ArrayConcatSemantics implements MethodSemantics {
     sourcePath: StructuredPath,
     context: AnalysisContext,
   ): void {
-    // Mark source as array
-    context.addType(sourcePath, 'array');
+    // NOTE: We use 'unknown' instead of 'array' for the source because .concat()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    context.addType(sourcePath, 'unknown');
 
-    // Any arguments are also added to the array
+    // Any arguments are also added to the result
     const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
 
     if (functionCallSegment) {
       // Each argument could be an array or single element
       functionCallSegment.args.forEach((argPath) => {
         // No need to guess the type - we'll discover it through normal processing
-        // But we can indicate that these elements will be in the result array
+        // But we can indicate that these elements will be in the result
         context.addEquivalence(methodCallPath, argPath);
       });
     }
 
-    // The original array elements are also in the result
-    context.addType(methodCallPath, 'array');
+    // The original elements are also in the result
     context.addEquivalence(methodCallPath, sourcePath.withElement('*'));
   }
 
@@ -369,11 +376,17 @@ export class ArrayConcatSemantics implements MethodSemantics {
 /**
  * Array slice method semantics
  *
- * slice() returns a shallow copy of a portion of an array
+ * slice() returns a shallow copy of a portion of an array (or string)
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .slice() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
  */
 export class ArraySliceSemantics implements MethodSemantics {
   getReturnType(): string {
-    return 'array';
+    return 'unknown'; // Could be array or string depending on source
   }
 
   addEquivalences(
@@ -381,12 +394,15 @@ export class ArraySliceSemantics implements MethodSemantics {
     sourcePath: StructuredPath,
     context: AnalysisContext,
   ): void {
-    // Mark source as array
-    context.addType(sourcePath, 'array');
+    // NOTE: We use 'unknown' instead of 'array' for the source because .slice()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    // Type inference happens later in checkIfKnownType() based on accumulated evidence.
+    context.addType(sourcePath, 'unknown');
 
-    // The elements in the result are the same type as the source array
+    // Still track the return value type for data structure tracking
     const methodCallPathWithReturnValues = methodCallPath.withReturnValues();
-    context.addType(methodCallPathWithReturnValues, 'array');
+    context.addType(methodCallPathWithReturnValues, 'unknown');
   }
 
   isComplete(): boolean {
@@ -608,6 +624,12 @@ export class ArrayFlatMapSemantics implements MethodSemantics {
  * Array at method semantics
  *
  * at() returns the element at the given index, supporting negative indices
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .at() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
  */
 export class ArrayAtSemantics implements MethodSemantics {
   getReturnType(): string {
@@ -619,10 +641,12 @@ export class ArrayAtSemantics implements MethodSemantics {
     sourcePath: StructuredPath,
     context: AnalysisContext,
   ): void {
-    // Mark source as array
-    context.addType(sourcePath, 'array');
+    // NOTE: We use 'unknown' instead of 'array' for the source because .at()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    context.addType(sourcePath, 'unknown');
 
-    // The return value is equivalent to an array element
+    // The return value is equivalent to an element
     context.addEquivalence(
       methodCallPath.withReturnValues(),
       sourcePath.withElement('*'),

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

@@ -22,11 +22,8 @@ export class ForInStatementHandler implements PatternHandler {
     // Process the expression being iterated over first (e.g., object)
     context.processExpression(node.expression);
 
-    // Get the path of the object being iterated
-    const expressionPath = context.getStructuralPath(node.expression);
-
-    // If the initializer is a variable declaration with an identifier, establish equivalence
-    // to indicate it's iterating over the keys of the expression
+    // If the initializer is a variable declaration with an identifier,
+    // type it as 'string' since for-in keys are always strings
     if (ts.isVariableDeclarationList(node.initializer)) {
       const declarations = node.initializer.declarations;
       if (
@@ -36,25 +33,21 @@ export class ForInStatementHandler implements PatternHandler {
       ) {
         const variableName = StructuredPath.fromBase(declarations[0].name.text);
 
-        // Add type for the key variable (string for object keys)
+        // Type the key variable as 'string' — for-in keys are always strings.
+        // Note: We intentionally do NOT equivalence the key variable to
+        // expressionPath[*key*]. The key variable is the KEY (a string),
+        // while [*key*] in the schema represents the VALUE at a dynamic key.
+        // Creating that equivalence would cause the 'string' type to propagate
+        // to the value path. The value access (e.g., obj[key]) is handled
+        // correctly by the element access handler in processExpression.
         context.addType(variableName, 'string');
-
-        if (expressionPath) {
-          // For for...in loops, the variable is equivalent to the keys of the object
-          // We represent this with a *key* suffix to indicate it's a key, not a value
-          context.addEquivalence(variableName, expressionPath.withKey('key'));
-        }
       }
     } else if (ts.isIdentifier(node.initializer)) {
       // If the initializer is directly an identifier (rare but possible)
       const variableName = StructuredPath.fromBase(node.initializer.text);
 
-      // Add type for the key variable
+      // See comment above — type as string but don't equivalence to value path
       context.addType(variableName, 'string');
-
-      if (expressionPath) {
-        context.addEquivalence(variableName, expressionPath.withKey('key'));
-      }
     } else {
       context.processExpression(node.initializer);
     }