@typed/virtual-modules 1.0.0-beta.1

package/src/LanguageServiceSession.ts

@@ -0,0 +1,160 @@
+/**
+ * Creates a CreateTypeInfoApiSession factory backed by a TypeScript Language Service.
+ * The program evolves over time as files change (via getModifiedTime versioning),
+ * so type-aware virtual module builds stay current during development.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type * as ts from "typescript";
+import type { CreateTypeInfoApiSession, TypeInfoApiSession, TypeTargetSpec } from "./types.js";
+import { createTypeInfoApiSession } from "./TypeInfoApi.js";
+import {
+  ensureTypeTargetBootstrapFile,
+  getProgramWithTypeTargetBootstrap,
+  getTypeTargetBootstrapPath,
+} from "./typeTargetBootstrap.js";
+
+function findTsconfig(fromDir: string): string | undefined {
+  let dir = resolve(fromDir);
+  const root = resolve(dir, "/");
+  while (dir !== root) {
+    const candidate = join(dir, "tsconfig.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+export interface CreateLanguageServiceSessionFactoryOptions {
+  readonly ts: typeof import("typescript");
+  readonly projectRoot: string;
+  readonly typeTargetSpecs?: readonly TypeTargetSpec[];
+  readonly tsconfigPath?: string;
+}
+
+/**
+ * Creates a LanguageService-backed CreateTypeInfoApiSession factory.
+ * Use when you need type-aware virtual module resolution with a program that
+ * evolves as files change (e.g. Vite dev server, standalone tooling).
+ *
+ * Returns undefined if tsconfig cannot be found or parsed.
+ */
+export function createLanguageServiceSessionFactory(
+  options: CreateLanguageServiceSessionFactoryOptions,
+): CreateTypeInfoApiSession | undefined {
+  const { ts, projectRoot, typeTargetSpecs, tsconfigPath: explicitTsconfigPath } = options;
+  const tsconfigPath = explicitTsconfigPath ?? findTsconfig(projectRoot);
+  if (!tsconfigPath) return undefined;
+
+  let parsed: ts.ParsedCommandLine;
+
+  try {
+    // oxlint-disable-next-line typescript/unbound-method
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error) return undefined;
+    const configDir = dirname(tsconfigPath);
+    parsed = ts.parseJsonConfigFileContent(
+      configFile.config,
+      ts.sys,
+      configDir,
+      undefined,
+      tsconfigPath,
+    );
+    if (parsed.errors.length > 0) return undefined;
+  } catch {
+    return undefined;
+  }
+
+  let rootNames = parsed.fileNames;
+  if (typeTargetSpecs && typeTargetSpecs.length > 0) {
+    ensureTypeTargetBootstrapFile(projectRoot, typeTargetSpecs);
+    const bootstrapPath = getTypeTargetBootstrapPath(projectRoot);
+    rootNames = [...rootNames, bootstrapPath];
+  }
+
+  const sys = ts.sys;
+  const compilerOptions = parsed.options;
+
+  const host: ts.LanguageServiceHost = {
+    getCompilationSettings: () => compilerOptions,
+    getScriptFileNames: () => rootNames,
+    getScriptVersion: (fileName: string) => {
+      const mtime = sys.getModifiedTime?.(fileName);
+      return mtime ? String(mtime.getTime()) : "0";
+    },
+    getScriptSnapshot: (fileName: string) => {
+      if (!sys.fileExists(fileName)) return undefined;
+      const content = sys.readFile(fileName);
+      return content !== undefined ? ts.ScriptSnapshot.fromString(content) : undefined;
+    },
+    getCurrentDirectory: () => dirname(tsconfigPath),
+    getDefaultLibFileName: (opts) => ts.getDefaultLibFilePath(opts),
+    directoryExists: sys.directoryExists?.bind(sys),
+    fileExists: sys.fileExists?.bind(sys),
+    readFile: sys.readFile?.bind(sys),
+    readDirectory: sys.readDirectory?.bind(sys),
+  };
+
+  const languageService = ts.createLanguageService(host);
+
+  const createTypeInfoApiSessionFn: CreateTypeInfoApiSession = ({
+    id: _id,
+    importer: _importer,
+  }) => {
+    let session: TypeInfoApiSession | null = null;
+    let apiUsed = false;
+
+    const getSession = (): TypeInfoApiSession => {
+      if (session) return session;
+
+      const program = languageService.getProgram();
+      if (!program) {
+        throw new Error(
+          "TypeInfo session creation failed: Program not yet available from Language Service. Retry when project is loaded.",
+        );
+      }
+
+      const programWithBootstrap = getProgramWithTypeTargetBootstrap(
+        ts,
+        program,
+        projectRoot,
+        typeTargetSpecs,
+      );
+
+      session = createTypeInfoApiSession({
+        ts,
+        program: programWithBootstrap,
+        ...(typeTargetSpecs && typeTargetSpecs.length > 0
+          ? { typeTargetSpecs, failWhenNoTargetsResolved: false }
+          : {}),
+      });
+      return session;
+    };
+
+    return {
+      api: {
+        file: (path, opts) => {
+          apiUsed = true;
+          return getSession().api.file(path, opts);
+        },
+        directory: (glob, opts) => {
+          apiUsed = true;
+          return getSession().api.directory(glob, opts);
+        },
+        resolveExport: (baseDir, filePath, exportName) => {
+          apiUsed = true;
+          return getSession().api.resolveExport(baseDir, filePath, exportName);
+        },
+        isAssignableTo: (node, targetId, projection) => {
+          apiUsed = true;
+          return getSession().api.isAssignableTo(node, targetId, projection);
+        },
+      },
+      consumeDependencies: () => (apiUsed ? getSession().consumeDependencies() : ([] as const)),
+    };
+  };
+
+  return createTypeInfoApiSessionFn;
+}

