@codeyam/codeyam-cli 0.1.0-staging.c9dc00c → 0.1.0-staging.d3e886e

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2026-02-12T00:59:17.612Z",
-  "buildTime": 1770857957612,
-  "gitCommit": "c9dc00c107fcfb3afffa887ba71388b8c1845bb5",
+  "buildTimestamp": "2026-02-13T23:04:02.101Z",
+  "buildTime": 1771023842101,
+  "gitCommit": "d3e886e41f5771474b7c08a4b372bac8f4a70537",
   "nodeVersion": "v20.20.0",
-  "contentHash": "758171aef85ccd1bc1f053e4d145ca64329fe1057b81fc88cd62eaa648a3dd12",
-  "buildNumber": 611,
-  "semanticVersion": "0.1.611",
-  "version": "0.1.611 (2026-02-12T00:59+758171a)"
+  "contentHash": "7f2a19190511996b687bdd764ab6297993590ece837b6bbdec8bda87b904ab50",
+  "buildNumber": 625,
+  "semanticVersion": "0.1.625",
+  "version": "0.1.625 (2026-02-13T23:04+7f2a191)"
 }

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[2/12/2026, 12:59:17 AM] > codeyam-combo@1.0.0 mergeDependencies
-[2/12/2026, 12:59:17 AM] > node ./scripts/mergePackageJsonFiles.cjs
+[2/13/2026, 11:04:01 PM] > codeyam-combo@1.0.0 mergeDependencies
+[2/13/2026, 11:04:01 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[2/12/2026, 12:59:17 AM] Merged dependencies into root package.json
+[2/13/2026, 11:04:02 PM] Merged dependencies into root package.json
 

package/analyzer-template/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-cloudwatch-logs": "^3.980.0",
-    "@aws-sdk/client-cloudfront": "^3.966.0",
+    "@aws-sdk/client-cloudfront": "^3.985.0",
     "@aws-sdk/client-codebuild": "^3.948.0",
     "@aws-sdk/client-dynamodb": "^3.956.0",
     "@aws-sdk/client-ec2": "^3.899.0",

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

@@ -43,6 +43,7 @@ export { default as isolateScopes } from './src/lib/isolateScopes';
 export {
   default as analyzeScope,
   destroyWorkerPool,
+  skipWorkerPool,
 } from './src/lib/analyzeScope';
 export { default as logOrderedMap } from './src/lib/logOrderedMap';
 export {

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

@@ -50,6 +50,19 @@ let workerPool: Piscina<
   AnalyzeScopeWorkerOutput
 > | null = null;
 let workerPoolDestroyed = false;
+let workerPoolSkipped = false;
+
+/**
+ * Skip worker pool initialization for the current session.
+ *
+ * The worker thread creates its own ProjectAnalyzer (ts.Program), which takes
+ * 50-70s — far longer than the actual entity processing (<2s for typical batches).
+ * When the entity count is small, running analyzeScopeLocal on the main thread
+ * reuses the existing ProjectAnalyzer and avoids this overhead entirely.
+ */
+export function skipWorkerPool() {
+  workerPoolSkipped = true;
+}
 
 /**
  * Check if we're in Node.js main thread
@@ -108,6 +121,7 @@ function ensureWorkerPool() {
         'analyzeScope should not be called after data structure preparation completes.',
     );
   }
+  if (workerPoolSkipped) return;
   if (workerPool !== null) return;
 
   // Only initialize worker pool in Node.js environment

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

@@ -9,6 +9,7 @@ import { StructuredPath } from './paths';
 import { nodeToSource } from './nodeToSource';
 import { methodRegistry, ArrayPushSemantics } from './methodSemantics';
 import {
+  getComparisonOperatorString,
   isArithmeticOperator,
   isAssignmentOperator,
   isBitwiseCompoundOperator,
@@ -25,6 +26,74 @@ import {
 } from './conditionalEffectsExtractor';
 import { detectArrayDerivedPattern } from './arrayDerivationDetector';
 
+/**
+ * Recursively extracts root variable names from an expression AST node.
+ * Used to identify which variables flow into JSX expression children,
+ * so we can link them to the return value schema.
+ *
+ * Examples:
+ * - `filteredTopPaths.map(...)` → ['filteredTopPaths']
+ * - `a && b` → ['a', 'b']
+ * - `condition ? x : y` → ['condition', 'x', 'y']
+ */
+function extractRootVariableNames(node: ts.Expression): string[] {
+  const ignoredIdentifiers = new Set([
+    'undefined',
+    'null',
+    'true',
+    'false',
+    'NaN',
+    'Infinity',
+  ]);
+
+  if (ts.isIdentifier(node)) {
+    const name = node.text;
+    return ignoredIdentifiers.has(name) ? [] : [name];
+  }
+
+  if (ts.isPropertyAccessExpression(node)) {
+    return extractRootVariableNames(node.expression);
+  }
+
+  if (ts.isCallExpression(node)) {
+    return extractRootVariableNames(node.expression);
+  }
+
+  if (ts.isBinaryExpression(node)) {
+    return [
+      ...extractRootVariableNames(node.left),
+      ...extractRootVariableNames(node.right),
+    ];
+  }
+
+  if (ts.isPrefixUnaryExpression(node)) {
+    return extractRootVariableNames(node.operand);
+  }
+
+  if (ts.isConditionalExpression(node)) {
+    return [
+      ...extractRootVariableNames(node.condition),
+      ...extractRootVariableNames(node.whenTrue),
+      ...extractRootVariableNames(node.whenFalse),
+    ];
+  }
+
+  if (ts.isParenthesizedExpression(node)) {
+    return extractRootVariableNames(node.expression);
+  }
+
+  // Stop recursion at JSX elements and other terminal nodes
+  if (
+    ts.isJsxElement(node) ||
+    ts.isJsxFragment(node) ||
+    ts.isJsxSelfClosingElement(node)
+  ) {
+    return [];
+  }
+
+  return [];
+}
+
 /**
  * Checks if a JSX element has props that reference variables from the parent scope.
  * This is used to detect unconditionally-rendered children that should have their
@@ -1294,6 +1363,11 @@ export function extractConditionalUsage(
         return literalValue;
       };
 
+      // Get the comparison operator string for the compound condition
+      const comparisonOperator = getComparisonOperatorString(
+        unwrapped.operatorToken.kind,
+      );
+
       // Helper to add a condition
       const addCondition = (
         path: string,
@@ -1338,6 +1412,7 @@ export function extractConditionalUsage(
             comparedValues,
             isNegated,
             requiredValue,
+            ...(comparisonOperator && { comparisonOperator }),
             ...(chainInfo.currentOrGroupId && {
               orGroupId: chainInfo.currentOrGroupId,
             }),
@@ -3334,6 +3409,19 @@ export function processExpression({
       for (const child of unwrappedNode.children) {
         // Process expressions in JSX children: <div>{expr}</div>
         if (ts.isJsxExpression(child) && child.expression) {
+          // When processing return value JSX, link root variables to return value schema
+          if (targetPath && targetPath.base !== '') {
+            const varNames = [
+              ...new Set(extractRootVariableNames(child.expression)),
+            ];
+            for (const varName of varNames) {
+              context.addEquivalence(
+                targetPath.withProperty(varName),
+                StructuredPath.fromBase(varName),
+              );
+            }
+          }
+
           // Process the expression with StructuredPath.empty() as targetPath
           // to trigger type registration without imposing prefix
           processExpression({
@@ -3368,6 +3456,19 @@ export function processExpression({
     for (const child of unwrappedNode.children) {
       // Process expressions in JSX children: <>{expr}</>
       if (ts.isJsxExpression(child) && child.expression) {
+        // When processing return value JSX, link root variables to return value schema
+        if (targetPath && targetPath.base !== '') {
+          const varNames = [
+            ...new Set(extractRootVariableNames(child.expression)),
+          ];
+          for (const varName of varNames) {
+            context.addEquivalence(
+              targetPath.withProperty(varName),
+              StructuredPath.fromBase(varName),
+            );
+          }
+        }
+
         // Process the expression to extract structure
         processExpression({
           node: child.expression,

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

@@ -71,6 +71,34 @@ export function isComparisonOperator(kind: ts.SyntaxKind): boolean {
   );
 }
 
+/**
+ * Returns the string representation of a comparison operator token.
+ */
+export function getComparisonOperatorString(
+  kind: ts.SyntaxKind,
+): string | undefined {
+  switch (kind) {
+    case ts.SyntaxKind.EqualsEqualsToken:
+      return '==';
+    case ts.SyntaxKind.EqualsEqualsEqualsToken:
+      return '===';
+    case ts.SyntaxKind.ExclamationEqualsToken:
+      return '!=';
+    case ts.SyntaxKind.ExclamationEqualsEqualsToken:
+      return '!==';
+    case ts.SyntaxKind.LessThanToken:
+      return '<';
+    case ts.SyntaxKind.LessThanEqualsToken:
+      return '<=';
+    case ts.SyntaxKind.GreaterThanToken:
+      return '>';
+    case ts.SyntaxKind.GreaterThanEqualsToken:
+      return '>=';
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Checks if an operator is an arithmetic operator
  */

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

@@ -433,6 +433,12 @@ export interface CompoundConditional {
     isNegated: boolean;
     /** Required value for this condition to be true */
     requiredValue?: string | boolean;
+    /**
+     * The comparison operator used (e.g., '>', '<', '>=', '<=', '===', '!==').
+     * Preserves the original operator so flow generation can distinguish
+     * `length > 0` from `length === 0`.
+     */
+    comparisonOperator?: string;
     /**
      * When conditions are part of an OR expression within an && chain,
      * they share the same orGroupId. Conditions with the same orGroupId

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

@@ -397,6 +397,7 @@ const SILENTLY_IGNORED_EQUIVALENCY_REASONS = new Set([
   'transformed non-object function equivalency - implicit parent equivalency - rerouted via useCallback',
   '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',
 ]);
 
 export class ScopeDataStructure {
@@ -3902,25 +3903,116 @@ export class ScopeDataStructure {
       return [source];
     };
 
-    return entries.reduce(
-      (acc, entry) => {
-        if (entry.sourceCandidates.length === 0) return acc;
+    const acc = entries.reduce(
+      (result, entry) => {
+        if (entry.sourceCandidates.length === 0) return result;
         const usages = entry.usages.filter(usageMatchesScope);
         for (const usage of usages) {
-          acc[usage.schemaPath] ||= [];
+          result[usage.schemaPath] ||= [];
           // Resolve each source candidate through the equivalency chain
           for (const source of entry.sourceCandidates) {
             const resolvedSources = resolveToSignature(source, new Set());
-            acc[usage.schemaPath].push(...resolvedSources);
+            result[usage.schemaPath].push(...resolvedSources);
           }
         }
-        return acc;
+        return result;
       },
       {} as Record<
         string,
         Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]
       >,
     );
+
+    // Post-processing: enrich useState-backed sources with co-located external
+    // function calls. When a useState value resolves to a setter variable that
+    // lives in the same scope as a fetch/API call, that fetch is a data source.
+    this.enrichUseStateSourcesWithCoLocatedCalls(acc);
+
+    return acc;
+  }
+
+  /**
+   * For each source that ends at a useState path, check if the setter was called
+   * from a scope that also contains external function calls (like fetch).
+   * If so, add those external calls as additional source candidates.
+   */
+  private enrichUseStateSourcesWithCoLocatedCalls(
+    acc: Record<string, Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]>,
+  ) {
+    const rootScopeName = this.scopeTreeManager.getRootName();
+    const rootScope = this.scopeNodes[rootScopeName];
+    if (!rootScope) return;
+
+    // Collect all descendants for each scope node
+    const getAllDescendants = (
+      node: import('./helpers/ScopeTreeManager').ScopeTreeNode,
+    ): Set<string> => {
+      const names = new Set<string>([node.name]);
+      for (const child of node.children) {
+        for (const name of getAllDescendants(child)) {
+          names.add(name);
+        }
+      }
+      return names;
+    };
+
+    for (const [usagePath, sources] of Object.entries(acc)) {
+      const additionalSources: Pick<
+        ScopeVariable,
+        'scopeNodeName' | 'schemaPath'
+      >[] = [];
+
+      for (const source of sources) {
+        // Check if this source is a useState-related terminal path
+        // (e.g., useState(X).functionCallReturnValue[1] or useState(X).signature[0])
+        if (!source.schemaPath.match(/^useState\([^)]*\)\./)) continue;
+
+        // Find the useState call from the source path
+        const useStateCallMatch = source.schemaPath.match(
+          /^(useState\([^)]*\))\./,
+        );
+        if (!useStateCallMatch) continue;
+        const useStateCall = useStateCallMatch[1];
+
+        // Look in the root scope for the useState value equivalency
+        // which tells us where the setter was called from
+        const valuePath = `${useStateCall}.functionCallReturnValue[0]`;
+        const valueEquivs = rootScope.equivalencies[valuePath];
+        if (!valueEquivs) continue;
+
+        for (const equiv of valueEquivs) {
+          // Find the scope where the setter was called
+          const setterScopeName = equiv.scopeNodeName;
+          const setterScopeTree =
+            this.scopeTreeManager.findNode(setterScopeName);
+          if (!setterScopeTree) continue;
+
+          // Get all descendant scope names from the setter scope
+          const relatedScopes = getAllDescendants(setterScopeTree);
+
+          // Find external function calls in those scopes whose return values
+          // are actually consumed (assigned to a variable). This excludes
+          // fire-and-forget calls like analytics.track() or console.log().
+          const coLocatedCalls = this.externalFunctionCalls.filter(
+            (efc) =>
+              relatedScopes.has(efc.callScope) &&
+              efc.receivingVariableNames &&
+              efc.receivingVariableNames.length > 0,
+          );
+
+          for (const call of coLocatedCalls) {
+            additionalSources.push({
+              scopeNodeName: call.callScope,
+              schemaPath: `${call.callSignature}.functionCallReturnValue`,
+            });
+          }
+        }
+      }
+
+      if (additionalSources.length > 0) {
+        acc[usagePath].push(...additionalSources);
+      }
+    }
   }
 
   getUsageEquivalencies(functionName?: string) {
@@ -4427,6 +4519,15 @@ export class ScopeDataStructure {
           !equivalentValue.schemaPath.startsWith('signature[') && // not a signature path
           !equivalentValue.schemaPath.endsWith('.functionCallReturnValue') // not already handled above
         ) {
+          // Skip bare "returnValue" from child scopes — this is the child's return value,
+          // not a meaningful data source path in the parent scope
+          if (
+            equivalentValue.schemaPath === 'returnValue' &&
+            equivalentValue.scopeNodeName !==
+              this.scopeTreeManager.getRootName()
+          ) {
+            continue;
+          }
           // Add equivalency (will accumulate if multiple values for OR expressions)
           addEquivalency(path, equivalentValue.schemaPath);
         }
@@ -5123,6 +5224,10 @@ export class ScopeDataStructure {
   getEnrichedConditionalUsages(): Record<string, EnrichedConditionalUsage[]> {
     const enriched: Record<string, EnrichedConditionalUsage[]> = {};
 
+    console.log(
+      `[getEnrichedConditionalUsages] Processing ${Object.keys(this.rawConditionalUsages).length} conditional paths: [${Object.keys(this.rawConditionalUsages).join(', ')}]`,
+    );
+
     for (const [path, usages] of Object.entries(this.rawConditionalUsages)) {
       // Try to trace this path back to a data source
       // First, try the root scope
@@ -5131,10 +5236,69 @@ export class ScopeDataStructure {
 
       let sourceDataPath: string | undefined;
       if (explanation.source) {
-        // Build the full data path: scopeName.path
-        sourceDataPath = `${explanation.source.scope}.${explanation.source.path}`;
+        const { scope, path: sourcePath } = explanation.source;
+
+        // Build initial path — avoid redundant prefix when path already contains the scope call
+        let fullPath: string;
+        if (sourcePath.startsWith(`${scope}(`)) {
+          fullPath = sourcePath;
+        } else {
+          fullPath = `${scope}.${sourcePath}`;
+        }
+
+        sourceDataPath = fullPath;
+        console.log(
+          `[getEnrichedConditionalUsages] "${path}" explainPath → scope="${scope}", sourcePath="${sourcePath}" → sourceDataPath="${sourceDataPath}"`,
+        );
+      } else {
+        console.log(
+          `[getEnrichedConditionalUsages] "${path}" explainPath → no source found`,
+        );
       }
 
+      // If explainPath didn't find a useful external source (e.g., it traced to
+      // useState or just to the component scope itself), check sourceEquivalencies
+      // for an external function call source like a fetch call
+      const hasExternalSource = sourceDataPath?.includes(
+        '.functionCallReturnValue',
+      );
+      if (!hasExternalSource) {
+        console.log(
+          `[getEnrichedConditionalUsages] "${path}" no external source (sourceDataPath="${sourceDataPath}"), checking sourceEquivalencies fallback...`,
+        );
+        const sourceEquiv = this.getSourceEquivalencies();
+        const returnValueKey = `returnValue.${path}`;
+        const sources = sourceEquiv[returnValueKey];
+        if (sources) {
+          console.log(
+            `[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] has ${sources.length} sources: [${sources.map((s: { schemaPath: string }) => s.schemaPath).join(', ')}]`,
+          );
+          const externalSource = sources.find(
+            (s: { schemaPath: string }) =>
+              s.schemaPath.includes('.functionCallReturnValue') &&
+              !s.schemaPath.startsWith('useState('),
+          );
+          if (externalSource) {
+            console.log(
+              `[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found external source: "${externalSource.schemaPath}"`,
+            );
+            sourceDataPath = externalSource.schemaPath;
+          } else {
+            console.log(
+              `[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found no external function call source`,
+            );
+          }
+        } else {
+          console.log(
+            `[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] not found`,
+          );
+        }
+      }
+
+      console.log(
+        `[getEnrichedConditionalUsages] "${path}" FINAL sourceDataPath="${sourceDataPath ?? '(none)'}" (${usages.length} usages)`,
+      );
+
       enriched[path] = usages.map((usage) => ({
         ...usage,
         sourceDataPath,

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

@@ -14,21 +14,46 @@ const isStandaloneIndex = (s?: string) => !!s && STANDALONE_INDEX_RE.test(s);
 // The regex matches any path ending with .length that has [] somewhere before it
 const DYNAMIC_LENGTH_RE = /\[\].*\.length$/;
 
-// Treat these as structural placeholders (don't commit them as concrete leaves)
-function isSkippableLeafType(t: string) {
-  // 'unknown' by itself is a placeholder (but 'boolean | unknown' is not)
-  // Also handles optional variants like 'object | undefined', 'object | null',
-  // 'array | undefined', etc. — these are still structural placeholders that
-  // should not overwrite already-populated structures.
+// Cache for type string analysis to avoid repeated split/filter operations.
+// These functions are called multiple times per path segment across thousands of paths.
+const typeAnalysisCache = new Map<
+  string,
+  { isSkippable: boolean; baseType: string; isNullable: boolean }
+>();
+
+function getTypeAnalysis(t: string) {
+  const cached = typeAnalysisCache.get(t);
+  if (cached) return cached;
   const parts = t.split('|').map((s) => s.trim());
   const base = parts.filter((s) => s !== 'undefined' && s !== 'null');
-  return (
-    base.length === 1 &&
-    (base[0] === 'object' ||
-      base[0] === 'array' ||
-      base[0] === 'function' ||
-      base[0] === 'unknown')
-  );
+  const result = {
+    isSkippable:
+      base.length === 1 &&
+      (base[0] === 'object' ||
+        base[0] === 'array' ||
+        base[0] === 'function' ||
+        base[0] === 'unknown'),
+    baseType: base[0],
+    isNullable: parts.includes('undefined') || parts.includes('null'),
+  };
+  typeAnalysisCache.set(t, result);
+  return result;
+}
+
+// Treat these as structural placeholders (don't commit them as concrete leaves)
+function isSkippableLeafType(t: string) {
+  return getTypeAnalysis(t).isSkippable;
+}
+
+// Extract the base structural type from a potentially nullable type string.
+// e.g., 'object | undefined' → 'object', 'array | null' → 'array'
+function getBaseSkippableType(t: string): string {
+  return getTypeAnalysis(t).baseType;
+}
+
+// Check if a type string has nullable annotations (| undefined or | null)
+function isNullableType(t: string): boolean {
+  return getTypeAnalysis(t).isNullable;
 }
 
 // Matches paths containing [][] — e.g., "items[][]" or "items[][].text"
@@ -317,15 +342,41 @@ export default function convertDotNotation(
           cursor[key] = typ;
         } else {
           // Structural/placeholder terminal
-          if (typ === 'array') {
+          const nullable = isNullableType(typ);
+          const baseType = getBaseSkippableType(typ);
+
+          if (baseType === 'array') {
             if (!Array.isArray(cursor[key])) cursor[key] = [];
+            if (nullable) {
+              (cursor[key] as any)._nullable = true;
+            }
           } else if (
-            typ === 'object' ||
-            typ === 'function' ||
-            typ.trim() === 'unknown'
+            baseType === 'object' ||
+            baseType === 'function' ||
+            baseType === 'unknown'
           ) {
-            if (cursor[key] === undefined) {
-              cursor[key] = typ;
+            if (nullable) {
+              // Nullable object: ensure it's an actual object (not a string
+              // placeholder) so _nullable can be set and child paths can
+              // populate properties on it.
+              if (
+                cursor[key] === undefined ||
+                typeof cursor[key] === 'string'
+              ) {
+                cursor[key] = {};
+              }
+              if (
+                typeof cursor[key] === 'object' &&
+                cursor[key] !== null &&
+                !Array.isArray(cursor[key])
+              ) {
+                (cursor[key] as any)._nullable = true;
+              }
+            } else {
+              // Non-nullable: preserve existing behavior (string placeholder)
+              if (cursor[key] === undefined) {
+                cursor[key] = typ;
+              }
             }
           }
         }