@tsonic/frontend 0.0.14 → 0.0.16

package/dist/ir/type-system/internal/type-converter/utility-types.js

@@ -0,0 +1,879 @@
+/**
+ * Utility type expansion - Partial, Required, Readonly, Pick, Omit
+ *
+ * DETERMINISTIC IR TYPING (INV-0 compliant):
+ * These utility types are expanded using AST-based analysis only.
+ * No banned APIs (getTypeAtLocation, getTypeOfSymbolAtLocation, typeToTypeNode).
+ * Uses Binding for symbol resolution and extracts types from TypeNodes.
+ */
+import * as ts from "typescript";
+/**
+ * Set of supported mapped utility types that can be expanded
+ */
+export const EXPANDABLE_UTILITY_TYPES = new Set([
+    "Partial",
+    "Required",
+    "Readonly",
+    "Pick",
+    "Omit",
+]);
+/**
+ * Check if a type name is an expandable utility type
+ */
+export const isExpandableUtilityType = (name) => EXPANDABLE_UTILITY_TYPES.has(name);
+/**
+ * Set of supported conditional utility types that can be expanded
+ * Uses AST-based syntactic algorithms, not TS type evaluation.
+ */
+export const EXPANDABLE_CONDITIONAL_UTILITY_TYPES = new Set([
+    "NonNullable",
+    "Exclude",
+    "Extract",
+    "ReturnType",
+    "Parameters",
+    "Awaited",
+]);
+/**
+ * Check if a type name is an expandable conditional utility type
+ */
+export const isExpandableConditionalUtilityType = (name) => EXPANDABLE_CONDITIONAL_UTILITY_TYPES.has(name);
+/**
+ * Maximum recursion depth for nested conditional utility expansion.
+ * Prevents infinite recursion on cyclic aliases or pathological inputs.
+ */
+const MAX_CONDITIONAL_UTILITY_RECURSION = 16;
+/**
+ * Resolve a type alias to its underlying TypeNode (AST-based, INV-0 compliant).
+ * Follows type alias chains to get the actual type definition.
+ *
+ * @param node - The TypeNode to resolve
+ * @param binding - The Binding layer for symbol resolution
+ * @returns The resolved TypeNode, or the original if not a resolvable alias
+ */
+const resolveTypeAlias = (node, binding) => {
+    // Only type references can be aliases
+    if (!ts.isTypeReferenceNode(node))
+        return node;
+    if (!ts.isIdentifier(node.typeName))
+        return node;
+    // IMPORTANT: Do not resolve compiler-known utility types to their lib.d.ts
+    // conditional/type-alias definitions. We treat these as intrinsic and expand
+    // them ourselves (deterministically) when requested.
+    const name = node.typeName.text;
+    if (isExpandableUtilityType(name) ||
+        isExpandableConditionalUtilityType(name) ||
+        name === "Record" ||
+        name === "CLROf" ||
+        name === "out" ||
+        name === "ref" ||
+        name === "inref") {
+        return node;
+    }
+    // Use Binding to resolve the type reference
+    const declId = binding.resolveTypeReference(node);
+    if (!declId)
+        return node;
+    const declInfo = binding
+        ._getHandleRegistry()
+        .getDecl(declId);
+    if (!declInfo)
+        return node;
+    // Look for a type alias declaration
+    const decl = declInfo.declNode;
+    if (!decl || !ts.isTypeAliasDeclaration(decl))
+        return node;
+    // Recursively resolve in case of chained aliases
+    return resolveTypeAlias(decl.type, binding);
+};
+const unwrapParens = (node) => {
+    let current = node;
+    while (ts.isParenthesizedTypeNode(current)) {
+        current = current.type;
+    }
+    return current;
+};
+const flattenUnionTypeNodes = (node) => {
+    const unwrapped = unwrapParens(node);
+    if (!ts.isUnionTypeNode(unwrapped))
+        return [unwrapped];
+    const parts = [];
+    for (const t of unwrapped.types) {
+        parts.push(...flattenUnionTypeNodes(t));
+    }
+    return parts;
+};
+/**
+ * Check if a TypeNode is a type parameter reference (symbol-based, INV-0 compliant)
+ */
+const isTypeParameterNode = (node, binding) => {
+    if (!ts.isTypeReferenceNode(node))
+        return false;
+    if (!ts.isIdentifier(node.typeName))
+        return false;
+    // Use Binding to resolve the type reference
+    const declId = binding.resolveTypeReference(node);
+    if (!declId)
+        return false;
+    const declInfo = binding
+        ._getHandleRegistry()
+        .getDecl(declId);
+    if (!declInfo)
+        return false;
+    // Check if the declaration is a type parameter
+    const decl = declInfo.declNode;
+    return decl ? ts.isTypeParameterDeclaration(decl) : false;
+};
+/**
+ * Extract members from an interface or type alias declaration (AST-based).
+ * Used for utility type expansion.
+ */
+const extractMembersFromDeclaration = (decl, binding, convertType) => {
+    // Get type elements from declaration
+    const typeElements = ts.isInterfaceDeclaration(decl)
+        ? decl.members
+        : ts.isTypeAliasDeclaration(decl) && ts.isTypeLiteralNode(decl.type)
+            ? decl.type.members
+            : undefined;
+    if (!typeElements) {
+        return null;
+    }
+    // Check for index signatures - can't expand these
+    for (const member of typeElements) {
+        if (ts.isIndexSignatureDeclaration(member)) {
+            return null;
+        }
+    }
+    const members = [];
+    for (const member of typeElements) {
+        if (ts.isPropertySignature(member)) {
+            const propName = ts.isIdentifier(member.name)
+                ? member.name.text
+                : ts.isStringLiteral(member.name)
+                    ? member.name.text
+                    : undefined;
+            if (!propName || !member.type) {
+                continue; // Skip computed keys or untyped properties
+            }
+            const isOptional = !!member.questionToken;
+            const isReadonly = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.ReadonlyKeyword) ?? false;
+            members.push({
+                kind: "propertySignature",
+                name: propName,
+                type: convertType(member.type, binding),
+                isOptional,
+                isReadonly,
+            });
+        }
+        if (ts.isMethodSignature(member)) {
+            const methodName = ts.isIdentifier(member.name)
+                ? member.name.text
+                : undefined;
+            if (!methodName) {
+                continue; // Skip computed keys
+            }
+            members.push({
+                kind: "methodSignature",
+                name: methodName,
+                parameters: member.parameters.map((param, index) => ({
+                    kind: "parameter",
+                    pattern: {
+                        kind: "identifierPattern",
+                        name: ts.isIdentifier(param.name) ? param.name.text : `arg${index}`,
+                    },
+                    type: param.type ? convertType(param.type, binding) : undefined,
+                    isOptional: !!param.questionToken,
+                    isRest: !!param.dotDotDotToken,
+                    passing: "value",
+                })),
+                returnType: member.type ? convertType(member.type, binding) : undefined,
+            });
+        }
+    }
+    return members.length > 0 ? members : null;
+};
+/**
+ * Extract literal keys from a TypeNode (AST-based).
+ * Returns null if the type contains non-literal constituents or is a type parameter.
+ */
+const extractLiteralKeysFromTypeNode = (node, binding) => {
+    // Check for type parameter
+    if (isTypeParameterNode(node, binding)) {
+        return null;
+    }
+    // Handle string literal: "foo"
+    if (ts.isLiteralTypeNode(node) && ts.isStringLiteral(node.literal)) {
+        return new Set([node.literal.text]);
+    }
+    // Handle number literal: 1
+    if (ts.isLiteralTypeNode(node) && ts.isNumericLiteral(node.literal)) {
+        return new Set([node.literal.text]);
+    }
+    // Handle union: "a" | "b" | "c"
+    if (ts.isUnionTypeNode(node)) {
+        const keys = new Set();
+        for (const member of node.types) {
+            if (ts.isLiteralTypeNode(member)) {
+                if (ts.isStringLiteral(member.literal)) {
+                    keys.add(member.literal.text);
+                }
+                else if (ts.isNumericLiteral(member.literal)) {
+                    keys.add(member.literal.text);
+                }
+                else {
+                    return null; // Non-string/number literal
+                }
+            }
+            else {
+                return null; // Non-literal in union
+            }
+        }
+        return keys;
+    }
+    // String keyword - infinite set, can't expand
+    if (node.kind === ts.SyntaxKind.StringKeyword) {
+        return null;
+    }
+    // Number keyword - infinite set, can't expand
+    if (node.kind === ts.SyntaxKind.NumberKeyword) {
+        return null;
+    }
+    return null; // Not supported
+};
+/**
+ * Expand a mapped utility type to an IrObjectType.
+ *
+ * DETERMINISTIC IR TYPING (INV-0 compliant):
+ * Uses AST-based analysis only. Gets members from type declarations,
+ * not from ts.Type resolution.
+ *
+ * @param node - The TypeReferenceNode for the utility type
+ * @param typeName - The name of the utility type (Partial, Required, etc.)
+ * @param binding - The Binding layer for symbol resolution
+ * @param convertType - Function to convert nested types
+ * @returns IrObjectType with the expanded properties, or null if expansion fails
+ */
+export const expandUtilityType = (node, typeName, binding, convertType) => {
+    const debug = !!process.env.DEBUG_UTILITY;
+    if (debug)
+        console.log(`[UTILITY] Expanding ${typeName}`);
+    const typeArgs = node.typeArguments;
+    if (!typeArgs || typeArgs.length === 0) {
+        if (debug)
+            console.log(`[UTILITY] No type args`);
+        return null;
+    }
+    // Get the target type argument (first argument for all mapped utilities)
+    const targetArg = typeArgs[0];
+    if (!targetArg) {
+        if (debug)
+            console.log(`[UTILITY] No target arg`);
+        return null;
+    }
+    // Check if target is a type parameter (can't expand generics)
+    if (isTypeParameterNode(targetArg, binding)) {
+        if (debug)
+            console.log(`[UTILITY] Target is type param`);
+        return null;
+    }
+    // For Pick/Omit, check if the keys argument is a type parameter
+    if ((typeName === "Pick" || typeName === "Omit") && typeArgs.length >= 2) {
+        const keysArg = typeArgs[1];
+        if (keysArg && isTypeParameterNode(keysArg, binding)) {
+            if (debug)
+                console.log(`[UTILITY] Keys is type param`);
+            return null;
+        }
+    }
+    // Get base members - either from declaration or from recursive expansion
+    let baseMembers = null;
+    // Get the target type's declaration
+    if (!ts.isTypeReferenceNode(targetArg)) {
+        // Only support named type references (not inline object types)
+        if (debug)
+            console.log(`[UTILITY] Target not TypeRef: ${ts.SyntaxKind[targetArg.kind]}`);
+        return null;
+    }
+    const targetName = ts.isIdentifier(targetArg.typeName)
+        ? targetArg.typeName.text
+        : undefined;
+    if (!targetName) {
+        if (debug)
+            console.log(`[UTILITY] No target name`);
+        return null;
+    }
+    if (debug)
+        console.log(`[UTILITY] Target: ${targetName}`);
+    // Check if target is itself a utility type (nested utility types)
+    if (isExpandableUtilityType(targetName) && targetArg.typeArguments?.length) {
+        // Recursively expand the inner utility type first
+        const innerExpanded = expandUtilityType(targetArg, targetName, binding, convertType);
+        if (innerExpanded) {
+            if (debug)
+                console.log(`[UTILITY] Recursively expanded ${targetName}, got ${innerExpanded.members.length} members`);
+            baseMembers = innerExpanded.members;
+        }
+        else {
+            if (debug)
+                console.log(`[UTILITY] Recursive expansion of ${targetName} failed`);
+            return null;
+        }
+    }
+    else {
+        // Not a utility type, resolve from declaration using Binding
+        const declId = binding.resolveTypeReference(targetArg);
+        if (!declId) {
+            if (debug)
+                console.log(`[UTILITY] No DeclId for ${targetName}`);
+            return null;
+        }
+        const declInfo = binding
+            ._getHandleRegistry()
+            .getDecl(declId);
+        if (!declInfo?.declNode) {
+            if (debug)
+                console.log(`[UTILITY] No declaration for ${targetName}`);
+            return null;
+        }
+        const decl = declInfo.declNode;
+        if (debug)
+            console.log(`[UTILITY] Found declaration: ${ts.SyntaxKind[decl.kind]}`);
+        // Check if it's an interface or type alias
+        if (!ts.isInterfaceDeclaration(decl) && !ts.isTypeAliasDeclaration(decl)) {
+            if (debug)
+                console.log(`[UTILITY] No interface/type alias decl`);
+            return null;
+        }
+        // Extract members from declaration (AST-based)
+        baseMembers = extractMembersFromDeclaration(decl, binding, convertType);
+        if (!baseMembers) {
+            if (debug)
+                console.log(`[UTILITY] extractMembersFromDeclaration returned null`);
+            return null;
+        }
+        if (debug)
+            console.log(`[UTILITY] Extracted ${baseMembers.length} members`);
+    }
+    if (!baseMembers) {
+        return null;
+    }
+    // Handle Pick/Omit - filter members by keys
+    if (typeName === "Pick" || typeName === "Omit") {
+        const keysArg = typeArgs[1];
+        if (!keysArg) {
+            return null;
+        }
+        const keys = extractLiteralKeysFromTypeNode(keysArg, binding);
+        if (!keys) {
+            return null; // Can't extract literal keys
+        }
+        const filteredMembers = baseMembers.filter((m) => {
+            const include = typeName === "Pick" ? keys.has(m.name) : !keys.has(m.name);
+            return include;
+        });
+        return { kind: "objectType", members: filteredMembers };
+    }
+    // Apply Partial/Required/Readonly transformations
+    const transformedMembers = baseMembers.map((m) => {
+        if (m.kind === "propertySignature") {
+            const isOptional = typeName === "Partial"
+                ? true
+                : typeName === "Required"
+                    ? false
+                    : m.isOptional;
+            const isReadonly = typeName === "Readonly" ? true : m.isReadonly;
+            return {
+                ...m,
+                isOptional,
+                isReadonly,
+            };
+        }
+        return m;
+    });
+    return { kind: "objectType", members: transformedMembers };
+};
+/**
+ * Check if a TypeNode recursively contains type parameters.
+ * Uses symbol-based checks only (INV-0 compliant).
+ */
+const typeNodeContainsTypeParameter = (node, binding) => {
+    if (isTypeParameterNode(node, binding)) {
+        return true;
+    }
+    if (ts.isUnionTypeNode(node)) {
+        return node.types.some((t) => typeNodeContainsTypeParameter(t, binding));
+    }
+    if (ts.isIntersectionTypeNode(node)) {
+        return node.types.some((t) => typeNodeContainsTypeParameter(t, binding));
+    }
+    if (ts.isArrayTypeNode(node)) {
+        return typeNodeContainsTypeParameter(node.elementType, binding);
+    }
+    if (ts.isTypeReferenceNode(node) && node.typeArguments) {
+        return node.typeArguments.some((t) => typeNodeContainsTypeParameter(t, binding));
+    }
+    return false;
+};
+const flattenUnionIrType = (type) => {
+    if (type.kind === "neverType")
+        return [];
+    if (type.kind !== "unionType")
+        return [type];
+    const flat = [];
+    for (const t of type.types) {
+        flat.push(...flattenUnionIrType(t));
+    }
+    return flat;
+};
+const isProvablyAssignable = (source, target) => {
+    // Union target: assignable if assignable to any constituent
+    if (target.kind === "unionType") {
+        let sawUnknown = false;
+        for (const t of target.types) {
+            const res = isProvablyAssignable(source, t);
+            if (res === true)
+                return true;
+            if (res === null)
+                sawUnknown = true;
+        }
+        return sawUnknown ? null : false;
+    }
+    // Top types
+    if (target.kind === "anyType")
+        return true;
+    if (target.kind === "unknownType")
+        return true;
+    // Bottom
+    if (target.kind === "neverType")
+        return source.kind === "neverType";
+    if (source.kind === "neverType")
+        return true;
+    // Exact literals
+    if (source.kind === "literalType" && target.kind === "literalType") {
+        return source.value === target.value;
+    }
+    // Primitive ↔ primitive
+    if (source.kind === "primitiveType" && target.kind === "primitiveType") {
+        return source.name === target.name;
+    }
+    // Literal → primitive
+    if (source.kind === "literalType" && target.kind === "primitiveType") {
+        switch (typeof source.value) {
+            case "string":
+                return target.name === "string";
+            case "number":
+                // Numeric literal types are always assignable to `number`.
+                // Assignability to `int` is intentionally left unknown here (range-dependent).
+                if (target.name === "number")
+                    return true;
+                if (target.name === "int")
+                    return null;
+                return false;
+            case "boolean":
+                return target.name === "boolean";
+            default:
+                return null;
+        }
+    }
+    // Primitive → literal is never provable (would require narrowing)
+    if (source.kind === "primitiveType" && target.kind === "literalType") {
+        return false;
+    }
+    // Other kinds (reference types, functions, objects, etc.) require richer typing.
+    return null;
+};
+/**
+ * Expand NonNullable<T> using syntactic filtering (INV-0 compliant).
+ */
+const expandNonNullable = (typeArg, binding, convertType) => {
+    // Check for type parameter
+    if (isTypeParameterNode(typeArg, binding)) {
+        return null;
+    }
+    // Resolve type aliases to get the underlying type
+    const resolved = resolveTypeAlias(typeArg, binding);
+    // Handle special keywords
+    if (resolved.kind === ts.SyntaxKind.AnyKeyword)
+        return { kind: "anyType" };
+    if (resolved.kind === ts.SyntaxKind.UnknownKeyword)
+        return { kind: "unknownType" };
+    if (resolved.kind === ts.SyntaxKind.NeverKeyword)
+        return { kind: "neverType" };
+    // Syntactic filtering of union types
+    if (ts.isUnionTypeNode(resolved)) {
+        const filtered = resolved.types.filter((t) => {
+            // Direct null/undefined keywords
+            if (t.kind === ts.SyntaxKind.NullKeyword)
+                return false;
+            if (t.kind === ts.SyntaxKind.UndefinedKeyword)
+                return false;
+            // LiteralTypeNode wrapping null/undefined
+            if (ts.isLiteralTypeNode(t) &&
+                (t.literal.kind === ts.SyntaxKind.NullKeyword ||
+                    t.literal.kind === ts.SyntaxKind.UndefinedKeyword)) {
+                return false;
+            }
+            return true;
+        });
+        if (filtered.length === 0)
+            return { kind: "neverType" };
+        if (filtered.length === 1 && filtered[0]) {
+            return convertType(filtered[0], binding);
+        }
+        return {
+            kind: "unionType",
+            types: filtered.map((t) => convertType(t, binding)),
+        };
+    }
+    // Not a union — return as-is (null/undefined are already filtered by check above)
+    if (resolved.kind === ts.SyntaxKind.NullKeyword)
+        return { kind: "neverType" };
+    if (resolved.kind === ts.SyntaxKind.UndefinedKeyword)
+        return { kind: "neverType" };
+    return convertType(resolved, binding);
+};
+const expandConditionalUtilityTypeInternal = (node, typeName, binding, convertType, depth) => {
+    if (depth > MAX_CONDITIONAL_UTILITY_RECURSION) {
+        return null;
+    }
+    const typeArgs = node.typeArguments;
+    if (!typeArgs || typeArgs.length === 0) {
+        return null;
+    }
+    // Check for type parameters in any argument
+    for (const typeArg of typeArgs) {
+        if (typeNodeContainsTypeParameter(typeArg, binding)) {
+            return null;
+        }
+    }
+    const firstArg = typeArgs[0];
+    if (!firstArg) {
+        return null;
+    }
+    switch (typeName) {
+        case "NonNullable":
+            return expandNonNullable(firstArg, binding, convertType);
+        case "Exclude": {
+            const secondArg = typeArgs[1];
+            if (!secondArg)
+                return null;
+            return expandExcludeExtract(firstArg, secondArg, false, binding, convertType, depth);
+        }
+        case "Extract": {
+            const secondArg = typeArgs[1];
+            if (!secondArg)
+                return null;
+            return expandExcludeExtract(firstArg, secondArg, true, binding, convertType, depth);
+        }
+        case "ReturnType":
+            return expandReturnType(firstArg, binding, convertType);
+        case "Parameters":
+            return expandParameters(firstArg, binding, convertType);
+        case "Awaited":
+            return expandAwaited(firstArg, binding, convertType);
+        default:
+            return null;
+    }
+};
+/**
+ * Expand Exclude<T, U> or Extract<T, U> using syntactic filtering (INV-0 compliant).
+ */
+const expandExcludeExtract = (tArg, uArg, isExtract, binding, convertType, depth) => {
+    // Check for type parameters
+    if (typeNodeContainsTypeParameter(tArg, binding)) {
+        return null;
+    }
+    if (typeNodeContainsTypeParameter(uArg, binding)) {
+        return null;
+    }
+    if (depth > MAX_CONDITIONAL_UTILITY_RECURSION) {
+        return null;
+    }
+    const tryExpandConditionalArg = (node) => {
+        const unwrapped = unwrapParens(node);
+        if (!ts.isTypeReferenceNode(unwrapped) || !ts.isIdentifier(unwrapped.typeName)) {
+            return null;
+        }
+        const name = unwrapped.typeName.text;
+        if (!isExpandableConditionalUtilityType(name)) {
+            return null;
+        }
+        if (!unwrapped.typeArguments?.length) {
+            return null;
+        }
+        return expandConditionalUtilityTypeInternal(unwrapped, name, binding, convertType, depth + 1);
+    };
+    const convertForFiltering = (node) => {
+        const directExpanded = tryExpandConditionalArg(node);
+        if (directExpanded)
+            return directExpanded;
+        const resolved = unwrapParens(resolveTypeAlias(unwrapParens(node), binding));
+        const resolvedExpanded = tryExpandConditionalArg(resolved);
+        if (resolvedExpanded)
+            return resolvedExpanded;
+        if (ts.isUnionTypeNode(resolved)) {
+            const parts = flattenUnionTypeNodes(resolved);
+            const converted = [];
+            for (const p of parts) {
+                const inner = convertForFiltering(p);
+                if (!inner)
+                    return null;
+                converted.push(inner);
+            }
+            return { kind: "unionType", types: converted };
+        }
+        return convertType(resolved, binding);
+    };
+    const tType = convertForFiltering(tArg);
+    const uType = convertForFiltering(uArg);
+    if (!tType || !uType) {
+        return null;
+    }
+    const tMembers = flattenUnionIrType(tType);
+    const filtered = [];
+    for (const t of tMembers) {
+        const assignable = isProvablyAssignable(t, uType);
+        if (isExtract) {
+            // Conservative: keep unless we can prove NOT assignable
+            if (assignable !== false) {
+                filtered.push(t);
+            }
+        }
+        else {
+            // Conservative: exclude only when we can prove assignable
+            if (assignable !== true) {
+                filtered.push(t);
+            }
+        }
+    }
+    if (filtered.length === 0)
+        return { kind: "neverType" };
+    if (filtered.length === 1)
+        return filtered[0] ?? { kind: "neverType" };
+    return { kind: "unionType", types: filtered };
+};
+/**
+ * Expand ReturnType<F> by extracting from function type declaration (INV-0 compliant).
+ */
+const expandReturnType = (fArg, binding, convertType) => {
+    // Check for type parameter
+    if (isTypeParameterNode(fArg, binding)) {
+        return null;
+    }
+    // Distribute over unions: ReturnType<F1 | F2> = ReturnType<F1> | ReturnType<F2>
+    const unwrapped = unwrapParens(fArg);
+    if (ts.isUnionTypeNode(unwrapped)) {
+        const results = [];
+        for (const member of flattenUnionTypeNodes(unwrapped)) {
+            const result = expandReturnType(member, binding, convertType);
+            if (!result)
+                return null;
+            results.push(result);
+        }
+        const flat = results.flatMap((t) => flattenUnionIrType(t));
+        if (flat.length === 0)
+            return { kind: "neverType" };
+        if (flat.length === 1)
+            return flat[0] ?? { kind: "neverType" };
+        return { kind: "unionType", types: flat };
+    }
+    // Case 1: Direct function type node
+    if (ts.isFunctionTypeNode(unwrapped)) {
+        return unwrapped.type
+            ? convertType(unwrapped.type, binding)
+            : { kind: "voidType" };
+    }
+    // Case 2: Type reference to function type alias
+    if (ts.isTypeReferenceNode(unwrapped) && ts.isIdentifier(unwrapped.typeName)) {
+        const declId = binding.resolveTypeReference(unwrapped);
+        if (declId) {
+            const declInfo = binding
+                ._getHandleRegistry()
+                .getDecl(declId);
+            const decl = declInfo?.declNode;
+            if (decl &&
+                ts.isTypeAliasDeclaration(decl) &&
+                ts.isFunctionTypeNode(decl.type)) {
+                return decl.type.type
+                    ? convertType(decl.type.type, binding)
+                    : { kind: "voidType" };
+            }
+        }
+    }
+    // Case 3: typeof function value (ReturnType<typeof fn>)
+    //
+    // INV-0 COMPLIANT: Resolve the identifier to a declaration via Binding and
+    // read the syntactic return type annotation (no ts.Type queries).
+    if (ts.isTypeQueryNode(unwrapped) && ts.isIdentifier(unwrapped.exprName)) {
+        const declId = binding.resolveIdentifier(unwrapped.exprName);
+        if (declId) {
+            const declInfo = binding
+                ._getHandleRegistry()
+                .getDecl(declId);
+            const decl = declInfo?.declNode;
+            if (decl &&
+                (ts.isFunctionDeclaration(decl) || ts.isMethodDeclaration(decl))) {
+                return decl.type ? convertType(decl.type, binding) : null;
+            }
+            if (decl && ts.isVariableDeclaration(decl) && decl.type) {
+                return expandReturnType(decl.type, binding, convertType);
+            }
+        }
+    }
+    return null; // Can't extract return type
+};
+/**
+ * Expand Parameters<F> by extracting from function type declaration (INV-0 compliant).
+ */
+const expandParameters = (fArg, binding, convertType) => {
+    // Check for type parameter
+    if (isTypeParameterNode(fArg, binding)) {
+        return null;
+    }
+    let functionType;
+    // Case 1: Direct function type node
+    if (ts.isFunctionTypeNode(fArg)) {
+        functionType = fArg;
+    }
+    // Case 2: Type reference to function type alias
+    if (!functionType &&
+        ts.isTypeReferenceNode(fArg) &&
+        ts.isIdentifier(fArg.typeName)) {
+        const declId = binding.resolveTypeReference(fArg);
+        if (declId) {
+            const declInfo = binding
+                ._getHandleRegistry()
+                .getDecl(declId);
+            const decl = declInfo?.declNode;
+            if (decl &&
+                ts.isTypeAliasDeclaration(decl) &&
+                ts.isFunctionTypeNode(decl.type)) {
+                functionType = decl.type;
+            }
+        }
+    }
+    // Case 3: typeof function value (Parameters<typeof fn>)
+    //
+    // INV-0 COMPLIANT: Resolve the identifier to a declaration via Binding and
+    // read syntactic parameter type annotations (no ts.Type queries).
+    if (!functionType && ts.isTypeQueryNode(fArg) && ts.isIdentifier(fArg.exprName)) {
+        const declId = binding.resolveIdentifier(fArg.exprName);
+        if (declId) {
+            const declInfo = binding
+                ._getHandleRegistry()
+                .getDecl(declId);
+            const decl = declInfo?.declNode;
+            if (decl && (ts.isFunctionDeclaration(decl) || ts.isMethodDeclaration(decl))) {
+                const paramTypes = decl.parameters.map((param) => param.type ? convertType(param.type, binding) : { kind: "anyType" });
+                return { kind: "tupleType", elementTypes: paramTypes };
+            }
+            if (decl && ts.isVariableDeclaration(decl) && decl.type) {
+                return expandParameters(decl.type, binding, convertType);
+            }
+        }
+    }
+    if (!functionType) {
+        return null; // Can't extract parameters
+    }
+    // Build tuple type from parameters
+    const paramTypes = functionType.parameters.map((param) => param.type ? convertType(param.type, binding) : { kind: "anyType" });
+    return { kind: "tupleType", elementTypes: paramTypes };
+};
+/**
+ * Expand Awaited<T> by extracting from Promise type parameter (INV-0 compliant).
+ */
+const expandAwaited = (tArg, binding, convertType) => {
+    // Check for type parameter
+    if (isTypeParameterNode(tArg, binding)) {
+        return null;
+    }
+    // Handle Promise<T> or PromiseLike<T>
+    if (ts.isTypeReferenceNode(tArg) && ts.isIdentifier(tArg.typeName)) {
+        const name = tArg.typeName.text;
+        if ((name === "Promise" || name === "PromiseLike") && tArg.typeArguments) {
+            const innerArg = tArg.typeArguments[0];
+            if (innerArg) {
+                // Recursively unwrap nested promises
+                return (expandAwaited(innerArg, binding, convertType) ??
+                    convertType(innerArg, binding));
+            }
+        }
+    }
+    // Not a Promise type - return as-is
+    return convertType(tArg, binding);
+};
+/**
+ * Expand a conditional utility type (NonNullable, Exclude, Extract) to IR.
+ *
+ * DETERMINISTIC IR TYPING (INV-0 compliant):
+ * Uses AST-based syntactic algorithms only. No getTypeAtLocation or typeToTypeNode.
+ *
+ * @param node - The TypeReferenceNode for the utility type
+ * @param typeName - The name of the utility type (NonNullable, Exclude, Extract, etc.)
+ * @param binding - The Binding layer for symbol resolution
+ * @param convertType - Function to convert nested types
+ * @returns IR type with the expanded result, or null if expansion fails
+ */
+export const expandConditionalUtilityType = (node, typeName, binding, convertType) => {
+    return expandConditionalUtilityTypeInternal(node, typeName, binding, convertType, 0);
+};
+/**
+ * Expand Record<K, T> to IrObjectType when K is a finite set of literal keys.
+ *
+ * DETERMINISTIC IR TYPING (INV-0 compliant):
+ * Uses AST-based analysis only. Extracts literal keys from TypeNode,
+ * not from ts.Type.
+ *
+ * Gating conditions:
+ * - Returns null if K contains type parameters (generic context)
+ * - Returns null if K is string or number (should remain IrDictionaryType)
+ * - Returns null if K contains non-literal types
+ *
+ * Examples:
+ * - Record<"a" | "b", number> → IrObjectType with props {a: number, b: number}
+ * - Record<1 | 2, string> → IrObjectType with props {"1": string, "2": string}
+ * - Record<string, number> → null (use IrDictionaryType)
+ * - Record<K, T> → null (type parameter)
+ *
+ * @param node - The TypeReferenceNode for Record<K, T>
+ * @param binding - The Binding layer for symbol resolution
+ * @param convertType - Function to convert nested types
+ * @returns IrObjectType with the expanded properties, or null if should use dictionary
+ */
+export const expandRecordType = (node, binding, convertType) => {
+    const typeArgs = node.typeArguments;
+    if (!typeArgs || typeArgs.length !== 2) {
+        return null;
+    }
+    const keyTypeNode = typeArgs[0];
+    const valueTypeNode = typeArgs[1];
+    if (!keyTypeNode || !valueTypeNode) {
+        return null;
+    }
+    // Check for type parameters in key (AST-based)
+    if (typeNodeContainsTypeParameter(keyTypeNode, binding)) {
+        return null;
+    }
+    // Check for type parameters in value (AST-based)
+    if (typeNodeContainsTypeParameter(valueTypeNode, binding)) {
+        return null;
+    }
+    // Try to extract finite literal keys (AST-based)
+    const literalKeys = extractLiteralKeysFromTypeNode(keyTypeNode, binding);
+    if (literalKeys === null || literalKeys.size === 0) {
+        // Not a finite set of literals - use IrDictionaryType
+        return null;
+    }
+    // Convert the value type
+    const irValueType = convertType(valueTypeNode, binding);
+    // Build IrObjectType with a property for each key
+    // Prefix numeric keys with '_' to make them valid C# identifiers
+    const members = Array.from(literalKeys).map((key) => ({
+        kind: "propertySignature",
+        name: /^\d/.test(key) ? `_${key}` : key,
+        type: irValueType,
+        isOptional: false,
+        isReadonly: false,
+    }));
+    return { kind: "objectType", members };
+};
+//# sourceMappingURL=utility-types.js.map