@typed/virtual-modules 1.0.0-beta.1

package/dist/TypeInfoApi.js

@@ -0,0 +1,855 @@
+import { relative } from "node:path";
+import { getAliasedSymbol as resolveAliasedSymbol, getBaseTypes as getBaseTypesInternal, getIndexInfosOfType, getSymbolExports, getTypeReferenceTarget, getTypeSymbol, FALLBACK_OBJECT_FLAGS_MAPPED, } from "./internal/tsInternal.js";
+import { dedupeSorted, pathIsUnderBase, resolvePathUnderBase, resolveRelativePath, toPosixPath, } from "./internal/path.js";
+import { validatePathSegment, validateRelativeGlobs } from "./internal/validation.js";
+const TYPE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".d.ts"];
+const DEFAULT_MAX_DEPTH = 6;
+const compareByName = (a, b) => a.name.localeCompare(b.name);
+const toOptionalFlag = (symbol, tsMod) => (symbol.flags & tsMod.SymbolFlags.Optional) !== 0;
+const hasReadonlyModifier = (declaration, tsMod) => {
+    if (!declaration || !tsMod.canHaveModifiers(declaration)) {
+        return false;
+    }
+    const modifiers = tsMod.getModifiers(declaration);
+    return modifiers?.some((modifier) => modifier.kind === tsMod.SyntaxKind.ReadonlyKeyword) ?? false;
+};
+const asLiteral = (type, checker, tsMod) => {
+    const text = checker.typeToString(type);
+    if ((type.flags & tsMod.TypeFlags.StringLiteral) !== 0 ||
+        (type.flags & tsMod.TypeFlags.NumberLiteral) !== 0 ||
+        (type.flags & tsMod.TypeFlags.BooleanLiteral) !== 0 ||
+        (type.flags & tsMod.TypeFlags.BigIntLiteral) !== 0) {
+        return { kind: "literal", text };
+    }
+    return undefined;
+};
+const serializeFunctionSignature = (signature, checker, tsMod, depth, maxDepth, visited, onInternalError, registry) => {
+    const parameters = signature.getParameters().map((parameter) => {
+        const declaration = parameter.valueDeclaration ?? parameter.declarations?.[0];
+        const parameterType = declaration
+            ? checker.getTypeOfSymbolAtLocation(parameter, declaration)
+            : checker.getDeclaredTypeOfSymbol(parameter);
+        return {
+            name: parameter.getName(),
+            optional: toOptionalFlag(parameter, tsMod),
+            type: serializeTypeNode(parameterType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        };
+    });
+    const returnType = serializeTypeNode(checker.getReturnTypeOfSignature(signature), checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry);
+    return {
+        parameters: parameters.sort(compareByName),
+        returnType,
+    };
+};
+const serializeObjectProperties = (type, checker, tsMod, depth, maxDepth, visited, onInternalError, registry) => {
+    const properties = checker.getPropertiesOfType(type);
+    const snapshots = properties.map((property) => {
+        const declaration = property.valueDeclaration ?? property.declarations?.[0];
+        const propertyType = declaration
+            ? checker.getTypeOfSymbolAtLocation(property, declaration)
+            : checker.getDeclaredTypeOfSymbol(property);
+        return {
+            name: property.getName(),
+            optional: toOptionalFlag(property, tsMod),
+            readonly: hasReadonlyModifier(declaration, tsMod),
+            type: serializeTypeNode(propertyType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        };
+    });
+    return snapshots.sort(compareByName);
+};
+const serializeIndexSignature = (type, checker, tsMod, depth, maxDepth, visited, onInternalError, registry) => {
+    const infos = getIndexInfosOfType(type, checker);
+    if (!infos || infos.length === 0)
+        return undefined;
+    const first = infos[0];
+    if (!first)
+        return undefined;
+    return {
+        keyType: serializeTypeNode(first.keyType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        valueType: serializeTypeNode(first.type, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        readonly: first.isReadonly ?? false,
+    };
+};
+const primitiveTypeNode = (type, checker, tsMod) => {
+    const text = checker.typeToString(type);
+    if ((type.flags & tsMod.TypeFlags.Any) !== 0) {
+        return { kind: "any", text };
+    }
+    if ((type.flags & tsMod.TypeFlags.Unknown) !== 0) {
+        return { kind: "unknown", text };
+    }
+    if ((type.flags & tsMod.TypeFlags.Never) !== 0) {
+        return { kind: "never", text };
+    }
+    if ((type.flags & tsMod.TypeFlags.StringLike) !== 0 ||
+        (type.flags & tsMod.TypeFlags.NumberLike) !== 0 ||
+        (type.flags & tsMod.TypeFlags.BooleanLike) !== 0 ||
+        (type.flags & tsMod.TypeFlags.BigIntLike) !== 0 ||
+        (type.flags & tsMod.TypeFlags.ESSymbolLike) !== 0 ||
+        (type.flags & tsMod.TypeFlags.Null) !== 0 ||
+        (type.flags & tsMod.TypeFlags.Undefined) !== 0 ||
+        (type.flags & tsMod.TypeFlags.Void) !== 0) {
+        return { kind: "primitive", text };
+    }
+    return undefined;
+};
+const UNKNOWN_NODE = { kind: "unknown", text: "unknown" };
+const serializeTypeNode = (type, checker, tsMod, depth, maxDepth, visited, onInternalError, registry) => {
+    const text = checker.typeToString(type);
+    const reg = (node) => {
+        registry?.set(node, type);
+        return node;
+    };
+    const typeId = `${type.id ?? "anon"}:${text}`;
+    if (depth > maxDepth || visited.has(typeId)) {
+        return reg({ kind: "reference", text });
+    }
+    visited.add(typeId);
+    const literal = asLiteral(type, checker, tsMod);
+    if (literal) {
+        return reg(literal);
+    }
+    if (type.isUnion()) {
+        const union = {
+            kind: "union",
+            text,
+            elements: type.types.map((value) => serializeTypeNode(value, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+        };
+        return reg(union);
+    }
+    if (type.isIntersection()) {
+        const intersection = {
+            kind: "intersection",
+            text,
+            elements: type.types.map((value) => serializeTypeNode(value, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+        };
+        return reg(intersection);
+    }
+    const primitive = primitiveTypeNode(type, checker, tsMod);
+    if (primitive) {
+        return reg(primitive);
+    }
+    if ((type.flags & tsMod.TypeFlags.Enum) !== 0) {
+        const members = [];
+        try {
+            const props = checker.getPropertiesOfType(type);
+            for (const sym of props) {
+                const name = sym.name;
+                let value;
+                const decl = sym.valueDeclaration;
+                if (decl && tsMod.isEnumMember?.(decl) && decl.initializer) {
+                    const init = decl.initializer;
+                    if (tsMod.isNumericLiteral?.(init)) {
+                        value = parseInt(init.text, 10);
+                    }
+                    else if (tsMod.isStringLiteral?.(init) || tsMod.isNoSubstitutionTemplateLiteral?.(init)) {
+                        value = init.text;
+                    }
+                    else {
+                        const cv = checker.getConstantValue?.(init);
+                        if (cv !== undefined)
+                            value = cv;
+                    }
+                }
+                members.push(value !== undefined ? { name, value } : { name });
+            }
+        }
+        catch (err) {
+            onInternalError?.(err, "enum-members");
+        }
+        const enumNode = {
+            kind: "enum",
+            text,
+            members: members.length > 0 ? members : undefined,
+        };
+        return reg(enumNode);
+    }
+    if ((type.flags & tsMod.TypeFlags.Conditional) !== 0) {
+        const ct = type;
+        const trueType = ct.resolvedTrueType ??
+            (ct.root?.node?.trueType
+                ? checker.getTypeFromTypeNode?.(ct.root.node.trueType)
+                : undefined);
+        const falseType = ct.resolvedFalseType ??
+            (ct.root?.node?.falseType
+                ? checker.getTypeFromTypeNode?.(ct.root.node.falseType)
+                : undefined);
+        const conditional = {
+            kind: "conditional",
+            text,
+            checkType: serializeTypeNode(ct.checkType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+            extendsType: serializeTypeNode(ct.extendsType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+            trueType: trueType
+                ? serializeTypeNode(trueType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)
+                : UNKNOWN_NODE,
+            falseType: falseType
+                ? serializeTypeNode(falseType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)
+                : UNKNOWN_NODE,
+        };
+        return reg(conditional);
+    }
+    if ((type.flags & tsMod.TypeFlags.IndexedAccess) !== 0) {
+        const iat = type;
+        const indexed = {
+            kind: "indexedAccess",
+            text,
+            objectType: serializeTypeNode(iat.objectType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+            indexType: serializeTypeNode(iat.indexType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        };
+        return reg(indexed);
+    }
+    if ((type.flags & tsMod.TypeFlags.TemplateLiteral) !== 0) {
+        const tlt = type;
+        const texts = tlt.texts ?? [];
+        const types = tlt.types ?? [];
+        const template = {
+            kind: "templateLiteral",
+            text,
+            texts,
+            types: types.map((t) => serializeTypeNode(t, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+        };
+        return reg(template);
+    }
+    const objType = type;
+    const mappedFlag = tsMod.ObjectFlags?.Mapped ?? FALLBACK_OBJECT_FLAGS_MAPPED;
+    if (objType.objectFlags !== undefined && (objType.objectFlags & mappedFlag) !== 0) {
+        const mt = type;
+        const constraintType = mt.constraint ?? mt.typeParameter?.constraint;
+        const mappedType = mt.templateType ?? mt.mappedType;
+        const mapped = {
+            kind: "mapped",
+            text,
+            constraintType: constraintType
+                ? serializeTypeNode(constraintType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)
+                : UNKNOWN_NODE,
+            mappedType: mappedType
+                ? serializeTypeNode(mappedType, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)
+                : UNKNOWN_NODE,
+        };
+        return reg(mapped);
+    }
+    if ((type.flags & tsMod.TypeFlags.Index) !== 0) {
+        const idxType = type;
+        const typeOperator = {
+            kind: "typeOperator",
+            text,
+            operator: "keyof",
+            type: serializeTypeNode(idxType.type, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry),
+        };
+        return reg(typeOperator);
+    }
+    if (checker.isTupleType(type)) {
+        const typeArguments = checker.getTypeArguments(type);
+        const tuple = {
+            kind: "tuple",
+            text,
+            elements: typeArguments.map((value) => serializeTypeNode(value, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+        };
+        return reg(tuple);
+    }
+    if (checker.isArrayType(type)) {
+        const typeArguments = checker.getTypeArguments(type);
+        const element = typeArguments[0];
+        const array = {
+            kind: "array",
+            text,
+            elements: element
+                ? [serializeTypeNode(element, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)]
+                : [UNKNOWN_NODE],
+        };
+        return reg(array);
+    }
+    const referenceArguments = checker.getTypeArguments(type);
+    if (referenceArguments.length > 0) {
+        const ref = {
+            kind: "reference",
+            text,
+            typeArguments: referenceArguments.map((value) => serializeTypeNode(value, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+        };
+        return reg(ref);
+    }
+    const constructSignatures = checker.getSignaturesOfType(type, tsMod.SignatureKind.Construct);
+    if (constructSignatures.length > 0) {
+        const sig = serializeFunctionSignature(constructSignatures[0], checker, tsMod, depth, maxDepth, visited, onInternalError, registry);
+        const ctor = {
+            kind: "constructor",
+            text,
+            parameters: sig.parameters,
+            returnType: sig.returnType,
+        };
+        return reg(ctor);
+    }
+    const callSignatures = checker.getSignaturesOfType(type, tsMod.SignatureKind.Call);
+    if (callSignatures.length > 0) {
+        if (callSignatures.length > 1) {
+            const signatures = callSignatures.map((s) => {
+                const serialized = serializeFunctionSignature(s, checker, tsMod, depth, maxDepth, visited, onInternalError, registry);
+                return { parameters: serialized.parameters, returnType: serialized.returnType };
+            });
+            const overload = { kind: "overloadSet", text, signatures };
+            return reg(overload);
+        }
+        const signature = serializeFunctionSignature(callSignatures[0], checker, tsMod, depth, maxDepth, visited, onInternalError, registry);
+        const fn = {
+            kind: "function",
+            text,
+            parameters: signature.parameters,
+            returnType: signature.returnType,
+        };
+        return reg(fn);
+    }
+    const indexSig = serializeIndexSignature(type, checker, tsMod, depth, maxDepth, visited, onInternalError, registry);
+    const object = {
+        kind: "object",
+        text,
+        properties: serializeObjectProperties(type, checker, tsMod, depth, maxDepth, visited, onInternalError, registry),
+        ...(indexSig !== undefined && { indexSignature: indexSig }),
+    };
+    return reg(object);
+};
+/**
+ * Serialize a TypeScript type to TypeNode. For testing serializer branches (typeOperator, enum, etc).
+ * @internal
+ */
+export function serializeTypeForTest(type, checker, tsMod, maxDepth = 6) {
+    return serializeTypeNode(type, checker, tsMod, 0, maxDepth, new Set());
+}
+/**
+ * Generate bootstrap file content that imports all modules from typeTargetSpecs.
+ * Include this file in the program's rootNames so resolveTypeTargetsFromSpecs can
+ * find types without requiring user source to import them.
+ *
+ * @example
+ * ```ts
+ * const bootstrapContent = createTypeTargetBootstrapContent(HTTPAPI_TYPE_TARGET_SPECS);
+ * const bootstrapPath = join(tmpDir, "__typeTargetBootstrap.ts");
+ * writeFileSync(bootstrapPath, bootstrapContent);
+ * const program = ts.createProgram([...rootFiles, bootstrapPath], options, host);
+ * ```
+ */
+export function createTypeTargetBootstrapContent(specs) {
+    const seen = new Set();
+    const lines = [
+        "/**",
+        " * Auto-generated bootstrap for type target resolution.",
+        " * Imports canonical modules so resolveTypeTargetsFromSpecs can find types.",
+        " * Include in program rootNames when using typeTargetSpecs without user imports.",
+        " */",
+    ];
+    for (const spec of specs) {
+        if (seen.has(spec.module))
+            continue;
+        seen.add(spec.module);
+        const id = spec.module.replace(/\W+/g, "_").replace(/_+/g, "_") || "m";
+        lines.push(`import * as _${id} from "${spec.module}";`);
+        lines.push(`void _${id};`);
+    }
+    lines.push("export {};");
+    return lines.join("\n");
+}
+/**
+ * Resolve type targets from program imports using the given specs.
+ * Scans source files for imports from the specified modules and extracts types.
+ * Requires the program to include files that import from these modules (e.g.
+ * use createTypeTargetBootstrapContent and add to rootNames).
+ */
+export function resolveTypeTargetsFromSpecs(program, tsMod, specs) {
+    const checker = program.getTypeChecker();
+    const found = new Map();
+    const getTypeFromSymbol = (symbol) => {
+        const aliased = resolveAliasedSymbol(symbol, checker, tsMod);
+        const decls = aliased.declarations ?? (aliased.valueDeclaration ? [aliased.valueDeclaration] : []);
+        const typeDecl = decls.find((d) => tsMod.isTypeAliasDeclaration(d) ||
+            tsMod.isInterfaceDeclaration(d) ||
+            tsMod.isTypeParameterDeclaration(d));
+        const decl = typeDecl ?? decls[0];
+        const useDeclaredType = decl &&
+            (tsMod.isTypeAliasDeclaration(decl) ||
+                tsMod.isInterfaceDeclaration(decl) ||
+                tsMod.isTypeParameterDeclaration(decl));
+        const type = useDeclaredType
+            ? checker.getDeclaredTypeOfSymbol(aliased)
+            : decl
+                ? checker.getTypeOfSymbolAtLocation(aliased, decl)
+                : checker.getDeclaredTypeOfSymbol(aliased);
+        if (!type || (type.flags & tsMod.TypeFlags.Any) !== 0)
+            return undefined;
+        return type;
+    };
+    const getTypeFromSpec = (symbol, spec) => {
+        const primaryType = getTypeFromSymbol(symbol);
+        if (!primaryType || !spec.typeMember)
+            return primaryType;
+        const aliased = resolveAliasedSymbol(symbol, checker, tsMod);
+        const exports = getSymbolExports(aliased);
+        if (!exports)
+            return primaryType;
+        const memberSymbol = Array.from(exports.values()).find((s) => s.getName() === spec.typeMember);
+        if (!memberSymbol)
+            return primaryType;
+        const memberType = checker.getDeclaredTypeOfSymbol(memberSymbol);
+        if (!memberType || (memberType.flags & tsMod.TypeFlags.Any) !== 0)
+            return primaryType;
+        return memberType;
+    };
+    const addFromModuleSymbol = (moduleSymbol, moduleSpec) => {
+        if (!moduleSymbol)
+            return;
+        const exportsByName = new Map(checker.getExportsOfModule(moduleSymbol).map((moduleExport) => [
+            moduleExport.getName(),
+            moduleExport,
+        ]));
+        for (const spec of specs) {
+            if (spec.module !== moduleSpec || found.has(spec.id))
+                continue;
+            const moduleExport = exportsByName.get(spec.exportName);
+            if (!moduleExport)
+                continue;
+            const type = getTypeFromSpec(moduleExport, spec);
+            if (type)
+                found.set(spec.id, type);
+        }
+    };
+    for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile)
+            continue;
+        tsMod.forEachChild(sourceFile, (node) => {
+            if (!tsMod.isImportDeclaration(node))
+                return;
+            const moduleSpecifier = node.moduleSpecifier;
+            if (!tsMod.isStringLiteral(moduleSpecifier))
+                return;
+            const moduleSpec = moduleSpecifier.text;
+            const binding = node.importClause;
+            if (!binding)
+                return;
+            const moduleSymbol = checker.getSymbolAtLocation(moduleSpecifier);
+            const addNamed = (name) => {
+                const exportName = (name.propertyName ?? name.name).getText(sourceFile);
+                const spec = specs.find((s) => s.module === moduleSpec && s.exportName === exportName);
+                if (!spec || found.has(spec.id))
+                    return;
+                const symbol = checker.getSymbolAtLocation(name.name);
+                if (!symbol)
+                    return;
+                const type = getTypeFromSpec(symbol, spec);
+                if (type)
+                    found.set(spec.id, type);
+            };
+            if (binding.namedBindings) {
+                if (tsMod.isNamedImports(binding.namedBindings)) {
+                    for (const elem of binding.namedBindings.elements) {
+                        addNamed(elem);
+                    }
+                }
+                else if (tsMod.isNamespaceImport(binding.namedBindings)) {
+                    const nsName = binding.namedBindings.name;
+                    const symbol = checker.getSymbolAtLocation(nsName);
+                    const nsType = symbol ? checker.getTypeOfSymbolAtLocation(symbol, nsName) : undefined;
+                    for (const spec of specs) {
+                        if (spec.module !== moduleSpec || found.has(spec.id))
+                            continue;
+                        const prop = nsType?.getProperty?.(spec.exportName);
+                        if (!prop)
+                            continue;
+                        const type = getTypeFromSpec(prop, spec);
+                        if (type)
+                            found.set(spec.id, type);
+                    }
+                    addFromModuleSymbol(moduleSymbol, moduleSpec);
+                }
+            }
+            else if (binding.name) {
+                const symbol = checker.getSymbolAtLocation(binding.name);
+                const nsType = symbol ? checker.getTypeOfSymbolAtLocation(symbol, binding.name) : undefined;
+                for (const spec of specs) {
+                    if (spec.module !== moduleSpec || found.has(spec.id))
+                        continue;
+                    const prop = nsType?.getProperty?.(spec.exportName);
+                    if (!prop)
+                        continue;
+                    const type = getTypeFromSpec(prop, spec);
+                    if (type)
+                        found.set(spec.id, type);
+                }
+                addFromModuleSymbol(moduleSymbol, moduleSpec);
+            }
+        });
+    }
+    return specs.filter((s) => found.has(s.id)).map((s) => ({ id: s.id, type: found.get(s.id) }));
+}
+/**
+ * Resolve an export symbol to the symbol it aliases when present (re-exports and import-then-export),
+ * so we derive the type from the target file for cross-file type resolution.
+ */
+const resolveExportSymbol = (symbol, checker, tsMod) => resolveAliasedSymbol(symbol, checker, tsMod);
+/** Get the base GenericType from a generic instantiation (TypeReference). */
+const getGenericBase = (type, checker) => getTypeReferenceTarget(type, checker);
+/** Get the symbol representing the "root" type for comparison (handles GenericType and TypeReference). */
+const getComparisonSymbol = (type, checker) => {
+    const base = getGenericBase(type, checker);
+    if (base?.symbol)
+        return base.symbol;
+    return getTypeSymbol(type);
+};
+/**
+ * Assignability and serialization may use internal TS APIs or heuristics. When those
+ * paths throw, errors are caught and behavior degrades (e.g. "not assignable" or a
+ * safe fallback node); no errors are thrown to the caller. Use session option
+ * onInternalError for observability when provided.
+ */
+/**
+ * Check assignability. In strict mode, uses only checker.isTypeAssignableTo.
+ * In compatibility mode, adds fallbacks for generic instantiations and inheritance
+ * when types come from different files. Union sources require ALL constituents to
+ * be assignable (sound semantics).
+ */
+const isAssignableTo = (source, target, checker, tsMod, mode) => {
+    if (checker.isTypeAssignableTo(source, target))
+        return true;
+    if (mode === "strict")
+        return false;
+    const tgtBase = getGenericBase(target, checker);
+    const tgtSymbol = tgtBase?.symbol ?? getTypeSymbol(target);
+    const matchSymbol = (sym) => sym && tgtSymbol && sym === tgtSymbol;
+    if (source.isUnion()) {
+        const constituents = source.types;
+        if (!constituents.every((t) => isAssignableTo(t, target, checker, tsMod, mode)))
+            return false;
+        return true;
+    }
+    const srcBase = getGenericBase(source, checker);
+    if (srcBase?.symbol && matchSymbol(srcBase.symbol))
+        return true;
+    const tgtTarget = getTypeReferenceTarget(target, checker);
+    if (srcBase?.symbol && tgtTarget?.symbol && srcBase.symbol === tgtTarget.symbol)
+        return true;
+    const srcSymbol = getComparisonSymbol(source, checker);
+    if (matchSymbol(srcSymbol))
+        return true;
+    if ((source.flags & tsMod.TypeFlags.Object) !== 0) {
+        const srcSym = source.symbol;
+        const isClassOrInterface = srcSym &&
+            (srcSym.flags & (tsMod.SymbolFlags.Class | tsMod.SymbolFlags.Interface)) !== 0;
+        if (isClassOrInterface) {
+            const bases = getBaseTypesInternal(source, checker);
+            const hasMatchingBase = (bases ?? []).some((b) => {
+                const bSym = getTypeSymbol(b);
+                return bSym && matchSymbol(bSym);
+            });
+            if (hasMatchingBase)
+                return true;
+        }
+    }
+    const tgtName = tgtSymbol?.getName();
+    if (tgtName && srcBase?.symbol?.getName() === tgtName)
+        return true;
+    if (tgtName && srcSymbol?.getName() === tgtName)
+        return true;
+    return false;
+};
+const serializeExport = (symbol, checker, tsMod, maxDepth, onInternalError, registry) => {
+    const resolved = resolveExportSymbol(symbol, checker, tsMod);
+    const declaration = resolved.valueDeclaration ?? resolved.declarations?.[0];
+    const useDeclaredType = declaration &&
+        (tsMod.isTypeAliasDeclaration(declaration) || tsMod.isInterfaceDeclaration(declaration));
+    const exportedType = useDeclaredType
+        ? checker.getDeclaredTypeOfSymbol(resolved)
+        : declaration
+            ? checker.getTypeOfSymbolAtLocation(resolved, declaration)
+            : checker.getDeclaredTypeOfSymbol(resolved);
+    return {
+        name: symbol.getName(),
+        declarationKind: declaration ? tsMod.SyntaxKind[declaration.kind] : undefined,
+        declarationText: declaration ? declaration.getText() : undefined,
+        docs: tsMod.displayPartsToString(symbol.getDocumentationComment(checker)) || undefined,
+        type: serializeTypeNode(exportedType, checker, tsMod, 0, maxDepth, new Set(), onInternalError, registry),
+    };
+};
+const collectImports = (sourceFile, program, tsMod) => {
+    const imports = [];
+    tsMod.forEachChild(sourceFile, (node) => {
+        if (!tsMod.isImportDeclaration(node))
+            return;
+        const moduleSpecifier = node.moduleSpecifier;
+        if (!tsMod.isStringLiteral(moduleSpecifier))
+            return;
+        const spec = moduleSpecifier.text;
+        const binding = node.importClause;
+        let info = { moduleSpecifier: spec };
+        if (binding) {
+            if (binding.namedBindings) {
+                if (tsMod.isNamedImports(binding.namedBindings)) {
+                    info = {
+                        ...info,
+                        importedNames: binding.namedBindings.elements.map((el) => (el.propertyName ?? el.name).getText(sourceFile)),
+                    };
+                }
+                else if (tsMod.isNamespaceImport(binding.namedBindings)) {
+                    info = {
+                        ...info,
+                        namespaceImport: binding.namedBindings.name.getText(sourceFile),
+                    };
+                }
+            }
+            if (binding.name) {
+                info = { ...info, defaultImport: binding.name.getText(sourceFile) };
+            }
+        }
+        imports.push(info);
+    });
+    return imports;
+};
+const createFileSnapshot = (sourceFile, checker, program, tsMod, maxDepth, includeImports, onInternalError, registry) => {
+    const filePath = sourceFile.fileName;
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exports = moduleSymbol
+        ? checker
+            .getExportsOfModule(moduleSymbol)
+            .map((value) => serializeExport(value, checker, tsMod, maxDepth, onInternalError, registry))
+            .sort(compareByName)
+        : [];
+    const imports = includeImports ? collectImports(sourceFile, program, tsMod) : undefined;
+    return {
+        filePath,
+        exports,
+        ...(imports !== undefined && imports.length > 0 ? { imports } : {}),
+    };
+};
+/**
+ * Apply a sequence of projection steps to a ts.Type, navigating to a sub-type.
+ * Returns undefined when any step fails (e.g. returnType on non-function).
+ */
+const applyProjection = (type, steps, checker, tsMod, opts) => {
+    const { onInternalError, targetsByIdMap, assignabilityMode, maxDepth } = opts;
+    let current = type;
+    for (const step of steps) {
+        try {
+            switch (step.kind) {
+                case "returnType": {
+                    const sigs = checker.getSignaturesOfType(current, tsMod.SignatureKind.Call);
+                    if (sigs.length === 0)
+                        return undefined;
+                    current = checker.getReturnTypeOfSignature(sigs[0]);
+                    break;
+                }
+                case "param": {
+                    const sigs = checker.getSignaturesOfType(current, tsMod.SignatureKind.Call);
+                    if (sigs.length === 0)
+                        return undefined;
+                    const params = sigs[0].getParameters();
+                    if (step.index < 0 || step.index >= params.length)
+                        return undefined;
+                    const param = params[step.index];
+                    const decl = param.valueDeclaration ?? param.declarations?.[0];
+                    current = decl
+                        ? checker.getTypeOfSymbolAtLocation(param, decl)
+                        : checker.getDeclaredTypeOfSymbol(param);
+                    break;
+                }
+                case "typeArg": {
+                    const args = checker.getTypeArguments(current);
+                    if (step.index < 0 || step.index >= args.length)
+                        return undefined;
+                    current = args[step.index];
+                    break;
+                }
+                case "property": {
+                    const prop = current.getProperty(step.name);
+                    if (!prop)
+                        return undefined;
+                    const decl = prop.valueDeclaration ?? prop.declarations?.[0];
+                    current = decl
+                        ? checker.getTypeOfSymbolAtLocation(prop, decl)
+                        : checker.getDeclaredTypeOfSymbol(prop);
+                    break;
+                }
+                case "ensure": {
+                    const target = targetsByIdMap.get(step.targetId);
+                    if (!target)
+                        return undefined;
+                    if (!isAssignableTo(current, target, checker, tsMod, assignabilityMode))
+                        return undefined;
+                    break;
+                }
+                case "predicate": {
+                    const serialized = serializeTypeNode(current, checker, tsMod, 0, maxDepth, new Set(), onInternalError);
+                    if (!step.fn(serialized))
+                        return undefined;
+                    break;
+                }
+                default:
+                    return undefined;
+            }
+        }
+        catch (err) {
+            onInternalError?.(err, `applyProjection:${step.kind}`);
+            return undefined;
+        }
+    }
+    return current;
+};
+export const createTypeInfoApiSession = (options) => {
+    let effectiveTypeTargets = options.typeTargets ??
+        (options.typeTargetSpecs?.length
+            ? resolveTypeTargetsFromSpecs(options.program, options.ts, options.typeTargetSpecs)
+            : undefined);
+    const failWhenNoTargets = options.failWhenNoTargetsResolved !== false;
+    if (failWhenNoTargets &&
+        options.typeTargetSpecs &&
+        options.typeTargetSpecs.length > 0 &&
+        (!effectiveTypeTargets || effectiveTypeTargets.length === 0)) {
+        const modules = [...new Set(options.typeTargetSpecs.map((s) => s.module))].join(", ");
+        throw new Error(`type targets could not be resolved; ensure program includes imports from: ${modules}. ` +
+            "Use createTypeTargetBootstrapContent(typeTargetSpecs) to generate a bootstrap file and add it to program rootNames.");
+    }
+    const checker = options.program.getTypeChecker();
+    const descriptors = new Map();
+    const snapshotCache = new Map();
+    const directoryCache = new Map();
+    const maxDepth = options.maxTypeDepth ?? DEFAULT_MAX_DEPTH;
+    const assignabilityMode = options.assignabilityMode ?? "compatibility";
+    const typeNodeRegistry = new WeakMap();
+    const targetsByIdMap = new Map((effectiveTypeTargets ?? []).map((t) => [t.id, t.type]));
+    const registerDescriptor = (descriptor) => {
+        if (descriptor.type === "file") {
+            descriptors.set(`file:${descriptor.path}`, descriptor);
+            return;
+        }
+        const globs = descriptor.relativeGlobs.join("|");
+        descriptors.set(`glob:${descriptor.baseDir}:${descriptor.recursive ? "r" : "nr"}:${globs}`, descriptor);
+    };
+    const file = (relativePath, queryOptions) => {
+        const baseDirResult = validatePathSegment(queryOptions.baseDir, "baseDir");
+        if (!baseDirResult.ok)
+            return { ok: false, error: "invalid-input" };
+        const relativePathResult = validatePathSegment(relativePath, "relativePath");
+        if (!relativePathResult.ok)
+            return { ok: false, error: "invalid-input" };
+        const baseDir = baseDirResult.value;
+        const normalizedRelativePath = relativePathResult.value;
+        const pathResult = resolvePathUnderBase(baseDir, normalizedRelativePath);
+        if (!pathResult.ok) {
+            return {
+                ok: false,
+                error: "path-escapes-base",
+                path: resolveRelativePath(baseDir, normalizedRelativePath),
+            };
+        }
+        const absolutePath = pathResult.path;
+        try {
+            if (!pathIsUnderBase(baseDir, absolutePath)) {
+                return { ok: false, error: "path-escapes-base", path: absolutePath };
+            }
+        }
+        catch {
+            return { ok: false, error: "path-escapes-base", path: absolutePath };
+        }
+        if (queryOptions.watch) {
+            registerDescriptor({
+                type: "file",
+                path: absolutePath,
+            });
+        }
+        const sourceFile = options.program.getSourceFile(absolutePath);
+        if (!sourceFile) {
+            return { ok: false, error: "file-not-in-program", path: absolutePath };
+        }
+        const cached = snapshotCache.get(absolutePath);
+        if (cached !== undefined) {
+            return { ok: true, snapshot: cached };
+        }
+        const snapshot = createFileSnapshot(sourceFile, checker, options.program, options.ts, maxDepth, true, options.onInternalError, typeNodeRegistry);
+        snapshotCache.set(absolutePath, snapshot);
+        return { ok: true, snapshot };
+    };
+    const directoryCacheKey = (baseDir, normalizedGlobs, recursive) => `${baseDir}\0${normalizedGlobs.join("\0")}\0${recursive ? "r" : "nr"}`;
+    const directory = (relativeGlobs, queryOptions) => {
+        const baseDirResult = validatePathSegment(queryOptions.baseDir, "baseDir");
+        if (!baseDirResult.ok)
+            return [];
+        const baseDir = baseDirResult.value;
+        const globsResult = validateRelativeGlobs(relativeGlobs, "relativeGlobs");
+        if (!globsResult.ok)
+            return [];
+        const normalizedGlobs = dedupeSorted(globsResult.value);
+        const cacheKey = directoryCacheKey(baseDir, normalizedGlobs, queryOptions.recursive ?? false);
+        const cached = directoryCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        if (queryOptions.watch) {
+            registerDescriptor({
+                type: "glob",
+                baseDir: toPosixPath(baseDir),
+                relativeGlobs: normalizedGlobs,
+                recursive: queryOptions.recursive,
+            });
+        }
+        const depth = queryOptions.recursive ? undefined : 1;
+        const includes = queryOptions.recursive && normalizedGlobs.every((g) => !g.includes("**"))
+            ? [...normalizedGlobs, ...normalizedGlobs.map((g) => `**/${g}`)]
+            : normalizedGlobs;
+        const matchedPaths = options.ts.sys.readDirectory(baseDir, TYPE_EXTENSIONS, undefined, includes, depth);
+        const normalizedMatches = dedupeSorted(matchedPaths.map((value) => resolveRelativePath(baseDir, value)));
+        const underBase = normalizedMatches.filter((filePath) => pathIsUnderBase(baseDir, filePath));
+        const filteredMatches = queryOptions.recursive
+            ? underBase
+            : underBase.filter((filePath) => {
+                const relativePath = toPosixPath(relative(baseDir, filePath));
+                return !relativePath.includes("/");
+            });
+        const program = options.program;
+        const tsMod = options.ts;
+        const snapshots = filteredMatches.flatMap((filePath) => {
+            const sf = program.getSourceFile(filePath);
+            if (!sf)
+                return [];
+            try {
+                return [
+                    createFileSnapshot(sf, checker, program, tsMod, maxDepth, true, options.onInternalError, typeNodeRegistry),
+                ];
+            }
+            catch (err) {
+                options.onInternalError?.(err, `directory() serialization for ${filePath}`);
+                return [];
+            }
+        });
+        directoryCache.set(cacheKey, snapshots);
+        return snapshots;
+    };
+    const resolveExport = (baseDir, filePath, exportName) => {
+        const result = file(filePath, { baseDir });
+        if (!result.ok)
+            return undefined;
+        return result.snapshot.exports.find((e) => e.name === exportName);
+    };
+    const apiIsAssignableTo = (node, targetId, projection) => {
+        const sourceType = typeNodeRegistry.get(node);
+        if (!sourceType)
+            return false;
+        const targetType = targetsByIdMap.get(targetId);
+        if (!targetType)
+            return false;
+        const projected = projection?.length
+            ? applyProjection(sourceType, projection, checker, options.ts, {
+                onInternalError: options.onInternalError,
+                targetsByIdMap,
+                assignabilityMode,
+                maxDepth,
+            })
+            : sourceType;
+        if (!projected)
+            return false;
+        return isAssignableTo(projected, targetType, checker, options.ts, assignabilityMode);
+    };
+    return {
+        api: {
+            file,
+            directory,
+            resolveExport,
+            isAssignableTo: apiIsAssignableTo,
+        },
+        consumeDependencies: () => [...descriptors.values()],
+    };
+};
+export const createTypeInfoApiSessionFactory = (options) => () => createTypeInfoApiSession(options);