@stll/folio-core 0.52.0 → 0.54.0

package/dist/ai-edits/result-validation.d.ts

@@ -0,0 +1,29 @@
+import { document_d_exports } from "../types/document.js";
+import { Node } from "prosemirror-model";
+import { ValidateDocumentModelIssue } from "@stll/docx-core";
+//#region src/ai-edits/result-validation.d.ts
+/** What the story's package knows that the story itself does not. */
+type FolioOperationResultValidationContext = {
+  /**
+   * The document's numbering definitions; `null` when the story states none,
+   * `undefined` when it cannot say (no numbering plugin), which leaves
+   * numbering references unchecked.
+   */
+  numbering: document_d_exports.NumberingDefinitions | null | undefined;
+  /** Comment ids the batch allocated; the host holds the comments themselves. */
+  createdCommentIds: readonly number[];
+  /**
+   * The author the host stamps on those comments, when the batch names one;
+   * the host writes the batch's author, so a blank one fails there too.
+   */
+  commentAuthor?: string;
+};
+/**
+ * The save-validator errors the batch introduced: errors in the changed window
+ * of `after` that the same window of `before` did not already report. Empty
+ * when the result is as saveable as the story it started from.
+ */
+declare const findIntroducedModelErrors: (before: Node, after: Node, context: FolioOperationResultValidationContext) => ValidateDocumentModelIssue[];
+declare const describeModelError: ({ path, message }: ValidateDocumentModelIssue) => string;
+//#endregion
+export { FolioOperationResultValidationContext, describeModelError, findIntroducedModelErrors };

package/dist/ai-edits/result-validation.js

@@ -0,0 +1,164 @@
+import { validateFolioDocumentModel } from "../docx/modelValidation.js";
+import { proseDocToBlocks } from "../prosemirror/conversion/fromProseDoc.js";
+import { sectionPropertiesOf } from "../prosemirror/sectionCarrier.js";
+import { anchoredCommentIdsInProseDoc } from "./comment-lifecycle.js";
+import { Fragment } from "prosemirror-model";
+//#region src/ai-edits/result-validation.ts
+/**
+* The check an operation batch's result passes before it is committed.
+*
+* An operation that reaches the document is a promise that the document can
+* still be saved: the batch reports it as applied, issues a receipt and an
+* undo handle, and the next thing the caller does may be `save()`. The model
+* validator the save runs (`validateFolioDocumentModel`, the one
+* `repackDocx` asserts) is therefore the judge here too, run on what the
+* batch produced, while the batch can still be refused.
+*
+* Two constraints shape it:
+*
+* - Cost. Converting a whole story back to the model and validating it costs
+*   about as much as the apply itself on a long document. A batch only
+*   changes the top-level blocks it touched, and ProseMirror keeps every
+*   untouched child node by identity, so only the window between the first
+*   and the last changed child is converted and validated.
+* - Blame. The apply layer holds the story, not the package: comments, notes
+*   and header/footer parts are the host's. A window can therefore report an
+*   error the batch did not cause (a comment the package defines, a range the
+*   window cuts). Only an error the same window did not already have before
+*   the batch counts; an error the document already carried is the
+*   document's, and refusing every later edit near it would help no one.
+*/
+/**
+* The top-level children that differ between two versions of one story,
+* found by node identity from both ends. `null` when every child is shared.
+*/
+const changedTopLevelWindow = (before, after) => {
+	if (before === after) return null;
+	const beforeCount = before.childCount;
+	const afterCount = after.childCount;
+	let from = 0;
+	while (from < beforeCount && from < afterCount && before.child(from) === after.child(from)) from += 1;
+	let beforeTo = beforeCount;
+	let afterTo = afterCount;
+	while (beforeTo > from && afterTo > from && before.child(beforeTo - 1) === after.child(afterTo - 1)) {
+		beforeTo -= 1;
+		afterTo -= 1;
+	}
+	if (from === beforeTo && from === afterTo) return null;
+	return {
+		from,
+		beforeTo,
+		afterTo
+	};
+};
+const TOP_LEVEL_PATH = /^package\.document\.content\[(\d+)\]/u;
+/** Rebase a window-relative block path onto the story's own block index. */
+const rebasePath = (path, offset) => path.replace(TOP_LEVEL_PATH, (_match, index) => `package.document.content[${String(Number(index) + offset)}]`);
+const syntheticComment = (id, author) => ({
+	id,
+	author,
+	content: []
+});
+/** A story can identify its existing references even though the host owns the parts. */
+const knownSectionParts = (doc) => {
+	const headers = /* @__PURE__ */ new Map();
+	const footers = /* @__PURE__ */ new Map();
+	doc.descendants((node) => {
+		if (node.type.name !== "paragraph") return true;
+		const section = sectionPropertiesOf(node);
+		for (const { rId, type } of section?.headerReferences ?? []) headers.set(rId, {
+			type: "header",
+			hdrFtrType: type,
+			content: []
+		});
+		for (const { rId, type } of section?.footerReferences ?? []) footers.set(rId, {
+			type: "footer",
+			hdrFtrType: type,
+			content: []
+		});
+		return false;
+	});
+	return {
+		headers,
+		footers
+	};
+};
+const windowErrors = ({ doc, from, to, context, knownParts, knownCommentIds }) => {
+	if (to <= from) return [];
+	const children = [];
+	for (let index = from; index < to; index += 1) children.push(doc.child(index));
+	let content;
+	try {
+		content = proseDocToBlocks(doc.copy(Fragment.fromArray(children)), []);
+	} catch (error) {
+		return [{
+			path: `package.document.content[${String(from)}]`,
+			message: `The content cannot be converted for saving: ${error instanceof Error ? error.message : String(error)}`,
+			severity: "error"
+		}];
+	}
+	return validateFolioDocumentModel({ package: {
+		document: {
+			content,
+			comments: [...[...knownCommentIds ?? []].map((id) => syntheticComment(id, "")), ...context.createdCommentIds.filter((id) => !knownCommentIds?.has(id)).map((id) => syntheticComment(id, context.commentAuthor ?? ""))]
+		},
+		...context.numbering !== null && context.numbering !== void 0 && { numbering: context.numbering },
+		...knownParts && {
+			headers: knownParts.headers,
+			footers: knownParts.footers
+		}
+	} }).issues.filter((issue) => issue.severity === "error" && !(context.numbering === void 0 && issue.path.endsWith(".numPr.numId"))).map(({ path, message, severity }) => ({
+		path: rebasePath(path, from),
+		message,
+		severity
+	}));
+};
+/**
+* The save-validator errors the batch introduced: errors in the changed window
+* of `after` that the same window of `before` did not already report. Empty
+* when the result is as saveable as the story it started from.
+*/
+const findIntroducedModelErrors = (before, after, context) => {
+	const window = changedTopLevelWindow(before, after);
+	if (window === null) return [];
+	let afterErrors = windowErrors({
+		doc: after,
+		from: window.from,
+		to: window.afterTo,
+		context
+	});
+	let parts;
+	if (afterErrors.some(({ message }) => message.startsWith("Section references missing "))) parts = knownSectionParts(before);
+	let knownCommentIds;
+	if (afterErrors.some(({ message }) => /^Comment \d+ is referenced but not present/u.test(message))) knownCommentIds = anchoredCommentIdsInProseDoc(before);
+	if (parts || knownCommentIds) afterErrors = windowErrors({
+		doc: after,
+		from: window.from,
+		to: window.afterTo,
+		context,
+		...parts !== void 0 && { knownParts: parts },
+		...knownCommentIds !== void 0 && { knownCommentIds }
+	});
+	if (afterErrors.length === 0) return afterErrors;
+	const known = /* @__PURE__ */ new Map();
+	for (const { message } of windowErrors({
+		doc: before,
+		from: window.from,
+		to: window.beforeTo,
+		context: {
+			...context,
+			createdCommentIds: []
+		},
+		...parts !== void 0 && { knownParts: parts },
+		...knownCommentIds !== void 0 && { knownCommentIds }
+	})) known.set(message, (known.get(message) ?? 0) + 1);
+	return afterErrors.filter(({ message }) => {
+		const remaining = known.get(message) ?? 0;
+		if (remaining === 0) return true;
+		known.set(message, remaining - 1);
+		return false;
+	});
+};
+const describeModelError = ({ path, message }) => `The result would not save: ${path}: ${message}`;
+//#endregion
+export { describeModelError, findIntroducedModelErrors };

package/dist/ai-edits/revisionStretches.d.ts

@@ -0,0 +1,17 @@
+import { Transaction } from "prosemirror-state";
+//#region src/ai-edits/revisionStretches.d.ts
+type SeparateRevisionStretchesOptions = {
+  tr: Transaction;
+  revisionSeed: number;
+};
+type SeparatedRevisionStretches = {
+  nextRevisionId: number;
+  /** Each fresh id, with the revision whose stretch it now names. */
+  minted: {
+    revisionId: number;
+    from: number;
+  }[];
+};
+declare const separateRevisionStretches: ({ tr, revisionSeed }: SeparateRevisionStretchesOptions) => SeparatedRevisionStretches;
+//#endregion
+export { SeparatedRevisionStretches, separateRevisionStretches };

package/dist/ai-edits/revisionStretches.js

@@ -0,0 +1,80 @@
+import { expectTrackedChangeMarkAttrs } from "../prosemirror/attrs/index.js";
+//#region src/ai-edits/revisionStretches.ts
+const INLINE_REVISION_MARKS = /* @__PURE__ */ new Set(["insertion", "deletion"]);
+const separateRevisionStretches = ({ tr, revisionSeed }) => {
+	let nextRevisionId = revisionSeed;
+	const minted = [];
+	const retargets = [];
+	let stretches = /* @__PURE__ */ new Map();
+	tr.doc.descendants((node, pos) => {
+		if (node.isTextblock) {
+			stretches = /* @__PURE__ */ new Map();
+			return true;
+		}
+		if (!node.isInline || !(node.isLeaf || node.isText)) return true;
+		const layersOf = (mark) => {
+			const attrs = expectTrackedChangeMarkAttrs(mark);
+			return [...(attrs._docxRevisionAncestors ?? []).flatMap((ancestor) => ancestor.type === "insertion" || ancestor.type === "deletion" ? [{
+				kind: ancestor.type,
+				revisionId: ancestor.revisionId
+			}] : []), {
+				kind: mark.type.name,
+				revisionId: attrs.revisionId
+			}];
+		};
+		const revisionMarks = node.marks.filter((mark) => INLINE_REVISION_MARKS.has(mark.type.name) && expectTrackedChangeMarkAttrs(mark).moveKind === void 0);
+		const carried = new Set(revisionMarks.flatMap((mark) => layersOf(mark).map(({ kind, revisionId }) => `${kind}:${String(revisionId)}`)));
+		if (node.type.name !== "commentReference") {
+			for (const [key, stretch] of stretches) if (!carried.has(key)) stretch.interrupted = true;
+		}
+		for (const mark of revisionMarks) {
+			const ids = /* @__PURE__ */ new Map();
+			for (const { kind, revisionId } of layersOf(mark)) {
+				const key = `${kind}:${String(revisionId)}`;
+				let stretch = stretches.get(key);
+				if (!stretch) {
+					stretch = {
+						id: revisionId,
+						interrupted: false
+					};
+					stretches.set(key, stretch);
+				} else if (stretch.interrupted) {
+					const fresh = nextRevisionId++;
+					minted.push({
+						revisionId: fresh,
+						from: revisionId
+					});
+					stretch = {
+						id: fresh,
+						interrupted: false
+					};
+					stretches.set(key, stretch);
+				}
+				if (stretch.id !== revisionId) ids.set(revisionId, stretch.id);
+			}
+			if (ids.size > 0) retargets.push({
+				from: pos,
+				to: pos + node.nodeSize,
+				mark,
+				ids
+			});
+		}
+		return true;
+	});
+	for (const { from, to, mark, ids } of retargets) {
+		const attrs = expectTrackedChangeMarkAttrs(mark);
+		const ancestors = attrs._docxRevisionAncestors;
+		tr.removeMark(from, to, mark);
+		tr.addMark(from, to, mark.type.create({
+			...mark.attrs,
+			revisionId: ids.get(attrs.revisionId) ?? attrs.revisionId,
+			...ancestors && { _docxRevisionAncestors: ancestors.map((ancestor) => Object.assign(structuredClone(ancestor), { revisionId: ids.get(ancestor.revisionId) ?? ancestor.revisionId })) }
+		}));
+	}
+	return {
+		nextRevisionId,
+		minted
+	};
+};
+//#endregion
+export { separateRevisionStretches };

package/dist/ai-edits/snapshot.d.ts

@@ -1,4 +1,5 @@
 import { FolioAIBlock, FolioAIBlockStructuralBoundary, FolioAIEditSnapshot, FolioAITextRangeHandle } from "./types.js";
+import { NoteReferenceLabels } from "./note-references.js";
 import { CleanBlockText } from "./clean-text.js";
 import { RunStyleResolver } from "../prosemirror/runStyleFormatting.js";
 import { Node } from "prosemirror-model";
