@codeyam/codeyam-cli 0.0.0 → 0.1.0-staging.036391e

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

@@ -0,0 +1,1065 @@
+import {
+  splitOutsideParenthesesAndArrays,
+  joinParenthesesAndArrays,
+} from '../../splitOutsideParentheses';
+import pluralize from 'pluralize';
+import knownMethodCalls from './knownMethodCalls';
+import { ScopeNode } from '../ScopeDataStructure';
+import cleanOutBoundary from '../../cleanOutBoundary';
+
+export default function fillInSchemaGapsAndUnknowns(
+  scopeNode: Pick<ScopeNode, 'name' | 'schema' | 'equivalencies'>,
+  fillInUnknowns = false,
+  attempts = 0,
+) {
+  const { name, schema, equivalencies } = scopeNode;
+
+  const existingSchema = (path: any) => {
+    const options = [path, `${name}.${path}`, `${name}().${path}`];
+    for (const option of options) {
+      if (schema[option] && schema[option] !== 'unknown') 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].push(lastPart);
+        return acc;
+      },
+      {} as Record<string, string[]>,
+    );
+
+  let changeMade = false;
+  const guessTypeForPath = (path: string, defaultType = 'string') => {
+    let knownType = checkIfKnownType(path, functionKeysMapping);
+    if (!knownType) {
+      knownType = checkIfObjectOrFunction(path, schema);
+    }
+
+    if (knownType && schema[path] !== knownType) {
+      return knownType;
+    }
+
+    const keyParts = splitOutsideParenthesesAndArrays(path);
+    const lastPart = keyParts[keyParts.length - 1];
+
+    if (isLikelyBoolean(lastPart)) {
+      return 'boolean';
+    } else if (isLikelyDate(lastPart)) {
+      return 'date';
+    } else if (isLikelyAction(lastPart)) {
+      return 'function';
+    } else if (pluralize.isPlural(lastPart)) {
+      // Default to number instead of array - safer for JSX rendering
+      // Arrays cause "Objects are not valid as a React child" errors when rendered directly
+      return 'number';
+    } else {
+      return defaultType;
+    }
+  };
+
+  if (fillInUnknowns) {
+    for (const [equivalentKey, equivalentValues] of Object.entries(
+      equivalencies,
+    )) {
+      for (const equivalentValue of equivalentValues) {
+        if (
+          schema[equivalentKey] === 'unknown' &&
+          schema[equivalentValue.schemaPath] === 'unknown'
+        ) {
+          const newEquivalentValueType = guessTypeForPath(
+            equivalentValue.schemaPath,
+          );
+          if (newEquivalentValueType) {
+            schema[equivalentValue.schemaPath] = newEquivalentValueType;
+            changeMade = true;
+          }
+        }
+
+        if (
+          schema[equivalentKey] === 'unknown' &&
+          schema[equivalentValue.schemaPath] &&
+          schema[equivalentValue.schemaPath] !== 'unknown'
+        ) {
+          schema[equivalentKey] = schema[equivalentValue.schemaPath];
+          changeMade = true;
+        }
+      }
+    }
+  }
+
+  for (const key in schema) {
+    if (fillInUnknowns) {
+      if (!schema[key]) schema[key] = 'unknown';
+      if (schema[key].includes(' | unknown')) {
+        schema[key] = schema[key].replace(' | unknown', '');
+        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;
+        }
+      } else if (schema[key] === 'unknown') {
+        const newType = guessTypeForPath(key, 'string');
+        if (newType) {
+          schema[key] = newType;
+          changeMade = true;
+        }
+      }
+    }
+
+    const keyParts = splitOutsideParenthesesAndArrays(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) continue;
+
+      const previousSubPath = joinParenthesesAndArrays(previousSubPathParts);
+
+      if (
+        cleanOutBoundary(lastSubPathPart).match(/\[\d*\]/) &&
+        !lastSubPathPart.match(/signature\[\d+\]/)
+      ) {
+        if (schema[previousSubPath] !== 'array') {
+          schema[previousSubPath] = 'array';
+          changeMade = true;
+        }
+      }
+
+      const isFunction =
+        lastSubPathPart.endsWith(')') ||
+        lastSubPathPart === 'functionCallReturnValue' ||
+        lastSubPathPart.match(/signature\[\d+\]/);
+
+      if (
+        !isFunction &&
+        !['object', 'array', 'function', 'async-function'].includes(
+          schema[previousSubPath],
+        )
+      ) {
+        // 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;
+          changeMade = true;
+        }
+      }
+
+      // 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'
+          : fillInUnknowns
+            ? (checkIfKnownType(previousSubPath, functionKeysMapping) ??
+              'object')
+            : 'unknown';
+        changeMade = true;
+      }
+
+      // Handle function chains: if we have x().y(), set x().functionCallReturnValue to 'function'
+      // Only do this when the current part is an actual method (ends with ')'), not 'functionCallReturnValue'
+      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 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)
+        if (
+          fillInUnknowns &&
+          schema[functionReturnValuePath] &&
+          schema[functionReturnValuePath] !== 'function' &&
+          !(isPromiseMethod && isPreviousAsync)
+        ) {
+          schema[functionReturnValuePath] = 'function';
+          changeMade = true;
+        }
+      }
+    }
+  }
+
+  if (changeMade && attempts < 10) {
+    fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns, ++attempts);
+  }
+}
+
+/**
+ * Pre-built indexes that can be reused across multiple calls to fillInDirectSchemaGapsAndUnknowns.
+ * Build once with buildSchemaIndexes(), then pass to all calls processing the same schema.
+ */
+export interface SchemaIndexes {
+  functionKeysMapping: Record<string, string[]>;
+  prefixMaxDepth: Map<string, number>;
+}
+
+/**
+ * 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: Record<string, string>,
+): SchemaIndexes {
+  // Build functionKeysMapping + prefixMaxDepth in a single pass
+  // Avoid repeated split/join work by caching parts and building prefixes incrementally.
+  const functionKeysMapping: Record<string, string[]> = {};
+  const prefixMaxDepth = new Map<string, number>();
+  const partsCache = new Map<string, string[]>();
+
+  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].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,
+}: {
+  scopeName?: string;
+  schema: Record<string, string>;
+  mergedSchema?: Record<string, string>;
+  attempts?: number;
+  /** Pre-built indexes from buildSchemaIndexes() - pass to reuse across multiple calls */
+  prebuiltIndexes?: SchemaIndexes;
+  // Internal: pre-computed indexes to avoid rebuilding on recursion (used by recursive calls)
+  _functionKeysMapping?: Record<string, string[]>;
+  _prefixMaxDepth?: Map<string, number>;
+  _partsCache?: Map<string, string[]>;
+  _prefixPartsCache?: Map<string, string[]>;
+  _knownTypeCache?: Map<string, string | undefined>;
+  _guessTypeCache?: Map<string, string | undefined>;
+  _nameHintCache?: Map<string, string | undefined>;
+}) {
+  try {
+    const existingSchema = (path: any) => {
+      const options = [path, `${scopeName}.${path}`, `${scopeName}().${path}`];
+      for (const option of options) {
+        if (schema[option] && schema[option] !== 'unknown')
+          return schema[option];
+      }
+    };
+
+    const partsCache = _partsCache ?? new Map<string, string[]>();
+    const prefixPartsCache = _prefixPartsCache ?? new Map<string, string[]>();
+    const knownTypeCache =
+      _knownTypeCache ?? new Map<string, string | undefined>();
+    const guessTypeCache =
+      _guessTypeCache ?? new Map<string, string | undefined>();
+    const nameHintCache =
+      _nameHintCache ?? new Map<string, string | undefined>();
+
+    const getParts = (path: string) => getCachedParts(partsCache, path);
+    const getPrefixParts = (path: string) => {
+      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: Record<string, string[]> = {};
+        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].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<string, number>();
+      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);
+          }
+        }
+      }
+    }
+
+    // O(1) replacement for checkIfObjectOrFunction
+    const checkIfObjectOrFunctionFast = (path: string): string | undefined => {
+      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';
+      }
+
+      // Check if there are deeper keys
+      if (maxDepth > pathParts.length) {
+        return 'object';
+      }
+
+      return undefined;
+    };
+
+    let changeMade = false;
+    const getKnownType = (path: string) => {
+      if (knownTypeCache.has(path)) return knownTypeCache.get(path);
+      const known = checkIfKnownType(path, functionKeysMapping);
+      knownTypeCache.set(path, known);
+      return known;
+    };
+    const guessTypeFromName = (lastPart: string, defaultType: string) => {
+      if (nameHintCache.has(lastPart)) {
+        return nameHintCache.get(lastPart) ?? defaultType;
+      }
+
+      let hint: string | undefined;
+      if (isLikelyBoolean(lastPart)) {
+        hint = 'boolean';
+      } else if (isLikelyDate(lastPart)) {
+        hint = 'date';
+      } else if (isLikelyAction(lastPart)) {
+        hint = 'function';
+      } else if (pluralize.isPlural(lastPart)) {
+        // 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: string, 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);
+      }
+
+      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')) {
+        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) {
+          const replacement = `${newType} | ${remainingType}`;
+          if (schema[key] !== replacement) {
+            schema[key] = replacement;
+            changeMade = true;
+          }
+        }
+      } else if (schema[key] === 'unknown') {
+        const newType = guessTypeForPath(key, 'string');
+        // 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 = getParts(key);
+      const prefixParts = getPrefixParts(key);
+      for (let i = 0; i < keyParts.length; i++) {
+        if (i === 0) continue;
+        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' ||
+          isSignatureIndex;
+
+        if (
+          !isFunction &&
+          !['object', 'array', 'function', 'async-function'].includes(
+            schema[previousSubPath],
+          )
+        ) {
+          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'
+            : (getKnownType(previousSubPath) ?? 'object');
+          changeMade = true;
+        }
+
+        // Handle function chains: if we have x().y(), set x().functionCallReturnValue to 'function'
+        // Only do this when the current part is an actual method (ends with ')'), not 'functionCallReturnValue'
+        if (lastSubPathPart.endsWith(')') && previousSubPath.endsWith(')')) {
+          const functionReturnValuePath = `${previousSubPath}.functionCallReturnValue`;
+
+          // Extract the method name from lastSubPathPart (e.g., "then()" -> "then")
+          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)
+          // Also don't overwrite 'array' - the function might return an array (e.g., getAll())
+          if (
+            schema[functionReturnValuePath] &&
+            schema[functionReturnValuePath] !== 'function' &&
+            schema[functionReturnValuePath] !== 'array' &&
+            !(isPromiseMethod && isPreviousAsync)
+          ) {
+            schema[functionReturnValuePath] = 'function';
+            changeMade = true;
+          }
+        }
+      }
+    }
+
+    if (changeMade && attempts < 10) {
+      fillInDirectSchemaGapsAndUnknowns({
+        scopeName,
+        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).
+    // These are built-in properties that were used for type inference but shouldn't appear
+    // in the final schema (they create { length: N } objects instead of proper arrays).
+    // 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 = getParts(key);
+      if (parts[parts.length - 1] === 'length') {
+        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
+          const typeParts = parentType.split(' | ').map((t) => t.trim());
+          const nonNullableTypes = typeParts.filter(
+            (t) => t !== 'undefined' && t !== 'null',
+          );
+          // Only remove if ALL non-nullable types are array or string
+          // This ensures we don't remove .length from potential custom objects
+          if (
+            nonNullableTypes.length > 0 &&
+            nonNullableTypes.every((t) => t === 'array' || t === 'string')
+          ) {
+            delete schema[key];
+          }
+        }
+      }
+    }
+
+    return schema;
+  } catch (error) {
+    console.info(
+      'Failed to fill in schema gaps and unknowns for scope:',
+      JSON.stringify(
+        {
+          scopeName,
+          schema,
+        },
+        null,
+        2,
+      ),
+    );
+    throw error;
+  }
+}
+
+const SIGNATURE_INDEX_REGEX = /signature\[\d+\]/;
+const PROMISE_METHODS = new Set(['then', 'catch', 'finally']);
+
+function getCachedParts(cache: Map<string, string[]>, path: string): string[] {
+  const cached = cache.get(path);
+  if (cached) return cached;
+  const parts = splitOutsideParenthesesAndArrays(path);
+  cache.set(path, parts);
+  return parts;
+}
+
+function buildPrefixParts(parts: string[]): string[] {
+  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: string, schema: ScopeNode['schema']) {
+  const pathParts = splitOutsideParenthesesAndArrays(path);
+  for (const structureKey in schema) {
+    if (structureKey.startsWith(path)) {
+      const structureKeyParts = splitOutsideParenthesesAndArrays(structureKey);
+      const relevantPart = structureKeyParts[pathParts.length - 1];
+      // Guard against undefined (can happen with complex keys containing expanded callback text)
+      if (relevantPart?.endsWith(')')) {
+        return 'function';
+      } else if (structureKeyParts.length > pathParts.length) {
+        return 'object';
+      }
+    }
+  }
+}
+
+// Methods that are ambiguous - used on both arrays and non-arrays
+// These methods exist on arrays but also on Map, Set, Headers, FormData, URLSearchParams, etc.
+// Don't infer array type from these alone without additional evidence
+const AMBIGUOUS_ARRAY_METHODS = new Set([
+  'push',
+  'pop',
+  'entries',
+  'keys',
+  'values',
+  'forEach',
+]);
+
+// Methods that are strongly indicative of arrays - only arrays have these
+// Note: entries, keys, values, forEach are NOT in this list because they also exist
+// on Map, Set, Headers, FormData, URLSearchParams, and other iterable types
+const STRONG_ARRAY_METHODS = new Set([
+  'map',
+  'filter',
+  'reduce',
+  'reduceRight',
+  'every',
+  'some',
+  'find',
+  'findIndex',
+  'findLast',
+  'findLastIndex',
+  'flat',
+  'flatMap',
+  'fill',
+  'copyWithin',
+  'toReversed',
+  'toSorted',
+  '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: string): boolean {
+  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: string,
+  functionAndAttributesKeysMapping: Record<string, string[]>,
+) {
+  let isArray: boolean | undefined;
+  let isString: boolean | undefined;
+  let hasStrongArrayEvidence = false;
+  let hasOnlyAmbiguousArrayMethods = true;
+  let hasLengthAccess = false;
+  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 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)
+    // 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)) {
+      hasStrongArrayEvidence = true;
+    }
+
+    // Check if we have any non-ambiguous array method
+    if (couldBeArray && !AMBIGUOUS_ARRAY_METHODS.has(methodName)) {
+      hasOnlyAmbiguousArrayMethods = false;
+    }
+
+    if (!couldBeArray) {
+      isArray = false;
+    }
+    if (!couldBeString) {
+      isString = false;
+    }
+
+    if (isArray !== false && couldBeArray) {
+      isArray = true;
+    }
+    if (isString !== false && couldBeString) {
+      isString = true;
+    }
+  }
+
+  // Strong array evidence (unambiguous methods like .map, .filter) -> definitely array
+  if (isArray && hasStrongArrayEvidence) {
+    return 'array';
+  }
+
+  // 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 (already handled above)
+  // or non-ambiguous array methods that don't exist on strings
+  if (isArray && !hasOnlyAmbiguousArrayMethods) {
+    return 'array';
+  }
+}
+
+// --- Targeted Verb List for Programming ---
+const commonProgrammingVerbs = new Set([
+  'add',
+  'get',
+  'set',
+  'create',
+  'read',
+  'update',
+  'delete',
+  'remove',
+  'calculate',
+  'validate',
+  'parse',
+  'load',
+  'save',
+  'init',
+  'initialize',
+  'start',
+  'stop',
+  'send',
+  'receive',
+  'build',
+  'find',
+  'search',
+  'is',
+  'has',
+  'can',
+  'should',
+  'check',
+  'process',
+  'generate',
+  'render',
+  'fetch',
+  'push',
+  'pop',
+  'open',
+  'close',
+  'connect',
+  'disconnect',
+  'enable',
+  'disable',
+  'append',
+  'prepend',
+  'insert',
+  'select',
+  'make',
+  'perform',
+  'execute',
+  'run',
+  'join',
+  'split',
+  'merge',
+  'clear',
+  'reset',
+  'await',
+  'handle',
+  'log',
+  'debug',
+  'show',
+  'hide',
+  'toggle',
+  'mount',
+  'unmount',
+  'register',
+  'unregister',
+  'emit',
+  'broadcast',
+  'apply',
+  'format',
+  'move',
+  'copy',
+  'compare',
+  // Add more as needed based on your specific domain/codebase
+]);
+
+const commonBooleanIndicators = new Set([
+  'is',
+  'has',
+  'can',
+  'should',
+  'was',
+  'were',
+  'are',
+  'will',
+  'would',
+  'could',
+  'might',
+  'must',
+  'need',
+  'want',
+  'allow',
+  'permit',
+  'enable',
+  'disable',
+  'diabled',
+  'block',
+  'prevent',
+  'forbid',
+  'prohibit',
+  'accept',
+  'reject',
+  'agree',
+  'disagree',
+  'confirm',
+  'deny',
+  'validate',
+  'invalidate',
+  'check',
+  'verify',
+  'test',
+  'assert',
+  'ensure',
+  'guarantee',
+  'promise',
+  'assure',
+  'warrant',
+  'certify',
+]);
+
+/**
+ * Splits camelCase, PascalCase, or snake_case identifiers into words.
+ * Handles simple acronyms (e.g., HTTPResponse -> ['http', 'response']).
+ * @param {string} identifier
+ * @returns {string[]} Array of words in lowercase.
+ */
+function splitIdentifier(identifier: any) {
+  if (!identifier) return [];
+
+  // Handle snake_case first
+  identifier = identifier.replace(/_/g, ' ');
+
+  // Split based on capital letters, including handling sequences of capitals (acronyms)
+  // Example: "addData" -> "add Data"
+  // Example: "HTTPResponse" -> "HTTP Response"
+  // Example: "myNASAData" -> "my NASA Data"
+  const words = identifier
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // Split acronym followed by word (HTTPRequest -> HTTP Request)
+    .replace(/([a-z\d])([A-Z])/g, '$1 $2') // Split word/digit followed by capital (addData -> add Data)
+    .split(' ');
+
+  return words.map((word: any) => word.toLowerCase()).filter(Boolean); // Filter empty strings from potential multiple spaces
+}
+
+/**
+ * Checks if a variable name likely represents an action (often starts with a verb).
+ * @param {string} varName The variable name.
+ * @returns {boolean}
+ */
+function isLikelyAction(varName: any) {
+  const words = splitIdentifier(varName);
+  if (words.length === 0) {
+    return false;
+  }
+  // Check if the first word is a common programming verb
+  return commonProgrammingVerbs.has(words[0]);
+}
+
+/**
+ * Checks if a variable name likely represents a boolean value.
+ * @param {string} varName The variable name.
+ * @returns {boolean}
+ */
+function isLikelyBoolean(varName: any) {
+  const words = splitIdentifier(varName);
+  if (words.length === 0) {
+    return false;
+  }
+  // Check if the first word is a common programming boolean indicator
+  if (commonBooleanIndicators.has(words[0])) return true;
+
+  const booleanOperators = ['===', '!==', '==', '!=', '>=', '<=', '>', '<'];
+
+  if (booleanOperators.some((op) => varName.includes(op))) return true;
+  return false;
+}
+
+/**
+ * Checks if a variable name likely represents a date.
+ * @param {string} varName The variable name.
+ * @returns {boolean}
+ */
+function isLikelyDate(varName: any) {
+  const words = splitIdentifier(varName);
+  if (words.length === 0) {
+    return false;
+  }
+  // Check for common date-related terms
+  const dateIndicators = new Set([
+    'date',
+    'time',
+    'timestamp',
+    'datetime',
+    'day',
+    'month',
+    'year',
+    'calendar',
+    'epoch',
+  ]);
+
+  return words.some((word: any) => dateIndicators.has(word));
+}