@gui-chat-plugin/spreadsheet 4.2.0 → 4.2.1

package/README.md

@@ -123,6 +123,8 @@ Dates are serial numbers on the real calendar, as in LibreOffice and Google Shee
 ### Lookup & Reference
 `HLOOKUP`, `INDEX`, `MATCH`, `VLOOKUP`, `XLOOKUP`
 
+A range is written `A1:C10`, `Data!A1:C10` or `'My Sheet'!A1:C10`. A whole column (`A:A`, `B:D`) or a whole row (`1:1`) covers its sheet as far as the data reaches, which gives the same answers, since everything past the data is blank.
+
 ### Statistical
 `AVERAGE`, `AVERAGEIF`, `AVERAGEIFS`, `CONFIDENCE.NORM`, `CONFIDENCE.T`, `CORREL`, `COUNT`, `COUNTA`, `COUNTIF`, `COUNTIFS`, `COVARIANCE.P`, `COVARIANCE.S`, `FORECAST`, `FORECAST.LINEAR`, `GEOMEAN`, `HARMEAN`, `INTERCEPT`, `KURT`, `LARGE`, `MAX`, `MAXIFS`, `MEDIAN`, `MIN`, `MINIFS`, `MODE`, `NORM.DIST`, `NORM.INV`, `NORM.S.DIST`, `NORM.S.INV`, `PEARSON`, `PERCENTILE`, `PERCENTILE.INC`, `PERCENTRANK`, `PERCENTRANK.INC`, `QUARTILE`, `QUARTILE.INC`, `RANK`, `RANK.EQ`, `RSQ`, `SKEW`, `SLOPE`, `SMALL`, `STANDARDIZE`, `STDEV`, `STDEV.P`, `STDEV.S`, `STDEVP`, `STEYX`, `SUM`, `SUMIF`, `SUMIFS`, `T.DIST`, `T.DIST.2T`, `T.DIST.RT`, `T.INV`, `T.INV.2T`, `T.TEST`, `TREND`, `TTEST`, `VAR`, `VAR.P`, `VAR.S`, `VARP`
 
@@ -148,9 +150,11 @@ A workbook can define functions of its own, for an analysis no built-in function
 ```
 
 - A function body is JavaScript, run in [QuickJS](https://github.com/justjake/quickjs-emscripten) (WebAssembly) with no DOM, network, file system or timers, at most 50 ms per call, 2 s per calculation and 16 MB of memory. Each function has a global scope of its own.
-- A range argument arrives as rows of cells (an array of arrays, a blank cell as `null`); a single cell and any other argument as its value. A whole column or row (`A:A`, `2:2`) is `#VALUE!`: the engine does not read those. An argument that is an error is passed on without calling the function.
+- A range argument arrives as rows of cells (an array of arrays, a blank cell as `null`); a single cell and any other argument as its value. A whole column or row (`A:A`, `2:2`) arrives as the range it covers in its sheet's data. An argument that is an error is passed on without calling the function.
 - Return a number, text or `true`/`false`. A time-out or a non-finite number shows `#NUM!`; a thrown error or any other return value shows `#VALUE!`.
 - A name is letters and digits, parts joined by dots, and cannot be a built-in function's. `presentSpreadsheet` says in its reply which definitions could not be used.
+- `presentSpreadsheet`'s reply also lists formula cells that calculate to an error (a few, and how many in all), so an agent can fix a workbook before handing it over: the saved file holds formulas, not results.
+- Each workbook's functions get a QuickJS instance of their own, so a failure in one (an abort while freeing a runtime that ran out of time) cannot affect another.
 - QuickJS loads only for a workbook that defines functions. The View and `readCalculatedRange` load it themselves; a host calling `calculatedRange` directly passes the set from `loadCustomFunctions`.
 
 ## Development

package/dist/core/calculationErrors.d.ts

