@typed/virtual-modules 1.0.0-beta.1

package/src/VmcConfigLoader.test.ts

@@ -0,0 +1,108 @@
+import { mkdirSync, 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 { loadVmcConfig } from "./VmcConfigLoader.js";
+
+const tempDirs: string[] = [];
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "typed-vmc-config-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore cleanup failures in test temp dirs
+      }
+    }
+  }
+});
+
+describe("loadVmcConfig", () => {
+  it("returns not-found when vmc config does not exist", () => {
+    const dir = createTempDir();
+    const result = loadVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("not-found");
+  });
+
+  it("loads vmc.config.ts with default export", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "vmc.config.ts"),
+      `const plugin = {
+  name: "virtual",
+  shouldResolve: (id) => id === "virtual:foo",
+  build: () => "export const value = 1;",
+};
+
+export default {
+  plugins: [plugin, "./plugin.mjs"],
+};
+`,
+      "utf8",
+    );
+
+    const result = loadVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+    expect(result.path.endsWith("vmc.config.ts")).toBe(true);
+    expect(result.config.plugins).toBeDefined();
+    expect(result.config.plugins).toHaveLength(2);
+    const first = result.config.plugins?.[0];
+    const second = result.config.plugins?.[1];
+    expect(typeof first).toBe("object");
+    expect(typeof second).toBe("string");
+  });
+
+  it("returns error when configPath is not a string", () => {
+    const dir = createTempDir();
+    const result = loadVmcConfig({
+      projectRoot: dir,
+      ts,
+      configPath: 123 as unknown as string,
+    });
+    expect(result.status).toBe("error");
+    if (result.status === "error") {
+      expect(result.message).toContain("configPath must be a string");
+    }
+  });
+
+  it("returns error when configPath is not a .ts file", () => {
+    const dir = createTempDir();
+    writeFileSync(join(dir, "vmc.config.mjs"), `export default { plugins: [] };`, "utf8");
+    const result = loadVmcConfig({
+      projectRoot: dir,
+      ts,
+      configPath: "./vmc.config.mjs",
+    });
+    expect(result.status).toBe("error");
+    if (result.status === "error") {
+      expect(result.message).toContain(".ts");
+    }
+  });
+
+  it("returns error when configPath is a directory", () => {
+    const dir = createTempDir();
+    const configDir = join(dir, "vmc.config.ts");
+    mkdirSync(configDir, { recursive: true });
+    const result = loadVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("not-found");
+    const explicit = loadVmcConfig({
+      projectRoot: dir,
+      ts,
+      configPath: "./vmc.config.ts",
+    });
+    expect(explicit.status).toBe("error");
+    if (explicit.status === "error") {
+      expect(explicit.message).toContain("must point to a file");
+    }
+  });
+});

package/src/VmcConfigLoader.ts

