apexfile 1.1.0

package/src/index.js

@@ -0,0 +1,438 @@
+'use strict';
+
+/**
+ * ApexDoc — Public API
+ *
+ * Usage:
+ *   const apex = require('apexdoc');
+ *
+ *   const ast  = apex.parse('./doc.apx');
+ *   const html = apex.render(ast, 'html');
+ *   apex.export(ast, 'pdf', './dist/doc.pdf');
+ */
+
+const fs          = require('fs');
+const path        = require('path');
+const Tokenizer   = require('./tokenizer');
+const Parser      = require('./parser');
+const Resolver    = require('./resolver');
+const HTMLRenderer = require('./renderer/html');
+
+// ── Core Pipeline ───────────────────────────────────────────────────────────
+
+/**
+ * Parse an .apx source string or file path into a resolved AST.
+ *
+ * @param {string} input  — Raw .apx source OR a file path ending in .apx
+ * @param {object} context — Optional variable context to inject
+ * @returns {object} Resolved AST document node
+ */
+function parse(input, context = {}) {
+  let source = input;
+
+  // Accept file paths
+  if (typeof input === 'string' && input.endsWith('.apx') && fs.existsSync(input)) {
+    source = fs.readFileSync(input, 'utf8');
+  }
+
+  // 1. Tokenize
+  const tokenizer = new Tokenizer(source);
+  const tokens    = tokenizer.tokenize();
+
+  // 2. Parse tokens → raw AST
+  const parser    = new Parser(tokens);
+  const rawAst    = parser.parse();
+
+  // 3. Resolve variables, expressions, conditionals, loops
+  const resolver  = new Resolver(rawAst, context);
+  const ast       = resolver.resolve();
+
+  // Attach any parse/resolve errors
+  ast._errors = [...(parser.errors || []), ...(resolver.errors || [])];
+
+  return ast;
+}
+
+/**
+ * Render a resolved AST to a target format string.
+ *
+ * @param {object} ast    — Resolved AST from parse()
+ * @param {string} target — 'html' | 'text' | 'json' | 'md'
+ * @returns {string}
+ */
+function render(ast, target = 'html') {
+  switch (target.toLowerCase()) {
+    case 'html':
+      return new HTMLRenderer(ast).render();
+    case 'json':
+      return JSON.stringify(ast, null, 2);
+    case 'text':
+      return renderPlainText(ast);
+    case 'md':
+      return renderMarkdown(ast);
+    default:
+      throw new ApexError(`Unknown render target: "${target}". Use: html, json, text, md`);
+  }
+}
+
+/**
+ * Parse + render in one step.
+ *
+ * @param {string} input   — Source or file path
+ * @param {string} target  — Render target
+ * @param {object} context — Variable context
+ * @returns {string}
+ */
+function compile(input, target = 'html', context = {}) {
+  const ast = parse(input, context);
+  return render(ast, target);
+}
+
+/**
+ * Parse + render + write to output file.
+ *
+ * @param {string} input      — Source or file path
+ * @param {string} target     — Render target
+ * @param {string} outputPath — Destination file path
+ * @param {object} context    — Variable context
+ */
+function exportFile(input, target = 'html', outputPath, context = {}) {
+  const output = compile(input, target, context);
+
+  // Auto-generate output path if not given
+  if (!outputPath) {
+    const base = typeof input === 'string' && input.endsWith('.apx')
+      ? input.replace(/\.apx$/, '')
+      : 'output';
+    const ext = { html: '.html', text: '.txt', json: '.json', md: '.md' };
+    outputPath = base + (ext[target] || '.html');
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, output, 'utf8');
+  return outputPath;
+}
+
+// ── Linter ──────────────────────────────────────────────────────────────────
+
+/**
+ * Validate an .apx source and return a list of errors/warnings.
+ *
+ * @param {string} input — Source or file path
+ * @returns {{ errors: Array, warnings: Array, valid: boolean }}
+ */
+function lint(input) {
+  const errors   = [];
+  const warnings = [];
+
+  let source = input;
+  if (typeof input === 'string' && input.endsWith('.apx') && fs.existsSync(input)) {
+    source = fs.readFileSync(input, 'utf8');
+  }
+
+  try {
+    const ast = parse(source);
+
+    // Propagate parse errors
+    if (ast._errors) {
+      errors.push(...ast._errors);
+    }
+
+    // Structural checks
+    const checks = _runLintChecks(source, ast);
+    errors.push(...checks.errors);
+    warnings.push(...checks.warnings);
+
+  } catch (err) {
+    errors.push({ code: 'APX001', message: err.message, line: 0 });
+  }
+
+  return { errors, warnings, valid: errors.length === 0 };
+}
+
+function _runLintChecks(source, ast) {
+  const errors   = [];
+  const warnings = [];
+  const lines    = source.split('\n');
+
+  // APX002: Unclosed blocks
+  let openCount  = 0;
+  let closeCount = 0;
+  lines.forEach((line, i) => {
+    const t = line.trim();
+    if (t.startsWith('%%') && !t.startsWith('%%end') && !t.includes('%%end')) openCount++;
+    if (t === '%%end') closeCount++;
+  });
+  if (openCount !== closeCount) {
+    errors.push({
+      code: 'APX002',
+      message: `Unclosed blocks detected: ${openCount} opened, ${closeCount} closed`,
+      line: 0,
+    });
+  }
+
+  // APX005: Undefined variables in expressions
+  const vars     = new Set(Object.keys(ast._vars || {}));
+  const exprRe   = /\{(\w+)\}/g;
+  lines.forEach((line, i) => {
+    let m;
+    while ((m = exprRe.exec(line)) !== null) {
+      const name = m[1];
+      if (!vars.has(name) && !_isBuiltinFn(name)) {
+        warnings.push({
+          code: 'APX005',
+          message: `Possibly undefined variable: "{${name}}"`,
+          line: i + 1,
+        });
+      }
+    }
+  });
+
+  // APX009: Unknown theme reference
+  const metaTheme    = ast.meta?.fields?.theme;
+  const knownThemes  = new Set([
+    'default', 'dark-ocean', 'neon-city', 'sunset', 'minimal-light',
+    'forest', 'candy', 'terminal', 'academic', 'newspaper',
+    ...Object.keys(ast.style?.themes || {}),
+  ]);
+  if (metaTheme && !knownThemes.has(metaTheme)) {
+    warnings.push({
+      code: 'APX009',
+      message: `Theme "${metaTheme}" is not defined in %%style or built-in themes`,
+      line: 0,
+    });
+  }
+
+  return { errors, warnings };
+}
+
+function _isBuiltinFn(name) {
+  const builtins = ['today', 'now', 'timestamp', 'uuid', 'random', 'uppercase',
+                    'lowercase', 'length', 'sum', 'avg', 'round', 'readingTime', 'wordCount'];
+  return builtins.includes(name);
+}
+
+// ── AST Inspector ───────────────────────────────────────────────────────────
+
+/**
+ * Return the raw AST as a clean JSON string (for debugging).
+ */
+function inspect(input) {
+  const ast = parse(input);
+  return JSON.stringify(ast, null, 2);
+}
+
+// ── Plain Text Renderer ─────────────────────────────────────────────────────
+
+function renderPlainText(ast) {
+  const lines = [];
+
+  function walkNode(node) {
+    if (!node) return '';
+    switch (node.type) {
+      case 'Heading':    return '#'.repeat(node.level) + ' ' + walkChildren(node) + '\n';
+      case 'Paragraph':  return walkChildren(node) + '\n\n';
+      case 'Text':       return node.value;
+      case 'Bold':       return '**' + walkChildren(node) + '**';
+      case 'Italic':     return '_' + walkChildren(node) + '_';
+      case 'CodeInline': return '`' + node.value + '`';
+      case 'MathInline': return '$' + node.value + '$';
+      case 'Expression': return String(node.resolved ?? node.value);
+      case 'Link':       return walkChildren(node) + ' (' + node.href + ')';
+      case 'List':       return node.items.map(i => '- ' + walkChildren(i)).join('\n') + '\n';
+      case 'Blockquote': return '> ' + walkChildren(node) + '\n';
+      case 'HR':         return '---\n';
+      case 'Block':      return walkChildren(node);
+      default:           return walkChildren(node) || '';
+    }
+  }
+
+  function walkChildren(node) {
+    if (!node.children && !node.items && !node.body) return '';
+    const arr = node.children || node.items || node.body || [];
+    return arr.map(walkNode).join('');
+  }
+
+  return ast.body.map(walkNode).join('');
+}
+
+// ── Markdown Renderer ───────────────────────────────────────────────────────
+
+function renderMarkdown(ast) {
+  // Best-effort Markdown export
+  // Apex features without Markdown equivalents are stripped or approximated
+
+  function walkNode(node) {
+    if (!node) return '';
+    switch (node.type) {
+      case 'Heading':    return '#'.repeat(node.level) + ' ' + walkChildren(node) + '\n\n';
+      case 'Paragraph':  return walkChildren(node) + '\n\n';
+      case 'Text':       return node.value;
+      case 'Bold':       return '**' + walkChildren(node) + '**';
+      case 'Italic':     return '_' + walkChildren(node) + '_';
+      case 'Underline':  return '__' + walkChildren(node) + '__';
+      case 'Strike':     return '~~' + walkChildren(node) + '~~';
+      case 'CodeInline': return '`' + node.value + '`';
+      case 'MathInline': return '$' + node.value + '$';
+      case 'Expression': return String(node.resolved ?? node.value);
+      case 'Link':       return '[' + walkChildren(node) + '](' + node.href + ')';
+      case 'Blockquote': return '> ' + walkChildren(node) + '\n\n';
+      case 'HR':         return '---\n\n';
+      case 'List':       return node.items.map(i => {
+        const prefix = i.type === 'TaskItem'
+          ? (i.state === 'done' ? '- [x] ' : '- [ ] ')
+          : '- ';
+        return prefix + walkChildren(i);
+      }).join('\n') + '\n\n';
+      case 'Block': {
+        if (node.name === 'code') {
+          const raw  = node.children?.[0]?.value || '';
+          const lang = node.props?.lang || '';
+          return '```' + lang + '\n' + raw + '\n```\n\n';
+        }
+        if (node.name === 'math') {
+          const raw = node.children?.[0]?.value || '';
+          return '$$\n' + raw + '\n$$\n\n';
+        }
+        return walkChildren(node);
+      }
+      default: return walkChildren(node) || '';
+    }
+  }
+
+  function walkChildren(node) {
+    const arr = node.children || node.items || node.body || [];
+    return arr.map(walkNode).join('');
+  }
+
+  const meta = ast.meta?.fields || {};
+  let front  = '';
+  if (Object.keys(meta).length > 0) {
+    front = '---\n' + Object.entries(meta)
+      .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+      .join('\n') + '\n---\n\n';
+  }
+
+  return front + ast.body.map(walkNode).join('');
+}
+
+// ── Error Class ─────────────────────────────────────────────────────────────
+
+class ApexError extends Error {
+  constructor(message, code = 'APX000', line = 0) {
+    super(message);
+    this.name  = 'ApexError';
+    this.code  = code;
+    this.line  = line;
+  }
+}
+
+// ── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * Create a blank .apx document template string.
+ */
+function template(type = 'document') {
+  const templates = {
+    document: `%%meta
+  title:   "My Document"
+  author:  "Author"
+  theme:   dark-ocean
+%%end
+
+%%style
+  --primary: #00f5d4
+  --bg:      #0d0d0d
+  --text:    #f0f0f0
+  --font:    "Inter", sans-serif
+%%end
+
+%%body
+
+# My Document
+
+Welcome to **ApexDoc** — the last document format you'll ever need.
+
+%%end
+`,
+    presentation: `%%meta
+  title:  "My Presentation"
+  mode:   presentation
+  theme:  dark-ocean
+%%end
+
+%%style
+  --primary: #00f5d4
+%%end
+
+%%body
+
+%%slide {transition: fade}
+  # Slide One
+  Your content here.
+%%end
+
+%%slide {transition: slideLeft}
+  # Slide Two
+  More content here.
+%%end
+
+%%end
+`,
+    report: `%%meta
+  title:   "Report"
+  author:  "Author"
+  toc:     true
+  theme:   minimal-light
+%%end
+
+%%style
+  --primary: #1a1a2e
+  --bg:      #ffffff
+  --text:    #222222
+%%end
+
+%%body
+
+# Executive Summary
+
+Write your summary here.
+
+## Section One
+
+Content goes here.
+
+## Section Two
+
+Content goes here.
+
+%%end
+`,
+  };
+
+  return templates[type] || templates.document;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Core
+  parse,
+  render,
+  compile,
+  export:   exportFile,
+
+  // Tools
+  lint,
+  inspect,
+  template,
+
+  // Renderers (direct access)
+  HTMLRenderer,
+
+  // Classes (for extending)
+  Tokenizer,
+  Parser,
+  Resolver,
+  ApexError,
+};