@entropicwarrior/sdoc 0.2.4 → 0.2.6

package/docs/reference/sdoc-authoring.sdoc

@@ -274,6 +274,34 @@ Content of Section B.
                 \|x\| + \|y\| | 8
             }
             ```
+
+            # Table Formulas @table-formulas
+            {
+                Cells starting with \`=\` are evaluated as formulas. Hover a computed cell in preview to see the original formula.
+
+                ```
+                {[table]
+                    Investor | Shares | Ownership
+                    Seed Fund | 500,000 | 25%
+                    Founder A | 1,000,000 | 50%
+                    Founder B | 500,000 | 25%
+                    **Total** | =SUM(B1:B3) | =SUM(C1:C3)
+                }
+                ```
+
+                Cell references use A1 notation (column letter + row number). Headers are excluded from row numbering, so the first data row is row 1.
+
+                {[.]
+                    - \`=SUM(range)\` — sum of values
+                    - \`=AVG(range)\` — arithmetic mean
+                    - \`=COUNT(range)\` — number of cells
+                    - Arithmetic: \`=B1+B2\`, \`=B1*3\`, \`=(A1+A2)/2\`, \`=-B1\`
+                    - Function names are uppercase only
+                    - Escape with \`\\=\` for a literal equals sign at the start of a cell
+                }
+
+                Errors display in red italic: \`#DIV/0!\` (division by zero), \`#VALUE!\` (bad reference), \`#REF!\` (invalid syntax), \`#NAME!\` (unknown function), \`#CIRCULAR!\` (circular dependency).
+            }
         }
 
         # Inline Formatting @inline-formatting
@@ -309,7 +337,7 @@ Content of Section B.
             ![A](a.png =48%) ![B](b.png =48%)
             ```
 
-            Autolinks: \`\<https://example.com\>\` — angle brackets are optional; bare URLs starting with \`http://\`, \`https://\`, or \`mailto:\` are also auto-linked.
+            Autolinks: \`\<https://example.com\>\` — angle brackets are optional; bare URLs starting with \`http://\`, \`https://\`, or \`mailto:\` are also auto-linked. Bare email addresses (e.g. \`hello@example.com\`) are automatically rendered as \`mailto:\` links.
 
             Math: Use \`\$...\$\` for inline math and \`\$\$...\$\$\` for display math. Use \`\\\`\\\`\\\`math\` code fences for multi-line equations. A plain \`\$\` followed by a digit (e.g. \`\$100\`) does not trigger math mode.
         }
@@ -691,21 +719,21 @@ Content of Section B.
 
         # Cross-Document @slug References @cross-doc-refs
         {
-            \`@slug\` references are document-local. Using \`@slug\` to refer to a section in another file produces a broken reference error:
+            \`@slug\` references are document-local. Using \`@slug\` to refer to a section in another file produces a broken reference error. This is the most common reference mistake — especially in audits, reviews, and documents that discuss other documents, where writing \`file.sdoc @section\` reads naturally but is wrong.
 
-            **Wrong** — \`@setup\` does not exist in this file:
+            **Wrong** — \`@extension\` looks for a local section, not one in \`foundations.sdoc\`:
 
             ```
-            See `getting-started.sdoc` @setup for installation steps.
+            See `foundations.sdoc` @extension for the design rationale.
             ```
 
             **Right** — use a link with a fragment:
 
             ```
