@sprlab/wccompiler 0.0.2 → 0.2.0

package/lib/compiler.js

@@ -1,49 +1,124 @@
 /**
- * Compiler — integrates parser, tree-walker, css-scoper, and codegen
- * into a single compile(filePath, config) function.
+ * Compiler — orchestrates the full compilation pipeline for wcCompiler v2.
  *
- * This is the main entry point for compiling a .html source file
- * into a self-contained .js web component.
+ * Pipeline: parse → jsdom template → tree-walk → codegen
+ *
+ * Takes a .ts/.js source file path and produces a self-contained
+ * JavaScript web component string.
  */
 
-import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
 import { JSDOM } from 'jsdom';
 import { parse } from './parser.js';
-import { walkTree } from './tree-walker.js';
+import { walkTree, processIfChains, processForBlocks, recomputeAnchorPath, detectRefs } from './tree-walker.js';
 import { generateComponent } from './codegen.js';
-
 /**
- * Compile a single .html source file into a self-contained JS component string.
+ * Compile a single .ts/.js source file into a self-contained JS component.
  *
- * @param {string} filePath - Absolute or relative path to the .html source file
- * @param {object} [config] - Optional config (currently unused, reserved for future options)
- * @returns {string} The generated JavaScript component code
+ * @param {string} filePath — Absolute or relative path to the source file
+ * @param {object} [config] — Optional config (reserved for future options)
+ * @returns {Promise<string>} The generated JavaScript component code
  */
