@particle-academy/holy-sheet 2.3.1 → 2.4.0

package/dist/index.d.ts

@@ -102,9 +102,129 @@ interface BuilderOptions {
     enclosure?: string;
 }
 
+/**
+ * One op from `Agent.diff`, applied by `Agent.reduce`. Mirrors the PHP
+ * `HolySheet\Ops\SheetOpSchema` variants: same `type`, same field names.
+ *
+ * `set_cell`, `set_range` and `set_workbook` are fancy-sheets' `SheetOp` shapes;
+ * `set_workbook.data` here is a Holy Sheet schema, not fancy-sheets'
+ * `WorkbookData`.
+ */
+type SheetOp = SetCellOp | SetRangeOp | SetWorkbookOp | ClearCellOp | InsertRowsOp | DeleteRowsOp | InsertColumnsOp | DeleteColumnsOp | AddSheetOp | RemoveSheetOp | RenameSheetOp | MoveSheetOp | ReplaceSheetOp | SetMergedRegionsOp | SetColumnWidthsOp | SetFrozenOp | SetMetaOp;
+type SheetOpType = SheetOp["type"];
+/** Omitting `formula` or `computedValue` clears it; omitting `format` or `comment` keeps it; null clears it. */
+interface SetCellOp {
+    type: "set_cell";
+    sheet: string;
+    address: string;
+    value?: CellPrimitive;
+    formula?: string;
+    computedValue?: CellPrimitive;
+    format?: CellFormatInput | null;
+    comment?: CommentInput | null;
+}
+/** Values row-major from `start`, each written as a `set_cell` with no formula. `end` is accepted and not read. */
+interface SetRangeOp {
+    type: "set_range";
+    sheet: string;
+    start: string;
+    end?: string;
+    values: CellPrimitive[][];
+}
+interface SetWorkbookOp {
+    type: "set_workbook";
+    data: HolySheetSchema | Record<string, unknown>;
+}
+interface ClearCellOp {
+    type: "clear_cell";
+    sheet: string;
+    address: string;
+}
+/** Insert rows before 1-based row `at`. */
+interface InsertRowsOp {
+    type: "insert_rows";
+    sheet: string;
+    at: number;
+    count: number;
+}
+/** Delete rows starting at 1-based row `at`. */
+interface DeleteRowsOp {
+    type: "delete_rows";
+    sheet: string;
+    at: number;
+    count: number;
+}
+/** Insert columns before 1-based column `at` (A = 1). */
+interface InsertColumnsOp {
+    type: "insert_columns";
+    sheet: string;
+    at: number;
+    count: number;
+}
+/** Delete columns starting at 1-based column `at` (A = 1). */
+interface DeleteColumnsOp {
+    type: "delete_columns";
+    sheet: string;
+    at: number;
+    count: number;
+}
+/** Insert a sheet at a 0-based position. */
+interface AddSheetOp {
+    type: "add_sheet";
+    index: number;
+    sheet: SheetSchema | Record<string, unknown>;
+}
+interface RemoveSheetOp {
+    type: "remove_sheet";
+    sheet: string;
+}
+interface RenameSheetOp {
+    type: "rename_sheet";
+    sheet: string;
+    name: string;
+}
+/** Move a sheet to a 0-based position. */
+interface MoveSheetOp {
+    type: "move_sheet";
+    sheet: string;
+    toIndex: number;
+}
+interface ReplaceSheetOp {
+    type: "replace_sheet";
+    sheet: string;
+    data: SheetSchema | Record<string, unknown>;
+}
+/** An empty list removes the key. */
+interface SetMergedRegionsOp {
+    type: "set_merged_regions";
+    sheet: string;
+    mergedRegions: {
+        start: string;
+        end: string;
+    }[];
+}
+/** 0-based column index to pixels. An empty map removes the key. */
+interface SetColumnWidthsOp {
+    type: "set_column_widths";
+    sheet: string;
+    columnWidths: Record<number | string, number>;
+}
+/** 0 removes the key. */
+interface SetFrozenOp {
+    type: "set_frozen";
+    sheet: string;
+    rows: number;
+    cols: number;
+}
+/** null removes the meta. */
+interface SetMetaOp {
+    type: "set_meta";
+    meta: Record<string, unknown> | null;
+}
+
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.3.1";
-type Any$5 = any;
+declare const VERSION = "2.4.0";
+type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
  * Universal methods are synchronous; file-touching methods (`write`,
@@ -112,11 +232,11 @@ type Any$5 = any;
  */
 declare const Agent: {
     /** Validate a schema without writing. Empty array = valid. */
-    validate(schema: Any$5): ValidationError[];
+    validate(schema: Any$6): ValidationError[];
     /** xlsx bytes without touching disk. Universal. Throws SchemaException if invalid. */
-    toBytes(schema: Any$5): Uint8Array;
+    toBytes(schema: Any$6): Uint8Array;
     /** Write a workbook to disk (Node only). Throws SchemaException if invalid. */
-    write(schema: Any$5, path: string): Promise<WriteResult>;
+    write(schema: Any$6, path: string): Promise<WriteResult>;
     /** JSON Schema for LLM tool-use. */
     toolDefinition(): Record<string, unknown>;
     /**
@@ -128,33 +248,64 @@ declare const Agent: {
     /** Round-trip an xlsx or ods file on disk back to a schema (Node only). */
     describe(path: string): Promise<Record<string, unknown>>;
     /** Validate + conservative repairs in one call. */
-    validateAndRepair(schema: Any$5): RepairResult;
+    validateAndRepair(schema: Any$6): RepairResult;
     /** Build a schema from a flat array of rows (+ optional headers). */
-    fromArray(rows: Any$5[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+    fromArray(rows: Any$6[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
     /** Build a schema from CSV content (read files yourself in Node). */
     fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
     /** Evaluate every formula and report Excel-style errors. Empty array = clean. */
-    lint(schema: Any$5): FormulaProblem[];
+    lint(schema: Any$6): FormulaProblem[];
+    /**
+     * The ops that turn schema `a` into schema `b`. Mirrors PHP `Agent::diff`, and
+     * gives the same ops in the same order for the same inputs.
+     *
+     * - `reduce(a, diff(a, b))` equals `b` (key order aside).
+     * - Schemas that write the same workbook diff to `[]`, so
+     *   `diff(s, read(toBytes(s)))` is `[]`: a save without a change records
+     *   nothing.
+     * - One changed cell is one `set_cell`; an inserted row is one
+     *   `insert_rows` plus its cells.
+     *
+     * Store `diff(newer, older)` to keep a version as the ops that restore it.
+     * Both schemas must be valid: the "same workbook" check writes them.
+     */
+    diff(a: Any$6, b: Any$6): SheetOp[];
+    /**
+     * Apply one op, or a list of them, to a schema; returns a new schema and never
+     * modifies the input. An op naming a sheet that is not there is skipped.
+     */
+    reduce(schema: Any$6, opOrOps: SheetOp | readonly SheetOp[]): Record<string, any>;
+    /**
+     * JSON Schema for one op. `set_cell`, `set_range` and `set_workbook` are
+     * fancy-sheets' `SheetOp` shapes.
+     */
+    opSchema(): Record<string, unknown>;
+    /**
+     * Whether two schemas write the same workbook: a columns/rows sheet and the
+     * cell map it becomes are equivalent, and so are a schema without
+     * `meta.created` and its written copy.
+     */
+    equivalent(a: Any$6, b: Any$6): boolean;
     version(): string;
 };
 
-type Any$4 = any;
+type Any$5 = any;
 /**
  * Holy Sheet — instance entry point mirroring PHP `HolySheet`. Thin wrappers
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.3.1";
-    validate(schema: Any$4): ValidationError[];
-    toBytes(schema: Any$4): Uint8Array;
-    write(schema: Any$4, path: string): Promise<WriteResult>;
+    static readonly VERSION = "2.4.0";
+    validate(schema: Any$5): ValidationError[];
+    toBytes(schema: Any$5): Uint8Array;
+    write(schema: Any$5, path: string): Promise<WriteResult>;
     toolDefinition(): Record<string, unknown>;
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
     describe(path: string): Promise<Record<string, unknown>>;
-    validateAndRepair(schema: Any$4): RepairResult;
-    fromArray(rows: Any$4[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+    validateAndRepair(schema: Any$5): RepairResult;
+    fromArray(rows: Any$5[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
     fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
-    lint(schema: Any$4): FormulaProblem[];
+    lint(schema: Any$5): FormulaProblem[];
     getVersion(): string;
     static version(): string;
 }
@@ -184,24 +335,24 @@ declare class UnsupportedFormatException extends Error {
     static unknownPackage(path: string | null, mimetype: string | null): UnsupportedFormatException;
 }
 
-type Any$3 = any;
+type Any$4 = any;
 /** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
 declare class Validator {
-    validate(schema: Any$3): ValidationError[];
-    assert(schema: Any$3): void;
-    validateAndRepair(schema: Any$3): RepairResult;
+    validate(schema: Any$4): ValidationError[];
+    assert(schema: Any$4): void;
+    validateAndRepair(schema: Any$4): RepairResult;
     private validateSheet;
     private validateColumn;
 }
 
-type Any$2 = any;
+type Any$3 = any;
 /**
  * Conservative, high-confidence schema repairs. Mirrors PHP `Schema\Repairer`.
  * Returns [repairedSchema, repairs].
  */
 declare class Repairer {
     private repairs;
-    repair(schema: Any$2): [Record<string, unknown>, string[]];
+    repair(schema: Any$3): [Record<string, unknown>, string[]];
     private repairTopLevel;
     private repairSheet;
     private repairColumnTypeInference;
@@ -302,10 +453,10 @@ declare class Workbook {
     constructor(sheets: Sheet[], meta?: Record<string, unknown>);
 }
 
-type Any$1 = any;
+type Any$2 = any;
 /** Schema → canonical Workbook. Mirrors PHP `Schema\Normalizer`. */
 declare class Normalizer {
-    normalize(schema: Any$1): Workbook;
+    normalize(schema: Any$2): Workbook;
     private normalizeSheet;
     private normalizeCellMap;
     private normalizeMerges;
@@ -440,13 +591,13 @@ declare const FormatSniffer: {
     };
 };
 
-type Any = any;
+type Any$1 = any;
 /**
  * Flat rows (+ optional headers) → Holy Sheet schema with inferred column types.
  * Mirrors PHP `Helpers\ArrayBuilder`.
  */
 declare const ArrayBuilder: {
-    build(rows: Any[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
+    build(rows: Any$1[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
 };
 
 /**
@@ -471,6 +622,145 @@ declare const CellAddress: {
     parse(address: string): [number, number] | null;
 };
 
+/**
+ * The few PHP array and cast semantics the op reducer and diff depend on, in one
+ * place so `sheet-reducer.ts` and `sheet-diff.ts` read like the PHP they mirror.
+ *
+ * PHP has one array type for lists and maps; a JSON object and a JSON array both
+ * decode to it. `isArr` is PHP's `is_array` over parsed JSON: any object or array.
+ * A key whose value is `undefined` is treated as absent, as JSON would.
+ */
+type Any = any;
+
+/**
+ * The op list that turns one Holy Sheet schema into another. Mirrors PHP
+ * `HolySheet\Ops\SheetDiff`: the same algorithm, so the same inputs give the
+ * same ops in the same order in both runtimes (pinned against the PHP package
+ * by `tests/sheet-ops-parity.test.ts`).
+ *
+ * ## Two guarantees, and where each applies
+ *
+ * 1. **Same workbook, no ops.** When `a` and `b` write the same workbook —
+ *    compared as `read(toBytes(...))`, so a columns/rows sheet and the cell
+ *    map it becomes are the same, and the timestamp the writer stamps on a
+ *    schema that names none is not a change — the diff is `[]`. This is what
+ *    makes `diff(s, read(toBytes(s)))` `[]`: saving without a change records
+ *    nothing.
+ * 2. **Otherwise, exact.** `reduce(a, diff(a, b))` equals `b`, key order
+ *    aside. The ops are computed on the schemas as given and VERIFIED by
+ *    replaying them through `SheetReducer`; a sheet whose granular ops do not
+ *    reproduce it is replaced whole, and a workbook that still does not match
+ *    is replaced whole. Correct first, small second.
+ *
+ * ## Small edits stay small
+ *
+ * Rows and columns are ALIGNED before cells are compared (a longest common
+ * subsequence over each row's, then each column's, contents), so inserting a row
+ * above a hundred others is one `insert_rows` plus the new row's cells, not a
+ * hundred rewritten cells. One changed cell is one `set_cell`.
+ *
+ * Granular ops apply to sheets in CELL form — the form `read()` returns. A sheet
+ * authored as columns/rows/theme/totals, on either side, is replaced whole when
+ * it changes: those keys expand at write time into cells an op could not
+ * address without re-deriving the writer.
+ *
+ * ## Determinism
+ *
+ * Alignment ties break toward deleting first, and the alignment is skipped (the
+ * changed middle treated as rows changed in place) past `ALIGN_LIMIT` cells of
+ * work.
+ */
+declare const SheetDiff: {
+    /** Above this many LCS cells (after trimming the common prefix and suffix), rows or columns are not aligned. */
+    ALIGN_LIMIT: number;
+    diff(a: Any, b: Any): SheetOp[];
+    /**
+     * Whether two schemas write the same workbook.
+     *
+     * Both are written and read back. `meta.created` is compared only when both
+     * schemas name one: the writer stamps the current time on a schema that
+     * does not, and that timestamp is not an edit.
+     */
+    equivalent(a: Any, b: Any): boolean;
+    /**
+     * Structural equality with map key order ignored and list order kept.
+     *
+     * Equality is on values, never on insertion order — a JS object cannot keep
+     * the order of integer-like keys anyway (`columnWidths`). It follows PHP's
+     * canonical form, where lists and maps are one array type: `{}` equals `[]`,
+     * and an object keyed exactly "0".."n-1" equals the list of its values.
+     *
+     * Two divergences from the PHP `same()` cannot be removed, because the
+     * distinctions do not exist in JS values:
+     *
+     * - PHP encodes the float `1.0` as `1.0` and the int `1` as `1`, so it calls
+     *   them different; JS has one number, so here they are the same. A PHP diff
+     *   can therefore emit a `set_cell` that rewrites `1` as `1.0` where this one
+     *   emits nothing. Parsed JSON gives PHP a float only for a literal written
+     *   with a fraction or exponent.
+     * - PHP treats an int-keyed array whose keys are 0..n-1 but out of order (for
+     *   example `columnWidths` decoded from `{"1":140,"0":120}`) as a map, not a
+     *   list, and so as different from the same widths in order. A JS object has
+     *   no such order to compare.
+     */
+    same(a: unknown, b: unknown): boolean;
+    /**
+     * Hunks of a longest-common-subsequence alignment: [start in a, deleted, inserted].
+     *
+     * Ties break toward deleting first. Past `ALIGN_LIMIT` the changed middle is
+     * one hunk.
+     */
+    hunks(a: readonly string[], b: readonly string[]): [number, number, number][];
+};
+
+/**
+ * Apply `SheetOpSchema` ops to a Holy Sheet schema, returning a new schema.
+ * Mirrors PHP `HolySheet\Ops\SheetReducer`, op for op.
+ *
+ * Pure: the input is never modified. An op naming a sheet or cell that is not
+ * there is skipped, as fancy-sheets' `reduceWorkbook` skips an unknown sheet, so
+ * a replayed history degrades rather than throws. Unchanged parts of the input
+ * are shared with the result rather than copied, as in any immutable reducer:
+ * nothing here mutates either, but a caller that mutates a result in place
+ * reaches into the input too.
+ *
+ * `set_cell`, `set_range` and `set_workbook` keep fancy-sheets' shapes and
+ * semantics — a `set_cell` without `formula` clears the formula and keeps the
+ * format and comment; a null write to an absent cell does nothing — so the same
+ * ops can drive a live `useSheetSync` session. Everything else is holy-sheet's:
+ * the structure fancy-sheets has no op for (sheets, rows, columns, merges, widths,
+ * panes, meta) and the cell parts it does not carry (`computedValue`, `format`,
+ * `comment`).
+ *
+ * The row and column ops move cells, merged regions and column widths. They do
+ * not rewrite formula text: a formula that should follow an inserted row is a
+ * change to that cell, and a diff records it as one.
+ */
+declare const SheetReducer: {
+    /** Sheet keys the granular ops address. A sheet with any other key is authored form. */
+    CELL_FORM_KEYS: readonly string[];
+    applyAll(schema: Any, ops: readonly Any[]): Any;
+    apply(schema: Any, op: Any): Any;
+};
+
+/**
+ * JSON Schema for one sheet op — validate ops on the wire, or register the op
+ * vocabulary as an LLM tool. Mirrors PHP `HolySheet\Ops\SheetOpSchema`, key for
+ * key (pinned byte-for-byte against the PHP package by
+ * `tests/sheet-ops-parity.test.ts`).
+ *
+ * `set_cell`, `set_range` and `set_workbook` are fancy-sheets' `SheetOp`
+ * variants, same `type` and same fields, so a stored op stream can drive a live
+ * `useSheetSync` session. One difference: `set_workbook.data` here is a Holy
+ * Sheet schema, not fancy-sheets' `WorkbookData`.
+ */
+declare const SheetOpSchema: {
+    /** Every op type, in the order the variants are listed. */
+    TYPES: readonly ["set_cell", "set_range", "set_workbook", "clear_cell", "insert_rows", "delete_rows", "insert_columns", "delete_columns", "add_sheet", "remove_sheet", "rename_sheet", "move_sheet", "replace_sheet", "set_merged_regions", "set_column_widths", "set_frozen", "set_meta"];
+    /** A fresh object on every call, so a caller editing it changes nothing here. */
+    jsonSchema(): Record<string, unknown>;
+};
+
 interface ZipFile {
     name: string;
     data: Uint8Array;
@@ -479,4 +769,4 @@ declare function zipSync(files: ZipFile[]): Uint8Array;
 
 declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
 
-export { Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, Normalizer, OdsReader, type RepairResult, Repairer, type RowCell, SchemaException, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };
+export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };