@macroforge/typescript-plugin 0.1.33 → 0.1.35

package/dist/source-map.d.ts

@@ -1,16 +1,91 @@
+/**
+ * @fileoverview Source mapping type definitions for the TypeScript plugin.
+ *
+ * This module re-exports and extends position mapping types from the core
+ * macroforge package. These types are used to translate positions between
+ * original source code and macro-expanded code.
+ *
+ * @module @macroforge/typescript-plugin/source-map
+ */
 import type { SourceMappingResult } from "macroforge";
+/**
+ * Re-export of the core source mapping result type.
+ *
+ * Contains the complete mapping data between original and expanded code,
+ * including segment information and generated region metadata.
+ */
 export type SourceMapping = SourceMappingResult;
+/**
+ * Interface for mapping positions between original and expanded code.
+ *
+ * The TypeScript plugin uses this interface to translate cursor positions,
+ * text spans, and other location data between the original source code
+ * (what the user sees) and the expanded code (what TypeScript analyzes).
+ *
+ * @remarks
+ * Position mapping is bidirectional:
+ * - Original → Expanded: Used when sending positions TO TypeScript (cursor, selection)
+ * - Expanded → Original: Used when receiving positions FROM TypeScript (errors, spans)
+ *
+ * @example
+ * ```typescript
+ * // Map a cursor position from original to expanded
+ * const expandedPos = mapper.originalToExpanded(cursorPosition);
+ *
+ * // Map an error span from expanded back to original
+ * const originalSpan = mapper.mapSpanToOriginal(error.start, error.length);
+ * if (originalSpan) {
+ *   // Error is in user code - show it at originalSpan position
+ * } else {
+ *   // Error is in generated code - show it at decorator position instead
+ * }
+ * ```
+ */
 export interface PositionMapper {
+    /**
+     * Maps a position from original source to expanded code.
+     *
+     * @param pos - Position in the original source (0-indexed character offset)
+     * @returns Corresponding position in the expanded code
+     */
     originalToExpanded(pos: number): number;
+    /**
+     * Maps a position from expanded code back to original source.
+     *
+     * @param pos - Position in the expanded code (0-indexed character offset)
+     * @returns Corresponding position in the original source, or `null` if the
+     *          position falls within generated code (no original equivalent)
+     */
     expandedToOriginal(pos: number): number | null;
+    /**
+     * Maps a text span from expanded code back to original source.
+     *
+     * @param start - Start position in expanded code
+     * @param length - Length of the span in expanded code
+     * @returns Object with mapped start and length, or `null` if the span
+     *          falls within generated code
+     */
     mapSpanToOriginal(start: number, length: number): {
         start: number;
         length: number;
     } | null;
+    /**
+     * Maps a text span from original source to expanded code.
+     *
+     * @param start - Start position in original source
+     * @param length - Length of the span in original source
+     * @returns Object with mapped start and length in expanded code
+     */
     mapSpanToExpanded(start: number, length: number): {
         start: number;
         length: number;
     };
+    /**
+     * Checks if this mapper has any mapping data.
+     *
+     * @returns `true` if no macro expansion occurred (original === expanded),
+     *          `false` if there are position differences to account for
+     */
     isEmpty(): boolean;
 }
 //# sourceMappingURL=source-map.d.ts.map

package/dist/source-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-map.d.ts","sourceRoot":"","sources":["../src/source-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/C,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5C,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,OAAO,IAAI,OAAO,CAAC;CACpB"}
+{"version":3,"file":"source-map.d.ts","sourceRoot":"","sources":["../src/source-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAExC;;;;;;OAMG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE/C;;;;;;;OAOG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE5C;;;;;;OAMG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAErC;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC;CACpB"}

package/dist/source-map.js

@@ -1,2 +1,11 @@
 "use strict";
+/**
+ * @fileoverview Source mapping type definitions for the TypeScript plugin.
+ *
+ * This module re-exports and extends position mapping types from the core
+ * macroforge package. These types are used to translate positions between
+ * original source code and macro-expanded code.
+ *
+ * @module @macroforge/typescript-plugin/source-map
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroforge/typescript-plugin",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "TypeScript language service plugin that augments classes decorated with @derive to include macro-generated methods.",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "test": "bun run build && node --test tests/**/*.test.js"
   },
   "dependencies": {
-    "macroforge": "^0.1.33"
+    "macroforge": "^0.1.35"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"