-export function compile(filePath, config) {
-  // 1. Read the source file
-  const html = readFileSync(filePath, 'utf-8');
-  const fileName = basename(filePath);
-
-  // 2. Parse the HTML into the IR
-  const parseResult = parse(html, fileName);
+export async function compile(filePath, config) {
+  // 1. Parse the source file
+  const parseResult = await parse(filePath);
 
-  // 3. Create a jsdom DOM from the template and walk it
+  // 2. Parse template HTML into jsdom DOM
   const dom = new JSDOM(`<div id="__root">${parseResult.template}</div>`);
   const rootEl = dom.window.document.getElementById('__root');
 
-  const propsSet = new Set(parseResult.props);
+  // 3. Build name sets
+  const signalNames = new Set(parseResult.signals.map(s => s.name));
   const computedNames = new Set(parseResult.computeds.map(c => c.name));
-  const rootVarNames = new Set(parseResult.reactiveVars.map(v => v.name));
+  const propNames = new Set((parseResult.propDefs || []).map(p => p.name));
+
+  // 4. Process each blocks BEFORE if chains (replaces each elements with comment anchors)
+  const forBlocks = processForBlocks(rootEl, [], signalNames, computedNames, propNames);
+
+  // 5. Process conditional chains BEFORE walkTree (if/else-if/else)
+  // This replaces conditional elements with comment anchors so walkTree
+  // doesn't discover bindings inside conditional branches at the top level.
+  const ifBlocks = processIfChains(rootEl, [], signalNames, computedNames, propNames);
+
+  // 6. Normalize DOM after all directive processing to merge adjacent text nodes
+  rootEl.normalize();
+
+  // 7. Recompute anchor paths after normalization since text node merging
+  // may have changed childNode indices
+  for (const fb of forBlocks) {
+    fb.anchorPath = recomputeAnchorPath(rootEl, fb._anchorNode);
+  }
+  for (const ib of ifBlocks) {
+    ib.anchorPath = recomputeAnchorPath(rootEl, ib._anchorNode);
+  }
+
+  // 8. Walk the tree (discovers bindings/events/showBindings/slots in non-conditional content)
+  const { bindings, events, showBindings, modelBindings, attrBindings, slots } = walkTree(rootEl, signalNames, computedNames, propNames);
+
+  // 9. Detect refs (after walkTree — ref attributes are compile-time directives)
+  const refBindings = detectRefs(rootEl);
+
+  // 10. Validate refs
+  const refs = parseResult.refs || [];
+
+  // REF_NOT_FOUND: templateRef('name') with no matching ref="name" in template
+  for (const decl of refs) {
+    if (!refBindings.find(b => b.refName === decl.refName)) {
+      const error = new Error(`templateRef('${decl.refName}') has no matching ref="${decl.refName}" in template`);
+      /** @ts-expect-error — custom error code */
+      error.code = 'REF_NOT_FOUND';
+      throw error;
+    }
+  }
+
+  // Unused ref warning: ref="name" in template with no matching templateRef('name') in script
+  for (const binding of refBindings) {
+    if (!refs.find(d => d.refName === binding.refName)) {
+      console.warn(`Warning: ref="${binding.refName}" in template has no matching templateRef('${binding.refName}') in script`);
+    }
+  }
 
-  const { bindings, events, slots } = walkTree(rootEl, propsSet, computedNames, rootVarNames);
+  // 10b. Validate model bindings — target must be a signal (not prop, computed, or constant)
+  const constantNames = new Set((parseResult.constantVars || []).map(v => v.name));
+  for (const mb of modelBindings) {
+    if (propNames.has(mb.signal)) {
+      const error = new Error(`model cannot bind to prop '${mb.signal}' (read-only)`);
+      /** @ts-expect-error — custom error code */
+      error.code = 'MODEL_READONLY';
+      throw error;
+    }
+    if (computedNames.has(mb.signal)) {
+      const error = new Error(`model cannot bind to computed '${mb.signal}' (read-only)`);
+      /** @ts-expect-error — custom error code */
+      error.code = 'MODEL_READONLY';
+      throw error;
+    }
+    if (constantNames.has(mb.signal)) {
+      const error = new Error(`model cannot bind to constant '${mb.signal}' (read-only)`);
+      /** @ts-expect-error — custom error code */
+      error.code = 'MODEL_READONLY';
+      throw error;
+    }
+    if (!signalNames.has(mb.signal)) {
+      const error = new Error(`model references undeclared variable '${mb.signal}'`);
+      /** @ts-expect-error — custom error code */
+      error.code = 'MODEL_UNKNOWN_VAR';
+      throw error;
+    }
+  }
 
-  // 4. Update the parseResult with tree-walker results
+  // 11. Merge results into ParseResult
   parseResult.bindings = bindings;
   parseResult.events = events;
+  parseResult.showBindings = showBindings;
+  parseResult.modelBindings = modelBindings;
+  parseResult.attrBindings = attrBindings;
+  parseResult.ifBlocks = ifBlocks;
+  parseResult.forBlocks = forBlocks;
   parseResult.slots = slots;
+  parseResult.refBindings = refBindings;
+  // Recompute processedTemplate after all directive replacements (including ref removal)
   parseResult.processedTemplate = rootEl.innerHTML;
 
-  // 5. Generate the component code
+  // 12. Generate component
   return generateComponent(parseResult);
 }

package/lib/config.js

@@ -1,60 +1,50 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
 
-const DEFAULTS = {
-  port: 4100,
-  input: 'src',
-  output: 'dist',
-};
+/**
+ * @typedef {Object} WccConfig
+ * @property {number} port — Dev server port (default: 4100)
+ * @property {string} input — Source directory (default: 'src')
+ * @property {string} output — Output directory (default: 'dist')
+ */
 
 /**
- * Load and validate wcc.config.js from the given project root.
- * Returns defaults if the config file doesn't exist.
+ * Load wcc.config.js from the project root.
+ * Returns defaults if the file doesn't exist.
+ * Validates port (finite number), input (non-empty string), output (non-empty string).
  *
- * @param {string} projectRoot - Absolute path to the project root
- * @returns {Promise<{port: number, input: string, output: string}>}
+ * @param {string} projectRoot
+ * @returns {Promise<WccConfig>}
  */
 export async function loadConfig(projectRoot) {
+  const defaults = { port: 4100, input: 'src', output: 'dist' };
   const configPath = resolve(projectRoot, 'wcc.config.js');
 
-  if (!existsSync(configPath)) {
-    return { ...DEFAULTS };
-  }
+  if (!existsSync(configPath)) return defaults;
 
-  const fileUrl = pathToFileURL(configPath).href;
-  const mod = await import(fileUrl);
-  const raw = mod.default ?? mod;
+  const configUrl = pathToFileURL(configPath).href;
+  // Add cache-busting query to avoid ESM module cache issues
+  const mod = await import(`${configUrl}?t=${Date.now()}`);
+  const userConfig = mod.default || mod;
 
-  const config = { ...DEFAULTS };
-  const errors = [];
+  const config = { ...defaults, ...userConfig };
 
-  if ('port' in raw) {
-    if (typeof raw.port !== 'number' || !Number.isFinite(raw.port)) {
-      errors.push("la propiedad 'port' debe ser un número válido");
-    } else {
-      config.port = raw.port;
-    }
+  // Validate
+  if (typeof config.port !== 'number' || !isFinite(config.port)) {
+    const error = new Error(`Error en wcc.config.js: port debe ser un número finito`);
+    error.code = 'INVALID_CONFIG';
+    throw error;
   }
-
-  if ('input' in raw) {
-    if (typeof raw.input !== 'string' || raw.input.trim() === '') {
-      errors.push("la propiedad 'input' debe ser un string no vacío");
-    } else {
-      config.input = raw.input;
-    }
+  if (typeof config.input !== 'string' || !config.input.trim()) {
+    const error = new Error(`Error en wcc.config.js: input debe ser un string no vacío`);
+    error.code = 'INVALID_CONFIG';
+    throw error;
   }
-
-  if ('output' in raw) {
-    if (typeof raw.output !== 'string' || raw.output.trim() === '') {
-      errors.push("la propiedad 'output' debe ser un string no vacío");
-    } else {
-      config.output = raw.output;
-    }
-  }
-
-  if (errors.length > 0) {
-    throw new Error(`Error en wcc.config.js: ${errors.join('; ')}`);
+  if (typeof config.output !== 'string' || !config.output.trim()) {
+    const error = new Error(`Error en wcc.config.js: output debe ser un string no vacío`);
+    error.code = 'INVALID_CONFIG';
+    throw error;
   }
 
   return config;

package/lib/css-scoper.js

@@ -69,6 +69,10 @@ export function scopeCSS(css, tagName) {
 /**
  * Prefix comma-separated selectors with the tag name.
  * e.g. ".foo, .bar" → "tag .foo, tag .bar"
+ *
+ * @param {string} raw - Raw selector string (may be comma-separated)
+ * @param {string} tagName - Component tag name to prefix
+ * @returns {string} Prefixed selector string
  */
 function prefixSelectors(raw, tagName) {
   return raw
@@ -86,6 +90,10 @@ function prefixSelectors(raw, tagName) {
 /**
  * Consume a { ... } block starting at the opening brace.
  * Returns the text (including braces) and the position after the closing brace.
+ *
+ * @param {string} css - Full CSS string
+ * @param {number} start - Index of the opening brace
+ * @returns {{text: string, end: number}} Consumed block text and position after closing brace
  */
 function consumeBlock(css, start) {
   let depth = 0;
@@ -112,6 +120,11 @@ function consumeBlock(css, start) {
  * Consume an at-rule starting at '@'.
  * Handles both block at-rules (@media { ... }) and statement at-rules (@import ...).
  * For block at-rules, recursively scopes selectors inside.
+ *
+ * @param {string} css - Full CSS string
+ * @param {number} start - Index of the '@' character
+ * @param {string} tagName - Component tag name for scoping nested selectors
+ * @returns {{text: string, end: number}} Consumed at-rule text and position after it
  */
 function consumeAtRule(css, start, tagName) {
   // Read the at-rule prelude (everything up to '{' or ';')

package/lib/dev-server.js

@@ -6,6 +6,19 @@ import { createServer } from 'node:http';
 import { readFileSync, watch, existsSync } from 'node:fs';
 import { resolve, extname } from 'node:path';
 
+/**
+ * @typedef {Object} DevServerOptions
+ * @property {number} port
+ * @property {string} root
+ * @property {string} outputDir
+ */
+
+/**
+ * @typedef {Object} DevServerHandle
+ * @property {import('node:http').Server} server
+ * @property {() => void} close
+ */
+
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
@@ -29,6 +42,12 @@ const POLL_SNIPPET = `<script>
 })();
 </script>`;
 
+/**
+ * Start a development server with live-reload support.
+ *
+ * @param {DevServerOptions} options
+ * @returns {DevServerHandle}
+ */
 export function startDevServer({ port, root, outputDir }) {
   let changeTs = Date.now();