feat(comparison): present semantic changes

Assisted-by: OpenAI Codex:gpt-5.6-sol
Signed-off-by: Hoang Pham <hoangmaths96@gmail.com>

Author: hweihwang

src/comparison/comparisonPresentation.ts

@@ -0,0 +1,64 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import type { ComparisonAttributeCode as AttributeCode, ComparisonMarkCode as MarkCode, ComparisonSignal as Signal } from './markdownComparisonTypes.ts'
+
+import { t } from '@nextcloud/l10n'
+
+type Label = () => string
+const attributes: Record<AttributeCode, readonly [number, Label]> = {
+	'image-target': [219, () => t('text', 'Image changed')],
+	'image-alt': [218, () => t('text', 'Image description changed')],
+	'link-target': [217, () => t('text', 'Link target changed')],
+	link: [216, () => t('text', 'Link changed')],
+	'mention-identity': [215, () => t('text', 'Mention changed')],
+	mathematics: [214, () => t('text', 'Mathematics changed')],
+	'preview-target': [213, () => t('text', 'Link preview changed')],
+	'footnote-reference': [212, () => t('text', 'Footnote changed')],
+	'task-state': [211, () => t('text', 'Task state changed')],
+	'heading-level': [210, () => t('text', 'Heading level changed')],
+	'list-start': [209, () => t('text', 'List start changed')],
+	'code-language': [208, () => t('text', 'Code language changed')],
+	'text-direction': [207, () => t('text', 'Text direction changed')],
+	'table-span': [206, () => t('text', 'Table structure changed')],
+	'table-alignment': [205, () => t('text', 'Table alignment changed')],
+	'callout-type': [204, () => t('text', 'Callout type changed')],
+	'details-state': [203, () => t('text', 'Details state changed')],
+	'unknown-attribute': [202, () => t('text', 'Attribute changed')],
+}
+
+const marks: Record<MarkCode, readonly [number, Label]> = {
+	bold: [106, () => t('text', 'Bold')],
+	italic: [105, () => t('text', 'Italic')],
+	strike: [104, () => t('text', 'Strikethrough')],
+	highlight: [103, () => t('text', 'Highlight')],
+	underline: [102, () => t('text', 'Underline')],
+	'inline-code': [101, () => t('text', 'Inline code')],
+}
+
+export function selectComparisonSignal(signals: readonly Signal[]): Signal | undefined {
+	return signals.reduce<Signal | undefined>((selected, signal) => (
+		!selected || signalPriority(signal) > signalPriority(selected) ? signal : selected
+	), undefined)
+}
+
+export function comparisonSignalLabel(signal: Signal) {
+	if (signal.type === 'attribute') {
+		return attributes[signal.attribute][1]()
+	}
+	if (signal.type === 'mark') {
+		return t('text', '{formatting} changed', { formatting: marks[signal.mark][1]() })
+	}
+}
+
+function signalPriority(signal: Signal) {
+	if (signal.type === 'attribute') {
+		return attributes[signal.attribute][0]
+	}
+	if (signal.type === 'mark') {
+		return marks[signal.mark][0]
+	}
+	return 150
+}

src/comparison/comparisonSections.ts

