@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

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

@@ -1,10 +1,10 @@
 {
-  "buildTimestamp": "2025-12-29T14:25:31.079Z",
-  "buildTime": 1767018331079,
-  "gitCommit": "596f0eba949668a0fbeb95513ac34bec8fe830b9",
-  "nodeVersion": "v20.19.6",
-  "contentHash": "4ace14f6fdebddb09650af55ef766aa49b01e8edc4c9644fff7d051498b4e584",
-  "buildNumber": 251,
-  "semanticVersion": "0.1.251",
-  "version": "0.1.251 (2025-12-29T14:25+4ace14f)"
+  "buildTimestamp": "2026-01-27T18:35:02.170Z",
+  "buildTime": 1769538902170,
+  "gitCommit": "6e699e56ee4e2c0efa0086ccf7268b040394c2c2",
+  "nodeVersion": "v20.20.0",
+  "contentHash": "cce7c765a7074dbbc87cc66ff68e4de45336dce2e768af7373c978f5db3afe4d",
+  "buildNumber": 522,
+  "semanticVersion": "0.1.522",
+  "version": "0.1.522 (2026-01-27T18:35+cce7c76)"
 }

package/analyzer-template/common/execAsync.ts

@@ -6,7 +6,7 @@ import * as fs from 'fs';
 import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
 
 import { loadEnv } from '~codeyam/utils/server';
-import { getGlobalProcessManager, ProcessType } from '../process';
+import { getGlobalProcessManager, ProcessType } from '~codeyam/process';
 
 loadEnv();
 

package/analyzer-template/log.txt

@@ -1,7 +1,7 @@
 
-[12/29/2025, 2:25:30 PM] > codeyam-combo@1.0.0 mergeDependencies
-[12/29/2025, 2:25:30 PM] > node ./scripts/mergePackageJsonFiles.cjs
+[1/27/2026, 6:35:02 PM] > codeyam-combo@1.0.0 mergeDependencies
+[1/27/2026, 6:35:02 PM] > node ./scripts/mergePackageJsonFiles.cjs
 
 
-[12/29/2025, 2:25:31 PM] Merged dependencies into root package.json
+[1/27/2026, 6:35:02 PM] Merged dependencies into root package.json
 

package/analyzer-template/package.json

