@typed/virtual-modules 1.0.0-beta.1

package/src/NodeModulePluginLoader.ts

@@ -0,0 +1,268 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { runInThisContext } from "node:vm";
+import type {
+  NodeModulePluginLoadError,
+  NodeModulePluginLoadInput,
+  NodeModulePluginLoadResult,
+  NodeModulePluginRequest,
+  VirtualModulePlugin,
+} from "./types.js";
+export type { NodeModulePluginLoadInput };
+import { pathIsUnderBase } from "./internal/path.js";
+import { sanitizeErrorMessage } from "./internal/sanitize.js";
+
+const toMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+const isPluginLike = (value: unknown): value is VirtualModulePlugin => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.name === "string" &&
+    typeof candidate.shouldResolve === "function" &&
+    typeof candidate.build === "function"
+  );
+};
+
+const invalidPluginError = (
+  request: NodeModulePluginRequest,
+  message: string,
+): NodeModulePluginLoadError => ({
+  status: "error",
+  specifier: request.specifier,
+  baseDir: request.baseDir,
+  code: "invalid-plugin-export",
+  message,
+});
+
+const loadFailedError = (
+  request: NodeModulePluginRequest,
+  message: string,
+): NodeModulePluginLoadError => ({
+  status: "error",
+  specifier: request.specifier,
+  baseDir: request.baseDir,
+  code: "module-load-failed",
+  message,
+});
+
+const notFoundError = (
+  request: NodeModulePluginRequest,
+  message: string,
+): NodeModulePluginLoadError => ({
+  status: "error",
+  specifier: request.specifier,
+  baseDir: request.baseDir,
+  code: "module-not-found",
+  message,
+});
+
+const pathEscapesError = (
+  request: NodeModulePluginRequest,
+  message: string,
+): NodeModulePluginLoadError => ({
+  status: "error",
+  specifier: request.specifier,
+  baseDir: request.baseDir,
+  code: "path-escapes-base",
+  message,
+});
+
+const MAX_PATH_LENGTH = 4096;
+
+const invalidRequestError = (message: string): NodeModulePluginLoadError => ({
+  status: "error",
+  specifier: "",
+  baseDir: "",
+  code: "invalid-request",
+  message,
+});
+
+const getErrorCode = (error: unknown): string | undefined =>
+  typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+
+export class NodeModulePluginLoader {
+  load(input: NodeModulePluginLoadInput): NodeModulePluginLoadResult {
+    if (isPluginLike(input)) {
+      return {
+        status: "loaded",
+        plugin: input,
+        resolvedPath: "<preloaded>",
+      };
+    }
+
+    const request = input;
+    if (typeof request.baseDir !== "string" || request.baseDir.trim() === "") {
+      return invalidRequestError("baseDir must be a non-empty string");
+    }
+    if (typeof request.specifier !== "string" || request.specifier.trim() === "") {
+      return invalidRequestError("specifier must be a non-empty string");
+    }
+    if (request.baseDir.length > MAX_PATH_LENGTH || request.specifier.length > MAX_PATH_LENGTH) {
+      return invalidRequestError(
+        `baseDir and specifier must be at most ${MAX_PATH_LENGTH} characters`,
+      );
+    }
+
+    const require = createRequire(resolve(request.baseDir, "__typed_virtual_modules_loader__.cjs"));
+    let resolvedPath: string;
+
+    try {
+      resolvedPath = require.resolve(request.specifier, { paths: [request.baseDir] });
+    } catch (error) {
+      return notFoundError(
+        request,
+        `Could not resolve plugin "${request.specifier}" from "${request.baseDir}": ${sanitizeErrorMessage(toMessage(error))}`,
+      );
+    }
+
+    if (!pathIsUnderBase(request.baseDir, resolvedPath)) {
+      return pathEscapesError(
+        request,
+        sanitizeErrorMessage(
+          `Resolved plugin path "${resolvedPath}" is not under baseDir "${request.baseDir}"`,
+        ),
+      );
+    }
+
+    let mod: unknown;
+    try {
+      mod = require(resolvedPath) as unknown;
+    } catch (error) {
+      const errorCode = getErrorCode(error);
+      if (errorCode === "ERR_REQUIRE_ASYNC_MODULE") {
+        return loadFailedError(
+          request,
+          sanitizeErrorMessage(
+            `Could not load plugin module "${resolvedPath}": plugin module uses top-level await and cannot be loaded synchronously`,
+          ),
+        );
+      }
+      if (errorCode === "ERR_REQUIRE_ESM") {
+        const esmFallback = this.#loadSyncEsmModule(resolvedPath, require);
+        if (esmFallback.status === "loaded") {
+          mod = esmFallback.moduleExport;
+        } else {
+          return loadFailedError(request, esmFallback.message);
+        }
+      } else {
+        return loadFailedError(
+          request,
+          `Could not load plugin module "${resolvedPath}": ${sanitizeErrorMessage(toMessage(error))}`,
+        );
+      }
+    }
+
+    const normalizedPlugin = this.#normalizeModuleExport(mod);
+    if (!normalizedPlugin) {
+      return invalidPluginError(
+        request,
+        sanitizeErrorMessage(
+          `Resolved module "${resolvedPath}" does not export a valid VirtualModulePlugin`,
+        ),
+      );
+    }
+
+    return {
+      status: "loaded",
+      plugin: normalizedPlugin,
+      resolvedPath,
+    };
+  }
+
+  loadMany(inputs: readonly NodeModulePluginLoadInput[]): readonly NodeModulePluginLoadResult[] {
+    return inputs.map((input) => this.load(input));
+  }
+
+  #loadSyncEsmModule(
+    resolvedPath: string,
+    localRequire: NodeJS.Require,
+  ):
+    | { readonly status: "loaded"; readonly moduleExport: unknown }
+    | { readonly status: "error"; readonly message: string } {
+    let tsMod: typeof import("typescript");
+    try {
+      tsMod = localRequire("typescript") as typeof import("typescript");
+    } catch (error) {
+      return loadFailedError(
+        { specifier: resolvedPath, baseDir: dirname(resolvedPath) },
+        sanitizeErrorMessage(
+          `Could not load sync ESM plugin "${resolvedPath}": failed to load TypeScript for transpilation: ${toMessage(error)}`,
+        ),
+      );
+    }
+
+    try {
+      const sourceText = readFileSync(resolvedPath, "utf8");
+      const transpiled = tsMod.transpileModule(sourceText, {
+        fileName: resolvedPath,
+        compilerOptions: {
+          module: tsMod.ModuleKind.CommonJS,
+          target: tsMod.ScriptTarget.ES2020,
+          moduleResolution: tsMod.ModuleResolutionKind.NodeNext,
+          esModuleInterop: true,
+          allowSyntheticDefaultImports: true,
+        },
+        reportDiagnostics: false,
+      }).outputText;
+
+      const module = { exports: {} as unknown };
+      const evaluate = runInThisContext(
+        `(function (exports, require, module, __filename, __dirname) {${transpiled}\n})`,
+        { filename: resolvedPath },
+      ) as (
+        exportsObject: unknown,
+        requireFn: NodeJS.Require,
+        moduleObject: { exports: unknown },
+        filename: string,
+        dirname: string,
+      ) => void;
+      evaluate(module.exports, localRequire, module, resolvedPath, dirname(resolvedPath));
+
+      return { status: "loaded", moduleExport: module.exports };
+    } catch (error) {
+      return {
+        status: "error",
+        message: sanitizeErrorMessage(
+          `Could not load sync ESM plugin "${resolvedPath}": ${toMessage(error)}`,
+        ),
+      };
+    }
+  }
+
+  #normalizeModuleExport(mod: unknown): VirtualModulePlugin | undefined {
+    if (isPluginLike(mod)) {
+      return mod;
+    }
+
+    if (!mod || typeof mod !== "object") {
+      return undefined;
+    }
+
+    const candidate = mod as {
+      default?: unknown;
+      plugin?: unknown;
+    };
+
+    if (isPluginLike(candidate.default)) {
+      return candidate.default;
+    }
+
+    if (isPluginLike(candidate.plugin)) {
+      return candidate.plugin;
+    }
+
+    return undefined;
+  }
+}

