@particle-academy/holy-sheet 2.11.1 → 2.11.2

package/dist/cli.cjs

@@ -1066,13 +1066,46 @@ var ERR_REF = "#REF!";
 var ERR_NAME = "#NAME?";
 var ERR_DIV0 = "#DIV/0!";
 var ERR_CIRC = "#CIRC!";
+var FUNCTIONS = /* @__PURE__ */ new Set([
+  "SUM",
+  "AVERAGE",
+  "AVG",
+  "COUNT",
+  "COUNTA",
+  "MIN",
+  "MAX",
+  "IF",
+  "ROUND",
+  "ABS",
+  "LEN",
+  "UPPER",
+  "LOWER",
+  "CONCAT",
+  "CONCATENATE",
+  "TRUE",
+  "FALSE"
+]);
 var SHEET_QUALIFIER = "('(?:[^']|'')+'|[A-Za-z_][A-Za-z0-9_.]*)!";
-var LinterError = class extends Error {
-  constructor(errorCode) {
+var LinterError = class _LinterError extends Error {
+  /**
+   * @param cause Why a #NAME? arose in THIS formula: "syntax" or "function".
+   *   Null for an error that was computed, or inherited from another cell.
+   * @param detail The syntax fault, or the unknown function's name.
+   */
+  constructor(errorCode, cause = null, detail = "") {
     super(errorCode);
     this.errorCode = errorCode;
+    this.cause = cause;
+    this.detail = detail;
+  }
+  static syntax(detail) {
+    return new _LinterError(ERR_NAME, "syntax", detail);
   }
 };
+var isSpace = (ch) => ch === " " || ch >= "	" && ch <= "\r";
+var isDigit = (ch) => ch >= "0" && ch <= "9";
+var isAlpha = (ch) => ch >= "A" && ch <= "Z" || ch >= "a" && ch <= "z";
+var isAlnum = (ch) => isAlpha(ch) || isDigit(ch);
 var FormulaLinter = class {
   constructor() {
     this.index = /* @__PURE__ */ new Map();
@@ -1083,10 +1116,25 @@ var FormulaLinter = class {
      * `#REF!` rather than a range of blanks.
      */
     this.sheetNames = /* @__PURE__ */ new Map();
+    /**
+     * Why a cell's own formula produced #NAME?, keyed `Sheet!A1`: a syntax
+     * error, an unknown function, or a linter fault. A cell with #NAME? and no
+     * entry here inherited it from a cell it references.
+     */
+    this.nameCauses = /* @__PURE__ */ new Map();
+    /**
+     * Greater than 0 while parsing an IF branch that is not taken. The parser
+     * evaluates as it goes, so a skipped branch is still PARSED (its syntax
+     * errors and unknown functions are reported) but nothing in it is
+     * EVALUATED: no operator runs, no cell is read, and every value is null.
+     */
+    this.skipping = 0;
   }
   lint(schema) {
     const workbook = new Normalizer().normalize(schema);
     this.sheetNames = new Map(workbook.sheets.map((sheet) => [sheet.name.toLowerCase(), sheet.name]));
+    this.nameCauses = /* @__PURE__ */ new Map();
+    this.skipping = 0;
     this.index = this.buildIndex(workbook);
     this.cache = /* @__PURE__ */ new Map();
     const issues = [];
@@ -1102,7 +1150,7 @@ var FormulaLinter = class {
             address,
             formula: cell.formula,
             error: result,
-            hint: this.hint(result, cell.formula, sheet.name)
+            hint: this.hint(result, key, cell.formula, sheet.name)
           });
         }
       }
@@ -1122,25 +1170,39 @@ var FormulaLinter = class {
     return typeof v === "string" && v.length > 0 && v[0] === "#";
   }
   evaluate(formula2, defaultSheet, stack) {
+    const key = stack[stack.length - 1];
+    this.nameCauses.delete(key);
     try {
       const c = { tokens: this.tokenize(formula2), pos: 0 };
       const result = this.parseExpr(c, defaultSheet, stack);
-      if (c.pos < c.tokens.length) return ERR_NAME;
+      if (c.pos < c.tokens.length) {
+        throw LinterError.syntax(`unexpected ${this.describeToken(c.tokens[c.pos])} after a complete expression`);
+      }
       return result;
     } catch (e) {
-      if (e instanceof LinterError) return e.errorCode;
+      if (e instanceof LinterError) {
+        if (e.cause !== null) this.nameCauses.set(key, { cause: e.cause, detail: e.detail });
+        return e.errorCode;
+      }
+      this.nameCauses.set(key, { cause: "internal", detail: e instanceof Error ? e.constructor.name : typeof e });
       return ERR_NAME;
     }
   }
+  describeToken(tok) {
+    switch (tok.type) {
+      case "STRING":
+        return 'text "' + tok.value + '"';
+      case "NUMBER":
+        return "number " + tok.value;
+      default:
+        return "'" + tok.value + "'";
+    }
+  }
   // ---- Tokenizer ----
   tokenize(src) {
     const tokens = [];
     let i = 0;
     const len = src.length;
-    const isSpace = (ch) => /\s/.test(ch);
-    const isDigit = (ch) => ch >= "0" && ch <= "9";
-    const isAlpha = (ch) => /[A-Za-z]/.test(ch);
-    const isAlnum = (ch) => /[A-Za-z0-9]/.test(ch);
     while (i < len) {
       const ch = src[i];
       if (isSpace(ch)) {
@@ -1155,10 +1217,21 @@ var FormulaLinter = class {
       }
       if (ch === '"') {
         i++;
-        const start = i;
-        while (i < len && src[i] !== '"') i++;
-        const value = src.slice(start, i);
-        i++;
+        let value = "";
+        for (; ; ) {
+          if (i >= len) throw LinterError.syntax('a text literal opens with " and never closes');
+          if (src[i] === '"') {
+            if (i + 1 < len && src[i + 1] === '"') {
+              value += '"';
+              i += 2;
+              continue;
+            }
+            i++;
+            break;
+          }
+          value += src[i];
+          i++;
+        }
         tokens.push({ type: "STRING", value });
         continue;
       }
@@ -1166,7 +1239,7 @@ var FormulaLinter = class {
         const start = i;
         i++;
         for (; ; ) {
-          if (i >= len) throw new LinterError(ERR_NAME);
+          if (i >= len) throw LinterError.syntax("a quoted sheet name opens with ' and never closes");
           if (src[i] === "'") {
             if (i + 1 < len && src[i + 1] === "'") {
               i += 2;
@@ -1199,7 +1272,9 @@ var FormulaLinter = class {
         i++;
         continue;
       }
-      throw new LinterError(ERR_NAME);
+      throw LinterError.syntax(
+        ch.charCodeAt(0) < 128 ? `unexpected character '${ch}'` : "unexpected non-ASCII character outside a text literal"
+      );
     }
     return tokens;
   }
@@ -1217,7 +1292,7 @@ var FormulaLinter = class {
       const op = c.tokens[c.pos].value;
       c.pos++;
       const right = this.parseConcat(c, sheet, stack);
-      left = this.compare(left, right, op);
+      left = this.skipping > 0 ? null : this.compare(left, right, op);
     }
     return left;
   }
@@ -1226,7 +1301,7 @@ var FormulaLinter = class {
     while (this.isOp(c, "&")) {
       c.pos++;
       const right = this.parseArith(c, sheet, stack);
-      left = this.coerceString(left) + this.coerceString(right);
+      left = this.skipping > 0 ? null : this.coerceString(left) + this.coerceString(right);
     }
     return left;
   }
@@ -1236,6 +1311,10 @@ var FormulaLinter = class {
       const op = c.tokens[c.pos].value;
       c.pos++;
       const right = this.parseTerm(c, sheet, stack);
+      if (this.skipping > 0) {
+        left = null;
+        continue;
+      }
       const a = this.coerceNumber(left);
       const b = this.coerceNumber(right);
       left = op === "+" ? a + b : a - b;
@@ -1243,46 +1322,68 @@ var FormulaLinter = class {
     return left;
   }
   parseTerm(c, sheet, stack) {
-    let left = this.parseUnary(c, sheet, stack);
-    while (this.isOp(c, "*", "/", "%", "^")) {
+    let left = this.parsePower(c, sheet, stack);
+    while (this.isOp(c, "*", "/")) {
       const op = c.tokens[c.pos].value;
       c.pos++;
-      const right = this.parseUnary(c, sheet, stack);
+      const right = this.parsePower(c, sheet, stack);
+      if (this.skipping > 0) {
+        left = null;
+        continue;
+      }
       const a = this.coerceNumber(left);
       const b = this.coerceNumber(right);
-      switch (op) {
-        case "*":
-          left = a * b;
-          break;
-        case "/":
-          if (b === 0) throw new LinterError(ERR_DIV0);
-          left = a / b;
-          break;
-        case "%":
-          left = a / 100 * b;
-          break;
-        case "^":
-          left = a ** b;
-          break;
+      if (op === "*") {
+        left = a * b;
+      } else {
+        if (b === 0) throw new LinterError(ERR_DIV0);
+        left = a / b;
       }
     }
     return left;
   }
+  /**
+   * `^` binds tighter than `*` and `/` (=2*3^2 is 18) and, as in Excel, is
+   * left-associative (=2^3^2 is 64). Negation binds tighter than `^`, so
+   * =-2^2 is 4: Excel's order, not mathematics'.
+   */
+  parsePower(c, sheet, stack) {
+    let left = this.parseUnary(c, sheet, stack);
+    while (this.isOp(c, "^")) {
+      c.pos++;
+      const right = this.parseUnary(c, sheet, stack);
+      left = this.skipping > 0 ? null : this.coerceNumber(left) ** this.coerceNumber(right);
+    }
+    return left;
+  }
   parseUnary(c, sheet, stack) {
     if (this.isOp(c, "-")) {
       c.pos++;
       const v = this.parseUnary(c, sheet, stack);
-      return -this.coerceNumber(v);
+      return this.skipping > 0 ? null : -this.coerceNumber(v);
     }
     if (this.isOp(c, "+")) {
       c.pos++;
       return this.parseUnary(c, sheet, stack);
     }
-    return this.parsePrimary(c, sheet, stack);
+    return this.parsePercent(c, sheet, stack);
+  }
+  /**
+   * Excel's `%` is a POSTFIX operator that divides by 100: `50%` is 0.5 and
+   * `A1%` is A1/100. It binds tighter than `^`, `*` and `/`. There is no
+   * binary `%`, so `10%2` leaves a stray `2` and is a syntax error.
+   */
+  parsePercent(c, sheet, stack) {
+    let value = this.parsePrimary(c, sheet, stack);
+    while (this.isOp(c, "%")) {
+      c.pos++;
+      value = this.skipping > 0 ? null : this.coerceNumber(value) / 100;
+    }
+    return value;
   }
   parsePrimary(c, sheet, stack) {
     const tok = this.peek(c);
-    if (!tok) throw new LinterError(ERR_NAME);
+    if (!tok) throw LinterError.syntax("the formula ends where a value was expected");
     if (tok.type === "OP" && tok.value === "(") {
       c.pos++;
       const val = this.parseExpr(c, sheet, stack);
@@ -1302,15 +1403,19 @@ var FormulaLinter = class {
       const next2 = c.tokens[c.pos + 2];
       if (next && next.type === "OP" && next.value === "!" && next2 && next2.type === "IDENT") {
         const sheetName2 = this.sheetNames.get(this.cleanSheetName(tok.value).toLowerCase());
-        if (sheetName2 === void 0) throw new LinterError(ERR_REF);
+        if (sheetName2 === void 0 && this.skipping === 0) throw new LinterError(ERR_REF);
         c.pos += 2;
         const startTok = c.tokens[c.pos].value;
         c.pos++;
-        return this.resolveRefOrRange(startTok, sheetName2, c, stack);
+        return this.resolveRefOrRange(startTok, sheetName2 ?? tok.value, c, stack);
+      }
+      if (tok.type === "SHEET") {
+        throw LinterError.syntax(`the quoted name ${tok.value} is not followed by ! and a cell reference`);
       }
-      if (tok.type === "SHEET") throw new LinterError(ERR_NAME);
       if (next && next.type === "OP" && next.value === "(") {
         const name = tok.value.toUpperCase();
+        if (!FUNCTIONS.has(name)) throw new LinterError(ERR_NAME, "function", name);
+        if (name === "IF") return this.parseIf(c, sheet, stack);
         c.pos += 2;
         const args = [];
         if (!this.isOp(c, ")")) {
@@ -1324,7 +1429,7 @@ var FormulaLinter = class {
           }
         }
         this.expectOp(c, ")");
-        return this.callFunction(name, args);
+        return this.skipping > 0 ? null : this.callFunction(name, args);
       }
       const upper = tok.value.toUpperCase();
       if (upper === "TRUE" || upper === "FALSE") {
@@ -1334,13 +1439,65 @@ var FormulaLinter = class {
       c.pos++;
       return this.resolveRefOrRange(tok.value, sheet, c, stack);
     }
-    throw new LinterError(ERR_NAME);
+    throw LinterError.syntax(`unexpected ${this.describeToken(tok)} where a value was expected`);
+  }
+  /**
+   * IF, evaluated lazily as Excel does: `=IF(A2=0,0,1/A2)` with A2 = 0 is 0,
+   * not #DIV/0!. Every argument is parsed, so a syntax error or an unknown
+   * function anywhere in it is still reported, but only the condition and the
+   * branch it selects are evaluated.
+   *
+   * The order of the verdicts is deliberate. A syntax error anywhere wins,
+   * because Excel refuses a formula it cannot parse and computes nothing.
+   * Then fewer than two arguments is #VALUE!. Then an error in the condition
+   * propagates, and neither branch is evaluated.
+   */
+  parseIf(c, sheet, stack) {
+    c.pos += 2;
+    const args = [];
+    let take = null;
+    let conditionError = null;
+    if (!this.isOp(c, ")")) {
+      for (; ; ) {
+        const i = args.length;
+        const skip = i > 0 && i !== take;
+        if (skip) this.skipping++;
+        try {
+          args.push(this.parseExpr(c, sheet, stack));
+        } finally {
+          if (skip) this.skipping--;
+        }
+        if (i === 0 && this.skipping === 0) {
+          try {
+            take = this.toLogical(args[0]) ? 1 : 2;
+          } catch (e) {
+            if (!(e instanceof LinterError)) throw e;
+            conditionError = e;
+          }
+        }
+        if (this.isOp(c, ",")) {
+          c.pos++;
+          continue;
+        }
+        break;
+      }
+    }
+    this.expectOp(c, ")");
+    if (this.skipping > 0) return null;
+    if (args.length < 2) return ERR_VALUE;
+    if (conditionError !== null) throw conditionError;
+    return take === 1 ? args[1] : args[2] ?? false;
   }
   resolveRefOrRange(startRef, defaultSheet, c, stack) {
+    const next = c.tokens[c.pos + 1];
+    const isRange = this.isOp(c, ":") && !!next && next.type === "IDENT";
+    if (this.skipping > 0) {
+      if (isRange) c.pos += 2;
+      return null;
+    }
     const cleanStart = this.cleanRef(startRef);
     if (cleanStart === null) throw new LinterError(ERR_REF);
-    const next = c.tokens[c.pos + 1];
-    if (this.isOp(c, ":") && next && next.type === "IDENT") {
+    if (isRange) {
       const endRef = next.value;
       c.pos += 2;
       const cleanEnd = this.cleanRef(endRef);
@@ -1394,7 +1551,10 @@ var FormulaLinter = class {
   }
   expectOp(c, op) {
     const t = c.tokens[c.pos];
-    if (!t || t.type !== "OP" || t.value !== op) throw new LinterError(ERR_NAME);
+    if (!t) throw LinterError.syntax(`expected '${op}', but the formula ends`);
+    if (t.type !== "OP" || t.value !== op) {
+      throw LinterError.syntax(`expected '${op}', found ${this.describeToken(t)}`);
+    }
     c.pos++;
   }
   // ---- Coercion / comparison / functions ----
@@ -1439,17 +1599,28 @@ var FormulaLinter = class {
         return false;
     }
   }
+  /**
+   * Excel's comparison. An error on either side propagates. Otherwise the
+   * types rank number < text < logical, so ="5">9 is TRUE: numeric TEXT is
+   * text, never a number. Text compares without regard to case. A blank
+   * takes the other side's type (0, "" or FALSE); two blanks are equal.
+   */
   cmpVal(a, b) {
-    const an = typeof a === "number" || typeof a === "string" && isNumericString(a);
-    const bn = typeof b === "number" || typeof b === "string" && isNumericString(b);
-    if (an && bn) {
-      const x = Number(a);
-      const y = Number(b);
-      return x < y ? -1 : x > y ? 1 : 0;
-    }
-    const sa = String(a);
-    const sb = String(b);
-    return sa < sb ? -1 : sa > sb ? 1 : 0;
+    if (this.isError(a)) throw new LinterError(a);
+    if (this.isError(b)) throw new LinterError(b);
+    if (Array.isArray(a) || Array.isArray(b)) {
+      return compareCodePoints(String(a), String(b));
+    }
+    const x = a ?? blankLike(b);
+    const y = b ?? blankLike(x);
+    const rank = (v) => typeof v === "boolean" ? 2 : typeof v === "string" ? 1 : 0;
+    if (rank(x) !== rank(y)) return rank(x) < rank(y) ? -1 : 1;
+    if (typeof x === "string") {
+      return compareCodePoints(x.toLowerCase(), String(y).toLowerCase());
+    }
+    const p = Number(x);
+    const q = Number(y);
+    return p < q ? -1 : p > q ? 1 : 0;
   }
   callFunction(name, args) {
     const flat = this.flatten(args);
@@ -1467,10 +1638,8 @@ var FormulaLinter = class {
         return this.minMax(flat, true);
       case "MAX":
         return this.minMax(flat, false);
-      case "IF":
-        return this.ifFn(args);
       case "ROUND":
-        return phpRound(this.coerceNumber(args[0] ?? 0), Math.trunc(this.coerceNumber(args[1] ?? 0)));
+        return excelRound(this.coerceNumber(args[0] ?? 0), Math.trunc(this.coerceNumber(args[1] ?? 0)));
       case "ABS":
         return Math.abs(this.coerceNumber(args[0] ?? 0));
       case "LEN":
@@ -1487,7 +1656,7 @@ var FormulaLinter = class {
       case "FALSE":
         return false;
       default:
-        return ERR_NAME;
+        throw new LinterError(ERR_NAME, "function", name);
     }
   }
   flatten(args) {
@@ -1515,21 +1684,34 @@ var FormulaLinter = class {
     const vals = nums.map((v) => this.maybeNum(v));
     return min ? Math.min(...vals) : Math.max(...vals);
   }
-  ifFn(args) {
-    if (args.length < 2) return ERR_VALUE;
-    const cond = args[0];
-    const truthy = typeof cond === "boolean" ? cond : cond !== null && cond !== 0 && cond !== "" && cond !== "FALSE";
-    return truthy ? args[1] : args[2] ?? false;
+  /**
+   * Excel's reading of an IF condition: an error propagates, a blank is
+   * FALSE, a number is TRUE unless it is 0, and text is TRUE or FALSE only
+   * when it spells one of them (in any case). Any other text, "" included,
+   * is #VALUE!.
+   */
+  toLogical(v) {
+    if (this.isError(v)) throw new LinterError(v);
+    if (typeof v === "boolean") return v;
+    if (v === null) return false;
+    if (typeof v === "number") return v !== 0;
+    if (typeof v === "string") {
+      const upper = v.toUpperCase();
+      if (upper === "TRUE") return true;
+      if (upper === "FALSE") return false;
+      throw new LinterError(ERR_VALUE);
+    }
+    return true;
   }
   // ---- Hints ----
-  hint(error2, formula2, sheet) {
+  hint(error2, key, formula2, sheet) {
     switch (error2) {
       case ERR_VALUE:
         return this.hintValue(formula2, sheet);
       case ERR_REF:
         return this.hintRef(formula2);
       case ERR_NAME:
-        return "The formula references an unknown function or has a syntax error. Holy Sheet supports: SUM, AVERAGE, COUNT, COUNTA, MIN, MAX, IF, ROUND, ABS, LEN, UPPER, LOWER, CONCAT.";
+        return this.hintName(key, formula2, sheet);
       case ERR_DIV0:
         return "Division by zero \u2014 the divisor evaluated to 0.";
       case ERR_CIRC:
@@ -1538,6 +1720,39 @@ var FormulaLinter = class {
         return "Formula evaluation failed.";
     }
   }
+  /**
+   * #NAME? has three causes in this formula, plus inheritance, and each hint
+   * says which one it is. A syntax error used to be told it "references an
+   * unknown function", and an agent went hunting for a function that was fine.
+   * The texts are byte-identical to PHP's and Python's: see PHP
+   * `FormulaLinter::hintName` for why a syntax error keeps the #NAME? label.
+   */
+  hintName(key, formula2, sheet) {
+    const cause = this.nameCauses.get(key);
+    switch (cause?.cause) {
+      case "syntax":
+        return `Syntax error: ${cause.detail}. Excel cannot parse this formula. Check for an unbalanced parenthesis or quote, a missing operator or argument, or a character a formula cannot contain. Text goes in double quotes, and a quote inside text is written twice: "a""b".`;
+      case "function":
+        return `Unknown function ${cause.detail}. Holy Sheet supports: SUM, AVERAGE, COUNT, COUNTA, MIN, MAX, IF, ROUND, ABS, LEN, UPPER, LOWER, CONCAT.`;
+      case "internal":
+        return `The linter itself failed on this formula (${cause.detail}). That is a holy-sheet defect, not evidence that the formula is wrong.`;
+      default:
+        return this.hintInheritedName(formula2, sheet);
+    }
+  }
+  hintInheritedName(formula2, sheet) {
+    const re = new RegExp(`(?:${SHEET_QUALIFIER})?\\$?([A-Z]+)\\$?(\\d+)`, "gi");
+    const sources = [];
+    for (const m of formula2.matchAll(re)) {
+      const sheetName2 = m[1] ? this.sheetNames.get(this.cleanSheetName(m[1]).toLowerCase()) ?? this.cleanSheetName(m[1]) : sheet;
+      const a1 = m[2].toUpperCase() + m[3];
+      if (this.cache.get(sheetName2 + "!" + a1) === ERR_NAME) {
+        const source = m[1] ? m[1] + "!" + a1 : a1;
+        if (!sources.includes(source)) sources.push(source);
+      }
+    }
+    return sources.length === 0 ? "This formula depends on a cell whose value is #NAME?. Fix that cell first." : `This formula depends on ${sources.join(", ")}, whose value is #NAME?. Fix that cell first.`;
+  }
   hintRef(formula2) {
     for (const m of formula2.matchAll(new RegExp(SHEET_QUALIFIER, "g"))) {
       const name = this.cleanSheetName(m[1]);
@@ -1575,9 +1790,30 @@ var FormulaLinter = class {
     return "A non-numeric value was used in arithmetic. Check that all referenced cells contain numbers.";
   }
 };
-function phpRound(x, n) {
-  const factor = 10 ** n;
-  return Math.sign(x) * Math.round(Math.abs(x) * factor) / factor;
+function blankLike(other) {
+  if (typeof other === "boolean") return false;
+  if (typeof other === "string") return "";
+  return 0;
+}
+function compareCodePoints(a, b) {
+  const x = Array.from(a);
+  const y = Array.from(b);
+  const n = Math.min(x.length, y.length);
+  for (let i = 0; i < n; i++) {
+    const p = x[i].codePointAt(0);
+    const q = y[i].codePointAt(0);
+    if (p !== q) return p < q ? -1 : 1;
+  }
+  return x.length < y.length ? -1 : x.length > y.length ? 1 : 0;
+}
+function excelRound(x, n) {
+  if (!Number.isFinite(x)) return x;
+  const [mantissa, exponent] = Math.abs(x).toExponential().split("e");
+  const shifted = Number(`${mantissa}e${Number(exponent) + n}`);
+  if (!Number.isFinite(shifted)) return x;
+  const rounded = Math.round(shifted);
+  const digits = String(rounded);
+  return Math.sign(x) * (digits.includes("e") ? rounded / 10 ** n : Number(`${digits}e${-n}`));
 }
 
 // src/schema/repairer.ts
@@ -6692,7 +6928,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.11.1";
+var VERSION = "2.11.2";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }