@ricsam/isolate-test-utils 0.0.1 → 0.1.1

package/src/runtime-context.ts

@@ -0,0 +1,120 @@
+import type ivm from "isolated-vm";
+import { MockFileSystem } from "./mock-fs.ts";
+
+export interface MockResponse {
+  status?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface RuntimeTestContextOptions {
+  /** Enable file system APIs with mock file system */
+  fs?: boolean;
+}
+
+export interface RuntimeTestContext {
+  isolate: ivm.Isolate;
+  context: ivm.Context;
+  /** Advance virtual time and process pending timers */
+  tick(ms?: number): Promise<void>;
+  dispose(): void;
+  /** Captured console.log calls */
+  logs: Array<{ level: string; args: unknown[] }>;
+  /** Captured fetch calls */
+  fetchCalls: Array<{ url: string; method: string; headers: [string, string][] }>;
+  /** Set the mock response for the next fetch call */
+  setMockResponse(response: MockResponse): void;
+  /** Mock file system (only available if fs option is true) */
+  mockFs: MockFileSystem;
+}
+
+/**
+ * Create a full runtime test context with all APIs set up.
+ * Includes console logging capture, fetch mocking, and optionally file system.
+ *
+ * @example
+ * const ctx = await createRuntimeTestContext({ fs: true });
+ *
+ * // Set up mock response for fetch
+ * ctx.setMockResponse({ status: 200, body: '{"data": "test"}' });
+ *
+ * // Run code
+ * await ctx.context.eval(`
+ *   (async () => {
+ *     console.log("Starting fetch...");
+ *     const response = await fetch("https://api.example.com/data");
+ *     const data = await response.json();
+ *     console.log("Got data:", data);
+ *   })()
+ * `, { promise: true });
+ *
+ * // Check logs
+ * console.log(ctx.logs); // [{ level: "log", args: ["Starting fetch..."] }, ...]
+ *
+ * // Check fetch calls
+ * console.log(ctx.fetchCalls); // [{ url: "https://api.example.com/data", method: "GET", ... }]
+ *
+ * ctx.dispose();
+ */
+export async function createRuntimeTestContext(
+  options?: RuntimeTestContextOptions
+): Promise<RuntimeTestContext> {
+  const opts = options ?? {};
+  const { createRuntime } = await import("@ricsam/isolate-runtime");
+  const { clearAllInstanceState } = await import("@ricsam/isolate-core");
+
+  // Clear any previous instance state
+  clearAllInstanceState();
+
+  // State for capturing logs and fetch calls
+  const logs: Array<{ level: string; args: unknown[] }> = [];
+  const fetchCalls: Array<{
+    url: string;
+    method: string;
+    headers: [string, string][];
+  }> = [];
+
+  let mockResponse: MockResponse = { status: 200, body: "" };
+
+  // Create mock file system
+  const mockFs = new MockFileSystem();
+
+  // Create runtime with configured handlers
+  const runtime = await createRuntime({
+    console: {
+      onLog: (level: string, ...args: unknown[]) => {
+        logs.push({ level, args });
+      },
+    },
+    fetch: {
+      onFetch: async (request: Request) => {
+        // Capture fetch call
+        fetchCalls.push({
+          url: request.url,
+          method: request.method,
+          headers: [...request.headers.entries()],
+        });
+
+        // Return mock response
+        return new Response(mockResponse.body ?? "", {
+          status: mockResponse.status ?? 200,
+          headers: mockResponse.headers,
+        });
+      },
+    },
+    fs: opts.fs ? { getDirectory: async () => mockFs } : undefined,
+  });
+
+  return {
+    isolate: runtime.isolate,
+    context: runtime.context,
+    tick: runtime.tick.bind(runtime),
+    dispose: runtime.dispose.bind(runtime),
+    logs,
+    fetchCalls,
+    setMockResponse(response: MockResponse) {
+      mockResponse = response;
+    },
+    mockFs,
+  };
+}

package/src/server.ts

@@ -0,0 +1,150 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+
+export interface MockServerResponse {
+  status?: number;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface RecordedRequest {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+export interface IntegrationServer {
+  /** The base URL of the server (e.g., "http://localhost:3000") */
+  url: string;
+  /** The port the server is listening on */
+  port: number;
+  /** Close the server */
+  close(): Promise<void>;
+  /** Set the response for a specific path */
+  setResponse(path: string, response: MockServerResponse): void;
+  /** Set a default response for any unmatched path */
+  setDefaultResponse(response: MockServerResponse): void;
+  /** Get all recorded requests */
+  getRequests(): RecordedRequest[];
+  /** Clear all recorded requests */
+  clearRequests(): void;
+  /** Clear all configured responses */
+  clearResponses(): void;
+}
+
+/**
+ * Start an HTTP server for integration tests.
+ * Useful for testing fetch operations against a real server.
+ *
+ * @example
+ * const server = await startIntegrationServer();
+ *
+ * server.setResponse("/api/data", {
+ *   status: 200,
+ *   body: JSON.stringify({ message: "Hello" }),
+ *   headers: { "Content-Type": "application/json" }
+ * });
+ *
+ * // In your test
+ * const response = await fetch(`${server.url}/api/data`);
+ * const data = await response.json();
+ *
+ * // Check what requests were made
+ * const requests = server.getRequests();
+ * console.log(requests[0].path); // "/api/data"
+ *
+ * await server.close();
+ */
+export async function startIntegrationServer(
+  port?: number
+): Promise<IntegrationServer> {
+  const responses = new Map<string, MockServerResponse>();
+  const requests: RecordedRequest[] = [];
+  let defaultResponse: MockServerResponse = { status: 404, body: "Not Found" };
+
+  const server: Server = createServer(
+    async (req: IncomingMessage, res: ServerResponse) => {
+      const path = req.url ?? "/";
+      const method = req.method ?? "GET";
+
+      // Read request body
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) {
+        chunks.push(chunk as Buffer);
+      }
+      const body = chunks.length > 0 ? Buffer.concat(chunks).toString() : undefined;
+
+      // Record the request
+      const headers: Record<string, string> = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string") {
+          headers[key] = value;
+        } else if (Array.isArray(value)) {
+          headers[key] = value.join(", ");
+        }
+      }
+      requests.push({ method, path, headers, body });
+
+      // Find and send response
+      const mockResponse = responses.get(path) ?? defaultResponse;
+
+      res.statusCode = mockResponse.status ?? 200;
+
+      if (mockResponse.headers) {
+        for (const [key, value] of Object.entries(mockResponse.headers)) {
+          res.setHeader(key, value);
+        }
+      }
+
+      res.end(mockResponse.body ?? "");
+    }
+  );
+
+  // Find an available port
+  const actualPort = await new Promise<number>((resolve, reject) => {
+    server.listen(port ?? 0, () => {
+      const address = server.address();
+      if (address && typeof address === "object") {
+        resolve(address.port);
+      } else {
+        reject(new Error("Failed to get server address"));
+      }
+    });
+    server.on("error", reject);
+  });
+
+  return {
+    url: `http://localhost:${actualPort}`,
+    port: actualPort,
+
+    async close() {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+
+    setResponse(path: string, response: MockServerResponse) {
+      responses.set(path, response);
+    },
+
+    setDefaultResponse(response: MockServerResponse) {
+      defaultResponse = response;
+    },
+
+    getRequests() {
+      return [...requests];
+    },
+
+    clearRequests() {
+      requests.length = 0;
+    },
+
+    clearResponses() {
+      responses.clear();
+      defaultResponse = { status: 404, body: "Not Found" };
+    },
+  };
+}

package/src/typecheck.ts

@@ -0,0 +1,291 @@
+/**
+ * Type-checking utility for isolated-vm user code using ts-morph.
+ *
+ * This utility allows you to validate TypeScript code strings against
+ * the isolate global type definitions before running them in the sandbox.
+ *
+ * @example
+ * import { typecheckIsolateCode } from "@ricsam/isolate-test-utils";
+ *
+ * const result = typecheckIsolateCode(`
+ *   serve({
+ *     fetch(request, server) {
+ *       return new Response("Hello!");
+ *     }
+ *   });
+ * `, { include: ["fetch"] });
+ *
+ * if (!result.success) {
+ *   console.error("Type errors:", result.errors);
+ * }
+ */
+
+import { Project, ts } from "ts-morph";
+import { TYPE_DEFINITIONS, type TypeDefinitionKey } from "./isolate-types.ts";
+
+/**
+ * Result of type-checking isolate code.
+ */
+export interface TypecheckResult {
+  /**
+   * Whether the code passed type checking.
+   */
+  success: boolean;
+
+  /**
+   * Array of type errors found in the code.
+   */
+  errors: TypecheckError[];
+}
+
+/**
+ * A single type-checking error.
+ */
+export interface TypecheckError {
+  /**
+   * The error message from TypeScript.
+   */
+  message: string;
+
+  /**
+   * The line number where the error occurred (1-indexed).
+   */
+  line?: number;
+
+  /**
+   * The column number where the error occurred (1-indexed).
+   */
+  column?: number;
+
+  /**
+   * The TypeScript error code.
+   */
+  code?: number;
+}
+
+/**
+ * A single library type file to inject into the virtual file system.
+ */
+export interface LibraryTypeFile {
+  /** The file content (e.g., .d.ts or package.json content) */
+  content: string;
+  /** The virtual path (e.g., "node_modules/zod/index.d.ts") */
+  path: string;
+}
+
+/**
+ * Library types bundle for a single package.
+ */
+export interface LibraryTypes {
+  files: LibraryTypeFile[];
+}
+
+/**
+ * Options for type-checking isolate code.
+ */
+export interface TypecheckOptions {
+  /**
+   * Which isolate global types to include.
+   * @default ["core", "fetch", "fs"]
+   */
+  include?: Array<"core" | "fetch" | "fs" | "console" | "encoding" | "timers" | "testEnvironment">;
+
+  /**
+   * Library type definitions to inject for import resolution.
+   * These are added to the virtual node_modules/ for module resolution.
+   *
+   * Use the build-library-types.ts script to generate these bundles from
+   * your project's node_modules, then pass them here.
+   *
+   * @example
+   * import { LIBRARY_TYPES } from "./my-library-types.ts";
+   *
+   * typecheckIsolateCode(code, {
+   *   libraryTypes: {
+   *     zod: LIBRARY_TYPES.zod,
+   *     "@richie-rpc/core": LIBRARY_TYPES["@richie-rpc/core"],
+   *   }
+   * });
+   */
+  libraryTypes?: Record<string, LibraryTypes>;
+
+  /**
+   * Additional compiler options to pass to TypeScript.
+   */
+  compilerOptions?: Partial<ts.CompilerOptions>;
+}
+
+/**
+ * Get the message text from a TypeScript diagnostic message.
+ * Handles both string messages and DiagnosticMessageChain objects.
+ */
+function getMessageText(messageText: unknown): string {
+  if (typeof messageText === "string") {
+    return messageText;
+  }
+
+  // Handle ts-morph DiagnosticMessageChain wrapper
+  if (
+    messageText &&
+    typeof messageText === "object" &&
+    "getMessageText" in messageText &&
+    typeof (messageText as { getMessageText: unknown }).getMessageText ===
+      "function"
+  ) {
+    return (messageText as { getMessageText: () => string }).getMessageText();
+  }
+
+  // Handle raw TypeScript DiagnosticMessageChain
+  if (
+    messageText &&
+    typeof messageText === "object" &&
+    "messageText" in messageText
+  ) {
+    return String((messageText as { messageText: unknown }).messageText);
+  }
+
+  return String(messageText);
+}
+
+
+/**
+ * Type-check isolate user code against the package type definitions.
+ *
+ * @param code - The TypeScript/JavaScript code to check
+ * @param options - Configuration options
+ * @returns The result of type checking
+ *
+ * @example
+ * // Check code that uses the fetch API
+ * const result = typecheckIsolateCode(`
+ *   const response = await fetch("https://api.example.com/data");
+ *   const data = await response.json();
+ * `, { include: ["core", "fetch"] });
+ *
+ * @example
+ * // Check code that uses serve()
+ * const result = typecheckIsolateCode(`
+ *   serve({
+ *     fetch(request, server) {
+ *       return new Response("Hello!");
+ *     }
+ *   });
+ * `, { include: ["fetch"] });
+ *
+ * @example
+ * // Check code that uses the file system API
+ * const result = typecheckIsolateCode(`
+ *   const root = await getDirectory("/data");
+ *   const file = await root.getFileHandle("config.json");
+ * `, { include: ["core", "fs"] });
+ */
+export function typecheckIsolateCode(
+  code: string,
+  options?: TypecheckOptions
+): TypecheckResult {
+  const include = options?.include ?? ["core", "fetch", "fs"];
+  const libraryTypes = options?.libraryTypes ?? {};
+  const hasLibraries = Object.keys(libraryTypes).length > 0;
+
+  // Create a project with in-memory file system
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.ESNext,
+      // Use NodeJs resolution for node_modules/ lookup when libraries are included
+      moduleResolution: hasLibraries
+        ? ts.ModuleResolutionKind.NodeJs
+        : undefined,
+      lib: ["lib.esnext.d.ts", "lib.dom.d.ts"],
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      esModuleInterop: true,
+      allowSyntheticDefaultImports: true,
+      ...options?.compilerOptions,
+    },
+  });
+
+  const memFs = project.getFileSystem();
+
+  // Add type definition files from embedded strings (isolate globals)
+  for (const pkg of include) {
+    const content = TYPE_DEFINITIONS[pkg as TypeDefinitionKey];
+    if (content) {
+      project.createSourceFile(`${pkg}.d.ts`, content);
+    }
+  }
+
+  // Add library type definitions to virtual node_modules/
+  for (const [_libName, lib] of Object.entries(libraryTypes)) {
+    for (const typeFile of lib.files) {
+      // JSON files go to file system, TS files as source files
+      if (typeFile.path.endsWith(".json")) {
+        memFs.writeFileSync(`/${typeFile.path}`, typeFile.content);
+      } else {
+        project.createSourceFile(`/${typeFile.path}`, typeFile.content, { overwrite: true });
+      }
+    }
+  }
+
+  // Add the user code
+  const sourceFile = project.createSourceFile("usercode.ts", code);
+
+  // Get diagnostics
+  const diagnostics = sourceFile.getPreEmitDiagnostics();
+
+  // Convert diagnostics to our error format
+  const errors: TypecheckError[] = diagnostics.map((diagnostic) => {
+    const start = diagnostic.getStart();
+    const sourceFile = diagnostic.getSourceFile();
+
+    let line: number | undefined;
+    let column: number | undefined;
+
+    if (start !== undefined && sourceFile) {
+      const lineAndChar = sourceFile.getLineAndColumnAtPos(start);
+      line = lineAndChar.line;
+      column = lineAndChar.column;
+    }
+
+    return {
+      message: getMessageText(diagnostic.getMessageText()),
+      line,
+      column,
+      code: diagnostic.getCode(),
+    };
+  });
+
+  return {
+    success: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Format type-check errors for display.
+ *
+ * @param result - The type-check result
+ * @returns A formatted string of errors
+ *
+ * @example
+ * const result = typecheckIsolateCode(code);
+ * if (!result.success) {
+ *   console.error(formatTypecheckErrors(result));
+ * }
+ */
+export function formatTypecheckErrors(result: TypecheckResult): string {
+  if (result.success) {
+    return "No type errors found.";
+  }
+
+  return result.errors
+    .map((error) => {
+      const location =
+        error.line !== undefined ? `:${error.line}:${error.column ?? 1}` : "";
+      const code = error.code ? ` (TS${error.code})` : "";
+      return `usercode.ts${location}${code}: ${error.message}`;
+    })
+    .join("\n");
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/README.md

@@ -1,45 +0,0 @@
-# @ricsam/isolate-test-utils
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/isolate-test-utils`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**