@stll/folio-core 0.32.2 → 0.33.0

package/dist/compare/reproducible-package.d.ts

@@ -0,0 +1,17 @@
+//#region src/compare/reproducible-package.d.ts
+/**
+ * The last clock in the compare path is the ZIP container itself.
+ *
+ * Every part the serializer rewrites is stored with JSZip's default entry
+ * date, which is `new Date()`. The XML is identical between two runs, but the
+ * DOS timestamp fields in the local headers are not, and they only agree when
+ * both runs land in the same two-second bucket — so the packages match most of
+ * the time and differ occasionally, which is worse than differing always.
+ *
+ * Restamping every entry from the comparison's own timestamp removes it. It
+ * also states the truth about the package: a generated redline is dated by the
+ * comparison that produced it, not by the second it happened to be written.
+ */
+declare const withFixedPackageDates: (buffer: ArrayBuffer, date: Date) => Promise<ArrayBuffer>;
+//#endregion
+export { withFixedPackageDates };

package/dist/compare/reproducible-package.js

@@ -0,0 +1,30 @@
+import JSZip from "jszip";
+//#region src/compare/reproducible-package.ts
+/**
+* The last clock in the compare path is the ZIP container itself.
+*
+* Every part the serializer rewrites is stored with JSZip's default entry
+* date, which is `new Date()`. The XML is identical between two runs, but the
+* DOS timestamp fields in the local headers are not, and they only agree when
+* both runs land in the same two-second bucket — so the packages match most of
+* the time and differ occasionally, which is worse than differing always.
+*
+* Restamping every entry from the comparison's own timestamp removes it. It
+* also states the truth about the package: a generated redline is dated by the
+* comparison that produced it, not by the second it happened to be written.
+*/
+/** JSZip deflate level `repackDocx` writes DOCX parts at. */
+const DOCX_COMPRESSION_LEVEL = 6;
+const withFixedPackageDates = async (buffer, date) => {
+	const zip = await JSZip.loadAsync(buffer);
+	zip.forEach((_path, file) => {
+		file.date = date;
+	});
+	return await zip.generateAsync({
+		type: "arraybuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: DOCX_COMPRESSION_LEVEL }
+	});
+};
+//#endregion
+export { withFixedPackageDates };

package/dist/compare/scenario.d.ts

@@ -0,0 +1,77 @@
+import { FolioAIInlineFormatting } from "../ai-edits/types.js";
+import { CompareDocxParseError, CompareDocxSerializeError } from "./types.js";
+import { Result } from "better-result";
+//#region src/compare/scenario.d.ts
+type EditScriptStep = {
+  type: "insertParagraphAfter";
+  blockIndex: number;
+  text: string;
+} | {
+  type: "deleteParagraph";
+  blockIndex: number;
+} | {
+  type: "replaceWords";
+  blockIndex: number;
+  find: string;
+  replace: string;
+} |
+/** Delete the block at `blockIndex` and reinsert its text before `beforeBlockIndex`. */
+{
+  type: "moveParagraph";
+  blockIndex: number;
+  beforeBlockIndex: number;
+} |
+/**
+ * Break one paragraph into two at `wordIndex`, which is an inserted
+ * paragraph mark and nothing else: both halves keep their words.
+ */
+{
+  type: "splitParagraph";
+  blockIndex: number;
+  wordIndex: number;
+} |
+/**
+ * Join the block at `blockIndex` with the one after it, which is a deleted
+ * paragraph mark and nothing else.
+ */
+{
+  type: "mergeParagraphs";
+  blockIndex: number;
+} | {
+  type: "formatRange";
+  blockIndex: number;
+  startOffset: number;
+  endOffset: number;
+  formatting: FolioAIInlineFormatting;
+} | {
+  type: "insertTableRow";
+  blockIndex: number;
+  cellTexts: readonly string[];
+} | {
+  type: "deleteTableRow";
+  blockIndex: number;
+} | {
+  type: "editTableCell";
+  blockIndex: number;
+  text: string;
+};
+type EditScript = readonly EditScriptStep[];
+declare const EDIT_SCRIPT_UNRESOLVED_REASONS: readonly ["block-out-of-range", "block-not-in-table", "range-out-of-bounds", "text-not-found", "no-paragraph-boundary", "refused"];
+type EditScriptUnresolvedReason = (typeof EDIT_SCRIPT_UNRESOLVED_REASONS)[number];
+type EditScriptUnresolvedStep = {
+  step: EditScriptStep;
+  reason: EditScriptUnresolvedReason;
+};
+type EditScriptResult = {
+  /** The base document with every applied step written in directly. */
+  buffer: ArrayBuffer;
+  /** The steps that reached the document, in script order. */
+  applied: readonly EditScriptStep[];
+  unresolved: readonly EditScriptUnresolvedStep[];
+};
+/**
+ * Apply `script` to `base` directly and return the resulting target document.
+ */
+declare const applyEditScript: (base: ArrayBuffer, script: EditScript) => Promise<Result<EditScriptResult, CompareDocxParseError | CompareDocxSerializeError>>;
+//#endregion
+export { EDIT_SCRIPT_UNRESOLVED_REASONS, EditScript, EditScriptResult, EditScriptStep, EditScriptUnresolvedReason, EditScriptUnresolvedStep, applyEditScript };

