@typed/virtual-modules 1.0.0-beta.1

package/src/TypeInfoApi.ts

@@ -0,0 +1,1228 @@
+import { relative } from "node:path";
+import type * as ts from "typescript";
+import {
+  type CreateTypeInfoApiSession,
+  type ExportedTypeInfo,
+  type FileSnapshotResult,
+  type TypeInfoApi,
+  type TypeInfoApiSession,
+  type TypeInfoFileQueryOptions,
+  type TypeInfoFileSnapshot,
+  type TypeProjectionStep,
+  type WatchDependencyDescriptor,
+} from "./types.js";
+import type {
+  AnyTypeNode,
+  ArrayTypeNode,
+  ConditionalTypeNode,
+  ConstructorTypeNode,
+  EnumTypeNode,
+  FunctionSignature,
+  FunctionTypeNode,
+  IndexedAccessTypeNode,
+  IndexSignatureInfo,
+  ImportInfo,
+  IntersectionTypeNode,
+  LiteralTypeNode,
+  MappedTypeNode,
+  NeverTypeNode,
+  ObjectProperty,
+  ObjectTypeNode,
+  OverloadSetTypeNode,
+  PrimitiveTypeNode,
+  ReferenceTypeNode,
+  TemplateLiteralTypeNode,
+  TupleTypeNode,
+  TypeNode,
+  TypeOperatorTypeNode,
+  TypeParameter,
+  TypeTargetSpec,
+  UnionTypeNode,
+  UnknownTypeNode,
+} from "./types.js";
+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;
+
+/**
+ * Pre-resolved type for structural assignability checks.
+ * Host resolves ts.Type from the program (e.g. Fx from @typed/fx) and passes it.
+ */
+export interface ResolvedTypeTarget {
+  readonly id: string;
+  readonly type: ts.Type;
+}
+
+export interface CreateTypeInfoApiSessionOptions {
+  readonly ts: typeof import("typescript");
+  readonly program: ts.Program;
+  readonly maxTypeDepth?: number;
+  /** Pre-resolved types for assignability checks. Takes precedence over typeTargetSpecs when both exist. */
+  readonly typeTargets?: readonly ResolvedTypeTarget[];
+  /**
+   * Specs to resolve from program imports for assignability checks.
+   * Resolution happens internally; use this instead of typeTargets when you have module+export specs.
+   */
+  readonly typeTargetSpecs?: readonly TypeTargetSpec[];
+  /**
+   * When true (default) and typeTargetSpecs are provided but resolution finds zero targets,
+   * session creation throws. Set false to allow empty resolution (assignableTo will be undefined for all exports).
+   */
+  readonly failWhenNoTargetsResolved?: boolean;
+  /**
+   * Assignability check mode.
+   * - "strict": Use only checker.isTypeAssignableTo; no heuristic fallbacks. Correct TS semantics.
+   * - "compatibility" (default): Use checker.isTypeAssignableTo first, then fallbacks for generic/inheritance
+   *   when types come from different files (e.g. fixture vs bootstrap). Union sources require ALL
+   *   constituents to be assignable (sound union semantics).
+   */
+  readonly assignabilityMode?: "strict" | "compatibility";
+  /**
+   * Optional callback when an internal TS API or fallback path catches an error.
+   * Assignability and serialization may degrade (e.g. "not assignable" or safe fallback) without throwing.
+   * Use for observability in production; default behavior is unchanged when not provided.
+   */
+  readonly onInternalError?: (err: unknown, context: string) => void;
+}
+
+const compareByName = <T extends { readonly name: string }>(a: T, b: T): number =>
+  a.name.localeCompare(b.name);
+
+const toOptionalFlag = (symbol: ts.Symbol, tsMod: typeof import("typescript")): boolean =>
+  (symbol.flags & tsMod.SymbolFlags.Optional) !== 0;
+
+const hasReadonlyModifier = (
+  declaration: ts.Declaration | undefined,
+  tsMod: typeof import("typescript"),
+): boolean => {
+  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: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+): LiteralTypeNode | undefined => {
+  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: ts.Signature,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  depth: number,
+  maxDepth: number,
+  visited: Set<string>,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): { parameters: readonly TypeParameter[]; returnType: TypeNode } => {
+  const parameters: TypeParameter[] = 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: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  depth: number,
+  maxDepth: number,
+  visited: Set<string>,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): readonly ObjectProperty[] => {
+  const properties = checker.getPropertiesOfType(type);
+  const snapshots = properties.map((property): ObjectProperty => {
+    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: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  depth: number,
+  maxDepth: number,
+  visited: Set<string>,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): IndexSignatureInfo | undefined => {
+  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: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+): PrimitiveTypeNode | AnyTypeNode | UnknownTypeNode | NeverTypeNode | undefined => {
+  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: UnknownTypeNode = { kind: "unknown", text: "unknown" };
+
+const serializeTypeNode = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  depth: number,
+  maxDepth: number,
+  visited: Set<string>,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): TypeNode => {
+  const text = checker.typeToString(type);
+  const reg = <T extends TypeNode>(node: T): T => {
+    registry?.set(node, type);
+    return node;
+  };
+  const typeId = `${(type as { id?: number }).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: UnionTypeNode = {
+      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: IntersectionTypeNode = {
+      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: { name: string; value?: string | number }[] = [];
+    try {
+      const props = checker.getPropertiesOfType(type);
+      for (const sym of props) {
+        const name = sym.name;
+        let value: string | number | undefined;
+        const decl = sym.valueDeclaration;
+        if (decl && tsMod.isEnumMember?.(decl) && decl.initializer) {
+          const init = decl.initializer;
+          if (tsMod.isNumericLiteral?.(init)) {
+            value = parseInt((init as { text: string }).text, 10);
+          } else if (tsMod.isStringLiteral?.(init) || tsMod.isNoSubstitutionTemplateLiteral?.(init)) {
+            value = (init as { text: string }).text;
+          } else {
+            const cv = (checker as ts.TypeChecker & { getConstantValue?(n: ts.Node): string | number | undefined }).getConstantValue?.(init);
+            if (cv !== undefined) value = cv;
+          }
+        }
+        members.push(value !== undefined ? { name, value } : { name });
+      }
+    } catch (err) {
+      onInternalError?.(err, "enum-members");
+    }
+    const enumNode: EnumTypeNode = {
+      kind: "enum",
+      text,
+      members: members.length > 0 ? members : undefined,
+    };
+    return reg(enumNode);
+  }
+
+  if ((type.flags & tsMod.TypeFlags.Conditional) !== 0) {
+    const ct = type as ts.Type & {
+      checkType: ts.Type;
+      extendsType: ts.Type;
+      resolvedTrueType?: ts.Type;
+      resolvedFalseType?: ts.Type;
+      root?: { node?: { trueType?: ts.TypeNode; falseType?: ts.TypeNode } };
+    };
+    const trueType =
+      ct.resolvedTrueType ??
+      (ct.root?.node?.trueType
+        ? (checker as ts.TypeChecker & { getTypeFromTypeNode?(n: ts.TypeNode): ts.Type }).getTypeFromTypeNode?.(ct.root.node.trueType!)
+        : undefined);
+    const falseType =
+      ct.resolvedFalseType ??
+      (ct.root?.node?.falseType
+        ? (checker as ts.TypeChecker & { getTypeFromTypeNode?(n: ts.TypeNode): ts.Type }).getTypeFromTypeNode?.(ct.root.node.falseType!)
+        : undefined);
+    const conditional: ConditionalTypeNode = {
+      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 as ts.Type & { objectType: ts.Type; indexType: ts.Type };
+    const indexed: IndexedAccessTypeNode = {
+      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 as ts.Type & { texts?: readonly string[]; types?: readonly ts.Type[] };
+    const texts = tlt.texts ?? [];
+    const types = tlt.types ?? [];
+    const template: TemplateLiteralTypeNode = {
+      kind: "templateLiteral",
+      text,
+      texts,
+      types: types.map((t) => serializeTypeNode(t, checker, tsMod, depth + 1, maxDepth, visited, onInternalError, registry)),
+    };
+    return reg(template);
+  }
+
+  const objType = type as ts.Type & { objectFlags?: number };
+  const mappedFlag = tsMod.ObjectFlags?.Mapped ?? FALLBACK_OBJECT_FLAGS_MAPPED;
+  if (objType.objectFlags !== undefined && (objType.objectFlags & mappedFlag) !== 0) {
+    const mt = type as ts.Type & {
+      constraint?: ts.Type;
+      templateType?: ts.Type;
+      mappedType?: ts.Type;
+      modifierFlags?: number;
+    };
+    const constraintType = mt.constraint ?? (mt as ts.Type & { typeParameter?: { constraint?: ts.Type } }).typeParameter?.constraint;
+    const mappedType = mt.templateType ?? mt.mappedType;
+    const mapped: MappedTypeNode = {
+      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 as ts.Type & { type: ts.Type };
+    const typeOperator: TypeOperatorTypeNode = {
+      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 as ts.TypeReference);
+    const tuple: TupleTypeNode = {
+      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 as ts.TypeReference);
+    const element = typeArguments[0];
+    const array: ArrayTypeNode = {
+      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 as ts.TypeReference);
+  if (referenceArguments.length > 0) {
+    const ref: ReferenceTypeNode = {
+      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: ConstructorTypeNode = {
+      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: FunctionSignature[] = callSignatures.map((s) => {
+        const serialized = serializeFunctionSignature(s, checker, tsMod, depth, maxDepth, visited, onInternalError, registry);
+        return { parameters: serialized.parameters, returnType: serialized.returnType };
+      });
+      const overload: OverloadSetTypeNode = { kind: "overloadSet", text, signatures };
+      return reg(overload);
+    }
+    const signature = serializeFunctionSignature(
+      callSignatures[0],
+      checker,
+      tsMod,
+      depth,
+      maxDepth,
+      visited,
+      onInternalError,
+      registry,
+    );
+    const fn: FunctionTypeNode = {
+      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: ObjectTypeNode = {
+    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: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  maxDepth = 6,
+): TypeNode {
+  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: readonly TypeTargetSpec[],
+): string {
+  const seen = new Set<string>();
+  const lines: string[] = [
+    "/**",
+    " * 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: ts.Program,
+  tsMod: typeof import("typescript"),
+  specs: readonly TypeTargetSpec[],
+): ResolvedTypeTarget[] {
+  const checker = program.getTypeChecker();
+  const found = new Map<string, ts.Type>();
+
+  const getTypeFromSymbol = (symbol: ts.Symbol): ts.Type | undefined => {
+    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: ts.Symbol,
+    spec: (typeof specs)[number],
+  ): ts.Type | undefined => {
+    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: ts.Symbol | undefined, moduleSpec: string): void => {
+    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: ts.ImportSpecifier) => {
+        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: ts.Symbol,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+): ts.Symbol => resolveAliasedSymbol(symbol, checker, tsMod);
+
+/** Get the base GenericType from a generic instantiation (TypeReference). */
+const getGenericBase = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): (ts.Type & { symbol?: ts.Symbol }) | undefined => getTypeReferenceTarget(type, checker);
+
+/** Get the symbol representing the "root" type for comparison (handles GenericType and TypeReference). */
+const getComparisonSymbol = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): ts.Symbol | undefined => {
+  const base = getGenericBase(type, checker);
+  if (base?.symbol) return base.symbol;
+  return getTypeSymbol(type);
+};
+
+type AssignabilityMode = "strict" | "compatibility";
+
+/**
+ * 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: ts.Type,
+  target: ts.Type,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  mode: AssignabilityMode,
+): boolean => {
+  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: ts.Symbol | undefined) =>
+    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 as ts.Type & { symbol?: ts.Symbol }).symbol;
+    const isClassOrInterface =
+      srcSym &&
+      (srcSym.flags & (tsMod.SymbolFlags.Class | tsMod.SymbolFlags.Interface)) !== 0;
+    if (isClassOrInterface) {
+      const bases = getBaseTypesInternal(source as ts.InterfaceType, 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: ts.Symbol,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  maxDepth: number,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): ExportedTypeInfo => {
+  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: ts.SourceFile,
+  program: ts.Program,
+  tsMod: typeof import("typescript"),
+): ImportInfo[] => {
+  const imports: ImportInfo[] = [];
+  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: ImportInfo = { 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: ts.SourceFile,
+  checker: ts.TypeChecker,
+  program: ts.Program,
+  tsMod: typeof import("typescript"),
+  maxDepth: number,
+  includeImports: boolean,
+  onInternalError?: (err: unknown, context: string) => void,
+  registry?: WeakMap<TypeNode, ts.Type>,
+): TypeInfoFileSnapshot => {
+  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: ts.Type,
+  steps: readonly TypeProjectionStep[],
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+  opts: {
+    onInternalError?: (err: unknown, context: string) => void;
+    targetsByIdMap: Map<string, ts.Type>;
+    assignabilityMode: AssignabilityMode;
+    maxDepth: number;
+  },
+): ts.Type | undefined => {
+  const { onInternalError, targetsByIdMap, assignabilityMode, maxDepth } = opts;
+  let current: ts.Type = 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 as ts.TypeReference);
+          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: CreateTypeInfoApiSessionOptions,
+): TypeInfoApiSession => {
+  let effectiveTypeTargets: readonly ResolvedTypeTarget[] | undefined =
+    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<string, WatchDependencyDescriptor>();
+  const snapshotCache = new Map<string, TypeInfoFileSnapshot>();
+  const directoryCache = new Map<string, TypeInfoFileSnapshot[]>();
+  const maxDepth = options.maxTypeDepth ?? DEFAULT_MAX_DEPTH;
+  const assignabilityMode: AssignabilityMode =
+    options.assignabilityMode ?? "compatibility";
+  const typeNodeRegistry = new WeakMap<TypeNode, ts.Type>();
+  const targetsByIdMap = new Map<string, ts.Type>(
+    (effectiveTypeTargets ?? []).map((t) => [t.id, t.type]),
+  );
+
+  const registerDescriptor = (descriptor: WatchDependencyDescriptor): void => {
+    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: string,
+    queryOptions: TypeInfoFileQueryOptions,
+  ): FileSnapshotResult => {
+    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: string,
+    normalizedGlobs: readonly string[],
+    recursive: boolean,
+  ): string =>
+    `${baseDir}\0${normalizedGlobs.join("\0")}\0${recursive ? "r" : "nr"}`;
+
+  const directory: TypeInfoApi["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: string,
+    filePath: string,
+    exportName: string,
+  ): ExportedTypeInfo | undefined => {
+    const result = file(filePath, { baseDir });
+    if (!result.ok) return undefined;
+    return result.snapshot.exports.find((e) => e.name === exportName);
+  };
+
+  const apiIsAssignableTo = (
+    node: TypeNode,
+    targetId: string,
+    projection?: readonly TypeProjectionStep[],
+  ): boolean => {
+    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: CreateTypeInfoApiSessionOptions): CreateTypeInfoApiSession =>
+  () =>
+    createTypeInfoApiSession(options);