apexfile 1.1.0

package/src/parser/index.js

@@ -0,0 +1,594 @@
+'use strict';
+
+/**
+ * ApexDoc Parser
+ * Converts a flat token array (from Tokenizer) into a full AST.
+ *
+ * Parsing strategy:
+ *   1. Partition tokens into META / STYLE / BODY groups
+ *   2. Parse each group into its subtree
+ *   3. Merge into a Document root node
+ */
+
+const T    = require('../tokenizer/tokens');
+const Node = require('../ast');
+
+class Parser {
+  constructor(tokens) {
+    this.tokens  = tokens;
+    this.pos     = 0;
+    this.errors  = [];
+  }
+
+  // ── Entry Point ────────────────────────────────────────────────
+
+  parse() {
+    const groups = this._partition();
+
+    const meta  = this._parseMeta(groups.meta);
+    const style = this._parseStyle(groups.style);
+    const body  = this._parseBody(groups.body);
+
+    return Node.document(meta, style, body);
+  }
+
+  // ── Partition tokens into sections ────────────────────────────
+
+  _partition() {
+    const groups = { meta: [], style: [], body: [] };
+
+    let current = null;
+    let depth   = 0;
+
+    for (const tok of this.tokens) {
+      if (tok.type === T.SECTION_OPEN) {
+        current = tok.value; // 'meta' | 'style' | 'body'
+        depth   = 0;
+        continue;
+      }
+
+      if (tok.type === T.SECTION_CLOSE) {
+        current = null;
+        continue;
+      }
+
+      if (tok.type === T.EOF) break;
+
+      // If no section is open, assume body (bare file)
+      const target = current || 'body';
+      if (groups[target]) {
+        groups[target].push(tok);
+      }
+    }
+
+    return groups;
+  }
+
+  // ── META Parser ────────────────────────────────────────────────
+
+  _parseMeta(tokens) {
+    const fields = {};
+
+    for (const tok of tokens) {
+      if (tok.type === T.META_FIELD) {
+        fields[tok.value] = tok.props.value;
+      }
+    }
+
+    return Node.meta(fields);
+  }
+
+  // ── STYLE Parser ───────────────────────────────────────────────
+
+  _parseStyle(tokens) {
+    const variables  = {};
+    const themes     = {};
+    const directives = [];
+
+    let i           = 0;
+    let currentBlock = null;  // current @theme / @media name
+
+    while (i < tokens.length) {
+      const tok = tokens[i];
+
+      if (tok.type === T.STYLE_BLOCK_OPEN) {
+        // e.g. @theme dark-ocean  or  @media (prefers-color-scheme: dark)
+        currentBlock = { directive: tok.value, name: tok.props.name, vars: {} };
+        i++;
+        continue;
+      }
+
+      if (tok.type === T.STYLE_BLOCK_CLOSE) {
+        if (currentBlock) {
+          if (currentBlock.directive === '@theme') {
+            themes[currentBlock.name] = currentBlock.vars;
+          }
+          // @media / @breakpoint blocks stored in directives with their vars
+          else {
+            directives.push({
+              directive: currentBlock.directive,
+              name:      currentBlock.name,
+              variables: currentBlock.vars,
+            });
+          }
+          currentBlock = null;
+        }
+        i++;
+        continue;
+      }
+
+      if (tok.type === T.STYLE_VAR) {
+        if (currentBlock) {
+          currentBlock.vars[tok.value] = tok.props.value;
+        } else {
+          variables[tok.value] = tok.props.value;
+        }
+        i++;
+        continue;
+      }
+
+      if (tok.type === T.STYLE_DIRECTIVE) {
+        directives.push(Node.styleDirective(tok.value, tok.props));
+        i++;
+        continue;
+      }
+
+      i++;
+    }
+
+    return Node.style(variables, themes, directives);
+  }
+
+  // ── BODY Parser ────────────────────────────────────────────────
+
+  _parseBody(tokens) {
+    this._bodyTokens = tokens;
+    this._bodyPos    = 0;
+    return this._parseNodes();
+  }
+
+  /**
+   * Parse a sequence of nodes until we hit EOF or a matching BLOCK_CLOSE.
+   * This is called recursively for nested blocks.
+   */
+  _parseNodes(stopAtBlockClose = false) {
+    const nodes = [];
+
+    while (this._bodyPos < this._bodyTokens.length) {
+      const tok = this._bodyTokens[this._bodyPos];
+
+      if (!tok || tok.type === T.EOF) break;
+
+      // Stop when we hit a block close (used for nested block parsing)
+      if (stopAtBlockClose && tok.type === T.BLOCK_CLOSE) break;
+
+      const node = this._parseNode();
+      if (node) {
+        // Flatten arrays (inline parsers return arrays)
+        if (Array.isArray(node)) {
+          nodes.push(...node.filter(Boolean));
+        } else {
+          nodes.push(node);
+        }
+      }
+    }
+
+    return nodes;
+  }
+
+  _parseNode() {
+    const tok = this._current();
+    if (!tok) return null;
+
+    switch (tok.type) {
+
+      // ── Headings ──────────────────────────────────────────────
+      case T.HEADING: {
+        this._advance();
+        // Parse heading text as inline content
+        const children = this._parseInlineText(tok.value, tok.line);
+        return Node.heading(tok.props.level, children, tok.props, tok.line);
+      }
+
+      // ── Block (%%name {props} ... %%end) ──────────────────────
+      case T.BLOCK_OPEN: {
+        return this._parseBlock();
+      }
+
+      // ── Self-Closing Block ─────────────────────────────────────
+      case T.BLOCK_SELF_CLOSE: {
+        this._advance();
+        return Node.selfCloseBlock(tok.value, tok.props, tok.line);
+      }
+
+      // ── Logic ─────────────────────────────────────────────────
+      case T.SET: {
+        this._advance();
+        return Node.setVar(tok.value, tok.props.value, tok.line);
+      }
+
+      case T.IF: {
+        return this._parseConditional();
+      }
+
+      case T.EACH: {
+        return this._parseLoop();
+      }
+
+      case T.KEYFRAME: {
+        return this._parseKeyframe();
+      }
+
+      case T.MATH_BLOCK: {
+        this._advance();
+        return Node.mathBlock(tok.value, tok.props, tok.line);
+      }
+
+      // ── Lists ─────────────────────────────────────────────────
+      case T.LIST_ITEM:
+      case T.LIST_ITEM_ORDERED:
+      case T.LIST_ITEM_TASK: {
+        return this._parseList();
+      }
+
+      // ── Blockquote ────────────────────────────────────────────
+      case T.BLOCKQUOTE: {
+        return this._parseBlockquote();
+      }
+
+      // ── HR ────────────────────────────────────────────────────
+      case T.HR: {
+        this._advance();
+        return Node.hr(tok.value, tok.line);
+      }
+
+      // ── Footnotes ─────────────────────────────────────────────
+      case T.FOOTNOTE_DEF: {
+        this._advance();
+        return Node.footnoteDef(tok.value, tok.props.content, tok.line);
+      }
+
+      // ── Inline text tokens → paragraph ────────────────────────
+      case T.TEXT:
+      case T.BOLD:
+      case T.ITALIC:
+      case T.UNDERLINE:
+      case T.STRIKETHROUGH:
+      case T.SUPERSCRIPT:
+      case T.SUBSCRIPT:
+      case T.CODE_INLINE:
+      case T.HIGHLIGHT:
+      case T.INLINE_STYLED:
+      case T.LINK:
+      case T.FOOTNOTE_REF:
+      case T.MATH_INLINE:
+      case T.EXPRESSION: {
+        return this._parseParagraph();
+      }
+
+      // ── Newline ───────────────────────────────────────────────
+      case T.NEWLINE: {
+        this._advance();
+        return null; // Skip bare newlines — paragraphs handle spacing
+      }
+
+      // ── Unknown / skip ────────────────────────────────────────
+      default: {
+        this._advance();
+        return null;
+      }
+    }
+  }
+
+  // ── Block Parser ───────────────────────────────────────────────
+
+  _parseBlock() {
+    const openTok = this._current();
+    this._advance(); // consume BLOCK_OPEN
+
+    const name     = openTok.value;
+    const props    = openTok.props;
+    const children = [];
+
+    // Special handling for blocks with raw content (code, math, etc.)
+    const RAW_BLOCKS = new Set(['code', 'math', 'chem', 'svg', 'uml',
+                                 'flowchart', 'sequence', 'terminal',
+                                 'diff', 'keyframe']);
+
+    if (RAW_BLOCKS.has(name)) {
+      // Collect raw text lines until BLOCK_CLOSE
+      const rawLines = [];
+      while (this._bodyPos < this._bodyTokens.length) {
+        const tok = this._current();
+        if (!tok || tok.type === T.BLOCK_CLOSE) break;
+        if (tok.type === T.TEXT)    rawLines.push(tok.value);
+        if (tok.type === T.NEWLINE) rawLines.push('');
+        this._advance();
+      }
+      this._advance(); // consume BLOCK_CLOSE
+      return Node.block(name, props, [Node.text(rawLines.join('\n'), openTok.line)], openTok.line);
+    }
+
+    // For special nesting-aware blocks, parse children recursively
+    while (this._bodyPos < this._bodyTokens.length) {
+      const tok = this._current();
+      if (!tok || tok.type === T.EOF) break;
+      if (tok.type === T.BLOCK_CLOSE) {
+        this._advance(); // consume %%end
+        break;
+      }
+      const child = this._parseNode();
+      if (child) {
+        if (Array.isArray(child)) children.push(...child.filter(Boolean));
+        else children.push(child);
+      }
+    }
+
+    return Node.block(name, props, children, openTok.line);
+  }
+
+  // ── List Parser ────────────────────────────────────────────────
+
+  _parseList() {
+    const items   = [];
+    const isTask  = this._current().type === T.LIST_ITEM_TASK;
+    const ordered = this._current().type === T.LIST_ITEM_ORDERED;
+
+    while (this._bodyPos < this._bodyTokens.length) {
+      const tok = this._current();
+      if (!tok) break;
+
+      // Stop if we see something that's not a list item
+      const isListTok = tok.type === T.LIST_ITEM ||
+                        tok.type === T.LIST_ITEM_ORDERED ||
+                        tok.type === T.LIST_ITEM_TASK;
+      if (!isListTok) break;
+
+      this._advance();
+      const children = this._parseInlineText(tok.value, tok.line);
+
+      if (tok.type === T.LIST_ITEM_TASK) {
+        items.push(Node.taskItem(children, tok.props.state, tok.props.indent, tok.line));
+      } else {
+        items.push(Node.listItem(children, tok.props.indent, tok.line));
+      }
+    }
+
+    return Node.list(items, ordered, items[0]?.line);
+  }
+
+  // ── Blockquote Parser ──────────────────────────────────────────
+
+  _parseBlockquote() {
+    const lines = [];
+    const level = this._current().props.level;
+
+    while (this._bodyPos < this._bodyTokens.length) {
+      const tok = this._current();
+      if (!tok || tok.type !== T.BLOCKQUOTE) break;
+      if (tok.props.level !== level) break;
+      this._advance();
+      lines.push(tok.value);
+    }
+
+    const children = this._parseInlineText(lines.join(' '), lines[0]?.line);
+    return Node.blockquote(children, level, lines[0]?.line);
+  }
+
+  // ── Paragraph Parser ───────────────────────────────────────────
+
+  _parseParagraph() {
+    const INLINE_TYPES = new Set([
+      T.TEXT, T.BOLD, T.ITALIC, T.UNDERLINE, T.STRIKETHROUGH,
+      T.SUPERSCRIPT, T.SUBSCRIPT, T.CODE_INLINE, T.HIGHLIGHT,
+      T.INLINE_STYLED, T.LINK, T.FOOTNOTE_REF, T.EXPRESSION,
+      T.MATH_INLINE,
+    ]);
+
+    const children = [];
+    const lineNum  = this._current()?.line;
+
+    // Collect all consecutive inline tokens
+    while (this._bodyPos < this._bodyTokens.length) {
+      const tok = this._current();
+      if (!tok) break;
+      if (tok.type === T.NEWLINE) {
+        // Two newlines in a row = paragraph break
+        const next = this._peek(1);
+        if (!next || next.type === T.NEWLINE) break;
+        // Single newline — soft break, continue paragraph
+        this._advance();
+        continue;
+      }
+      if (!INLINE_TYPES.has(tok.type)) break;
+
+      children.push(this._parseInlineNode(tok));
+      this._advance();
+    }
+
+    if (children.length === 0) return null;
+    return Node.paragraph(children, lineNum);
+  }
+
+  // ── Conditional Parser ─────────────────────────────────────────
+
+  _parseConditional() {
+    const tok       = this._current();
+    const condition = tok.value;
+    this._advance(); // consume @if
+
+    const consequent = [];
+    const alternates = [];
+    let   fallback   = [];
+    let   branch     = 'if'; // 'if' | 'elseif' | 'else'
+    let   currentAlt = null;
+
+    while (this._bodyPos < this._bodyTokens.length) {
+      const t = this._current();
+      if (!t || t.type === T.EOF) break;
+
+      if (t.type === T.END_LOGIC) {
+        this._advance();
+        if (currentAlt) {
+          alternates.push(currentAlt);
+          currentAlt = null;
+        }
+        break;
+      }
+
+      if (t.type === T.ELSEIF) {
+        if (currentAlt) alternates.push(currentAlt);
+        currentAlt = { condition: t.value, body: [] };
+        branch = 'elseif';
+        this._advance();
+        continue;
+      }
+
+      if (t.type === T.ELSE) {
+        if (currentAlt) { alternates.push(currentAlt); currentAlt = null; }
+        branch = 'else';
+        this._advance();
+        continue;
+      }
+
+      const node = this._parseNode();
+      if (!node) continue;
+
+      if (branch === 'if')     consequent.push(node);
+      else if (branch === 'elseif' && currentAlt) currentAlt.body.push(node);
+      else if (branch === 'else')  fallback.push(node);
+    }
+
+    return Node.conditional(condition, consequent, alternates, fallback, tok.line);
+  }
+
+  // ── Loop Parser ────────────────────────────────────────────────
+
+  _parseLoop() {
+    const tok = this._current();
+    this._advance(); // consume @each
+
+    const variable = tok.value;
+    const source   = tok.props.source;
+    const body     = [];
+
+    while (this._bodyPos < this._bodyTokens.length) {
+      const t = this._current();
+      if (!t || t.type === T.EOF) break;
+      if (t.type === T.END_LOGIC) { this._advance(); break; }
+
+      const node = this._parseNode();
+      if (node) body.push(node);
+    }
+
+    return Node.loop(variable, source, body, tok.line);
+  }
+
+  // ── Keyframe Parser ────────────────────────────────────────────
+
+  _parseKeyframe() {
+    const tok = this._current();
+    this._advance();
+    const name  = tok.value;
+    const steps = {};
+
+    // Collect text lines and parse as keyframe steps
+    while (this._bodyPos < this._bodyTokens.length) {
+      const t = this._current();
+      if (!t || t.type === T.EOF || t.type === T.BLOCK_CLOSE) break;
+      if (t.type === T.TEXT) {
+        // e.g. "0%   { transform: scale(1) }"
+        const stepMatch = t.value.match(/^(\d+%|from|to)\s*\{([^}]*)\}/);
+        if (stepMatch) {
+          steps[stepMatch[1]] = stepMatch[2].trim();
+        }
+      }
+      this._advance();
+    }
+    if (this._current()?.type === T.BLOCK_CLOSE) this._advance();
+
+    return Node.keyframe(name, steps, tok.line);
+  }
+
+  // ── Inline Node Builder ────────────────────────────────────────
+
+  /**
+   * Build an inline AST node from a single token.
+   * Called during paragraph parsing.
+   */
+  _parseInlineNode(tok) {
+    switch (tok.type) {
+      case T.TEXT:          return Node.text(tok.value, tok.line);
+      case T.BOLD:          return Node.bold(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.ITALIC:        return Node.italic(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.UNDERLINE:     return Node.underline(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.STRIKETHROUGH: return Node.strikethrough(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.SUPERSCRIPT:   return Node.superscript(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.SUBSCRIPT:     return Node.subscript(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.CODE_INLINE:   return Node.codeInline(tok.value, tok.line);
+      case T.HIGHLIGHT:     return Node.highlight(this._parseInlineText(tok.value, tok.line), tok.line);
+      case T.EXPRESSION:    return Node.expression(tok.value, tok.line);
+      case T.MATH_INLINE:   return Node.mathInline(tok.value, tok.line);
+      case T.FOOTNOTE_REF:  return Node.footnoteRef(tok.value, tok.line);
+
+      case T.INLINE_STYLED:
+        return Node.inlineStyled(
+          this._parseInlineText(tok.value, tok.line),
+          tok.props.props || {},
+          tok.line
+        );
+
+      case T.LINK:
+        return Node.link(
+          this._parseInlineText(tok.value, tok.line),
+          tok.props.href || '',
+          tok.line
+        );
+
+      default:
+        return Node.text(tok.value || '', tok.line);
+    }
+  }
+
+  /**
+   * Re-tokenize a plain string as inline nodes.
+   * Used for heading text, list items, and blockquote content.
+   */
+  _parseInlineText(text, lineNum) {
+    if (!text || text.trim() === '') return [];
+
+    // We re-use the tokenizer's inline method
+    const Tokenizer = require('../tokenizer');
+    const tmpTok    = new Tokenizer('');
+    const inlineToks = tmpTok._tokenizeInline(text, lineNum || 0);
+
+    return inlineToks.map(tok => this._parseInlineNode(tok)).filter(Boolean);
+  }
+
+  // ── Cursor Helpers ─────────────────────────────────────────────
+
+  _current() {
+    return this._bodyTokens[this._bodyPos] || null;
+  }
+
+  _peek(offset = 1) {
+    return this._bodyTokens[this._bodyPos + offset] || null;
+  }
+
+  _advance() {
+    this._bodyPos++;
+    return this._bodyTokens[this._bodyPos - 1];
+  }
+
+  _error(msg, tok) {
+    const err = {
+      code:    'APX-PARSE',
+      message: msg,
+      line:    tok?.line || 0,
+    };
+    this.errors.push(err);
+    return err;
+  }
+}
+
+module.exports = Parser;