macroforge 0.1.78 → 0.1.80

package/README.md

@@ -5,9 +5,13 @@ TypeScript macro expansion engine - write compile-time macros in Rust
 [![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
+
 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.
+TypeScript. It supports multiple output targets via feature flags:
+
+- `wasm`: (Default) Universal WebAssembly module via wasm-bindgen for browser and edge environments.
+- `node`: Optional native Node.js bindings via NAPI-RS.
 
 ## Overview
 
@@ -19,31 +23,30 @@ concrete implementations. For example, a class decorated with `@derive(Debug, Cl
 
 The crate is organized into several key components:
 
-- **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.)
-
-## Performance Considerations
+- **Unified API** (`api` module): An output-agnostic trait-based interface (`MacroforgeApi`) that
+  defines all macro operations.
+- **Target Bindings**:
+  - `bindings_napi`: Node.js specific entry points using NAPI-RS.
+  - `bindings_wasm`: Universal entry points using `wasm-bindgen`.
+- **Position Mapping** (`api_types::SourceMappingResult`): 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.).
 
-- 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
+## Usage
 
-## Usage from Node.js
+### From Node.js
 
 ```javascript
-const { NativePlugin, expand_sync } = require('macroforge-ts');
-
-// Create a plugin instance with caching
-const plugin = new NativePlugin();
+const { expandSync } = require('macroforge');
+const result = expandSync(code, filepath, { keep_decorators: false });
+```
 
-// Process a file (uses cache if version matches)
-const result = plugin.process_file(filepath, code, { version: '1.0' });
+### From WASM
 
-// Or use the sync function directly
+```javascript
+import init, { expand_sync } from './pkg/macroforge_ts.js';
+await init();
 const result = expand_sync(code, filepath, { keep_decorators: false });
 ```
 
@@ -53,7 +56,7 @@ This crate re-exports several dependencies for convenience when writing custom m
 
 - `ts_syn`: TypeScript syntax types for AST manipulation
 - `macros`: Macro attributes and quote templates
-- `swc_core`, `swc_common`, `swc_ecma_ast`: SWC compiler infrastructure
+- `swc_core`, `swc_common`, `swc_ecma_ast`: SWC compatibility infrastructure
 
 ## Installation
 
@@ -61,41 +64,15 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-macroforge_ts = "0.1.38"
+macroforge_ts = "0.1.79"
 ```
 
 ## 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
+- **`__macroforge_ffi_free`** - Free a buffer allocated by an FFI function.
+- **`__macroforge_ffi_get_manifest`** - Returns the full MacroManifest as JSON via FFI.
 
 ## API Reference
 

package/js/buildtime/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * # Macroforge Buildtime Module
+ *
+ * Compile-time JavaScript evaluation — the Zig-comptime primitive for
+ * TypeScript. Annotate a top-level `const` or `function` declaration with
+ * `/** @buildtime *\/` and the macroforge build pass evaluates it in a
+ * sandboxed JS context, serializes the result, and splices a plain TS
+ * literal back into the module.
+ *
+ * ```ts
+ * /** @buildtime *\/
+ * const BUILT_AT = buildtime.time.iso();
+ *
+ * /** @buildtime *\/
+ * const SCHEMA = buildtime.fs.readJson("./schema.json");
+ *
+ * /** @buildtime *\/
+ * function generateValidators() {
+ *   const schema = buildtime.fs.readJson("./schema.json");
+ *   return schema.fields.map(f =>
+ *     `export function is_${f.name}(v: unknown): v is ${f.type} {
+ *        return typeof v === "${f.jsType}";
+ *      }`
+ *   ).join("\n");
+ * }
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * Every export from this module is a sentinel. Calling any of them at
+ * runtime throws — they should have been resolved by the macroforge
+ * build pass and no longer exist in the output. If you see the runtime
+ * error, the build pass is not running on this file.
+ *
+ * @module macroforge/buildtime
+ */
+export interface BuildtimeFs {
+    /** Read a file as UTF-8 text. Path is resolved relative to the file the
+     *  @buildtime declaration lives in. Throws if the path is not in the
+     *  `buildtime.capabilities.filesystem.read` allowlist. */
+    readText(path: string): string;
+    /** Read a file and parse its content as JSON. Same capability rules
+     *  as `readText`. */
+    readJson(path: string): unknown;
+    /** Return whether the path exists on disk. Counts as a read for
+     *  dependency tracking — if the file appears later, the cache
+     *  invalidates. */
+    exists(path: string): boolean;
+    /** Return the names of the entries in a directory, sorted. Counts as
+     *  a read. */
+    listDir(path: string): string[];
+}
+export interface BuildtimeCrypto {
+    /** SHA-256 of the input, lowercase hex. Pure — always allowed. */
+    sha256(input: string): string;
+    /** SHA-512 of the input, lowercase hex. Pure — always allowed. */
+    sha512(input: string): string;
+}
+export interface BuildtimeTime {
+    /** Current wall-clock time as an ISO 8601 string. Makes builds
+     *  non-deterministic — prefer recording a fixed timestamp if
+     *  determinism matters. */
+    now(): string;
+    /** Current wall-clock time in unix seconds. */
+    unix(): number;
+    /** Alias for {@link BuildtimeTime.now}. */
+    iso(): string;
+}
+export interface BuildtimeFlags {
+    /** True if the named flag was passed to the build (e.g. from a
+     *  `--define` argument or from `config.buildtime.flags`). */
+    has(flag: string): boolean;
+    /** Value of the named flag, or undefined if not set. */
+    get(flag: string): string | undefined;
+}
+export interface BuildtimeLocation {
+    /** Absolute path of the source file the @buildtime declaration
+     *  lives in. */
+    readonly file: string;
+    /** 1-based line number of the `/** @buildtime *\/` annotation. */
+    readonly line: number;
+    /** 1-based column number of the annotation. */
+    readonly column: number;
+}
+export interface Buildtime {
+    readonly fs: BuildtimeFs;
+    readonly crypto: BuildtimeCrypto;
+    readonly time: BuildtimeTime;
+    /** Environment variables the build was allowed to read. Populated
+     *  from `buildtime.capabilities.env` in macroforge.config.js. Reads
+     *  of variables not in the allowlist return `undefined`. */
+    readonly env: Record<string, string | undefined>;
+    readonly flags: BuildtimeFlags;
+    readonly location: BuildtimeLocation;
+}
+/**
+ * The compile-time API. Inside a `@buildtime` declaration, calls
+ * against this object are routed to native implementations. At
+ * runtime, every access throws — see module docs for why.
+ */
+export declare const buildtime: Buildtime;
+/**
+ * Re-export with the name `$buildtime` for users who prefer the macroforge
+ * convention of prefixing compile-time identifiers with `$`. Points at the
+ * same object.
+ */
+export declare const $buildtime: Buildtime;

package/js/buildtime/index.mjs

@@ -0,0 +1,65 @@
+// js/buildtime/index.ts
+var runtimeError = (method) => new Error(
+  `macroforge/buildtime.${method}: @buildtime APIs are only available inside @buildtime declarations evaluated by macroforge. If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file.`
+);
+var buildtime = {
+  fs: {
+    readText(_path) {
+      throw runtimeError("fs.readText");
+    },
+    readJson(_path) {
+      throw runtimeError("fs.readJson");
+    },
+    exists(_path) {
+      throw runtimeError("fs.exists");
+    },
+    listDir(_path) {
+      throw runtimeError("fs.listDir");
+    }
+  },
+  crypto: {
+    sha256(_input) {
+      throw runtimeError("crypto.sha256");
+    },
+    sha512(_input) {
+      throw runtimeError("crypto.sha512");
+    }
+  },
+  time: {
+    now() {
+      throw runtimeError("time.now");
+    },
+    unix() {
+      throw runtimeError("time.unix");
+    },
+    iso() {
+      throw runtimeError("time.iso");
+    }
+  },
+  env: new Proxy(
+    {},
+    {
+      get(_target, _prop) {
+        throw runtimeError("env");
+      }
+    }
+  ),
+  flags: {
+    has(_flag) {
+      throw runtimeError("flags.has");
+    },
+    get(_flag) {
+      throw runtimeError("flags.get");
+    }
+  },
+  location: new Proxy({}, {
+    get(_target, _prop) {
+      throw runtimeError("location");
+    }
+  })
+};
+var $buildtime = buildtime;
+export {
+  $buildtime,
+  buildtime
+};

package/js/buildtime/index.ts

@@ -0,0 +1,176 @@
+/**
+ * # Macroforge Buildtime Module
+ *
+ * Compile-time JavaScript evaluation — the Zig-comptime primitive for
+ * TypeScript. Annotate a top-level `const` or `function` declaration with
+ * `/** @buildtime *\/` and the macroforge build pass evaluates it in a
+ * sandboxed JS context, serializes the result, and splices a plain TS
+ * literal back into the module.
+ *
+ * ```ts
+ * /** @buildtime *\/
+ * const BUILT_AT = buildtime.time.iso();
+ *
+ * /** @buildtime *\/
+ * const SCHEMA = buildtime.fs.readJson("./schema.json");
+ *
+ * /** @buildtime *\/
+ * function generateValidators() {
+ *   const schema = buildtime.fs.readJson("./schema.json");
+ *   return schema.fields.map(f =>
+ *     `export function is_${f.name}(v: unknown): v is ${f.type} {
+ *        return typeof v === "${f.jsType}";
+ *      }`
+ *   ).join("\n");
+ * }
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * Every export from this module is a sentinel. Calling any of them at
+ * runtime throws — they should have been resolved by the macroforge
+ * build pass and no longer exist in the output. If you see the runtime
+ * error, the build pass is not running on this file.
+ *
+ * @module macroforge/buildtime
+ */
+
+const runtimeError = (method: string) =>
+  new Error(
+    `macroforge/buildtime.${method}: @buildtime APIs are only available inside @buildtime declarations evaluated by macroforge. ` +
+      `If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file.`,
+  );
+
+export interface BuildtimeFs {
+  /** Read a file as UTF-8 text. Path is resolved relative to the file the
+   *  @buildtime declaration lives in. Throws if the path is not in the
+   *  `buildtime.capabilities.filesystem.read` allowlist. */
+  readText(path: string): string;
+  /** Read a file and parse its content as JSON. Same capability rules
+   *  as `readText`. */
+  readJson(path: string): unknown;
+  /** Return whether the path exists on disk. Counts as a read for
+   *  dependency tracking — if the file appears later, the cache
+   *  invalidates. */
+  exists(path: string): boolean;
+  /** Return the names of the entries in a directory, sorted. Counts as
+   *  a read. */
+  listDir(path: string): string[];
+}
+
+export interface BuildtimeCrypto {
+  /** SHA-256 of the input, lowercase hex. Pure — always allowed. */
+  sha256(input: string): string;
+  /** SHA-512 of the input, lowercase hex. Pure — always allowed. */
+  sha512(input: string): string;
+}
+
+export interface BuildtimeTime {
+  /** Current wall-clock time as an ISO 8601 string. Makes builds
+   *  non-deterministic — prefer recording a fixed timestamp if
+   *  determinism matters. */
+  now(): string;
+  /** Current wall-clock time in unix seconds. */
+  unix(): number;
+  /** Alias for {@link BuildtimeTime.now}. */
+  iso(): string;
+}
+
+export interface BuildtimeFlags {
+  /** True if the named flag was passed to the build (e.g. from a
+   *  `--define` argument or from `config.buildtime.flags`). */
+  has(flag: string): boolean;
+  /** Value of the named flag, or undefined if not set. */
+  get(flag: string): string | undefined;
+}
+
+export interface BuildtimeLocation {
+  /** Absolute path of the source file the @buildtime declaration
+   *  lives in. */
+  readonly file: string;
+  /** 1-based line number of the `/** @buildtime *\/` annotation. */
+  readonly line: number;
+  /** 1-based column number of the annotation. */
+  readonly column: number;
+}
+
+export interface Buildtime {
+  readonly fs: BuildtimeFs;
+  readonly crypto: BuildtimeCrypto;
+  readonly time: BuildtimeTime;
+  /** Environment variables the build was allowed to read. Populated
+   *  from `buildtime.capabilities.env` in macroforge.config.js. Reads
+   *  of variables not in the allowlist return `undefined`. */
+  readonly env: Record<string, string | undefined>;
+  readonly flags: BuildtimeFlags;
+  readonly location: BuildtimeLocation;
+}
+
+/**
+ * The compile-time API. Inside a `@buildtime` declaration, calls
+ * against this object are routed to native implementations. At
+ * runtime, every access throws — see module docs for why.
+ */
+export const buildtime: Buildtime = {
+  fs: {
+    readText(_path: string): string {
+      throw runtimeError("fs.readText");
+    },
+    readJson(_path: string): unknown {
+      throw runtimeError("fs.readJson");
+    },
+    exists(_path: string): boolean {
+      throw runtimeError("fs.exists");
+    },
+    listDir(_path: string): string[] {
+      throw runtimeError("fs.listDir");
+    },
+  },
+  crypto: {
+    sha256(_input: string): string {
+      throw runtimeError("crypto.sha256");
+    },
+    sha512(_input: string): string {
+      throw runtimeError("crypto.sha512");
+    },
+  },
+  time: {
+    now(): string {
+      throw runtimeError("time.now");
+    },
+    unix(): number {
+      throw runtimeError("time.unix");
+    },
+    iso(): string {
+      throw runtimeError("time.iso");
+    },
+  },
+  env: new Proxy(
+    {},
+    {
+      get(_target, _prop): never {
+        throw runtimeError("env");
+      },
+    },
+  ),
+  flags: {
+    has(_flag: string): boolean {
+      throw runtimeError("flags.has");
+    },
+    get(_flag: string): string | undefined {
+      throw runtimeError("flags.get");
+    },
+  },
+  location: new Proxy({} as BuildtimeLocation, {
+    get(_target, _prop): never {
+      throw runtimeError("location");
+    },
+  }),
+};
+
+/**
+ * Re-export with the name `$buildtime` for users who prefer the macroforge
+ * convention of prefixing compile-time identifiers with `$`. Points at the
+ * same object.
+ */
+export const $buildtime = buildtime;

package/js/cli/svelte-check-wrapper.js

@@ -0,0 +1,177 @@
+/**
+ * Svelte-check wrapper — spawned by the CLI's `run_svelte_check_wrapper`.
+ *
+ * Patches `ts.sys.readFile` to expand macros before svelte-check sees the files.
+ * Since svelte-check uses TypeScript as a peer dependency and Node.js caches
+ * modules, the patched `ts.sys.readFile` is shared with svelte-check's internal
+ * TypeScript language service.
+ *
+ * Arguments:
+ *   argv[2..] — forwarded to svelte-check CLI
+ *
+ * Environment:
+ *   MACROFORGE_TYPE_REGISTRY_PATH — path to pre-built type registry JSON
+ */
+const { createRequire } = require("module");
+const fs = require("fs");
+const path = require("path");
+const cwdRequire = createRequire(process.cwd() + "/package.json");
+let ts;
+let macros;
+try {
+  ts = cwdRequire("typescript");
+} catch {
+  console.error(
+    "[macroforge] error: typescript is not installed in this project",
+  );
+  process.exit(1);
+}
+try {
+  macros = cwdRequire("macroforge");
+} catch {
+  console.error(
+    "[macroforge] error: macroforge is not installed in this project",
+  );
+  process.exit(1);
+}
+if (macros.setupExternalMacros) {
+  let resolveDecoratorNames = function (packagePath) {
+      const candidates = [packagePath];
+      for (const id of candidates) {
+        try {
+          const pkg = req(id);
+          const names = [];
+          if (pkg.__macroforgeGetManifest) {
+            names.push(
+              ...(pkg.__macroforgeGetManifest().decorators || []).map(
+                (d) => d.export,
+              ),
+            );
+          }
+          for (const key of Object.keys(pkg)) {
+            if (
+              key.startsWith("__macroforgeGetManifest_") &&
+              typeof pkg[key] === "function"
+            ) {
+              names.push(...(pkg[key]().decorators || []).map((d) => d.export));
+            }
+          }
+          if (names.length > 0) return [...new Set(names)];
+        } catch {}
+      }
+      return [];
+    },
+    runMacro = function (ctxJson) {
+      const ctx = JSON.parse(ctxJson);
+      const fnName = `__macroforgeRun${ctx.macro_name}`;
+      const candidates = [ctx.module_path];
+      for (const id of candidates) {
+        try {
+          const pkg = req(id);
+          const fn_ = pkg?.[fnName] || pkg?.default?.[fnName];
+          if (typeof fn_ === "function") return fn_(ctxJson);
+        } catch {}
+      }
+      throw new Error(`Macro ${fnName} not found in ${ctx.module_path}`);
+    };
+  var resolveDecoratorNames2 = resolveDecoratorNames,
+    runMacro2 = runMacro;
+  const req = createRequire(process.cwd() + "/package.json");
+  macros.setupExternalMacros(resolveDecoratorNames, runMacro);
+}
+const CONFIG_FILES = [
+  "macroforge.config.ts",
+  "macroforge.config.mts",
+  "macroforge.config.js",
+  "macroforge.config.mjs",
+  "macroforge.config.cjs",
+];
+let macroConfigPath = null;
+let currentDir = process.cwd();
+while (true) {
+  for (const filename of CONFIG_FILES) {
+    const candidate = path.join(currentDir, filename);
+    if (fs.existsSync(candidate)) {
+      macroConfigPath = candidate;
+      break;
+    }
+  }
+  if (macroConfigPath) break;
+  if (fs.existsSync(path.join(currentDir, "package.json"))) break;
+  const parent = path.dirname(currentDir);
+  if (parent === currentDir) break;
+  currentDir = parent;
+}
+if (macroConfigPath) {
+  try {
+    const configContent = fs.readFileSync(macroConfigPath, "utf8");
+    macros.loadConfig(configContent, macroConfigPath);
+  } catch {}
+}
+const typeRegistryPath = process.env.MACROFORGE_TYPE_REGISTRY_PATH;
+let typeRegistryJson = void 0;
+if (typeRegistryPath) {
+  try {
+    typeRegistryJson = fs.readFileSync(typeRegistryPath, "utf8");
+  } catch {}
+}
+const declarativeRegistryPath =
+  process.env.MACROFORGE_DECLARATIVE_REGISTRY_PATH;
+let declarativeRegistryJson = void 0;
+if (declarativeRegistryPath) {
+  try {
+    declarativeRegistryJson = fs.readFileSync(declarativeRegistryPath, "utf8");
+  } catch {}
+}
+const plugin = new macros.NativePlugin();
+const expandOpts = {};
+if (macroConfigPath) expandOpts.configPath = macroConfigPath;
+if (typeRegistryJson) expandOpts.typeRegistryJson = typeRegistryJson;
+if (declarativeRegistryJson) {
+  expandOpts.declarativeRegistryJson = declarativeRegistryJson;
+}
+const tsSys = ts.sys;
+const origReadFile = tsSys.readFile.bind(tsSys);
+// Text-level fast path matching the tsc wrapper — covers derive macros
+// plus both sides of the declarative macro system (defining and consuming).
+function hasMacroMarkers(sourceText) {
+  if (!sourceText) return false;
+  if (sourceText.includes("@derive")) return true;
+  if (sourceText.includes("macroforge/rules")) return true;
+  if (sourceText.includes("import macro")) return true;
+  return false;
+}
+tsSys.readFile = (filePath, encoding) => {
+  const content = origReadFile(filePath, encoding);
+  if (content == null) return content;
+  try {
+    if (
+      (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) &&
+      !filePath.endsWith(".d.ts") &&
+      hasMacroMarkers(content)
+    ) {
+      const result = plugin.processFile(filePath, content, expandOpts);
+      return result.code || content;
+    }
+  } catch {}
+  return content;
+};
+const args = ["svelte-check"];
+for (let i = 2; i < process.argv.length; i++) {
+  args.push(process.argv[i]);
+}
+process.argv = [process.argv[0], ...args];
+try {
+  cwdRequire("svelte-check");
+} catch (e) {
+  if (e.code === "MODULE_NOT_FOUND") {
+    console.error(
+      "[macroforge] error: svelte-check is not installed in this project",
+    );
+    console.error(
+      "[macroforge] install it with: npm install --save-dev svelte-check",
+    );
+    process.exit(1);
+  }
+  throw e;
+}