@opengeni/artifact-tool 0.2.2

package/src/snapshot.ts

@@ -0,0 +1,88 @@
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
+  EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+} from "@opengeni/contracts/editable-artifact-versions";
+import type { Document } from "./document";
+import {
+  NativeDocumentSession,
+  NativePresentationSession,
+  NativeSpreadsheetSession,
+} from "./native";
+import type { Presentation } from "./presentation";
+import { requireCompositeState } from "./production-composite";
+import type { Workbook } from "./spreadsheet";
+
+type ArtifactSnapshotCommon = Readonly<{
+  schemaVersion: 1;
+  modality: "spreadsheet" | "document" | "presentation";
+  runtimeTarget: string;
+  kernelVersion: string;
+  modelSchemaVersion: 1;
+  snapshotVersion: 1;
+  stateHash: string;
+  snapshotBytes: Uint8Array;
+}>;
+
+/** Exact native-canonical state at one durable artifact boundary. */
+export type ArtifactSnapshot =
+  | (ArtifactSnapshotCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        coveredCausalFrontierBytes: Uint8Array;
+        operationProtocolVersion: 1;
+        crdtStateVersion: 1;
+      }>)
+  | (ArtifactSnapshotCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        nativeRevision: number;
+      }>);
+
+/** Capture one immutable native snapshot from an open artifact object. */
+export function createArtifactSnapshot(
+  artifact: Workbook | Document | Presentation,
+): ArtifactSnapshot {
+  const state = requireCompositeState(artifact);
+  const native = state.native;
+  const common = {
+    schemaVersion: 1 as const,
+    modality: state.modality,
+    runtimeTarget: native.target,
+    kernelVersion: native.buildIdentity,
+    modelSchemaVersion: EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
+    snapshotVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+    stateHash: native.stateHash(),
+    snapshotBytes: Uint8Array.from(native.snapshot()),
+  };
+  if (state.modality === "spreadsheet") {
+    if (!(native instanceof NativeSpreadsheetSession)) {
+      throw new Error("Spreadsheet composite does not own a spreadsheet native session");
+    }
+    return Object.freeze({
+      ...common,
+      modality: "spreadsheet" as const,
+      coveredCausalFrontierBytes: Uint8Array.from(native.frontier()),
+      operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+      crdtStateVersion: EDITABLE_ARTIFACT_SNAPSHOT_VERSION,
+    });
+  }
+  if (
+    !(native instanceof NativeDocumentSession) &&
+    !(native instanceof NativePresentationSession)
+  ) {
+    throw new Error("Serialized composite does not own its expected native session");
+  }
+  return Object.freeze({
+    ...common,
+    modality: state.modality,
+    nativeRevision: safeNativeRevision(native.revision()),
+  });
+}
+
+function safeNativeRevision(value: bigint): number {
+  if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("Artifact native revision exceeds the durable range");
+  }
+  return Number(value);
+}

package/src/spreadsheet-address.ts