@@ -0,0 +1,157 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import type { Node } from '@tiptap/pm/model'
+import type { ComparisonEdit } from './markdownComparisonTypes.ts'
+
+import { increasingSubsequence } from './comparisonAlignment.ts'
+
+export interface ComparisonHeading {
+	from: number
+	text: string
+}
+
+export interface ComparisonSection {
+	id: string
+	title: string
+	edits: readonly ComparisonEdit[]
+}
+type Heading = ComparisonHeading
+
+export function headingLocations(doc: Node): readonly Heading[] {
+	const headings: Heading[] = []
+	doc.forEach((node, from) => {
+		const text = node.textContent.trim()
+		if (node.type.name === 'heading' && text) {
+			headings.push({ from, text })
+		}
+	})
+	return headings
+}
+
+function nearestHeadingIndex(headings: readonly Heading[], position: number) {
+	let lower = 0
+	let upper = headings.length
+	while (lower < upper) {
+		const middle = Math.floor((lower + upper) / 2)
+		if (headings[middle]!.from <= position) {
+			lower = middle + 1
+		} else {
+			upper = middle
+		}
+	}
+	return lower - 1
+}
+export function nearestHeading(headings: readonly Heading[], position: number) {
+	return headings[nearestHeadingIndex(headings, position)]?.text ?? ''
+}
+
+interface HeadingIndex {
+	headings: readonly Heading[]
+	keys: readonly string[]
+}
+
+function indexByUniqueTitle(headings: readonly Heading[]) {
+	const indexes = new Map<string, number>()
+	const repeated = new Set<string>()
+	headings.forEach(({ text }, index) => {
+		if (indexes.has(text)) {
+			repeated.add(text)
+		} else {
+			indexes.set(text, index)
+		}
+	})
+	for (const text of repeated) {
+		indexes.delete(text)
+	}
+	return indexes
+}
+
+function headingAnchors(before: readonly Heading[], after: readonly Heading[]) {
+	const beforeIndexes = indexByUniqueTitle(before)
+	const afterIndexes = indexByUniqueTitle(after)
+	const pairs: Array<readonly [number, number]> = []
+	after.forEach(({ text }, afterIndex) => {
+		const beforeIndex = beforeIndexes.get(text)
+		if (beforeIndex !== undefined && afterIndexes.get(text) === afterIndex) {
+			pairs.push([beforeIndex, afterIndex])
+		}
+	})
+	return increasingSubsequence(pairs.map(([index]) => index)).indices.map((index) => pairs[index]!)
+}
+
+function correlateHeadings(before: readonly Heading[], after: readonly Heading[]) {
+	const beforeKeys: string[] = []
+	const afterKeys: string[] = []
+	let next = 0
+	let row = 0
+	let column = 0
+
+	function pairGap(rowEnd: number, columnEnd: number) {
+		const rowCount = rowEnd - row
+		const columnCount = columnEnd - column
+		if (rowCount !== columnCount || rowCount > 1) {
+			while (row < rowEnd) {
+				beforeKeys[row++] = `#${next++}`
+			}
+			while (column < columnEnd) {
+				afterKeys[column++] = `#${next++}`
+			}
+			return
+		}
+		while (row < rowEnd) {
+			const key = `#${next++}`
+			beforeKeys[row++] = key
+			afterKeys[column++] = key
+		}
+	}
+
+	for (const [anchorRow, anchorColumn] of headingAnchors(before, after)) {
+		pairGap(anchorRow, anchorColumn)
+		const key = `#${next++}`
+		beforeKeys[row++] = key
+		afterKeys[column++] = key
+	}
+	pairGap(before.length, after.length)
+	return { before: beforeKeys, after: afterKeys }
+}
+
+function resolveSection(edit: ComparisonEdit, before: HeadingIndex, after: HeadingIndex) {
+	const descriptor = edit.primary
+	const deleted = descriptor.operation === 'delete'
+	const side = deleted ? before : after
+	const position = deleted
+		? descriptor.context.before?.from ?? descriptor.before.from
+		: descriptor.context.after?.from ?? descriptor.after.from
+	return side.keys[nearestHeadingIndex(side.headings, position)] ?? ''
+}
+
+export function buildComparisonSections(edits: readonly ComparisonEdit[], beforeDocument: Node, afterDocument: Node): readonly ComparisonSection[] {
+	const beforeHeadings = headingLocations(beforeDocument)
+	const afterHeadings = headingLocations(afterDocument)
+	const correlation = correlateHeadings(beforeHeadings, afterHeadings)
+	const before: HeadingIndex = { headings: beforeHeadings, keys: correlation.before }
+	const after: HeadingIndex = { headings: afterHeadings, keys: correlation.after }
+	const titleByKey = new Map<string, string>()
+	beforeHeadings.forEach((heading, index) => titleByKey.set(correlation.before[index]!, heading.text))
+	afterHeadings.forEach((heading, index) => titleByKey.set(correlation.after[index]!, heading.text))
+
+	const sections: Array<{ id: string, key: string, title: string, edits: ComparisonEdit[] }> = []
+	for (const edit of edits) {
+		const key = resolveSection(edit, before, after)
+		const title = titleByKey.get(key) ?? ''
+		const current = sections.at(-1)
+		if (current?.key === key) {
+			current.edits.push(edit)
+		} else {
+			sections.push({ id: edit.id, key, title, edits: [edit] })
+		}
+	}
+	return sections.map(({ id, title, edits: sectionEdits }) => ({
+		id,
+		title,
+		edits: sectionEdits,
+	}))
+}