@@ -0,0 +1,297 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { runInThisContext } from "node:vm";
+import { pathIsUnderBase, resolvePathUnderBase } from "./internal/path.js";
+import { sanitizeErrorMessage } from "./internal/sanitize.js";
+import { validatePathSegment } from "./internal/validation.js";
+import type { VirtualModulePlugin, VirtualModuleResolver } from "./types.js";
+
+const VMC_CONFIG_NAMES = ["vmc.config.ts"] as const;
+
+export type VmcPluginEntry = VirtualModulePlugin | string;
+
+export interface VmcConfig {
+  readonly resolver?: VirtualModuleResolver;
+  readonly plugins?: readonly VmcPluginEntry[];
+}
+
+export interface LoadVmcConfigOptions {
+  readonly projectRoot: string;
+  /**
+   * TypeScript module used to transpile vmc.config.ts on the fly.
+   * Required only when loading .ts configs.
+   */
+  readonly ts?: typeof import("typescript");
+  /**
+   * Optional explicit config file path (absolute or relative to projectRoot).
+   */
+  readonly configPath?: string;
+}
+
+export type LoadVmcConfigResult =
+  | { readonly status: "not-found" }
+  | { readonly status: "loaded"; readonly path: string; readonly config: VmcConfig }
+  | { readonly status: "error"; readonly path?: string; readonly message: string };
+
+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 isResolverLike = (value: unknown): value is VirtualModuleResolver => {
+  if (!value || typeof value !== "object") return false;
+  return typeof (value as { resolveModule?: unknown }).resolveModule === "function";
+};
+
+const normalizePluginEntries = (
+  value: unknown,
+): { readonly ok: true; readonly plugins: readonly VmcPluginEntry[] } | { readonly ok: false } => {
+  if (value === undefined) return { ok: true, plugins: [] };
+  if (!Array.isArray(value)) return { ok: false };
+
+  const plugins: VmcPluginEntry[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string" && entry.trim().length > 0) {
+      plugins.push(entry.trim());
+      continue;
+    }
+    if (isPluginLike(entry)) {
+      plugins.push(entry);
+      continue;
+    }
+    return { ok: false };
+  }
+  return { ok: true, plugins };
+};
+
+function validateProjectRoot(projectRoot: unknown): LoadVmcConfigResult | string {
+  const projectRootResult = validatePathSegment(projectRoot, "projectRoot");
+  if (!projectRootResult.ok) {
+    return {
+      status: "error",
+      message: projectRootResult.reason,
+    };
+  }
+  const resolvedProjectRoot = resolve(projectRootResult.value);
+  if (!existsSync(resolvedProjectRoot)) {
+    return {
+      status: "error",
+      path: resolvedProjectRoot,
+      message: `projectRoot does not exist: ${resolvedProjectRoot}`,
+    };
+  }
+  if (!statSync(resolvedProjectRoot).isDirectory()) {
+    return {
+      status: "error",
+      path: resolvedProjectRoot,
+      message: `projectRoot must be a directory: ${resolvedProjectRoot}`,
+    };
+  }
+  return resolvedProjectRoot;
+}
+
+function resolveConfigPath(
+  projectRoot: string,
+  configPath?: unknown,
+): LoadVmcConfigResult | string {
+  if (configPath !== undefined) {
+    const configPathResult = validatePathSegment(configPath, "configPath");
+    if (!configPathResult.ok) {
+      return {
+        status: "error",
+        message: configPathResult.reason,
+      };
+    }
+
+    const configPathValue = configPathResult.value;
+    if (!configPathValue.endsWith(".ts")) {
+      return {
+        status: "error",
+        message: `configPath must point to a .ts file: ${configPathValue}`,
+      };
+    }
+    const resolvedPath = resolve(projectRoot, configPathValue);
+    const underBase = resolvePathUnderBase(projectRoot, configPathValue);
+    if (!underBase.ok || resolve(underBase.path) !== resolvedPath) {
+      return {
+        status: "error",
+        message: `vmc config path escapes project root: ${configPathValue}`,
+      };
+    }
+    if (!existsSync(resolvedPath)) {
+      return {
+        status: "error",
+        path: resolvedPath,
+        message: `vmc config not found: ${resolvedPath}`,
+      };
+    }
+    if (!statSync(resolvedPath).isFile()) {
+      return {
+        status: "error",
+        path: resolvedPath,
+        message: `vmc config path must point to a file: ${resolvedPath}`,
+      };
+    }
+    if (!pathIsUnderBase(projectRoot, resolvedPath)) {
+      return {
+        status: "error",
+        path: resolvedPath,
+        message: `vmc config path is outside project root after resolving symlinks: ${resolvedPath}`,
+      };
+    }
+    return resolvedPath;
+  }
+
+  for (const name of VMC_CONFIG_NAMES) {
+    const candidate = join(projectRoot, name);
+    if (!existsSync(candidate)) continue;
+    if (!statSync(candidate).isFile()) continue;
+    if (!pathIsUnderBase(projectRoot, candidate)) {
+      return {
+        status: "error",
+        path: candidate,
+        message: `vmc config is outside project root after resolving symlinks: ${candidate}`,
+      };
+    }
+    return candidate;
+  }
+  return { status: "not-found" };
+}
+
+function loadTsConfigModule(tsMod: typeof import("typescript"), configPath: string): unknown {
+  // vmc config is executable project code.
+  const sourceText = readFileSync(configPath, "utf8");
+  const transpiled = tsMod.transpileModule(sourceText, {
+    fileName: configPath,
+    compilerOptions: {
+      module: tsMod.ModuleKind.CommonJS,
+      target: tsMod.ScriptTarget.ES2020,
+      moduleResolution: tsMod.ModuleResolutionKind.NodeNext,
+      esModuleInterop: true,
+    },
+    reportDiagnostics: false,
+  }).outputText;
+
+  const localRequire = createRequire(configPath);
+  const module = { exports: {} as unknown };
+  const evaluate = runInThisContext(
+    `(function (exports, require, module, __filename, __dirname) {${transpiled}\n})`,
+    { filename: configPath },
+  ) as (
+    exportsObject: unknown,
+    requireFn: NodeJS.Require,
+    moduleObject: { exports: unknown },
+    filename: string,
+    dirname: string,
+  ) => void;
+
+  evaluate(module.exports, localRequire, module, configPath, dirname(configPath));
+  return module.exports;
+}
+
+function normalizeConfigModule(
+  loadedModule: unknown,
+): { readonly ok: true; readonly config: VmcConfig } | { readonly ok: false } {
+  const withDefault =
+    loadedModule && typeof loadedModule === "object" && "default" in loadedModule
+      ? (loadedModule as { default: unknown }).default
+      : loadedModule;
+
+  if (!withDefault || typeof withDefault !== "object") {
+    return { ok: false };
+  }
+
+  const candidate = withDefault as {
+    resolver?: unknown;
+    plugins?: unknown;
+  };
+
+  if (candidate.resolver !== undefined && !isResolverLike(candidate.resolver)) {
+    return { ok: false };
+  }
+  const normalizedPlugins = normalizePluginEntries(candidate.plugins);
+  if (!normalizedPlugins.ok) {
+    return { ok: false };
+  }
+
+  return {
+    ok: true,
+    config: {
+      ...(candidate.resolver !== undefined
+        ? { resolver: candidate.resolver as VirtualModuleResolver }
+        : {}),
+      ...(normalizedPlugins.plugins.length > 0 ? { plugins: normalizedPlugins.plugins } : {}),
+    },
+  };
+}
+
+export function loadVmcConfig(options: LoadVmcConfigOptions): LoadVmcConfigResult {
+  let attemptedPath: string | undefined;
+  try {
+    const projectRootOrStatus = validateProjectRoot(options.projectRoot);
+    if (typeof projectRootOrStatus !== "string") return projectRootOrStatus;
+    const projectRoot = projectRootOrStatus;
+
+    const resolvedPathOrStatus = resolveConfigPath(projectRoot, options.configPath);
+    if (typeof resolvedPathOrStatus !== "string") return resolvedPathOrStatus;
+    const resolvedPath = resolvedPathOrStatus;
+    attemptedPath = resolvedPath;
+
+    const loadedModule = resolvedPath.endsWith(".ts")
+      ? (() => {
+          if (!options.ts) {
+            return {
+              __vmcConfigLoaderError: "TypeScript module is required to load vmc.config.ts",
+            };
+          }
+          return loadTsConfigModule(options.ts, resolvedPath);
+        })()
+      : createRequire(resolvedPath)(resolvedPath);
+
+    if (
+      loadedModule &&
+      typeof loadedModule === "object" &&
+      "__vmcConfigLoaderError" in loadedModule
+    ) {
+      return {
+        status: "error",
+        path: resolvedPath,
+        message: (loadedModule as { __vmcConfigLoaderError: string }).__vmcConfigLoaderError,
+      };
+    }
+
+    const normalized = normalizeConfigModule(loadedModule);
+    if (!normalized.ok) {
+      return {
+        status: "error",
+        path: resolvedPath,
+        message: `Invalid vmc config export in ${resolvedPath}`,
+      };
+    }
+
+    return {
+      status: "loaded",
+      path: resolvedPath,
+      config: normalized.config,
+    };
+  } catch (error) {
+    return {
+      status: "error",
+      ...(attemptedPath ? { path: attemptedPath } : {}),
+      message: sanitizeErrorMessage(
+        `Failed to load vmc config${attemptedPath ? ` "${attemptedPath}"` : ""}: ${toMessage(error)}`,
+      ),
+    };
+  }
+}

package/src/VmcResolverLoader.test.ts

@@ -0,0 +1,181 @@
+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 { loadResolverFromVmcConfig } from "./VmcResolverLoader.js";
+
+const tempDirs: string[] = [];
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "typed-vmc-resolver-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore cleanup failures in test temp dirs
+      }
+    }
+  }
+});
+
+describe("loadResolverFromVmcConfig", () => {
+  it("returns not-found when vmc config is missing", () => {
+    const dir = createTempDir();
+    const result = loadResolverFromVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("not-found");
+  });
+
+  it("uses exported resolver directly when provided", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "vmc.config.ts"),
+      `const resolver = {
+  resolveModule: () => ({ status: "unresolved" }),
+};
+
+export default {
+  resolver,
+  plugins: ["./missing-plugin.cjs"],
+};
+`,
+      "utf8",
+    );
+
+    const result = loadResolverFromVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+
+    expect(result.resolver).toBeDefined();
+    expect(result.pluginSpecifiers).toEqual(["./missing-plugin.cjs"]);
+    expect(result.pluginLoadErrors).toHaveLength(0);
+  });
+
+  it("collects typeTargetSpecs from plugins when they declare them", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "file-plugin.cjs"),
+      `module.exports = {
+  name: "file-plugin",
+  typeTargetSpecs: [
+    { id: "Route", module: "@typed/router", exportName: "Route" },
+    { id: "Effect", module: "effect", exportName: "Effect" },
+  ],
+  shouldResolve(id) {
+    return id === "virtual:file";
+  },
+  build() {
+    return "export const fileValue = 1;";
+  },
+};
+`,
+      "utf8",
+    );
+    writeFileSync(
+      join(dir, "vmc.config.ts"),
+      `export default {
+  plugins: ["./file-plugin.cjs"],
+};
+`,
+      "utf8",
+    );
+
+    const result = loadResolverFromVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+
+    expect(result.typeTargetSpecs).toBeDefined();
+    expect(result.typeTargetSpecs).toHaveLength(2);
+    expect(result.typeTargetSpecs?.[0]).toEqual({
+      id: "Route",
+      module: "@typed/router",
+      exportName: "Route",
+    });
+  });
+
+  it("builds a plugin-manager resolver from plugin entries", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "file-plugin.cjs"),
+      `module.exports = {
+  name: "file-plugin",
+  shouldResolve(id) {
+    return id === "virtual:file";
+  },
+  build() {
+    return "export const fileValue = 1;";
+  },
+};
+`,
+      "utf8",
+    );
+    writeFileSync(
+      join(dir, "vmc.config.ts"),
+      `const inlinePlugin = {
+  name: "inline-plugin",
+  shouldResolve: (id) => id === "virtual:inline",
+  build: () => "export const inlineValue = 2;",
+};
+
+export default {
+  plugins: ["./file-plugin.cjs", inlinePlugin],
+};
+`,
+      "utf8",
+    );
+
+    const result = loadResolverFromVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+
+    expect(result.pluginSpecifiers).toEqual(["./file-plugin.cjs"]);
+    expect(result.pluginLoadErrors).toHaveLength(0);
+    expect(result.resolver).toBeDefined();
+
+    const fileResolution = result.resolver?.resolveModule({
+      id: "virtual:file",
+      importer: join(dir, "entry.ts"),
+    });
+    expect(fileResolution?.status).toBe("resolved");
+    if (fileResolution?.status === "resolved") {
+      expect(fileResolution.pluginName).toBe("file-plugin");
+    }
+
+    const inlineResolution = result.resolver?.resolveModule({
+      id: "virtual:inline",
+      importer: join(dir, "entry.ts"),
+    });
+    expect(inlineResolution?.status).toBe("resolved");
+    if (inlineResolution?.status === "resolved") {
+      expect(inlineResolution.pluginName).toBe("inline-plugin");
+    }
+  });
+
+  it("collects plugin load errors and returns no resolver when all fail", () => {
+    const dir = createTempDir();
+    writeFileSync(
+      join(dir, "vmc.config.ts"),
+      `export default {
+  plugins: ["./missing-plugin.cjs"],
+};
+`,
+      "utf8",
+    );
+
+    const result = loadResolverFromVmcConfig({ projectRoot: dir, ts });
+    expect(result.status).toBe("loaded");
+    if (result.status !== "loaded") return;
+
+    expect(result.resolver).toBeUndefined();
+    expect(result.pluginSpecifiers).toEqual(["./missing-plugin.cjs"]);
+    expect(result.pluginLoadErrors).toHaveLength(1);
+    expect(result.pluginLoadErrors[0]?.code).toBe("module-not-found");
+  });
+});

