pulse-js-framework 1.4.7 → 1.4.9

package/compiler/sourcemap.js

@@ -0,0 +1,360 @@
+/**
+ * Pulse Source Map Generator
+ *
+ * Generates V3 source maps for .pulse files compiled to JavaScript.
+ * Enables debugging of original .pulse code in browser devtools.
+ *
+ * @module pulse-js-framework/compiler/sourcemap
+ */
+
+/**
+ * Base64 VLQ encoding for source map mappings
+ * VLQ (Variable Length Quantity) is used to encode position data compactly
+ */
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * Encode a number as VLQ base64
+ * @param {number} value - Number to encode (can be negative)
+ * @returns {string} VLQ encoded string
+ */
+export function encodeVLQ(value) {
+  let encoded = '';
+  // Convert to unsigned and add sign bit
+  let vlq = value < 0 ? ((-value) << 1) + 1 : (value << 1);
+
+  do {
+    let digit = vlq & 0x1F; // 5 bits
+    vlq >>>= 5;
+    if (vlq > 0) {
+      digit |= 0x20; // Set continuation bit
+    }
+    encoded += BASE64_CHARS[digit];
+  } while (vlq > 0);
+
+  return encoded;
+}
+
+/**
+ * Source Map Generator class
+ * Tracks mappings between generated and original source positions
+ */
+export class SourceMapGenerator {
+  /**
+   * @param {Object} options
+   * @param {string} options.file - Generated file name
+   * @param {string} options.sourceRoot - Root URL for source files
+   */
+  constructor(options = {}) {
+    this.file = options.file || '';
+    this.sourceRoot = options.sourceRoot || '';
+    this.sources = [];
+    this.sourcesContent = [];
+    this.names = [];
+    this.mappings = [];
+
+    // Current state for relative encoding
+    this._lastGeneratedLine = 0;
+    this._lastGeneratedColumn = 0;
+    this._lastSourceIndex = 0;
+    this._lastSourceLine = 0;
+    this._lastSourceColumn = 0;
+    this._lastNameIndex = 0;
+  }
+
+  /**
+   * Add a source file
+   * @param {string} source - Source file path
+   * @param {string} content - Source file content (optional)
+   * @returns {number} Source index
+   */
+  addSource(source, content = null) {
+    let index = this.sources.indexOf(source);
+    if (index === -1) {
+      index = this.sources.length;
+      this.sources.push(source);
+      this.sourcesContent.push(content);
+    }
+    return index;
+  }
+
+  /**
+   * Add a name (identifier) to the names array
+   * @param {string} name - Identifier name
+   * @returns {number} Name index
+   */
+  addName(name) {
+    let index = this.names.indexOf(name);
+    if (index === -1) {
+      index = this.names.length;
+      this.names.push(name);
+    }
+    return index;
+  }
+
+  /**
+   * Add a mapping between generated and original positions
+   * @param {Object} mapping
+   * @param {Object} mapping.generated - Generated position {line, column}
+   * @param {Object} mapping.original - Original position {line, column} (optional)
+   * @param {string} mapping.source - Source file path (required if original provided)
+   * @param {string} mapping.name - Original identifier name (optional)
+   */
+  addMapping(mapping) {
+    const { generated, original, source, name } = mapping;
+
+    // Ensure mappings array has enough lines
+    while (this.mappings.length <= generated.line) {
+      this.mappings.push([]);
+    }
+
+    const segment = {
+      generatedColumn: generated.column,
+      sourceIndex: source ? this.addSource(source) : null,
+      originalLine: original?.line ?? null,
+      originalColumn: original?.column ?? null,
+      nameIndex: name ? this.addName(name) : null
+    };
+
+    this.mappings[generated.line].push(segment);
+  }
+
+  /**
+   * Encode all mappings as VLQ string
+   * @returns {string} Encoded mappings
+   */
+  _encodeMappings() {
+    let previousGeneratedColumn = 0;
+    let previousSourceIndex = 0;
+    let previousSourceLine = 0;
+    let previousSourceColumn = 0;
+    let previousNameIndex = 0;
+
+    const lines = [];
+
+    for (const line of this.mappings) {
+      if (line.length === 0) {
+        lines.push('');
+        continue;
+      }
+
+      // Sort segments by generated column
+      line.sort((a, b) => a.generatedColumn - b.generatedColumn);
+
+      const segments = [];
+      previousGeneratedColumn = 0; // Reset column for each line
+
+      for (const segment of line) {
+        let encoded = '';
+
+        // 1. Generated column (relative to previous segment in same line)
+        encoded += encodeVLQ(segment.generatedColumn - previousGeneratedColumn);
+        previousGeneratedColumn = segment.generatedColumn;
+
+        // If we have source info
+        if (segment.sourceIndex !== null) {
+          // 2. Source file index (relative)
+          encoded += encodeVLQ(segment.sourceIndex - previousSourceIndex);
+          previousSourceIndex = segment.sourceIndex;
+
+          // 3. Original line (relative, 0-based in source maps)
+          encoded += encodeVLQ(segment.originalLine - previousSourceLine);
+          previousSourceLine = segment.originalLine;
+
+          // 4. Original column (relative)
+          encoded += encodeVLQ(segment.originalColumn - previousSourceColumn);
+          previousSourceColumn = segment.originalColumn;
+
+          // 5. Optional: name index (relative)
+          if (segment.nameIndex !== null) {
+            encoded += encodeVLQ(segment.nameIndex - previousNameIndex);
+            previousNameIndex = segment.nameIndex;
+          }
+        }
+
+        segments.push(encoded);
+      }
+
+      lines.push(segments.join(','));
+    }
+
+    return lines.join(';');
+  }
+
+  /**
+   * Generate the source map object
+   * @returns {Object} Source map object (V3 format)
+   */
+  toJSON() {
+    return {
+      version: 3,
+      file: this.file,
+      sourceRoot: this.sourceRoot,
+      sources: this.sources,
+      sourcesContent: this.sourcesContent,
+      names: this.names,
+      mappings: this._encodeMappings()
+    };
+  }
+
+  /**
+   * Generate source map as JSON string
+   * @returns {string} JSON string
+   */
+  toString() {
+    return JSON.stringify(this.toJSON());
+  }
+
+  /**
+   * Generate inline source map comment
+   * @returns {string} Comment with base64 encoded source map
+   */
+  toComment() {
+    const base64 = typeof btoa === 'function'
+      ? btoa(this.toString())
+      : Buffer.from(this.toString()).toString('base64');
+    return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64}`;
+  }
+
+  /**
+   * Generate external source map URL comment
+   * @param {string} url - URL to source map file
+   * @returns {string} Comment with source map URL
+   */
+  static toURLComment(url) {
+    return `//# sourceMappingURL=${url}`;
+  }
+}
+
+/**
+ * Source Map Consumer - parse and query source maps
+ * Useful for error stack trace translation
+ */
+export class SourceMapConsumer {
+  /**
+   * @param {Object|string} sourceMap - Source map object or JSON string
+   */
+  constructor(sourceMap) {
+    this.map = typeof sourceMap === 'string' ? JSON.parse(sourceMap) : sourceMap;
+    this._decodedMappings = null;
+  }
+
+  /**
+   * Decode VLQ string to numbers
+   * @param {string} str - VLQ encoded string
+   * @returns {number[]} Decoded numbers
+   */
+  static decodeVLQ(str) {
+    const values = [];
+    let value = 0;
+    let shift = 0;
+
+    for (const char of str) {
+      const digit = BASE64_CHARS.indexOf(char);
+      if (digit === -1) continue;
+
+      value += (digit & 0x1F) << shift;
+
+      if (digit & 0x20) {
+        shift += 5;
+      } else {
+        // Check sign bit
+        const negative = value & 1;
+        value >>= 1;
+        values.push(negative ? -value : value);
+        value = 0;
+        shift = 0;
+      }
+    }
+
+    return values;
+  }
+
+  /**
+   * Get original position for a generated position
+   * @param {Object} position - Generated position {line, column}
+   * @returns {Object|null} Original position or null
+   */
+  originalPositionFor(position) {
+    this._ensureDecoded();
+
+    const { line, column } = position;
+    const lineData = this._decodedMappings[line];
+
+    if (!lineData) return null;
+
+    // Find the closest mapping at or before this column
+    let closest = null;
+    for (const mapping of lineData) {
+      if (mapping.generatedColumn <= column) {
+        closest = mapping;
+      } else {
+        break;
+      }
+    }
+
+    if (!closest || closest.sourceIndex === null) return null;
+
+    return {
+      source: this.map.sources[closest.sourceIndex],
+      line: closest.originalLine,
+      column: closest.originalColumn,
+      name: closest.nameIndex !== null ? this.map.names[closest.nameIndex] : null
+    };
+  }
+
+  /**
+   * Decode mappings lazily
+   */
+  _ensureDecoded() {
+    if (this._decodedMappings) return;
+
+    this._decodedMappings = [];
+    const lines = this.map.mappings.split(';');
+
+    let sourceIndex = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let nameIndex = 0;
+
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+      const segments = line.split(',').filter(s => s);
+      const lineData = [];
+      let generatedColumn = 0;
+
+      for (const segment of segments) {
+        const values = SourceMapConsumer.decodeVLQ(segment);
+
+        generatedColumn += values[0];
+
+        const mapping = { generatedColumn };
+
+        if (values.length >= 4) {
+          sourceIndex += values[1];
+          sourceLine += values[2];
+          sourceColumn += values[3];
+
+          mapping.sourceIndex = sourceIndex;
+          mapping.originalLine = sourceLine;
+          mapping.originalColumn = sourceColumn;
+        }
+
+        if (values.length >= 5) {
+          nameIndex += values[4];
+          mapping.nameIndex = nameIndex;
+        }
+
+        lineData.push(mapping);
+      }
+
+      this._decodedMappings.push(lineData);
+    }
+  }
+}
+
+export default {
+  SourceMapGenerator,
+  SourceMapConsumer,
+  encodeVLQ
+};

