@macroforge/svelte-preprocessor 0.1.79 → 0.1.83

package/README.md

@@ -1,37 +1,10 @@
 # @macroforge/svelte-preprocessor
 
-Svelte preprocessor for expanding Macroforge macros in component script blocks
-
 [![npm version](https://badge.fury.io/js/%40macroforge%2Fsvelte-preprocessor.svg)](https://www.npmjs.com/package/@macroforge/svelte-preprocessor)
 
 ## Overview
 
-@macroforge/svelte-preprocessor
-
-Svelte preprocessor for expanding Macroforge macros in component script blocks.
-
-This module provides integration between Macroforge's macro expansion system and
-Svelte's preprocessing pipeline. It intercepts `<script>` blocks in `.svelte`
-files, detects `@derive` decorators, and expands them into generated code before
-TypeScript compilation occurs.
-
-## How It Works
-
-1. The preprocessor is registered in `svelte.config.js` as part of the
-   preprocess array
-2. When Svelte compiles a component, it passes each `<script>` block to this
-   preprocessor
-3. The preprocessor checks if the script contains `@derive` decorators
-4. If found, it calls the native `macroforge` binding to expand the macros
-5. The expanded code replaces the original script content
-
-## Important Notes
-
-- Must be placed BEFORE other preprocessors (like `vitePreprocess()`) in the
-  chain
-- Uses lazy-loading for native bindings to avoid initialization overhead
-- Gracefully degrades if native bindings are unavailable
-- Only processes TypeScript blocks by default (configurable via options)
+Svelte preprocessor for expanding Macroforge macros in component script blocks
 
 ## Installation
 
@@ -43,29 +16,23 @@ npm install @macroforge/svelte-preprocessor
 
 ### Functions
 
-- **`macroforgePreprocess`** - Whether to preserve `@derive` decorators in the
-  expanded output.
+- **`macroforgePreprocess`** - Creates a Svelte preprocessor that expands Macroforge macros in
+  `<script>` blocks.
 
-### Types
+### Interfaces
 
-- **`ExpandResult`** - Whether to preserve `@derive` decorators in the expanded
-  output.
-- **`MacroforgePreprocessorOptions`** - Configuration options for the Macroforge
-  Svelte preprocessor.
+- **`MacroforgePreprocessorOptions`** - Configuration options for the Macroforge Svelte
+  preprocessor.
 
-## Examples
+### Constants
 
-```typescript
-macroforgePreprocess();
-macroforgePreprocess({ keepDecorators: true });
-macroforgePreprocess({ processJavaScript: true });
-```
+- **`default`** - Default export for convenient importing.
 
 ## Documentation
 
 See the
-[full documentation](https://macroforge.dev/docs/api/reference/typescript/svelte-preprocessor)
-on the Macroforge website.
+[full documentation](https://macroforge.dev/docs/api/reference/typescript/svelte-preprocessor) on
+the Macroforge website.
 
 ## License
 

package/dist/index.d.ts

@@ -25,7 +25,7 @@
  *
  * @packageDocumentation
  */
-import type { PreprocessorGroup } from "svelte/compiler";
+import type { PreprocessorGroup } from 'svelte/compiler';
 /**
  * Configuration options for the Macroforge Svelte preprocessor.
  *
@@ -92,15 +92,18 @@ export interface MacroforgePreprocessorOptions {
  * The preprocessor performs these steps for each script block:
  *
  * 1. **Language Check** - Verifies the script is TypeScript (or JavaScript if enabled)
- * 2. **Quick Scan** - Skips blocks without `@derive` (performance optimization)
- * 3. **Expansion** - Calls the native engine to expand macros
- * 4. **Diagnostics** - Logs any errors or warnings from expansion
- * 5. **Return** - Returns transformed code or `undefined` if unchanged
+ * 2. **Expansion** - Calls the native engine to expand macros
+ * 3. **Diagnostics** - Logs any errors or warnings from expansion
+ * 4. **Return** - Returns transformed code or `undefined` if unchanged
+ *
+ * Every matching script block is passed to the engine; there is no
+ * pre-scan for `@derive`, so unchanged blocks simply come back identical.
  *
  * ## Error Handling
  *
  * The preprocessor is designed to be resilient:
- * - If native bindings fail to load, it silently skips processing
+ * - If native bindings fail to load, it logs a warning, skips the block, and
+ *   retries the import on the next block (so a warning is emitted per attempt)
  * - If macro expansion throws, it logs a warning and continues
  * - Svelte compilation proceeds even if preprocessing fails
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA6OvE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,6BAAkC,GAC1C,iBAAiB,CA6JnB;AAED;;;;;;;GAOG;AACH,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA+OvE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,6BAA6B;IAC1C;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,GAAE,6BAAkC,GAC5C,iBAAiB,CA+InB;AAED;;;;;;;GAOG;AACH,eAAe,oBAAoB,CAAC"}

package/dist/index.js

@@ -25,14 +25,13 @@
  *
  * @packageDocumentation
  */
-import { hasMacroAnnotations } from "@macroforge/shared";
 // ============================================================================
 // Source Map Generation
 // ============================================================================
-const VLQ_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VLQ_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
 function vlqEncode(value) {
     let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
-    let encoded = "";
+    let encoded = '';
     do {
         let digit = vlq & 0x1f;
         vlq >>>= 5;
@@ -46,7 +45,7 @@ function vlqEncode(value) {
 function buildLineOffsets(text) {
     const offsets = [0];
     for (let i = 0; i < text.length; i++) {
-        if (text[i] === "\n")
+        if (text[i] === '\n')
             offsets.push(i + 1);
     }
     return offsets;
@@ -80,7 +79,7 @@ function buildSourceMap(original, expanded, mapping, filename) {
         lineSegments.get(exp.line).push({
             expCol: exp.column,
             origLine: orig.line,
-            origCol: orig.column,
+            origCol: orig.column
         });
     }
     // Encode VLQ mappings
@@ -90,7 +89,7 @@ function buildSourceMap(original, expanded, mapping, filename) {
     for (let line = 0; line < totalLines; line++) {
         const segs = lineSegments.get(line);
         if (!segs || segs.length === 0) {
-            mappingsArr.push("");
+            mappingsArr.push('');
             continue;
         }
         segs.sort((a, b) => a.expCol - b.expCol);
@@ -105,14 +104,14 @@ function buildSourceMap(original, expanded, mapping, filename) {
             prevOrigLine = seg.origLine;
             prevOrigCol = seg.origCol;
         }
-        mappingsArr.push(parts.join(","));
+        mappingsArr.push(parts.join(','));
     }
     return {
         version: 3,
         sources: [filename],
         sourcesContent: [original],
         names: [],
-        mappings: mappingsArr.join(";"),
+        mappings: mappingsArr.join(';')
     };
 }
 /**
@@ -121,7 +120,7 @@ function buildSourceMap(original, expanded, mapping, filename) {
  * This variable implements a lazy-loading pattern:
  * - Initially `null`, indicating the binding hasn't been loaded yet
  * - Set to the actual function after first successful load
- * - Remains `null` if loading fails (graceful degradation)
+ * - Remains `null` if loading fails, so the next call retries the import
  *
  * The lazy-loading approach avoids loading native bindings at module import time,
  * which improves startup performance when the preprocessor is registered but no
@@ -137,17 +136,20 @@ let expandSync = null;
  *
  * 1. On first call, dynamically imports the `macroforge` package
  * 2. Extracts and caches the `expandSync` function
- * 3. On subsequent calls, returns the cached function immediately
+ * 3. On subsequent calls after a successful load, returns the cached function
+ *    immediately
  *
  * The function is async because dynamic imports return promises, even though
- * the underlying `expandSync` function is synchronous. This async wrapper
- * only runs once; after initialization, the cached sync function is used directly.
+ * the underlying `expandSync` function is synchronous. After a successful
+ * initialization, the cached sync function is used directly.
  *
  * ## Error Handling
  *
  * If the native bindings fail to load (e.g., missing native module, architecture
- * mismatch), the function logs a warning and returns `null`. This allows the
- * preprocessor to gracefully skip macro expansion rather than crashing the build.
+ * mismatch), the function logs a warning and returns `null`. Because failure
+ * leaves the cache `null`, the import (and the warning) is retried on every
+ * subsequent call. This allows the preprocessor to skip macro expansion rather
+ * than crashing the build.
  *
  * @returns The cached `expandSync` function, or `null` if loading failed
  * @internal
@@ -156,12 +158,12 @@ async function ensureExpandSync() {
     if (expandSync === null) {
         try {
             // Dynamic import defers loading until first use
-            const macroforge = await import("macroforge");
+            const macroforge = await import('macroforge');
             expandSync = macroforge.expandSync;
         }
         catch (error) {
             // Log warning but don't throw - allows graceful degradation
-            console.warn("[@macroforge/svelte-preprocessor] Failed to load macroforge native bindings:", error);
+            console.warn('[@macroforge/svelte-preprocessor] Failed to load macroforge native bindings:', error);
             expandSync = null;
         }
     }
@@ -186,15 +188,18 @@ async function ensureExpandSync() {
  * The preprocessor performs these steps for each script block:
  *
  * 1. **Language Check** - Verifies the script is TypeScript (or JavaScript if enabled)
- * 2. **Quick Scan** - Skips blocks without `@derive` (performance optimization)
- * 3. **Expansion** - Calls the native engine to expand macros
- * 4. **Diagnostics** - Logs any errors or warnings from expansion
- * 5. **Return** - Returns transformed code or `undefined` if unchanged
+ * 2. **Expansion** - Calls the native engine to expand macros
+ * 3. **Diagnostics** - Logs any errors or warnings from expansion
+ * 4. **Return** - Returns transformed code or `undefined` if unchanged
+ *
+ * Every matching script block is passed to the engine; there is no
+ * pre-scan for `@derive`, so unchanged blocks simply come back identical.
  *
  * ## Error Handling
  *
  * The preprocessor is designed to be resilient:
- * - If native bindings fail to load, it silently skips processing
+ * - If native bindings fail to load, it logs a warning, skips the block, and
+ *   retries the import on the next block (so a warning is emitted per attempt)
  * - If macro expansion throws, it logs a warning and continues
  * - Svelte compilation proceeds even if preprocessing fails
  *
@@ -243,9 +248,9 @@ export function macroforgePreprocess(options = {}) {
      *
      * @returns An object with `code` property if transformed, or `undefined` if no changes
      */
-    const scriptPreprocessor = async ({ content, filename, attributes, }) => {
-        if (filename?.includes("macroforge.svelte")) {
-            console.log(`[PREPROC DEBUG] file=${filename}, lang=${attributes.lang}, type=${attributes.type}, has @derive=${content.includes("@derive")}, has serviceDeserialize=${content.includes("function serviceDeserialize")}`);
+    const scriptPreprocessor = async ({ content, filename, attributes }) => {
+        if (filename?.includes('macroforge.svelte')) {
+            console.log(`[PREPROC DEBUG] file=${filename}, lang=${attributes.lang}, type=${attributes.type}, has @derive=${content.includes('@derive')}, has serviceDeserialize=${content.includes('function serviceDeserialize')}`);
         }
         /*
          * STEP 1: Language Detection
@@ -261,25 +266,15 @@ export function macroforgePreprocess(options = {}) {
          * - <script type="module">    → isJavaScript = true
          */
         const lang = attributes.lang || attributes.type;
-        const isTypeScript = lang === "ts" || lang === "typescript";
-        const isJavaScript = !lang || lang === "js" || lang === "javascript" ||
-            lang === "module";
+        const isTypeScript = lang === 'ts' || lang === 'typescript';
+        const isJavaScript = !lang || lang === 'js' || lang === 'javascript' ||
+            lang === 'module';
         // Skip non-TypeScript blocks unless processJavaScript is enabled
         if (!isTypeScript && !(processJavaScript && isJavaScript)) {
             return; // Return undefined = no changes, Svelte keeps original content
         }
         /*
-         * STEP 2: Quick Scan Optimization
-         *
-         * Before loading native bindings, do a cheap string check for "@derive".
-         * Most components won't have macros, so this saves the cost of loading
-         * and calling the native expansion engine in the common case.
-         */
-        if (!hasMacroAnnotations(content)) {
-            return;
-        }
-        /*
-         * STEP 3: Load Native Bindings
+         * STEP 2: Load Native Bindings
          *
          * The expansion engine is a native module (Rust compiled to Node addon).
          * We lazy-load it on first use to avoid startup overhead.
@@ -287,36 +282,37 @@ export function macroforgePreprocess(options = {}) {
         const expand = await ensureExpandSync();
         if (!expand) {
             // Native bindings unavailable (missing module, architecture mismatch, etc.)
-            // Silently skip - the component will fail later if macros are actually needed
+            // ensureExpandSync already logged a warning; skip this block. The import
+            // is retried on the next block, so the warning repeats per attempt.
             return;
         }
         try {
             /*
-             * STEP 4: Macro Expansion
+             * STEP 3: Macro Expansion
              *
              * Call the native engine to parse the TypeScript, find @derive decorators,
              * and generate the expanded code with all macro-derived methods/properties.
              */
-            const result = expand(content, filename || "component.svelte", {
-                keepDecorators,
+            const result = expand(content, filename || 'component.svelte', {
+                keepDecorators
             });
             /*
-             * STEP 5: Diagnostic Reporting
+             * STEP 4: Diagnostic Reporting
              *
              * The expansion engine may report errors (invalid macro syntax, unknown macros)
              * or warnings (deprecated patterns, suggestions). Log these to help developers
              * debug issues without failing the build.
              */
             for (const diag of result.diagnostics) {
-                if (diag.level === "error") {
+                if (diag.level === 'error') {
                     console.error(`[@macroforge/svelte-preprocessor] Error in ${filename}: ${diag.message}`);
                 }
-                else if (diag.level === "warning") {
+                else if (diag.level === 'warning') {
                     console.warn(`[@macroforge/svelte-preprocessor] Warning in ${filename}: ${diag.message}`);
                 }
             }
             /*
-             * STEP 6: Return Transformed Code
+             * STEP 5: Return Transformed Code
              *
              * Only return a result if the code was actually modified. Returning undefined
              * tells Svelte to keep the original content, which is more efficient than
@@ -324,7 +320,7 @@ export function macroforgePreprocess(options = {}) {
              *
              * The return object can include:
              * - code: The transformed source code (required)
-             * - map: Source map for debugging (optional, not yet implemented)
+             * - map: v3 source map built from the engine's segment mapping (when available)
              */
             if (result.code && result.code !== content) {
                 const mapping = result.sourceMapping;
@@ -358,8 +354,8 @@ export function macroforgePreprocess(options = {}) {
      * Note: We only handle script blocks, not markup or style blocks.
      */
     return {
-        name: "macroforge",
-        script: scriptPreprocessor,
+        name: 'macroforge',
+        script: scriptPreprocessor
     };
 }
 /**

package/package.json

@@ -40,9 +40,9 @@
     "build": "deno install --node-modules-dir --quiet && deno run -A npm:typescript@5/tsc -p tsconfig.json",
     "clean": "rm -rf dist",
     "cleanbuild": "deno task clean && deno task build",
-    "test": "deno task build && node --test tests/**/*.test.js"
+    "test": "deno test --allow-read --allow-env --allow-write --unstable-detect-cjs tests/"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.1.79"
+  "version": "0.1.83"
 }