package/src/VmcResolverLoader.ts

@@ -0,0 +1,116 @@
+import { dirname } from "node:path";
+import { collectTypeTargetSpecsFromPlugins } from "./collectTypeTargetSpecs.js";
+import { NodeModulePluginLoader } from "./NodeModulePluginLoader.js";
+import { PluginManager } from "./PluginManager.js";
+import { loadVmcConfig } from "./VmcConfigLoader.js";
+import type { VmcPluginEntry } from "./VmcConfigLoader.js";
+import type {
+  NodeModulePluginLoadError,
+  TypeTargetSpec,
+  VirtualModulePlugin,
+  VirtualModuleResolver,
+} from "./types.js";
+
+function collectFromResolver(resolver: VirtualModuleResolver): readonly TypeTargetSpec[] | undefined {
+  const pm = resolver as { plugins?: readonly VirtualModulePlugin[] };
+  if (!Array.isArray(pm.plugins) || pm.plugins.length === 0) return undefined;
+  const merged = collectTypeTargetSpecsFromPlugins(pm.plugins);
+  return merged.length > 0 ? merged : undefined;
+}
+
+export interface LoadPluginsFromEntriesResult {
+  readonly plugins: readonly VirtualModulePlugin[];
+  readonly pluginSpecifiers: readonly string[];
+  readonly errors: readonly NodeModulePluginLoadError[];
+}
+
+export function loadPluginsFromEntries(
+  entries: readonly VmcPluginEntry[],
+  baseDir: string,
+): LoadPluginsFromEntriesResult {
+  const loader = new NodeModulePluginLoader();
+  const plugins: VirtualModulePlugin[] = [];
+  const pluginSpecifiers: string[] = [];
+  const errors: NodeModulePluginLoadError[] = [];
+
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      pluginSpecifiers.push(entry);
+      const loaded = loader.load({ specifier: entry, baseDir });
+      if (loaded.status === "loaded") {
+        plugins.push(loaded.plugin);
+      } else {
+        errors.push(loaded);
+      }
+      continue;
+    }
+
+    plugins.push(entry);
+  }
+
+  return {
+    plugins,
+    pluginSpecifiers,
+    errors,
+  };
+}
+
+export type LoadResolverFromVmcConfigResult =
+  | { readonly status: "not-found" }
+  | { readonly status: "error"; readonly path?: string; readonly message: string }
+  | {
+      readonly status: "loaded";
+      readonly path: string;
+      readonly resolver?: VirtualModuleResolver;
+      readonly pluginSpecifiers: readonly string[];
+      readonly pluginLoadErrors: readonly NodeModulePluginLoadError[];
+      /** Type target specs from config for structural assignability in TypeInfo API. */
+      readonly typeTargetSpecs?: readonly TypeTargetSpec[];
+    };
+
+export interface LoadResolverFromVmcConfigOptions {
+  readonly projectRoot: string;
+  readonly ts: typeof import("typescript");
+  readonly configPath?: string;
+}
+
+export function loadResolverFromVmcConfig(
+  options: LoadResolverFromVmcConfigOptions,
+): LoadResolverFromVmcConfigResult {
+  const loadedVmcConfig = loadVmcConfig(options);
+  if (loadedVmcConfig.status === "not-found") {
+    return loadedVmcConfig;
+  }
+  if (loadedVmcConfig.status === "error") {
+    return loadedVmcConfig;
+  }
+
+  const vmcPlugins = loadedVmcConfig.config.plugins ?? [];
+  const pluginSpecifiers = vmcPlugins.filter((entry): entry is string => typeof entry === "string");
+
+  if (loadedVmcConfig.config.resolver) {
+    const resolver = loadedVmcConfig.config.resolver;
+    const typeTargetSpecs = collectFromResolver(resolver);
+    return {
+      status: "loaded",
+      path: loadedVmcConfig.path,
+      resolver,
+      pluginSpecifiers,
+      pluginLoadErrors: [],
+      ...(typeTargetSpecs ? { typeTargetSpecs } : {}),
+    };
+  }
+
+  const loadedPlugins = loadPluginsFromEntries(vmcPlugins, dirname(loadedVmcConfig.path));
+  const resolver =
+    loadedPlugins.plugins.length > 0 ? new PluginManager(loadedPlugins.plugins) : undefined;
+  const typeTargetSpecs = resolver ? collectFromResolver(resolver) : undefined;
+  return {
+    status: "loaded",
+    path: loadedVmcConfig.path,
+    ...(resolver ? { resolver } : {}),
+    pluginSpecifiers: loadedPlugins.pluginSpecifiers,
+    pluginLoadErrors: loadedPlugins.errors,
+    ...(typeTargetSpecs ? { typeTargetSpecs } : {}),
+  };
+}