Files
Tom MoorandClaude Opus 5 84c40c8392 fix: Revision diff mismatching node closing tokens (#13537)
The changeset token encoder cached node type ids in an object created
with a null prototype, but tested for a cache miss with `=== null`. The
miss reads as undefined, so the cache was never filled and every node
end encoded to undefined — making the closing token of any node compare
equal to that of any other.

As a result revision diffs could omit a node's closing token when its
type changed, and attribute an inserted wrapper's closing token to the
node it wraps.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 16:29:21 -04:00

480 lines
16 KiB
TypeScript

import type { Mark, Slice } from "prosemirror-model";
import { Fragment, Node, Schema } from "prosemirror-model";
import type { Change, TokenEncoder } from "prosemirror-changeset";
import { ChangeSet, simplifyChanges } from "prosemirror-changeset";
import { ReplaceStep, type Step } from "prosemirror-transform";
import ExtensionManager from "./ExtensionManager";
import { recreateTransform } from "./prosemirror-recreate-transform";
import { richExtensions, withComments } from "../nodes";
import type { ProsemirrorData } from "../../types";
/**
* The structural subset of a changeset `Change` that this module reads and
* produces. Using a `Pick` rather than the `Change` class avoids requiring
* class-only members (such as `toJSON`) on the plain objects we build.
*/
type ChangeFields<T> = Pick<
Change<T>,
"fromA" | "toA" | "fromB" | "toB" | "deleted" | "inserted"
>;
/**
* The maximum number of unchanged characters allowed between two adjacent
* changes for them to still be merged into a single change. This is
* deliberately small: merging absorbs the gap into the diff, so any unchanged
* text within it is rendered as deleted/reinserted. A value of 3 is the
* minimum that rejoins hyphenated word fragments such as replacing
* "no-await-in-loop", where the differ aligns the shared "no" and leaves an
* unchanged "no-" (gap of 3) between fragments, without swallowing longer
* unchanged words.
*/
const MAX_UNCHANGED_GAP = 3;
/**
* Merges adjacent Change objects that represent interleaved deletions/insertions.
*
* When word-level diffing is used, replacing "no-await-in-loop" with
* "jsx-no-jsx-as-prop" can produce multiple adjacent Change objects like:
* Change1: delete "no", insert "jsx"
* Change2: delete "await", insert "no"
* ...
*
* This function merges such adjacent changes into a single change:
* Change: delete "no-await-in-loop", insert "jsx-no-jsx-as-prop"
*
* @param changes - The changes from simplifyChanges
* @param docOld - The old document (to extract merged deletion content)
* @returns Changes with adjacent interleaved changes merged
*/
function mergeInterleavedChanges<T extends { step: Step; slice: Slice | null }>(
changes: readonly ChangeFields<T>[],
docOld: Node
): ChangeFields<T>[] {
if (changes.length <= 1) {
return [...changes];
}
const result: ChangeFields<T>[] = [];
let i = 0;
while (i < changes.length) {
const current = changes[i];
// Check if this change and subsequent changes form a contiguous replacement
// (i.e., they're adjacent in both old and new document positions)
let j = i + 1;
while (j < changes.length) {
const prev = changes[j - 1];
const next = changes[j];
// Check if changes are adjacent (toA of prev equals fromA of next, same for B)
// Allow gaps (like hyphens or other unchanged characters between changes)
const gapA = next.fromA - prev.toA;
const gapB = next.fromB - prev.toB;
// Check if changes are in the same parent node (e.g., same table cell, same paragraph)
// by verifying that the gap in the old document doesn't cross node boundaries
let crossesNodeBoundary = false;
if (gapA > 0) {
try {
// If the gap contains any non-text node, it crosses a boundary
const gap = docOld.slice(prev.toA, next.fromA).content;
for (let n = 0; n < gap.childCount; n++) {
if (!gap.child(n).isText) {
crossesNodeBoundary = true;
break;
}
}
} catch {
crossesNodeBoundary = true;
}
}
// If gaps are equal, reasonably small, and don't cross node boundaries,
// they're part of the same logical replacement
if (
gapA === gapB &&
gapA >= 0 &&
gapA <= MAX_UNCHANGED_GAP &&
!crossesNodeBoundary
) {
j++;
} else {
break;
}
}
// The merged change only needs the first deletion/insertion in the window
// to carry forward the originating step; the spans themselves are
// recomputed from the window bounds below.
let firstDeleted: { length: number; data: T } | undefined;
let firstInserted: { length: number; data: T } | undefined;
for (let k = i; k < j; k++) {
firstDeleted ??= changes[k].deleted[0];
firstInserted ??= changes[k].inserted[0];
}
// Merge the window only when it is a genuine replacement — it must contain
// both a deletion and an insertion. Otherwise a cluster of pure insertions
// (or pure deletions) separated by a short unchanged gap would merge and
// render the unchanged text between them as inserted/deleted.
if (j > i + 1 && firstDeleted && firstInserted) {
const lastChange = changes[j - 1];
// Create merged change. The deletion slice holds the original (old) text
// spanning the whole window so it renders as one block; it is not treated
// as a modification downstream because its text differs from the insertion.
const mergedChange: ChangeFields<T> = {
fromA: current.fromA,
toA: lastChange.toA,
fromB: current.fromB,
toB: lastChange.toB,
deleted: [
{
length: lastChange.toA - current.fromA,
data: {
...firstDeleted.data,
slice: docOld.slice(current.fromA, lastChange.toA),
} as T,
},
],
inserted: [
{
length: lastChange.toB - current.fromB,
data: firstInserted.data,
},
],
};
result.push(mergedChange);
i = j;
} else {
result.push(current);
i++;
}
}
return result;
}
/**
* The maximum estimated cost of computing a changeset, as the number of patch
* operations multiplied by the document node size. Step recreation copies and
* validates the full document once per operation, so its runtime grows with
* this product; above the bound the changeset is skipped instead of blocking
* the process for seconds or minutes.
*/
const MAX_CHANGESET_COMPLEXITY = 50_000_000;
/**
* Marks that carry no document content and should not be surfaced as changes.
*/
const IGNORED_MARKS = ["comment"];
/**
* Recursively removes marks that are irrelevant to a diff from a node, so that
* adding or removing one does not render as a change to the text it covers.
*
* @param node - The node to strip marks from.
* @returns an equivalent node without the ignored marks.
*/
function removeIgnoredMarks(node: Node): Node {
const marks = node.marks.filter(
(mark) => !IGNORED_MARKS.includes(mark.type.name)
);
if (node.isText || !node.childCount) {
return node.mark(marks);
}
const children: Node[] = [];
node.content.forEach((child) => children.push(removeIgnoredMarks(child)));
return node.copy(Fragment.fromArray(children)).mark(marks);
}
/**
* Represents a modification (attribute change) in the document.
*/
export type Modification = {
length: number;
data: {
step: Step;
slice: Slice | null;
oldAttrs: Record<string, unknown>;
newAttrs: Record<string, unknown>;
};
};
/**
* Extended Change type that includes modifications.
*/
export interface ExtendedChange extends Pick<
Change,
"fromA" | "toA" | "fromB" | "toB" | "deleted" | "inserted"
> {
modified: readonly Modification[];
}
export type DiffChanges = {
changes: readonly ExtendedChange[];
doc: Node;
};
class AttributeEncoder implements TokenEncoder<string | number> {
public encodeCharacter(char: number, marks: Mark[]): string | number {
return `${char}:${this.encodeMarks(marks)}`;
}
public encodeNodeStart(node: Node): string {
const nodeName = node.type.name;
const marks = node.marks;
// Add node attributes if they exist
let nodeStr = nodeName;
// Enable more attribute encoding as tested
if (Object.keys(node.attrs).length) {
nodeStr += ":" + JSON.stringify(node.attrs);
}
if (!marks.length) {
return nodeStr;
}
return `${nodeStr}:${this.encodeMarks(marks)}`;
}
// See: https://github.com/ProseMirror/prosemirror-changeset/blob/23f67c002e5489e454a0473479e407decb238afe/src/diff.ts#L26
public encodeNodeEnd({ type }: Node): number {
const cache: Record<string, number> =
type.schema.cached.changeSetIDs ||
(type.schema.cached.changeSetIDs = Object.create(null));
// The cache has a null prototype, so a miss reads as undefined.
let id = cache[type.name];
if (id === undefined) {
cache[type.name] = id =
Object.keys(type.schema.nodes).indexOf(type.name) + 1;
}
return id;
}
public compareTokens(a: string | number, b: string | number): boolean {
return a === b;
}
private encodeMarks(marks: readonly Mark[]): string {
return marks
.map((m) => {
let result = m.type.name;
if (Object.keys(m.attrs).length) {
result += ":" + JSON.stringify(m.attrs);
}
return result;
})
.sort()
.join(",");
}
}
export class ChangesetHelper {
/**
* Calculates a changeset between two revisions of a document.
*
* @param revision - The current revision data.
* @param previousRevision - The previous revision data to compare against.
* @returns An object containing the simplified changes and the new document,
* or null when there is nothing to compare against or the changeset is too
* expensive to compute.
*/
public static getChangeset(
revision?: ProsemirrorData | null,
previousRevision?: ProsemirrorData | null
): DiffChanges | null {
if (!revision || !previousRevision) {
// This is the first revision, nothing to compare against
return null;
}
try {
// Create schema from extensions
const extensionManager = new ExtensionManager(
withComments(richExtensions)
);
const schema = new Schema({
nodes: extensionManager.nodes,
marks: extensionManager.marks,
});
// Parse documents from JSON (old = previous revision, new = current revision)
const original = Node.fromJSON(schema, revision);
// Diffing runs against copies without the ignored marks. Stripping marks
// leaves every position unchanged, so the resulting changes still line up
// with the original document.
const docOld = removeIgnoredMarks(
Node.fromJSON(schema, previousRevision)
);
const docNew = removeIgnoredMarks(original);
// Calculate the transform and changeset. Throws, and so returns null,
// when the diff is too expensive to compute.
const tr = recreateTransform(docOld, docNew, {
complexSteps: false,
wordDiffs: true,
simplifyDiff: true,
maxComplexity: MAX_CHANGESET_COMPLEXITY,
});
// Map steps to capture the actual content being replaced from the document
// state at that specific step. This ensures deleted content is correctly
// captured for diff rendering.
const changeset = ChangeSet.create<{
step: Step;
slice: Slice | null;
}>(docOld, undefined, this.attributeEncoder).addSteps(
tr.doc,
tr.mapping.maps,
tr.steps.map((step, i) => ({
step,
slice:
step instanceof ReplaceStep
? tr.docs[i].slice(step.from, step.to)
: null,
}))
);
// Merge interleaved deletions/insertions into cleaner blocks
const changes = mergeInterleavedChanges(
simplifyChanges(changeset.changes, docNew),
docOld
);
// Post-process changes to detect modifications (attribute-only changes)
const extendedChanges: ExtendedChange[] = changes.map((change) => {
const modified: Modification[] = [];
const matchedDeletionIndices = new Set<number>();
const matchedInsertionIndices = new Set<number>();
// Each deletion entry contains both old (step.slice) and new (slice) content
// Check if the deletion represents a modification by comparing these
for (let i = 0; i < change.deleted.length; i++) {
const deletion = change.deleted[i];
if (!deletion.data.slice || !deletion.data.step.slice) {
continue;
}
// deletion.data.step.slice = OLD content (what was in the document)
// deletion.data.slice = NEW content (what it changed to)
const oldSlice = deletion.data.step.slice;
const newSlice = deletion.data.slice;
// Check if both slices have the same number of nodes
if (
oldSlice.content.childCount === newSlice.content.childCount &&
oldSlice.content.childCount > 0
) {
let isModification = true;
const nodes: Array<{
oldNode: Node;
newNode: Node;
}> = [];
// Check each corresponding node pair
for (let index = 0; index < oldSlice.content.childCount; index++) {
const oldNode = oldSlice.content.child(index);
const newNode = newSlice.content.child(index);
// For modifications, we allow:
// 1. Same node type with different attributes (e.g., code_block language change)
// 2. Related node types with same semantic group (e.g., td <-> th share "tableCell" group)
const isSameType = oldNode.type.name === newNode.type.name;
// Check if nodes share a common semantic group (excluding generic "block"/"inline")
const getSemanticGroups = (node: Node): Set<string> => {
const groups = node.type.spec.group?.split(" ") || [];
return new Set(
groups.filter((g) => g !== "block" && g !== "inline")
);
};
const oldGroups = getSemanticGroups(oldNode);
const newGroups = getSemanticGroups(newNode);
const hasSharedGroup = Array.from(oldGroups).some((g) =>
newGroups.has(g)
);
const isRelatedNodeType = !isSameType && hasSharedGroup;
try {
if (
oldNode.textContent !== newNode.textContent ||
(!isSameType && !isRelatedNodeType)
) {
isModification = false;
} else if (
isSameType &&
JSON.stringify(oldNode.attrs) ===
JSON.stringify(newNode.attrs)
) {
// Same type and same attributes = not a modification
isModification = false;
}
nodes.push({ oldNode, newNode });
} catch {
isModification = false;
}
}
if (isModification) {
modified.push({
length: deletion.length,
data: {
step: deletion.data.step,
slice: deletion.data.slice,
oldAttrs: nodes.length === 1 ? nodes[0].oldNode.attrs : {},
newAttrs: nodes.length === 1 ? nodes[0].newNode.attrs : {},
},
});
// Mark this deletion for removal
matchedDeletionIndices.add(i);
// Also find and mark corresponding insertion for removal
for (let j = 0; j < change.inserted.length; j++) {
const insertion = change.inserted[j];
if (
insertion.length === deletion.length &&
!matchedInsertionIndices.has(j)
) {
matchedInsertionIndices.add(j);
break;
}
}
}
}
}
return Object.assign({}, change, {
deleted: change.deleted.filter(
(_, index) => !matchedDeletionIndices.has(index)
),
inserted: change.inserted.filter(
(_, index) => !matchedInsertionIndices.has(index)
),
modified,
});
});
return {
changes: extendedChanges,
doc: original,
};
} catch {
return null;
}
}
private static attributeEncoder = new AttributeEncoder();
}