@macroforge/typescript-plugin 0.1.33 → 0.1.34

package/README.md

@@ -1,10 +1,53 @@
 # @macroforge/typescript-plugin
 
-> **Warning:** This is a work in progress and probably won't work for you. Use at your own risk!
+TypeScript language service plugin that augments classes decorated with @derive to include macro-generated methods.
 
-TypeScript language service plugin for macroforge compile-time macros.
+[![npm version](https://badge.fury.io/js/%40macroforge%2Ftypescript-plugin.svg)](https://www.npmjs.com/package/@macroforge/typescript-plugin)
 
-Part of the [macroforge](https://github.com/rymskip/macroforge-ts) project.
+## Overview
+
+TypeScript Language Service Plugin for Macroforge
+
+This plugin integrates Macroforge's compile-time macro expansion with TypeScript's
+Language Service to provide seamless IDE support for macro-decorated classes.
+
+## Architecture Overview
+
+The plugin operates by intercepting TypeScript's Language Service methods and
+transforming source code on-the-fly:
+
+1. **Macro Expansion**: When TypeScript requests a file's content via `getScriptSnapshot`,
+this plugin intercepts the call and returns the macro-expanded version instead.
+
+2. **Position Mapping**: Since expanded code has different positions than the original,
+the plugin maintains a {@link PositionMapper} for each file to translate positions
+between original and expanded coordinates.
+
+3. **Virtual .d.ts Files**: For each macro-containing file, the plugin generates a
+companion `.macroforge.d.ts` file containing type declarations for generated methods.
+
+## Supported File Types
+
+- `.ts` - TypeScript files
+- `.tsx` - TypeScript JSX files
+- `.svelte` - Svelte components (with `<script lang="ts">`)
+
+## Hook Categories
+
+The plugin hooks into three categories of Language Service methods:
+
+- **Host-level hooks**: Control what TypeScript "sees" (`getScriptSnapshot`, `fileExists`, etc.)
+- **Diagnostic hooks**: Map error positions back to original source (`getSemanticDiagnostics`)
+- **Navigation hooks**: Handle go-to-definition, references, completions, etc.
+
+@example
+```typescript
+{
+"compilerOptions": {
+"plugins": [{ "name": "@macroforge/typescript-plugin" }]
+}
+}
+```
 
 ## Installation
 
@@ -12,20 +55,40 @@ Part of the [macroforge](https://github.com/rymskip/macroforge-ts) project.
 npm install @macroforge/typescript-plugin
 ```
 
-## Usage
+## API
+
+### Functions
 
-Add to your `tsconfig.json`:
+- **`findDeriveAtPosition`** - Finds a macro name within `@derive(...)` decorators at a given cursor position.
+- **`findDecoratorAtPosition`** - Finds a field decorator (like `@serde` or `@debug`) at a given cursor position.
+- **`getMacroHoverInfo`** - const lastCommentEnd = beforeMatch.lastIndexOf("*/
+- **`shouldProcess`** - Determines whether a file should be processed for macro expansion.
+- **`hasMacroDirectives`** - Performs a quick check to determine if a file contains any macro-related directives.
+- **`loadMacroConfig`** - Whether to preserve decorator syntax in the expanded output.
+- **`init`** - Main plugin factory function conforming to the TypeScript Language Service Plugin API.
+- **`create`** - Creates the plugin instance for a TypeScript project.
+- **`processFile`** - Processes a file through macro expansion via the native Rust plugin.
+- **`toPlainDiagnostic`** - Converts a TypeScript diagnostic to a plain object for the native plugin.
+- ... and 1 more
 
-```json
+### Types
+
+- **`MacroConfig`** - Configuration options loaded from `macroforge.json`.
+
+## Examples
+
+```typescript
 {
-  "compilerOptions": {
-    "plugins": [
-      { "name": "@macroforge/typescript-plugin" }
-    ]
-  }
+"compilerOptions": {
+"plugins": [{ "name": "@macroforge/typescript-plugin" }]
+}
 }
 ```
 
+## Documentation
+
+See the [full documentation](https://macroforge.dev/docs/api/reference/typescript/typescript-plugin) on the Macroforge website.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,111 @@
+/**
+ * @fileoverview TypeScript Language Service Plugin for Macroforge
+ *
+ * This plugin integrates Macroforge's compile-time macro expansion with TypeScript's
+ * Language Service to provide seamless IDE support for macro-decorated classes.
+ *
+ * ## Architecture Overview
+ *
+ * The plugin operates by intercepting TypeScript's Language Service methods and
+ * transforming source code on-the-fly:
+ *
+ * 1. **Macro Expansion**: When TypeScript requests a file's content via `getScriptSnapshot`,
+ *    this plugin intercepts the call and returns the macro-expanded version instead.
+ *
+ * 2. **Position Mapping**: Since expanded code has different positions than the original,
+ *    the plugin maintains a {@link PositionMapper} for each file to translate positions
+ *    between original and expanded coordinates.
+ *
+ * 3. **Virtual .d.ts Files**: For each macro-containing file, the plugin generates a
+ *    companion `.macroforge.d.ts` file containing type declarations for generated methods.
+ *
+ * ## Supported File Types
+ *
+ * - `.ts` - TypeScript files
+ * - `.tsx` - TypeScript JSX files
+ * - `.svelte` - Svelte components (with `<script lang="ts">`)
+ *
+ * ## Hook Categories
+ *
+ * The plugin hooks into three categories of Language Service methods:
+ *
+ * - **Host-level hooks**: Control what TypeScript "sees" (`getScriptSnapshot`, `fileExists`, etc.)
+ * - **Diagnostic hooks**: Map error positions back to original source (`getSemanticDiagnostics`)
+ * - **Navigation hooks**: Handle go-to-definition, references, completions, etc.
+ *
+ * @example
+ * ```typescript
+ * // tsconfig.json
+ * {
+ *   "compilerOptions": {
+ *     "plugins": [{ "name": "@macroforge/typescript-plugin" }]
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link init} - The main plugin factory function
+ * @see {@link PositionMapper} - Position mapping between original and expanded code
+ * @module @macroforge/typescript-plugin
+ */
 import type ts from "typescript/lib/tsserverlibrary";
+/**
+ * Main plugin factory function conforming to the TypeScript Language Service Plugin API.
+ *
+ * This function is called by TypeScript when the plugin is loaded. It receives the
+ * TypeScript module reference and returns an object with a `create` function that
+ * TypeScript will call to instantiate the plugin for each project.
+ *
+ * @param modules - Object containing the TypeScript module reference
+ * @param modules.typescript - The TypeScript module (`typescript/lib/tsserverlibrary`)
+ * @returns An object with a `create` method that TypeScript calls to instantiate the plugin
+ *
+ * @remarks
+ * The plugin follows the standard TypeScript Language Service Plugin pattern:
+ * 1. `init()` is called once when the plugin is loaded
+ * 2. `create()` is called for each TypeScript project that uses the plugin
+ * 3. The returned LanguageService has hooked methods that intercept TypeScript operations
+ *
+ * ## Plugin Architecture
+ *
+ * The plugin maintains several internal data structures:
+ * - **virtualDtsFiles**: Stores generated `.macroforge.d.ts` type declaration files
+ * - **snapshotCache**: Caches expanded file snapshots for stable identity across TS requests
+ * - **processingFiles**: Guards against reentrancy during macro expansion
+ * - **nativePlugin**: Rust-backed expansion engine (handles actual macro processing)
+ *
+ * ## Hooked Methods
+ *
+ * The plugin hooks into ~22 TypeScript Language Service methods to provide seamless
+ * IDE support. These fall into three categories:
+ *
+ * 1. **Host-level hooks** (what TS "sees"):
+ *    - `getScriptSnapshot` - Returns expanded code instead of original
+ *    - `getScriptVersion` - Provides versions for virtual .d.ts files
+ *    - `getScriptFileNames` - Includes virtual .d.ts in project file list
+ *    - `fileExists` - Resolves virtual .d.ts files
+ *
+ * 2. **Diagnostic hooks** (error reporting):
+ *    - `getSemanticDiagnostics` - Maps error positions, adds macro errors
+ *    - `getSyntacticDiagnostics` - Maps syntax error positions
+ *
+ * 3. **Navigation hooks** (IDE features):
+ *    - `getQuickInfoAtPosition` - Hover information
+ *    - `getCompletionsAtPosition` - IntelliSense completions
+ *    - `getDefinitionAtPosition` - Go to definition
+ *    - `findReferences` - Find all references
+ *    - ... and many more
+ *
+ * @example
+ * ```typescript
+ * // This is how TypeScript loads the plugin (internal to TS)
+ * const plugin = require('@macroforge/typescript-plugin');
+ * const { create } = plugin(modules);
+ * const languageService = create(pluginCreateInfo);
+ * ```
+ *
+ * @see {@link shouldProcess} - File filtering logic
+ * @see {@link processFile} - Main macro expansion entry point
+ */
 declare function init(modules: {
     typescript: typeof ts;
 }): {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAoOrD,iBAAS,IAAI,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE;mBACxB,EAAE,CAAC,MAAM,CAAC,gBAAgB;EAgoDjD;AAED,SAAS,IAAI,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAmdrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,iBAAS,IAAI,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE;mBAcxB,EAAE,CAAC,MAAM,CAAC,gBAAgB;EA69DjD;AAED,SAAS,IAAI,CAAC"}