@@ -0,0 +1,17 @@
+import { type CustomFunctionSet } from "../engine/customFunctions";
+import type { SpreadsheetSheet } from "./types";
+/** How many erroring cells a reply names; the rest are counted. */
+export declare const ERROR_SAMPLES = 5;
+/** A formula is quoted up to this many characters, so the reply stays short whatever was written. */
+export declare const FORMULA_QUOTE_LIMIT = 80;
+export interface CalculationErrors {
+    count: number;
+    /** `Summary!B4 = #N/A (=FORECAST.LINEAR(B3,Data!H2:H37,Data!D2:D37))` */
+    samples: string[];
+}
+/** Every formula cell whose calculated value is an error, with `functions` visible. Read from the
+ *  calculation before display formatting, where an error is an error VALUE: a formula that returns
+ *  the text "#N/A" is not one. */
+export declare function calculationErrors(sheets: SpreadsheetSheet[], functions?: CustomFunctionSet): CalculationErrors;
+/** The sentence a reply carries about them, or "" when there are none. */
+export declare function calculationErrorsNote({ count, samples }: CalculationErrors): string;

package/dist/{core-CwIoDrlM.js → core-CTRlKL9k.js}

@@ -1,4 +1,4 @@
-import { C as e, a as t, b as n, c as r, f as i, i as a, l as o, p as s, u as c, v as l, y as u } from "./samples-DBNVoegC.js";
+import { C as e, b as t, c as n, f as r, l as i, o as a, p as o, s, u as c, v as l, y as u } from "./samples-C5JjpxYJ.js";
 //#region src/core/rangeValues.ts
 var d = 1e5, f = (e) => {
 	if (!e) return null;
@@ -6,13 +6,13 @@ var d = 1e5, f = (e) => {
 	return t.startsWith("'") && t.endsWith("'") ? t.slice(1, -1).replaceAll("''", "'") : t;
 };
 function p(e) {
-	let t = e.lastIndexOf("!"), n = e.slice(t + 1), r = i(n.includes(":") ? e : `${e}:${n}`);
-	return !r || !s(n.split(":")[0] ?? "") ? null : {
-		sheetName: f(r.sheetPrefix),
-		startRow: Math.min(r.startRow, r.endRow) - 1,
-		endRow: Math.max(r.startRow, r.endRow) - 1,
-		startCol: Math.min(r.startCol, r.endCol),
-		endCol: Math.max(r.startCol, r.endCol)
+	let t = e.lastIndexOf("!"), n = e.slice(t + 1), i = r(n.includes(":") ? e : `${e}:${n}`);
+	return !i || !o((n.split(":")[0] ?? "").toUpperCase()) ? null : {
+		sheetName: f(i.sheetPrefix),
+		startRow: Math.min(i.startRow, i.endRow) - 1,
+		endRow: Math.max(i.startRow, i.endRow) - 1,
+		startCol: Math.min(i.startCol, i.endCol),
+		endCol: Math.max(i.startCol, i.endCol)
 	};
 }
 var m = /[ymdhs]/i, h = (t) => e(t) && typeof t.f == "string" && t.f !== "" && !m.test(t.f);
@@ -21,26 +21,26 @@ function g(e, t, n) {
 }
 var _ = (e) => ({
 	name: e.name,
-	data: t(e.data)
+	data: s(e.data)
 }), v = ({ startRow: e, endRow: t }) => Array.from({ length: t - e + 1 }, (t, n) => e + n), y = ({ startCol: e, endCol: t }) => Array.from({ length: t - e + 1 }, (t, n) => e + n);
-function b(e, t, n = r) {
-	let i = p(t.trim());
-	if (!i) throw Error(`"${t}" is not a range such as Data!A1:C13`);
-	let s = (i.endRow - i.startRow + 1) * (i.endCol - i.startCol + 1);
+function b(e, t, r = n) {
+	let o = p(t.trim());
+	if (!o) throw Error(`"${t}" is not a range such as Data!A1:C13`);
+	let s = (o.endRow - o.startRow + 1) * (o.endCol - o.startCol + 1);
 	if (s > 1e5) throw Error(`"${t}" has ${s} cells; the limit is ${d}`);
-	let c = i.sheetName === null ? 0 : e.findIndex((e) => e.name === i.sheetName), l = e[c];
-	if (c < 0 || !l) throw Error(`the spreadsheet has no sheet named "${i.sheetName ?? ""}"`);
-	let u = e.map(_), f = u[c] ?? _(l), { calculated: m, displayed: h } = o(n, () => ({
+	let c = o.sheetName === null ? 0 : e.findIndex((e) => e.name === o.sheetName), l = e[c];
+	if (c < 0 || !l) throw Error(`the spreadsheet has no sheet named "${o.sheetName ?? ""}"`);
+	let u = e.map(_), f = u[c] ?? _(l), { calculated: m, displayed: h } = i(r, () => ({
 		calculated: a(f, u, { skipFormatting: !0 }).data,
 		displayed: a(f, u).data
 	}));
-	return v(i).map((e) => y(i).map((t) => g(f.data[e]?.[t], x(m[e]?.[t]), x(h[e]?.[t]))));
+	return v(o).map((e) => y(o).map((t) => g(f.data[e]?.[t], x(m[e]?.[t]), x(h[e]?.[t]))));
 }
 var x = (e) => typeof e == "string" || typeof e == "number" || typeof e == "boolean" ? e : void 0;
-async function S(e, t, r) {
-	if (!u(t)) throw Error("path must be a .json file under artifacts/spreadsheets/");
-	let i = l(JSON.parse(await e.read(n(t))));
-	if (!i) throw Error(`${t} does not hold an array of sheets`);
+async function S(e, n, r) {
+	if (!u(n)) throw Error("path must be a .json file under artifacts/spreadsheets/");
+	let i = l(JSON.parse(await e.read(t(n))));
+	if (!i) throw Error(`${n} does not hold an array of sheets`);
 	let a = await c(i);
 	try {
 		return b(i, r, a);

package/dist/core-Cf9Pxo_q.cjs

@@ -0,0 +1 @@
+const e=require("./samples-UnTPgkyq.cjs");var t=1e5,n=e=>{if(!e)return null;let t=e.slice(0,-1);return t.startsWith(`'`)&&t.endsWith(`'`)?t.slice(1,-1).replaceAll(`''`,`'`):t};function r(t){let r=t.lastIndexOf(`!`),i=t.slice(r+1),a=e.f(i.includes(`:`)?t:`${t}:${i}`);return!a||!e.p((i.split(`:`)[0]??``).toUpperCase())?null:{sheetName:n(a.sheetPrefix),startRow:Math.min(a.startRow,a.endRow)-1,endRow:Math.max(a.startRow,a.endRow)-1,startCol:Math.min(a.startCol,a.endCol),endCol:Math.max(a.startCol,a.endCol)}}var i=/[ymdhs]/i,a=t=>e.C(t)&&typeof t.f==`string`&&t.f!==``&&!i.test(t.f);function o(e,t,n){return n===void 0||n===``?null:typeof n==`number`?n:typeof t==`number`&&a(e)?t:typeof n==`boolean`?String(n).toUpperCase():n}var s=t=>({name:t.name,data:e.s(t.data)}),c=({startRow:e,endRow:t})=>Array.from({length:t-e+1},(t,n)=>e+n),l=({startCol:e,endCol:t})=>Array.from({length:t-e+1},(t,n)=>e+n);function u(n,i,a=e.c){let u=r(i.trim());if(!u)throw Error(`"${i}" is not a range such as Data!A1:C13`);let f=(u.endRow-u.startRow+1)*(u.endCol-u.startCol+1);if(f>1e5)throw Error(`"${i}" has ${f} cells; the limit is ${t}`);let p=u.sheetName===null?0:n.findIndex(e=>e.name===u.sheetName),m=n[p];if(p<0||!m)throw Error(`the spreadsheet has no sheet named "${u.sheetName??``}"`);let h=n.map(s),g=h[p]??s(m),{calculated:_,displayed:v}=e.l(a,()=>({calculated:e.o(g,h,{skipFormatting:!0}).data,displayed:e.o(g,h).data}));return c(u).map(e=>l(u).map(t=>o(g.data[e]?.[t],d(_[e]?.[t]),d(v[e]?.[t]))))}var d=e=>typeof e==`string`||typeof e==`number`||typeof e==`boolean`?e:void 0;async function f(t,n,r){if(!e.y(n))throw Error(`path must be a .json file under artifacts/spreadsheets/`);let i=e.v(JSON.parse(await t.read(e.b(n))));if(!i)throw Error(`${n} does not hold an array of sheets`);let a=await e.u(i);try{return u(i,r,a)}finally{a.dispose()}}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/dist/core.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-DyQFcwBX.cjs"),t=require("./core-DHWKHgsJ.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.w,exports.TOOL_DEFINITION=e.T,exports.TOOL_NAME=e.E,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.o,exports.executeSpreadsheetDispatch=e.g,exports.isSpreadsheetArtifactPath=e.y,exports.isSpreadsheetDispatchArgs=e._,exports.pluginCore=e.s,exports.readCalculatedRange=t.r,exports.samples=e.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-UnTPgkyq.cjs"),t=require("./core-Cf9Pxo_q.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.w,exports.TOOL_DEFINITION=e.T,exports.TOOL_NAME=e.E,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.n,exports.executeSpreadsheetDispatch=e.g,exports.isSpreadsheetArtifactPath=e.y,exports.isSpreadsheetDispatchArgs=e._,exports.pluginCore=e.r,exports.readCalculatedRange=t.r,exports.samples=e.t;

package/dist/core.js

@@ -1,3 +1,3 @@
-import { E as e, T as t, _ as n, g as r, o as i, s as a, t as o, w as s, y as c } from "./samples-DBNVoegC.js";
-import { n as l, r as u, t as d } from "./core-CwIoDrlM.js";
+import { E as e, T as t, _ as n, g as r, n as i, r as a, t as o, w as s, y as c } from "./samples-C5JjpxYJ.js";
+import { n as l, r as u, t as d } from "./core-CTRlKL9k.js";
 export { d as MAX_RANGE_CELLS, s as SYSTEM_PROMPT, t as TOOL_DEFINITION, e as TOOL_NAME, l as calculatedRange, i as executeSpreadsheet, r as executeSpreadsheetDispatch, c as isSpreadsheetArtifactPath, n as isSpreadsheetDispatchArgs, a as pluginCore, u as readCalculatedRange, o as samples };

package/dist/engine/blankOperands.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A blank cell standing alone as one side of a comparison: Excel compares it as whatever the
+ * other side is — 0 beside a number, FALSE beside a logical value, "" beside text — where the
+ * substitution has already read it as 0.
+ */
+import type { CellValue } from "./types";
+/** What a blank compares as beside `other`. */
+export declare const blankBeside: (other: CellValue) => CellValue;
+/**
+ * The comparison's values with each blank side read as `blankBeside` its left neighbour (the
+ * right one for the first side). In a chain the left neighbour of a later side is the result so
+ * far, a logical value; a neighbour that is blank too compares as it was read.
+ */
+export declare function withBlankSides(values: readonly CellValue[], isBlankSide: readonly boolean[]): CellValue[];

package/dist/engine/calculator.d.ts

@@ -8,6 +8,13 @@ export declare function normalizeData(data: any): SpreadsheetCell[][];
 type SheetCalculateOptions = CalculateOptions & {
     skipFormatting?: boolean;
 };
+/**
+ * Calculate formulas in a single sheet
+ *
+ * @param sheet - Sheet data to calculate
+ * @param allSheets - All sheets for cross-sheet references
+ * @returns Calculated sheet with formulas evaluated
+ */
 export declare function calculateSheet(sheet: SheetData, allSheets?: SheetData[], options?: SheetCalculateOptions): CalculatedSheet;
 /**
  * Calculate all sheets in a workbook

package/dist/engine/evaluator.d.ts

@@ -64,6 +64,8 @@ export declare function substituteCellRefs(expr: string, cellRefs: CellRefSpan[]
  * @returns Array of argument strings
  */
 export declare function parseFunctionArgs(argsStr: string): string[];
+/** The reference an operand is, perhaps in brackets, or null when it is anything more. */
+export declare function loneReference(operand: string): string | null;
 /**
  * Evaluate a formula string
  *
@@ -81,4 +83,4 @@ export declare function parseFunctionArgs(argsStr: string): string[];
  * @param context - Evaluation context with cell/range accessors
  * @returns Evaluated result (number or string)
  */
-export declare function evaluateFormula(formula: string, context: EvaluatorContext): CellValue;
+export declare function evaluateFormula(writtenFormula: string, context: EvaluatorContext): CellValue;

package/dist/engine/functions/statistical.d.ts

@@ -1,7 +1,8 @@
 /**
  * Statistical Functions
  */
-import { type FunctionContext, type RangeGetter } from "../registry";
+import { type FunctionContext, type FunctionHandler, type RangeGetter } from "../registry";
+import { type SpreadsheetError } from "../spreadsheet-errors";
 import type { CellValue } from "../types";
 /** One value an argument contributed, tagged by where it came from. A range cell
  *  was already filtered by the range getter; a scalar is whatever the argument
@@ -11,5 +12,14 @@ interface ArgumentValue {
     isScalar: boolean;
 }
 export declare const collectArgumentValues: (args: string[], context: FunctionContext, readRange: RangeGetter) => ArgumentValue[];
+/** The numbers an aggregate reads from its arguments, or the first error among them in argument
+ *  order — an error cell in a range, or an argument that evaluated to one — read in one pass, so
+ *  no argument is read or evaluated twice. A range keeps only the cells that hold a number, as the
+ *  numeric read does. */
+export declare const collectNumbersOrError: (args: string[], context: FunctionContext) => number[] | SpreadsheetError;
+/** The cells of a range read blank-aware that hold a number, as numbers — what the numeric read keeps. */
+export declare const rangeNumbers: (values: CellValue[]) => number[];
+/** The handler's rule over the numbers of its arguments, or the first error among them. */
+export declare const overNumbers: (rule: (values: number[]) => CellValue) => FunctionHandler;
 export declare const collectNumericValues: (args: string[], context: FunctionContext) => number[];
 export {};

package/dist/engine/logicalLiterals.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The logical literals `TRUE` and `FALSE` written in a formula, in any case, as the boolean values
+ * a logical cell already renders as (`true` / `false`), so a written TRUE and a cell holding TRUE
+ * read alike. A function call (`TRUE()`), a sheet name (`TRUE!A1`) and text in quotes are left.
+ */
+export declare function logicalLiteralsAsBooleans(formula: string): string;
+/** The boolean an expression is when it is nothing but one, or null. */
+export declare function loneBoolean(expr: string): boolean | null;
+/** An expression with its booleans as the numbers arithmetic reads them (TRUE is 1), when it holds
+ *  no text that could contain the words. */
+export declare function booleansAsNumbers(expr: string): string;

package/dist/engine/registry.d.ts

@@ -21,6 +21,8 @@ export interface FunctionContext {
     /** How many cells of a range hold something, a formula's "" included (COUNTA). */
     countFilledCells?: ((range: string) => number) | undefined;
     evaluateFormula: (formula: string) => CellValue;
+    /** Whether an argument is nothing but a reference to a blank cell, which evaluating reads as 0. */
+    isBlankReference?: ((arg: string) => boolean) | undefined;
     /** Read an ambiguous `01/02/2020` as day-first, as the sheet's own dates are. */
     preferDDMMYYYY?: boolean | undefined;
 }
@@ -92,9 +94,7 @@ export declare const isCallableName: (name: string) => boolean;
  * in numericCoercion.parseNumericString, shared with the strict scalar read.
  */
 export declare function toNumber(value: CellValue): number;
-/**
- * Helper function to convert a value to a string
- */
+/** A value as text, as Excel writes it: a logical value is TRUE or FALSE. */
 export declare function toString(value: CellValue): string;
 /**
  * Helper to parse criteria for conditional functions like COUNTIF, SUMIF

package/dist/engine/sheetReference.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reading the sheet out of a sheet-qualified reference: `Data!A1`, `'My Sheet'!A1:B2`, and a
+ * quoted name holding an apostrophe written twice, as Excel writes it (`'It''s'!A1` names It's).
+ */
+/** A reference split from the sheet it names. */
+export interface SheetQualifiedReference {
+    sheetName: string;
+    ref: string;
+}
+/** The sheet a reference names and the reference within it, or null when it names no sheet. */
+export declare function splitSheetReference(fullRef: string): SheetQualifiedReference | null;
+/** The index just past the closing quote of the sheet name that opens at `start` (a `'`), a
+ *  doubled `''` inside it read as part of the name; -1 when the name never closes. */
+export declare function endOfQuotedSheetName(text: string, start: number): number;

package/dist/engine/wholeReferences.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whole-column (`A:A`, `B:D`) and whole-row (`1:1`, `2:5`) references, rewritten as the bounded
+ * range they cover in their sheet: `A:A` becomes `A1:A<last row>`, `1:1` becomes
+ * `A1:<last column>1`. Everything past a sheet's data is blank, so the answers are Excel's, and
+ * every reader downstream (ranges, lookups, argument checks) sees an ordinary `A1:B2` range.
+ */
+/** How far a sheet's data reaches: the number of rows, and the longest row's length. */
+export interface SheetExtent {
+    rows: number;
+    columns: number;
+}
+/** The extent of the sheet a reference names (`null` for the formula's own sheet), or null when there is no such sheet. */
+export type ExtentOf = (sheetName: string | null) => SheetExtent | null;
+/**
+ * The formula with every whole-column and whole-row reference bounded to its sheet's data. Text
+ * inside a string literal (`"A:A"`) is left as written. A reference to a sheet that does not
+ * exist is left as written too, so it fails as any reference to that sheet does.
+ */
+export declare function boundWholeReferences(formula: string, extentOf: ExtentOf): string;

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-DyQFcwBX.cjs"),t=require("./core-DHWKHgsJ.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.w,exports.TOOL_DEFINITION=e.T,exports.TOOL_NAME=e.E,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.o,exports.executeSpreadsheetDispatch=e.g,exports.isSpreadsheetArtifactPath=e.y,exports.isSpreadsheetDispatchArgs=e._,exports.pluginCore=e.s,exports.readCalculatedRange=t.r,exports.samples=e.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-UnTPgkyq.cjs"),t=require("./core-Cf9Pxo_q.cjs");exports.MAX_RANGE_CELLS=t.t,exports.SYSTEM_PROMPT=e.w,exports.TOOL_DEFINITION=e.T,exports.TOOL_NAME=e.E,exports.calculatedRange=t.n,exports.executeSpreadsheet=e.n,exports.executeSpreadsheetDispatch=e.g,exports.isSpreadsheetArtifactPath=e.y,exports.isSpreadsheetDispatchArgs=e._,exports.pluginCore=e.r,exports.readCalculatedRange=t.r,exports.samples=e.t;

package/dist/index.js

@@ -1,3 +1,3 @@
-import { E as e, T as t, _ as n, g as r, o as i, s as a, t as o, w as s, y as c } from "./samples-DBNVoegC.js";
-import { n as l, r as u, t as d } from "./core-CwIoDrlM.js";
+import { E as e, T as t, _ as n, g as r, n as i, r as a, t as o, w as s, y as c } from "./samples-C5JjpxYJ.js";
+import { n as l, r as u, t as d } from "./core-CTRlKL9k.js";
 export { d as MAX_RANGE_CELLS, s as SYSTEM_PROMPT, t as TOOL_DEFINITION, e as TOOL_NAME, l as calculatedRange, i as executeSpreadsheet, r as executeSpreadsheetDispatch, c as isSpreadsheetArtifactPath, n as isSpreadsheetDispatchArgs, a as pluginCore, u as readCalculatedRange, o as samples };