@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/lib/types/contract/operations.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Operations: their shape, their expansion into Steps, and which Univer
+ * commands may become one (docs/issue/0022 P0).
+ *
+ * The mutation whitelist lives here rather than beside the engine because it is
+ * a policy about the *version model* — which canvas commands are durable
+ * content and which are derived UI state — not an engine detail. The engine
+ * asks; this module decides.
+ */
+import type { WorkbookOperation } from '../types.ts';
+/**
+ * The v3 tier of the Version these operations make up.
+ *
+ * Explicit when the log carries one. Operations written before v3 carry no
+ * `versionKind`, so the tier is derived from the facts that already separated a
+ * deliberate Version from editing-session churn — a summary, an Agent actor, a
+ * restore. Reading a missing tier as its schema default (`named`) instead is what
+ * once made every legacy Version unprunable.
+ *
+ * It is here because two layers need it and neither may import the other: the
+ * projection in `version/grouping.ts` and the retention policy in
+ * `store/retention.ts`, which the directory guard keeps below `version/`. Same
+ * reason `operationSummary` is here. It was written out twice, in different
+ * words that happened to agree.
+ */
+export declare function versionKindOfOperations(operations: WorkbookOperation[]): 'named' | 'auto';
+/**
+ * How many proposals a workbook keeps.
+ *
+ * One constant because the bound was applied in two layers — the manager when it
+ * created a proposal, and the store on every write — which is two policies for
+ * one array, and the layer that runs less often is the one that gets forgotten.
+ * The store owns it now, since it runs on every write.
+ */
+export declare const PROPOSAL_LOG_LIMIT = 20;
+/**
+ * What `append_rows` says when its columns do not match the sheet's header.
+ *
+ * It lives here, not in `contract/mutations.ts` where the check is made, because
+ * the canvas applier raises the same error and `mutations.ts` imports
+ * `node:crypto` — the moment a browser-bundled module reached it, esbuild failed
+ * on a built-in Node module. This module is the one both halves already share.
+ */
+export declare const APPEND_HEADER_MISMATCH = "\u8FFD\u52A0\u6570\u636E\u7684\u5217\u7ED3\u6784\u4E0E\u73B0\u6709\u8868\u5934\u4E0D\u4E00\u81F4\uFF1B\u82E5\u771F\u5B9E\u5217\u5934\u4E0D\u5728\u7B2C 0 \u884C\uFF0C\u8BF7\u7528 headerRowIndex \u6307\u5411\u5B83\uFF0C\u6216\u6539\u7528 workbook_edit \u7684 update_cells command";
+export type UniverMutationPersistence = 'ignore' | 'snapshot';
+/** Classify a Univer command before it is allowed to dirty a workbook. */
+export declare function classifyUniverMutation(commandId: string): UniverMutationPersistence;
+/** Return whether a Univer mutation represents durable workbook state. */
+export declare function shouldPersistUniverMutation(commandId: string): boolean;
+/** Expand a persisted operation into the ordered steps of one Version. A
+ * normal operation is one step; a batch keeps each child visible for history
+ * and replay without introducing a second persistence model. */
+export declare function workbookOperationSteps(operation: WorkbookOperation): WorkbookOperation[];
+export declare function operationSummary(operation: WorkbookOperation): string;

package/lib/types/contract/operations.js