package/src/LanguageServiceTester.integration.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Integration test using @manuth/typescript-languageservice-tester.
+ * Validates that the LS tester harness runs against a real tsserver workspace.
+ * Full virtual-module resolution in tsserver would require a TypeScript plugin
+ * that attaches our adapter (TS-4 / TS-12); the in-memory test in LanguageServiceAdapter.test.ts
+ * covers resolution and diagnostics with ts.createLanguageService + adapter.
+ *
+ * Additional in-process integration tests validate load, build, and import of virtual
+ * modules with the real TypeScript language service and compiler (real temp dirs, real hosts).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import ts from "typescript";
+import { afterEach, describe, expect, it } from "vitest";
+import { LanguageServiceTester } from "@manuth/typescript-languageservice-tester";
+import { attachCompilerHostAdapter } from "./CompilerHostAdapter.js";
+import { attachLanguageServiceAdapter } from "./LanguageServiceAdapter.js";
+import { NodeModulePluginLoader } from "./NodeModulePluginLoader.js";
+import { PluginManager } from "./PluginManager.js";
+
+const tempDirs: string[] = [];
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "typed-vm-lstester-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+const standardCompilerOptions: ts.CompilerOptions = {
+  strict: true,
+  noEmit: true,
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  skipLibCheck: true,
+};
+
+function createProjectWithVirtualEntry(dir: string, entryContent: string): { entryPath: string } {
+  writeFileSync(
+    join(dir, "tsconfig.json"),
+    JSON.stringify({
+      compilerOptions: {
+        strict: true,
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        noEmit: true,
+        skipLibCheck: true,
+      },
+      include: ["*.ts"],
+    }),
+    "utf8",
+  );
+  const entryPath = join(dir, "entry.ts");
+  writeFileSync(entryPath, entryContent, "utf8");
+  return { entryPath };
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+});
+
+describe("LanguageServiceTester integration", () => {
+  it("runs tsserver-backed analysis via LanguageServiceTester", { timeout: 60_000 }, async () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: {
+          strict: true,
+          target: "ESNext",
+          module: "ESNext",
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ["*.ts"],
+      }),
+      "utf8",
+    );
+    writeFileSync(join(dir, "index.ts"), "export const x = 1;\n", "utf8");
+
+    const tester = new LanguageServiceTester(dir);
+    try {
+      await tester.Install();
+      await tester.Configure();
+      const result = await tester.AnalyzeCode("export const y = 2;", "TS", "file.ts");
+      expect(result).toBeDefined();
+      expect(result.Diagnostics).toBeDefined();
+      expect(Array.isArray(result.Diagnostics)).toBe(true);
+    } finally {
+      await tester.Dispose();
+    }
+  });
+});
+
+describe("Virtual modules with real TypeScript", () => {
+  it(
+    "imports virtual module with real Language Service (host reads from disk)",
+    { timeout: 15_000 },
+    () => {
+      const dir = createTempDir();
+      const { entryPath } = createProjectWithVirtualEntry(
+        dir,
+        'import type { Foo } from "virtual:foo";\nexport const value: Foo = { n: 1 };\n',
+      );
+
+      const host: ts.LanguageServiceHost = {
+        getCompilationSettings: () => standardCompilerOptions,
+        getScriptFileNames: () => [entryPath],
+        getScriptVersion: () => "1",
+        getScriptSnapshot: (fileName: string) => {
+          const content = ts.sys.readFile(fileName);
+          return content != null ? ts.ScriptSnapshot.fromString(content) : undefined;
+        },
+        getCurrentDirectory: () => dir,
+        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+        fileExists: (fileName) => ts.sys.fileExists(fileName),
+        readFile: (fileName) => ts.sys.readFile(fileName),
+        readDirectory: (...args: Parameters<typeof ts.sys.readDirectory>) =>
+          ts.sys.readDirectory(...args),
+      };
+
+      const manager = new PluginManager([
+        {
+          name: "virtual",
+          shouldResolve: (id) => id === "virtual:foo",
+          build: () => "export interface Foo { n: number }",
+        },
+      ]);
+
+      const languageService = ts.createLanguageService(host);
+      const adapter = attachLanguageServiceAdapter({
+        ts,
+        languageService,
+        languageServiceHost: host,
+        resolver: manager,
+        projectRoot: dir,
+      });
+
+      try {
+        const diagnostics = languageService.getSemanticDiagnostics(entryPath);
+        expect(diagnostics).toHaveLength(0);
+        const program = languageService.getProgram();
+        expect(program).toBeDefined();
+        expect(program!.getSourceFiles().some((sf) => sf.fileName.includes("__virtual_"))).toBe(
+          true,
+        );
+      } finally {
+        adapter.dispose();
+      }
+    },
+  );
+
+  it(
+    "builds program that imports virtual module with real CompilerHost",
+    { timeout: 15_000 },
+    () => {
+      const dir = createTempDir();
+      const { entryPath } = createProjectWithVirtualEntry(
+        dir,
+        'import type { Foo } from "virtual:foo";\nexport const value: Foo = { n: 1 };\n',
+      );
+
+      const manager = new PluginManager([
+        {
+          name: "virtual",
+          shouldResolve: (id) => id === "virtual:foo",
+          build: () => "export interface Foo { n: number }",
+        },
+      ]);
+
+      const host = ts.createCompilerHost(standardCompilerOptions);
+      const adapter = attachCompilerHostAdapter({
+        ts,
+        compilerHost: host,
+        resolver: manager,
+        projectRoot: dir,
+      });
+
+      try {
+        const program = ts.createProgram([entryPath], standardCompilerOptions, host);
+        const diagnostics = ts.getPreEmitDiagnostics(program);
+        expect(diagnostics).toHaveLength(0);
+        expect(program.getSourceFiles().some((sf) => sf.fileName.includes("__virtual_"))).toBe(
+          true,
+        );
+      } finally {
+        adapter.dispose();
+      }
+    },
+  );
+
+  it(
+    "loads plugin from disk and resolves virtual module via Language Service",
+    { timeout: 15_000 },
+    () => {
+      const dir = createTempDir();
+      writeFileSync(
+        join(dir, "plugin.mjs"),
+        `export default {
+  name: "virtual",
+  shouldResolve: (id) => id === "virtual:foo",
+  build: () => "export interface Foo { n: number }"
+};
+`,
+        "utf8",
+      );
+      const { entryPath } = createProjectWithVirtualEntry(
+        dir,
+        'import type { Foo } from "virtual:foo";\nexport const value: Foo = { n: 1 };\n',
+      );
+
+      const loader = new NodeModulePluginLoader();
+      const loadResult = loader.load({ specifier: "./plugin.mjs", baseDir: dir });
+      expect(loadResult.status).toBe("loaded");
+      if (loadResult.status !== "loaded") return;
+
+      const manager = new PluginManager([loadResult.plugin]);
+
+      const host: ts.LanguageServiceHost = {
+        getCompilationSettings: () => standardCompilerOptions,
+        getScriptFileNames: () => [entryPath],
+        getScriptVersion: () => "1",
+        getScriptSnapshot: (fileName: string) => {
+          const content = ts.sys.readFile(fileName);
+          return content != null ? ts.ScriptSnapshot.fromString(content) : undefined;
+        },
+        getCurrentDirectory: () => dir,
+        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+        fileExists: (fileName) => ts.sys.fileExists(fileName),
+        readFile: (fileName) => ts.sys.readFile(fileName),
+        readDirectory: (...args: Parameters<typeof ts.sys.readDirectory>) =>
+          ts.sys.readDirectory(...args),
+      };
+
+      const languageService = ts.createLanguageService(host);
+      const adapter = attachLanguageServiceAdapter({
+        ts,
+        languageService,
+        languageServiceHost: host,
+        resolver: manager,
+        projectRoot: dir,
+      });
+
+      try {
+        const diagnostics = languageService.getSemanticDiagnostics(entryPath);
+        expect(diagnostics).toHaveLength(0);
+        const program = languageService.getProgram();
+        expect(program).toBeDefined();
+        expect(program!.getSourceFiles().some((sf) => sf.fileName.includes("__virtual_"))).toBe(
+          true,
+        );
+      } finally {
+        adapter.dispose();
+      }
+    },
+  );
+});

package/src/NodeModulePluginLoader.test.ts

@@ -0,0 +1,170 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { NodeModulePluginLoader } from "./NodeModulePluginLoader.js";
+
+const tempDirs: string[] = [];
+
+const createTempDir = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "typed-virtual-modules-"));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe("NodeModulePluginLoader", () => {
+  it("accepts preloaded plugin objects", () => {
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      name: "preloaded",
+      shouldResolve: () => true,
+      build: () => "export const x = 1;",
+    });
+
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+    expect(result.plugin.name).toBe("preloaded");
+  });
+
+  it("loads an ESM module by explicit path", () => {
+    const dir = createTempDir();
+    const filePath = join(dir, "plugin.mjs");
+    writeFileSync(
+      filePath,
+      `export default { name: "esm", shouldResolve: () => true, build: () => "export const esm = true;" };`,
+      "utf8",
+    );
+
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./plugin.mjs",
+      baseDir: dir,
+    });
+
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+    expect(result.plugin.name).toBe("esm");
+    expect(result.resolvedPath.endsWith("plugin.mjs")).toBe(true);
+  });
+
+  it("loads a synchronous ESM module with default export", () => {
+    const dir = createTempDir();
+    const filePath = join(dir, "plugin.mjs");
+    writeFileSync(
+      filePath,
+      `export default { name: "esm-default", shouldResolve: () => true, build: () => "export const esm = true;" };`,
+      "utf8",
+    );
+
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./plugin.mjs",
+      baseDir: dir,
+    });
+
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+    expect(result.plugin.name).toBe("esm-default");
+    expect(result.resolvedPath.endsWith("plugin.mjs")).toBe(true);
+  });
+
+  it("loads a synchronous ESM module with named plugin export", () => {
+    const dir = createTempDir();
+    const filePath = join(dir, "plugin-named.mjs");
+    writeFileSync(
+      filePath,
+      `export const plugin = { name: "esm-named", shouldResolve: () => true, build: () => "export const esm = true;" };`,
+      "utf8",
+    );
+
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./plugin-named.mjs",
+      baseDir: dir,
+    });
+
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+    expect(result.plugin.name).toBe("esm-named");
+  });
+
+  it("returns module-load-failed for async ESM (top-level await)", () => {
+    const dir = createTempDir();
+    const filePath = join(dir, "plugin-async.mjs");
+    writeFileSync(
+      filePath,
+      `await Promise.resolve(); export default { name: "esm-async", shouldResolve: () => true, build: () => "export const esm = true;" };`,
+      "utf8",
+    );
+
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./plugin-async.mjs",
+      baseDir: dir,
+    });
+
+    expect(result.status).toBe("error");
+    if (result.status !== "error") return;
+    expect(result.code).toBe("module-load-failed");
+    expect(result.message.toLowerCase()).toContain("await");
+  });
+
+  it("returns structured error for invalid exports", () => {
+    const dir = createTempDir();
+    writeFileSync(join(dir, "bad.mjs"), `export default { nope: true };`, "utf8");
+
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./bad.mjs",
+      baseDir: dir,
+    });
+
+    expect(result.status).toBe("error");
+    if (result.status !== "error") return;
+    expect(result.code).toBe("invalid-plugin-export");
+  });
+
+  it("returns invalid-request for empty baseDir", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "p.mjs"),
+      `export default { name: "p", shouldResolve: () => true, build: () => "" };`,
+      "utf8",
+    );
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({ specifier: "./p.mjs", baseDir: "" });
+    expect(result.status).toBe("error");
+    if (result.status !== "error") return;
+    expect(result.code).toBe("invalid-request");
+  });
+
+  it("returns invalid-request for empty specifier", () => {
+    const dir = createTempDir();
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({ specifier: "", baseDir: dir });
+    expect(result.status).toBe("error");
+    if (result.status !== "error") return;
+    expect(result.code).toBe("invalid-request");
+  });
+
+  it("returns module-not-found for non-existent specifier", () => {
+    const dir = createTempDir();
+    const loader = new NodeModulePluginLoader();
+    const result = loader.load({
+      specifier: "./does-not-exist-12345.mjs",
+      baseDir: dir,
+    });
+    expect(result.status).toBe("error");
+    if (result.status !== "error") return;
+    expect(result.code).toBe("module-not-found");
+  });
+});