@@ -7,8 +7,8 @@
     "build": "tsc && node ./scripts/postbuild.cjs"
   },
   "dependencies": {
-    "@aws-sdk/client-cloudwatch-logs": "^3.940.0",
-    "@aws-sdk/client-cloudfront": "^3.899.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.966.0",
+    "@aws-sdk/client-cloudfront": "^3.966.0",
     "@aws-sdk/client-codebuild": "^3.948.0",
     "@aws-sdk/client-dynamodb": "^3.956.0",
     "@aws-sdk/client-ec2": "^3.899.0",
@@ -16,8 +16,8 @@
     "@aws-sdk/client-ecs": "^3.956.0",
     "@aws-sdk/client-s3": "^3.940.0",
     "@aws-sdk/client-sqs": "^3.956.0",
-    "@aws-sdk/lib-storage": "^3.940.0",
-    "@aws-sdk/util-dynamodb": "^3.902.0",
+    "@aws-sdk/lib-storage": "^3.975.0",
+    "@aws-sdk/util-dynamodb": "^3.971.0",
     "@octokit/auth-app": "^8.1.0",
     "@octokit/rest": "^22.0.0",
     "@sendgrid/mail": "^8.1.4",
@@ -31,9 +31,9 @@
     "jsdom": "^27.4.0",
     "jsonc-parser": "^3.2.1",
     "lru-cache": "^11.2.4",
-    "openai": "^6.9.0",
+    "openai": "^6.16.0",
     "p-queue": "^8.1.0",
-    "p-retry": "^6.2.1",
+    "p-retry": "^7.1.1",
     "piscina": "^5.1.4",
     "pixelmatch": "^5.3.0",
     "playwright": "^1.56.1",
@@ -42,6 +42,8 @@
     "undici": "^7.16.0",
     "uuid": "^11.1.0",
     "pluralize": "^8.0.0",
+    "yargs": "^18.0.0",
+    "json5": "^2.2.3",
     "@anthropic-ai/sdk": "^0.71.0",
     "@aws-sdk/s3-request-presigner": "^3.940.0",
     "better-sqlite3": "^12.4.1",
@@ -55,6 +57,8 @@
   "devDependencies": {
     "typescript": "^5.9.3",
     "@jest/types": "^30.2.0",
+    "@types/node": "^25.0.2",
+    "@types/yargs": "^17.0.34",
     "@types/jsdom": "^27.0.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/jest": "^30.0.0",

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

@@ -21,8 +21,7 @@ export {
 } from './src/lib/generateEntityScenarioData';
 export { default as generateChangesEntityScenarios } from './src/lib/generateChangesEntityScenarios';
 export { default as generateChangesEntityScenarioData } from './src/lib/generateChangesEntityScenarioData';
-export { default as generateEntityKeyAttributes } from './src/lib/generateEntityKeyAttributes';
-export { default as generateChangesEntityKeyAttributes } from './src/lib/generateChangesEntityKeyAttributes';
+export { default as generateExecutionFlows } from './src/lib/generateExecutionFlows';
 export {
   default as guessScenarioDataFromName,
   type GuessScenarioDataFromNameArgs,
@@ -30,6 +29,7 @@ export {
 export {
   default as guessScenarioDataFromDescription,
   type GuessScenarioDataFromDescriptionArgs,
+  type ExecutionFlowSelection,
 } from './src/lib/guessScenarioDataFromDescription';
 export { default as generateBranchSummary } from './src/lib/generateBranchSummary';
 export { default as extractOverlappingMocks } from './src/lib/extractOverlappingMocks';
@@ -57,7 +57,6 @@ export { default as convertDotNotation } from './src/lib/dataStructure/helpers/c
 export { default as cleanOutBoundary } from './src/lib/cleanOutBoundary';
 export { fillInDirectSchemaGapsAndUnknowns } from './src/lib/dataStructure/helpers/fillInSchemaGapsAndUnknowns';
 export { default as deduplicateFunctionSchemas } from './src/lib/dataStructure/helpers/deduplicateFunctionSchemas';
-export { default as gatherRelevantDependentKeyAttributes } from './src/lib/gatherRelevantDependentKeyAttributes';
 export { default as getConditionalUsagesFromCode } from './src/lib/getConditionalUsagesFromCode';
 export type {
   ScopeInfo,
@@ -79,10 +78,18 @@ export {
   getSourceEquivalencies,
   getEquivalentSignatureVariables,
   getConditionalUsages,
+  getConditionalEffects,
+  getCompoundConditionals,
+  getChildBoundaryGatingConditions,
+  getJsxRenderingUsages,
 } from './src/lib/worker/SerializableDataStructure';
 export { parseJsonSafe } from './src/lib/parsers/parseJsonSafe';
 export { default as completionCall } from './src/lib/completionCall';
 
+// NOTE: E2E data tracking utilities (e2eDataTracking.ts) are NOT exported here
+// because they use Node.js 'crypto' module which breaks browser builds.
+// Import directly from '~codeyam/ai/src/lib/e2eDataTracking' when needed in Node.js tests.
+
 // Wrapper detection
 export { default as detectWrapperRequirements } from './src/lib/wrapperDetection/detectWrapperRequirements';
 export { KNOWN_LIBRARY_HOOKS } from './src/lib/wrapperDetection/knownLibraryHooks';

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

@@ -12,7 +12,7 @@
     "@anthropic-ai/sdk": "^0.71.0",
     "jsdom": "^27.4.0",
     "p-queue": "^8.1.0",
-    "p-retry": "^6.2.1",
+    "p-retry": "^7.1.1",
     "piscina": "^5.1.4",
     "lru-cache": "^11.2.4"
   },

package/analyzer-template/packages/ai/src/lib/__mocks__/completionCall.ts

@@ -1,3 +1,5 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import OpenAI from 'openai';
 import * as lib from '../../lib';
 import { AI } from '../../lib/types';
@@ -23,6 +25,121 @@ interface CompletionCallProps {
   attempts?: number;
 }
 
+// Track which fixture index to use for each type (for LLM replay)
+const callIndexByType: Record<string, number> = {};
+
+/**
+ * Replays a captured LLM call from test fixtures instead of making a real API call.
+ */
+function replayLlmCall(
+  type: string,
+  fixturesDir: string,
+): {
+  finishReason: string;
+  completion: string;
+  stats: lib.types.LlmCallStats;
+} {
+  console.log(
+    `CodeYam Test: Replaying LLM call for type '${type}' from ${fixturesDir}`,
+  );
+
+  // Ensure the fixtures directory exists
+  if (!fs.existsSync(fixturesDir)) {
+    throw new Error(
+      `No LLM fixture files found - directory does not exist: ${fixturesDir}`,
+    );
+  }
+
+  // Load all JSON files from fixtures directory
+  const files = fs
+    .readdirSync(fixturesDir)
+    .filter((f) => f.endsWith('.json'));
+
+  if (files.length === 0) {
+    throw new Error(`No LLM fixture files found in ${fixturesDir}`);
+  }
+
+  // Track calls of each type to handle multiple calls with same type
+  const callsByType: Record<string, any[]> = {};
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(fixturesDir, file), 'utf-8');
+      const call = JSON.parse(content);
+
+      if (!callsByType[call.prompt_type]) {
+        callsByType[call.prompt_type] = [];
+      }
+      callsByType[call.prompt_type].push(call);
+    } catch (error) {
+      console.warn(`Failed to parse LLM fixture file ${file}:`, error);
+    }
+  }
+
+  const matchingCalls = callsByType[type];
+
+  if (!matchingCalls || matchingCalls.length === 0) {
+    const availableTypes = Object.keys(callsByType).join(', ');
+    console.warn(
+      `CodeYam Test: No captured LLM call found for type '${type}'. Available types: ${availableTypes}`,
+    );
+    // Return empty response - callers should handle gracefully
+    // This allows new LLM call types to be added without breaking existing fixtures
+    return {
+      finishReason: 'stop',
+      completion: '{}',
+      stats: {
+        model: 'fixture-fallback',
+        prompt_type: type,
+        system_message: '',
+        prompt_text: '',
+        response: '{}',
+        input_tokens: 0,
+        output_tokens: 0,
+        cost: 0,
+      },
+    };
+  }
+
+  // Track call count per type and cycle through multiple responses
+  const callKey = `${fixturesDir}::${type}`;
+  if (!callIndexByType[callKey]) {
+    callIndexByType[callKey] = 0;
+  }
+  const callIndex = callIndexByType[callKey];
+  callIndexByType[callKey] = (callIndex + 1) % matchingCalls.length;
+
+  const call = matchingCalls[callIndex];
+
+  console.log(
+    `CodeYam Test: Replaying LLM response for '${type}' [${callIndex + 1}/${matchingCalls.length}]`,
+  );
+
+  // Extract the actual completion content from the OpenAI response
+  let completion: string;
+  try {
+    const responseObj = JSON.parse(call.response);
+    completion = responseObj.choices?.[0]?.message?.content || call.response;
+  } catch {
+    completion = call.response;
+  }
+
+  return {
+    finishReason: 'stop',
+    completion,
+    stats: {
+      model: call.model ?? 'fixture',
+      prompt_type: type,
+      system_message: call.system_message ?? '',
+      prompt_text: call.prompt_text ?? '',
+      response: call.response ?? '',
+      input_tokens: call.input_tokens ?? 0,
+      output_tokens: call.output_tokens ?? 0,
+      cost: call.cost ?? 0,
+    },
+  };
+}
+
 export default async function completionCall({
   type,
   systemMessage,
@@ -34,6 +151,11 @@ export default async function completionCall({
   // model = AI.Model.DEEPSEEK_CHAT,
   attempts = 0,
 }: CompletionCallProps) {
+  // Support for E2E testing with replayed LLM calls
+  if (process.env.CODEYAM_LLM_FIXTURES_DIR) {
+    return replayLlmCall(type, process.env.CODEYAM_LLM_FIXTURES_DIR);
+  }
+
   const modelInfo = getModelInfo(model);
   const apiKey = process.env[modelInfo.provider.apiKeyEnvVar];
 

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

@@ -32,6 +32,7 @@ import {
 import FunctionCallManager from './dataStructure/equivalencyManagers/FunctionCallManager';
 import { ReactFrameworkManager } from './dataStructure/equivalencyManagers/frameworks/ReactFrameworkManager';
 import { JavascriptFrameworkManager } from './dataStructure/equivalencyManagers/frameworks/JavascriptFrameworkManager';
+import { MuiManager } from './dataStructure/equivalencyManagers/frameworks/MuiManager';
 import ParentScopeManager from './dataStructure/equivalencyManagers/ParentScopeManager';
 import { AI } from '~codeyam/ai';
 import Piscina from 'piscina';
@@ -163,13 +164,27 @@ export async function analyzeScopeLocal({
     // Collect conditional usages from all statement analyses
     const allConditionalUsages: Record<
       string,
-      Array<{
-        path: string;
-        conditionType: 'truthiness' | 'comparison' | 'switch';
-        comparedValues?: string[];
-        location: 'if' | 'ternary' | 'logical-and' | 'switch';
-      }>
+      import('./astScopes/types').ConditionalUsage[]
     > = {};
+    // Collect conditional effects (setter calls inside conditionals)
+    const allConditionalEffects: import('./astScopes/types').ConditionalEffect[] =
+      [];
+    // Collect compound conditionals (grouped conditions that must all be true)
+    const allCompoundConditionals: import('./astScopes/types').CompoundConditional[] =
+      [];
+    // Collect derived variables (variables computed from boolean expressions)
+    const allDerivedVariables: Record<
+      string,
+      import('./astScopes/types').DerivedVariableInfo
+    > = {};
+    // Collect child boundary gating conditions across all statements
+    const allChildBoundaryGatingConditions: Record<
+      string,
+      import('./astScopes/types').ConditionalUsage[]
+    > = {};
+    // Collect JSX rendering usages (arrays via .map(), strings via interpolation)
+    const allJsxRenderingUsages: import('./astScopes/types').JsxRenderingUsage[] =
+      [];
 
     const astAnalysisResultWithStatements = statementScopes.map(
       (statementScope) => {
@@ -190,6 +205,39 @@ export async function analyzeScopeLocal({
           }
           allConditionalUsages[path].push(...usages);
         }
+        // Collect conditional effects from AST analysis
+        if (astAnalysisResult.conditionalEffects?.length > 0) {
+          allConditionalEffects.push(...astAnalysisResult.conditionalEffects);
+        }
+        // Collect compound conditionals from AST analysis
+        if (astAnalysisResult.compoundConditionals?.length > 0) {
+          allCompoundConditionals.push(
+            ...astAnalysisResult.compoundConditionals,
+          );
+        }
+        // Collect derived variables from AST analysis
+        if (astAnalysisResult.derivedVariables) {
+          for (const [varName, derivationInfo] of Object.entries(
+            astAnalysisResult.derivedVariables,
+          )) {
+            allDerivedVariables[varName] = derivationInfo;
+          }
+        }
+        // Collect child boundary gating conditions from AST analysis
+        if (astAnalysisResult.childBoundaryGatingConditions) {
+          for (const [childName, usages] of Object.entries(
+            astAnalysisResult.childBoundaryGatingConditions,
+          )) {
+            if (!allChildBoundaryGatingConditions[childName]) {
+              allChildBoundaryGatingConditions[childName] = [];
+            }
+            allChildBoundaryGatingConditions[childName].push(...usages);
+          }
+        }
+        // Collect JSX rendering usages from AST analysis
+        if (astAnalysisResult.jsxRenderingUsages?.length) {
+          allJsxRenderingUsages.push(...astAnalysisResult.jsxRenderingUsages);
+        }
         return {
           statementScope,
           astAnalysisResult,
@@ -473,6 +521,7 @@ export async function analyzeScopeLocal({
           new FunctionCallManager(),
           new ReactFrameworkManager(),
           new JavascriptFrameworkManager(),
+          new MuiManager(),
           new ParentScopeManager(),
         ],
         scope.name,
@@ -489,11 +538,83 @@ export async function analyzeScopeLocal({
       );
     }
 
+    // Enrich conditional usages with derived variable info
+    // This must happen after all statements are processed so derived variables from
+    // earlier statements can be used to enrich usages from later statements
+    if (Object.keys(allDerivedVariables).length > 0) {
+      for (const [path, usages] of Object.entries(allConditionalUsages)) {
+        for (const usage of usages) {
+          if (!usage.derivedFrom && allDerivedVariables[path]) {
+            usage.derivedFrom = allDerivedVariables[path];
+          }
+        }
+      }
+    }
+
     // Add conditional usages from this scope's analysis
     if (Object.keys(allConditionalUsages).length > 0) {
       scopeDataStructure.addConditionalUsages(allConditionalUsages);
     }
 
+    // Add conditional effects from this scope's analysis
+    if (allConditionalEffects.length > 0) {
+      scopeDataStructure.addConditionalEffects(allConditionalEffects);
+    }
+
+    // Add compound conditionals from this scope's analysis
+    if (allCompoundConditionals.length > 0) {
+      scopeDataStructure.addCompoundConditionals(allCompoundConditionals);
+    }
+
+    // Merge extracted gating conditions from JSX extraction (processJSXForScope)
+    // These were detected BEFORE JSX was simplified, so they have the full context
+    if (scope.extractedGatingConditions) {
+      for (const [childName, conditions] of Object.entries(
+        scope.extractedGatingConditions,
+      )) {
+        if (!allChildBoundaryGatingConditions[childName]) {
+          allChildBoundaryGatingConditions[childName] = [];
+        }
+        for (const condition of conditions) {
+          // Convert to full ConditionalUsage format
+          allChildBoundaryGatingConditions[childName].push({
+            path: condition.path,
+            conditionType: condition.conditionType,
+            location: condition.location,
+            isNegated: condition.isNegated,
+            controlsJsxRendering: true,
+          });
+        }
+      }
+    }
+
+    // Enrich child boundary gating conditions with derived variable info
+    // This must happen after all statements are processed so derived variables from
+    // earlier statements can be used to enrich gating conditions from later statements
+    if (Object.keys(allDerivedVariables).length > 0) {
+      for (const [_childName, conditions] of Object.entries(
+        allChildBoundaryGatingConditions,
+      )) {
+        for (const condition of conditions) {
+          if (!condition.derivedFrom && allDerivedVariables[condition.path]) {
+            condition.derivedFrom = allDerivedVariables[condition.path];
+          }
+        }
+      }
+    }
+
+    // Add child boundary gating conditions from this scope's analysis
+    if (Object.keys(allChildBoundaryGatingConditions).length > 0) {
+      scopeDataStructure.addChildBoundaryGatingConditions(
+        allChildBoundaryGatingConditions,
+      );
+    }
+
+    // Add JSX rendering usages from this scope's analysis
+    if (allJsxRenderingUsages.length > 0) {
+      scopeDataStructure.addJsxRenderingUsages(allJsxRenderingUsages);
+    }
+
     await Promise.all(
       Object.values(scope.childScopes).map(async (childScope) => {
         // This is awkward but need to identify class scopes
@@ -572,6 +693,7 @@ export default async function analyzeScope(
         end: scope.end,
         variables: scope.variables,
         childScopes: scope.childScopes,
+        extractedGatingConditions: scope.extractedGatingConditions,
       },
       model: args.model,
     };

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

@@ -0,0 +1,199 @@
+/**
+ * Shared utilities for detecting array-derived expressions in conditionals.
+ *
+ * These utilities detect patterns like:
+ * - arr.some(fn) → { sourcePath: 'arr', operation: 'arraySome' }
+ * - arr.every(fn) → { sourcePath: 'arr', operation: 'arrayEvery' }
+ * - arr.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ *
+ * Used by both:
+ * - variableDeclarationHandler.ts (for variable assignments)
+ * - processExpression.ts (for inline conditionals)
+ */
+
+import ts from 'typescript';
+
+/** Array predicate method operations */
+export type ArrayPredicateOperation =
+  | 'arrayIncludes'
+  | 'arraySome'
+  | 'arrayEvery';
+
+/** Array length operation */
+export type ArrayLengthOperation = 'arrayLength';
+
+/** All array-derived operations */
+export type ArrayDerivedOperation =
+  | ArrayPredicateOperation
+  | ArrayLengthOperation;
+
+/** Result of detecting an array derivation pattern */
+export interface ArrayDerivationResult {
+  sourcePath: string;
+  operation: ArrayDerivedOperation;
+}
+
+/**
+ * Extracts a simple path string from an expression.
+ * Returns the path for identifiers and property access chains.
+ */
+export function getSimplePath(node: ts.Expression): string | null {
+  if (ts.isIdentifier(node)) {
+    return node.text;
+  }
+  if (ts.isPropertyAccessExpression(node)) {
+    const objectPath = getSimplePath(node.expression);
+    if (objectPath) {
+      return `${objectPath}.${node.name.text}`;
+    }
+  }
+  // Handle optional chaining: a?.b
+  if (ts.isNonNullExpression(node)) {
+    return getSimplePath(node.expression);
+  }
+  return null;
+}
+
+/**
+ * Maps array method names to derivation operation names
+ */
+function getArrayPredicateOperation(
+  methodName: string,
+): ArrayPredicateOperation | null {
+  switch (methodName) {
+    case 'includes':
+      return 'arrayIncludes';
+    case 'some':
+      return 'arraySome';
+    case 'every':
+      return 'arrayEvery';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Detects if an expression is an array predicate call and extracts the array path.
+ * Patterns detected:
+ * - arr.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr?.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr.some(fn) → { sourcePath: 'arr', operation: 'arraySome' }
+ * - arr.every(fn) → { sourcePath: 'arr', operation: 'arrayEvery' }
+ * - Boolean(x && arr?.includes(y)) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ */
+export function detectArrayPredicatePattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Unwrap Boolean() calls: Boolean(x) → x
+  if (
+    ts.isCallExpression(expr) &&
+    ts.isIdentifier(expr.expression) &&
+    expr.expression.text === 'Boolean' &&
+    expr.arguments.length === 1
+  ) {
+    return detectArrayPredicatePattern(expr.arguments[0]);
+  }
+
+  // Handle logical AND: a && b - check both sides for array predicates
+  if (
+    ts.isBinaryExpression(expr) &&
+    expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken
+  ) {
+    // Try the right side first (more likely to have the predicate)
+    const rightResult = detectArrayPredicatePattern(expr.right);
+    if (rightResult) return rightResult;
+    // Try the left side
+    const leftResult = detectArrayPredicatePattern(expr.left);
+    if (leftResult) return leftResult;
+    return null;
+  }
+
+  // Handle parenthesized expressions
+  if (ts.isParenthesizedExpression(expr)) {
+    return detectArrayPredicatePattern(expr.expression);
+  }
+
+  if (!ts.isCallExpression(expr)) {
+    return null;
+  }
+
+  const callExpr = expr.expression;
+
+  // Handle both regular property access (arr.includes) and optional chaining (arr?.includes)
+  let objectExpr: ts.Expression | null = null;
+  let methodName: string | null = null;
+
+  if (ts.isPropertyAccessExpression(callExpr)) {
+    objectExpr = callExpr.expression;
+    methodName = callExpr.name.text;
+  } else if (
+    ts.isElementAccessExpression(callExpr) &&
+    ts.isStringLiteral(callExpr.argumentExpression)
+  ) {
+    // Handle arr["includes"]() syntax (rare but possible)
+    objectExpr = callExpr.expression;
+    methodName = callExpr.argumentExpression.text;
+  }
+
+  if (!objectExpr || !methodName) {
+    return null;
+  }
+
+  const operation = getArrayPredicateOperation(methodName);
+  if (!operation) {
+    return null;
+  }
+
+  // Get the source path for the array
+  const sourcePath = getSimplePath(objectExpr);
+  if (!sourcePath) {
+    return null;
+  }
+
+  return { sourcePath, operation };
+}
+
+/**
+ * Detects if an expression is an array.length access.
+ * Patterns detected:
+ * - arr.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ * - arr?.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ */
+export function detectArrayLengthPattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Handle property access: arr.length
+  if (ts.isPropertyAccessExpression(expr)) {
+    if (expr.name.text === 'length') {
+      const sourcePath = getSimplePath(expr.expression);
+      if (sourcePath) {
+        return { sourcePath, operation: 'arrayLength' };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects any array-derived pattern (predicate methods or .length).
+ * This is the main entry point for inline conditional detection.
+ */
+export function detectArrayDerivedPattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Check for array predicate methods first (.some, .every, .includes)
+  const predicateResult = detectArrayPredicatePattern(expr);
+  if (predicateResult) {
+    return predicateResult;
+  }
+
+  // Check for .length access
+  const lengthResult = detectArrayLengthPattern(expr);
+  if (lengthResult) {
+    return lengthResult;
+  }
+
+  return null;
+}