package/src/PluginManager.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it, vi } from "vitest";
+import { PluginManager } from "./PluginManager.js";
+
+describe("PluginManager", () => {
+  it("uses first matching plugin only", () => {
+    const firstBuild = vi.fn(() => "export const value = 1;");
+    const secondBuild = vi.fn(() => "export const value = 2;");
+
+    const manager = new PluginManager([
+      {
+        name: "first",
+        shouldResolve: () => true,
+        build: firstBuild,
+      },
+      {
+        name: "second",
+        shouldResolve: () => true,
+        build: secondBuild,
+      },
+    ]);
+
+    const resolved = manager.resolveModule({
+      id: "virtual:test",
+      importer: "/project/src/main.ts",
+    });
+
+    expect(resolved.status).toBe("resolved");
+    if (resolved.status !== "resolved") return;
+    expect(resolved.pluginName).toBe("first");
+    expect(firstBuild).toHaveBeenCalledTimes(1);
+    expect(secondBuild).toHaveBeenCalledTimes(0);
+  });
+
+  it("returns unresolved when no plugin matches", () => {
+    const manager = new PluginManager([
+      {
+        name: "noop",
+        shouldResolve: () => false,
+        build: () => "export {};",
+      },
+    ]);
+
+    expect(
+      manager.resolveModule({
+        id: "virtual:none",
+        importer: "/project/src/main.ts",
+      }),
+    ).toEqual({ status: "unresolved" });
+  });
+
+  it("returns structured error when shouldResolve throws", () => {
+    const manager = new PluginManager([
+      {
+        name: "broken",
+        shouldResolve: () => {
+          throw new Error("explode");
+        },
+        build: () => "export {};",
+      },
+    ]);
+
+    const resolved = manager.resolveModule({
+      id: "virtual:bad",
+      importer: "/project/src/main.ts",
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("plugin-should-resolve-threw");
+    expect(resolved.diagnostic.message).toContain("explode");
+  });
+
+  it("returns invalid-options for empty id", () => {
+    const manager = new PluginManager([
+      { name: "any", shouldResolve: () => true, build: () => "export {};" },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "",
+      importer: "/project/src/main.ts",
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("invalid-options");
+    expect(resolved.diagnostic.message).toContain("id");
+  });
+
+  it("returns invalid-options for empty importer", () => {
+    const manager = new PluginManager([
+      { name: "any", shouldResolve: () => true, build: () => "export {};" },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "virtual:x",
+      importer: "",
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("invalid-options");
+    expect(resolved.diagnostic.message).toContain("importer");
+  });
+
+  it("returns invalid-options when a plugin has empty name", () => {
+    const manager = new PluginManager([
+      { name: "", shouldResolve: () => true, build: () => "export {};" },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "virtual:x",
+      importer: "/project/src/main.ts",
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("invalid-options");
+    expect(resolved.diagnostic.message).toContain("Plugin name");
+  });
+
+  it("returns plugin-build-threw when plugin build() throws", () => {
+    const manager = new PluginManager([
+      {
+        name: "throws",
+        shouldResolve: () => true,
+        build: () => {
+          throw new Error("build exploded");
+        },
+      },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "virtual:x",
+      importer: "/project/src/main.ts",
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("plugin-build-threw");
+    expect(resolved.diagnostic.message).toContain("build exploded");
+  });
+
+  it("returns invalid-build-output when plugin returns non-string", () => {
+    const manager = new PluginManager([
+      {
+        name: "bad-return",
+        shouldResolve: () => true,
+        build: () => null as unknown as string,
+      },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "virtual:x",
+      importer: "/project/src/main.ts",
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("invalid-build-output");
+  });
+
+  it("returns unresolved when plugin list is empty", () => {
+    const manager = new PluginManager([]);
+    const resolved = manager.resolveModule({
+      id: "virtual:any",
+      importer: "/project/src/main.ts",
+    });
+    expect(resolved.status).toBe("unresolved");
+  });
+
+  it("returns session-creation-failed when createTypeInfoApiSession throws", () => {
+    const manager = new PluginManager([
+      { name: "needs-session", shouldResolve: () => true, build: () => "export {};" },
+    ]);
+    const resolved = manager.resolveModule({
+      id: "virtual:x",
+      importer: "/project/src/main.ts",
+      createTypeInfoApiSession: () => {
+        throw new Error("session factory error");
+      },
+    });
+    expect(resolved.status).toBe("error");
+    if (resolved.status !== "error") return;
+    expect(resolved.diagnostic.code).toBe("session-creation-failed");
+    expect(resolved.diagnostic.message).toContain("Session creation failed");
+    expect(resolved.diagnostic.message).toContain("session factory error");
+  });
+});

package/src/PluginManager.ts

@@ -0,0 +1,218 @@
+import { sanitizeErrorMessage } from "./internal/sanitize.js";
+import { validateNonEmptyString } from "./internal/validation.js";
+import type {
+  ResolveVirtualModuleOptions,
+  TypeInfoApi,
+  TypeInfoApiSession,
+  VirtualModuleBuildResult,
+  VirtualModuleDiagnostic,
+  VirtualModulePlugin,
+  VirtualModuleResolution,
+  VirtualModuleResolver,
+} from "./types.js";
+import {
+  isVirtualModuleBuildError,
+  isVirtualModuleBuildSuccess,
+} from "./types.js";
+
+/**
+ * TypeInfoApi used when createTypeInfoApiSession is not provided.
+ * Returns safe defaults instead of throwing.
+ * Hosts should always supply createTypeInfoApiSession when plugins use api.file(), api.directory(), or api.resolveExport() for correct behavior.
+ */
+const noopTypeInfoApi: TypeInfoApi = {
+  file: () => ({ ok: false as const, error: "invalid-input" }),
+  directory: () => [],
+  resolveExport: () => undefined,
+  isAssignableTo: () => false,
+};
+
+const noopSession: TypeInfoApiSession = {
+  api: noopTypeInfoApi,
+  consumeDependencies: () => [],
+};
+
+const toMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+const createDiagnostic = (
+  code: VirtualModuleDiagnostic["code"],
+  pluginName: string,
+  message: string,
+): VirtualModuleDiagnostic => ({
+  code,
+  pluginName,
+  message,
+});
+
+export class PluginManager implements VirtualModuleResolver {
+  readonly #plugins: VirtualModulePlugin[];
+
+  constructor(plugins: readonly VirtualModulePlugin[] = []) {
+    this.#plugins = [...plugins];
+  }
+
+  get plugins(): readonly VirtualModulePlugin[] {
+    return this.#plugins;
+  }
+
+  register(plugin: VirtualModulePlugin): void {
+    this.#plugins.push(plugin);
+  }
+
+  registerMany(plugins: readonly VirtualModulePlugin[]): void {
+    for (const plugin of plugins) {
+      this.register(plugin);
+    }
+  }
+
+  resolveModule(options: ResolveVirtualModuleOptions): VirtualModuleResolution {
+    const idResult = validateNonEmptyString(options.id, "options.id");
+    if (!idResult.ok) {
+      return {
+        status: "error",
+        diagnostic: createDiagnostic("invalid-options", "", idResult.reason),
+      };
+    }
+    const importerResult = validateNonEmptyString(options.importer, "options.importer");
+    if (!importerResult.ok) {
+      return {
+        status: "error",
+        diagnostic: createDiagnostic("invalid-options", "", importerResult.reason),
+      };
+    }
+
+    const createSession = options.createTypeInfoApiSession;
+
+    for (const plugin of this.#plugins) {
+      const nameResult = validateNonEmptyString(plugin.name, "Plugin name");
+      if (!nameResult.ok) {
+        return {
+          status: "error",
+          diagnostic: createDiagnostic("invalid-options", "", nameResult.reason),
+        };
+      }
+      const shouldResolve = this.#safeShouldResolve(plugin, options.id, options.importer);
+
+      if (shouldResolve.status === "error") {
+        return shouldResolve;
+      }
+
+      if (!shouldResolve.value) {
+        continue;
+      }
+
+      let session: TypeInfoApiSession;
+      try {
+        session = createSession?.({ id: options.id, importer: options.importer }) ?? noopSession;
+      } catch (error) {
+        const msg = toMessage(error);
+        // Treat temporary unavailability (e.g. program not loaded) as unresolved so retry can succeed later.
+        if (
+          msg.includes("Program not yet available") ||
+          msg.includes("TypeInfo session creation failed")
+        ) {
+          continue;
+        }
+        return {
+          status: "error",
+          diagnostic: createDiagnostic(
+            "session-creation-failed",
+            plugin.name,
+            `Session creation failed: ${sanitizeErrorMessage(msg)}`,
+          ),
+        };
+      }
+
+      try {
+        const result: VirtualModuleBuildResult = plugin.build(
+          options.id,
+          options.importer,
+          session.api,
+        );
+
+        if (typeof result === "string") {
+          return {
+            status: "resolved",
+            pluginName: plugin.name,
+            sourceText: result,
+            dependencies: session.consumeDependencies(),
+          };
+        }
+
+        if (isVirtualModuleBuildError(result)) {
+          const first = result.errors[0];
+          const diagnostic: VirtualModuleDiagnostic =
+            first &&
+            typeof first === "object" &&
+            typeof first.code === "string" &&
+            typeof first.message === "string" &&
+            typeof first.pluginName === "string"
+              ? first
+              : createDiagnostic(
+                  "invalid-build-output",
+                  plugin.name,
+                  `Plugin "${plugin.name}" returned errors with invalid diagnostic shape`,
+                );
+          return { status: "error", diagnostic };
+        }
+
+        if (isVirtualModuleBuildSuccess(result)) {
+          return {
+            status: "resolved",
+            pluginName: plugin.name,
+            sourceText: result.sourceText,
+            dependencies: session.consumeDependencies(),
+            ...(result.warnings?.length ? { warnings: result.warnings } : {}),
+          };
+        }
+
+        return {
+          status: "error",
+          diagnostic: createDiagnostic(
+            "invalid-build-output",
+            plugin.name,
+            `Plugin "${plugin.name}" returned a non-string build result`,
+          ),
+        };
+      } catch (error) {
+        return {
+          status: "error",
+          diagnostic: createDiagnostic(
+            "plugin-build-threw",
+            plugin.name,
+            `Plugin "${plugin.name}" build failed: ${sanitizeErrorMessage(toMessage(error))}`,
+          ),
+        };
+      }
+    }
+
+    return { status: "unresolved" };
+  }
+
+  #safeShouldResolve(
+    plugin: VirtualModulePlugin,
+    id: string,
+    importer: string,
+  ): { status: "ok"; value: boolean } | { status: "error"; diagnostic: VirtualModuleDiagnostic } {
+    try {
+      return {
+        status: "ok",
+        value: plugin.shouldResolve(id, importer),
+      };
+    } catch (error) {
+      return {
+        status: "error",
+        diagnostic: createDiagnostic(
+          "plugin-should-resolve-threw",
+          plugin.name,
+          `Plugin "${plugin.name}" shouldResolve failed: ${sanitizeErrorMessage(toMessage(error))}`,
+        ),
+      };
+    }
+  }
+}