@stll/folio-core 0.32.2 → 0.33.1

package/dist/compare/__fixtures__/numbered-list.js

@@ -0,0 +1,85 @@
+import JSZip from "jszip";
+//#region src/compare/__fixtures__/numbered-list.ts
+/**
+* A small multi-level numbered list, authored here rather than committed as
+* bytes.
+*
+* The corpus fixtures carry no numbering at all, so a probe that says "an added
+* list item" while editing an unnumbered paragraph is testing something else
+* and saying it is testing numbering. Generating the package keeps its content
+* legible in the diff and keeps the provenance trivial.
+*/
+const NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+const RELATIONSHIPS = "http://schemas.openxmlformats.org/package/2006/relationships";
+const OFFICE_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const WORDPROCESSING = "application/vnd.openxmlformats-officedocument.wordprocessingml";
+/**
+* `createFolders: false` because JSZip stamps the folder entries it
+* synthesizes with `new Date()`, which the fixed date above does not reach.
+*/
+const ZIP_ENTRY_OPTIONS = {
+	date: new Date(Date.UTC(2e3, 0, 1)),
+	createFolders: false
+};
+const LIST_LEVELS = 3;
+const abstractLevels = (topLevelFormat) => Array.from({ length: LIST_LEVELS }, (_unused, level) => {
+	return `<w:lvl w:ilvl="${String(level)}"><w:start w:val="1"/><w:numFmt w:val="${level === 0 ? topLevelFormat : "lowerLetter"}"/><w:lvlText w:val="%${String(level + 1)}."/><w:lvlJc w:val="left"/></w:lvl>`;
+}).join("");
+const listParagraph = (level, text) => {
+	return `<w:p><w:pPr><w:pStyle w:val="ListParagraph"/>${level === null ? "" : `<w:numPr><w:ilvl w:val="${String(level)}"/><w:numId w:val="1"/></w:numPr>`}</w:pPr><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>`;
+};
+const NUMBERED_LIST_ITEMS = Object.freeze([
+	{
+		level: 0,
+		text: "The supplier shall deliver the goods to the named place."
+	},
+	{
+		level: 1,
+		text: "Delivery is complete on unloading at that place."
+	},
+	{
+		level: 1,
+		text: "Risk passes to the buyer on completion of delivery."
+	},
+	{
+		level: 0,
+		text: "The buyer shall pay within thirty days of the invoice date."
+	},
+	{
+		level: 1,
+		text: "Late payment carries interest at the statutory rate."
+	},
+	{
+		level: 0,
+		text: "Either party may terminate for material breach."
+	}
+]);
+/** The same list with one item demoted one level: a level change and no text change. */
+const withItemDemoted = (items, index) => items.map((item, at) => at === index ? {
+	level: Math.min(LIST_LEVELS - 1, (item.level ?? 0) + 1),
+	text: item.text
+} : item);
+/**
+* The same list with one item no longer numbered: the paragraph keeps every
+* word and stops being a list item, which is the edit a level change cannot
+* express.
+*/
+const withItemUnnumbered = (items, index) => items.map((item, at) => at === index ? {
+	level: null,
+	text: item.text
+} : item);
+const buildNumberedListDocx = async (items = NUMBERED_LIST_ITEMS, { format = "decimal" } = {}) => {
+	const parts = {
+		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="${WORDPROCESSING}.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="${WORDPROCESSING}.styles+xml"/><Override PartName="/word/numbering.xml" ContentType="${WORDPROCESSING}.numbering+xml"/></Types>`,
+		"_rels/.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/officeDocument" Target="word/document.xml"/></Relationships>`,
+		"word/_rels/document.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${RELATIONSHIPS}"><Relationship Id="rId1" Type="${OFFICE_RELATIONSHIPS}/styles" Target="styles.xml"/><Relationship Id="rId2" Type="${OFFICE_RELATIONSHIPS}/numbering" Target="numbering.xml"/></Relationships>`,
+		"word/styles.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="${NAMESPACE}"><w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style><w:style w:type="paragraph" w:styleId="ListParagraph"><w:name w:val="List Paragraph"/></w:style></w:styles>`,
+		"word/numbering.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:numbering xmlns:w="${NAMESPACE}"><w:abstractNum w:abstractNumId="0">${abstractLevels(format)}</w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num></w:numbering>`,
+		"word/document.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${NAMESPACE}"><w:body>` + items.map(({ level, text }) => listParagraph(level, text)).join("") + "<w:sectPr><w:pgSz w:w=\"12240\" w:h=\"15840\"/><w:pgMar w:top=\"1440\" w:right=\"1440\" w:bottom=\"1440\" w:left=\"1440\"/></w:sectPr></w:body></w:document>"
+	};
+	const zip = new JSZip();
+	for (const name of Object.keys(parts).toSorted()) zip.file(name, parts[name] ?? "", ZIP_ENTRY_OPTIONS);
+	return await zip.generateAsync({ type: "arraybuffer" });
+};
+//#endregion
+export { NUMBERED_LIST_ITEMS, buildNumberedListDocx, withItemDemoted, withItemUnnumbered };

package/dist/compare/column-alignment.d.ts

@@ -0,0 +1,27 @@
+import { FolioAIBlock, FolioAIBlockTableLocation } from "../ai-edits/types.js";
+//#region src/compare/column-alignment.d.ts
+type TableColumnAlignmentStep = {
+  type: "baseColumn";
+  blocks: readonly FolioAIBlock[];
+  location: FolioAIBlockTableLocation;
+  columnIndex: number;
+} | {
+  type: "targetColumn";
+  blocks: readonly FolioAIBlock[];
+  location: FolioAIBlockTableLocation;
+  columnIndex: number;
+  anchor: {
+    blockId: string;
+    position: "after" | "before";
+  };
+};
+type TableColumnAlignment = {
+  steps: TableColumnAlignmentStep[];
+  baseBlocks: FolioAIBlock[];
+  targetBlocks: FolioAIBlock[];
+  baseColumnKeys: ReadonlyMap<number, number>;
+  targetColumnKeys: ReadonlyMap<number, number>;
+};
+declare const alignTableColumns: (baseBlocks: readonly FolioAIBlock[], targetBlocks: readonly FolioAIBlock[]) => TableColumnAlignment | null;
+//#endregion
+export { TableColumnAlignment, TableColumnAlignmentStep, alignTableColumns };

package/dist/compare/column-alignment.js

@@ -0,0 +1,162 @@
+import { panic } from "better-result";
+//#region src/compare/column-alignment.ts
+const MAX_TABLE_GRID_COLUMNS = 63;
+const MAX_TABLE_GRID_AREA = 1e6;
+const tableGridColumns = (blocks) => {
+	const cellsByPhysicalLocation = /* @__PURE__ */ new Map();
+	let width = 0;
+	let height = 0;
+	for (const block of blocks) {
+		const location = block.table;
+		if (!location) return null;
+		const key = `${String(location.rowIndex)}:${String(location.cellIndex)}`;
+		const existing = cellsByPhysicalLocation.get(key);
+		if (existing) {
+			existing.blocks.push(block);
+			continue;
+		}
+		const right = location.gridColumnIndex + location.columnSpan;
+		const bottom = location.rowIndex + location.rowSpan;
+		if (location.gridColumnIndex < 0 || location.rowIndex < 0 || location.columnSpan < 1 || location.rowSpan < 1 || right > MAX_TABLE_GRID_COLUMNS) return null;
+		cellsByPhysicalLocation.set(key, {
+			blocks: [block],
+			rowIndex: location.rowIndex,
+			gridColumnIndex: location.gridColumnIndex,
+			columnSpan: location.columnSpan,
+			rowSpan: location.rowSpan
+		});
+		width = Math.max(width, right);
+		height = Math.max(height, bottom);
+	}
+	if (width === 0 || height === 0 || width * height > MAX_TABLE_GRID_AREA) return null;
+	const grid = Array.from({ length: height }, () => Array.from({ length: width }));
+	const ownedCellsByColumn = Array.from({ length: width }, () => []);
+	for (const cell of cellsByPhysicalLocation.values()) {
+		ownedCellsByColumn[cell.gridColumnIndex]?.push(cell);
+		for (let row = cell.rowIndex; row < cell.rowIndex + cell.rowSpan; row++) for (let column = cell.gridColumnIndex; column < cell.gridColumnIndex + cell.columnSpan; column++) {
+			const gridRow = grid[row];
+			if (!gridRow || gridRow[column] !== void 0) return null;
+			gridRow[column] = cell;
+		}
+	}
+	return Array.from({ length: width }, (_unused, columnIndex) => {
+		const structuralRows = grid.map((row) => {
+			const cell = row[columnIndex];
+			return cell ? [
+				columnIndex - cell.gridColumnIndex,
+				cell.columnSpan,
+				cell.rowIndex,
+				cell.rowSpan,
+				cell.blocks.map(({ text }) => text)
+			] : null;
+		});
+		return {
+			index: columnIndex,
+			signature: JSON.stringify(structuralRows),
+			ownedCells: ownedCellsByColumn[columnIndex] ?? []
+		};
+	});
+};
+/** The sole exact ordered embedding of `shorter` in `wider`, or null when ambiguous. */
+const uniqueColumnEmbedding = (shorter, wider) => {
+	const counts = Array.from({ length: shorter.length + 1 }, () => Array.from({ length: wider.length + 1 }, () => 0));
+	for (let wideIndex = 0; wideIndex <= wider.length; wideIndex++) {
+		const finalRow = counts[shorter.length];
+		if (finalRow) finalRow[wideIndex] = 1;
+	}
+	for (let shortIndex = shorter.length - 1; shortIndex >= 0; shortIndex--) for (let wideIndex = wider.length - 1; wideIndex >= 0; wideIndex--) {
+		const skip = counts[shortIndex]?.[wideIndex + 1] ?? 0;
+		const match = shorter[shortIndex]?.signature === wider[wideIndex]?.signature ? counts[shortIndex + 1]?.[wideIndex + 1] ?? 0 : 0;
+		const row = counts[shortIndex];
+		if (row) row[wideIndex] = Math.min(2, skip + match);
+	}
+	if (counts[0]?.[0] !== 1) return null;
+	const mapping = [];
+	let shortIndex = 0;
+	let wideIndex = 0;
+	while (shortIndex < shorter.length) {
+		if (wideIndex >= wider.length) return panic("A unique column embedding ended before every column was mapped");
+		const canMatch = shorter[shortIndex]?.signature === wider[wideIndex]?.signature && (counts[shortIndex + 1]?.[wideIndex + 1] ?? 0) > 0;
+		const canSkip = (counts[shortIndex]?.[wideIndex + 1] ?? 0) > 0;
+		if (canMatch && !canSkip) {
+			mapping.push(wideIndex);
+			shortIndex += 1;
+		}
+		wideIndex += 1;
+	}
+	return mapping;
+};
+const columnOwnedBlocks = ({ ownedCells }) => {
+	if (ownedCells.length === 0 || ownedCells.some(({ columnSpan }) => columnSpan !== 1)) return null;
+	return ownedCells.flatMap(({ blocks }) => blocks);
+};
+const alignTableColumns = (baseBlocks, targetBlocks) => {
+	const baseColumns = tableGridColumns(baseBlocks);
+	const targetColumns = tableGridColumns(targetBlocks);
+	if (!baseColumns || !targetColumns || baseColumns.length === targetColumns.length) return null;
+	const targetIsWider = targetColumns.length > baseColumns.length;
+	const mapping = uniqueColumnEmbedding(targetIsWider ? baseColumns : targetColumns, targetIsWider ? targetColumns : baseColumns);
+	if (!mapping) return null;
+	const widerColumns = targetIsWider ? targetColumns : baseColumns;
+	const mapped = new Set(mapping);
+	const unmatchedColumns = widerColumns.filter((_column, index) => !mapped.has(index));
+	const ownedColumns = [];
+	for (const column of unmatchedColumns) {
+		const blocks = columnOwnedBlocks(column);
+		if (!blocks) return null;
+		ownedColumns.push({
+			column,
+			blocks
+		});
+	}
+	if (ownedColumns.length === 0 || targetIsWider && unmatchedColumns.some(({ ownedCells }) => ownedCells.some(({ rowSpan }) => rowSpan !== 1))) return null;
+	const unmatchedIds = new Set(ownedColumns.flatMap(({ blocks }) => blocks.map(({ id }) => id)));
+	const baseColumnKeys = /* @__PURE__ */ new Map();
+	const targetColumnKeys = /* @__PURE__ */ new Map();
+	mapping.forEach((wideIndex, shortIndex) => {
+		if (targetIsWider) {
+			baseColumnKeys.set(shortIndex, shortIndex);
+			targetColumnKeys.set(wideIndex, shortIndex);
+		} else {
+			baseColumnKeys.set(wideIndex, shortIndex);
+			targetColumnKeys.set(shortIndex, shortIndex);
+		}
+	});
+	const steps = [];
+	if (!targetIsWider) for (const { column, blocks } of ownedColumns) {
+		const location = blocks.at(0)?.table;
+		if (!location) return null;
+		steps.push({
+			type: "baseColumn",
+			blocks,
+			location,
+			columnIndex: column.index
+		});
+	}
+	else for (const { column, blocks } of ownedColumns) {
+		const location = blocks.at(0)?.table;
+		const rightBaseIndex = mapping.findIndex((targetIndex) => targetIndex > column.index);
+		const leftBaseIndex = mapping.findLastIndex((targetIndex) => targetIndex < column.index);
+		const anchorBlock = (rightBaseIndex >= 0 ? baseColumns[rightBaseIndex] : baseColumns[leftBaseIndex])?.ownedCells.at(0)?.blocks.at(0);
+		if (!location || !anchorBlock) return null;
+		steps.push({
+			type: "targetColumn",
+			blocks,
+			location,
+			columnIndex: column.index,
+			anchor: {
+				blockId: anchorBlock.id,
+				position: rightBaseIndex >= 0 ? "before" : "after"
+			}
+		});
+	}
+	return {
+		steps,
+		baseBlocks: baseBlocks.filter(({ id }) => targetIsWider || !unmatchedIds.has(id)),
+		targetBlocks: targetBlocks.filter(({ id }) => !targetIsWider || !unmatchedIds.has(id)),
+		baseColumnKeys,
+		targetColumnKeys
+	};
+};
+//#endregion
+export { alignTableColumns };

package/dist/compare/compare.d.ts

@@ -0,0 +1,107 @@
+import { FolioAIEditSnapshot } from "../ai-edits/types.js";
+import { WordDiffGranularity } from "../ai-edits/word-diff.js";
+import { FolioRevisionStamp } from "../ai-edits/apply.js";
+import { FolioDocumentStoryHandle, FolioDocxReviewer } from "../ai-edits/headless.js";
+import { CompareVerification } from "./verification.js";
+import { CompareChange, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
+import { CompareStoryPlan } from "./plan.js";
+import { Result } from "better-result";
+//#region src/compare/compare.d.ts
+/**
+ * Cap on operations one comparison generates. Both inputs are untrusted
+ * documents, and each operation costs a document walk plus revision ids.
+ */
+declare const MAX_COMPARE_OPERATIONS = 10000;
+/** Two stories the comparison will align against one another. */
+type ComparedStoryPair = {
+  baseStory: FolioDocumentStoryHandle;
+  targetStory: FolioDocumentStoryHandle;
+  baseSnapshot: FolioAIEditSnapshot;
+  targetSnapshot: FolioAIEditSnapshot;
+};
+/** Everything the later stages need, and nothing they have to re-derive. */
+type ParsedComparison = {
+  /** Token size a changed paragraph's redline is cut at. */
+  granularity: WordDiffGranularity;
+  /**
+   * The base package as it arrived. It is the result when nothing changed, but
+   * only when it carried no revisions of its own: otherwise the compared base
+   * is its accepted view and these bytes are a different document.
+   */
+  baseBuffer: ArrayBuffer;
+  baseCarriedRevisions: boolean;
+  reviewer: FolioDocxReviewer;
+  targetReviewer: FolioDocxReviewer;
+  revisionStamp: FolioRevisionStamp;
+  packageDate: Date;
+  pairs: readonly ComparedStoryPair[];
+  /** Package-level numbering differences, which belong to no story. */
+  numberingChanges: readonly CompareChange[];
+  unsupported: readonly CompareUnsupportedPart[];
+};
+/** Stage 1: both packages to editor models, paired story by story. */
+declare const parseComparison: (base: ArrayBuffer, target: ArrayBuffer, options: CompareDocxOptions) => Promise<Result<ParsedComparison, CompareDocxParseError | InvalidCompareDocxOptionsError>>;
+/** One story's plan, kept with the pair it belongs to. */
+type PlannedStoryComparison = {
+  pair: ComparedStoryPair;
+  plan: CompareStoryPlan;
+};
+/**
+ * Stage 2: align every paired story and derive its operations. Pure — no
+ * parsing, no serialization, no clock.
+ */
+declare const planComparison: ({ pairs }: ParsedComparison) => Result<readonly PlannedStoryComparison[], CompareDocxOperationLimitError>;
+/** What stage 3 produced: the change list, and whether it was proven. */
+type AppliedComparison = {
+  changes: readonly CompareChange[];
+  verification: CompareVerification;
+};
+/**
+ * Stage 3: write the planned operations into the base document as tracked
+ * changes, then check the work rather than trust it. Both directions of the
+ * round trip are checked, structure included: accepting the story's generated
+ * revisions must reproduce the target, and rejecting them must reproduce the
+ * base it was compared from. A difference the operation vocabulary cannot
+ * express would otherwise leave a redline that reads plausibly and is wrong.
+ *
+ * The check reports rather than throws. {@link compareDocx} decides what to do
+ * with an unverified result, because "give me your best attempt and tell me
+ * what you could not represent" and "give me nothing unless you can prove it"
+ * are both legitimate asks and only the caller knows which one it is making.
+ */
+declare const applyComparison: ({ reviewer, revisionStamp, granularity, numberingChanges }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError>;
+/**
+ * Stage 4: the result package, with every ZIP entry date pinned.
+ *
+ * A comparison that found nothing returns the base bytes as they arrived. A
+ * change is only ever reported alongside the operations that realize it, so no
+ * operations means no changes, and re-serializing then rewrites a document
+ * nobody edited: on a 2,200-block pair that was a second of work to reproduce
+ * the input.
+ *
+ * Unless the base carried revisions of its own. Then the compared base was its
+ * accepted view, the arriving bytes are a different document, and handing them
+ * back would make rejecting the result land before the previous reviewer's
+ * edits rather than after them.
+ *
+ * The short-circuit lives here rather than in {@link compareDocx} so that
+ * every caller of the stages sees the same decision. Putting it in the
+ * composition let the benchmark's own composition disagree with the shipped
+ * one within a single run.
+ */
+declare const serializeComparison: ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Promise<Result<ArrayBuffer, CompareDocxSerializeError | CompareDocxFinalParagraphMarkError>>;
+/**
+ * Compare `base` against `target` and return `base` carrying the tracked
+ * changes that turn it into `target`, alongside the change list describing
+ * them.
+ *
+ * The result is verified by default: a redline whose round trip cannot be
+ * proven is refused rather than returned, because one that reads plausibly and
+ * is wrong is worse than none. `onUnverified: "emit"` asks for the opposite
+ * trade — the best redline available, plus the typed list of what could not be
+ * represented — for a caller that would rather show something and say what is
+ * missing.
+ */
+declare const compareDocx: (base: ArrayBuffer, target: ArrayBuffer, options: CompareDocxOptions) => Promise<Result<CompareResult, CompareDocxError>>;
+//#endregion
+export { AppliedComparison, ComparedStoryPair, MAX_COMPARE_OPERATIONS, ParsedComparison, PlannedStoryComparison, applyComparison, compareDocx, parseComparison, planComparison, serializeComparison };