@macroforge/vite-plugin 0.1.33 → 0.1.34

package/README.md

@@ -1,10 +1,32 @@
 # @macroforge/vite-plugin
 
-> **Warning:** This is a work in progress and probably won't work for you. Use at your own risk!
+[![npm version](https://badge.fury.io/js/%40macroforge%2Fvite-plugin.svg)](https://www.npmjs.com/package/@macroforge/vite-plugin)
 
-Vite plugin for macroforge compile-time TypeScript macros.
+## Overview
 
-Part of the [macroforge](https://github.com/rymskip/macroforge-ts) project.
+@macroforge/vite-plugin
+
+Vite plugin for Macroforge compile-time TypeScript macro expansion.
+
+This plugin integrates Macroforge's Rust-based macro expander into the Vite build pipeline,
+enabling compile-time code generation through `@derive` decorators. It processes TypeScript
+files during the build, expands macros, generates type definitions, and emits metadata.
+
+@example
+```typescript
+import { defineConfig } from 'vite';
+import macroforgePlugin from '@macroforge/vite-plugin';
+
+export default defineConfig({
+plugins: [
+macroforgePlugin({
+generateTypes: true,
+typesOutputDir: 'src/types/generated',
+emitMetadata: true,
+}),
+],
+});
+```
 
 ## Installation
 
@@ -12,24 +34,42 @@ Part of the [macroforge](https://github.com/rymskip/macroforge-ts) project.
 npm install @macroforge/vite-plugin
 ```
 
-## Usage
+## API
 
-```typescript
-// vite.config.ts
-import macroforge from "@macroforge/vite-plugin";
+### Functions
+
+- **`loadMacroConfig`** - Whether to preserve `@derive` decorators in the output code after macro expansion.
+- **`napiMacrosPlugin`** - Creates a Vite plugin for Macroforge compile-time macro expansion.
+- **`ensureDir`** - Ensures a directory exists, creating it recursively if necessary.
+- **`writeTypeDefinitions`** - Writes generated TypeScript declaration files to the configured output directory.
+- **`writeMetadata`** - Writes macro intermediate representation (IR) metadata to JSON files.
+- **`formatTransformError`** - Formats transformation errors into user-friendly messages.
+
+### Types
+
+- **`NapiMacrosPluginOptions`** - Configuration options for the Macroforge Vite plugin.
+- **`MacroConfig`** - Glob patterns, regular expressions, or arrays of either to specify which files
 
+## Examples
+
+```typescript
+import { defineConfig } from 'vite';
+import macroforgePlugin from '@macroforge/vite-plugin';
 export default defineConfig({
-  plugins: [
-    macroforge({
-      typesOutputDir: ".macroforge/types",
-      metadataOutputDir: ".macroforge/meta",
-      generateTypes: true,
-      emitMetadata: true,
-    }),
-  ],
+plugins: [
+macroforgePlugin({
+generateTypes: true,
+typesOutputDir: 'src/types/generated',
+emitMetadata: true,
+}),
+],
 });
 ```
 
+## Documentation
+
+See the [full documentation](https://macroforge.dev/docs/api/reference/typescript/vite-plugin) on the Macroforge website.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,12 +1,186 @@
+/**
+ * @module @macroforge/vite-plugin
+ *
+ * Vite plugin for Macroforge compile-time TypeScript macro expansion.
+ *
+ * This plugin integrates Macroforge's Rust-based macro expander into the Vite build pipeline,
+ * enabling compile-time code generation through `@derive` decorators. It processes TypeScript
+ * files during the build, expands macros, generates type definitions, and emits metadata.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     macroforgePlugin({
+ *       generateTypes: true,
+ *       typesOutputDir: 'src/types/generated',
+ *       emitMetadata: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
 import { Plugin } from "vite";
+/**
+ * Configuration options for the Macroforge Vite plugin.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const options: NapiMacrosPluginOptions = {
+ *   include: ['src/**\/*.ts'],
+ *   exclude: ['**\/*.test.ts'],
+ *   generateTypes: true,
+ *   typesOutputDir: 'src/types/generated',
+ *   emitMetadata: true,
+ *   metadataOutputDir: 'src/macros/metadata',
+ * };
+ * ```
+ */
 export interface NapiMacrosPluginOptions {
+    /**
+     * Glob patterns, regular expressions, or arrays of either to specify which files
+     * should be processed by the macro expander.
+     *
+     * @remarks
+     * If not specified, all `.ts` and `.tsx` files (excluding `node_modules`) are processed.
+     *
+     * @example
+     * ```typescript
+     * include: ['src/**\/*.ts', /components\/.*\.tsx$/]
+     * ```
+     */
     include?: string | RegExp | (string | RegExp)[];
+    /**
+     * Glob patterns, regular expressions, or arrays of either to specify which files
+     * should be excluded from macro processing.
+     *
+     * @remarks
+     * Files in `node_modules` are always excluded by default.
+     *
+     * @example
+     * ```typescript
+     * exclude: ['**\/*.test.ts', '**\/*.spec.ts']
+     * ```
+     */
     exclude?: string | RegExp | (string | RegExp)[];
+    /**
+     * Whether to generate TypeScript declaration files (`.d.ts`) for transformed code.
+     *
+     * @remarks
+     * When enabled, the plugin uses the TypeScript compiler to emit declaration files
+     * based on the macro-expanded code. This ensures type definitions accurately reflect
+     * the generated code.
+     *
+     * @default true
+     */
     generateTypes?: boolean;
+    /**
+     * Output directory for generated TypeScript declaration files.
+     *
+     * @remarks
+     * Path is relative to the project root. The directory structure of the source files
+     * is preserved within this output directory.
+     *
+     * @default "src/macros/generated"
+     *
+     * @example
+     * ```typescript
+     * // Source: src/models/User.ts
+     * // Output: src/types/generated/models/User.d.ts
+     * typesOutputDir: 'src/types/generated'
+     * ```
+     */
     typesOutputDir?: string;
+    /**
+     * Whether to emit macro intermediate representation (IR) metadata as JSON files.
+     *
+     * @remarks
+     * The metadata contains information about which macros were applied, their configurations,
+     * and the transformation results. This can be useful for debugging, tooling integration,
+     * or build analysis.
+     *
+     * @default true
+     */
     emitMetadata?: boolean;
+    /**
+     * Output directory for macro IR metadata JSON files.
+     *
+     * @remarks
+     * Path is relative to the project root. If not specified, defaults to the same
+     * directory as `typesOutputDir`. Metadata files are named with a `.macro-ir.json` suffix.
+     *
+     * @default Same as `typesOutputDir`
+     *
+     * @example
+     * ```typescript
+     * // Source: src/models/User.ts
+     * // Output: src/macros/metadata/models/User.macro-ir.json
+     * metadataOutputDir: 'src/macros/metadata'
+     * ```
+     */
     metadataOutputDir?: string;
 }
+/**
+ * Creates a Vite plugin for Macroforge compile-time macro expansion.
+ *
+ * @remarks
+ * This is the main entry point for integrating Macroforge into a Vite build pipeline.
+ * The plugin:
+ *
+ * 1. **Runs early** (`enforce: "pre"`) to transform code before other plugins
+ * 2. **Processes TypeScript files** (`.ts` and `.tsx`) excluding `node_modules`
+ * 3. **Expands macros** using the Macroforge Rust binary via `expandSync()`
+ * 4. **Generates type definitions** for transformed code (optional, default: enabled)
+ * 5. **Emits metadata** about macro transformations (optional, default: enabled)
+ *
+ * **Plugin Lifecycle:**
+ * - `configResolved`: Initializes project root, loads config, and attempts to load Rust binary
+ * - `transform`: Processes each TypeScript file through the macro expander
+ *
+ * **Error Handling:**
+ * - If the Rust binary is not available, files pass through unchanged
+ * - Macro expansion errors are reported via Vite's `this.error()` mechanism
+ * - TypeScript emission errors are logged as warnings
+ *
+ * @param options - Plugin configuration options
+ *
+ * @returns A Vite plugin instance
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [macroforgePlugin()],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     macroforgePlugin({
+ *       generateTypes: true,
+ *       typesOutputDir: 'src/types/generated',
+ *       emitMetadata: false,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 declare function napiMacrosPlugin(options?: NapiMacrosPluginOptions): Plugin;
 export default napiMacrosPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAsC9B,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAChD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AA6LD,iBAAS,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM,CA0LvE;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAuD9B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEhD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEhD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAiTD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,iBAAS,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM,CAmTvE;AAED,eAAe,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,3 +1,31 @@
+/**
+ * @module @macroforge/vite-plugin
+ *
+ * Vite plugin for Macroforge compile-time TypeScript macro expansion.
+ *
+ * This plugin integrates Macroforge's Rust-based macro expander into the Vite build pipeline,
+ * enabling compile-time code generation through `@derive` decorators. It processes TypeScript
+ * files during the build, expands macros, generates type definitions, and emits metadata.
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     macroforgePlugin({
+ *       generateTypes: true,
+ *       typesOutputDir: 'src/types/generated',
+ *       emitMetadata: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
 import { createRequire } from "module";
 import * as fs from "fs";
 import * as path from "path";
@@ -12,6 +40,23 @@ catch (error) {
 }
 const compilerOptionsCache = new Map();
 let cachedRequire;
+/**
+ * Ensures that `require()` is available in the current execution context.
+ *
+ * @remarks
+ * This function handles the ESM/CommonJS interoperability problem. In pure ESM environments,
+ * `require` is not defined, but some native modules (like the Macroforge Rust binary) may
+ * depend on it being available. This function:
+ *
+ * 1. Returns the existing `require` if already available (CommonJS context)
+ * 2. Creates a synthetic `require` using Node's `createRequire` API (ESM context)
+ * 3. Exposes the created `require` on `globalThis` for native runtime loaders
+ * 4. Caches the result to avoid redundant creation
+ *
+ * @returns A Promise resolving to a Node.js `require` function
+ *
+ * @internal
+ */
 async function ensureRequire() {
     if (typeof require !== "undefined") {
         return require;
@@ -24,6 +69,31 @@ async function ensureRequire() {
     }
     return cachedRequire;
 }
+/**
+ * Loads Macroforge configuration from `macroforge.json`.
+ *
+ * @remarks
+ * Searches for `macroforge.json` starting from `projectRoot` and traversing up the
+ * directory tree until found or the filesystem root is reached. This allows monorepo
+ * setups where the config may be at the workspace root rather than the package root.
+ *
+ * If the config file is found but cannot be parsed (invalid JSON), returns the
+ * default configuration rather than throwing an error.
+ *
+ * @param projectRoot - The directory to start searching from (usually Vite's resolved root)
+ *
+ * @returns The loaded configuration, or a default config if no file is found
+ *
+ * @example
+ * ```typescript
+ * // macroforge.json
+ * {
+ *   "keepDecorators": true
+ * }
+ * ```
+ *
+ * @internal
+ */
 function loadMacroConfig(projectRoot) {
     let current = projectRoot;
     const fallback = { keepDecorators: false };
@@ -46,6 +116,40 @@ function loadMacroConfig(projectRoot) {
     }
     return fallback;
 }
+/**
+ * Retrieves and normalizes TypeScript compiler options for declaration emission.
+ *
+ * @remarks
+ * This function reads the project's `tsconfig.json` and adjusts the compiler options
+ * specifically for generating declaration files from macro-expanded code. The function:
+ *
+ * 1. Locates `tsconfig.json` using TypeScript's built-in config file discovery
+ * 2. Parses and validates the configuration
+ * 3. Normalizes options for declaration-only emission
+ * 4. Caches results per project root for performance
+ *
+ * **Forced Options:**
+ * - `declaration: true` - Enable declaration file output
+ * - `emitDeclarationOnly: true` - Only emit `.d.ts` files, not JavaScript
+ * - `noEmitOnError: false` - Continue emission even with type errors
+ * - `incremental: false` - Disable incremental compilation
+ *
+ * **Default Options** (applied if not specified in tsconfig):
+ * - `moduleResolution: Bundler` - Modern bundler-style resolution
+ * - `module: ESNext` - ES module output
+ * - `target: ESNext` - Latest ECMAScript target
+ * - `strict: true` - Enable strict type checking
+ * - `skipLibCheck: true` - Skip type checking of declaration files
+ *
+ * **Removed Options:**
+ * - `outDir` and `outFile` - Removed to allow programmatic output control
+ *
+ * @param projectRoot - The project root directory to search for tsconfig.json
+ *
+ * @returns Normalized compiler options, or `undefined` if TypeScript is not available
+ *
+ * @internal
+ */
 function getCompilerOptions(projectRoot) {
     if (!tsModule) {
         return undefined;
@@ -81,6 +185,7 @@ function getCompilerOptions(projectRoot) {
     else {
         options = {};
     }
+    // Normalize options for declaration-only emission
     const normalized = {
         ...options,
         declaration: true,
@@ -88,8 +193,10 @@ function getCompilerOptions(projectRoot) {
         noEmitOnError: false,
         incremental: false,
     };
+    // Remove output path options to allow programmatic control
     delete normalized.outDir;
     delete normalized.outFile;
+    // Apply sensible defaults for modern TypeScript projects
     normalized.moduleResolution ??= tsModule.ModuleResolutionKind.Bundler;
     normalized.module ??= tsModule.ModuleKind.ESNext;
     normalized.target ??= tsModule.ScriptTarget.ESNext;
@@ -98,6 +205,36 @@ function getCompilerOptions(projectRoot) {
     compilerOptionsCache.set(projectRoot, normalized);
     return normalized;
 }
+/**
+ * Generates TypeScript declaration files (`.d.ts`) from in-memory source code.
+ *
+ * @remarks
+ * This function creates a virtual TypeScript compilation environment to emit declaration
+ * files from macro-expanded code. It sets up a custom compiler host that serves the
+ * transformed source from memory while delegating other file operations to the filesystem.
+ *
+ * **Virtual Compiler Host:**
+ * The custom compiler host intercepts file operations for the target file:
+ * - `getSourceFile`: Returns the in-memory code for the target file, filesystem for others
+ * - `readFile`: Returns the in-memory code for the target file, filesystem for others
+ * - `fileExists`: Reports the target file as existing even though it's virtual
+ *
+ * This approach allows generating declarations for transformed code without writing
+ * intermediate files to disk.
+ *
+ * **Error Handling:**
+ * If declaration emission fails (e.g., due to type errors in the transformed code),
+ * diagnostics are formatted and logged as warnings, and `undefined` is returned.
+ *
+ * @param code - The macro-expanded TypeScript source code
+ * @param fileName - The original file path (used for module resolution and output naming)
+ * @param projectRoot - The project root directory (used for diagnostic formatting)
+ *
+ * @returns The generated declaration file content, or `undefined` if emission failed
+ *         or TypeScript is not available
+ *
+ * @internal
+ */
 function emitDeclarationsFromCode(code, fileName, projectRoot) {
     if (!tsModule) {
         return undefined;
@@ -109,6 +246,7 @@ function emitDeclarationsFromCode(code, fileName, projectRoot) {
     const normalizedFileName = path.resolve(fileName);
     const sourceText = code;
     const compilerHost = tsModule.createCompilerHost(compilerOptions, true);
+    // Override getSourceFile to serve in-memory code for the target file
     compilerHost.getSourceFile = (requestedFileName, languageVersion) => {
         if (path.resolve(requestedFileName) === normalizedFileName) {
             return tsModule.createSourceFile(requestedFileName, sourceText, languageVersion, true);
@@ -118,15 +256,18 @@ function emitDeclarationsFromCode(code, fileName, projectRoot) {
             ? tsModule.createSourceFile(requestedFileName, text, languageVersion, true)
             : undefined;
     };
+    // Override readFile to serve in-memory code for the target file
     compilerHost.readFile = (requestedFileName) => {
         return path.resolve(requestedFileName) === normalizedFileName
             ? sourceText
             : tsModule.sys.readFile(requestedFileName);
     };
+    // Override fileExists to report the virtual file as existing
     compilerHost.fileExists = (requestedFileName) => {
         return (path.resolve(requestedFileName) === normalizedFileName ||
             tsModule.sys.fileExists(requestedFileName));
     };
+    // Capture emitted declaration content
     let output;
     const writeFile = (outputName, text) => {
         if (outputName.endsWith(".d.ts")) {
@@ -135,6 +276,7 @@ function emitDeclarationsFromCode(code, fileName, projectRoot) {
     };
     const program = tsModule.createProgram([normalizedFileName], compilerOptions, compilerHost);
     const emitResult = program.emit(undefined, writeFile, undefined, true);
+    // Log diagnostics if emission was skipped due to errors
     if (emitResult.emitSkipped && emitResult.diagnostics.length > 0) {
         const formatted = tsModule.formatDiagnosticsWithColorAndContext(emitResult.diagnostics, {
             getCurrentDirectory: () => projectRoot,
@@ -146,20 +288,100 @@ function emitDeclarationsFromCode(code, fileName, projectRoot) {
     }
     return output;
 }
+/**
+ * Creates a Vite plugin for Macroforge compile-time macro expansion.
+ *
+ * @remarks
+ * This is the main entry point for integrating Macroforge into a Vite build pipeline.
+ * The plugin:
+ *
+ * 1. **Runs early** (`enforce: "pre"`) to transform code before other plugins
+ * 2. **Processes TypeScript files** (`.ts` and `.tsx`) excluding `node_modules`
+ * 3. **Expands macros** using the Macroforge Rust binary via `expandSync()`
+ * 4. **Generates type definitions** for transformed code (optional, default: enabled)
+ * 5. **Emits metadata** about macro transformations (optional, default: enabled)
+ *
+ * **Plugin Lifecycle:**
+ * - `configResolved`: Initializes project root, loads config, and attempts to load Rust binary
+ * - `transform`: Processes each TypeScript file through the macro expander
+ *
+ * **Error Handling:**
+ * - If the Rust binary is not available, files pass through unchanged
+ * - Macro expansion errors are reported via Vite's `this.error()` mechanism
+ * - TypeScript emission errors are logged as warnings
+ *
+ * @param options - Plugin configuration options
+ *
+ * @returns A Vite plugin instance
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [macroforgePlugin()],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * import macroforgePlugin from '@macroforge/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     macroforgePlugin({
+ *       generateTypes: true,
+ *       typesOutputDir: 'src/types/generated',
+ *       emitMetadata: false,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
 function napiMacrosPlugin(options = {}) {
+    /**
+     * Reference to the loaded Macroforge Rust binary module.
+     * Contains the `expandSync` function for synchronous macro expansion.
+     * Will be `undefined` if the binary failed to load.
+     */
     let rustTransformer;
+    /** The resolved Vite project root directory */
     let projectRoot;
+    /** Loaded configuration from macroforge.json */
     let macroConfig = { keepDecorators: false };
+    // Resolve options with defaults
     const generateTypes = options.generateTypes !== false; // Default to true
     const typesOutputDir = options.typesOutputDir || "src/macros/generated";
     const emitMetadata = options.emitMetadata !== false;
     const metadataOutputDir = options.metadataOutputDir || typesOutputDir;
-    // Ensure directory exists
+    /**
+     * Ensures a directory exists, creating it recursively if necessary.
+     *
+     * @param dir - The directory path to ensure exists
+     */
     function ensureDir(dir) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
     }
+    /**
+     * Writes generated TypeScript declaration files to the configured output directory.
+     *
+     * @remarks
+     * Preserves the source file's directory structure within the output directory.
+     * Implements change detection to avoid unnecessary file writes - only writes
+     * if the content differs from the existing file (or the file doesn't exist).
+     *
+     * Output path formula:
+     * `{projectRoot}/{typesOutputDir}/{relative/path/to/source}/{filename}.d.ts`
+     *
+     * @param id - The absolute path of the source file
+     * @param types - The generated declaration file content
+     */
     function writeTypeDefinitions(id, types) {
         const relativePath = path.relative(projectRoot, id);
         const parsed = path.parse(relativePath);
@@ -179,6 +401,23 @@ function napiMacrosPlugin(options = {}) {
             console.error(`[@macroforge/vite-plugin] Failed to write type definitions for ${id}:`, error);
         }
     }
+    /**
+     * Writes macro intermediate representation (IR) metadata to JSON files.
+     *
+     * @remarks
+     * Preserves the source file's directory structure within the output directory.
+     * Implements change detection to avoid unnecessary file writes - only writes
+     * if the content differs from the existing file (or the file doesn't exist).
+     *
+     * Output path formula:
+     * `{projectRoot}/{metadataOutputDir}/{relative/path/to/source}/{filename}.macro-ir.json`
+     *
+     * The metadata contains information about which macros were applied and their
+     * transformation results, useful for debugging and tooling integration.
+     *
+     * @param id - The absolute path of the source file
+     * @param metadata - The macro IR metadata as a JSON string
+     */
     function writeMetadata(id, metadata) {
         const relativePath = path.relative(projectRoot, id);
         const parsed = path.parse(relativePath);
@@ -198,6 +437,19 @@ function napiMacrosPlugin(options = {}) {
             console.error(`[@macroforge/vite-plugin] Failed to write metadata for ${id}:`, error);
         }
     }
+    /**
+     * Formats transformation errors into user-friendly messages.
+     *
+     * @remarks
+     * Handles both Error instances and unknown error types. For Error instances,
+     * includes the full stack trace if available. Paths are made relative to the
+     * project root for readability.
+     *
+     * @param error - The caught error (can be any type)
+     * @param id - The absolute path of the file that failed to transform
+     *
+     * @returns A formatted error message string with plugin prefix
+     */
     function formatTransformError(error, id) {
         const relative = projectRoot ? path.relative(projectRoot, id) || id : id;
         if (error instanceof Error) {
@@ -209,8 +461,33 @@ function napiMacrosPlugin(options = {}) {
         return `[@macroforge/vite-plugin] Failed to transform ${relative}: ${String(error)}`;
     }
     return {
+        /**
+         * The unique identifier for this plugin.
+         * Used by Vite for plugin ordering and error reporting.
+         */
         name: "@macroforge/vite-plugin",
+        /**
+         * Run this plugin before other plugins.
+         *
+         * @remarks
+         * Macro expansion must happen early in the build pipeline so that
+         * subsequent plugins (like TypeScript compilation) see the expanded code.
+         */
         enforce: "pre",
+        /**
+         * Hook called when Vite config has been resolved.
+         *
+         * @remarks
+         * Performs plugin initialization:
+         * 1. Stores the resolved project root directory
+         * 2. Loads the Macroforge configuration from `macroforge.json`
+         * 3. Attempts to load the Rust macro expander binary
+         *
+         * If the Rust binary fails to load, a warning is logged but the plugin
+         * continues to function (files will pass through unchanged).
+         *
+         * @param config - The resolved Vite configuration
+         */
         configResolved(config) {
             projectRoot = config.root;
             macroConfig = loadMacroConfig(projectRoot);
@@ -223,7 +500,35 @@ function napiMacrosPlugin(options = {}) {
                 console.warn(error);
             }
         },
+        /**
+         * Transform hook for processing TypeScript files through the macro expander.
+         *
+         * @remarks
+         * This is the core of the plugin. For each TypeScript file (`.ts` or `.tsx`):
+         *
+         * 1. **Filtering**: Skips non-TypeScript files and `node_modules`
+         * 2. **Expansion**: Calls the Rust binary's `expandSync()` function
+         * 3. **Diagnostics**: Reports errors via `this.error()`, logs warnings
+         * 4. **Post-processing**: Removes macro-only imports to prevent SSR issues
+         * 5. **Type Generation**: Optionally generates `.d.ts` files
+         * 6. **Metadata Emission**: Optionally writes macro IR JSON files
+         *
+         * **Return Value:**
+         * - Returns `null` if the file should not be transformed (not TS, in node_modules, etc.)
+         * - Returns `{ code, map }` with the transformed code (source maps not yet supported)
+         *
+         * **Error Handling:**
+         * - Macro expansion errors are reported via Vite's error mechanism
+         * - Vite plugin errors are re-thrown to preserve plugin attribution
+         * - Other errors are formatted and reported
+         *
+         * @param code - The source code to transform
+         * @param id - The absolute file path
+         *
+         * @returns Transformed code and source map, or null if no transformation needed
+         */
         async transform(code, id) {
+            // Ensure require() is available for native module loading
             await ensureRequire();
             // Only transform TypeScript files
             if (!id.endsWith(".ts") && !id.endsWith(".tsx")) {
@@ -239,10 +544,11 @@ function napiMacrosPlugin(options = {}) {
                 return null;
             }
             try {
+                // Perform macro expansion via the Rust binary
                 const result = rustTransformer.expandSync(code, id, {
                     keepDecorators: macroConfig.keepDecorators,
                 });
-                // Report diagnostics
+                // Report diagnostics from macro expansion
                 for (const diag of result.diagnostics) {
                     if (diag.level === "error") {
                         const message = `Macro error at ${id}:${diag.start ?? "?"}-${diag.end ?? "?"}: ${diag.message}`;
@@ -255,19 +561,23 @@ function napiMacrosPlugin(options = {}) {
                 }
                 if (result && result.code) {
                     // TODO: Needs complete overhaul and dynamic attribute removal NO HARDCODING
+                    // Decorator removal is currently handled by the Rust binary based on keepDecorators config
                     // if (!macroConfig.keepDecorators) {
                     //   result.code = result.code
                     //     .replace(/\/\*\*\s*@derive[\s\S]*?\*\/\s*/gi, "")
                     //     .replace(/\/\*\*\s*@debug[\s\S]*?\*\/\s*/gi, "");
                     // }
                     // Remove macro-only imports so SSR output doesn't load native bindings
+                    // These imports are only needed at compile-time for type checking
                     result.code = result.code.replace(/\/\*\*\s*import\s+macro[\s\S]*?\*\/\s*/gi, "");
+                    // Generate type definitions if enabled
                     if (generateTypes) {
                         const emitted = emitDeclarationsFromCode(result.code, id, projectRoot);
                         if (emitted) {
                             writeTypeDefinitions(id, emitted);
                         }
                     }
+                    // Write macro IR metadata if enabled
                     if (emitMetadata && result.metadata) {
                         writeMetadata(id, result.metadata);
                     }
@@ -278,9 +588,11 @@ function napiMacrosPlugin(options = {}) {
                 }
             }
             catch (error) {
+                // Re-throw Vite plugin errors to preserve plugin attribution
                 if (error && typeof error === "object" && "plugin" in error) {
                     throw error;
                 }
+                // Format and report other errors
                 const message = formatTransformError(error, id);
                 this.error(message);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroforge/vite-plugin",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,7 @@
     "test": "npm run build && node --test tests/**/*.test.js"
   },
   "dependencies": {
-    "macroforge": "^0.1.33"
+    "macroforge": "^0.1.34"
   },
   "devDependencies": {
     "typescript": "^5.9.3",