-            See [Setup](./getting-started.sdoc#setup) for installation steps.
+            See [Extension](./foundations.sdoc#extension) for the design rationale.
             ```
 
-            The fragment (\`#setup\`) matches the target scope's \`@id\`. Use \`\\@\` if you need a literal \`@\` in text without triggering reference resolution.
+            The fragment (\`#extension\`) matches the target scope's \`@id\`. Use \`\\@\` if you need a literal \`@\` in text without triggering reference resolution.
         }
 
         # @References Inside Link Labels @refs-in-link-labels

package/docs/reference/slide-authoring.sdoc

@@ -4,7 +4,7 @@
     {
         type: skill
 
-        sdoc-version: 0.1
+        sdoc-version: 0.2
     }
 
     # About @about

package/lexica/specification.sdoc

@@ -378,6 +378,78 @@ Content of Section B.
 }
                 ```
             }
+
+            # Table Formulas @table-formulas
+            {
+                Table cells whose text begins with `=` (but not `==`) are evaluated as formulas. The result replaces the cell text in rendered output; the original formula is preserved as a tooltip.
+
+                ```
+{[table]
+    Item | Qty | Price
+    Widget | 10 | 5.00
+    Gadget | 5 | 12.50
+    **Total** | =SUM(B1:B2) | =SUM(C1:C2)
+}
+                ```
+
+                # Cell References
+                {
+                    {[.]
+                        - References use spreadsheet-style A1 notation: column letter (A-Z) followed by row number (1-based)
+                        - Row numbering starts at 1 for the first data row; headers are excluded from numbering
+                        - A range is two references separated by a colon: `A1:B3`
+                    }
+                }
+
+                # Supported Functions
+                {
+                    {[.]
+                        - `=SUM(range)` — sum of all values in the range
+                        - `=AVG(range)` — arithmetic mean of the range
+                        - `=COUNT(range)` — number of cells in the range
+                    }
+
+                    Function names are case-sensitive (uppercase only). Multiple ranges can be separated by commas: `=SUM(A1:A3,B1:B3)`.
+                }
+
+                # Arithmetic Expressions
+                {
+                    Cells may also contain arithmetic expressions using `+`, `-`, `*`, `/`, parentheses, and cell references:
+
+                    ```
+                    =B1+B2
+                    =B1*3
+                    =(A1+A2)/2
+                    =-B1
+                    ```
+
+                    Standard operator precedence applies (multiplication and division before addition and subtraction). Unary minus is supported.
+                }
+
+                # Percentage Values
+                {
+                    Cells ending in `%` are stored internally as decimals (e.g. `25%` = 0.25). When all values in a `SUM` or `AVG` are percentages, the result displays as a percentage. Arithmetic between percentages and plain numbers produces a plain number.
+                }
+
+                # Error Values
+                {
+                    {[.]
+                        - `#DIV/0!` — division by zero
+                        - `#VALUE!` — unresolvable reference (e.g. reference to a text cell or out-of-bounds)
+                        - `#REF!` — invalid cell reference syntax
+                        - `#NAME!` — unknown function name
+                        - `#SYNTAX!` — malformed formula expression
+                        - `#CIRCULAR!` — circular dependency between formula cells
+                    }
+
+                    Error cells are styled distinctly (red italic) and display the original formula as a tooltip.
+                }
+
+                # Escaping
+                {
+                    To display a literal `=` at the start of a cell, escape it: `\=SUM(...)` renders as plain text `=SUM(...)`.
+                }
+            }
         }
 
         # Paragraphs @paragraphs
@@ -431,6 +503,8 @@ Content of Section B.
             Only `http`, `https`, and `mailto` schemes are recognised.
 
             Bare URLs starting with `http://`, `https://`, or `mailto:` are also auto-linked without angle brackets.
+
+            Bare email addresses (e.g. `hello@example.com`) are automatically detected and rendered as `mailto:` links. The detection requires at least one character before and after the `@`, with a domain containing a dot. Email auto-detection does not apply inside code spans, links, or angle-bracket autolinks.
         }
 
         # Images @images

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -1309,7 +1309,35 @@ function parseInline(text) {
       }
     }
 
-    if (ch === "@" && next && isIdentStart(next)) {
+    // Bare email autolink: local@domain.tld
+    if (ch === "@" && next && /[A-Za-z0-9]/.test(next)) {
+      const prevCh = i > 0 ? text[i - 1] : "";
+      if (/[A-Za-z0-9._+-]/.test(prevCh)) {
+        // Scan forward for domain part (letters, digits, dots, hyphens)
+        let j = i + 1;
+        while (j < text.length && /[A-Za-z0-9.-]/.test(text[j])) j++;
+        // Strip trailing dots/hyphens
+        while (j > i + 1 && /[.-]/.test(text[j - 1])) j--;
+        const domain = text.slice(i + 1, j);
+        // Must have at least one dot with content on both sides
+        if (/^[A-Za-z0-9]([A-Za-z0-9-]*\.)+[A-Za-z]{2,}$/.test(domain)) {
+          // Extract local part from buffer
+          let k = buffer.length;
+          while (k > 0 && /[A-Za-z0-9._+\-]/.test(buffer[k - 1])) k--;
+          const local = buffer.slice(k);
+          if (local.length > 0) {
+            buffer = buffer.slice(0, k);
+            const email = local + "@" + domain;
+            flush();
+            nodes.push({ type: "link", href: "mailto:" + email, children: [{ type: "text", value: email }] });
+            i = j;
+            continue;
+          }
+        }
+      }
+    }
+
+    if (ch === "@" && next && isIdentStart(next) && !(i > 0 && /[A-Za-z0-9._+-]/.test(text[i - 1]))) {
       let j = i + 1;
       while (j < text.length && isIdentChar(text[j])) {
         j += 1;
@@ -1522,6 +1550,307 @@ function renderListItem(scope, listType, depth) {
   return `<section class="${scopeClass}">${heading}${bodyWrapper}</section>`;
 }
 
+// ── Table formula engine ──────────────────────────────────────────────
+
+function isFormulaCell(text) {
+  const t = text.trim();
+  return t.length > 1 && t[0] === "=" && t[1] !== "=" && !t.startsWith("\\=");
+}
+
+function parseCellRef(ref) {
+  const m = ref.match(/^([A-Z])(\d+)$/);
+  if (!m) return null;
+  return { col: m[1].charCodeAt(0) - 65, row: parseInt(m[2], 10) - 1 };
+}
+
+function expandRange(rangeStr) {
+  const parts = rangeStr.split(":");
+  if (parts.length !== 2) return null;
+  const start = parseCellRef(parts[0]);
+  const end = parseCellRef(parts[1]);
+  if (!start || !end) return null;
+  const refs = [];
+  for (let r = start.row; r <= end.row; r++) {
+    for (let c = start.col; c <= end.col; c++) {
+      refs.push({ col: c, row: r });
+    }
+  }
+  return refs;
+}
+
+function parseCellValue(text) {
+  const t = text.trim();
+  if (/^-?\d+(\.\d+)?%$/.test(t)) {
+    return { value: parseFloat(t) / 100, isPercent: true };
+  }
+  // Strip commas for numbers like 1,000,000
+  const stripped = t.replace(/,/g, "");
+  if (/^-?\d+(\.\d+)?$/.test(stripped)) {
+    return { value: parseFloat(stripped), isPercent: false };
+  }
+  return { value: NaN, isPercent: false };
+}
+
+function buildCellGrid(rows) {
+  return rows.map((row) => row.map((cell) => {
+    if (isFormulaCell(cell)) return { value: NaN, isPercent: false, formula: cell.trim().slice(1) };
+    return parseCellValue(cell);
+  }));
+}
+
+function resolveRef(grid, ref) {
+  if (ref.row < 0 || ref.row >= grid.length) return null;
+  if (ref.col < 0 || ref.col >= grid[ref.row].length) return null;
+  return grid[ref.row][ref.col];
+}
+
+function resolveRefs(grid, refs) {
+  const values = [];
+  for (const ref of refs) {
+    const cell = resolveRef(grid, ref);
+    if (!cell || isNaN(cell.value)) return null;
+    values.push(cell);
+  }
+  return values;
+}
+
+function tokenizeFormula(expr) {
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    if (/\s/.test(expr[i])) { i++; continue; }
+    // Function name
+    if (/[A-Z]/.test(expr[i]) && i + 1 < expr.length && /[A-Z]/.test(expr[i + 1])) {
+      let j = i;
+      while (j < expr.length && /[A-Z]/.test(expr[j])) j++;
+      tokens.push({ type: "func", value: expr.slice(i, j) });
+      i = j;
+      continue;
+    }
+    // Cell ref or range (e.g. A1, A1:B3)
+    if (/[A-Z]/.test(expr[i]) && i + 1 < expr.length && /\d/.test(expr[i + 1])) {
+      let j = i;
+      while (j < expr.length && /[A-Z0-9:]/.test(expr[j])) j++;
+      tokens.push({ type: "ref", value: expr.slice(i, j) });
+      i = j;
+      continue;
+    }
+    // Number
+    if (/[\d.]/.test(expr[i])) {
+      let j = i;
+      while (j < expr.length && /[\d.]/.test(expr[j])) j++;
+      const numStr = expr.slice(i, j);
+      if ((numStr.match(/\./g) || []).length > 1) return { error: "#SYNTAX!" };
+      if (j < expr.length && expr[j] === "%") {
+        tokens.push({ type: "num", value: parseFloat(numStr) / 100, isPercent: true });
+        j++;
+      } else {
+        tokens.push({ type: "num", value: parseFloat(numStr), isPercent: false });
+      }
+      i = j;
+      continue;
+    }
+    if ("+-*/(),".includes(expr[i])) {
+      tokens.push({ type: "op", value: expr[i] });
+      i++;
+      continue;
+    }
+    return { error: "#SYNTAX!" };
+  }
+  return { tokens };
+}
+
+function evaluateFormula(formula, grid) {
+  const { tokens, error } = tokenizeFormula(formula);
+  if (error) return { value: NaN, isPercent: false, error };
+
+  let pos = 0;
+  const peek = () => pos < tokens.length ? tokens[pos] : null;
+  const consume = () => tokens[pos++];
+
+  function resolveArg() {
+    const tok = peek();
+    if (!tok) return null;
+    if (tok.type === "ref") {
+      consume();
+      if (tok.value.includes(":")) {
+        const refs = expandRange(tok.value);
+        if (!refs) return { error: "#REF!" };
+        const cells = resolveRefs(grid, refs);
+        if (!cells) return { error: "#VALUE!" };
+        return { cells };
+      } else {
+        const ref = parseCellRef(tok.value);
+        if (!ref) return { error: "#REF!" };
+        const cell = resolveRef(grid, ref);
+        if (!cell || isNaN(cell.value)) return { error: "#VALUE!" };
+        return { cells: [cell] };
+      }
+    }
+    return null;
+  }
+
+  function parseFuncArgs() {
+    const allCells = [];
+    if (!peek() || peek().value !== "(") return { error: "#SYNTAX!" };
+    consume(); // (
+    while (peek() && peek().value !== ")") {
+      const arg = resolveArg();
+      if (!arg) return { error: "#SYNTAX!" };
+      if (arg.error) return arg;
+      allCells.push(...arg.cells);
+      if (peek() && peek().value === ",") consume();
+    }
+    if (!peek() || peek().value !== ")") return { error: "#SYNTAX!" };
+    consume(); // )
+    return { cells: allCells };
+  }
+
+  function parseAtom() {
+    const tok = peek();
+    if (!tok) return { error: "#SYNTAX!" };
+
+    if (tok.type === "func") {
+      const fname = consume().value;
+      const args = parseFuncArgs();
+      if (args.error) return args;
+      const allPercent = args.cells.every((c) => c.isPercent);
+      const vals = args.cells.map((c) => c.value);
+      if (fname === "SUM") {
+        return { value: vals.reduce((a, b) => a + b, 0), isPercent: allPercent };
+      } else if (fname === "AVG") {
+        if (vals.length === 0) return { error: "#DIV/0!" };
+        return { value: vals.reduce((a, b) => a + b, 0) / vals.length, isPercent: allPercent };
+      } else if (fname === "COUNT") {
+        return { value: vals.length, isPercent: false };
+      }
+      return { error: "#NAME!" };
+    }
+
+    if (tok.type === "num") {
+      consume();
+      return { value: tok.value, isPercent: tok.isPercent };
+    }
+
+    if (tok.type === "ref") {
+      consume();
+      const ref = parseCellRef(tok.value);
+      if (!ref) return { error: "#REF!" };
+      const cell = resolveRef(grid, ref);
+      if (!cell || isNaN(cell.value)) return { error: "#VALUE!" };
+      return { value: cell.value, isPercent: cell.isPercent };
+    }
+
+    if (tok.type === "op" && tok.value === "(") {
+      consume();
+      const result = parseExpr();
+      if (result.error) return result;
+      if (!peek() || peek().value !== ")") return { error: "#SYNTAX!" };
+      consume();
+      return result;
+    }
+
+    // Unary minus
+    if (tok.type === "op" && tok.value === "-") {
+      consume();
+      const operand = parseAtom();
+      if (operand.error) return operand;
+      return { value: -operand.value, isPercent: operand.isPercent };
+    }
+
+    return { error: "#SYNTAX!" };
+  }
+
+  function parseTerm() {
+    let left = parseAtom();
+    if (left.error) return left;
+    while (peek() && (peek().value === "*" || peek().value === "/")) {
+      const op = consume().value;
+      const right = parseAtom();
+      if (right.error) return right;
+      if (op === "/") {
+        if (right.value === 0) return { error: "#DIV/0!" };
+        left = { value: left.value / right.value, isPercent: false };
+      } else {
+        left = { value: left.value * right.value, isPercent: false };
+      }
+    }
+    return left;
+  }
+
+  function parseExpr() {
+    let left = parseTerm();
+    if (left.error) return left;
+    while (peek() && (peek().value === "+" || peek().value === "-")) {
+      const op = consume().value;
+      const right = parseTerm();
+      if (right.error) return right;
+      const bothPercent = left.isPercent && right.isPercent;
+      left = {
+        value: op === "+" ? left.value + right.value : left.value - right.value,
+        isPercent: bothPercent,
+      };
+    }
+    return left;
+  }
+
+  const result = parseExpr();
+  if (result.error) return { value: NaN, isPercent: false, error: result.error };
+  if (peek()) return { value: NaN, isPercent: false, error: "#SYNTAX!" };
+  return { value: result.value, isPercent: result.isPercent, error: null };
+}
+
+function evaluateGrid(grid) {
+  // Track which cells started as formulas for circular reference detection
+  const formulaCells = [];
+  for (let r = 0; r < grid.length; r++) {
+    for (let c = 0; c < grid[r].length; c++) {
+      if (grid[r][c].formula) formulaCells.push([r, c]);
+    }
+  }
+  // Topological evaluation: resolve formulas that depend on other formulas
+  const maxPasses = formulaCells.length + 1;
+  for (let pass = 0; pass < maxPasses; pass++) {
+    let pending = false;
+    for (let r = 0; r < grid.length; r++) {
+      for (let c = 0; c < grid[r].length; c++) {
+        const cell = grid[r][c];
+        if (!cell.formula) continue;
+        const result = evaluateFormula(cell.formula, grid);
+        if (result.error === "#VALUE!" && pass < maxPasses - 1) {
+          // Might resolve on a later pass when dependencies are computed
+          pending = true;
+          continue;
+        }
+        cell.value = result.value;
+        cell.isPercent = result.isPercent;
+        cell.error = result.error;
+        delete cell.formula;
+      }
+    }
+    if (!pending) break;
+  }
+  // Any formula cells still showing #VALUE! after all passes are circular
+  for (const [r, c] of formulaCells) {
+    if (grid[r][c].error === "#VALUE!") {
+      grid[r][c].error = "#CIRCULAR!";
+    }
+  }
+  return grid;
+}
+
+function formatFormulaResult(cell) {
+  if (cell.error) return cell.error;
+  if (cell.isPercent) {
+    const pct = cell.value * 100;
+    return (Number.isInteger(pct) ? pct.toString() : pct.toFixed(2).replace(/\.?0+$/, "")) + "%";
+  }
+  if (Number.isInteger(cell.value)) return cell.value.toLocaleString();
+  return cell.value.toFixed(2).replace(/\.?0+$/, "");
+}
+
+// ── End formula engine ───────────────────────────────────────────────
+
 function renderTable(table) {
   const dl = dataLineAttrs(table);
   const opts = table.options || {};
@@ -1538,10 +1867,24 @@ function renderTable(table) {
     thead = `<thead class="sdoc-table-head"><tr>${headerCells}</tr></thead>`;
   }
 
+  // Formula evaluation
+  const grid = evaluateGrid(buildCellGrid(table.rows));
+
   const bodyRows = table.rows
-    .map((row) => {
+    .map((row, r) => {
       const cells = row
-        .map((cell) => `<td class="sdoc-table-td">${renderInline(cell)}</td>`)
+        .map((cell, c) => {
+          if (isFormulaCell(cell)) {
+            const result = grid[r][c];
+            const display = escapeHtml(formatFormulaResult(result));
+            const formula = escapeAttr(cell.trim());
+            if (result.error) {
+              return `<td class="sdoc-table-td sdoc-formula-error" title="${formula}">${display}</td>`;
+            }
+            return `<td class="sdoc-table-td sdoc-formula-cell" title="${formula}">${display}</td>`;
+          }
+          return `<td class="sdoc-table-td">${renderInline(cell)}</td>`;
+        })
         .join("");
       return `<tr>${cells}</tr>`;
     })
@@ -1871,6 +2214,19 @@ const DEFAULT_STYLE = `
     border-bottom: none;
   }
 
+  td.sdoc-formula-cell {
+    font-variant-numeric: tabular-nums;
+    font-weight: 600;
+    color: #2a7a8a !important;
+    cursor: help;
+    border-bottom: 1px dotted #2a7a8a40;
+  }
+  td.sdoc-formula-error {
+    color: #c33 !important;
+    font-style: italic;
+    cursor: help;
+  }
+
   .sdoc-table-borderless,
   .sdoc-table-borderless th,
   .sdoc-table-borderless td {