@typed/virtual-modules 1.0.0-beta.1

package/src/internal/validation.ts

@@ -0,0 +1,85 @@
+/**
+ * Pure validators for plugin and TypeInfoApi boundaries. No I/O.
+ */
+
+const DEFAULT_MAX_LENGTH = 4096;
+
+export type ValidationOk<T> = { ok: true; value: T };
+export type ValidationFail = { ok: false; reason: string };
+export type ValidationResult<T> = ValidationOk<T> | ValidationFail;
+
+/**
+ * Validates a non-empty string (trimmed). Rejects null bytes.
+ */
+export function validateNonEmptyString(
+  value: unknown,
+  name: string,
+  maxLength: number = DEFAULT_MAX_LENGTH,
+): ValidationResult<string> {
+  if (typeof value !== "string") {
+    return { ok: false, reason: `${name} must be a string` };
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return { ok: false, reason: `${name} must be non-empty` };
+  }
+  if (value.includes("\0")) {
+    return { ok: false, reason: `${name} must not contain null bytes` };
+  }
+  if (value.length > maxLength) {
+    return { ok: false, reason: `${name} exceeds max length ${maxLength}` };
+  }
+  return { ok: true, value: trimmed };
+}
+
+/**
+ * Validates a path-like segment: string, non-empty, no null byte, optional max length.
+ * Does not trim so path semantics are preserved.
+ */
+export function validatePathSegment(
+  value: unknown,
+  name: string,
+  maxLength: number = DEFAULT_MAX_LENGTH,
+): ValidationResult<string> {
+  if (typeof value !== "string") {
+    return { ok: false, reason: `${name} must be a string` };
+  }
+  if (value.length === 0 || value.trim() === "") {
+    return { ok: false, reason: `${name} must be non-empty` };
+  }
+  if (value.includes("\0")) {
+    return { ok: false, reason: `${name} must not contain null bytes` };
+  }
+  if (value.length > maxLength) {
+    return { ok: false, reason: `${name} exceeds max length ${maxLength}` };
+  }
+  return { ok: true, value };
+}
+
+/**
+ * Validates relativeGlobs: array or single string; each element non-empty, no null byte,
+ * no parent-segment (..) or absolute paths, optional max length.
+ * Rejects patterns that could escape the intended base directory.
+ */
+export function validateRelativeGlobs(
+  value: unknown,
+  name: string,
+  maxLength: number = DEFAULT_MAX_LENGTH,
+): ValidationResult<string[]> {
+  const arr = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  const result: string[] = [];
+  for (let i = 0; i < arr.length; i++) {
+    const v = arr[i];
+    const r = validatePathSegment(v, `${name}[${i}]`, maxLength);
+    if (!r.ok) return r;
+    const normalized = (r.value as string).replaceAll("\\", "/");
+    if (normalized.includes("..")) {
+      return { ok: false, reason: `${name}[${i}] must not contain parent path segments (..)` };
+    }
+    if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
+      return { ok: false, reason: `${name}[${i}] must be a relative glob, not absolute` };
+    }
+    result.push(r.value);
+  }
+  return { ok: true, value: result };
+}

