Implement cleanCode, add tests

Author: hippotastic

.changeset/fluffy-countries-look.md

@@ -0,0 +1,5 @@
+---
+'annotation-comments': minor
+---
+
+Adds `cleanCode()` functionality.

packages/annotation-comments/README.md

@@ -74,6 +74,7 @@ type AnnotationComment = {
   tag: AnnotationTag
   contents: string[]
   commentRange: SourceRange
+  commentInnerRange: SourceRange
   annotationRange: SourceRange
   contentRanges: SourceRange[]
   targetRanges: SourceRange[]
@@ -100,9 +101,6 @@ export type SourceLocation = {
 
 ### cleanCode()
 
-> **Warning**
-> This function is not implemented yet.
-
 This function prepares annotated code lines for display or copying to the clipboard by making it look like regular (non-annotated) code again.
 
 It will collect all necessary edits and apply them to the code in reverse order (from the last edit location to the first) to avoid having to update the locations of all remaining annotations after each edit.
@@ -132,6 +130,7 @@ type HandleEditLineContext = {
   lineIndex: number
   startColumn: number
   endColumn: number
+  newText?: string | undefined
   codeLines: string[]
 }
 ```

packages/annotation-comments/src/core/clean.ts

@@ -1,4 +1,6 @@
-import type { AnnotatedCode, AnnotationComment } from './types'
+import { cloneRange, createSingleLineRange, excludeRangesFromOuterRange, mergeIntersectingOrAdjacentRanges, rangesAreEqual, splitRangeByLines } from '../internal/ranges'
+import { excludeWhitespaceRanges } from '../internal/text-content'
+import type { AnnotatedCode, AnnotationComment, SourceLocation, SourceRange } from './types'
 
 export type CleanCodeOptions = AnnotatedCode & {
 	removeAnnotationContents?: boolean | ((context: RemoveAnnotationContentsContext) => boolean)
@@ -11,19 +13,144 @@ export type RemoveAnnotationContentsContext = {
 	comment: AnnotationComment
 }
 
-export type HandleRemoveLineContext = {
-	lineIndex: number
+export type HandleCodeChangeContextBase = {
 	codeLines: string[]
 }
 
-export type HandleEditLineContext = {
+export type HandleRemoveLineContext = HandleCodeChangeContextBase & RemoveLine
+export type HandleEditLineContext = HandleCodeChangeContextBase & EditLine
+
+export type RemoveLine = {
+	editType: 'removeLine'
+	lineIndex: number
+}
+
+export type EditLine = {
+	editType: 'editLine'
 	lineIndex: number
 	startColumn: number
 	endColumn: number
-	codeLines: string[]
+	newText?: string | undefined
 }
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type SourceChange = RemoveLine | EditLine
+
 export function cleanCode(options: CleanCodeOptions) {
-	// TODO: Implement cleanCode()
+	const { codeLines, annotationComments, removeAnnotationContents = false, updateTargetRanges = true, handleRemoveLine, handleEditLine } = options
+
+	// Go through all annotation comments and collect an array of ranges to be removed
+	const rangesToBeRemoved: SourceRange[] = []
+	annotationComments.forEach((annotationComment) => {
+		const hasContents = annotationComment.contents.length > 0
+		const removeEntireAnnotation =
+			!hasContents || (typeof removeAnnotationContents === 'function' ? removeAnnotationContents({ comment: annotationComment }) : removeAnnotationContents)
+		const rangeToBeRemoved = cloneRange(removeEntireAnnotation ? annotationComment.annotationRange : annotationComment.tag.range)
+
+		// If we're removing an entire annotation, include up to one line of whitespace above it
+		const lineAboveIndex = rangeToBeRemoved.start.line - 1
+		if (removeEntireAnnotation && annotationComment.commentInnerRange.start.line < lineAboveIndex) {
+			const contentInLineAbove = excludeWhitespaceRanges(codeLines, [createSingleLineRange(lineAboveIndex)])
+			if (!contentInLineAbove.length) {
+				rangeToBeRemoved.start = { line: lineAboveIndex }
+			}
+		}
+
+		rangesToBeRemoved.push(rangeToBeRemoved)
+	})
+
+	// Remove any parent comments that would be empty after removing the annotations
+	const handledRanges: SourceRange[] = []
+	annotationComments.forEach(({ commentRange, commentInnerRange }) => {
+		if (handledRanges.some((range) => rangesAreEqual(range, commentInnerRange))) return
+		handledRanges.push(commentInnerRange)
+		// If the outer range is already in the list of ranges to be removed, skip this comment
+		if (rangesToBeRemoved.some((range) => rangesAreEqual(range, commentRange))) return
+		const remainingParts = excludeRangesFromOuterRange({
+			codeLines,
+			outerRange: commentInnerRange,
+			rangesToExclude: rangesToBeRemoved,
+		})
+		const nonWhitespaceParts = excludeWhitespaceRanges(codeLines, remainingParts)
+		// If the comment's inner range only contains whitespace after all removals,
+		// remove the entire comment
+		if (!nonWhitespaceParts.length) rangesToBeRemoved.push(commentRange)
+	})
+
+	// Build an array of changes by line to be applied to the code
+	const mergedRangesToBeRemoved = mergeIntersectingOrAdjacentRanges(rangesToBeRemoved)
+	const changes = mergedRangesToBeRemoved.flatMap((range) => getRangeRemovalChanges(codeLines, range))
+
+	// Apply the changes to the code in reverse order to avoid having to change edit locations
+	changes.reverse()
+	changes.forEach((change) => {
+		if (change.editType === 'removeLine') {
+			if (!handleRemoveLine || !handleRemoveLine({ codeLines, ...change })) {
+				codeLines.splice(change.lineIndex, 1)
+			}
+			if (updateTargetRanges) updateTargetRangesAfterRemoveLine(annotationComments, change)
+		} else {
+			if (!handleEditLine || !handleEditLine({ codeLines, ...change })) {
+				const line = codeLines[change.lineIndex]
+				codeLines[change.lineIndex] = line.slice(0, change.startColumn) + (change.newText ?? '') + line.slice(change.endColumn)
+			}
+			if (updateTargetRanges) updateTargetRangesAfterEditLine(annotationComments, change)
+		}
+	})
+}
+
+function updateTargetRangesAfterRemoveLine(annotationComments: AnnotationComment[], change: RemoveLine) {
+	annotationComments.forEach(({ targetRanges }) => {
+		targetRanges.forEach((targetRange, index) => {
+			if (targetRange.start.line === change.lineIndex) {
+				targetRanges.splice(index, 1)
+			} else if (targetRange.start.line > change.lineIndex) {
+				targetRange.start.line--
+				targetRange.end.line--
+			}
+		})
+	})
+}
+
+function updateTargetRangesAfterEditLine(annotationComments: AnnotationComment[], change: EditLine) {
+	annotationComments.forEach(({ targetRanges }) => {
+		targetRanges.forEach((targetRange) => {
+			updateLocationIfNecessary(targetRange.start, change)
+			updateLocationIfNecessary(targetRange.end, change)
+		})
+	})
+}
+
+function updateLocationIfNecessary(location: SourceLocation, change: EditLine) {
+	if (location.line !== change.lineIndex) return
+	if (!location.column || change.startColumn > location.column) return
+	const changeDelta = (change.newText?.length ?? 0) - (change.endColumn - change.startColumn)
+	location.column += changeDelta
+}
+
+function getRangeRemovalChanges(codeLines: string[], range: SourceRange): SourceChange[] {
+	const singleLineRanges = splitRangeByLines(range)
+
+	return singleLineRanges.map((singleLineRange) => {
+		const lineIndex = singleLineRange.start.line
+		const lineLength = codeLines[lineIndex].length
+		const {
+			start: { column: startColumn = 0 },
+			end: { column: endColumn = lineLength },
+		} = singleLineRange
+
+		if (startColumn > 0 || endColumn < lineLength) {
+			return {
+				editType: 'editLine',
+				lineIndex,
+				startColumn,
+				endColumn,
+				newText: '',
+			}
+		} else {
+			return {
+				editType: 'removeLine',
+				lineIndex,
+			}
+		}
+	})
 }

packages/annotation-comments/src/core/find-targets.ts

@@ -95,6 +95,6 @@ export function findAnnotationTargets(annotatedCode: AnnotatedCode) {
 			}
 		}
 		// In case of a negative direction, fix the potentially mixed up order of target ranges
-		if (relativeTargetRange < 0) targetRanges.sort((a, b) => compareRanges(b, a, 'start'))
+		if (relativeTargetRange < 0) targetRanges.sort((a, b) => compareRanges(a, b, 'start'))
 	})
 }

packages/annotation-comments/src/core/types.ts

@@ -9,6 +9,11 @@ export type AnnotationComment = {
 	 * In such cases, the comment range is larger than {@link AnnotationComment.annotationRange}.
 	 */
 	commentRange: SourceRange
+	/**
+	 * The inner range of the parent comment that contains the annotation,
+	 * excluding the comment's opening and closing syntax.
+	 */
+	commentInnerRange: SourceRange
 	/**
 	 * The outer range of the annotation, covering both the annotation tag and
 	 * any optional content.

packages/annotation-comments/src/internal/ranges.ts

@@ -14,6 +14,13 @@ export function createRange(options: { codeLines: string[]; start: SourceLocatio
 	return range
 }
 
+/**
+ * Returns a copy of the given source range.
+ */
+export function cloneRange(range: SourceRange): SourceRange {
+	return { start: { ...range.start }, end: { ...range.end } }
+}
+
 export function createSingleLineRange(lineIndex: number): SourceRange {
 	return { start: { line: lineIndex }, end: { line: lineIndex } }
 }
@@ -26,35 +33,149 @@ export function createSingleLineRanges(...lineIndices: number[]): SourceRange[]
  * Compares two source ranges by their start or end locations.
  *
  * Returns:
- * - `> 0` if the second location is **greater than** (comes after) the first,
- * - `< 0` if the second location is **smaller than** (comes before) the first, or
+ * - `> 0` if the first location is **greater than** (comes after) the second,
+ * - `< 0` if the first location is **smaller than** (comes before) the second, or
  * - `0` if they are equal.
  */
-export function compareRanges(a: SourceRange, b: SourceRange, prop: 'start' | 'end'): number {
+export function compareRanges(a: SourceRange, b: SourceRange, propA: 'start' | 'end', propB: 'start' | 'end' = propA): number {
 	// Compare line numbers first
-	const lineResult = b[prop].line - a[prop].line
+	const lineResult = a[propA].line - b[propB].line
 	if (lineResult !== 0) return lineResult
 
 	// Line numbers are equal, so compare columns
-	const aCol = a[prop].column
-	const bCol = b[prop].column
+	const aCol = a[propA].column
+	const bCol = b[propB].column
 
 	// If both columns are undefined, the ranges are equal
 	if (aCol === undefined && bCol === undefined) return 0
 
 	// If only one column is undefined (= covers the full line),
 	// the other column starts after and ends before it
-	if (aCol === undefined) return prop === 'start' ? 1 : -1
-	if (bCol === undefined) return prop === 'start' ? -1 : 1
+	if (aCol === undefined) return propA === 'start' ? -1 : 1
+	if (bCol === undefined) return propB === 'start' ? 1 : -1
 
-	return bCol - aCol
+	return aCol - bCol
+}
+
+export function rangesAreEqual(a: SourceRange, b: SourceRange): boolean {
+	return compareRanges(a, b, 'start') === 0 && compareRanges(a, b, 'end') === 0
 }
 
 export function secondRangeIsInFirst(potentialOuterRange: SourceRange, rangeToTest: SourceRange): boolean {
 	return (
 		// To be in range, rangeToTest must start at or after potentialOuterRange...
-		compareRanges(potentialOuterRange, rangeToTest, 'start') >= 0 &&
+		compareRanges(rangeToTest, potentialOuterRange, 'start') >= 0 &&
 		// ...and end at or before potentialOuterRange
-		compareRanges(potentialOuterRange, rangeToTest, 'end') <= 0
+		compareRanges(rangeToTest, potentialOuterRange, 'end') <= 0
 	)
 }
+
+/**
+ * Splits the given range that may span multiple lines into an array of single-line ranges.
+ */
+export function splitRangeByLines(range: SourceRange): SourceRange[] {
+	// For single-line ranges, just return a copy of the range
+	if (range.start.line === range.end.line) return [cloneRange(range)]
+
+	// For multi-line ranges, create a mix of column ranges and full line ranges as needed
+	const ranges: SourceRange[] = []
+	const isPartialStartLine = range.start.column ? range.start.column > 0 : false
+	const isPartialEndLine = range.end.column !== undefined
+
+	// If the range starts in the middle of a line, add an inline range
+	if (isPartialStartLine) {
+		ranges.push({
+			start: { line: range.start.line, column: range.start.column },
+			end: { line: range.start.line },
+		})
+	}
+	// Add all full line ranges
+	for (let lineIndex = range.start.line + (isPartialStartLine ? 1 : 0); lineIndex < range.end.line + (isPartialEndLine ? 0 : 1); lineIndex++) {
+		ranges.push(createSingleLineRange(lineIndex))
+	}
+	// If the range ends in the middle of a line, add an inline range
+	if (isPartialEndLine) {
+		ranges.push({
+			start: { line: range.end.line },
+			end: { line: range.end.line, column: range.end.column },
+		})
+	}
+	return ranges
+}
+
+/**
+ * Merges any intersecting or adjacent ranges in the given array of source ranges.
+ */
+export function mergeIntersectingOrAdjacentRanges(ranges: SourceRange[]): SourceRange[] {
+	const sortedRanges = ranges.slice().sort((a, b) => compareRanges(a, b, 'start'))
+	const mergedRanges: SourceRange[] = []
+	let currentRange: SourceRange | undefined
+	for (const newRange of sortedRanges) {
+		if (!currentRange) {
+			currentRange = cloneRange(newRange)
+			continue
+		}
+		// If the new range starts inside or right at the end of the current one,
+		// extend the current range if needed
+		if (compareRanges(newRange, currentRange, 'start', 'end') <= 0) {
+			if (compareRanges(newRange, currentRange, 'end') > 0) currentRange.end = newRange.end
+			continue
+		}
+		// Otherwise, we're done with the current range and can switch to the new one
+		mergedRanges.push(currentRange)
+		currentRange = cloneRange(newRange)
+	}
+	if (currentRange) mergedRanges.push(currentRange)
+	return mergedRanges
+}
+
+/**
+ * Excludes the given exclusion ranges from the outer range by splitting the outer range into
+ * multiple parts that do not overlap with the exclusions.
+ *
+ * The resulting array of source ranges is split by lines and can be a combination of partial
+ * and full line ranges. The array can also be empty if the outer range is completely covered
+ * by the exclusions.
+ */
+export function excludeRangesFromOuterRange(options: { codeLines: string[]; outerRange: SourceRange; rangesToExclude: SourceRange[] }): SourceRange[] {
+	const { codeLines, outerRange, rangesToExclude } = options
+
+	const remainingRanges: SourceRange[] = splitRangeByLines(outerRange)
+	const exclusionsSplitByLine = rangesToExclude.flatMap((exclusion) => splitRangeByLines(exclusion))
+
+	exclusionsSplitByLine.forEach((exclusion) => {
+		const lineIndex = exclusion.start.line
+		const lineLength = codeLines[lineIndex].length
+		const exclusionStartColumn = exclusion.start.column ?? 0
+		const exclusionEndColumn = exclusion.end.column ?? lineLength
+		for (let i = remainingRanges.length - 1; i >= 0; i--) {
+			const range = remainingRanges[i]
+			// If the range is on a different line, it cannot be affected by the exclusion
+			if (range.start.line !== lineIndex) continue
+			const rangeStartColumn = range.start.column ?? 0
+			const rangeEndColumn = range.end.column ?? lineLength
+			if (exclusionStartColumn <= rangeStartColumn && exclusionEndColumn >= rangeEndColumn) {
+				// The exclusion completely covers the range, so remove it
+				remainingRanges.splice(i, 1)
+			} else if (exclusionStartColumn <= rangeStartColumn && exclusionEndColumn < rangeEndColumn) {
+				// The exclusion overlaps with the start of the range, so adjust the range start
+				range.start.column = exclusionEndColumn
+			} else if (exclusionStartColumn > rangeStartColumn && exclusionEndColumn >= rangeEndColumn) {
+				// The exclusion overlaps with the end of the range, so adjust the range end
+				range.end.column = exclusionStartColumn
+			} else if (exclusionStartColumn > rangeStartColumn && exclusionEndColumn < rangeEndColumn) {
+				// The exclusion is inside the range, so split the range into two
+				// ...by making the current range end before the exclusion
+				range.end.column = exclusionStartColumn
+				// ...and inserting a new range that starts after the exclusion
+				//    and ends at the end of the current range
+				const rangeAfterExclusion = createSingleLineRange(lineIndex)
+				if (exclusionEndColumn > 0) rangeAfterExclusion.start.column = exclusionEndColumn
+				if (rangeEndColumn < lineLength) rangeAfterExclusion.end.column = rangeEndColumn
+				remainingRanges.splice(i + 1, 0, rangeAfterExclusion)
+			}
+		}
+	})
+
+	return remainingRanges
+}