@@ -67,10 +68,12 @@ declare const isFolioAIContentBlock: ({ text }: Pick<FolioAIBlock, "text">) => b
 declare const trailingBodyBlockId: ({ blocks }: FolioAIEditSnapshot) => string | null;
 declare const hashFolioAIBlockText: (text: string) => string;
 /**
- * Canonical public projection of the clean view's zero-width structure.
+ * Canonical public projection of the clean view's inline structure.
  *
  * A field boundary stays internal: it marks text the reader already sees, so it
- * belongs to range resolution rather than to a block's published structure.
+ * belongs to range resolution rather than to a block's published structure. A
+ * note reference is published: its marker reads like text, and a reader has to
+ * be able to tell it is not.
  */
 declare const projectFolioAIBlockStructuralBoundaries: ({ structuralBoundaries }: Pick<CleanBlockText, "structuralBoundaries">) => readonly FolioAIBlockStructuralBoundary[];
 /** Stable precondition fingerprint for a block's zero-width structure. */
@@ -90,6 +93,36 @@ declare const createFolioAITextRangeHandle: ({ blockId, text, startOffset, endOf
  * whole subtree, so a table nested inside a hidden row is hidden with it.
  */
 declare const isHiddenTableRow: (node: Node) => boolean;
+/**
+ * The marker every footnote/endnote reference of a story reads as: numbered in
+ * reading order over the blocks {@link createFolioAIEditSnapshot} reads (a
+ * hidden row's references are as absent as its text), so the applier, the
+ * range resolvers and the snapshot all read the same text.
+ *
+ * The story is numbered on the first label asked for, not here: a reader
+ * whose walk meets no reference (most documents, and every revision-stats
+ * read) never pays for a second walk of the story.
+ */
+declare const collectNoteReferenceLabels: (doc: Node) => NoteReferenceLabels;
+/**
+ * @internal The markers a comparison reads a revised story's references as:
+ * each note the base story references keeps the base's marker, and a note
+ * only the revised story references is numbered after them.
+ *
+ * Each story's own reading-order numbering would renumber every later marker
+ * of the revised story as soon as a reference is added or removed before it,
+ * and a text comparison would then read a reference both stories keep as an
+ * edit of it. Numbering the revised story on from the base keeps a kept
+ * reference's marker identical, and makes a reference the comparison brings
+ * write the marker the base story (which the edits resolve against) gives it.
+ */
+declare const alignedNoteReferenceLabels: (base: Node, revised: Node) => NoteReferenceLabels;
+/**
+ * @internal The same snapshot with every note reference read through `labels`
+ * rather than the story's own numbering. Only the text and structural
+ * boundaries can change: block ids, anchors and the source document do not.
+ */
+declare const relabelFolioAIEditSnapshotNoteReferences: (snapshot: FolioAIEditSnapshot, labels: NoteReferenceLabels) => FolioAIEditSnapshot;
 /** One table of a story, numbered the way {@link createFolioAIEditSnapshot} numbers it. */
 type FolioStoryTable = {
   /** Document-order index over every table, nested ones included. */
@@ -110,4 +143,4 @@ declare const createFolioAIEditSnapshot: (doc: Node) => FolioAIEditSnapshot;
 /** @internal Use for an EditorState that owns the document's style resolver. */
 declare const createFolioAIEditSnapshotWithStyleResolver: (doc: Node, styleResolver: RunStyleResolver | null) => FolioAIEditSnapshot;
 //#endregion
-export { FolioStoryTable, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, detachFolioAIEditSnapshotExternalHyperlinks, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences, sourceDocumentOf, storyTablesOf, styleResolverOf, trailingBodyBlockId };
+export { FolioStoryTable, alignedNoteReferenceLabels, collectNoteReferenceLabels, createFolioAIEditSnapshot, createFolioAIEditSnapshotWithStyleResolver, createFolioAITextRangeHandle, detachFolioAIEditSnapshotExternalHyperlinks, folioStoryTables, hashFolioAIBlockStructuralBoundaries, hashFolioAIBlockText, isFolioAIContentBlock, isHiddenTableRow, normalizeFolioAIBlockText, numberingReferenceKeysOf, projectFolioAIBlockStructuralBoundaries, relabelFolioAIEditSnapshotNoteReferences, remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences, sourceDocumentOf, storyTablesOf, styleResolverOf, trailingBodyBlockId };