pulse-js-framework 1.10.0 → 1.10.1

package/compiler/parser/blocks.js

@@ -0,0 +1,361 @@
+/**
+ * Pulse Parser - Block Parsing
+ *
+ * Actions, router, store blocks, and function/guard parsing
+ *
+ * @module compiler/parser/blocks
+ */
+
+import { TokenType } from '../lexer.js';
+import { NodeType, ASTNode, Parser } from './core.js';
+
+// ============================================================
+// Actions Block Parsing
+// ============================================================
+
+/**
+ * Parse actions block
+ */
+Parser.prototype.parseActionsBlock = function() {
+  this.expect(TokenType.ACTIONS);
+  this.expect(TokenType.LBRACE);
+
+  const functions = [];
+  while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+    functions.push(this.parseFunctionDeclaration());
+  }
+
+  this.expect(TokenType.RBRACE);
+  return new ASTNode(NodeType.ActionsBlock, { functions });
+};
+
+/**
+ * Parse function declaration
+ */
+Parser.prototype.parseFunctionDeclaration = function() {
+  let async = false;
+  if (this.is(TokenType.IDENT) && this.current().value === 'async') {
+    this.advance();
+    async = true;
+  }
+
+  const name = this.expect(TokenType.IDENT).value;
+  this.expect(TokenType.LPAREN);
+
+  const params = [];
+  while (!this.is(TokenType.RPAREN) && !this.is(TokenType.EOF)) {
+    // Accept IDENT or keyword tokens that can be used as parameter names
+    const paramToken = this.current();
+    if (this.is(TokenType.IDENT) || this.is(TokenType.PAGE) ||
+        this.is(TokenType.ROUTE) || this.is(TokenType.FROM) ||
+        this.is(TokenType.STATE) || this.is(TokenType.VIEW) ||
+        this.is(TokenType.STORE) || this.is(TokenType.ROUTER)) {
+      params.push(this.advance().value);
+    } else {
+      throw this.createError(`Expected parameter name but got ${paramToken?.type}`);
+    }
+    if (this.is(TokenType.COMMA)) {
+      this.advance();
+    }
+  }
+  this.expect(TokenType.RPAREN);
+
+  // Parse function body as raw JS
+  this.expect(TokenType.LBRACE);
+  const body = this.parseFunctionBody();
+  this.expect(TokenType.RBRACE);
+
+  return new ASTNode(NodeType.FunctionDeclaration, { name, params, body, async });
+};
+
+/**
+ * Parse function body (raw content between braces)
+ */
+Parser.prototype.parseFunctionBody = function() {
+  // Simplified: collect all tokens until matching }
+  const statements = [];
+  let braceCount = 1;
+
+  while (!this.is(TokenType.EOF)) {
+    if (this.is(TokenType.LBRACE)) {
+      braceCount++;
+    } else if (this.is(TokenType.RBRACE)) {
+      braceCount--;
+      if (braceCount === 0) break;
+    }
+
+    // Collect raw token for reconstruction
+    statements.push(this.current());
+    this.advance();
+  }
+
+  return statements;
+};
+
+// ============================================================
+// Router Block Parsing
+// ============================================================
+
+/**
+ * Parse router block
+ */
+Parser.prototype.parseRouterBlock = function() {
+  this.expect(TokenType.ROUTER);
+  this.expect(TokenType.LBRACE);
+
+  const config = {
+    mode: 'history',
+    base: '',
+    routes: [],
+    beforeEach: null,
+    afterEach: null
+  };
+
+  while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+    // mode: "hash"
+    if (this.is(TokenType.MODE)) {
+      this.advance();
+      this.expect(TokenType.COLON);
+      config.mode = this.expect(TokenType.STRING).value;
+    }
+    // base: "/app"
+    else if (this.is(TokenType.BASE)) {
+      this.advance();
+      this.expect(TokenType.COLON);
+      config.base = this.expect(TokenType.STRING).value;
+    }
+    // routes { ... }
+    else if (this.is(TokenType.ROUTES)) {
+      config.routes = this.parseRoutesBlock();
+    }
+    // beforeEach(to, from) { ... }
+    else if (this.is(TokenType.BEFORE_EACH)) {
+      config.beforeEach = this.parseGuardHook('beforeEach');
+    }
+    // afterEach(to) { ... }
+    else if (this.is(TokenType.AFTER_EACH)) {
+      config.afterEach = this.parseGuardHook('afterEach');
+    }
+    else {
+      throw this.createError(
+        `Unexpected token '${this.current()?.value}' in router block. ` +
+        `Expected: mode, base, routes, beforeEach, or afterEach`
+      );
+    }
+  }
+
+  this.expect(TokenType.RBRACE);
+  return new ASTNode(NodeType.RouterBlock, config);
+};
+
+/**
+ * Parse routes block
+ */
+Parser.prototype.parseRoutesBlock = function() {
+  this.expect(TokenType.ROUTES);
+  this.expect(TokenType.LBRACE);
+
+  const routes = [];
+  while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+    const path = this.expect(TokenType.STRING).value;
+    this.expect(TokenType.COLON);
+    const handler = this.expect(TokenType.IDENT).value;
+    routes.push(new ASTNode(NodeType.RouteDefinition, { path, handler }));
+  }
+
+  this.expect(TokenType.RBRACE);
+  return routes;
+};
+
+/**
+ * Parse guard hook: beforeEach(to, from) { ... }
+ */
+Parser.prototype.parseGuardHook = function(name) {
+  this.advance(); // skip keyword
+  this.expect(TokenType.LPAREN);
+  const params = [];
+  while (!this.is(TokenType.RPAREN) && !this.is(TokenType.EOF)) {
+    // Accept IDENT or FROM (since 'from' is a keyword but valid as parameter name)
+    if (this.is(TokenType.IDENT)) {
+      params.push(this.advance().value);
+    } else if (this.is(TokenType.FROM)) {
+      params.push(this.advance().value);
+    } else {
+      throw this.createError(`Expected parameter name but got ${this.current()?.type}`);
+    }
+    if (this.is(TokenType.COMMA)) this.advance();
+  }
+  this.expect(TokenType.RPAREN);
+  this.expect(TokenType.LBRACE);
+  const body = this.parseFunctionBody();
+  this.expect(TokenType.RBRACE);
+
+  return new ASTNode(NodeType.GuardHook, { name, params, body });
+};
+
+// ============================================================
+// Store Block Parsing
+// ============================================================
+
+/**
+ * Parse store block
+ */
+Parser.prototype.parseStoreBlock = function() {
+  this.expect(TokenType.STORE);
+  this.expect(TokenType.LBRACE);
+
+  const config = {
+    state: null,
+    getters: null,
+    actions: null,
+    persist: false,
+    storageKey: 'pulse-store',
+    plugins: []
+  };
+
+  while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+    // state { ... }
+    if (this.is(TokenType.STATE)) {
+      config.state = this.parseStateBlock();
+    }
+    // getters { ... }
+    else if (this.is(TokenType.GETTERS)) {
+      config.getters = this.parseGettersBlock();
+    }
+    // actions { ... }
+    else if (this.is(TokenType.ACTIONS)) {
+      config.actions = this.parseActionsBlock();
+    }
+    // persist: true
+    else if (this.is(TokenType.PERSIST)) {
+      this.advance();
+      this.expect(TokenType.COLON);
+      if (this.is(TokenType.TRUE)) {
+        this.advance();
+        config.persist = true;
+      } else if (this.is(TokenType.FALSE)) {
+        this.advance();
+        config.persist = false;
+      } else {
+        throw this.createError('Expected true or false for persist');
+      }
+    }
+    // storageKey: "my-store"
+    else if (this.is(TokenType.STORAGE_KEY)) {
+      this.advance();
+      this.expect(TokenType.COLON);
+      config.storageKey = this.expect(TokenType.STRING).value;
+    }
+    // plugins: [historyPlugin, loggerPlugin]
+    else if (this.is(TokenType.PLUGINS)) {
+      this.advance();
+      this.expect(TokenType.COLON);
+      config.plugins = this.parseArrayLiteral();
+    }
+    else {
+      throw this.createError(
+        `Unexpected token '${this.current()?.value}' in store block. ` +
+        `Expected: state, getters, actions, persist, storageKey, or plugins`
+      );
+    }
+  }
+
+  this.expect(TokenType.RBRACE);
+  return new ASTNode(NodeType.StoreBlock, config);
+};
+
+/**
+ * Parse getters block
+ */
+Parser.prototype.parseGettersBlock = function() {
+  this.expect(TokenType.GETTERS);
+  this.expect(TokenType.LBRACE);
+
+  const getters = [];
+  while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+    getters.push(this.parseGetterDeclaration());
+  }
+
+  this.expect(TokenType.RBRACE);
+  return new ASTNode(NodeType.GettersBlock, { getters });
+};
+
+/**
+ * Parse getter declaration: name() { return ... }
+ */
+Parser.prototype.parseGetterDeclaration = function() {
+  const name = this.expect(TokenType.IDENT).value;
+  this.expect(TokenType.LPAREN);
+  this.expect(TokenType.RPAREN);
+  this.expect(TokenType.LBRACE);
+  const body = this.parseFunctionBody();
+  this.expect(TokenType.RBRACE);
+
+  return new ASTNode(NodeType.GetterDeclaration, { name, body });
+};
+
+// ============================================================
+// Router View Directives
+// ============================================================
+
+/**
+ * Parse @link directive: @link("/path") "text"
+ */
+Parser.prototype.parseLinkDirective = function() {
+  this.expect(TokenType.LPAREN);
+  const path = this.parseExpression();
+
+  let options = null;
+  if (this.is(TokenType.COMMA)) {
+    this.advance();
+    options = this.parseObjectLiteralExpr();
+  }
+  this.expect(TokenType.RPAREN);
+
+  // Parse link content (text or children)
+  let content = null;
+  if (this.is(TokenType.STRING)) {
+    content = this.parseTextNode();
+  } else if (this.is(TokenType.LBRACE)) {
+    this.advance();
+    content = [];
+    while (!this.is(TokenType.RBRACE) && !this.is(TokenType.EOF)) {
+      content.push(this.parseViewChild());
+    }
+    this.expect(TokenType.RBRACE);
+  }
+
+  return new ASTNode(NodeType.LinkDirective, { path, options, content });
+};
+
+/**
+ * Parse @outlet directive
+ */
+Parser.prototype.parseOutletDirective = function() {
+  let container = null;
+  if (this.is(TokenType.LPAREN)) {
+    this.advance();
+    if (this.is(TokenType.STRING)) {
+      container = this.expect(TokenType.STRING).value;
+    }
+    this.expect(TokenType.RPAREN);
+  }
+  return new ASTNode(NodeType.OutletDirective, { container });
+};
+
+/**
+ * Parse @navigate directive
+ */
+Parser.prototype.parseNavigateDirective = function() {
+  this.expect(TokenType.LPAREN);
+  const path = this.parseExpression();
+
+  let options = null;
+  if (this.is(TokenType.COMMA)) {
+    this.advance();
+    options = this.parseObjectLiteralExpr();
+  }
+  this.expect(TokenType.RPAREN);
+
+  return new ASTNode(NodeType.NavigateDirective, { path, options });
+};

