@typed/virtual-modules 1.0.0-beta.1

package/src/collectTypeTargetSpecs.ts

@@ -0,0 +1,22 @@
+import type { TypeTargetSpec, VirtualModulePlugin } from "./types.js";
+
+/**
+ * Collects and merges typeTargetSpecs from plugins. Dedupes by id (first wins).
+ */
+export function collectTypeTargetSpecsFromPlugins(
+  plugins: readonly VirtualModulePlugin[],
+): readonly TypeTargetSpec[] {
+  const seen = new Set<string>();
+  const result: TypeTargetSpec[] = [];
+  for (const plugin of plugins) {
+    const specs = plugin.typeTargetSpecs;
+    if (!specs?.length) continue;
+    for (const spec of specs) {
+      if (!seen.has(spec.id)) {
+        seen.add(spec.id);
+        result.push(spec);
+      }
+    }
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export * from "./types.js";
+export * from "./PluginManager.js";
+export { collectTypeTargetSpecsFromPlugins } from "./collectTypeTargetSpecs.js";
+export {
+  createTypeInfoApiSession,
+  createTypeInfoApiSessionFactory,
+  createTypeTargetBootstrapContent,
+  resolveTypeTargetsFromSpecs,
+  type CreateTypeInfoApiSessionOptions,
+  type ResolvedTypeTarget,
+} from "./TypeInfoApi.js";
+export * from "./NodeModulePluginLoader.js";
+export * from "./LanguageServiceAdapter.js";
+export * from "./CompilerHostAdapter.js";
+export * from "./VmcConfigLoader.js";
+export * from "./VmcResolverLoader.js";
+export {
+  createVirtualFileName,
+  createVirtualKey,
+  VIRTUAL_MODULE_URI_SCHEME,
+  VIRTUAL_NODE_MODULES_RELATIVE,
+  type CreateVirtualFileNameParams,
+  type CreateVirtualFileNameOptions,
+} from "./internal/path.js";
+export {
+  ensureTypeTargetBootstrapFile,
+  getProgramWithTypeTargetBootstrap,
+  getTypeTargetBootstrapPath,
+  TYPE_TARGET_BOOTSTRAP_RELATIVE,
+  type EnsureTypeTargetBootstrapFileFs,
+} from "./typeTargetBootstrap.js";
+export {
+  createLanguageServiceSessionFactory,
+  type CreateLanguageServiceSessionFactoryOptions,
+} from "./LanguageServiceSession.js";

package/src/internal/VirtualRecordStore.ts

@@ -0,0 +1,304 @@
+import type * as ts from "typescript";
+import type {
+  ResolveVirtualModuleOptions,
+  VirtualModuleDiagnostic,
+  VirtualModuleRecord,
+  VirtualModuleResolution,
+} from "../types.js";
+import { createVirtualFileName, createVirtualKey, createWatchDescriptorKey } from "./path.js";
+
+export type MutableVirtualRecord = Omit<VirtualModuleRecord, "version" | "stale"> & {
+  version: number;
+  stale: boolean;
+};
+
+export interface ResolveRecordResultResolved {
+  readonly status: "resolved";
+  readonly record: MutableVirtualRecord;
+}
+
+export interface ResolveRecordResultUnresolved {
+  readonly status: "unresolved";
+}
+
+export interface ResolveRecordResultError {
+  readonly status: "error";
+  readonly diagnostic: VirtualModuleDiagnostic;
+}
+
+export type ResolveRecordResult =
+  | ResolveRecordResultResolved
+  | ResolveRecordResultUnresolved
+  | ResolveRecordResultError;
+
+export interface VirtualRecordStoreOptions {
+  readonly projectRoot: string;
+  readonly resolver: {
+    resolveModule(options: ResolveVirtualModuleOptions): VirtualModuleResolution;
+  };
+  readonly createTypeInfoApiSession?: ResolveVirtualModuleOptions["createTypeInfoApiSession"];
+  readonly debounceMs?: number;
+  readonly watchHost?: {
+    watchFile?(path: string, callback: () => void): ts.FileWatcher;
+    watchDirectory?(path: string, callback: () => void, recursive?: boolean): ts.FileWatcher;
+  };
+  /** Used by evictStaleImporters: records for which this returns true are evicted. */
+  readonly shouldEvictRecord: (record: MutableVirtualRecord) => boolean;
+  /** Called when flushPendingStale runs (after debounce). LS uses for epoch++. */
+  readonly onFlushStale?: () => void;
+  /** Called when a record is marked stale (immediate or after flush). CH uses for invalidatedPaths. */
+  readonly onMarkStale?: (record: MutableVirtualRecord) => void;
+  /** Called at start of resolveRecord (e.g. LS sets inResolveRecord). */
+  readonly onBeforeResolve?: () => void;
+  /** Called in finally after resolveRecord (e.g. LS clears inResolveRecord). */
+  readonly onAfterResolve?: () => void;
+  /** Called after a record is stored and watchers registered (e.g. LS clears diagnostics for importer). */
+  readonly onRecordResolved?: (record: MutableVirtualRecord) => void;
+  /** Called when a record is evicted (e.g. LS clears diagnostics for importer). */
+  readonly onEvictRecord?: (record: MutableVirtualRecord) => void;
+}
+
+export function toResolvedModule(
+  tsMod: typeof import("typescript"),
+  fileName: string,
+): ts.ResolvedModuleFull {
+  return {
+    resolvedFileName: fileName,
+    extension: tsMod.Extension.Ts,
+    isExternalLibraryImport: false,
+  };
+}
+
+export function createVirtualRecordStore(options: VirtualRecordStoreOptions) {
+  const recordsByKey = new Map<string, MutableVirtualRecord>();
+  const recordsByVirtualFile = new Map<string, MutableVirtualRecord>();
+  const descriptorToVirtualKeys = new Map<string, Set<string>>();
+  const watcherByDescriptor = new Map<string, ts.FileWatcher>();
+
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+  const pendingStaleKeys = new Set<string>();
+  const {
+    debounceMs,
+    watchHost,
+    shouldEvictRecord,
+    onFlushStale,
+    onMarkStale,
+    onBeforeResolve,
+    onAfterResolve,
+    onRecordResolved,
+    onEvictRecord,
+  } = options;
+
+  const evictRecord = (record: MutableVirtualRecord): void => {
+    onEvictRecord?.(record);
+    recordsByKey.delete(record.key);
+    recordsByVirtualFile.delete(record.virtualFileName);
+    for (const descriptor of record.dependencies) {
+      const descriptorKey = createWatchDescriptorKey(descriptor);
+      const dependents = descriptorToVirtualKeys.get(descriptorKey);
+      if (dependents) {
+        dependents.delete(record.key);
+        if (dependents.size === 0) {
+          descriptorToVirtualKeys.delete(descriptorKey);
+          const watcher = watcherByDescriptor.get(descriptorKey);
+          if (watcher) {
+            watcher.close();
+            watcherByDescriptor.delete(descriptorKey);
+          }
+        }
+      }
+    }
+  };
+
+  const evictStaleImporters = (): void => {
+    const toEvict: MutableVirtualRecord[] = [];
+    for (const record of recordsByKey.values()) {
+      if (shouldEvictRecord(record)) {
+        toEvict.push(record);
+      }
+    }
+    for (const record of toEvict) {
+      evictRecord(record);
+    }
+  };
+
+  const registerWatchers = (record: MutableVirtualRecord): void => {
+    for (const descriptor of record.dependencies) {
+      const descriptorKey = createWatchDescriptorKey(descriptor);
+      const dependents = descriptorToVirtualKeys.get(descriptorKey) ?? new Set<string>();
+      dependents.add(record.key);
+      descriptorToVirtualKeys.set(descriptorKey, dependents);
+
+      if (watcherByDescriptor.has(descriptorKey)) {
+        continue;
+      }
+
+      if (descriptor.type === "file" && watchHost?.watchFile) {
+        const watcher = watchHost.watchFile(descriptor.path, () => {
+          markStale(descriptorKey);
+        });
+        watcherByDescriptor.set(descriptorKey, watcher);
+      } else if (descriptor.type === "glob" && watchHost?.watchDirectory) {
+        const watcher = watchHost.watchDirectory(
+          descriptor.baseDir,
+          () => {
+            markStale(descriptorKey);
+          },
+          descriptor.recursive,
+        );
+        watcherByDescriptor.set(descriptorKey, watcher);
+      }
+    }
+  };
+
+  const flushPendingStale = (): void => {
+    if (pendingStaleKeys.size === 0) {
+      return;
+    }
+    onFlushStale?.();
+    for (const descriptorKey of pendingStaleKeys) {
+      const keys = descriptorToVirtualKeys.get(descriptorKey);
+      if (!keys || keys.size === 0) {
+        continue;
+      }
+      for (const key of keys) {
+        const record = recordsByKey.get(key);
+        if (record) {
+          record.stale = true;
+          onMarkStale?.(record);
+        }
+      }
+    }
+    pendingStaleKeys.clear();
+    debounceTimer = undefined;
+  };
+
+  const markStale = (descriptorKey: string): void => {
+    if (debounceMs !== undefined && debounceMs > 0) {
+      pendingStaleKeys.add(descriptorKey);
+      if (debounceTimer === undefined) {
+        debounceTimer = setTimeout(() => {
+          flushPendingStale();
+        }, debounceMs);
+      }
+      return;
+    }
+
+    const keys = descriptorToVirtualKeys.get(descriptorKey);
+    if (!keys || keys.size === 0) {
+      return;
+    }
+
+    for (const key of keys) {
+      const record = recordsByKey.get(key);
+      if (record) {
+        record.stale = true;
+        onMarkStale?.(record);
+      }
+    }
+  };
+
+  const resolveRecord = (
+    id: string,
+    importer: string,
+    previous?: MutableVirtualRecord,
+  ): ResolveRecordResult => {
+    onBeforeResolve?.();
+    try {
+      const resolveOptions: ResolveVirtualModuleOptions = {
+        id,
+        importer,
+        createTypeInfoApiSession: options.createTypeInfoApiSession,
+      };
+
+      const resolution = options.resolver.resolveModule(resolveOptions);
+      if (resolution.status === "unresolved") {
+        return { status: "unresolved" };
+      }
+
+      if (resolution.status === "error") {
+        return {
+          status: "error",
+          diagnostic: resolution.diagnostic,
+        };
+      }
+
+      const key = createVirtualKey(id, importer);
+      const virtualFileName = createVirtualFileName(
+        resolution.pluginName,
+        key,
+        { id, importer },
+        { projectRoot: options.projectRoot },
+      );
+      const record: MutableVirtualRecord = {
+        key,
+        id,
+        importer,
+        pluginName: resolution.pluginName,
+        virtualFileName,
+        sourceText: resolution.sourceText,
+        dependencies: resolution.dependencies,
+        ...(resolution.warnings?.length ? { warnings: resolution.warnings } : {}),
+        version: previous ? previous.version + 1 : 1,
+        stale: false,
+      };
+
+      recordsByKey.set(key, record);
+      recordsByVirtualFile.set(virtualFileName, record);
+      registerWatchers(record);
+      onRecordResolved?.(record);
+      return {
+        status: "resolved",
+        record,
+      };
+    } finally {
+      onAfterResolve?.();
+    }
+  };
+
+  const getOrBuildRecord = (id: string, importer: string): ResolveRecordResult => {
+    evictStaleImporters();
+
+    const key = createVirtualKey(id, importer);
+    const existing = recordsByKey.get(key);
+    if (existing && !existing.stale) {
+      return {
+        status: "resolved",
+        record: existing,
+      };
+    }
+
+    return resolveRecord(id, importer, existing);
+  };
+
+  const dispose = (): void => {
+    if (debounceTimer !== undefined) {
+      clearTimeout(debounceTimer);
+      debounceTimer = undefined;
+    }
+    pendingStaleKeys.clear();
+
+    for (const watcher of watcherByDescriptor.values()) {
+      watcher.close();
+    }
+    watcherByDescriptor.clear();
+    descriptorToVirtualKeys.clear();
+    recordsByKey.clear();
+    recordsByVirtualFile.clear();
+  };
+
+  return {
+    recordsByKey,
+    recordsByVirtualFile,
+    descriptorToVirtualKeys,
+    watcherByDescriptor,
+    evictRecord,
+    evictStaleImporters,
+    registerWatchers,
+    markStale,
+    flushPendingStale,
+    resolveRecord,
+    getOrBuildRecord,
+    dispose,
+  };
+}

package/src/internal/materializeVirtualFile.ts

@@ -0,0 +1,38 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { toPosixPath } from "./path.js";
+
+/**
+ * Rewrite relative import specifiers in sourceText so they resolve correctly when
+ * the file is placed in previewDir instead of importerDir.
+ */
+export function rewriteSourceForPreviewLocation(
+  sourceText: string,
+  importer: string,
+  virtualFilePath: string,
+): string {
+  const importerDir = dirname(resolve(importer));
+  const previewDir = dirname(resolve(virtualFilePath));
+  return sourceText.replace(/from\s+['"](\.\.?\/[^'"]+)['"]/g, (match, spec: string) => {
+    const absoluteTarget = resolve(importerDir, spec);
+    const newRel = toPosixPath(relative(previewDir, absoluteTarget));
+    const newSpec = newRel.startsWith(".") ? newRel : `./${newRel}`;
+    const quote = match.includes('"') ? '"' : "'";
+    return `from ${quote}${newSpec}${quote}`;
+  });
+}
+
+/**
+ * Materialize virtual module content to disk at virtualFilePath. Rewrites relative
+ * imports so they resolve from the virtual file's location. Used so go-to-definition
+ * can open the file (path must exist on disk).
+ */
+export function materializeVirtualFile(
+  virtualFilePath: string,
+  importer: string,
+  sourceText: string,
+): void {
+  const rewritten = rewriteSourceForPreviewLocation(sourceText, importer, virtualFilePath);
+  mkdirSync(dirname(resolve(virtualFilePath)), { recursive: true });
+  writeFileSync(virtualFilePath, rewritten, "utf8");
+}

package/src/internal/path.ts

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { posix } from "node:path";
+import type { WatchDependencyDescriptor } from "../types.js";
+
+/** Base directory for virtual files under node_modules (enables go-to-definition to resolve correctly). */
+export const VIRTUAL_NODE_MODULES_RELATIVE = "node_modules/.typed/virtual";
+
+export const toPosixPath = (path: string): string => path.replaceAll("\\", "/");
+
+export const resolveRelativePath = (baseDir: string, relativePath: string): string =>
+  toPosixPath(resolve(baseDir, relativePath));
+
+/**
+ * Resolves relativePath against baseDir and ensures the result stays under baseDir.
+ * Use for plugin/caller-controlled paths to prevent path traversal.
+ */
+export function resolvePathUnderBase(
+  baseDir: string,
+  relativePath: string,
+): { ok: true; path: string } | { ok: false; error: "path-escapes-base" } {
+  const baseAbs = resolve(baseDir);
+  const resolved = resolve(baseDir, relativePath);
+  const rel = relative(baseAbs, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { ok: false, error: "path-escapes-base" };
+  }
+  return { ok: true, path: toPosixPath(resolved) };
+}
+
+/** Returns true if absolutePath is under baseDir (or equal). Canonicalizes with realpath so symlinks (e.g. /tmp) match. */
+export function pathIsUnderBase(baseDir: string, absolutePath: string): boolean {
+  let baseAbs: string;
+  let resolvedAbs: string;
+  try {
+    baseAbs = realpathSync(resolve(baseDir));
+    resolvedAbs = realpathSync(resolve(absolutePath));
+  } catch {
+    baseAbs = resolve(baseDir);
+    resolvedAbs = resolve(absolutePath);
+  }
+  const rel = relative(baseAbs, resolvedAbs);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return false;
+  }
+  return true;
+}
+
+export const stableHash = (input: string): string =>
+  createHash("sha1").update(input).digest("hex").slice(0, 16);
+
+const sanitizeSegment = (value: string): string => value.replaceAll(/[^a-zA-Z0-9._-]/g, "-");
+
+/** URI scheme for virtual module identifiers (e.g. `typed-virtual://0/...`). Single source of truth for all consumers. */
+export const VIRTUAL_MODULE_URI_SCHEME = "typed-virtual" as const;
+
+export const createVirtualKey = (id: string, importer: string): string => `${importer}::${id}`;
+
+export interface CreateVirtualFileNameParams {
+  readonly id: string;
+  readonly importer: string;
+}
+
+export interface CreateVirtualFileNameOptions {
+  /** When provided, virtual files use projectRoot/node_modules/.typed/virtual/ so go-to-definition resolves correctly. */
+  readonly projectRoot?: string;
+}
+
+/**
+ * Virtual file name for the TS program. When projectRoot is provided, uses
+ * node_modules/.typed/virtual/ so the path exists on disk (after materialization)
+ * and go-to-definition works like node_modules packages. Falls back to
+ * importer-adjacent path or typed-virtual:// URI when projectRoot is not set.
+ */
+export const createVirtualFileName = (
+  pluginName: string,
+  virtualKey: string,
+  params?: CreateVirtualFileNameParams,
+  options?: CreateVirtualFileNameOptions,
+): string => {
+  const safePluginName = sanitizeSegment(pluginName);
+  const hash = stableHash(virtualKey);
+  const basename = `__virtual_${safePluginName}_${hash}.ts`;
+  if (params) {
+    const projectRoot = options?.projectRoot;
+    if (typeof projectRoot === "string" && projectRoot.trim().length > 0) {
+      return toPosixPath(join(resolve(projectRoot), VIRTUAL_NODE_MODULES_RELATIVE, basename));
+    }
+    const importerDir = dirname(toPosixPath(params.importer));
+    return `${importerDir}/${basename}`;
+  }
+  return `${VIRTUAL_MODULE_URI_SCHEME}://0/${safePluginName}/${hash}.ts`;
+};
+
+export const createWatchDescriptorKey = (descriptor: WatchDependencyDescriptor): string => {
+  if (descriptor.type === "file") {
+    return `file:${toPosixPath(descriptor.path)}`;
+  }
+
+  const globs = [...descriptor.relativeGlobs].sort().join("|");
+  return `glob:${toPosixPath(descriptor.baseDir)}:${descriptor.recursive ? "r" : "nr"}:${globs}`;
+};
+
+export const dedupeSorted = (values: readonly string[]): readonly string[] =>
+  [...new Set(values.map(toPosixPath))].sort();

package/src/internal/sanitize.ts

@@ -0,0 +1,16 @@
+/**
+ * Sanitizes error messages for structured diagnostics: strips stack traces and
+ * redacts absolute paths to avoid leaking filesystem layout.
+ */
+export function sanitizeErrorMessage(message: string): string {
+  const withoutStack = message
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*at\s+/.test(line.trim()))
+    .join("\n")
+    .trim();
+
+  const unixPath = /\/[\w./-]+\/[\w./-]+(?:\/[\w./-]*)*/g;
+  const winPath = /[A-Za-z]:[\\/][\w.-]+(?:[\\/][\w.-]+)*/g;
+  let out = withoutStack.replace(unixPath, "[path]").replace(winPath, "[path]");
+  return out.replace(/\s{2,}/g, " ").trim();
+}

package/src/internal/tsInternal.ts

@@ -0,0 +1,127 @@
+/**
+ * Internal TypeScript API access.
+ *
+ * The TypeScript Compiler API does not expose all capabilities we need for
+ * type-target resolution, assignability fallbacks, and serialization. This
+ * module centralizes use of non-public APIs (via type casts) so that:
+ * - All such use is in one place and documented.
+ * - Callers can guard with try/catch and optional chaining.
+ * - Upgrades to new TS versions can be handled here.
+ *
+ * These APIs are not part of the public TypeScript contract and may change
+ * across versions. Tested with TypeScript 5.x.
+ */
+
+import type * as ts from "typescript";
+
+/** Index signature entry shape from internal getIndexInfosOfType (not in public .d.ts). */
+export interface IndexInfo {
+  readonly keyType: ts.Type;
+  readonly type: ts.Type;
+  readonly isReadonly?: boolean;
+}
+
+/**
+ * Get index signature key/value types for an object type when available.
+ * Uses internal TypeChecker.getIndexInfosOfType; may change in future TS versions.
+ * Returns undefined when the API is missing or throws.
+ */
+export function getIndexInfosOfType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): readonly IndexInfo[] | undefined {
+  try {
+    const fn = (checker as ts.TypeChecker & { getIndexInfosOfType?(t: ts.Type): readonly IndexInfo[] })
+      .getIndexInfosOfType;
+    return fn?.(type);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve an alias symbol to the symbol it refers to (re-exports, import-then-export).
+ * Only call when symbol.flags includes SymbolFlags.Alias.
+ * Uses internal TypeChecker.getAliasedSymbol; may change in future TS versions.
+ * Returns the original symbol when the API is missing or throws.
+ */
+export function getAliasedSymbol(
+  symbol: ts.Symbol,
+  checker: ts.TypeChecker,
+  tsMod: typeof import("typescript"),
+): ts.Symbol {
+  if ((symbol.flags & tsMod.SymbolFlags.Alias) === 0) return symbol;
+  try {
+    const aliased = (
+      checker as ts.TypeChecker & { getAliasedSymbol(s: ts.Symbol): ts.Symbol }
+    ).getAliasedSymbol(symbol);
+    return aliased ?? symbol;
+  } catch {
+    return symbol;
+  }
+}
+
+/**
+ * Get the base (generic declaration) type from a TypeReference.
+ * Uses internal (type as TypeReference).target; may change in future TS versions.
+ * Returns undefined when not a TypeReference with target or when access throws.
+ */
+export function getTypeReferenceTarget(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): (ts.Type & { symbol?: ts.Symbol }) | undefined {
+  try {
+    const args = checker.getTypeArguments(type as ts.TypeReference);
+    if (args.length > 0) {
+      const target = (type as ts.TypeReference & { target?: ts.Type }).target;
+      return target as (ts.Type & { symbol?: ts.Symbol }) | undefined;
+    }
+  } catch {
+    /* getTypeArguments can throw for some type shapes */
+  }
+  return undefined;
+}
+
+/**
+ * Get the symbol attached to a type when available (e.g. interface, class, type alias).
+ * Uses internal (type as Type).symbol; may change in future TS versions.
+ */
+export function getTypeSymbol(type: ts.Type): ts.Symbol | undefined {
+  return (type as ts.Type & { symbol?: ts.Symbol }).symbol;
+}
+
+/**
+ * Get namespace/merged declaration exports from a symbol when available.
+ * Uses internal (symbol as Symbol).exports; may change in future TS versions.
+ * Prefer checker.getExportsOfModule(moduleSymbol) for module symbols when applicable.
+ */
+export function getSymbolExports(
+  symbol: ts.Symbol,
+): Map<unknown, ts.Symbol> | undefined {
+  return (symbol as ts.Symbol & { exports?: Map<unknown, ts.Symbol> }).exports;
+}
+
+/**
+ * Get base types of an interface/class for inheritance checks.
+ * Uses internal TypeChecker.getBaseTypes; may change in future TS versions.
+ * Returns undefined when the API is missing or throws (e.g. type is not interface or class).
+ */
+export function getBaseTypes(
+  type: ts.InterfaceType,
+  checker: ts.TypeChecker,
+): ts.Type[] | undefined {
+  try {
+    const fn = (checker as ts.TypeChecker & { getBaseTypes?(t: ts.InterfaceType): ts.Type[] })
+      .getBaseTypes;
+    return fn?.(type);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * ObjectFlags.Mapped value when the public ts.ObjectFlags is missing (e.g. older or different TS build).
+ * Used only as a fallback for mapped-type detection in serialization.
+ * Value 32 corresponds to ObjectFlags.Mapped in TypeScript 5.x; may need adjustment for other versions.
+ */
+export const FALLBACK_OBJECT_FLAGS_MAPPED = 32;