@@ -0,0 +1,203 @@
+/**
+ * Univer emits a small number of mutation commands for derived layout or UI
+ * state. They are useful inside the live canvas, but must not become DSH
+ * workbook revisions: they are either no-ops, recalculation markers, or state
+ * that is reconstructed when the workbook is mounted again. In particular,
+ * selection, focus, scrolling, and editor-panel commands are emitted while a
+ * user is merely navigating the canvas and must not dirty the workbook.
+ */
+const NON_PERSISTED_MUTATION_IDS = new Set([
+    'sheet.mutation.empty',
+    'sheet.mutation.mark-dirty-filter-change',
+    'sheet.mutation.re-calc-filter',
+    'sheet.mutation.set-worksheet-row-auto-height',
+    'sheet.mutation.toggle-note-popup',
+    'sheet.mutation.update-note-position',
+    // View-only operations emitted by clicks, keyboard navigation, and panels.
+    'sheet.operation.set-selections',
+    'sheet.operation.set-worksheet-active',
+    'sheet.operation.set-scroll',
+    'sheet.operation.scroll-to-cell',
+    'sheet.operation.scroll-to-range',
+    'sheet.operation.set-zoom-ratio',
+    'sheet.operation.set-activate-cell-edit',
+    'sheet.operation.set-cell-edit-visible',
+    'sheet.operation.set-cell-edit-visible-arrow',
+    'sheet.operation.set-cell-edit-visible-f2',
+    'sheet.operation.set-format-painter',
+    'sheet.operation.open.numfmt.panel',
+    'sheet.operation.close.numfmt.panel',
+    'sheet.command.apply-format-painter',
+    'sheet.command.set-infinite-format-painter',
+    'sheet.command.set-once-format-painter',
+    'sheet.command.move-selection',
+    'sheet.command.move-selection-enter-tab',
+    'sheet.command.expand-selection',
+    'sheet.command.select-range',
+    'sheet.command.select-all',
+    'sheet.command.set-selection-frozen',
+    'sheet.command.scroll-to-cell',
+    'sheet.command.scroll-view',
+    'sheet.command.scroll-view-reset',
+    'sheet.command.set-scroll-relative',
+    'sheet.command.change-zoom-ratio',
+    'sheet.command.set-zoom-ratio',
+    'sheet.command.set-worksheet-activate',
+]);
+const NON_PERSISTED_MUTATION_PREFIXES = [
+    // Univer appends editor-specific suffixes to these UI operations.
+    'sheet.operation.editor-',
+];
+// Only these command ids are known to describe durable workbook state.  The
+// previous deny-list treated every new Univer command as a save candidate;
+// that made a navigation command capable of setting the dirty bit and caused
+// an unnecessary full snapshot request.  Unknown commands are deliberately
+// ignored until they have an explicit persistence contract and a parser.
+const PERSISTED_MUTATION_IDS = new Set([
+    'sheet.mutation.set-range-values',
+    'sheet.mutation.set-row-data',
+    'sheet.mutation.set-col-data',
+    'sheet.mutation.set-gridlines-color',
+    'sheet.mutation.set-worksheet-name',
+    'sheet.mutation.add-worksheet-merge',
+    'sheet.mutation.remove-worksheet-merge',
+    'sheet.mutation.set-style',
+    'sheet.mutation.set-number-format',
+    'sheet.command.clear-selection-content',
+    'sheet.command.set-bold',
+    'sheet.command.set-italic',
+    'sheet.command.set-underline',
+    'sheet.command.set-strikethrough',
+    'sheet.command.set-style',
+    'sheet.command.set-range-values',
+    'sheet.command.set-number-format',
+    'sheet.command.set-font-color',
+    'sheet.command.set-font-family',
+    'sheet.command.set-font-size',
+    'sheet.command.set-font-weight',
+    'sheet.command.set-font-style',
+    'sheet.command.set-horizontal-alignment',
+    'sheet.command.set-vertical-alignment',
+]);
+/**
+ * The v3 tier of the Version these operations make up.
+ *
+ * Explicit when the log carries one. Operations written before v3 carry no
+ * `versionKind`, so the tier is derived from the facts that already separated a
+ * deliberate Version from editing-session churn — a summary, an Agent actor, a
+ * restore. Reading a missing tier as its schema default (`named`) instead is what
+ * once made every legacy Version unprunable.
+ *
+ * It is here because two layers need it and neither may import the other: the
+ * projection in `version/grouping.ts` and the retention policy in
+ * `store/retention.ts`, which the directory guard keeps below `version/`. Same
+ * reason `operationSummary` is here. It was written out twice, in different
+ * words that happened to agree.
+ */
+export function versionKindOfOperations(operations) {
+    const explicit = operations.map(operation => operation.versionKind).find(kind => kind !== undefined);
+    if (explicit !== undefined)
+        return explicit;
+    const first = operations[0];
+    const last = operations.at(-1);
+    const deliberate = first?.versionSummary !== undefined || last?.versionSummary !== undefined
+        || first?.actor === 'agent'
+        || first?.restoredFromRevision !== undefined || last?.restoredFromRevision !== undefined;
+    return deliberate ? 'named' : 'auto';
+}
+/**
+ * How many proposals a workbook keeps.
+ *
+ * One constant because the bound was applied in two layers — the manager when it
+ * created a proposal, and the store on every write — which is two policies for
+ * one array, and the layer that runs less often is the one that gets forgotten.
+ * The store owns it now, since it runs on every write.
+ */
+export const PROPOSAL_LOG_LIMIT = 20;
+/**
+ * What `append_rows` says when its columns do not match the sheet's header.
+ *
+ * It lives here, not in `contract/mutations.ts` where the check is made, because
+ * the canvas applier raises the same error and `mutations.ts` imports
+ * `node:crypto` — the moment a browser-bundled module reached it, esbuild failed
+ * on a built-in Node module. This module is the one both halves already share.
+ */
+export const APPEND_HEADER_MISMATCH = '追加数据的列结构与现有表头不一致；若真实列头不在第 0 行，请用 headerRowIndex 指向它，或改用 workbook_edit 的 update_cells command';
+/** Classify a Univer command before it is allowed to dirty a workbook. */
+export function classifyUniverMutation(commandId) {
+    // Three rules, in order, each written as its own statement.
+    //
+    // It used to be two, the second of which read
+    // `A || B && !PERSISTED.has(id)`. `&&` binds tighter than `||`, so that was
+    // `A || (B && !has)`, not `(A || B) && !has` — and since the last line is an
+    // allow-list, the `B && !has` half could never change an answer. It is still
+    // unreachable today (no `sheet.operation.*` id is in the allow-list), but it
+    // would have flipped the moment one was added, in a file whose whole purpose
+    // is to say which commands may dirty a workbook.
+    if (NON_PERSISTED_MUTATION_IDS.has(commandId)
+        || NON_PERSISTED_MUTATION_PREFIXES.some(prefix => commandId.startsWith(prefix)))
+        return 'ignore';
+    // The `sheet.operation.*` namespace is view state — selections, scrolling,
+    // panel visibility. It is ignored *whatever* the allow-list later says, which
+    // is what the accidental `A ||` did and what is meant here.
+    if (commandId.startsWith('sheet.operation.'))
+        return 'ignore';
+    // Everything else is durable only with an explicit contract. Unknown commands
+    // are ignored on purpose: treating a new Univer command as a save candidate is
+    // how a navigation keystroke marks a workbook dirty.
+    return PERSISTED_MUTATION_IDS.has(commandId) ? 'snapshot' : 'ignore';
+}
+/** Return whether a Univer mutation represents durable workbook state. */
+export function shouldPersistUniverMutation(commandId) {
+    return classifyUniverMutation(commandId) !== 'ignore';
+}
+/** Expand a persisted operation into the ordered steps of one Version. A
+ * normal operation is one step; a batch keeps each child visible for history
+ * and replay without introducing a second persistence model. */
+export function workbookOperationSteps(operation) {
+    if (operation.type !== 'batch')
+        return [operation];
+    return (operation.payload.operations ?? []).map((child, index) => ({
+        opId: `${operation.opId}:${index + 1}`,
+        workbookId: operation.workbookId,
+        revision: operation.revision,
+        parentRevision: operation.parentRevision,
+        baseRevision: operation.baseRevision,
+        versionId: operation.versionId,
+        versionStatus: operation.versionStatus,
+        versionSummary: operation.versionSummary,
+        versionKind: operation.versionKind,
+        stepSummary: operation.stepSummary,
+        versionIntent: operation.versionIntent,
+        agentRunId: operation.agentRunId,
+        lineage: operation.lineage,
+        restoredFromRevision: operation.restoredFromRevision,
+        actor: operation.actor,
+        type: child.type,
+        timestamp: operation.timestamp,
+        payload: child.payload,
+    }));
+}
+export function operationSummary(operation) {
+    // A derived summary wins: the server knows what a generic operation changed
+    // (see `describeSnapshotReplace`). This used to exist twice — here and in
+    // `index.ts` — under a comment asking the two copies to stay in step.
+    if (operation.stepSummary !== undefined)
+        return operation.stepSummary;
+    const payload = operation.payload;
+    switch (operation.type) {
+        case 'update_cells': return `更新 ${payload.cells?.length ?? 0} 个单元格`;
+        case 'append_rows': return `追加 ${payload.rows?.length ?? 0} 行`;
+        case 'set_hyperlink': return '设置超链接';
+        case 'remove_hyperlink': return '移除超链接';
+        case 'create_sheet': return `新增 sheet${payload.name === undefined ? '' : `：${payload.name}`}`;
+        case 'delete_sheet': return '删除 sheet';
+        case 'rename_sheet': return `重命名 sheet${payload.name === undefined ? '' : `：${payload.name}`}`;
+        case 'batch': return `批量操作（${payload.operations?.length ?? 0} 个 step）`;
+        // Only pre-v3.1 records reach this: their payload was compacted away, so
+        // the change they made can no longer be derived. Say so, instead of a
+        // neutral label that reads like a normal save.
+        case 'snapshot_replace': return '保存整表内容（旧记录）';
+        default: return operation.type;
+    }
+}

