@entropicwarrior/sdoc 0.2.5 → 0.2.7

package/README.md

@@ -74,7 +74,17 @@ Key resources for agents:
 | [`docs/reference/sdoc-authoring.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc) | Skill document — drop into context to read/write SDOC immediately |
 | [`lexica/specification.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc) | Formal spec with EBNF grammar |
 
-All `.sdoc` files are designed for progressive disclosure — read the `@about` scope first (~50 tokens), then scan headings, then load only the section you need.
+All `.sdoc` files are designed for progressive disclosure. The JavaScript API provides three functions that let agents navigate without loading entire files:
+
+```javascript
+const { extractAbout, listSections, extractSection } = require("@entropicwarrior/sdoc");
+
+extractAbout(text);              // ~50 tokens — what is this file about?
+listSections(text);              // ~50-100 tokens — what sections does it have?
+extractSection(text, "error-handling"); // ~200-1000 tokens — give me just this section
+```
+
+Total cost for a precise answer: ~750 tokens. The same lookup in Markdown requires loading the full file (5,000-50,000 tokens).
 
 ## Format at a Glance
 
@@ -159,7 +169,7 @@ Markdown-style images with optional width and alignment:
 
 ### Tables
 
-Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely.
+Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely. Cells starting with `=` are evaluated as formulas (`=SUM`, `=AVG`, `=COUNT`, arithmetic with A1 cell references).
 
 ### Lists
 

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.5",
+  "version": "0.2.7",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -1550,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 || {};
@@ -1566,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>`;
     })
@@ -1899,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 {
@@ -2453,8 +2781,31 @@ function firstParagraphPreview(nodes, maxLen) {
   return "";
 }
 
+/**
+ * Recursively collect all tagged (has @id) scope nodes from the content tree.
+ * Skips @meta and @about. Used for deep section discovery — lets MCP clients
+ * find sections nested inside top-level scopes (e.g. @pass-terminology inside
+ * @pedantic-review inside @writing).
+ */
+function getAllTaggedScopes(nodes) {
+  const result = [];
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "scope") {
+        if (node.id && node.id.toLowerCase() !== "meta" && node.id.toLowerCase() !== "about") {
+          result.push(node);
+        }
+        if (node.children) walk(node.children);
+      }
+    }
+  }
+  const doc = getDocumentScope(nodes);
+  walk(doc ? doc.children : nodes);
+  return result;
+}
+
 function listSections(nodes) {
-  return getContentScopes(nodes).map((node) => ({
+  return getAllTaggedScopes(nodes).map((node) => ({
     id: node.id || null,
     derivedId: slugify(node.title),
     title: node.title,
@@ -2474,7 +2825,7 @@ function collectDataBlocks(children) {
 }
 
 function extractSection(nodes, sectionId) {
-  const scopes = getContentScopes(nodes);
+  const scopes = getAllTaggedScopes(nodes);
 
   function buildResult(node) {
     const data = collectDataBlocks(node.children || []);