macroforge 0.1.32 → 0.1.34

package/README.md

@@ -1,368 +1,101 @@
-# macroforge
+# macroforge_ts
 
-> **Warning:** This is a work in progress and probably won't work for you. Use at your own risk!
+TypeScript macro expansion engine - write compile-time macros in Rust
 
-TypeScript macro expansion engine powered by Rust and SWC.
+[![Crates.io](https://img.shields.io/crates/v/macroforge_ts.svg)](https://crates.io/crates/macroforge_ts)
+[![Documentation](https://docs.rs/macroforge_ts/badge.svg)](https://docs.rs/macroforge_ts)
 
-## Overview
-
-`macroforge` is a native Node.js module that enables compile-time code generation for TypeScript through a Rust-like derive macro system. It parses TypeScript using SWC, expands macros written in Rust, and outputs transformed TypeScript code with full source mapping support.
-
-## Installation
-
-```bash
-npm install macroforge
-```
+This crate provides a TypeScript macro expansion engine that brings Rust-like derive macros
+to TypeScript. It is designed to be used via NAPI bindings from Node.js, enabling compile-time
+code generation for TypeScript projects.
 
-The package includes pre-built binaries for:
-- macOS (x64, arm64)
-- Linux (x64, arm64)
-- Windows (x64, arm64)
-
-## Quick Start
-
-### Using Built-in Macros
+## Overview
 
-```typescript
-import { Derive, Debug, Clone, Eq } from "macroforge";
+Macroforge processes TypeScript source files containing `@derive` decorators and expands them
+into concrete implementations. For example, a class decorated with `@derive(Debug, Clone)`
+will have `toString()` and `clone()` methods automatically generated.
 
-/** @derive(Debug, Clone, Eq) */
-class User {
-  name: string;
-  age: number;
+## Architecture
 
-  constructor(name: string, age: number) {
-    this.name = name;
-    this.age = age;
-  }
-}
+The crate is organized into several key components:
 
-// After macro expansion, the class gains:
-// - toString(): string           (from Debug)
-// - clone(): User                (from Clone)
-// - equals(other: User): boolean (from Eq)
-```
+- **NAPI Bindings** (`NativePlugin`, `expand_sync`, `transform_sync`): Entry points for Node.js
+- **Position Mapping** (`NativePositionMapper`, `NativeMapper`): Bidirectional source mapping
+  for IDE integration
+- **Macro Host** (`host` module): Core expansion engine with registry and dispatcher
+- **Built-in Macros** (`builtin` module): Standard derive macros (Debug, Clone, Serialize, etc.)
 
-### Programmatic API
+## Performance Considerations
 
-```typescript
-import { expandSync, NativePlugin } from "macroforge";
+- Uses a 32MB thread stack to prevent stack overflow during deep SWC AST recursion
+- Implements early bailout for files without `@derive` decorators
+- Caches expansion results keyed by filepath and version
+- Uses binary search for O(log n) position mapping lookups
 
-// One-shot expansion
-const result = expandSync(sourceCode, "file.ts", {
-  keepDecorators: false
-});
+## Usage from Node.js
 
-console.log(result.code);        // Transformed TypeScript
-console.log(result.diagnostics); // Any warnings/errors
-console.log(result.metadata);    // Macro IR metadata (JSON)
+```javascript
+const { NativePlugin, expand_sync } = require('macroforge-ts');
 
-// Cached expansion (for language servers)
+// Create a plugin instance with caching
 const plugin = new NativePlugin();
-const cached = plugin.processFile("file.ts", sourceCode, {
-  version: "1.0.0" // Cache key
-});
-```
-
-## API Reference
-
-### Core Functions
-
-#### `expandSync(code, filepath, options?)`
-
-Expands macros in TypeScript code synchronously.
-
-```typescript
-function expandSync(
-  code: string,
-  filepath: string,
-  options?: ExpandOptions
-): ExpandResult;
-
-interface ExpandOptions {
-  keepDecorators?: boolean; // Keep @derive decorators in output (default: false)
-}
-
-interface ExpandResult {
-  code: string;                        // Transformed TypeScript
-  types?: string;                      // Generated .d.ts content
-  metadata?: string;                   // Macro IR as JSON
-  diagnostics: MacroDiagnostic[];      // Warnings and errors
-  sourceMapping?: SourceMappingResult; // Position mapping data
-}
-```
-
-#### `transformSync(code, filepath)`
-
-Lower-level transform that returns additional metadata.
 
-```typescript
-function transformSync(code: string, filepath: string): TransformResult;
+// Process a file (uses cache if version matches)
+const result = plugin.process_file(filepath, code, { version: '1.0' });
 
-interface TransformResult {
-  code: string;
-  map?: string;    // Source map (not yet implemented)
-  types?: string;  // Generated declarations
-  metadata?: string;
-}
+// Or use the sync function directly
+const result = expand_sync(code, filepath, { keep_decorators: false });
 ```
 
-#### `checkSyntax(code, filepath)`
+## Re-exports for Macro Authors
 
-Validates TypeScript syntax without macro expansion.
-
-```typescript
-function checkSyntax(code: string, filepath: string): SyntaxCheckResult;
-
-interface SyntaxCheckResult {
-  ok: boolean;
-  error?: string;
-}
-```
-
-#### `parseImportSources(code, filepath)`
-
-Extracts import information from TypeScript code.
-
-```typescript
-function parseImportSources(code: string, filepath: string): ImportSourceResult[];
-
-interface ImportSourceResult {
-  local: string;  // Local identifier name
-  module: string; // Module specifier
-}
-```
-
-### Classes
-
-#### `NativePlugin`
-
-Stateful plugin with caching for language server integration.
-
-```typescript
-class NativePlugin {
-  constructor();
-
-  // Process file with version-based caching
-  processFile(
-    filepath: string,
-    code: string,
-    options?: ProcessFileOptions
-  ): ExpandResult;
-
-  // Get position mapper for a cached file
-  getMapper(filepath: string): NativeMapper | null;
-
-  // Map diagnostics from expanded to original positions
-  mapDiagnostics(filepath: string, diags: JsDiagnostic[]): JsDiagnostic[];
-
-  // Logging utilities
-  log(message: string): void;
-  setLogFile(path: string): void;
-}
-```
-
-#### `NativeMapper` / `PositionMapper`
-
-Maps positions between original and expanded code.
-
-```typescript
-class NativeMapper {
-  constructor(mapping: SourceMappingResult);
-
-  isEmpty(): boolean;
-  originalToExpanded(pos: number): number;
-  expandedToOriginal(pos: number): number | null;
-  generatedBy(pos: number): string | null;
-  mapSpanToOriginal(start: number, length: number): SpanResult | null;
-  mapSpanToExpanded(start: number, length: number): SpanResult;
-  isInGenerated(pos: number): boolean;
-}
-```
+This crate re-exports several dependencies for convenience when writing custom macros:
+- `ts_syn`: TypeScript syntax types for AST manipulation
+- `macros`: Macro attributes and quote templates
+- `swc_core`, `swc_common`, `swc_ecma_ast`: SWC compiler infrastructure
 
-### Built-in Decorators
-
-| Decorator | Description |
-|-----------|-------------|
-| `@Derive(...features)` | Class decorator that triggers macro expansion |
-| `@Debug` | Generates `toString(): string` method |
-| `@Clone` | Generates `clone(): T` method |
-| `@Eq` | Generates `equals(other: T): boolean` method |
-
-## Writing Custom Macros
-
-Custom macros are written in Rust and compiled to native Node.js addons. See the [playground/macro](../../playground/macro) directory for examples.
+## Installation
 
-### Minimal Macro Crate
+Add this to your `Cargo.toml`:
 
-**Cargo.toml:**
 ```toml
-[package]
-name = "my-macros"
-version = "0.1.0"
-edition = "2024"
-
-[lib]
-crate-type = ["cdylib"]
-
 [dependencies]
-macroforge_ts = "0.1.0"
-napi = { version = "3.5.2", features = ["napi8", "compat-mode"] }
-napi-derive = "3.3.3"
-
-[build-dependencies]
-napi-build = "2.3.1"
-```
-
-**src/lib.rs:**
-```rust
-use macroforge_ts::macros::{ts_macro_derive, body};
-use macroforge_ts::ts_syn::{
-    Data, DeriveInput, MacroforgeError, TsStream, parse_ts_macro_input,
-};
-
-#[ts_macro_derive(
-    JSON,
-    description = "Generates toJSON() returning a plain object"
-)]
-pub fn derive_json(mut input: TsStream) -> Result<TsStream, MacroforgeError> {
-    let input = parse_ts_macro_input!(input as DeriveInput);
-
-    match &input.data {
-        Data::Class(class) => {
-            Ok(body! {
-                toJSON(): Record<string, unknown> {
-                    return {
-                        {#for field in class.field_names()}
-                            @{field}: this.@{field},
-                        {/for}
-                    };
-                }
-            })
-        }
-        _ => Err(MacroforgeError::new(
-            input.decorator_span(),
-            "@derive(JSON) only works on classes",
-        )),
-    }
-}
-```
-
-### Template Syntax
-
-The `ts_template!` and `body!` macros support:
-
-| Syntax | Description |
-|--------|-------------|
-| `@{expr}` | Interpolate Rust expression as identifier/code |
-| `{#for x in iter}...{/for}` | Loop over iterables |
-| `{$let name = expr}` | Local variable binding |
-| `{#if cond}...{/if}` | Conditional blocks |
-
-### Re-exported Crates
-
-`macroforge_ts` re-exports everything needed for macro development:
-
-```rust
-// TypeScript syntax types
-use macroforge_ts::ts_syn::*;
-
-// Macro attributes and quote templates
-use macroforge_ts::macros::{ts_macro_derive, body, ts_template, above, below};
-
-// SWC modules (for advanced use)
-use macroforge_ts::swc_core;
-use macroforge_ts::swc_common;
-use macroforge_ts::swc_ecma_ast;
-```
-
-## Integration
+macroforge_ts = "0.1.33"
+```
+
+## Key Exports
+
+### Structs
+
+- **`TransformResult`** - Result of transforming TypeScript code through the macro system.
+- **`MacroDiagnostic`** - A diagnostic message produced during macro expansion.
+- **`MappingSegmentResult`** - A segment mapping a range in the original source to a range in the expanded source.
+- **`GeneratedRegionResult`** - A region in the expanded source that was generated by a macro.
+- **`SourceMappingResult`** - Complete source mapping information for a macro expansion.
+- **`ExpandResult`** - Result of expanding macros in TypeScript source code.
+- **`ImportSourceResult`** - Information about an imported identifier from a TypeScript module.
+- **`SyntaxCheckResult`** - Result of checking TypeScript syntax validity.
+- **`SpanResult`** - A span (range) in source code, represented as start position and length.
+- **`JsDiagnostic`** - A diagnostic from the TypeScript/JavaScript compiler or IDE.
+- ... and 8 more
+
+### Functions
+
+- **`unchanged`** - Creates a no-op result with the original code unchanged.
+- **`new`** - Creates a new position mapper from source mapping data.
+- **`is_empty`** - Checks if this mapper has no mapping data.
+- **`original_to_expanded`** - Converts a position in the original source to the corresponding position in expanded source.
+- **`expanded_to_original`** - Converts a position in the expanded source back to the original source position.
+- **`generated_by`** - Returns the name of the macro that generated code at the given position.
+- **`map_span_to_original`** - Maps a span (start + length) from expanded source to original source.
+- **`map_span_to_expanded`** - Maps a span (start + length) from original source to expanded source.
+- **`is_in_generated`** - Checks if a position is inside macro-generated code.
+- **`new`** - Creates a new mapper wrapping the given source mapping.
+- ... and 23 more
 
-### Vite Plugin
-
-```typescript
-// vite.config.ts
-import macroforge from "@macroforge/vite-plugin";
-
-export default defineConfig({
-  plugins: [
-    macroforge({
-      typesOutputDir: ".macroforge/types",
-      metadataOutputDir: ".macroforge/meta",
-      generateTypes: true,
-      emitMetadata: true,
-    }),
-  ],
-});
-```
-
-### TypeScript Plugin
-
-Add to `tsconfig.json` for IDE support:
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "name": "@macroforge/typescript-plugin"
-      }
-    ]
-  }
-}
-```
-
-## Debug API
-
-For debugging macro registration:
-
-```typescript
-import {
-  __macroforgeGetManifest,
-  __macroforgeGetMacroNames,
-  __macroforgeIsMacroPackage,
-  __macroforgeDebugDescriptors,
-  __macroforgeDebugLookup,
-} from "macroforge";
-
-// Get all registered macros
-const manifest = __macroforgeGetManifest();
-console.log(manifest.macros);
-
-// Check if current package exports macros
-console.log(__macroforgeIsMacroPackage());
-
-// List macro names
-console.log(__macroforgeGetMacroNames());
-
-// Debug lookup
-console.log(__macroforgeDebugLookup("@my/macros", "JSON"));
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Node.js / Vite                       │
-├─────────────────────────────────────────────────────────┤
-│                   NAPI-RS Bindings                      │
-├─────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
-│  │   ts_syn    │  │   ts_quote   │  │ts_macro_derive│  │
-│  │  (parsing)  │  │ (templating) │  │  (proc-macro) │  │
-│  └─────────────┘  └──────────────┘  └───────────────┘  │
-├─────────────────────────────────────────────────────────┤
-│                    SWC Core                             │
-│            (TypeScript parsing & codegen)               │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Performance
+## API Reference
 
-- **Thread-safe expansion**: Each expansion runs in an isolated thread with a 32MB stack to handle deep AST recursion
-- **Caching**: `NativePlugin` caches expansion results by file version
-- **Binary search**: Position mapping uses O(log n) lookups
-- **Zero-copy parsing**: SWC's arena allocator minimizes allocations
+See the [full API documentation](https://macroforge.dev/docs/api/reference/rust/macroforge_ts) on the Macroforge website.
 
 ## License