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

package/packages/ai/src/lib/dataStructure/helpers/fillInSchemaGapsAndUnknowns.js

@@ -121,7 +121,11 @@ export default function fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns =
                 lastSubPathPart.match(/signature\[\d+\]/);
             if (!isFunction &&
                 !['object', 'array', 'function', 'async-function'].includes(schema[previousSubPath])) {
-                const newValue = checkIfKnownType(previousSubPath, functionKeysMapping) ?? 'object';
+                // When fillInUnknowns=false, add missing gaps as 'unknown' to preserve raw schema.
+                // When fillInUnknowns=true, infer the type using checkIfKnownType.
+                const newValue = fillInUnknowns
+                    ? (checkIfKnownType(previousSubPath, functionKeysMapping) ?? 'object')
+                    : 'unknown';
                 if (!schema[previousSubPath] ||
                     (fillInUnknowns && schema[previousSubPath] !== newValue)) {
                     schema[previousSubPath] = newValue;
@@ -130,10 +134,14 @@ export default function fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns =
             }
             // Handle the wrong function chaining function().function()
             if (isFunction && !existingSchema(previousSubPath)) {
+                // When fillInUnknowns=false, use 'unknown' for non-function paths.
+                // When fillInUnknowns=true, infer the type.
                 schema[previousSubPath] = previousSubPath.endsWith(')')
                     ? 'function'
-                    : (checkIfKnownType(previousSubPath, functionKeysMapping) ??
-                        'object');
+                    : fillInUnknowns
+                        ? (checkIfKnownType(previousSubPath, functionKeysMapping) ??
+                            'object')
+                        : 'unknown';
                 changeMade = true;
             }
             // Handle function chains: if we have x().y(), set x().functionCallReturnValue to 'function'
@@ -160,7 +168,45 @@ export default function fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns =
         fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns, ++attempts);
     }
 }