package/dist/compare/scenario.js

@@ -0,0 +1,263 @@
+import { FolioDocxReviewer } from "../ai-edits/headless.js";
+import { createFolioAITextRangeHandle } from "../ai-edits/snapshot.js";
+import { CompareDocxParseError, CompareDocxSerializeError } from "./types.js";
+import { Result, panic } from "better-result";
+//#region src/compare/scenario.ts
+/**
+* Edit scripts: ground truth for the compare engine, by construction.
+*
+* A property test cannot assert "this redline is right" against a document it
+* only guessed at. It can assert it against a document it BUILT: take a real
+* base, apply a scripted edit directly (no tracked changes), and the result is
+* a target whose difference from the base is known exactly. `compareDocx` then
+* has to rediscover that difference, and the script says what it should have
+* found.
+*
+* Every step is applied through the same headless applier `compareDocx` writes
+* its own operations through, in `"direct"` mode — so the target is an ordinary
+* document, not one carrying revisions the comparison would have to resolve
+* first.
+*
+* Steps address blocks by their index in the base story's block list rather
+* than by id, so a generator can pick targets without first parsing the
+* document. A step that does not resolve is reported in `unresolved`, never
+* dropped: a script silently doing less than it says would weaken every
+* property built on it.
+*/
+const EDIT_SCRIPT_UNRESOLVED_REASONS = Object.freeze([
+	"block-out-of-range",
+	"block-not-in-table",
+	"range-out-of-bounds",
+	"text-not-found",
+	"no-paragraph-boundary",
+	"refused"
+]);
+const blockAt = (blocks, index) => Number.isInteger(index) && index >= 0 ? blocks.at(index) : void 0;
+const planStep = ({ step, blocks, nextOperationId }) => {
+	const block = blockAt(blocks, step.blockIndex);
+	if (!block) return {
+		status: "unresolved",
+		reason: "block-out-of-range"
+	};
+	switch (step.type) {
+		case "insertParagraphAfter": return {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "insertAfterBlock",
+				blockId: block.id,
+				text: step.text
+			}]
+		};
+		case "deleteParagraph": return {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "deleteBlock",
+				blockId: block.id
+			}]
+		};
+		case "replaceWords": return block.text.includes(step.find) ? {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "replaceInBlock",
+				blockId: block.id,
+				find: step.find,
+				replace: step.replace
+			}]
+		} : {
+			status: "unresolved",
+			reason: "text-not-found"
+		};
+		case "moveParagraph": {
+			const destination = blockAt(blocks, step.beforeBlockIndex);
+			if (!destination || destination.id === block.id) return {
+				status: "unresolved",
+				reason: "block-out-of-range"
+			};
+			return {
+				status: "planned",
+				operations: [{
+					id: nextOperationId(),
+					type: "deleteBlock",
+					blockId: block.id
+				}, {
+					id: nextOperationId(),
+					type: "insertBeforeBlock",
+					blockId: destination.id,
+					text: block.text,
+					styleId: block.styleId ?? null,
+					listLevel: block.listLevel ?? null
+				}]
+			};
+		}
+		case "splitParagraph": {
+			const words = block.text.split(" ");
+			if (step.wordIndex <= 0 || step.wordIndex >= words.length) return {
+				status: "unresolved",
+				reason: "no-paragraph-boundary"
+			};
+			return {
+				status: "planned",
+				operations: [{
+					id: nextOperationId(),
+					type: "replaceBlock",
+					blockId: block.id,
+					text: words.slice(0, step.wordIndex).join(" ")
+				}, {
+					id: nextOperationId(),
+					type: "insertAfterBlock",
+					blockId: block.id,
+					text: words.slice(step.wordIndex).join(" "),
+					...block.styleId !== void 0 && { styleId: block.styleId }
+				}]
+			};
+		}
+		case "mergeParagraphs": {
+			const next = blockAt(blocks, step.blockIndex + 1);
+			if (!next || next.table?.cellIndex !== block.table?.cellIndex) return {
+				status: "unresolved",
+				reason: "no-paragraph-boundary"
+			};
+			return {
+				status: "planned",
+				operations: [{
+					id: nextOperationId(),
+					type: "replaceBlock",
+					blockId: block.id,
+					text: `${block.text} ${next.text}`
+				}, {
+					id: nextOperationId(),
+					type: "deleteBlock",
+					blockId: next.id
+				}]
+			};
+		}
+		case "formatRange": {
+			const range = createFolioAITextRangeHandle({
+				blockId: block.id,
+				text: block.text,
+				startOffset: step.startOffset,
+				endOffset: step.endOffset
+			});
+			return range ? {
+				status: "planned",
+				operations: [{
+					id: nextOperationId(),
+					type: "formatRange",
+					range,
+					formatting: step.formatting
+				}]
+			} : {
+				status: "unresolved",
+				reason: "range-out-of-bounds"
+			};
+		}
+		case "insertTableRow": return block.table ? {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "insertTableRow",
+				blockId: block.id,
+				position: "after",
+				cellTexts: [...step.cellTexts]
+			}]
+		} : {
+			status: "unresolved",
+			reason: "block-not-in-table"
+		};
+		case "deleteTableRow": return block.table ? {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "deleteTableRow",
+				blockId: block.id
+			}]
+		} : {
+			status: "unresolved",
+			reason: "block-not-in-table"
+		};
+		case "editTableCell": return block.table ? {
+			status: "planned",
+			operations: [{
+				id: nextOperationId(),
+				type: "replaceBlock",
+				blockId: block.id,
+				text: step.text
+			}]
+		} : {
+			status: "unresolved",
+			reason: "block-not-in-table"
+		};
+		default: return panic("Unhandled edit script step", { step });
+	}
+};
+/**
+* Apply `script` to `base` directly and return the resulting target document.
+*/
+const applyEditScript = async (base, script) => {
+	const parsed = await Result.tryPromise({
+		try: async () => await FolioDocxReviewer.fromBuffer(base),
+		catch: (cause) => new CompareDocxParseError({
+			message: "The edit script's base document could not be parsed.",
+			side: "base",
+			cause
+		})
+	});
+	if (parsed.isErr()) return Result.err(parsed.error);
+	const reviewer = parsed.value;
+	const snapshot = reviewer.snapshot();
+	const unresolved = [];
+	const planned = [];
+	let operationSequence = 0;
+	const nextOperationId = () => `scenario-${++operationSequence}`;
+	for (const step of script) {
+		const plan = planStep({
+			step,
+			blocks: snapshot.blocks,
+			nextOperationId
+		});
+		if (plan.status === "unresolved") {
+			unresolved.push({
+				step,
+				reason: plan.reason
+			});
+			continue;
+		}
+		planned.push({
+			step,
+			operations: plan.operations
+		});
+	}
+	const { skipped } = reviewer.applyOperations(planned.flatMap(({ operations }) => [...operations]), {
+		mode: "direct",
+		snapshot
+	});
+	const skippedIds = new Set(skipped.map(({ id }) => id));
+	const applied = [];
+	for (const { step, operations } of planned) {
+		if (operations.some(({ id }) => skippedIds.has(id))) {
+			unresolved.push({
+				step,
+				reason: "refused"
+			});
+			continue;
+		}
+		applied.push(step);
+	}
+	const serialized = await Result.tryPromise({
+		try: async () => await reviewer.toBuffer(),
+		catch: (cause) => new CompareDocxSerializeError({
+			message: "The edit script's target document could not be serialized.",
+			cause
+		})
+	});
+	return serialized.isErr() ? Result.err(serialized.error) : Result.ok({
+		buffer: serialized.value,
+		applied,
+		unresolved
+	});
+};
+//#endregion
+export { EDIT_SCRIPT_UNRESOLVED_REASONS, applyEditScript };

package/dist/compare/types.d.ts

@@ -0,0 +1,282 @@
+import { FolioAIBlockParagraphProperties, FolioAIBlockTableLocation, FolioAIEditSkippedOperation, FolioAIInlineFormatting } from "../ai-edits/types.js";
+import { WordDiffGranularity } from "../ai-edits/word-diff.js";
+import { FolioDocumentStoryHandle, FolioNumberingLevel } from "../ai-edits/headless.js";
+import { CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant } from "./verification.js";
+//#region src/compare/types.d.ts
+/** Everything {@link compareDocx} needs; nothing it reads from the ambient clock. */
+type CompareDocxOptions = {
+  /** Author recorded on every generated tracked change. */
+  author: string;
+  /**
+   * ISO-8601 date stamped on every generated tracked change. Required rather
+   * than defaulted so a caller cannot get a nondeterministic package by
+   * omission; pass the base document's own timestamp, a release date, or a
+   * fixed epoch.
+   */
+  timestamp: string;
+  /**
+   * What to do when the round-trip self-check cannot prove the result.
+   *
+   * `"refuse"` (default) returns a {@link CompareDocxRoundTripError}: a
+   * redline that reads plausibly and is wrong is worse than no redline.
+   * `"emit"` returns the redline anyway, with `verification` naming every
+   * invariant that did not hold, for a caller that would rather show its best
+   * attempt and say what is missing.
+   */
+  onUnverified?: "refuse" | "emit";
+  /**
+   * Token size a changed paragraph's redline is cut at: `"word"` (default)
+   * marks whole words, `"character"` marks the changed letters inside one.
+   *
+   * Case and whitespace normalization are not options here, though
+   * `diffWordSegments` offers them: a comparison that leaves a difference
+   * unmarked does not accept back to the target, and the round trip is the
+   * one thing this call promises.
+   */
+  granularity?: WordDiffGranularity;
+};
+/** Where one change sits in the base or target document. */
+type CompareChangeLocation = {
+  story: FolioDocumentStoryHandle;
+  /** Innermost table cell, when the change is inside a table. */
+  cell?: FolioAIBlockTableLocation;
+};
+/** One run of characters whose inline formatting differs, in base-block offsets. */
+type CompareFormatRange = {
+  startOffset: number;
+  endOffset: number;
+  /** Only the properties that differ, set to the target document's value. */
+  formatting: FolioAIInlineFormatting;
+};
+/**
+ * One difference between the two documents, in target-document order with
+ * base-only entries slotted where they sat. Every variant is plain JSON, so a
+ * caller can hand the list to an agent instead of the package.
+ *
+ * A `move` is reported, not represented: the tracked-change grammar has no
+ * "this paragraph came from there" mark that Word round-trips, so the buffer
+ * carries a deletion at the source and an insertion at the destination while
+ * the change list keeps the relocation visible.
+ */
+type CompareChange = {
+  kind: "insert";
+  location: CompareChangeLocation;
+  /** Id of the inserted block in the target document. */
+  targetBlockId: string;
+  after: string;
+} | {
+  kind: "delete";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  before: string;
+} | {
+  kind: "replace";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  before: string;
+  after: string;
+} | {
+  kind: "move";
+  location: CompareChangeLocation;
+  /** The block's id where it sat in the base document. */
+  baseBlockId: string;
+  /** The same content's id where it sits in the target document. */
+  targetBlockId: string;
+  text: string;
+} |
+/**
+ * One paragraph became two: a paragraph mark was inserted and no words
+ * changed. Reported as its own kind so a reader is not told the tail was
+ * newly written.
+ */
+{
+  kind: "split";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  /** The two blocks the base block became, in target order. */
+  targetBlockIds: readonly string[];
+  text: string;
+} |
+/** Two paragraphs became one: a paragraph mark was deleted. */
+{
+  kind: "merge";
+  location: CompareChangeLocation;
+  /** The two blocks that became one, in base order. */
+  baseBlockIds: readonly string[];
+  targetBlockId: string;
+  text: string;
+} |
+/**
+ * A paragraph property moved and no words did: a list item demoted a level,
+ * a paragraph restyled. Written as `w:pPrChange`, so rejecting restores the
+ * whole previous property set the way Word does.
+ */
+{
+  kind: "paragraph-format";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  /** Only the properties that differ, set to the target document's value. */
+  properties: FolioAIBlockParagraphProperties;
+} | {
+  kind: "format";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  text: string;
+  ranges: readonly CompareFormatRange[];
+} | {
+  kind: "table-row-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Row index in the target document's table. */
+  rowIndex: number;
+  /** The new row's cell texts, in physical cell order. */
+  cells: readonly string[];
+  targetBlockIds: readonly string[];
+} |
+/**
+ * A numbering definition that differs. It carries no `location`: numbering
+ * lives in the package, not in a story, and one definition governs every
+ * list that references it.
+ *
+ * Reported and not represented. A renumbering that FOLLOWS from an edit —
+ * an item inserted, so the ones below it count on — is already shown
+ * as-if-accepted, because labels are rendered from these definitions rather
+ * than stored on the paragraphs. A definition that itself changed is a
+ * different thing, and OOXML has no tracked-change grammar for it: Word
+ * does not track `numbering.xml` either.
+ */
+{
+  kind: "numbering";
+  numId: number;
+  level: number;
+  /** `null` when the target added this level. */
+  before: FolioNumberingLevel | null;
+  /** `null` when the target dropped it. */
+  after: FolioNumberingLevel | null;
+} |
+/** A whole table the target added. */
+{
+  kind: "table-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Cell texts row by row, in physical cell order. */
+  rows: readonly (readonly string[])[];
+  targetBlockIds: readonly string[];
+} |
+/** A whole table the target dropped. */
+{
+  kind: "table-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  rows: readonly (readonly string[])[];
+  baseBlockIds: readonly string[];
+} | {
+  kind: "table-row-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Row index in the base document's table. */
+  rowIndex: number;
+  cells: readonly string[];
+  baseBlockIds: readonly string[];
+} | {
+  kind: "table-column-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Grid-column index in the target table. */
+  columnIndex: number;
+  /** Newly created physical-cell text in row order. */
+  cells: readonly string[];
+  targetBlockIds: readonly string[];
+} | {
+  kind: "table-column-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Grid-column index in the base table. */
+  columnIndex: number;
+  cells: readonly string[];
+  baseBlockIds: readonly string[];
+};
+/** Why a part of the package is absent from `changes`. */
+declare const COMPARE_UNSUPPORTED_REASONS: readonly ["story-missing-in-base", "story-missing-in-target", "story-not-editable"];
+type CompareUnsupportedReason = (typeof COMPARE_UNSUPPORTED_REASONS)[number];
+/**
+ * A package part the comparison did not cover. Reported rather than dropped so
+ * a caller can tell "no differences" from "not looked at".
+ */
+type CompareUnsupportedPart = {
+  reason: CompareUnsupportedReason;
+  baseStory: FolioDocumentStoryHandle | null;
+  targetStory: FolioDocumentStoryHandle | null;
+};
+type CompareResult = {
+  /** The base package carrying the generated tracked changes. */
+  buffer: ArrayBuffer;
+  changes: readonly CompareChange[];
+  /**
+   * Whether the round trip was proven. Always `verified` unless the call asked
+   * for `onUnverified: "emit"`, which is the only way an unproven redline is
+   * returned at all.
+   */
+  verification: CompareVerification;
+  unsupported: readonly CompareUnsupportedPart[];
+};
+declare const InvalidCompareDocxOptionsError_base: import("better-result").TaggedErrorClass<"InvalidCompareDocxOptionsError">;
+declare class InvalidCompareDocxOptionsError extends InvalidCompareDocxOptionsError_base<{
+  message: string;
+  option: "timestamp";
+  receivedValue: unknown;
+}> {}
+declare const CompareDocxParseError_base: import("better-result").TaggedErrorClass<"CompareDocxParseError">;
+declare class CompareDocxParseError extends CompareDocxParseError_base<{
+  message: string;
+  side: "base" | "target";
+  cause: unknown;
+}> {}
+declare const CompareDocxApplyError_base: import("better-result").TaggedErrorClass<"CompareDocxApplyError">;
+/**
+ * The applier refused at least one derived operation, so accepting the result
+ * would not reproduce the target. Reported instead of returning a package that
+ * silently under-represents the difference.
+ */
+declare class CompareDocxApplyError extends CompareDocxApplyError_base<{
+  message: string;
+  skipped: readonly FolioAIEditSkippedOperation[];
+}> {}
+declare const CompareDocxRoundTripError_base: import("better-result").TaggedErrorClass<"CompareDocxRoundTripError">;
+/**
+ * The generated tracked changes do not accept back to the target. Raised by
+ * the self-check {@link compareDocx} runs before returning: a redline that
+ * quietly loses part of the difference is worse than no redline, so the
+ * mismatch is surfaced instead of the document.
+ */
+declare class CompareDocxRoundTripError extends CompareDocxRoundTripError_base<{
+  message: string;
+  story: FolioDocumentStoryHandle;
+  /** The invariant that did not hold, and what diverged under it. */
+  invariant: CompareVerificationInvariant;
+  cause: CompareVerificationCause;
+  /**
+   * Every invariant that failed, not only the one named above: a redline that
+   * loses a difference usually loses it in both directions, and a caller
+   * deciding what to do next wants the whole list. Each detail is structural,
+   * so it is safe to log or quote.
+   */
+  failures: readonly CompareVerificationFailure[];
+}> {}
+declare const CompareDocxOperationLimitError_base: import("better-result").TaggedErrorClass<"CompareDocxOperationLimitError">;
+/** The difference needs more operations than the engine will generate. */
+declare class CompareDocxOperationLimitError extends CompareDocxOperationLimitError_base<{
+  message: string;
+  limit: number;
+}> {}
+declare const CompareDocxSerializeError_base: import("better-result").TaggedErrorClass<"CompareDocxSerializeError">;
+declare class CompareDocxSerializeError extends CompareDocxSerializeError_base<{
+  message: string;
+  cause: unknown;
+}> {}
+type CompareDocxError = CompareDocxApplyError | CompareDocxOperationLimitError | CompareDocxParseError | CompareDocxRoundTripError | CompareDocxSerializeError | InvalidCompareDocxOptionsError;
+//#endregion
+export { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError };