apexfile 1.1.0

package/src/resolver/index.js

@@ -0,0 +1,442 @@
+'use strict';
+
+/**
+ * ApexDoc Resolver
+ * Walks the AST and resolves:
+ *   - Variables  (@set name = "Cold"  → {name} = "Cold")
+ *   - Expressions  ({price * 1.1})
+ *   - Built-in functions  ({today()}, {uppercase("hello")})
+ *   - Filters  ({name | uppercase})
+ *   - Conditionals  (@if / @elseif / @else)
+ *   - Loops  (@each)
+ */
+
+class Resolver {
+  constructor(ast, context = {}) {
+    this.ast     = ast;
+    this.context = {
+      ...this._builtinContext(),
+      ...context,
+    };
+    this.errors = [];
+  }
+
+  // ── Entry Point ────────────────────────────────────────────────
+
+  resolve() {
+    // Extract variables from @set nodes first (first pass)
+    this._collectVars(this.ast.body, this.context);
+
+    // Second pass: resolve expressions and expand conditionals/loops
+    const resolvedBody = this._resolveNodes(this.ast.body, this.context);
+
+    return {
+      ...this.ast,
+      body:   resolvedBody,
+      _vars:  this.context,
+    };
+  }
+
+  // ── First Pass: Collect Variables ──────────────────────────────
+
+  _collectVars(nodes, ctx) {
+    for (const node of nodes) {
+      if (!node) continue;
+      if (node.type === 'SetVar') {
+        ctx[node.name] = this._evalExpression(node.value, ctx);
+      }
+    }
+  }
+
+  // ── Second Pass: Resolve Nodes ─────────────────────────────────
+
+  _resolveNodes(nodes, ctx) {
+    const result = [];
+
+    for (const node of nodes) {
+      if (!node) continue;
+
+      switch (node.type) {
+        case 'SetVar':
+          // Already collected in first pass — emit nothing
+          ctx[node.name] = this._evalExpression(node.value, ctx);
+          break;
+
+        case 'Conditional':
+          result.push(...this._resolveConditional(node, ctx));
+          break;
+
+        case 'Loop':
+          result.push(...this._resolveLoop(node, ctx));
+          break;
+
+        case 'Expression':
+          result.push({
+            ...node,
+            resolved: this._evalExpression(node.value, ctx),
+          });
+          break;
+
+        case 'Block':
+        case 'Heading':
+        case 'Paragraph':
+        case 'Blockquote':
+        case 'List':
+          result.push(this._resolveChildren(node, ctx));
+          break;
+
+        default:
+          result.push(node);
+          break;
+      }
+    }
+
+    return result;
+  }
+
+  _resolveChildren(node, ctx) {
+    const fields = ['children', 'items', 'body', 'consequent', 'fallback'];
+    const resolved = { ...node };
+
+    for (const field of fields) {
+      if (Array.isArray(node[field])) {
+        resolved[field] = this._resolveNodes(node[field], ctx);
+      }
+    }
+
+    return resolved;
+  }
+
+  // ── Conditional Resolution ─────────────────────────────────────
+
+  _resolveConditional(node, ctx) {
+    // Evaluate the @if condition
+    if (this._evalCondition(node.condition, ctx)) {
+      return this._resolveNodes(node.consequent, ctx);
+    }
+
+    // Evaluate @elseif branches
+    for (const alt of node.alternates) {
+      if (this._evalCondition(alt.condition, ctx)) {
+        return this._resolveNodes(alt.body, ctx);
+      }
+    }
+
+    // @else fallback
+    if (node.fallback.length > 0) {
+      return this._resolveNodes(node.fallback, ctx);
+    }
+
+    return [];
+  }
+
+  // ── Loop Resolution ────────────────────────────────────────────
+
+  _resolveLoop(node, ctx) {
+    const result = [];
+
+    let collection = this._evalExpression(node.source, ctx);
+
+    // range(start, end) shorthand
+    if (typeof collection === 'string') {
+      const rangeMatch = collection.match(/^range\((\d+),\s*(\d+)\)$/);
+      if (rangeMatch) {
+        const start = parseInt(rangeMatch[1]);
+        const end   = parseInt(rangeMatch[2]);
+        collection  = Array.from({ length: end - start + 1 }, (_, i) => start + i);
+      }
+    }
+
+    if (!Array.isArray(collection)) {
+      this.errors.push({ message: `@each source "${node.source}" is not iterable`, line: node.line });
+      return [];
+    }
+
+    for (const item of collection) {
+      const loopCtx = {
+        ...ctx,
+        [node.variable]: item,
+      };
+      result.push(...this._resolveNodes(node.body, loopCtx));
+    }
+
+    return result;
+  }
+
+  // ── Expression Evaluator ───────────────────────────────────────
+
+  _evalExpression(expr, ctx) {
+    if (expr === undefined || expr === null) return '';
+    const str = String(expr).trim();
+
+    // 1. Quoted string literal — strip quotes immediately
+    if ((str.startsWith('"') && str.endsWith('"')) ||
+        (str.startsWith("'") && str.endsWith("'"))) {
+      return str.slice(1, -1);
+    }
+
+    // 2. JSON array literal  ["A","B"]  or object {}
+    if ((str.startsWith('[') && str.endsWith(']')) ||
+        (str.startsWith('{') && str.endsWith('}'))) {
+      try { return JSON.parse(str); } catch (_) {}
+    }
+
+    // 3. Built-in functions
+    const builtinResult = this._evalBuiltin(str, ctx);
+    if (builtinResult !== null) return builtinResult;
+
+    // 4. Pipe filters  expr | filter
+    if (str.includes('|')) {
+      const pipeIdx = str.lastIndexOf('|');
+      const left    = str.slice(0, pipeIdx).trim();
+      const filter  = str.slice(pipeIdx + 1).trim();
+      const base    = this._evalExpression(left, ctx);
+      return this._applyFilter(base, filter, ctx);
+    }
+
+    // 5. Simple variable lookup
+    if (/^\w+$/.test(str) && str in ctx) {
+      return ctx[str];
+    }
+
+    // 6. Dot notation  user.name  (letters/underscore only — not numbers)
+    if (/^[a-zA-Z_][\w.]*$/.test(str)) {
+      const val = this._dotLookup(str, ctx);
+      if (val !== undefined && val !== '') return val;
+    }
+
+    // 7. Pure number
+    if (/^-?\d+\.?\d*$/.test(str)) return parseFloat(str);
+
+    // 8. Arithmetic/comparison expression  price * 1.1 + 5
+    try {
+      const evaluated = this._safeEval(str, ctx);
+      if (evaluated !== undefined) return evaluated;
+    } catch (_) {}
+
+    // 9. Return as-is (unresolvable string)
+    return str;
+  }
+
+  _evalCondition(condition, ctx) {
+    try {
+      return !!this._safeEval(condition, ctx);
+    } catch (_) {
+      return false;
+    }
+  }
+
+  /**
+   * Safe arithmetic/comparison evaluator.
+   * Only allows: numbers, booleans, comparison ops, arithmetic ops, variable names.
+   */
+  _safeEval(expr, ctx) {
+    // Substitute variables into expression
+    let safe = expr.replace(/\b([a-zA-Z_]\w*)\b/g, (match) => {
+      if (match in ctx) {
+        const val = ctx[match];
+        if (typeof val === 'string') return JSON.stringify(val);
+        if (typeof val === 'number' || typeof val === 'boolean') return String(val);
+        return JSON.stringify(val);
+      }
+      // Leave unknown identifiers — they'll cause a safe eval failure
+      return match;
+    });
+
+    // After substitution, reject anything with bare identifiers (not in quotes)
+    // Strip out string contents first, then check for raw letters
+    const stripped = safe.replace(/"[^"]*"|'[^']*'/g, '""');
+    if (/[a-zA-Z_]/.test(stripped)) return undefined;
+
+    // eslint-disable-next-line no-new-func
+    try {
+      return Function(`"use strict"; return (${safe});`)();
+    } catch (_) {
+      return undefined;
+    }
+  }
+
+  // ── Built-in Functions ─────────────────────────────────────────
+
+  _evalBuiltin(str, ctx) {
+    // today()
+    if (str === 'today()') return new Date().toISOString().slice(0, 10);
+
+    // now()
+    if (str === 'now()') return new Date().toISOString().slice(0, 19);
+
+    // timestamp()
+    if (str === 'timestamp()') return Math.floor(Date.now() / 1000);
+
+    // uuid()
+    if (str === 'uuid()') return this._uuid();
+
+    // readingTime()
+    if (str === 'readingTime()') return ctx.__readingTime || 'N/A';
+
+    // wordCount()
+    if (str === 'wordCount()') return ctx.__wordCount || 0;
+
+    // random(min, max)
+    const randomMatch = str.match(/^random\((\d+),\s*(\d+)\)$/);
+    if (randomMatch) {
+      const min = parseInt(randomMatch[1]);
+      const max = parseInt(randomMatch[2]);
+      return Math.floor(Math.random() * (max - min + 1)) + min;
+    }
+
+    // uppercase("text")
+    const upperMatch = str.match(/^uppercase\(["']?(.+?)["']?\)$/);
+    if (upperMatch) return this._evalExpression(upperMatch[1], ctx).toString().toUpperCase();
+
+    // lowercase("text")
+    const lowerMatch = str.match(/^lowercase\(["']?(.+?)["']?\)$/);
+    if (lowerMatch) return this._evalExpression(lowerMatch[1], ctx).toString().toLowerCase();
+
+    // length(expr)
+    const lenMatch = str.match(/^length\((.+)\)$/);
+    if (lenMatch) {
+      const val = this._evalExpression(lenMatch[1], ctx);
+      return Array.isArray(val) ? val.length : String(val).length;
+    }
+
+    // sum([...]) or sum(varName)
+    const sumMatch = str.match(/^sum\((.+)\)$/);
+    if (sumMatch) {
+      const val = this._evalExpression(sumMatch[1], ctx);
+      const arr = Array.isArray(val) ? val : [val];
+      return arr.reduce((a, b) => a + Number(b), 0);
+    }
+
+    // avg([...]) or avg(varName)
+    const avgMatch = str.match(/^avg\((.+)\)$/);
+    if (avgMatch) {
+      const val = this._evalExpression(avgMatch[1], ctx);
+      const arr = Array.isArray(val) ? val : [val];
+      return arr.reduce((a, b) => a + Number(b), 0) / arr.length;
+    }
+
+    // round(expr, decimals)
+    const roundMatch = str.match(/^round\((.+),\s*(\d+)\)$/);
+    if (roundMatch) {
+      const val  = this._evalExpression(roundMatch[1], ctx);
+      const decs = parseInt(roundMatch[2]);
+      return parseFloat(Number(val).toFixed(decs));
+    }
+
+    return null;
+  }
+
+  // ── Filters ────────────────────────────────────────────────────
+
+  _applyFilter(value, filter, ctx) {
+    // uppercase
+    if (filter === 'uppercase') return String(value).toUpperCase();
+
+    // lowercase
+    if (filter === 'lowercase') return String(value).toLowerCase();
+
+    // comma  (number formatting)
+    if (filter === 'comma') return Number(value).toLocaleString();
+
+    // join(", ")
+    const joinMatch = filter.match(/^join\(["']?([^"']*)["']?\)$/);
+    if (joinMatch && Array.isArray(value)) return value.join(joinMatch[1]);
+
+    // truncate(n)
+    const truncMatch = filter.match(/^truncate\((\d+)\)$/);
+    if (truncMatch) {
+      const n = parseInt(truncMatch[1]);
+      return String(value).length > n ? String(value).slice(0, n) + '…' : String(value);
+    }
+
+    // currency("USD")
+    const currMatch = filter.match(/^currency\(["']?(\w+)["']?\)$/);
+    if (currMatch) {
+      return new Intl.NumberFormat('en-US', {
+        style:    'currency',
+        currency: currMatch[1] || 'USD',
+      }).format(Number(value));
+    }
+
+    // format("DD MMM YYYY")  - date formatting
+    const fmtMatch = filter.match(/^format\(["'](.+)["']\)$/);
+    if (fmtMatch) {
+      const d   = new Date(value);
+      const fmt = fmtMatch[1];
+      return this._formatDate(d, fmt);
+    }
+
+    // round(n)
+    const roundMatch = filter.match(/^round\((\d+)\)$/);
+    if (roundMatch) return parseFloat(Number(value).toFixed(parseInt(roundMatch[1])));
+
+    return value;
+  }
+
+  // ── Dot Notation Lookup ────────────────────────────────────────
+
+  _dotLookup(path, ctx) {
+    const parts = path.split('.');
+    let val = ctx;
+    for (const part of parts) {
+      if (val === null || val === undefined) return '';
+      val = val[part];
+    }
+    return val ?? '';
+  }
+
+  // ── Date Formatter ─────────────────────────────────────────────
+
+  _formatDate(d, fmt) {
+    if (isNaN(d)) return fmt;
+    const pad = n => String(n).padStart(2, '0');
+    const months = ['January','February','March','April','May','June',
+                    'July','August','September','October','November','December'];
+    const short  = months.map(m => m.slice(0, 3));
+
+    return fmt
+      .replace('YYYY', d.getFullYear())
+      .replace('YY',   String(d.getFullYear()).slice(-2))
+      .replace('MMMM', months[d.getMonth()])
+      .replace('MMM',  short[d.getMonth()])
+      .replace('MM',   pad(d.getMonth() + 1))
+      .replace('DD',   pad(d.getDate()))
+      .replace('HH',   pad(d.getHours()))
+      .replace('mm',   pad(d.getMinutes()))
+      .replace('ss',   pad(d.getSeconds()));
+  }
+
+  // ── Built-in Context ───────────────────────────────────────────
+
+  _builtinContext() {
+    return {
+      const: {
+        c: 299792458,
+        G: 6.674e-11,
+        h: 6.626e-34,
+        pi: Math.PI,
+        e:  Math.E,
+      },
+      color: {
+        lighten:    (c, p) => c, // Placeholder — HTML renderer expands
+        darken:     (c, p) => c,
+        alpha:      (c, a) => c,
+        complement: (c)    => c,
+        mix:        (a, b, p) => a,
+        contrast:   (a, b)    => '4.5:1',
+      },
+    };
+  }
+
+  // ── UUID Generator ─────────────────────────────────────────────
+
+  _uuid() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+    });
+  }
+}
+
+module.exports = Resolver;