package/compiler/transformer.js

@@ -7,9 +7,11 @@
  * - Import statement support
  * - Slot-based component composition
  * - CSS scoping with unique class prefixes
+ * - Source map generation
  */
 
 import { NodeType } from './parser.js';
+import { SourceMapGenerator } from './sourcemap.js';
 
 /** Generate a unique scope ID for CSS scoping */
 const generateScopeId = () => 'p' + Math.random().toString(36).substring(2, 8);
@@ -29,13 +31,92 @@ const STATEMENT_TOKEN_TYPES = new Set(['IF', 'FOR', 'EACH']);
 export class Transformer {
   constructor(ast, options = {}) {
     this.ast = ast;
-    this.options = { runtime: 'pulse-js-framework/runtime', minify: false, scopeStyles: true, ...options };
+    this.options = {
+      runtime: 'pulse-js-framework/runtime',
+      minify: false,
+      scopeStyles: true,
+      sourceMap: false,        // Enable source map generation
+      sourceFileName: null,    // Original .pulse file name
+      sourceContent: null,     // Original source content (for inline source maps)
+      ...options
+    };
     this.stateVars = new Set();
     this.propVars = new Set();
     this.propDefaults = new Map();
     this.actionNames = new Set();
     this.importedComponents = new Map();
     this.scopeId = this.options.scopeStyles ? generateScopeId() : null;
+
+    // Source map tracking
+    this.sourceMap = null;
+    this._currentLine = 0;
+    this._currentColumn = 0;
+
+    // Initialize source map generator if enabled
+    if (this.options.sourceMap) {
+      this.sourceMap = new SourceMapGenerator({
+        file: this.options.sourceFileName?.replace('.pulse', '.js') || 'output.js'
+      });
+      if (this.options.sourceFileName) {
+        this.sourceMap.addSource(
+          this.options.sourceFileName,
+          this.options.sourceContent
+        );
+      }
+    }
+  }
+
+  /**
+   * Add a mapping to the source map
+   * @param {Object} original - Original position {line, column} (1-based)
+   * @param {string} name - Optional identifier name
+   */
+  _addMapping(original, name = null) {
+    if (!this.sourceMap || !original) return;
+
+    this.sourceMap.addMapping({
+      generated: {
+        line: this._currentLine,
+        column: this._currentColumn
+      },
+      original: {
+        line: original.line - 1, // Convert to 0-based
+        column: original.column - 1
+      },
+      source: this.options.sourceFileName,
+      name
+    });
+  }
+
+  /**
+   * Track output position when writing code
+   * @param {string} code - Generated code
+   * @returns {string} The same code (for chaining)
+   */
+  _trackCode(code) {
+    for (const char of code) {
+      if (char === '\n') {
+        this._currentLine++;
+        this._currentColumn = 0;
+      } else {
+        this._currentColumn++;
+      }
+    }
+    return code;
+  }
+
+  /**
+   * Write code with optional source mapping
+   * @param {string} code - Code to write
+   * @param {Object} original - Original position {line, column}
+   * @param {string} name - Optional identifier name
+   * @returns {string} The code
+   */
+  _emit(code, original = null, name = null) {
+    if (original) {
+      this._addMapping(original, name);
+    }
+    return this._trackCode(code);
   }
 
   /**
@@ -100,7 +181,32 @@ export class Transformer {
     // Component export
     parts.push(this.generateExport());
 
-    return parts.filter(Boolean).join('\n\n');
+    const code = parts.filter(Boolean).join('\n\n');
+
+    // Track the generated code for source map positions
+    if (this.sourceMap) {
+      this._trackCode(code);
+    }
+
+    return code;
+  }
+
+  /**
+   * Transform AST and return result with optional source map
+   * @returns {Object} Result with code and optional sourceMap
+   */
+  transformWithSourceMap() {
+    const code = this.transform();
+
+    if (!this.sourceMap) {
+      return { code, sourceMap: null };
+    }
+
+    return {
+      code,
+      sourceMap: this.sourceMap.toJSON(),
+      sourceMapComment: this.sourceMap.toComment()
+    };
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -42,6 +42,7 @@
       "default": "./runtime/logger.js"
     },
     "./runtime/hmr": {
+      "types": "./types/hmr.d.ts",
       "default": "./runtime/hmr.js"
     },
     "./compiler": {
@@ -70,8 +71,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
+    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
     "test:compiler": "node test/compiler.test.js",
+    "test:sourcemap": "node test/sourcemap.test.js",
     "test:pulse": "node test/pulse.test.js",
     "test:dom": "node test/dom.test.js",
     "test:router": "node test/router.test.js",