package/lib/types/contract/snapshots.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Snapshot vocabulary: the workbook snapshot shape, the matrix tools, and the
+ * one range reader (docs/issue/0022 P0).
+ *
+ * The readers here are pure functions of their arguments. The two **accessors**
+ * are not, and the distinction is worth stating because the module used to claim
+ * otherwise:
+ *
+ *   - `asWorkbookSnapshot` fills in a missing `sheetOrder` by writing it into the
+ *     object it was handed. That is how a caller's `payload.snapshot` could be
+ *     modified as a side effect of reading it, which is what made a stored
+ *     operation's payload accumulate later revisions. `applyWorkbookOperation`
+ *     now clones before returning, so the write lands on a copy — but this
+ *     function still writes to its argument, and a caller must not assume
+ *     otherwise.
+ *   - `resolveSheet` materializes `cellData` on the sheet it returns. That is
+ *     load-bearing, not incidental: writers mutate the returned sheet and expect
+ *     the change to land in the snapshot, so handing back a copy would silently
+ *     drop every edit.
+ *
+ * `cloneSnapshot` is the point of the move: it existed twice — once in the model
+ * layer and once again inside `client/SheetPanel.tsx` — which is exactly the
+ * drift a contract module exists to prevent.
+ */
+import { type SheetSchema, type WorkbookCellStyle, type WorkbookCellValue, type WorkbookRange } from '../types.ts';
+/**
+ * The snapshot shape. It is declared here rather than in `types.ts` because it
+ * is the *input* of these functions and of nothing else on the wire; the
+ * tool-facing types stay in `types.ts`.
+ */
+/**
+ * The font family a blank sheet is created with.
+ *
+ * It lives in the contract because it is part of the stored snapshot's default
+ * style: the model, the xlsx reader and the engine all have to agree on it.
+ * Before the 0022 refactor it lived in the engine's font module, which made the
+ * model layer import *upward* into the engine (docs/issue/0022 §2).
+ */
+export declare const DEFAULT_SHEET_FONT_FAMILY = "PingFang SC";
+/**
+ * The grid a new sheet starts with.
+ *
+ * One constant because *two* layers create sheets — the snapshot mutator and the
+ * Univer canvas — and a sheet's declared extent has to match the grid the user
+ * is looking at. It was written out as `1000` and `26` in seven places across
+ * five files, which is how the two drift apart without anyone editing either
+ * number. It is also a *starting* size, not a read limit: writes grow the sheet
+ * (`SHEET_MAX_ROWS` is the ceiling), and reads take the range they are given.
+ */
+export declare const DEFAULT_SHEET_ROWS = 1000;
+export declare const DEFAULT_SHEET_COLUMNS = 26;
+export interface WorkbookSnapshot {
+    sheetOrder: string[];
+    sheets: Record<string, WorkbookSheet>;
+    [key: string]: unknown;
+}
+export interface WorkbookSheet {
+    id: string;
+    name: string;
+    rowCount: number;
+    columnCount: number;
+    cellData: Record<string, Record<string, StoredCell>>;
+    [key: string]: unknown;
+}
+export interface StoredCell {
+    v?: unknown;
+    f?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Deterministic JSON, so two equal values serialize identically.
+ *
+ * Object keys are sorted, which `JSON.stringify` does not do: it follows
+ * insertion order, so two snapshots holding the same content in a different
+ * order would compare unequal. Used for content hashes and for deciding whether
+ * a merge actually changed anything.
+ *
+ * It lived in the model layer *and* in the browser's merge code, byte for byte.
+ */
+export declare function stableJson(value: unknown): string;
+/** Deep copy through JSON; snapshots are plain JSON by construction. */
+export declare function cloneSnapshot<T>(value: T): T;
+/**
+ * Narrow `value` to a snapshot, defaulting `sheetOrder` from `sheets`.
+ *
+ * **Writes to its argument** when `sheetOrder` is absent (see the module note).
+ * Every caller here uses the return value, and `applyWorkbookOperation` clones,
+ * but a new caller should not read a snapshot *and* hand the same object
+ * somewhere else without knowing that.
+ */
+export declare function asWorkbookSnapshot(value: unknown): WorkbookSnapshot;
+export declare function resolveSheet(root: WorkbookSnapshot, ref: string | undefined): WorkbookSheet;
+export declare function validateIndex(value: number, label: string): void;
+export declare function validateRange(range: WorkbookRange | undefined): asserts range is WorkbookRange;
+/**
+ * A cell's formula in the one form this repository stores.
+ *
+ * `=SUM(A1:A2)` and `SUM(A1:A2)` are the same formula — the leading `=` is how a
+ * spreadsheet *displays* it, not part of it — and the whitespace around it is not
+ * part of it either. An input that reduces to nothing is not a formula at all.
+ *
+ * Four places wrote cells and each decided this for itself, so they disagreed:
+ * `update_cells` with `formula: '=SUM(A1:A2)'` stored `SUM(A1:A2)` in the
+ * snapshot and drew `=SUM(A1:A2)` on the canvas; `formula: ''` deleted the cell
+ * in the snapshot and left `{v:null,f:''}` on the canvas; `'='` was dropped by
+ * the snapshot and kept by the browser's merge. The snapshot and the canvas are
+ * two views of one workbook, so they cannot disagree about what is in it.
+ */
+export declare function normalizeCellFormula(formula: unknown): string | undefined;
+export declare function toCellValue(cell: StoredCell | undefined): WorkbookCellValue | null;
+export declare function cellType(value: WorkbookCellValue | null): string;
+/**
+ * The last row and column that actually carry something, or `-1` when the sheet
+ * is empty.
+ *
+ * A whole-sheet read needs this: the caller asking for "the sheet" must get the
+ * sheet, and the only way to know how big that is, is to look. A hard-coded
+ * window cannot know, and a window that is too small loses data silently.
+ *
+ * A cell that holds only a style is skipped — formatting an empty range writes
+ * style ids into every cell it covers, and those must not stretch a read.
+ */
+export declare function usedExtent(snapshot: unknown, sheetRef: string | undefined): {
+    endRow: number;
+    endColumn: number;
+};
+/**
+ * The style a cell actually paints with: the sheet's default under the cell's
+ * own, field by field.
+ *
+ * The sheet default is load-bearing, not decoration. `DEFAULT_SHEET_FONT_FAMILY`
+ * lives in every sheet's `defaultStyle` and is the **only** place a font family
+ * is recorded for a cell the user never formatted — a reader that skipped it
+ * would report "no font" for most of a sheet, which is how the Sheet Block
+ * preview could not show the font the workbook is actually set in.
+ *
+ * `null` means there is nothing to paint, so the wire carries a compact matrix
+ * instead of an object per empty cell.
+ */
+export declare function effectiveCellStyle(root: WorkbookSnapshot, sheet: WorkbookSheet, cell: StoredCell | undefined): WorkbookCellStyle | null;
+export declare function readWorkbookRange(snapshot: unknown, sheetRef: string, range: WorkbookRange, options?: {
+    styles?: boolean;
+}): {
+    sheetId: string;
+    sheetName: string;
+    range: WorkbookRange;
+    values: Array<Array<WorkbookCellValue | null>>;
+    formulas: Array<Array<string | null>>;
+    cells: Array<Array<{
+        value: WorkbookCellValue | null;
+        formula: string | null;
+        type: string;
+        calculation?: 'cached' | 'unavailable';
+        error?: string;
+    }>>;
+    /**
+     * The effective style of every cell in `values`, when the caller asked for it.
+     *
+     * Opt-in, because the two readers of this range want different things: the SQL
+     * loader materializes values as a relation and would pay for a second matrix
+     * it never reads, while the Sheet Block preview exists to show the range the
+     * way the sheet draws it.
+     */
+    styles?: Array<Array<WorkbookCellStyle | null>>;
+};
+/**
+ * Return original sheet row indexes that are duplicates within a rectangular
+ * range. This follows Excel's default behavior: compare the selected columns,
+ * keep the first occurrence, and leave the header untouched when requested.
+ */
+export declare function findDuplicateRows(values: ReadonlyArray<ReadonlyArray<unknown>>, range: WorkbookRange, columns?: readonly number[], hasHeader?: boolean, keep?: 'first' | 'last'): number[];
+export declare function isSheetSchema(value: unknown): value is SheetSchema;
+/** Force a snapshot's `name` field to the workbook's user-facing name.
+ * Both the read and the write path need it, which is why it is vocabulary
+ * rather than a store helper. */
+export declare function normalizeSnapshotName(snapshot: unknown, name: string): unknown;