@stll/folio-core 0.33.1 → 0.34.0

package/dist/compare/compare.js

@@ -1,10 +1,11 @@
 import { FolioDocxReviewer } from "../ai-edits/headless.js";
+import { projectTableGeometry } from "../ai-edits/table-geometry.js";
 import "../document-operations.js";
 import { pairFolioDocumentStories } from "../document-stories.js";
 import { planStoryCompare } from "./plan.js";
 import { withFixedPackageDates } from "./reproducible-package.js";
 import { CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "./types.js";
-import { classifyProjectionMismatch, deletedFinalParagraphMarks, projectSupportedInlineFormatting } from "./verification.js";
+import { classifyGeometryMismatch, classifyProjectionMismatch, projectSupportedInlineFormatting, revisedFinalParagraphMarks } from "./verification.js";
 import { Result, panic } from "better-result";
 //#region src/compare/compare.ts
 /**
@@ -151,6 +152,14 @@ const parseComparison = async (base, target, options) => {
 	const reviewer = baseParse.value;
 	const targetReviewer = targetParse.value;
 	const existing = existingRevisionsOf(reviewer);
+	for (const { handle } of reviewer.listStories()) reviewer.resolveReviewedStory({
+		story: handle,
+		view: "final"
+	});
+	for (const { handle } of targetReviewer.listStories()) targetReviewer.resolveReviewedStory({
+		story: handle,
+		view: "final"
+	});
 	const pairs = [];
 	const unsupported = [];
 	for (const { baseStory, revisedStory: targetStory } of pairFolioDocumentStories(reviewer.listStories().map(({ handle }) => handle), targetReviewer.listStories().map(({ handle }) => handle))) {
@@ -170,14 +179,6 @@ const parseComparison = async (base, target, options) => {
 			});
 			continue;
 		}
-		reviewer.resolveReviewedStory({
-			story: baseStory,
-			view: "final"
-		});
-		targetReviewer.resolveReviewedStory({
-			story: targetStory,
-			view: "final"
-		});
 		const baseSnapshot = reviewer.snapshotStory(baseStory);
 		const targetSnapshot = targetReviewer.snapshotStory(targetStory);
 		if (!baseSnapshot || !targetSnapshot) {
@@ -236,50 +237,126 @@ const planComparison = ({ pairs }) => {
 	return Result.ok(planned);
 };
 /**
+* What a skipped operation says about the plan that derived it.
+*
+* Two different things go wrong at apply time, and only one of them leaves the
+* result unusable. A reason that says the plan did not match the document it
+* was planned against is an engine defect — the operations came from this very
+* snapshot moments earlier, so nothing should have moved under them, and a
+* redline built on the rest is built on a document the plan no longer
+* describes. A reason that says the applier had nothing to write, or could not
+* write that shape THERE, leaves the redline standing and turns the question
+* into "was anything lost", which is what the round-trip check answers a few
+* lines below. Refusing on those instead trades a partial answer for none, and
+* refuses a whole document because one paragraph sits inside a structure the
+* block snapshot does not model — a text box, a content control — where a
+* paragraph mark has nowhere to go.
+*/
+const COMPARE_SKIP_DISPOSITION = {
+	missingBlock: "fatal",
+	changedBlock: "fatal",
+	ambiguousFind: "fatal",
+	missingFind: "fatal",
+	unsupportedBlock: "unwritable",
+	unsupportedMode: "fatal",
+	atomicBatchRejected: "fatal",
+	preconditionFailed: "fatal",
+	staleRange: "fatal",
+	emptyOperation: "unwritable",
+	noopOperation: "unwritable",
+	documentVersionMismatch: "fatal",
+	documentNotEditable: "fatal"
+};
+/**
+* The table each `insertTable` / `insertTableRow` in the plan should place,
+* resolved against the target document the plan named it in.
+*
+* The plan is pure and names a table by index; the node lives in the other
+* package, which only this stage holds. A request naming a table the target
+* does not have resolves to nothing and the operation falls back to its cell
+* texts, which is the same redline the comparison produced before.
+*/
+const resolveTableTemplates = (targetTables, requests) => {
+	const templates = /* @__PURE__ */ new Map();
+	for (const { operationId, targetTableIndex, targetRowIndex } of requests) {
+		const table = targetTables.get(targetTableIndex);
+		if (!table) continue;
+		if (targetRowIndex === void 0) {
+			templates.set(operationId, table);
+			continue;
+		}
+		const row = table.maybeChild(targetRowIndex);
+		if (row) templates.set(operationId, row);
+	}
+	return templates;
+};
+/**
 * 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.
+* round trip are checked, structure and table geometry 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.
 */
-const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChanges }, planned) => {
+const applyComparison = ({ reviewer, targetReviewer, revisionStamp, granularity, numberingChanges }, planned) => {
 	const changes = [...numberingChanges];
 	const failures = [];
 	let idSeed = revisionStamp.idSeed;
+	let documentChanged = false;
 	for (const { pair, plan } of planned) {
 		changes.push(...plan.changes);
-		if (plan.operations.length === 0) continue;
+		if (plan.operations.length === 0 && plan.tableGeometryPairings.length === 0) continue;
 		const baseBeforeBlocks = reviewer.readReviewedStory({
 			story: pair.baseStory,
 			view: "final"
 		})?.snapshot.blocks ?? [];
 		const baseBefore = projectBlocks(baseBeforeBlocks);
-		const { skipped, nextRevisionId } = reviewer.applyDocumentOperationsToStory({
+		const baseBeforeGeometry = projectTableGeometry(reviewer.storyTables({ story: pair.baseStory }));
+		const targetTables = new Map(targetReviewer.storyTables({ story: pair.targetStory }).map(({ index, node }) => [index, node]));
+		const afterGeometry = reviewer.matchStoryTableGeometry({
 			story: pair.baseStory,
-			snapshot: pair.baseSnapshot,
+			targetTables,
+			pairings: plan.tableGeometryPairings,
 			revisionStamp: {
 				date: revisionStamp.date,
 				idSeed
-			},
-			wordDiff: { granularity },
-			batch: {
-				version: 1,
-				mode: "tracked-changes",
-				operations: plan.operations
 			}
 		});
-		if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
-		idSeed = nextRevisionId;
-		if (skipped.length > 0) return Result.err(new CompareDocxApplyError({
-			message: "Some derived operations were refused, so the result would not match the target.",
-			skipped
-		}));
+		const geometryChanged = afterGeometry > idSeed;
+		documentChanged ||= geometryChanged;
+		idSeed = afterGeometry;
+		if (plan.operations.length === 0 && !geometryChanged) continue;
+		if (plan.operations.length > 0) {
+			const { skipped, nextRevisionId } = reviewer.applyDocumentOperationsToStory({
+				story: pair.baseStory,
+				snapshot: pair.baseSnapshot,
+				revisionStamp: {
+					date: revisionStamp.date,
+					idSeed
+				},
+				wordDiff: { granularity },
+				batch: {
+					version: 1,
+					mode: "tracked-changes",
+					operations: plan.operations
+				},
+				tableTemplates: resolveTableTemplates(targetTables, plan.tableTemplates)
+			});
+			if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
+			idSeed = nextRevisionId;
+			documentChanged = true;
+			const refused = skipped.filter(({ reason }) => COMPARE_SKIP_DISPOSITION[reason] === "fatal");
+			if (refused.length > 0) return Result.err(new CompareDocxApplyError({
+				message: "Some derived operations were refused, so the result would not match the target.",
+				skipped: refused
+			}));
+		}
 		const acceptedStory = reviewer.readReviewedStory({
 			story: pair.baseStory,
 			view: "final"
@@ -324,13 +401,34 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChange
 			});
 			if (formattingFailure) failures.push(formattingFailure);
 		}
+		const geometryAcceptFailure = classifyGeometryMismatch({
+			invariant: "accept-reproduces-target",
+			story: pair.baseStory,
+			actual: projectTableGeometry(reviewer.storyTables({
+				story: pair.baseStory,
+				view: "final"
+			})),
+			expected: projectTableGeometry(targetReviewer.storyTables({ story: pair.targetStory }))
+		});
+		if (geometryAcceptFailure) failures.push(geometryAcceptFailure);
+		const geometryRejectFailure = classifyGeometryMismatch({
+			invariant: "reject-reproduces-base",
+			story: pair.baseStory,
+			actual: projectTableGeometry(reviewer.storyTables({
+				story: pair.baseStory,
+				view: "original"
+			})),
+			expected: baseBeforeGeometry
+		});
+		if (geometryRejectFailure) failures.push(geometryRejectFailure);
 	}
 	return Result.ok({
 		changes,
 		verification: failures.length === 0 ? { status: "verified" } : {
 			status: "unverified",
 			failures
-		}
+		},
+		documentChanged
 	});
 };
 /**
@@ -352,13 +450,13 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, numberingChange
 * composition let the benchmark's own composition disagree with the shipped
 * one within a single run.
 */
-const serializeComparison = async ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate }, planned) => {
-	if (!baseCarriedRevisions && planned.every(({ plan }) => plan.operations.length === 0)) return Result.ok(baseBuffer);
-	const deletions = deletedFinalParagraphMarks(reviewer.toDocument());
-	const [firstDeletion] = deletions;
-	if (firstDeletion !== void 0) return Result.err(new CompareDocxFinalParagraphMarkError({
-		message: `A container's final paragraph mark carries a ${firstDeletion.kind}, which no consumer can resolve: ${firstDeletion.container} paragraph ${String(firstDeletion.paragraphIndex)}.`,
-		deletions
+const serializeComparison = async ({ baseBuffer, baseCarriedRevisions, reviewer, packageDate, revisionStamp }, { documentChanged }) => {
+	if (!baseCarriedRevisions && !documentChanged) return Result.ok(baseBuffer);
+	const revisions = revisedFinalParagraphMarks(reviewer.toDocument(), { since: revisionStamp.idSeed });
+	const [first] = revisions;
+	if (first !== void 0) return Result.err(new CompareDocxFinalParagraphMarkError({
+		message: `A container's final paragraph mark carries a ${first.kind}, which no consumer can resolve: ${first.container} paragraph ${String(first.paragraphIndex)}.`,
+		revisions
 	}));
 	return await Result.tryPromise({
 		try: async () => await withFixedPackageDates(await reviewer.toBuffer(), packageDate),
@@ -399,7 +497,7 @@ const compareDocx = async (base, target, options) => {
 			failures: verification.failures
 		}));
 	}
-	const serialized = await serializeComparison(parsed.value, planned.value);
+	const serialized = await serializeComparison(parsed.value, applied.value);
 	if (serialized.isErr()) return Result.err(serialized.error);
 	return Result.ok({
 		buffer: serialized.value,

package/dist/compare/formatting.d.ts

@@ -15,7 +15,7 @@ type InlineFormattingSegmentsOptions = {
   maxSegments: number;
 };
 /**
- * Segments where `targetBlock`'s bold / italic / underline / strike differs from
+ * Segments where `targetBlock`'s supported run formatting differs from
  * `baseBlock`'s, for two blocks that carry the same text. Returns `null` only
  * when the diff would exceed `maxSegments`.
  *

package/dist/compare/formatting.js

@@ -1,12 +1,41 @@
+import { resolveColorToHex } from "../utils/colorResolver.js";
 //#region src/compare/formatting.ts
-const changedSupportedFormatting = (base, target) => ({
-	...Boolean(base.bold) !== Boolean(target.bold) && { bold: Boolean(target.bold) },
-	...Boolean(base.italic) !== Boolean(target.italic) && { italic: Boolean(target.italic) },
-	...Boolean(base.underline) !== Boolean(target.underline) && { underline: Boolean(target.underline) },
-	...Boolean(base.strike) !== Boolean(target.strike) && { strike: Boolean(target.strike) }
-});
-const sameInlineFormatting = (left, right) => left.bold === right.bold && left.italic === right.italic && left.underline === right.underline && left.strike === right.strike;
-const hasInlineFormatting = (formatting) => formatting.bold !== void 0 || formatting.italic !== void 0 || formatting.underline !== void 0 || formatting.strike !== void 0;
+const normalizeInlineFormattingColor = (color) => resolveColorToHex(color === void 0 ? void 0 : { rgb: color }, null);
+const changedStringValue = (baseEffective, targetEffective, baseAuthored, targetAuthored) => {
+	if (baseAuthored !== targetAuthored) return targetAuthored ?? null;
+	return baseEffective === targetEffective ? void 0 : targetEffective ?? null;
+};
+const changedNumberValue = (baseEffective, targetEffective, baseAuthored, targetAuthored) => {
+	if (baseAuthored !== targetAuthored) return targetAuthored ?? null;
+	return baseEffective === targetEffective ? void 0 : targetEffective ?? null;
+};
+const changedSupportedFormatting = (base, target) => {
+	const baseDirect = base.directFormatting ?? {};
+	const targetDirect = target.directFormatting ?? {};
+	const formatting = {};
+	const changedBoolean = (property) => {
+		if (baseDirect[property] !== targetDirect[property]) return targetDirect[property] === true;
+		return Boolean(base[property]) === Boolean(target[property]) ? void 0 : Boolean(target[property]);
+	};
+	for (const property of [
+		"bold",
+		"italic",
+		"underline",
+		"strike"
+	]) {
+		const changed = changedBoolean(property);
+		if (changed !== void 0) formatting[property] = changed;
+	}
+	const fontFamily = changedStringValue(base.fontFamily, target.fontFamily, baseDirect.fontFamily, targetDirect.fontFamily);
+	if (fontFamily !== void 0) formatting.fontFamily = fontFamily;
+	const fontSizePt = changedNumberValue(base.fontSizePt, target.fontSizePt, baseDirect.fontSizePt, targetDirect.fontSizePt);
+	if (fontSizePt !== void 0) formatting.fontSizePt = fontSizePt;
+	const color = changedStringValue(normalizeInlineFormattingColor(base.color), normalizeInlineFormattingColor(target.color), normalizeInlineFormattingColor(baseDirect.color ?? void 0), normalizeInlineFormattingColor(targetDirect.color ?? void 0));
+	if (color !== void 0) formatting.color = color;
+	return formatting;
+};
+const sameInlineFormatting = (left, right) => left.bold === right.bold && left.italic === right.italic && left.underline === right.underline && left.strike === right.strike && left.fontFamily === right.fontFamily && left.fontSizePt === right.fontSizePt && left.color === right.color;
+const hasInlineFormatting = (formatting) => formatting.bold !== void 0 || formatting.italic !== void 0 || formatting.underline !== void 0 || formatting.strike !== void 0 || formatting.fontFamily !== void 0 || formatting.fontSizePt !== void 0 || formatting.color !== void 0;
 /**
 * A block's runs, or `null` when they cannot describe the block's text.
 * Non-text inline content (a field, an image) leaves the concatenated run text
@@ -18,7 +47,7 @@ const previewRunsForBlock = (block) => {
 	return runs.map(({ text }) => text).join("") === block.text ? runs : null;
 };
 /**
-* Segments where `targetBlock`'s bold / italic / underline / strike differs from
+* Segments where `targetBlock`'s supported run formatting differs from
 * `baseBlock`'s, for two blocks that carry the same text. Returns `null` only
 * when the diff would exceed `maxSegments`.
 *

package/dist/compare/plan.d.ts

@@ -1,10 +1,40 @@
 import { FolioAIEditOperation, FolioAIEditSnapshot } from "../ai-edits/types.js";
+import { TableGeometryPairing } from "../ai-edits/table-geometry.js";
 import { FolioDocumentStoryHandle } from "../ai-edits/headless.js";
 import { CompareChange } from "./types.js";
 //#region src/compare/plan.d.ts
+/**
+ * A table the target document already holds, which the operation naming it
+ * should place verbatim instead of rebuilding from its cell texts.
+ *
+ * The plan is pure and sees only block snapshots, so it names the table by the
+ * index the snapshot numbers tables with; the caller, which has both
+ * documents, resolves the index to the node.
+ */
+type CompareTableTemplateRequest = {
+  /** The `insertTable` or `insertTableRow` operation this table belongs to. */
+  operationId: string;
+  /** Index of the table in the TARGET story. */
+  targetTableIndex: number;
+  /** Set for a row insertion: which of that table's rows to place. */
+  targetRowIndex?: number;
+};
 type CompareStoryPlan = {
   changes: CompareChange[];
   operations: FolioAIEditOperation[];
+  /**
+   * Where an operation's table comes from. Kept beside the operations rather
+   * than inside them because a table node is not JSON, and the serialized
+   * operation contract describes a table by its cell texts.
+   */
+  tableTemplates: CompareTableTemplateRequest[];
+  /**
+   * Base cells the alignment put opposite a target cell. Their tables, rows
+   * and cells are the ones whose `w:tblPr` / `w:trPr` / `w:tcPr` the caller
+   * matches: a table that stayed in place while its widths, shading or header
+   * row changed moves no block, so no operation carries the difference.
+   */
+  tableGeometryPairings: TableGeometryPairing[];
 };
 type PlanStoryCompareOptions = {
   story: FolioDocumentStoryHandle;
@@ -19,4 +49,4 @@ type PlanStoryCompareOptions = {
  */
 declare const planStoryCompare: ({ story, baseSnapshot, targetSnapshot, maxOperations }: PlanStoryCompareOptions) => CompareStoryPlan | null;
 //#endregion
-export { CompareStoryPlan, PlanStoryCompareOptions, planStoryCompare };
+export { CompareStoryPlan, CompareTableTemplateRequest, PlanStoryCompareOptions, planStoryCompare };