package/compiler/parser/core.js

@@ -0,0 +1,306 @@
+/**
+ * Pulse Parser Core - Base parser infrastructure
+ *
+ * Contains NodeType constants, ASTNode class, and base Parser class with utility methods
+ *
+ * @module compiler/parser/core
+ */
+
+import { TokenType } from '../lexer.js';
+import { ParserError, SUGGESTIONS, getDocsUrl } from '../../runtime/errors.js';
+
+// ============================================================
+// AST Node Types
+// ============================================================
+
+export const NodeType = {
+  Program: 'Program',
+  ImportDeclaration: 'ImportDeclaration',
+  ImportSpecifier: 'ImportSpecifier',
+  PageDeclaration: 'PageDeclaration',
+  RouteDeclaration: 'RouteDeclaration',
+  PropsBlock: 'PropsBlock',
+  StateBlock: 'StateBlock',
+  ViewBlock: 'ViewBlock',
+  ActionsBlock: 'ActionsBlock',
+  StyleBlock: 'StyleBlock',
+  SlotElement: 'SlotElement',
+  Element: 'Element',
+  TextNode: 'TextNode',
+  Interpolation: 'Interpolation',
+  Directive: 'Directive',
+  IfDirective: 'IfDirective',
+  EachDirective: 'EachDirective',
+  EventDirective: 'EventDirective',
+  ModelDirective: 'ModelDirective',
+
+  // Accessibility directives
+  A11yDirective: 'A11yDirective',
+  LiveDirective: 'LiveDirective',
+  FocusTrapDirective: 'FocusTrapDirective',
+
+  // SSR directives
+  ClientDirective: 'ClientDirective',
+  ServerDirective: 'ServerDirective',
+
+  Property: 'Property',
+  ObjectLiteral: 'ObjectLiteral',
+  ArrayLiteral: 'ArrayLiteral',
+  Identifier: 'Identifier',
+  MemberExpression: 'MemberExpression',
+  CallExpression: 'CallExpression',
+  BinaryExpression: 'BinaryExpression',
+  UnaryExpression: 'UnaryExpression',
+  UpdateExpression: 'UpdateExpression',
+  Literal: 'Literal',
+  TemplateLiteral: 'TemplateLiteral',
+  ConditionalExpression: 'ConditionalExpression',
+  ArrowFunction: 'ArrowFunction',
+  SpreadElement: 'SpreadElement',
+  AssignmentExpression: 'AssignmentExpression',
+  FunctionDeclaration: 'FunctionDeclaration',
+  StyleRule: 'StyleRule',
+  StyleProperty: 'StyleProperty',
+
+  // Router nodes
+  RouterBlock: 'RouterBlock',
+  RoutesBlock: 'RoutesBlock',
+  RouteDefinition: 'RouteDefinition',
+  GuardHook: 'GuardHook',
+
+  // Store nodes
+  StoreBlock: 'StoreBlock',
+  GettersBlock: 'GettersBlock',
+  GetterDeclaration: 'GetterDeclaration',
+
+  // View directives for router
+  LinkDirective: 'LinkDirective',
+  OutletDirective: 'OutletDirective',
+  NavigateDirective: 'NavigateDirective'
+};
+
+// ============================================================
+// AST Node Class
+// ============================================================
+
+/**
+ * AST Node class
+ */
+export class ASTNode {
+  constructor(type, props = {}) {
+    this.type = type;
+    Object.assign(this, props);
+  }
+}
+
+// ============================================================
+// Base Parser Class
+// ============================================================
+
+/**
+ * Parser class with base utility methods
+ * Parse methods are added via modules (imports, state, view, style, expressions, blocks)
+ */
+export class Parser {
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.pos = 0;
+  }
+
+  /**
+   * Get current token
+   */
+  current() {
+    return this.tokens[this.pos];
+  }
+
+  /**
+   * Peek at token at offset
+   */
+  peek(offset = 1) {
+    const index = this.pos + offset;
+    if (index < 0 || index >= this.tokens.length) return undefined;
+    return this.tokens[index];
+  }
+
+  /**
+   * Check if current token matches type
+   */
+  is(type) {
+    return this.current()?.type === type;
+  }
+
+  /**
+   * Check if current token matches any of types
+   */
+  isAny(...types) {
+    return types.includes(this.current()?.type);
+  }
+
+  /**
+   * Advance to next token and return current
+   */
+  advance() {
+    return this.tokens[this.pos++];
+  }
+
+  /**
+   * Expect a specific token type
+   */
+  expect(type, message = null) {
+    if (!this.is(type)) {
+      const token = this.current();
+      throw this.createError(
+        message || `Expected ${type} but got ${token?.type}`,
+        token,
+        { suggestion: SUGGESTIONS['unexpected-token']?.(type, token?.type) }
+      );
+    }
+    return this.advance();
+  }
+
+  /**
+   * Create a parse error with detailed information
+   * @param {string} message - Error message
+   * @param {Object} [token] - Token where error occurred
+   * @param {Object} [options] - Additional options (suggestion, code)
+   * @returns {ParserError} The parser error
+   */
+  createError(message, token = null, options = {}) {
+    const t = token || this.current();
+    const code = options.code || 'PARSER_ERROR';
+
+    // Build enhanced message with docs link
+    let enhancedMessage = message;
+    if (options.suggestion) {
+      enhancedMessage += `\n  → ${options.suggestion}`;
+    }
+    enhancedMessage += `\n  See: ${getDocsUrl(code)}`;
+
+    return new ParserError(enhancedMessage, {
+      line: t?.line || 1,
+      column: t?.column || 1,
+      token: t,
+      code,
+      ...options
+    });
+  }
+
+  /**
+   * Parse the entire program
+   * This method delegates to specialized parse methods from other modules
+   */
+  parse() {
+    const program = new ASTNode(NodeType.Program, {
+      imports: [],
+      page: null,
+      route: null,
+      props: null,
+      state: null,
+      view: null,
+      actions: null,
+      style: null,
+      router: null,
+      store: null
+    });
+
+    while (!this.is(TokenType.EOF)) {
+      // Import declarations (must come first)
+      if (this.is(TokenType.IMPORT)) {
+        program.imports.push(this.parseImportDeclaration());
+      }
+      // Page/Route declarations
+      else if (this.is(TokenType.AT)) {
+        this.advance();
+        if (this.is(TokenType.PAGE)) {
+          program.page = this.parsePageDeclaration();
+        } else if (this.is(TokenType.ROUTE)) {
+          program.route = this.parseRouteDeclaration();
+        } else {
+          throw this.createError(
+            `Expected 'page' or 'route' after '@', got '${this.current()?.value}'`
+          );
+        }
+      }
+      // Props block
+      else if (this.is(TokenType.PROPS)) {
+        if (program.props) {
+          throw this.createError('Duplicate props block - only one props block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('props')
+          });
+        }
+        program.props = this.parsePropsBlock();
+      }
+      // State block
+      else if (this.is(TokenType.STATE)) {
+        if (program.state) {
+          throw this.createError('Duplicate state block - only one state block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('state')
+          });
+        }
+        program.state = this.parseStateBlock();
+      }
+      // View block
+      else if (this.is(TokenType.VIEW)) {
+        if (program.view) {
+          throw this.createError('Duplicate view block - only one view block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('view')
+          });
+        }
+        program.view = this.parseViewBlock();
+      }
+      // Actions block
+      else if (this.is(TokenType.ACTIONS)) {
+        if (program.actions) {
+          throw this.createError('Duplicate actions block - only one actions block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('actions')
+          });
+        }
+        program.actions = this.parseActionsBlock();
+      }
+      // Style block
+      else if (this.is(TokenType.STYLE)) {
+        if (program.style) {
+          throw this.createError('Duplicate style block - only one style block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('style')
+          });
+        }
+        program.style = this.parseStyleBlock();
+      }
+      // Router block
+      else if (this.is(TokenType.ROUTER)) {
+        if (program.router) {
+          throw this.createError('Duplicate router block - only one router block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('router')
+          });
+        }
+        program.router = this.parseRouterBlock();
+      }
+      // Store block
+      else if (this.is(TokenType.STORE)) {
+        if (program.store) {
+          throw this.createError('Duplicate store block - only one store block allowed per file', null, {
+            code: 'DUPLICATE_BLOCK',
+            suggestion: SUGGESTIONS['duplicate-declaration']?.('store')
+          });
+        }
+        program.store = this.parseStoreBlock();
+      }
+      else {
+        const token = this.current();
+        throw this.createError(
+          `Unexpected token '${token?.value || token?.type}' at line ${token?.line}:${token?.column}. ` +
+          `Expected: import, @page, @route, props, state, view, actions, style, router, or store`
+        );
+      }
+    }
+
+    return program;
+  }
+}