@stll/folio-core 0.9.0 → 0.10.0

package/dist/version-comparison.js

@@ -1,6 +1,9 @@
 import { getFolioParaIdFromBlockId } from "./types/block-id.js";
 import { diffWordSegments } from "./ai-edits/word-diff.js";
+import { pairFolioDocumentStories } from "./document-stories.js";
 import { FolioDocxReviewer } from "./ai-edits/headless.js";
+import { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, PRIVATE_METADATA_PROPERTIES_BY_TRANSFORM, isFolioDocumentPrivacyTransform } from "./docx/metadataPrivacy.js";
+import { TaggedError, panic } from "better-result";
 //#region src/version-comparison.ts
 /**
 * Document version-diff engine: compare two `.docx` buffers block by block
@@ -76,6 +79,16 @@ import { FolioDocxReviewer } from "./ai-edits/headless.js";
 * content that makes the preview texts disagree, detection backs off to
 * `unchanged` rather than misattribute properties.
 */
+/** Independently selectable comparison scopes. */
+const FOLIO_VERSION_COMPARISON_SCOPES = Object.freeze([
+	"text",
+	"formatting",
+	"metadata"
+]);
+const isFolioVersionComparisonScope = (value) => FOLIO_VERSION_COMPARISON_SCOPES.some((scope) => scope === value);
+var InvalidFolioVersionComparisonOptionsError = class extends TaggedError("InvalidFolioVersionComparisonOptionsError")() {};
+const FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS = FOLIO_DOCUMENT_PRIVACY_TRANSFORMS;
+const isFolioVersionComparisonPrivacyTransform = (value) => isFolioDocumentPrivacyTransform(value);
 /** Run-level formatting properties compared for `formatChanged` detection. */
 const FORMAT_PROPERTIES = [
 	"bold",
@@ -324,7 +337,7 @@ const meetsMoveWordCount = (text) => {
 * per text, so duplicated boilerplate above the word floor pairs
 * first-to-first rather than fanning out.
 */
-const detectMoves = (changes, counts) => {
+const detectMoves = (changes, counts, firstMoveGroupId) => {
 	const deletedIndexesByText = /* @__PURE__ */ new Map();
 	changes.forEach((change, index) => {
 		if (change.type === "deleted" && meetsMoveWordCount(change.text)) {
@@ -334,7 +347,7 @@ const detectMoves = (changes, counts) => {
 		}
 	});
 	if (deletedIndexesByText.size === 0) return;
-	let moveGroupId = 0;
+	let moveGroupId = firstMoveGroupId - 1;
 	changes.forEach((change, index) => {
 		if (change.type !== "added") return;
 		const deletedIndex = deletedIndexesByText.get(change.text)?.shift();
@@ -347,53 +360,72 @@ const detectMoves = (changes, counts) => {
 			blockId: deleted.blockId,
 			kind: deleted.kind,
 			text: deleted.text,
-			moveGroupId
+			moveGroupId,
+			baseHandle: deleted.baseHandle
 		};
 		changes[index] = {
 			type: "movedTo",
 			blockId: change.blockId,
 			kind: change.kind,
 			text: change.text,
-			moveGroupId
+			moveGroupId,
+			revisedHandle: change.revisedHandle
 		};
 		counts.deleted--;
 		counts.added--;
 		counts.moved++;
 	});
 };
-/**
-* Compare two `.docx` buffers and return a structured, block-level diff.
-* See the module doc comment for the as-accepted comparison semantics, the
-* three-pass alignment algorithm, move detection, and format-only change
-* detection.
-*/
-const compareDocxVersions = async (base, revised) => {
-	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
-	const baseBlocks = baseReviewer.snapshot().blocks;
-	const revisedBlocks = revisedReviewer.snapshot().blocks;
+const createSummaryCounts = () => ({
+	added: 0,
+	deleted: 0,
+	modified: 0,
+	formatChanged: 0,
+	moved: 0,
+	metadataChanged: 0,
+	unchanged: 0
+});
+const addSummaryCounts = (target, source) => {
+	target.added += source.added;
+	target.deleted += source.deleted;
+	target.modified += source.modified;
+	target.formatChanged += source.formatChanged;
+	target.moved += source.moved;
+	target.metadataChanged += source.metadataChanged;
+	target.unchanged += source.unchanged;
+};
+const compareStoryBlocks = ({ baseStory, revisedStory, baseBlocks, revisedBlocks, firstMoveGroupId, includeText, includeFormatting }) => {
 	const changes = [];
-	const counts = {
-		added: 0,
-		deleted: 0,
-		modified: 0,
-		formatChanged: 0,
-		moved: 0,
-		unchanged: 0
-	};
+	const counts = createSummaryCounts();
 	for (const event of alignFolioBlocks(baseBlocks, revisedBlocks)) {
 		if (event.type === "pair") {
+			if (!baseStory || !revisedStory) panic("A paired comparison event requires both story handles");
 			const { baseBlock, revisedBlock } = event;
+			const baseHandle = {
+				story: baseStory,
+				blockId: baseBlock.id
+			};
+			const revisedHandle = {
+				story: revisedStory,
+				blockId: revisedBlock.id
+			};
 			if (baseBlock.text !== revisedBlock.text) {
+				if (!includeText) {
+					counts.unchanged++;
+					continue;
+				}
 				counts.modified++;
 				changes.push({
 					type: "modified",
 					blockId: revisedBlock.id,
 					kind: revisedBlock.kind,
-					segments: diffWordSegments(baseBlock.text, revisedBlock.text)
+					segments: diffWordSegments(baseBlock.text, revisedBlock.text),
+					baseHandle,
+					revisedHandle
 				});
 				continue;
 			}
-			const changedProperties = diffPreviewRunFormatting(baseBlock, revisedBlock);
+			const changedProperties = includeFormatting ? diffPreviewRunFormatting(baseBlock, revisedBlock) : [];
 			if (changedProperties.length > 0) {
 				counts.formatChanged++;
 				changes.push({
@@ -401,7 +433,9 @@ const compareDocxVersions = async (base, revised) => {
 					blockId: revisedBlock.id,
 					kind: revisedBlock.kind,
 					text: revisedBlock.text,
-					changedProperties
+					changedProperties,
+					baseHandle,
+					revisedHandle
 				});
 				continue;
 			}
@@ -409,28 +443,152 @@ const compareDocxVersions = async (base, revised) => {
 			continue;
 		}
 		if (event.type === "baseOnly") {
+			if (!includeText) continue;
+			if (!baseStory) panic("A base-only comparison event requires a base story handle");
 			counts.deleted++;
 			changes.push({
 				type: "deleted",
 				blockId: event.block.id,
 				kind: event.block.kind,
-				text: event.block.text
+				text: event.block.text,
+				baseHandle: {
+					story: baseStory,
+					blockId: event.block.id
+				}
 			});
 			continue;
 		}
+		if (!includeText) continue;
+		if (!revisedStory) panic("A revised-only comparison event requires a revised story handle");
 		counts.added++;
 		changes.push({
 			type: "added",
 			blockId: event.block.id,
 			kind: event.block.kind,
-			text: event.block.text
+			text: event.block.text,
+			revisedHandle: {
+				story: revisedStory,
+				blockId: event.block.id
+			}
 		});
 	}
-	detectMoves(changes, counts);
+	detectMoves(changes, counts, firstMoveGroupId);
+	return {
+		baseStory,
+		revisedStory,
+		changes,
+		summaryCounts: counts
+	};
+};
+const DEFAULT_COMPARISON_SCOPES = Object.freeze(["text", "formatting"]);
+const resolveComparisonScopes = (options) => {
+	const include = options.include ?? DEFAULT_COMPARISON_SCOPES;
+	if (include.length === 0 || include.some((scope) => !isFolioVersionComparisonScope(scope))) throw new InvalidFolioVersionComparisonOptionsError({
+		message: "Version comparison requires at least one recognized scope",
+		option: "include",
+		receivedValue: include
+	});
+	return new Set(include);
+};
+const resolvePrivacyTransforms = (transforms) => {
+	if (!Array.isArray(transforms) || transforms.some((transform) => !isFolioVersionComparisonPrivacyTransform(transform))) throw new InvalidFolioVersionComparisonOptionsError({
+		message: "Version comparison received an unrecognized privacy transform",
+		option: "privacy.transforms",
+		receivedValue: transforms
+	});
+	const requested = new Set(transforms);
+	return FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS.filter((transform) => requested.has(transform));
+};
+/** Apply auditable, output-only privacy transforms to a structured version diff. */
+const applyFolioVersionDiffPrivacy = (diff, options) => {
+	const requestedTransforms = resolvePrivacyTransforms(options.transforms);
+	const appliedTransformSet = /* @__PURE__ */ new Set([...diff.privacyReport.appliedTransforms, ...requestedTransforms]);
+	const appliedTransforms = FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS.filter((transform) => appliedTransformSet.has(transform));
+	const removedPropertySet = /* @__PURE__ */ new Set();
+	for (const transform of appliedTransforms) for (const property of PRIVATE_METADATA_PROPERTIES_BY_TRANSFORM[transform]) removedPropertySet.add(property);
+	const actuallyRemovedPropertySet = /* @__PURE__ */ new Set([...diff.privacyReport.removedMetadataProperties, ...diff.metadataChanges.filter(({ property }) => removedPropertySet.has(property)).map(({ property }) => property)]);
+	const removedMetadataProperties = FOLIO_DOCUMENT_METADATA_PROPERTIES.filter((property) => actuallyRemovedPropertySet.has(property));
+	const metadataChanges = diff.metadataChanges.filter(({ property }) => !removedPropertySet.has(property));
 	return {
+		...diff,
+		metadataChanges,
+		privacyReport: {
+			appliedTransforms,
+			removedMetadataProperties
+		},
+		summaryCounts: {
+			...diff.summaryCounts,
+			metadataChanged: metadataChanges.length
+		}
+	};
+};
+const normalizeMetadataValue = (properties, property) => {
+	const value = properties?.[property];
+	return value instanceof Date ? value.toISOString() : value ?? null;
+};
+const compareMetadata = (base, revised) => {
+	const changes = [];
+	for (const property of FOLIO_DOCUMENT_METADATA_PROPERTIES) {
+		const baseValue = normalizeMetadataValue(base, property);
+		const revisedValue = normalizeMetadataValue(revised, property);
+		if (baseValue !== revisedValue) changes.push({
+			property,
+			baseValue,
+			revisedValue
+		});
+	}
+	return changes;
+};
+/**
+* Compare two `.docx` buffers and return a structured, block-level diff.
+* See the module doc comment for the as-accepted comparison semantics, the
+* three-pass alignment algorithm, move detection, and format-only change
+* detection.
+*/
+const compareDocxVersions = async (base, revised, options = {}) => {
+	const scopes = resolveComparisonScopes(options);
+	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
+	const changes = [];
+	const stories = [];
+	const counts = createSummaryCounts();
+	const baseStories = baseReviewer.listStories().map(({ handle }) => handle);
+	const revisedStories = revisedReviewer.listStories().map(({ handle }) => handle);
+	let nextMoveGroupId = 1;
+	for (const pair of pairFolioDocumentStories(baseStories, revisedStories)) {
+		const baseBlocks = pair.baseStory ? baseReviewer.readReviewedStory({
+			story: pair.baseStory,
+			view: "final"
+		})?.snapshot.blocks ?? [] : [];
+		const revisedBlocks = pair.revisedStory ? revisedReviewer.readReviewedStory({
+			story: pair.revisedStory,
+			view: "final"
+		})?.snapshot.blocks ?? [] : [];
+		const storyDiff = compareStoryBlocks({
+			...pair,
+			baseBlocks,
+			revisedBlocks,
+			firstMoveGroupId: nextMoveGroupId,
+			includeText: scopes.has("text"),
+			includeFormatting: scopes.has("formatting")
+		});
+		stories.push(storyDiff);
+		for (const change of storyDiff.changes) changes.push(change);
+		addSummaryCounts(counts, storyDiff.summaryCounts);
+		nextMoveGroupId += storyDiff.summaryCounts.moved;
+	}
+	const metadataChanges = scopes.has("metadata") ? compareMetadata(baseReviewer.getDocumentProperties(), revisedReviewer.getDocumentProperties()) : [];
+	counts.metadataChanged = metadataChanges.length;
+	const diff = {
 		changes,
+		stories,
+		metadataChanges,
+		privacyReport: {
+			appliedTransforms: [],
+			removedMetadataProperties: []
+		},
 		summaryCounts: counts
 	};
+	return options.privacy ? applyFolioVersionDiffPrivacy(diff, options.privacy) : diff;
 };
 //#endregion
-export { alignFolioBlocks, compareDocxVersions, exceedsLcsBudget };
+export { FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, InvalidFolioVersionComparisonOptionsError, alignFolioBlocks, applyFolioVersionDiffPrivacy, compareDocxVersions, exceedsLcsBudget, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",