@@ -0,0 +1,90 @@
+export const EXCEL_MAX_ROWS = 1_048_576;
+export const EXCEL_MAX_COLUMNS = 16_384;
+
+export type CellAddress = { row: number; col: number };
+export type RangeAddress = CellAddress & { rowCount: number; colCount: number };
+
+export function columnNameToIndex(name: string): number {
+  if (!/^[A-Za-z]+$/.test(name)) throw new Error(`Invalid column name: ${name}`);
+  let value = 0;
+  for (const character of name.toUpperCase()) {
+    value = value * 26 + character.charCodeAt(0) - 64;
+  }
+  const index = value - 1;
+  if (index < 0 || index >= EXCEL_MAX_COLUMNS) {
+    throw new Error(`Column is outside the XLSX range: ${name}`);
+  }
+  return index;
+}
+
+export function columnIndexToName(index: number): string {
+  assertIntegerInRange(index, 0, EXCEL_MAX_COLUMNS - 1, "column index");
+  let value = index + 1;
+  let result = "";
+  while (value > 0) {
+    const remainder = (value - 1) % 26;
+    result = String.fromCharCode(65 + remainder) + result;
+    value = Math.floor((value - 1) / 26);
+  }
+  return result;
+}
+
+export function parseCellAddress(input: string): CellAddress {
+  const match = /^\$?([A-Za-z]+)\$?([1-9]\d*)$/.exec(input.trim());
+  if (!match) throw new Error(`Invalid A1 cell address: ${input}`);
+  const row = Number(match[2]) - 1;
+  if (row < 0 || row >= EXCEL_MAX_ROWS) {
+    throw new Error(`Row is outside the XLSX range: ${input}`);
+  }
+  return { row, col: columnNameToIndex(match[1]!) };
+}
+
+export function parseRangeAddress(input: string): RangeAddress {
+  const parts = input.trim().split(":");
+  if (parts.length > 2 || !parts[0]) throw new Error(`Invalid A1 range: ${input}`);
+  const start = parseCellAddress(parts[0]);
+  const end = parseCellAddress(parts[1] ?? parts[0]);
+  if (end.row < start.row || end.col < start.col) {
+    throw new Error(`Range must run top-left to bottom-right: ${input}`);
+  }
+  return {
+    row: start.row,
+    col: start.col,
+    rowCount: end.row - start.row + 1,
+    colCount: end.col - start.col + 1,
+  };
+}
+
+export function formatCellAddress(address: CellAddress): string {
+  return `${columnIndexToName(address.col)}${address.row + 1}`;
+}
+
+export function formatRangeAddress(address: RangeAddress): string {
+  const start = formatCellAddress(address);
+  if (address.rowCount === 1 && address.colCount === 1) return start;
+  return `${start}:${formatCellAddress({
+    row: address.row + address.rowCount - 1,
+    col: address.col + address.colCount - 1,
+  })}`;
+}
+
+export function cellKey(row: number, col: number): number {
+  return row * EXCEL_MAX_COLUMNS + col;
+}
+
+export function assertRange(address: RangeAddress): void {
+  assertIntegerInRange(address.row, 0, EXCEL_MAX_ROWS - 1, "start row");
+  assertIntegerInRange(address.col, 0, EXCEL_MAX_COLUMNS - 1, "start column");
+  assertIntegerInRange(address.rowCount, 1, EXCEL_MAX_ROWS, "row count");
+  assertIntegerInRange(address.colCount, 1, EXCEL_MAX_COLUMNS, "column count");
+  if (address.row + address.rowCount > EXCEL_MAX_ROWS) throw new Error("Range exceeds XLSX rows");
+  if (address.col + address.colCount > EXCEL_MAX_COLUMNS) {
+    throw new Error("Range exceeds XLSX columns");
+  }
+}
+
+function assertIntegerInRange(value: number, min: number, max: number, label: string): void {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${label} must be an integer between ${min} and ${max}`);
+  }
+}

package/src/spreadsheet-file.ts

@@ -0,0 +1,71 @@
+import type { FileBlob } from "./file-blob";
+import type { Workbook } from "./spreadsheet";
+import {
+  SpreadsheetFidelityError,
+  SpreadsheetSecurityError,
+  type SpreadsheetFidelityIssue,
+  type SpreadsheetLossPreservationEnvelope,
+  type SpreadsheetXlsxExportOptions,
+  type SpreadsheetXlsxImportLimits,
+  type SpreadsheetXlsxImportOptions,
+} from "./spreadsheet-xlsx-api";
+import {
+  spreadsheetFidelityReport,
+  spreadsheetLossPreservationEnvelope,
+} from "./spreadsheet-xlsx-state";
+
+export {
+  SpreadsheetFidelityError,
+  SpreadsheetSecurityError,
+  type SpreadsheetFidelityIssue,
+  type SpreadsheetLossPreservationEnvelope,
+  type SpreadsheetXlsxExportOptions,
+  type SpreadsheetXlsxImportLimits,
+  type SpreadsheetXlsxImportOptions,
+};
+
+/** Lazily loaded XLSX codec around the canonical Workbook model. */
+// eslint-disable-next-line typescript/no-extraneous-class -- Skill-compatible static facade.
+export class SpreadsheetFile {
+  static async importXlsx(
+    input: FileBlob | Blob | ArrayBuffer | Uint8Array,
+    options: SpreadsheetXlsxImportOptions = {},
+  ): Promise<Workbook> {
+    const { SpreadsheetXlsxCodec } = await loadSpreadsheetXlsxCodec();
+    return SpreadsheetXlsxCodec.importXlsx(input, options);
+  }
+
+  static async exportXlsx(
+    workbook: Workbook,
+    options: SpreadsheetXlsxExportOptions = {},
+  ): Promise<FileBlob> {
+    const { SpreadsheetXlsxCodec } = await loadSpreadsheetXlsxCodec();
+    return SpreadsheetXlsxCodec.exportXlsx(workbook, options);
+  }
+
+  static fidelityReport(workbook: Workbook): readonly SpreadsheetFidelityIssue[] {
+    return spreadsheetFidelityReport(workbook);
+  }
+
+  /**
+   * Returns a portable copy of the opaque original-package envelope.
+   * Persist it beside Workbook.toJSON(); the Workbook JSON intentionally does not contain Office bytes.
+   */
+  static lossPreservationEnvelope(workbook: Workbook): SpreadsheetLossPreservationEnvelope | null {
+    return spreadsheetLossPreservationEnvelope(workbook);
+  }
+
+  /** Reattaches a separately persisted envelope to a restored canonical workbook snapshot. */
+  static async attachLossPreservationEnvelope(
+    workbook: Workbook,
+    envelope: SpreadsheetLossPreservationEnvelope,
+    options: Pick<SpreadsheetXlsxImportOptions, "limits"> = {},
+  ): Promise<void> {
+    const { SpreadsheetXlsxCodec } = await loadSpreadsheetXlsxCodec();
+    return SpreadsheetXlsxCodec.attachLossPreservationEnvelope(workbook, envelope, options);
+  }
+}
+
+function loadSpreadsheetXlsxCodec() {
+  return import("@opengeni/artifact-tool/spreadsheet/xlsx");
+}