@particle-academy/holy-sheet 2.3.0 → 2.3.1

package/dist/index.d.cts

@@ -103,7 +103,7 @@ interface BuilderOptions {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.3.0";
+declare const VERSION = "2.3.1";
 type Any$5 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -144,7 +144,7 @@ type Any$4 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.3.0";
+    static readonly VERSION = "2.3.1";
     validate(schema: Any$4): ValidationError[];
     toBytes(schema: Any$4): Uint8Array;
     write(schema: Any$4, path: string): Promise<WriteResult>;
@@ -322,6 +322,12 @@ declare class Normalizer {
 declare class FormulaLinter {
     private index;
     private cache;
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    private sheetNames;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
@@ -337,6 +343,10 @@ declare class FormulaLinter {
     private parsePrimary;
     private resolveRefOrRange;
     private cleanRef;
+    /**
+     * Unwrap the single quotes Excel puts around a sheet name that needs them,
+     * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+     */
     private cleanSheetName;
     private resolveCell;
     private resolveRange;
@@ -353,6 +363,7 @@ declare class FormulaLinter {
     private minMax;
     private ifFn;
     private hint;
+    private hintRef;
     private hintValue;
 }
 

package/dist/index.d.ts

@@ -103,7 +103,7 @@ interface BuilderOptions {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.3.0";
+declare const VERSION = "2.3.1";
 type Any$5 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -144,7 +144,7 @@ type Any$4 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.3.0";
+    static readonly VERSION = "2.3.1";
     validate(schema: Any$4): ValidationError[];
     toBytes(schema: Any$4): Uint8Array;
     write(schema: Any$4, path: string): Promise<WriteResult>;
@@ -322,6 +322,12 @@ declare class Normalizer {
 declare class FormulaLinter {
     private index;
     private cache;
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    private sheetNames;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
@@ -337,6 +343,10 @@ declare class FormulaLinter {
     private parsePrimary;
     private resolveRefOrRange;
     private cleanRef;
+    /**
+     * Unwrap the single quotes Excel puts around a sheet name that needs them,
+     * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+     */
     private cleanSheetName;
     private resolveCell;
     private resolveRange;
@@ -353,6 +363,7 @@ declare class FormulaLinter {
     private minMax;
     private ifFn;
     private hint;
+    private hintRef;
     private hintValue;
 }
 

package/dist/index.js

@@ -719,6 +719,7 @@ var ERR_REF = "#REF!";
 var ERR_NAME = "#NAME?";
 var ERR_DIV0 = "#DIV/0!";
 var ERR_CIRC = "#CIRC!";
+var SHEET_QUALIFIER = "('(?:[^']|'')+'|[A-Za-z_][A-Za-z0-9_.]*)!";
 var LinterError = class extends Error {
   constructor(errorCode) {
     super(errorCode);
@@ -729,9 +730,16 @@ var FormulaLinter = class {
   constructor() {
     this.index = /* @__PURE__ */ new Map();
     this.cache = /* @__PURE__ */ new Map();
+    /**
+     * Every sheet name, keyed by its lower-cased form. Excel matches sheet names
+     * without regard to case, and a reference to a sheet that is not here is
+     * `#REF!` rather than a range of blanks.
+     */
+    this.sheetNames = /* @__PURE__ */ new Map();
   }
   lint(schema) {
     const workbook = new Normalizer().normalize(schema);
+    this.sheetNames = new Map(workbook.sheets.map((sheet) => [sheet.name.toLowerCase(), sheet.name]));
     this.index = this.buildIndex(workbook);
     this.cache = /* @__PURE__ */ new Map();
     const issues = [];
@@ -807,6 +815,24 @@ var FormulaLinter = class {
         tokens.push({ type: "STRING", value });
         continue;
       }
+      if (ch === "'") {
+        const start = i;
+        i++;
+        for (; ; ) {
+          if (i >= len) throw new LinterError(ERR_NAME);
+          if (src[i] === "'") {
+            if (i + 1 < len && src[i + 1] === "'") {
+              i += 2;
+              continue;
+            }
+            i++;
+            break;
+          }
+          i++;
+        }
+        tokens.push({ type: "SHEET", value: src.slice(start, i) });
+        continue;
+      }
       if (isAlpha(ch) || ch === "_" || ch === "$") {
         const start = i;
         while (i < len && (isAlnum(src[i]) || src[i] === "_" || src[i] === "$" || src[i] === ".")) i++;
@@ -924,16 +950,18 @@ var FormulaLinter = class {
       c.pos++;
       return tok.value;
     }
-    if (tok.type === "IDENT") {
+    if (tok.type === "SHEET" || tok.type === "IDENT") {
       const next = c.tokens[c.pos + 1];
       const next2 = c.tokens[c.pos + 2];
       if (next && next.type === "OP" && next.value === "!" && next2 && next2.type === "IDENT") {
-        const sheetName = this.cleanSheetName(tok.value);
+        const sheetName = this.sheetNames.get(this.cleanSheetName(tok.value).toLowerCase());
+        if (sheetName === void 0) throw new LinterError(ERR_REF);
         c.pos += 2;
         const startTok = c.tokens[c.pos].value;
         c.pos++;
         return this.resolveRefOrRange(startTok, sheetName, c, stack);
       }
+      if (tok.type === "SHEET") throw new LinterError(ERR_NAME);
       if (next && next.type === "OP" && next.value === "(") {
         const name = tok.value.toUpperCase();
         c.pos += 2;
@@ -978,9 +1006,13 @@ var FormulaLinter = class {
     const r = ref.replace(/\$/g, "").toUpperCase();
     return /^[A-Z]+\d+$/.test(r) ? r : null;
   }
+  /**
+   * Unwrap the single quotes Excel puts around a sheet name that needs them,
+   * and turn its doubled quote back into one: 'Q3 ''Final''' is Q3 'Final'.
+   */
   cleanSheetName(name) {
     if (name.length >= 2 && name[0] === "'" && name[name.length - 1] === "'") {
-      return name.slice(1, -1);
+      return name.slice(1, -1).split("''").join("'");
     }
     return name;
   }
@@ -1148,7 +1180,7 @@ var FormulaLinter = class {
       case ERR_VALUE:
         return this.hintValue(formula, sheet);
       case ERR_REF:
-        return "A cell reference points to a cell that doesn't exist in the workbook. Check column letters and row numbers.";
+        return this.hintRef(formula);
       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.";
       case ERR_DIV0:
@@ -1159,11 +1191,20 @@ var FormulaLinter = class {
         return "Formula evaluation failed.";
     }
   }
+  hintRef(formula) {
+    for (const m of formula.matchAll(new RegExp(SHEET_QUALIFIER, "g"))) {
+      const name = this.cleanSheetName(m[1]);
+      if (!this.sheetNames.has(name.toLowerCase())) {
+        return `The formula refers to a sheet named '${name}', and this workbook has no such sheet. Its sheets are: ${[...this.sheetNames.values()].join(", ")}. Quote a name that contains spaces or punctuation: 'My Sheet'!A1.`;
+      }
+    }
+    return "A cell reference points to a cell that doesn't exist in the workbook. Check column letters and row numbers.";
+  }
   hintValue(formula, sheet) {
-    const re = /(?:([A-Za-z][A-Za-z0-9_]*)!)?\$?([A-Z]+)\$?(\d+)/gi;
+    const re = new RegExp(`(?:${SHEET_QUALIFIER})?\\$?([A-Z]+)\\$?(\\d+)`, "gi");
     const offenders = [];
     for (const m of formula.matchAll(re)) {
-      const sheetName = m[1] ? m[1] : sheet;
+      const sheetName = m[1] ? this.sheetNames.get(this.cleanSheetName(m[1]).toLowerCase()) ?? this.cleanSheetName(m[1]) : sheet;
       const a1 = m[2].toUpperCase() + m[3];
       const key = sheetName + "!" + a1;
       const cell = this.index.get(key);
@@ -4113,7 +4154,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.3.0";
+var VERSION = "2.3.1";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }