@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

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

@@ -64,6 +64,14 @@ const protoMethodSets: Record<PrimitiveKind, Set<string>> = {
   ),
 };
 
+/** Built-in properties (not methods) that should be removed from primitives.
+ * These are properties that exist on the prototype and shouldn't appear
+ * as schema entries (they cause malformed mock data structures). */
+const protoPropertySets: Partial<Record<PrimitiveKind, Set<string>>> = {
+  array: new Set(['length']),
+  string: new Set(['length']),
+};
+
 /**
  * Extract primitive kind from a type string, handling union types.
  * E.g., "number | undefined" -> "number", "string | null" -> "string"
@@ -118,11 +126,21 @@ function scrub(
       const rootKind = rootTable.get(prefix);
       if (!rootKind) continue;
 
-      const rawMethod = keyParts[cut].split('(')[0];
+      const rawToken = keyParts[cut];
+      const rawMethod = rawToken.split('(')[0];
+
+      // Check if it's a prototype method (e.g., map, filter, toString)
       if (protoMethodSets[rootKind].has(rawMethod)) {
         onRemove(keyPath);
         break;
       }
+
+      // Check if it's a built-in property (e.g., length on arrays/strings)
+      const propertySet = protoPropertySets[rootKind];
+      if (propertySet && propertySet.has(rawToken)) {
+        onRemove(keyPath);
+        break;
+      }
     }
   }
 }

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

@@ -30,11 +30,30 @@ export const nonTransformingArrayMethodsSet = new Set([
   'reverse',
   'entries',
 ]);
-const isolatingArrayMethodsSet = new Set(['find', 'at', 'pop', 'shift']);
+const isolatingArrayMethodsSet = new Set([
+  'find',
+  'findLast', // Returns element like find, but from end
+  'at',
+  'pop',
+  'shift',
+]);
 
 // Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
 // Don't infer array type from these alone without additional evidence
 const ambiguousArrayMethodsSet = new Set(['push', 'pop']);
+
+// Methods that return primitives (boolean, number) - their return values are not mockable
+// These should have their .functionCallReturnValue paths removed from the schema
+const primitiveReturningMethodsSet = new Set([
+  'some', // Returns boolean
+  'every', // Returns boolean
+  'includes', // Returns boolean
+  'indexOf', // Returns number (index)
+  'lastIndexOf', // Returns number (index from end)
+  'findIndex', // Returns number (index)
+  'findLastIndex', // Returns number (index from end)
+]);
+
 export const transformingArrayMethodsSet = new Set([
   'map',
   'reduce',
@@ -42,6 +61,12 @@ export const transformingArrayMethodsSet = new Set([
   'concat',
   'join',
   'some',
+  'every', // Returns boolean
+  'findIndex', // Returns number (index)
+  'findLastIndex', // Returns number (index from end)
+  'indexOf', // Returns number (index)
+  'lastIndexOf', // Returns number (index from end)
+  'includes', // Returns boolean
 ]);
 
 export const arrayMethodsSet = new Set([
@@ -103,12 +128,14 @@ const signatureRegExp = new RegExp(`^${signatureKeyWord}\\[\\d+\\]$`);
 
 // --- Caching splitOutsideParentheses ---
 // Instead of splitting the same string repeatedly, we cache the result.
+// IMPORTANT: Do NOT strip ::cyDuplicateKey:: markers - they are critical for
+// distinguishing variable reassignments (e.g., fetcher vs fetcher::cyDuplicateKey1::).
+// Stripping them causes schema contamination where fields from one type-parameterized
+// call get incorrectly attributed to another.
 const splitCache = new Map<string, string[]>();
 function cachedSplit(str: string): string[] {
   if (splitCache.has(str)) return splitCache.get(str)!;
-  const parts = splitOutsideParentheses(str).map((p) =>
-    p.replace(/::cyDuplicateKey\d+::/g, ''),
-  );
+  const parts = splitOutsideParentheses(str);
   splitCache.set(str, parts);
   return parts;
 }
@@ -225,6 +252,54 @@ export function clearAttributesFromMapping(
   clearAttributes(mapping, knownBasePaths);
 }
 
+/**
+ * Remove duplicate function calls (same function with different arguments) that have no return data.
+ * Example: setSelectedFilter(arg1) and setSelectedFilter(arg2) where neither has functionCallReturnValue
+ * These create invalid mock code when spread together (orphan spread statements).
+ *
+ * This is a targeted fix that can be called independently without the full clearAttributes logic,
+ * which was disabled in constructMockCode.ts due to side effects on array method calls.
+ */
+export function removeDuplicateFunctionCalls(
+  mapping: Record<string, string>,
+): void {
+  const allKeys = Object.keys(mapping);
+  const functionCallGroups: { [baseName: string]: string[] } = {};
+
+  for (const key of allKeys) {
+    // Only process paths that:
+    // 1. Are marked as 'function'
+    // 2. END with a function call (parentheses) - not just contain one somewhere
+    // 3. Are on an object path (contain '.')
+    if (mapping[key] === 'function' && key.endsWith(')') && key.includes('.')) {
+      // Extract base path + function name (without the arguments)
+      // e.g., "returnValue.setSelectedFilter(arg)" -> "returnValue.setSelectedFilter"
+      const baseName = key.replace(/\([^)]*\)$/, '');
+      functionCallGroups[baseName] ||= [];
+      functionCallGroups[baseName].push(key);
+    }
+  }
+
+  // For groups with multiple calls (same function, different args), remove those without return data
+  for (const baseName in functionCallGroups) {
+    const calls = functionCallGroups[baseName];
+    if (calls.length > 1) {
+      // Multiple calls to the same function with different arguments
+      for (const callPath of calls) {
+        // Check if this call has return data
+        const hasReturnData = allKeys.some(
+          (k: string) =>
+            k.startsWith(callPath + '.functionCallReturnValue') ||
+            k.startsWith(callPath + '.signature['),
+        );
+        if (!hasReturnData) {
+          delete mapping[callPath];
+        }
+      }
+    }
+  }
+}
+
 function transformPath({
   oldPath,
   newPath,
@@ -642,13 +717,16 @@ function handleFunctionMapping(
     }
 
     // Don't add [] element for ambiguous methods without other array evidence
+    // Also don't add [] if the path was already identified as a string type
     const methodName = getMethodName(lastPart);
     const isAmbiguousMethod = ambiguousArrayMethodsSet.has(methodName);
+    const isStringType = keyMapping[previousPath] === 'string';
     if (
       !isValidFunctionCall(previousPart) &&
       arrayMethodsSet.has(methodName) &&
       !keyMapping[previousPath + '[]'] &&
-      !isAmbiguousMethod
+      !isAmbiguousMethod &&
+      !isStringType
     ) {
       keyMapping[previousPath + '[]'] = 'unknown';
     }
@@ -901,9 +979,23 @@ function clearAttributes(
     }
   }
 
+  // Remove duplicate function calls (same function with different arguments) that have no return data
+  removeDuplicateFunctionCalls(mapping);
+
   for (const key in mapping) {
     const value = mapping[key];
     if (knownTypes.has(value)) {
+      // Don't add string-typed array element paths (ending with []) to knownBasePaths.
+      // When an array element is typed as 'string' but has child paths (like data[].id),
+      // it's actually an object - the 'string' type is incorrect. The child paths
+      // describe the array element structure and should not be deleted.
+      //
+      // However, array-typed [] paths (like matrix[] where matrix is array of arrays)
+      // should still be in knownBasePaths so their method calls (filter, map, etc.)
+      // get cleaned up properly.
+      if (key.endsWith('[]') && value === 'string') {
+        continue;
+      }
       knownBasePaths.add(key);
     }
   }
@@ -918,11 +1010,20 @@ function clearAttributes(
         basePath
       )
         continue;
+      // Preserve functionCallReturnValue for non-string types, UNLESS
+      // the method is a primitive-returning method (like some, every, includes, indexOf)
+      // whose return values are not mockable
+      const methodPart = keyParts[basePathParts.length];
+      const methodName = methodPart?.split('(')[0];
+      const isPrimitiveReturning = primitiveReturningMethodsSet.has(
+        methodName ?? '',
+      );
       if (
         mapping[basePath] !== 'string' &&
         keyParts[basePathParts.length + 1]?.startsWith(
           'functionCallReturnValue',
-        )
+        ) &&
+        !isPrimitiveReturning
       )
         continue;
 

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

@@ -6,6 +6,14 @@ const STANDALONE_INDEX_RE = /^\[(\d+)\]$/;
 const isExplicitIndex = (s?: string) => !!s && INDEXED_RE.test(s);
 const isStandaloneIndex = (s?: string) => !!s && STANDALONE_INDEX_RE.test(s);
 
+// Detect .length properties that come from dynamic iteration patterns
+// These aren't useful for mock data - arrays work without explicit length,
+// and objects shouldn't have length. We filter .length that appears:
+// 1. After array notation: metadata[].length, items[][].length
+// 2. On object paths that likely come from iteration: metadata.length (when metadata has other props)
+// 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)
@@ -23,10 +31,13 @@ export default function convertDotNotation(
   const result: JsonTypeDefinition = {};
 
   for (const [rawPath, typ] of Object.entries(schema)) {
+    // Skip paths with .length after array notation from dynamic iteration
+    // e.g., metadata[].length, metadata[][].length
+    if (DYNAMIC_LENGTH_RE.test(rawPath)) continue;
+
     const parts = splitOutsideParenthesesAndArrays(rawPath);
     if (!parts || parts.length === 0) continue;
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let cursor: any = result;
 
     for (let i = 0; i < parts.length; i++) {
@@ -181,12 +192,24 @@ export default function convertDotNotation(
           if (!isSkippableLeafType(typ)) {
             cursor[key] = [typ];
           } else {
-            // structural/placeholder subtype — ensure array exists but don't clobber
-            if (!Array.isArray(cursor[key])) cursor[key] = [];
+            // structural/placeholder subtype — ensure array exists but don't clobber existing values
+            // Only create an array if nothing exists yet; preserve concrete types like 'string'
+            if (cursor[key] === undefined) cursor[key] = [];
           }
           i++; // consume '[]'
         } else {
           // Pattern like: "items", "[]", "id" -> items: [ { id: ... } ]
+          // But if cursor[key] is already a non-array object (from paths like "metadata: object"),
+          // don't overwrite it with an array - the object type should take precedence.
+          // This handles spurious "metadata[]" paths from dynamic iteration (Object.keys, for...in).
+          if (
+            cursor[key] !== undefined &&
+            typeof cursor[key] === 'object' &&
+            !Array.isArray(cursor[key])
+          ) {
+            // Skip this path - it's trying to treat an object as an array
+            break;
+          }
           if (!Array.isArray(cursor[key])) cursor[key] = [];
 
           // Look ahead to see what comes after '[]'

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

@@ -0,0 +1,98 @@
+/**
+ * Converts null values to undefined (removes them) based on schema type constraints.
+ *
+ * When the LLM generates mock data, it uses `null` to represent "no value" because
+ * JSON doesn't support `undefined`. However, TypeScript types like `string | undefined`
+ * don't accept `null`.
+ *
+ * This function traverses data and schema together:
+ * - If schema type is "T | undefined" (but NOT "T | null"), convert null → undefined (delete key)
+ * - If schema type includes "null" (e.g., "T | null" or "T | null | undefined"), preserve null
+ * - If field not in schema, preserve as-is
+ *
+ * @param data The data object with potential null values
+ * @param schema The schema describing expected types
+ * @returns The data with null→undefined conversions applied (mutates original)
+ */
+export default function convertNullToUndefinedBySchema<T>(
+  data: T,
+  schema: unknown,
+): T {
+  // Handle null/undefined data
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Only process objects
+  if (typeof data !== 'object') {
+    return data;
+  }
+
+  // Handle arrays
+  if (Array.isArray(data)) {
+    // For arrays, the schema should be an array with one element describing the item type
+    const itemSchema = Array.isArray(schema) ? schema[0] : undefined;
+    for (let i = 0; i < data.length; i++) {
+      data[i] = convertNullToUndefinedBySchema(data[i], itemSchema);
+    }
+    return data;
+  }
+
+  // Handle objects
+  const dataObj = data as Record<string, unknown>;
+  const schemaObj = schema as Record<string, unknown> | undefined;
+
+  for (const key of Object.keys(dataObj)) {
+    const value = dataObj[key];
+    const fieldSchema = schemaObj?.[key];
+
+    if (value === null) {
+      // Check if schema allows null
+      if (shouldConvertNullToUndefined(fieldSchema)) {
+        // Delete the key (converts null to undefined)
+        delete dataObj[key];
+      }
+      // If schema allows null, preserve it
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively process nested objects/arrays
+      convertNullToUndefinedBySchema(value, fieldSchema);
+    }
+  }
+
+  return data;
+}
+
+/**
+ * Determines if a null value should be converted to undefined based on schema type.
+ *
+ * @param fieldSchema The schema type string or object for the field
+ * @returns true if null should be converted to undefined, false if null should be preserved
+ */
+function shouldConvertNullToUndefined(fieldSchema: unknown): boolean {
+  // If no schema for this field, preserve null (be conservative)
+  if (fieldSchema === undefined || fieldSchema === null) {
+    return false;
+  }
+
+  // If schema is a string type definition, check if it allows null
+  if (typeof fieldSchema === 'string') {
+    // Schema types that include "null" should preserve null values
+    // e.g., "string | null", "number | null | undefined", "null"
+    const allowsNull = fieldSchema.includes('null');
+    const allowsUndefined = fieldSchema.includes('undefined');
+
+    // If type allows undefined but NOT null, convert null to undefined
+    // e.g., "string | undefined" → convert null to undefined
+    // e.g., "string | null" → preserve null
+    // e.g., "string | null | undefined" → preserve null
+    if (allowsUndefined && !allowsNull) {
+      return true;
+    }
+
+    return false;
+  }
+
+  // If schema is an object or array, it's a nested structure
+  // Don't convert the container itself, just recurse into it
+  return false;
+}

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

@@ -208,10 +208,12 @@ export default function fillInSchemaGapsAndUnknowns(
 export function fillInDirectSchemaGapsAndUnknowns({
   scopeName,
   schema,
+  mergedSchema,
   attempts = 0,
 }: {
   scopeName?: string;
   schema: Record<string, string>;
+  mergedSchema?: Record<string, string>;
   attempts?: number;
 }) {
   try {
@@ -245,7 +247,9 @@ export function fillInDirectSchemaGapsAndUnknowns({
     const guessTypeForPath = (path: string, defaultType = 'string') => {
       let knownType = checkIfKnownType(path, functionKeysMapping);
       if (!knownType) {
-        knownType = checkIfObjectOrFunction(path, schema);
+        // 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);
       }
 
       if (knownType && schema[path] !== knownType) {
@@ -303,7 +307,14 @@ export function fillInDirectSchemaGapsAndUnknowns({
           cleanOutBoundary(lastSubPathPart).match(/\[\d*\]/) &&
           !lastSubPathPart.match(/signature\[\d+\]/)
         ) {
-          if (schema[previousSubPath] !== 'array') {
+          // 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;
           }
@@ -355,9 +366,11 @@ export function fillInDirectSchemaGapsAndUnknowns({
 
           // 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';
@@ -371,10 +384,39 @@ export function fillInDirectSchemaGapsAndUnknowns({
       fillInDirectSchemaGapsAndUnknowns({
         scopeName,
         schema,
+        mergedSchema,
         attempts: ++attempts,
       });
     }
 
+    // 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 = splitOutsideParenthesesAndArrays(key);
+      if (parts[parts.length - 1] === 'length') {
+        const parentPath = joinParenthesesAndArrays(parts.slice(0, -1));
+        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(
@@ -408,17 +450,26 @@ function checkIfObjectOrFunction(path: string, schema: ScopeNode['schema']) {
   }
 }
 
-// Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
+// 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']);
+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',
-  'forEach',
   'every',
   'some',
   'find',
@@ -429,9 +480,6 @@ const STRONG_ARRAY_METHODS = new Set([
   'flatMap',
   'fill',
   'copyWithin',
-  'entries',
-  'keys',
-  'values',
   'toReversed',
   'toSorted',
   'toSpliced',
@@ -446,6 +494,8 @@ function checkIfKnownType(
   let isString: boolean | undefined;
   let hasStrongArrayEvidence = false;
   let hasOnlyAmbiguousArrayMethods = true;
+  let hasLengthAccess = false;
+  let hasArrayStringAmbiguousMethod = false;
 
   for (const functionOrAttributeName of functionAndAttributesKeysMapping[key] ??
     []) {
@@ -459,11 +509,18 @@ function checkIfKnownType(
       knownMethodCalls(functionOrAttributeName).includes('string') ||
       functionOrAttributeName === 'length';
 
-    // Check if this is strong evidence of an array
-    if (
-      STRONG_ARRAY_METHODS.has(methodName) ||
-      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 this is strong evidence of an array (unambiguous array methods)
+    if (STRONG_ARRAY_METHODS.has(methodName)) {
       hasStrongArrayEvidence = true;
     }
 
@@ -487,10 +544,24 @@ function checkIfKnownType(
     }
   }
 
+  // Strong array evidence (unambiguous methods like .map, .filter) -> definitely array
+  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) {
+    return 'array';
+  }
+
   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
-  if (isArray && (hasStrongArrayEvidence || !hasOnlyAmbiguousArrayMethods)) {
+  if (isArray && !hasOnlyAmbiguousArrayMethods) {
     return 'array';
   }
 }

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

@@ -1,11 +1,41 @@
 import { splitOutsideParenthesesAndArrays } from '../../splitOutsideParentheses';
 
+/**
+ * Find the position of the first '(' that is NOT inside angle brackets.
+ * Returns -1 if not found.
+ */
+function findFirstParenOutsideTypeParams(signature: string): number {
+  let angleDepth = 0;
+
+  for (let i = 0; i < signature.length; i++) {
+    const char = signature[i];
+
+    if (char === '<') {
+      angleDepth++;
+    } else if (char === '>') {
+      angleDepth--;
+    } else if (char === '(' && angleDepth === 0) {
+      return i;
+    }
+  }
+
+  return -1;
+}
+
 export default function getFunctionCallRoot(functionCallSignature: string) {
   const functionCallSignatureParts = splitOutsideParenthesesAndArrays(
     functionCallSignature,
   );
 
-  return functionCallSignatureParts[0]
-    .replace(/(cyScope\d+)F/, '$1')
-    .split('(')[0];
+  const firstPart = functionCallSignatureParts[0];
+
+  // Find the first '(' that's not inside type parameters (angle brackets)
+  // This handles cases like "useFetcher<{ data: UserData | null }>()"
+  // which should return "useFetcher<{ data: UserData | null }>"
+  // (preserving type params for scope node matching)
+  const parenPos = findFirstParenOutsideTypeParams(firstPart);
+
+  const result = parenPos >= 0 ? firstPart.substring(0, parenPos) : firstPart;
+
+  return result.replace(/(cyScope\d+)F/, '$1');
 }

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

@@ -0,0 +1,70 @@
+/**
+ * selectBestValue
+ *
+ * Selects the most specific type value from two candidates.
+ * Prefers more specific types over 'unknown' values.
+ *
+ * ## Context
+ *
+ * During schema building, the same path may have type information from
+ * multiple sources (e.g., from a return statement and from a function call).
+ * When merging these, we want to keep the most specific type.
+ *
+ * "Specific" means:
+ * - `'string'` is more specific than `'unknown'`
+ * - `'string'` is more specific than `'unknown|string'`
+ * - `'string|number'` is equal specificity to `'number|string'`
+ *
+ * ## Selection Rules
+ *
+ * 1. If value1 exists and is not 'unknown', use value1
+ * 2. If value2 exists and is more specific (not 'unknown'), prefer value2
+ * 3. Otherwise use the first available value, or 'unknown' as default
+ *
+ * ## Where Used
+ *
+ * - `propagateSourceAndUsageEquivalencies.equateSchema()` - Merging schemas
+ * - `getReturnValue()` - Combining return type information
+ *
+ * ## Related Modules
+ *
+ * - `ensureSchemaConsistency.ts` - Also deals with type merging
+ * - `fillInSchemaGapsAndUnknowns.ts` - Fills in missing types after schema building
+ */
+
+/**
+ * Selects the best (most specific) value between two type candidates.
+ *
+ * @param value1 - Primary value (preferred if specific)
+ * @param value2 - Secondary value (used if value1 is 'unknown')
+ * @param defaultValue - Default when both are undefined (defaults to 'unknown')
+ * @returns The most specific type value
+ *
+ * @example
+ * selectBestValue('string', 'number') // 'string' - value1 is specific
+ * selectBestValue('unknown', 'string') // 'string' - value2 is more specific
+ * selectBestValue(undefined, 'number') // 'number' - value1 undefined
+ * selectBestValue(undefined, undefined) // 'unknown' - default
+ * selectBestValue('unknown|string', 'string') // 'string' - value2 has no unknown
+ */
+export default function selectBestValue(
+  value1: string | undefined,
+  value2: string | undefined,
+  defaultValue = 'unknown',
+): string {
+  let bestValue = value1 ?? value2 ?? defaultValue;
+
+  // Prefer value2 if:
+  // - value2 exists AND
+  // - bestValue is 'unknown' and value2 is not, OR
+  // - bestValue contains 'unknown' and value2 doesn't
+  if (
+    value2 &&
+    ((bestValue === 'unknown' && value2 !== 'unknown') ||
+      (bestValue.includes('unknown') && !value2.includes('unknown')))
+  ) {
+    bestValue = value2;
+  }
+
+  return bestValue;
+}