package/src/typeTargetBootstrap.ts

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type * as ts from "typescript";
+import { createTypeTargetBootstrapContent } from "./TypeInfoApi.js";
+import type { TypeTargetSpec } from "./types.js";
+
+/**
+ * Canonical relative path for the type-target bootstrap file.
+ * Always under node_modules so it is git-ignored and does not pollute the project.
+ */
+export const TYPE_TARGET_BOOTSTRAP_RELATIVE = "node_modules/.typed/type-target-bootstrap.ts";
+
+/**
+ * Returns the canonical path for the type-target bootstrap file.
+ * Always under projectRoot/node_modules/.typed/ so it is git-ignored.
+ * All consumers (TS plugin, VSCode resolver, VMC, Vite plugin) should use this path.
+ */
+export function getTypeTargetBootstrapPath(projectRoot: string): string {
+  return join(projectRoot, "node_modules", ".typed", "type-target-bootstrap.ts");
+}
+
+export interface EnsureTypeTargetBootstrapFileFs {
+  mkdirSync(path: string, options?: { recursive?: boolean }): void;
+  writeFile(path: string, content: string): void;
+}
+
+const defaultFs: EnsureTypeTargetBootstrapFileFs = {
+  mkdirSync(path: string, options?: { recursive?: boolean }) {
+    mkdirSync(path, options);
+  },
+  writeFile(path: string, content: string) {
+    writeFileSync(path, content, "utf8");
+  },
+};
+
+/**
+ * Ensures the type-target bootstrap file exists on disk. Writes to
+ * projectRoot/node_modules/.typed/type-target-bootstrap.ts (git-ignored via node_modules).
+ * Creates node_modules/.typed if needed. Returns the bootstrap path.
+ * Use default Node fs unless passing custom fs (e.g. ts.sys for VMC).
+ */
+export function ensureTypeTargetBootstrapFile(
+  projectRoot: string,
+  typeTargetSpecs: readonly TypeTargetSpec[],
+  fs: EnsureTypeTargetBootstrapFileFs = defaultFs,
+): string {
+  const bootstrapPath = getTypeTargetBootstrapPath(projectRoot);
+  if (typeTargetSpecs.length === 0) return bootstrapPath;
+  const dir = dirname(bootstrapPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFile(bootstrapPath, createTypeTargetBootstrapContent(typeTargetSpecs));
+  return bootstrapPath;
+}
+
+/**
+ * Returns a program that includes the type-target bootstrap file in rootNames when
+ * typeTargetSpecs is non-empty, so resolveTypeTargetsFromSpecs can find types.
+ * If typeTargetSpecs is empty or the program already includes the bootstrap, returns program unchanged.
+ */
+export function getProgramWithTypeTargetBootstrap(
+  tsMod: typeof import("typescript"),
+  program: ts.Program,
+  projectRoot: string,
+  typeTargetSpecs: readonly TypeTargetSpec[] | undefined,
+): ts.Program {
+  if (!typeTargetSpecs?.length) return program;
+  const bootstrapPath = ensureTypeTargetBootstrapFile(projectRoot, typeTargetSpecs);
+  const rootNames = program.getRootFileNames();
+  const canonicalBootstrap = resolve(bootstrapPath);
+  const alreadyHasBootstrap = rootNames.some((p) => resolve(p) === canonicalBootstrap);
+  if (alreadyHasBootstrap) return program;
+  const opts = program.getCompilerOptions();
+  const host = tsMod.createCompilerHost(opts, true);
+  return tsMod.createProgram([...rootNames, bootstrapPath], opts, host);
+}

package/src/types.ts

@@ -0,0 +1,535 @@
+import type * as ts from "typescript";
+
+/**
+ * Type-safe AST for serialized types. Discriminated union by `kind`.
+ * Use `node.kind` to narrow; each variant exposes only its fields (e.g. `UnionTypeNode.elements`, `FunctionTypeNode.parameters`).
+ *
+ * Forward-compatible consumer guidance: Use a switch with a default branch that handles unknown kinds
+ * (e.g. `return node.text` or fallback behavior). New `kind` values may be added over time;
+ * consumers that only care about specific variants should explicitly list them and treat others as opaque.
+ *
+ * @example
+ * function visit(node: TypeNode): string {
+ *   switch (node.kind) {
+ *     case "union": return node.elements.map(visit).join(" | ");
+ *     case "function": return `(${node.parameters.map(p => p.name).join(", ")}) => ${visit(node.returnType)}`;
+ *     case "object": return `{ ${node.properties.map(p => p.name).join(", ")} }`;
+ *     default: return node.text;
+ *   }
+ * }
+ */
+export type TypeNode =
+  | LiteralTypeNode
+  | PrimitiveTypeNode
+  | AnyTypeNode
+  | UnknownTypeNode
+  | NeverTypeNode
+  | UnionTypeNode
+  | IntersectionTypeNode
+  | TupleTypeNode
+  | ArrayTypeNode
+  | FunctionTypeNode
+  | ReferenceTypeNode
+  | ObjectTypeNode
+  | ConditionalTypeNode
+  | IndexedAccessTypeNode
+  | TemplateLiteralTypeNode
+  | MappedTypeNode
+  | TypeOperatorTypeNode
+  | ConstructorTypeNode
+  | IndexSignatureTypeNode
+  | OverloadSetTypeNode
+  | EnumTypeNode;
+
+export interface LiteralTypeNode {
+  readonly kind: "literal";
+  readonly text: string;
+}
+
+export interface PrimitiveTypeNode {
+  readonly kind: "primitive";
+  readonly text: string;
+}
+
+export interface AnyTypeNode {
+  readonly kind: "any";
+  readonly text: string;
+}
+
+export interface UnknownTypeNode {
+  readonly kind: "unknown";
+  readonly text: string;
+}
+
+export interface NeverTypeNode {
+  readonly kind: "never";
+  readonly text: string;
+}
+
+export interface UnionTypeNode {
+  readonly kind: "union";
+  readonly text: string;
+  readonly elements: readonly TypeNode[];
+}
+
+export interface IntersectionTypeNode {
+  readonly kind: "intersection";
+  readonly text: string;
+  readonly elements: readonly TypeNode[];
+}
+
+export interface TupleTypeNode {
+  readonly kind: "tuple";
+  readonly text: string;
+  readonly elements: readonly TypeNode[];
+}
+
+export interface ArrayTypeNode {
+  readonly kind: "array";
+  readonly text: string;
+  readonly elements: readonly TypeNode[];
+}
+
+export interface TypeParameter {
+  readonly name: string;
+  readonly optional: boolean;
+  readonly type: TypeNode;
+}
+
+export interface FunctionTypeNode {
+  readonly kind: "function";
+  readonly text: string;
+  readonly parameters: readonly TypeParameter[];
+  readonly returnType: TypeNode;
+}
+
+export interface ReferenceTypeNode {
+  readonly kind: "reference";
+  readonly text: string;
+  readonly typeArguments?: readonly TypeNode[];
+}
+
+export interface ObjectProperty {
+  readonly name: string;
+  readonly optional: boolean;
+  readonly readonly: boolean;
+  readonly type: TypeNode;
+}
+
+export interface ObjectTypeNode {
+  readonly kind: "object";
+  readonly text: string;
+  readonly properties: readonly ObjectProperty[];
+  /** Optional index signature for `[key: K]: V` when present. */
+  readonly indexSignature?: IndexSignatureInfo;
+}
+
+export interface IndexSignatureInfo {
+  readonly keyType: TypeNode;
+  readonly valueType: TypeNode;
+  readonly readonly: boolean;
+}
+
+export interface ConditionalTypeNode {
+  readonly kind: "conditional";
+  readonly text: string;
+  readonly checkType: TypeNode;
+  readonly extendsType: TypeNode;
+  readonly trueType: TypeNode;
+  readonly falseType: TypeNode;
+}
+
+export interface IndexedAccessTypeNode {
+  readonly kind: "indexedAccess";
+  readonly text: string;
+  readonly objectType: TypeNode;
+  readonly indexType: TypeNode;
+}
+
+export interface TemplateLiteralTypeNode {
+  readonly kind: "templateLiteral";
+  readonly text: string;
+  readonly texts: readonly string[];
+  readonly types: readonly TypeNode[];
+}
+
+export interface MappedTypeNode {
+  readonly kind: "mapped";
+  readonly text: string;
+  readonly constraintType: TypeNode;
+  readonly mappedType: TypeNode;
+  readonly readonlyModifier?: "+" | "-" | undefined;
+  readonly optionalModifier?: "+" | "-" | undefined;
+}
+
+export interface TypeOperatorTypeNode {
+  readonly kind: "typeOperator";
+  readonly text: string;
+  readonly operator: "keyof" | "unique" | "readonly";
+  readonly type: TypeNode;
+}
+
+export interface ConstructorTypeNode {
+  readonly kind: "constructor";
+  readonly text: string;
+  readonly parameters: readonly TypeParameter[];
+  readonly returnType: TypeNode;
+}
+
+export interface IndexSignatureTypeNode {
+  readonly kind: "indexSignature";
+  readonly text: string;
+  readonly keyType: TypeNode;
+  readonly valueType: TypeNode;
+  readonly readonly: boolean;
+}
+
+export interface FunctionSignature {
+  readonly parameters: readonly TypeParameter[];
+  readonly returnType: TypeNode;
+}
+
+export interface OverloadSetTypeNode {
+  readonly kind: "overloadSet";
+  readonly text: string;
+  readonly signatures: readonly FunctionSignature[];
+}
+
+export interface EnumTypeNode {
+  readonly kind: "enum";
+  readonly text: string;
+  readonly members?: readonly { readonly name: string; readonly value?: string | number }[];
+}
+
+export interface ExportedTypeInfo {
+  readonly name: string;
+  readonly declarationKind?: string;
+  readonly declarationText?: string;
+  readonly docs?: string;
+  readonly type: TypeNode;
+}
+
+/**
+ * A step that navigates from one type to a sub-type during assignability checking.
+ * Steps chain left-to-right when composed in an array.
+ */
+export type TypeProjectionStep =
+  | { readonly kind: "returnType" }
+  | { readonly kind: "param"; readonly index: number }
+  | { readonly kind: "typeArg"; readonly index: number }
+  | { readonly kind: "property"; readonly name: string }
+  | { readonly kind: "ensure"; readonly targetId: string }
+  | { readonly kind: "predicate"; readonly fn: (node: TypeNode) => boolean };
+
+/**
+ * Spec for resolving a type from program imports for structural assignability checks.
+ * Used with createTypeInfoApiSession typeTargetSpecs option; resolution happens internally.
+ */
+export interface TypeTargetSpec {
+  readonly id: string;
+  readonly module: string;
+  readonly exportName: string;
+  /**
+   * When the export is a merged interface+namespace with a type member that accepts
+   * all generic instantiations (e.g. Route.Any = Route<any, any>), use this to
+   * resolve that member's type for assignability checks.
+   * Enables Route.Parse("/status") (Route<"/status">) to pass assignableTo.Route
+   * by comparing against Route.Any instead of the uninstantiated generic.
+   */
+  readonly typeMember?: string;
+}
+
+/**
+ * Import information for cross-file reference resolution.
+ * Enables plugins to trace symbols to their source declarations.
+ */
+export interface ImportInfo {
+  readonly moduleSpecifier: string;
+  readonly importedNames?: readonly string[];
+  readonly defaultImport?: string;
+  readonly namespaceImport?: string;
+  /**
+   * Resolved absolute path when the module resolves to a project file.
+   * Optional; not currently populated by the API. Reserved for future use (e.g. plugin navigation).
+   */
+  readonly resolvedFilePath?: string;
+}
+
+export interface TypeInfoFileSnapshot {
+  readonly filePath: string;
+  readonly exports: readonly ExportedTypeInfo[];
+  /** Imports present in the file for cross-file reference resolution. */
+  readonly imports?: readonly ImportInfo[];
+}
+
+export interface FileSnapshotSuccess {
+  readonly ok: true;
+  readonly snapshot: TypeInfoFileSnapshot;
+}
+
+export type FileSnapshotErrorCode = "file-not-in-program" | "path-escapes-base" | "invalid-input";
+
+export interface FileSnapshotError {
+  readonly ok: false;
+  readonly error: FileSnapshotErrorCode;
+  readonly path?: string;
+}
+
+export type FileSnapshotResult = FileSnapshotSuccess | FileSnapshotError;
+
+export interface TypeInfoFileQueryOptions {
+  readonly baseDir: string;
+  readonly watch?: boolean;
+}
+
+export interface TypeInfoDirectoryQueryOptions {
+  readonly baseDir: string;
+  readonly recursive: boolean;
+  readonly watch?: boolean;
+}
+
+export interface FileWatchDependencyDescriptor {
+  readonly type: "file";
+  readonly path: string;
+}
+
+export interface GlobWatchDependencyDescriptor {
+  readonly type: "glob";
+  readonly baseDir: string;
+  readonly relativeGlobs: readonly string[];
+  readonly recursive: boolean;
+}
+
+export type WatchDependencyDescriptor =
+  | FileWatchDependencyDescriptor
+  | GlobWatchDependencyDescriptor;
+
+export interface TypeInfoApi {
+  file(relativePath: string, options: TypeInfoFileQueryOptions): FileSnapshotResult;
+  directory(
+    relativeGlobs: string | readonly string[],
+    options: TypeInfoDirectoryQueryOptions,
+  ): readonly TypeInfoFileSnapshot[];
+  /**
+   * Resolve an export by name from a file. Use baseDir-relative filePath.
+   * Returns undefined when the file is not in the program or the export is not found.
+   */
+  resolveExport(
+    baseDir: string,
+    filePath: string,
+    exportName: string,
+  ): ExportedTypeInfo | undefined;
+  /**
+   * Dynamic structural assignability check. Looks up the ts.Type backing `node`
+   * (registered during serialization), optionally applies projection steps to
+   * navigate to a sub-type, then checks assignability against the resolved target.
+   *
+   * Returns false when: node was not created by this API, projection fails
+   * (e.g. returnType on non-function), or targetId was not resolved.
+   *
+   * Plugins can navigate the TypeNode tree themselves and pass any sub-node
+   * (e.g. `functionNode.returnType`, `referenceNode.typeArguments[0]`) since
+   * all nodes are registered during serialization.
+   */
+  isAssignableTo(
+    node: TypeNode,
+    targetId: string,
+    projection?: readonly TypeProjectionStep[],
+  ): boolean;
+}
+
+export interface TypeInfoApiSession {
+  readonly api: TypeInfoApi;
+  consumeDependencies(): readonly WatchDependencyDescriptor[];
+}
+
+export interface TypeInfoApiFactoryParams {
+  readonly id: string;
+  readonly importer: string;
+}
+
+export type CreateTypeInfoApiSession = (params: TypeInfoApiFactoryParams) => TypeInfoApiSession;
+
+/** Result of a successful build; plain string is treated as { sourceText }. */
+export interface VirtualModuleBuildSuccess {
+  readonly sourceText: string;
+  readonly warnings?: readonly VirtualModuleDiagnostic[];
+}
+
+/** Result of a failed build with structured errors. */
+export interface VirtualModuleBuildError {
+  readonly errors: readonly VirtualModuleDiagnostic[];
+}
+
+export type VirtualModuleBuildResult = string | VirtualModuleBuildSuccess | VirtualModuleBuildError;
+
+/** Type guard: true when the build result indicates failure with structured errors. */
+export function isVirtualModuleBuildError(
+  result: VirtualModuleBuildResult,
+): result is VirtualModuleBuildError {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    "errors" in result &&
+    Array.isArray((result as VirtualModuleBuildError).errors) &&
+    (result as VirtualModuleBuildError).errors.length > 0
+  );
+}
+
+/** Type guard: true when the build result indicates success with sourceText. */
+export function isVirtualModuleBuildSuccess(
+  result: VirtualModuleBuildResult,
+): result is VirtualModuleBuildSuccess {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    "sourceText" in result &&
+    typeof (result as VirtualModuleBuildSuccess).sourceText === "string"
+  );
+}
+
+export interface VirtualModulePlugin {
+  readonly name: string;
+  shouldResolve(id: string, importer: string): boolean;
+  build(id: string, importer: string, api: TypeInfoApi): VirtualModuleBuildResult;
+  /**
+   * Optional type target specs for structural assignability checks.
+   * Plugins that need assignableTo (e.g. Route, Effect) should declare them here.
+   * Specs from all plugins are merged (deduped by id) when creating the TypeInfo session.
+   */
+  readonly typeTargetSpecs?: readonly TypeTargetSpec[];
+}
+
+export interface VirtualModuleDiagnostic {
+  readonly code:
+    | "plugin-should-resolve-threw"
+    | "plugin-build-threw"
+    | "session-creation-failed"
+    | "invalid-build-output"
+    | "invalid-options"
+    | "re-entrant-resolution"
+    | (string & {}); // allow plugin-specific codes e.g. RVM-GUARD-001
+  readonly message: string;
+  readonly pluginName: string;
+}
+
+export interface VirtualModuleResolved {
+  readonly status: "resolved";
+  readonly pluginName: string;
+  readonly sourceText: string;
+  readonly dependencies: readonly WatchDependencyDescriptor[];
+  readonly warnings?: readonly VirtualModuleDiagnostic[];
+}
+
+export interface VirtualModuleUnresolved {
+  readonly status: "unresolved";
+}
+
+export interface VirtualModuleError {
+  readonly status: "error";
+  readonly diagnostic: VirtualModuleDiagnostic;
+}
+
+export type VirtualModuleResolution =
+  | VirtualModuleResolved
+  | VirtualModuleUnresolved
+  | VirtualModuleError;
+
+export interface ResolveVirtualModuleOptions {
+  readonly id: string;
+  readonly importer: string;
+  readonly createTypeInfoApiSession?: CreateTypeInfoApiSession;
+}
+
+export interface VirtualModuleResolver {
+  resolveModule(options: ResolveVirtualModuleOptions): VirtualModuleResolution;
+}
+
+export interface NodeModulePluginRequest {
+  readonly specifier: string;
+  readonly baseDir: string;
+}
+
+export type NodeModulePluginLoadInput = VirtualModulePlugin | NodeModulePluginRequest;
+
+export interface NodeModulePluginLoadSuccess {
+  readonly status: "loaded";
+  readonly plugin: VirtualModulePlugin;
+  readonly resolvedPath: string;
+}
+
+export interface NodeModulePluginLoadError {
+  readonly status: "error";
+  readonly specifier: string;
+  readonly baseDir: string;
+  readonly code:
+    | "module-not-found"
+    | "module-load-failed"
+    | "invalid-plugin-export"
+    | "path-escapes-base"
+    | "invalid-request";
+  readonly message: string;
+}
+
+export type NodeModulePluginLoadResult = NodeModulePluginLoadSuccess | NodeModulePluginLoadError;
+
+export interface VirtualModuleRecord {
+  readonly key: string;
+  readonly id: string;
+  readonly importer: string;
+  readonly pluginName: string;
+  readonly virtualFileName: string;
+  readonly sourceText: string;
+  readonly dependencies: readonly WatchDependencyDescriptor[];
+  readonly diagnostic?: VirtualModuleDiagnostic;
+  readonly warnings?: readonly VirtualModuleDiagnostic[];
+  readonly version: number;
+  readonly stale: boolean;
+}
+
+export interface LanguageServiceWatchHost {
+  watchFile?: (
+    path: string,
+    callback: ts.FileWatcherCallback,
+    pollingInterval?: number,
+    options?: ts.WatchOptions,
+  ) => ts.FileWatcher;
+  watchDirectory?: (
+    path: string,
+    callback: ts.DirectoryWatcherCallback,
+    recursive?: boolean,
+    options?: ts.WatchOptions,
+  ) => ts.FileWatcher;
+}
+
+export interface LanguageServiceAdapterOptions {
+  readonly ts: typeof import("typescript");
+  readonly languageService: ts.LanguageService;
+  readonly languageServiceHost: ts.LanguageServiceHost;
+  readonly resolver: VirtualModuleResolver;
+  readonly projectRoot: string;
+  readonly createTypeInfoApiSession?: CreateTypeInfoApiSession;
+  readonly watchHost?: LanguageServiceWatchHost;
+  /** Coalesce rapid watch events (ms). When set, markStale is deferred until after the delay. */
+  readonly debounceMs?: number;
+}
+
+export interface CompilerHostAdapterOptions {
+  readonly ts: typeof import("typescript");
+  readonly compilerHost: ts.CompilerHost;
+  readonly resolver: VirtualModuleResolver;
+  readonly projectRoot: string;
+  readonly createTypeInfoApiSession?: CreateTypeInfoApiSession;
+  readonly watchHost?: LanguageServiceWatchHost;
+  /** Coalesce rapid watch events (ms). When set, markStale is deferred until after the delay. */
+  readonly debounceMs?: number;
+  /**
+   * When provided, called when a virtual module rebuild fails (stale record).
+   * Use to surface diagnostics to match LanguageServiceAdapter behavior.
+   */
+  readonly reportDiagnostic?: ts.DiagnosticReporter;
+}
+
+export interface VirtualModuleAdapterHandle {
+  dispose(): void;
+}