@particle-academy/holy-sheet 2.11.0 → 2.11.2

package/dist/index.d.cts

@@ -266,7 +266,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.11.0";
+declare const VERSION = "2.11.2";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -360,7 +360,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.11.0";
+    static readonly VERSION = "2.11.2";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -649,6 +649,14 @@ declare class Normalizer {
     private normalizeColumnWidths;
     private columnFormat;
     private buildCell;
+    /**
+     * `explicit`: the value came from an object cell's `value` key. An explicit
+     * string is the caller saying "this text, exactly", so it is never coerced
+     * to a number: `{value: "+1"}` stays "+1" and `{value: "007"}` stays "007".
+     * Only a date/datetime display format still turns a string into a serial,
+     * because that conversion is what the format asks for. Bare values keep
+     * numeric-string coercion. Mirrors PHP `Normalizer::coerceValue`.
+     */
     private coerceValue;
 }
 
@@ -665,10 +673,24 @@ declare class FormulaLinter {
      * `#REF!` rather than a range of blanks.
      */
     private sheetNames;
+    /**
+     * 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.
+     */
+    private nameCauses;
+    /**
+     * 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.
+     */
+    private skipping;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
     private evaluate;
+    private describeToken;
     private tokenize;
     private peek;
     private isOp;
@@ -676,8 +698,32 @@ declare class FormulaLinter {
     private parseConcat;
     private parseArith;
     private parseTerm;
+    /**
+     * `^` 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'.
+     */
+    private parsePower;
     private parseUnary;
+    /**
+     * 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.
+     */
+    private parsePercent;
     private parsePrimary;
+    /**
+     * 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.
+     */
+    private parseIf;
     private resolveRefOrRange;
     private cleanRef;
     /**
@@ -691,6 +737,12 @@ declare class FormulaLinter {
     private coerceNumber;
     private coerceString;
     private compare;
+    /**
+     * 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.
+     */
     private cmpVal;
     private callFunction;
     private flatten;
@@ -698,8 +750,23 @@ declare class FormulaLinter {
     private maybeNum;
     private avg;
     private minMax;
-    private ifFn;
+    /**
+     * 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!.
+     */
+    private toLogical;
     private hint;
+    /**
+     * #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.
+     */
+    private hintName;
+    private hintInheritedName;
     private hintRef;
     private hintValue;
 }

package/dist/index.d.ts

@@ -266,7 +266,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.11.0";
+declare const VERSION = "2.11.2";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -360,7 +360,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.11.0";
+    static readonly VERSION = "2.11.2";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -649,6 +649,14 @@ declare class Normalizer {
     private normalizeColumnWidths;
     private columnFormat;
     private buildCell;
+    /**
+     * `explicit`: the value came from an object cell's `value` key. An explicit
+     * string is the caller saying "this text, exactly", so it is never coerced
+     * to a number: `{value: "+1"}` stays "+1" and `{value: "007"}` stays "007".
+     * Only a date/datetime display format still turns a string into a serial,
+     * because that conversion is what the format asks for. Bare values keep
+     * numeric-string coercion. Mirrors PHP `Normalizer::coerceValue`.
+     */
     private coerceValue;
 }
 
@@ -665,10 +673,24 @@ declare class FormulaLinter {
      * `#REF!` rather than a range of blanks.
      */
     private sheetNames;
+    /**
+     * 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.
+     */
+    private nameCauses;
+    /**
+     * 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.
+     */
+    private skipping;
     lint(schema: unknown): FormulaProblem[];
     private buildIndex;
     private isError;
     private evaluate;
+    private describeToken;
     private tokenize;
     private peek;
     private isOp;
@@ -676,8 +698,32 @@ declare class FormulaLinter {
     private parseConcat;
     private parseArith;
     private parseTerm;
+    /**
+     * `^` 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'.
+     */
+    private parsePower;
     private parseUnary;
+    /**
+     * 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.
+     */
+    private parsePercent;
     private parsePrimary;
+    /**
+     * 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.
+     */
+    private parseIf;
     private resolveRefOrRange;
     private cleanRef;
     /**
@@ -691,6 +737,12 @@ declare class FormulaLinter {
     private coerceNumber;
     private coerceString;
     private compare;
+    /**
+     * 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.
+     */
     private cmpVal;
     private callFunction;
     private flatten;
@@ -698,8 +750,23 @@ declare class FormulaLinter {
     private maybeNum;
     private avg;
     private minMax;
-    private ifFn;
+    /**
+     * 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!.
+     */
+    private toLogical;
     private hint;
+    /**
+     * #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.
+     */
+    private hintName;
+    private hintInheritedName;
     private hintRef;
     private hintValue;
 }

package/dist/index.js

@@ -1,5 +1,5 @@
-import { Agent, VERSION } from './chunk-OL6E7DE5.js';
-export { Agent, ArchiveRefused, ArrayBuilder, CellAddress, CsvBuilder, FormatSniffer, FormulaLinter, Inference, Normalizer, OdsReader, OfficeTemplateRefused, Repairer, SchemaException, SheetDiff, SheetOpSchema, SheetReducer, Theme, UnsupportedFormatException, VERSION, Validator, XlsxReader, XlsxWriter, unzipSync, zipSync } from './chunk-OL6E7DE5.js';
+import { Agent, VERSION } from './chunk-Y32UXRQ6.js';
+export { Agent, ArchiveRefused, ArrayBuilder, CellAddress, CsvBuilder, FormatSniffer, FormulaLinter, Inference, Normalizer, OdsReader, OfficeTemplateRefused, Repairer, SchemaException, SheetDiff, SheetOpSchema, SheetReducer, Theme, UnsupportedFormatException, VERSION, Validator, XlsxReader, XlsxWriter, unzipSync, zipSync } from './chunk-Y32UXRQ6.js';
 
 // src/holy-sheet.ts
 var HolySheet = class {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@particle-academy/holy-sheet",
-    "version": "2.11.0",
+    "version": "2.11.2",
     "description": "Zero-dependency, isomorphic xlsx writer + reader + formula linter for agentic document creation. The Node/TypeScript mirror of the PHP particle-academy/holy-sheet (feature-parity with PHP 1.2.0).",
     "repository": {
         "type": "git",