@stll/folio-core 0.32.2 → 0.33.1

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

@@ -0,0 +1,21 @@
+//#region src/compare/reproducible-package.d.ts
+/**
+ * The last two clocks in the compare path are outside the document body.
+ *
+ * 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.
+ *
+ * The save also stamps `dcterms:modified` in `docProps/core.xml` from the wall
+ * clock, which is the same failure one part deeper: two runs over identical
+ * inputs differ in that part alone.
+ *
+ * Restamping both from the comparison's own timestamp removes them. 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,47 @@
+import JSZip from "jszip";
+//#region src/compare/reproducible-package.ts
+/**
+* The last two clocks in the compare path are outside the document body.
+*
+* 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.
+*
+* The save also stamps `dcterms:modified` in `docProps/core.xml` from the wall
+* clock, which is the same failure one part deeper: two runs over identical
+* inputs differ in that part alone.
+*
+* Restamping both from the comparison's own timestamp removes them. 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 CORE_PROPERTIES_PATH = "docProps/core.xml";
+const MODIFIED_ELEMENT = /<dcterms:modified[^<>]*>[^<]*<\/dcterms:modified>/u;
+/**
+* Rewrite `dcterms:modified` where the save already wrote one. An absent
+* element stays absent: the comparison edits the document it was handed, and
+* synthesizing metadata the input never carried is a different decision.
+*/
+const withFixedModifiedDate = (corePropsXml, date) => corePropsXml.replace(MODIFIED_ELEMENT, `<dcterms:modified xsi:type="dcterms:W3CDTF">${date.toISOString()}</dcterms:modified>`);
+const withFixedPackageDates = async (buffer, date) => {
+	const zip = await JSZip.loadAsync(buffer);
+	const coreProps = zip.file(CORE_PROPERTIES_PATH);
+	if (coreProps) zip.file(CORE_PROPERTIES_PATH, withFixedModifiedDate(await coreProps.async("text"), date), {
+		compression: "DEFLATE",
+		compressionOptions: { level: DOCX_COMPRESSION_LEVEL }
+	});
+	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 };