-export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSchema, attempts = 0, }) {
+/**
+ * Build indexes for a schema that can be reused across multiple calls.
+ * This avoids rebuilding indexes (~1-2 seconds for 18k keys) on every call.
+ *
+ * @param schema - The schema to build indexes from (typically the full dependency schema)
+ * @returns Indexes that can be passed to fillInDirectSchemaGapsAndUnknowns
+ */
+export function buildSchemaIndexes(schema) {
+    // Build functionKeysMapping + prefixMaxDepth in a single pass
+    // Avoid repeated split/join work by caching parts and building prefixes incrementally.
+    const functionKeysMapping = {};
+    const prefixMaxDepth = new Map();
+    const partsCache = new Map();
+    for (const key in schema) {
+        const parts = getCachedParts(partsCache, key);
+        const lastPart = parts[parts.length - 1];
+        const prefixes = buildPrefixParts(parts);
+        if (key.endsWith(')') ||
+            schema[key] === 'function' ||
+            lastPart === 'length') {
+            const allButLastPart = parts.length > 1 ? prefixes[parts.length - 2] : '';
+            functionKeysMapping[allButLastPart] || (functionKeysMapping[allButLastPart] = []);
+            functionKeysMapping[allButLastPart].push(lastPart);
+        }
+        for (let i = 0; i < prefixes.length; i++) {
+            const prefix = prefixes[i];
+            const existingMax = prefixMaxDepth.get(prefix) ?? 0;
+            if (parts.length > existingMax) {
+                prefixMaxDepth.set(prefix, parts.length);
+            }
+        }
+    }
+    return { functionKeysMapping, prefixMaxDepth };
+}
+export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSchema, attempts = 0, 
+// Pre-built indexes from buildSchemaIndexes() - use for cross-call caching
+prebuiltIndexes, 
+// Internal: pre-computed indexes to avoid rebuilding on recursion
+_functionKeysMapping, _prefixMaxDepth, _partsCache, _prefixPartsCache, _knownTypeCache, _guessTypeCache, _nameHintCache, }) {
     try {
         const existingSchema = (path) => {
             const options = [path, `${scopeName}.${path}`, `${scopeName}().${path}`];
@@ -169,112 +215,250 @@ export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSch
                     return schema[option];
             }
         };
-        const functionKeysMapping = [...Object.keys(schema)]
-            .filter((key) => {
-            if (key.endsWith(')') || schema[key] === 'function')
-                return true;
-            const parts = splitOutsideParenthesesAndArrays(key);
-            if (parts[parts.length - 1] === 'length')
-                return true;
-        })
-            .reduce((acc, key) => {
-            const parts = splitOutsideParenthesesAndArrays(key);
-            const allButLastPart = joinParenthesesAndArrays(parts.slice(0, -1));
-            const lastPart = parts[parts.length - 1];
-            acc[allButLastPart] || (acc[allButLastPart] = []);
-            acc[allButLastPart].push(lastPart);
-            return acc;
-        }, {});
-        let changeMade = false;
-        const guessTypeForPath = (path, defaultType = 'string') => {
-            let knownType = checkIfKnownType(path, functionKeysMapping);
-            if (!knownType) {
-                // Use mergedSchema for type inference if available (has more complete nested paths)
-                // Fall back to schema if mergedSchema is not provided
-                knownType = checkIfObjectOrFunction(path, mergedSchema ?? schema);
+        const partsCache = _partsCache ?? new Map();
+        const prefixPartsCache = _prefixPartsCache ?? new Map();
+        const knownTypeCache = _knownTypeCache ?? new Map();
+        const guessTypeCache = _guessTypeCache ?? new Map();
+        const nameHintCache = _nameHintCache ?? new Map();
+        const getParts = (path) => getCachedParts(partsCache, path);
+        const getPrefixParts = (path) => {
+            const cached = prefixPartsCache.get(path);
+            if (cached)
+                return cached;
+            const prefixes = buildPrefixParts(getParts(path));
+            prefixPartsCache.set(path, prefixes);
+            return prefixes;
+        };
+        // Index resolution priority:
+        // 1. _functionKeysMapping/_prefixMaxDepth (from recursive calls within this invocation)
+        // 2. prebuiltIndexes (from cross-call caching - built once, reused across multiple calls)
+        // 3. Build new indexes (fallback - expensive for large schemas)
+        const functionKeysMapping = _functionKeysMapping ??
+            prebuiltIndexes?.functionKeysMapping ??
+            (() => {
+                const mapping = {};
+                for (const key in schema) {
+                    const parts = getParts(key);
+                    const lastPart = parts[parts.length - 1];
+                    if (key.endsWith(')') ||
+                        schema[key] === 'function' ||
+                        lastPart === 'length') {
+                        const prefixes = getPrefixParts(key);
+                        const allButLastPart = parts.length > 1 ? prefixes[parts.length - 2] : '';
+                        mapping[allButLastPart] || (mapping[allButLastPart] = []);
+                        mapping[allButLastPart].push(lastPart);
+                    }
+                }
+                return mapping;
+            })();
+        // Build prefix index for O(1) lookups in checkIfObjectOrFunction
+        // Maps each prefix to the max depth of keys that have this prefix
+        // This replaces O(n) scans with O(1) lookups, fixing the O(n²) bottleneck
+        let prefixMaxDepth = _prefixMaxDepth ?? prebuiltIndexes?.prefixMaxDepth ?? null;
+        if (!prefixMaxDepth) {
+            prefixMaxDepth = new Map();
+            const targetSchema = mergedSchema ?? schema;
+            for (const key in targetSchema) {
+                const keyParts = getParts(key);
+                const prefixes = buildPrefixParts(keyParts);
+                // Record each prefix of this key with its max depth
+                for (let i = 0; i < prefixes.length; i++) {
+                    const prefix = prefixes[i];
+                    const existingMax = prefixMaxDepth.get(prefix) ?? 0;
+                    if (keyParts.length > existingMax) {
+                        prefixMaxDepth.set(prefix, keyParts.length);
+                    }
+                }
             }
-            if (knownType && schema[path] !== knownType) {
-                return knownType;
+        }
+        // O(1) replacement for checkIfObjectOrFunction
+        const checkIfObjectOrFunctionFast = (path) => {
+            const maxDepth = prefixMaxDepth.get(path);
+            if (maxDepth === undefined)
+                return undefined; // No key starts with this path
+            const pathParts = getParts(path);
+            // Check if path's last part ends with ')' → function
+            const lastPart = pathParts[pathParts.length - 1];
+            if (lastPart?.endsWith(')')) {
+                return 'function';
             }
-            const keyParts = splitOutsideParenthesesAndArrays(path);
-            const lastPart = keyParts[keyParts.length - 1];
+            // Check if there are deeper keys
+            if (maxDepth > pathParts.length) {
+                return 'object';
+            }
+            return undefined;
+        };
+        let changeMade = false;
+        const getKnownType = (path) => {
+            if (knownTypeCache.has(path))
+                return knownTypeCache.get(path);
+            const known = checkIfKnownType(path, functionKeysMapping);
+            knownTypeCache.set(path, known);
+            return known;
+        };
+        const guessTypeFromName = (lastPart, defaultType) => {
+            if (nameHintCache.has(lastPart)) {
+                return nameHintCache.get(lastPart) ?? defaultType;
+            }
+            let hint;
             if (isLikelyBoolean(lastPart)) {
-                return 'boolean';
+                hint = 'boolean';
             }
             else if (isLikelyDate(lastPart)) {
-                return 'date';
+                hint = 'date';
             }
             else if (isLikelyAction(lastPart)) {
-                return 'function';
+                hint = 'function';
             }
             else if (pluralize.isPlural(lastPart)) {
-                return 'number';
+                // Default to number instead of array - safer for JSX rendering
+                // Arrays cause "Objects are not valid as a React child" errors when rendered directly
+                hint = 'number';
+            }
+            nameHintCache.set(lastPart, hint);
+            return hint ?? defaultType;
+        };
+        const guessTypeForPath = (path, defaultType = 'string') => {
+            const cacheKey = `${path}|${defaultType}`;
+            if (guessTypeCache.has(cacheKey)) {
+                return guessTypeCache.get(cacheKey);
+            }
+            let knownType = getKnownType(path);
+            if (!knownType) {
+                // Use optimized O(1) prefix lookup instead of O(n) scan
+                knownType = checkIfObjectOrFunctionFast(path);
             }
-            else {
-                return defaultType;
+            if (knownType) {
+                guessTypeCache.set(cacheKey, knownType);
+                return knownType;
             }
+            const keyParts = getParts(path);
+            const lastPart = keyParts[keyParts.length - 1];
+            const guessed = guessTypeFromName(lastPart, defaultType);
+            guessTypeCache.set(cacheKey, guessed);
+            return guessed;
         };
         for (const key in schema) {
             if (!schema[key])
                 schema[key] = 'unknown';
             if (schema[key].includes(' | unknown')) {
-                schema[key] = schema[key].replace(' | unknown', '');
-                changeMade = true;
+                const cleaned = schema[key].replace(' | unknown', '');
+                if (schema[key] !== cleaned) {
+                    schema[key] = cleaned;
+                    changeMade = true;
+                }
             }
             else if (schema[key].startsWith('unknown | ')) {
                 // Handle "unknown | undefined" -> "string | undefined"
                 const remainingType = schema[key].substring('unknown | '.length);
                 const newType = guessTypeForPath(key, 'string');
                 if (newType) {
-                    schema[key] = `${newType} | ${remainingType}`;
-                    changeMade = true;
+                    const replacement = `${newType} | ${remainingType}`;
+                    if (schema[key] !== replacement) {
+                        schema[key] = replacement;
+                        changeMade = true;
+                    }
                 }
             }
             else if (schema[key] === 'unknown') {
                 const newType = guessTypeForPath(key, 'string');
-                if (newType) {
+                // Don't convert 'unknown' to 'object' — 'object' is just inferred from
+                // having child properties, which isn't more useful than 'unknown' and
+                // prevents enrichment from filling in the actual type later.
+                if (newType && newType !== 'object' && schema[key] !== newType) {
                     schema[key] = newType;
                     changeMade = true;
                 }
             }
-            const keyParts = splitOutsideParenthesesAndArrays(key);
+            const keyParts = getParts(key);
+            const prefixParts = getPrefixParts(key);
             for (let i = 0; i < keyParts.length; i++) {
-                const subPathParts = keyParts.slice(0, i + 1);
-                const lastSubPathPart = subPathParts[subPathParts.length - 1];
-                const previousSubPathParts = subPathParts.slice(0, i);
-                if (previousSubPathParts.length === 0)
+                if (i === 0)
                     continue;
-                const previousSubPath = joinParenthesesAndArrays(previousSubPathParts);
-                if (cleanOutBoundary(lastSubPathPart).match(/\[\d*\]/) &&
-                    !lastSubPathPart.match(/signature\[\d+\]/)) {
-                    // Fix 39: Don't overwrite explicit 'object' types with 'array'
-                    // This handles spurious [] paths from components like JsonNode that handle
-                    // both arrays and objects. When metadata is explicitly typed as 'object',
-                    // paths like metadata[] (from dynamic iteration) should not change it.
-                    if (schema[previousSubPath] !== 'array' &&
-                        schema[previousSubPath] !== 'object') {
-                        schema[previousSubPath] = 'array';
-                        changeMade = true;
+                const lastSubPathPart = keyParts[i];
+                const previousSubPath = prefixParts[i - 1];
+                const isSignatureIndex = lastSubPathPart.includes('signature[') &&
+                    SIGNATURE_INDEX_REGEX.test(lastSubPathPart);
+                if (lastSubPathPart.includes('[')) {
+                    const cleaned = cleanOutBoundary(lastSubPathPart);
+                    if (cleaned.match(/\[\d*\]/) && !isSignatureIndex) {
+                        // Fix 39: Don't overwrite explicit 'object' types with 'array'
+                        // This handles spurious [] paths from components like JsonNode that handle
+                        // both arrays and objects. When metadata is explicitly typed as 'object',
+                        // paths like metadata[] (from dynamic iteration) should not change it.
+                        const existingType = schema[previousSubPath];
+                        const baseType = existingType?.split(' | ')[0];
+                        // Also check if this path has meaningful object property children (non-[] children).
+                        // If it does, it's an object with mixed access patterns (e.g., agent.entries
+                        // AND agent[].type), not a pure array. Don't infer 'array' in that case.
+                        // Exclude .length since it exists on arrays too and is NOT evidence of object-ness.
+                        let hasObjectPropertyChildren = false;
+                        if (baseType !== 'array' && baseType !== 'object') {
+                            const dotPrefix = previousSubPath + '.';
+                            const lengthPath = previousSubPath + '.length';
+                            for (const schemaKey in schema) {
+                                if (schemaKey.startsWith(dotPrefix) &&
+                                    schemaKey !== lengthPath) {
+                                    hasObjectPropertyChildren = true;
+                                    break;
+                                }
+                            }
+                        }
+                        if (baseType !== 'array' &&
+                            baseType !== 'object' &&
+                            !hasObjectPropertyChildren) {
+                            // Preserve nullability from existing type (e.g., 'unknown | undefined' -> 'array | undefined')
+                            let newType = 'array';
+                            if (existingType?.includes(' | undefined')) {
+                                newType = 'array | undefined';
+                            }
+                            else if (existingType?.includes(' | null')) {
+                                newType = 'array | null';
+                            }
+                            if (schema[previousSubPath] !== newType) {
+                                schema[previousSubPath] = newType;
+                                changeMade = true;
+                            }
+                        }
                     }
                 }
                 const isFunction = lastSubPathPart.endsWith(')') ||
                     lastSubPathPart === 'functionCallReturnValue' ||
-                    lastSubPathPart.match(/signature\[\d+\]/);
+                    isSignatureIndex;
                 if (!isFunction &&
                     !['object', 'array', 'function', 'async-function'].includes(schema[previousSubPath])) {
-                    const newValue = checkIfKnownType(previousSubPath, functionKeysMapping) ?? 'object';
-                    if (!schema[previousSubPath] ||
-                        schema[previousSubPath] !== newValue) {
-                        schema[previousSubPath] = newValue;
-                        changeMade = true;
+                    const existingType = schema[previousSubPath];
+                    const baseExistingType = existingType?.split(' | ')[0];
+                    // Skip if the base type is already a structured type
+                    if (!['object', 'array', 'function', 'async-function'].includes(baseExistingType)) {
+                        let newValue = getKnownType(previousSubPath) ?? 'object';
+                        // Don't overwrite 'unknown' with 'object' — 'object' is just
+                        // inferred from child properties and isn't more useful than 'unknown'
+                        if (newValue === 'object' &&
+                            existingType &&
+                            existingType.split(' | ')[0] === 'unknown') {
+                            // preserve existing 'unknown' (possibly with nullability)
+                        }
+                        else {
+                            // Preserve nullability from existing type
+                            if (existingType?.includes(' | undefined')) {
+                                newValue = `${newValue} | undefined`;
+                            }
+                            else if (existingType?.includes(' | null')) {
+                                newValue = `${newValue} | null`;
+                            }
+                            if (!existingType || existingType !== newValue) {
+                                schema[previousSubPath] = newValue;
+                                changeMade = true;
+                            }
+                        }
                     }
                 }
                 // Handle the wrong function chaining function().function()
                 if (isFunction && !existingSchema(previousSubPath)) {
                     schema[previousSubPath] = previousSubPath.endsWith(')')
                         ? 'function'
-                        : (checkIfKnownType(previousSubPath, functionKeysMapping) ??
-                            'object');
+                        : (getKnownType(previousSubPath) ?? 'object');
                     changeMade = true;
                 }
                 // Handle function chains: if we have x().y(), set x().functionCallReturnValue to 'function'
@@ -282,8 +466,11 @@ export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSch
                 if (lastSubPathPart.endsWith(')') && previousSubPath.endsWith(')')) {
                     const functionReturnValuePath = `${previousSubPath}.functionCallReturnValue`;
                     // Extract the method name from lastSubPathPart (e.g., "then()" -> "then")
-                    const methodName = lastSubPathPart.split('(')[0];
-                    const isPromiseMethod = ['then', 'catch', 'finally'].includes(methodName);
+                    const parenIndex = lastSubPathPart.indexOf('(');
+                    const methodName = parenIndex === -1
+                        ? lastSubPathPart
+                        : lastSubPathPart.slice(0, parenIndex);
+                    const isPromiseMethod = PROMISE_METHODS.has(methodName);
                     const isPreviousAsync = schema[previousSubPath] === 'async-function';
                     // Don't set to 'function' if this is a promise method on an async function
                     // (we want the awaited value, not the promise)
@@ -304,6 +491,15 @@ export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSch
                 schema,
                 mergedSchema,
                 attempts: ++attempts,
+                prebuiltIndexes,
+                // Pass pre-computed indexes to avoid rebuilding on each recursive call
+                _functionKeysMapping: functionKeysMapping,
+                _prefixMaxDepth: prefixMaxDepth,
+                _partsCache: partsCache,
+                _prefixPartsCache: prefixPartsCache,
+                _knownTypeCache: knownTypeCache,
+                _guessTypeCache: guessTypeCache,
+                _nameHintCache: nameHintCache,
             });
         }
         // Remove .length paths when the parent is typed as 'array' or 'string' (or nullable variants).
@@ -312,9 +508,10 @@ export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSch
         // However, if the parent could be an 'object' or other type, keep .length as it may be
         // a custom property.
         for (const key of Object.keys(schema)) {
-            const parts = splitOutsideParenthesesAndArrays(key);
+            const parts = getParts(key);
             if (parts[parts.length - 1] === 'length') {
-                const parentPath = joinParenthesesAndArrays(parts.slice(0, -1));
+                const prefixes = getPrefixParts(key);
+                const parentPath = parts.length > 1 ? prefixes[parts.length - 2] : '';
                 const parentType = schema[parentPath];
                 if (parentType) {
                     // Split union types and filter out nullable parts
@@ -339,6 +536,36 @@ export function fillInDirectSchemaGapsAndUnknowns({ scopeName, schema, mergedSch
         throw error;
     }
 }
+const SIGNATURE_INDEX_REGEX = /signature\[\d+\]/;
+const PROMISE_METHODS = new Set(['then', 'catch', 'finally']);
+function getCachedParts(cache, path) {
+    const cached = cache.get(path);
+    if (cached)
+        return cached;
+    const parts = splitOutsideParenthesesAndArrays(path);
+    cache.set(path, parts);
+    return parts;
+}
+function buildPrefixParts(parts) {
+    if (parts.length === 0)
+        return [];
+    const prefixes = new Array(parts.length);
+    let prefix = '';
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (i === 0) {
+            prefix = part;
+        }
+        else if (part.startsWith('[') || part.startsWith('(')) {
+            prefix += part;
+        }
+        else {
+            prefix += `.${part}`;
+        }
+        prefixes[i] = prefix;
+    }
+    return prefixes;
+}
 function checkIfObjectOrFunction(path, schema) {
     const pathParts = splitOutsideParenthesesAndArrays(path);
     for (const structureKey in schema) {
@@ -389,28 +616,45 @@ const STRONG_ARRAY_METHODS = new Set([
     'toSpliced',
     'with',
 ]);
+/**
+ * Check if a method call argument looks like a string literal.
+ * String literals start with ' or " (e.g., includes('foo'), indexOf("bar"))
+ */
+function hasStringLiteralArgument(methodCall) {
+    const parenIndex = methodCall.indexOf('(');
+    if (parenIndex === -1)
+        return false;
+    const arg = methodCall.slice(parenIndex + 1).trim();
+    return arg.startsWith("'") || arg.startsWith('"') || arg.startsWith('`');
+}
 function checkIfKnownType(key, functionAndAttributesKeysMapping) {
     let isArray;
     let isString;
     let hasStrongArrayEvidence = false;
     let hasOnlyAmbiguousArrayMethods = true;
     let hasLengthAccess = false;
-    let hasArrayStringAmbiguousMethod = false;
-    for (const functionOrAttributeName of functionAndAttributesKeysMapping[key] ??
-        []) {
+    let hasIncludesOrIndexOfWithVariable = false;
+    const entries = functionAndAttributesKeysMapping[key];
+    if (!entries || entries.length === 0)
+        return;
+    for (const functionOrAttributeName of entries) {
         // Extract the method name without arguments for checking against ambiguous list
         const methodName = functionOrAttributeName.split('(')[0].trim();
-        const couldBeArray = knownMethodCalls(functionOrAttributeName).includes('array') ||
-            functionOrAttributeName === 'length';
-        const couldBeString = knownMethodCalls(functionOrAttributeName).includes('string') ||
-            functionOrAttributeName === 'length';
+        const knownType = knownMethodCalls(functionOrAttributeName);
+        const couldBeArray = knownType.includes('array') || functionOrAttributeName === 'length';
+        const couldBeString = knownType.includes('string') || functionOrAttributeName === 'length';
         // Track .length access
         if (functionOrAttributeName === 'length') {
             hasLengthAccess = true;
         }
         // Track methods that exist on both arrays and strings (like includes, indexOf)
-        if (couldBeArray && couldBeString && functionOrAttributeName !== 'length') {
-            hasArrayStringAmbiguousMethod = true;
+        // Check if .includes() or .indexOf() is called with a variable argument (not a string literal).
+        // Pattern: arr.includes(item) -> likely array (checking if item exists)
+        // Pattern: str.includes('substring') -> likely string (checking for substring)
+        if ((methodName === 'includes' || methodName === 'indexOf') &&
+            functionOrAttributeName.includes('(') &&
+            !hasStringLiteralArgument(functionOrAttributeName)) {
+            hasIncludesOrIndexOfWithVariable = true;
         }
         // Check if this is strong evidence of an array (unambiguous array methods)
         if (STRONG_ARRAY_METHODS.has(methodName)) {
@@ -437,17 +681,20 @@ function checkIfKnownType(key, functionAndAttributesKeysMapping) {
     if (isArray && hasStrongArrayEvidence) {
         return 'array';
     }
-    // When we have BOTH .length AND an ambiguous method like .includes(),
-    // prefer array. This pattern (checking .length AND calling .includes)
-    // is very common with arrays (e.g., arr.length > 0 && arr.includes(x))
-    // but rare with strings (you'd typically just call str.includes(x))
-    if (isArray && hasLengthAccess && hasArrayStringAmbiguousMethod) {
+    // When .includes() or .indexOf() is called with a variable argument, prefer array.
+    // Pattern: arr.includes(item) -> likely array (checking if item exists in collection)
+    // String literals are already filtered by hasStringLiteralArgument, so if we get here
+    // with a variable argument, it's strong evidence of array membership testing.
+    if (isArray && hasIncludesOrIndexOfWithVariable) {
         return 'array';
     }
+    // When both array and string are possible, prefer string.
+    // Strings have .length, .slice(), .includes(), etc. just like arrays.
+    // We only infer 'array' if we have STRONG evidence (like .map, .filter, .reduce).
     if (isString)
         return 'string';
-    // Only infer array if we have strong evidence OR not only ambiguous methods
-    // This prevents router.push() from being incorrectly inferred as an array
+    // Only infer array if we have strong evidence (already handled above)
+    // or non-ambiguous array methods that don't exist on strings
     if (isArray && !hasOnlyAmbiguousArrayMethods) {
         return 'array';
     }