Add commentRange / annotationRange separation

Author: hippotastic

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

@@ -17,11 +17,11 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 	const ignoreCountPerTagName = new Map<string, number>()
 	let tagsIgnoredUntilLineIndex = -1
 
-	let previousCommentRanges: SourceRange[] = []
+	let previousContentRanges: SourceRange[] = []
 	annotationTags.forEach((tag) => {
 		// Ignore the current tag if it is located inside the content ranges
 		// of the previously processed annotation comment
-		if (previousCommentRanges.some((range) => secondRangeIsInFirst(range, tag.range))) return
+		if (previousContentRanges.some((range) => secondRangeIsInFirst(range, tag.range))) return
 
 		// Attempt to find a comment that the current annotation tag is located in
 		const comment = parseParentComment({ codeLines, tag })
@@ -38,7 +38,7 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 		// Allow creating new ignores
 		if (tag.name === 'ignore-tags') {
 			// By definition, `ignore-tags` must be on its own line
-			if (comment.commentRange.start.column || comment.commentRange.end.column) return
+			if (comment.annotationRange.start.column || comment.annotationRange.end.column) return
 			const ignoreRange = tag.relativeTargetRange ?? 1
 			if (typeof tag.targetSearchQuery === 'string') {
 				const targetTagNames = tag.targetSearchQuery.split(',').map((name) => name.trim())
@@ -53,7 +53,7 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 
 		// If we arrive here, add the tag and comment to the list of annotation comments
 		annotationComments.push(comment)
-		previousCommentRanges = comment.contentRanges
+		previousContentRanges = comment.contentRanges
 	})
 
 	return annotationComments

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

@@ -1,7 +1,29 @@
 export type AnnotationComment = {
 	tag: AnnotationTag
 	contents: string[]
+	/**
+	 * The outer range of the parent comment that contains the annotation,
+	 * including the comment's opening and closing syntax.
+	 *
+	 * Note that multi-line comments can contain multiple annotations and non-annotation content.
+	 * In such cases, {@link AnnotationComment.commentRange} is larger than
+	 * {@link AnnotationComment.annotationRange}.
+	 */
 	commentRange: SourceRange
+	/**
+	 * The outer range of the annotation, covering both the annotation tag and
+	 * any optional content.
+	 *
+	 * If the parent comment only contains this annotation and nothing else,
+	 * this range is equal to {@link AnnotationComment.commentRange}, which includes
+	 * the comment's opening and closing syntax. This allows removing the annotation
+	 * from the code without leaving an empty comment behind.
+	 *
+	 * In all other cases, this range covers only the parts inside the parent comment
+	 * that belong to this annotation. This allows removing the annotation without
+	 * affecting other annotations or non-annotation content inside the parent comment.
+	 */
+	annotationRange: SourceRange
 	contentRanges: SourceRange[]
 	targetRanges: SourceRange[]
 }

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

@@ -1,13 +1,16 @@
-import type { SourceRange } from '../core/types'
+import type { SourceLocation, SourceRange } from '../core/types'
 
-export function createRange(options: { line: string; lineIndex: number; startColumn: number; endColumn: number }) {
-	const { line, lineIndex, startColumn, endColumn } = options
+/**
+ * Creates a new source range object from the given start and end locations.
+ */
+export function createRange(options: { codeLines: string[]; start: SourceLocation; end: SourceLocation }) {
+	const { codeLines, start, end } = options
 	const range: SourceRange = {
-		start: { line: lineIndex },
-		end: { line: lineIndex },
+		start: { line: start.line },
+		end: { line: end.line },
 	}
-	if (startColumn > 0) range.start.column = startColumn
-	if (endColumn < line.length) range.end.column = endColumn
+	if (start.column ?? 0 > 0) range.start.column = start.column
+	if (end.column && end.column < (codeLines[end.line] ?? '').length) range.end.column = end.column
 	return range
 }
 

packages/annotation-comments/src/parsers/comment-types/multi-line.ts

@@ -158,16 +158,14 @@ function findCommentSyntaxMatches(options: {
 				if (syntax[type] !== sequence.delimiter) return
 				// Otherwise, set the ranges and mark the array as updated
 				match[delimiterProp] = createRange({
-					line,
-					lineIndex,
-					startColumn: sequence.index,
-					endColumn: sequence.index + sequence.delimiter.length,
+					codeLines,
+					start: { line: lineIndex, column: sequence.index },
+					end: { line: lineIndex, column: sequence.index + sequence.delimiter.length },
 				})
 				match[whitespaceProp] = createRange({
-					line,
-					lineIndex,
-					startColumn: sequence.index - sequence.leadingWhitespace.length,
-					endColumn: sequence.index + sequence.delimiter.length + sequence.trailingWhitespace.length,
+					codeLines,
+					start: { line: lineIndex, column: sequence.index - sequence.leadingWhitespace.length },
+					end: { line: lineIndex, column: sequence.index + sequence.delimiter.length + sequence.trailingWhitespace.length },
 				})
 				foundNewMatches = true
 			})
@@ -254,28 +252,40 @@ function getCommentFromMatchingSyntaxPair(options: {
 		const syntax = multiLineCommentSyntaxes[bestMatchIndex]
 		const isOnSingleLine = match.openingRange.start.line === match.closingRange.end.line
 		const isOnSingleLineBeforeCode = isOnSingleLine && match.closingRangeWithWhitespace.end.column
-		const commentRange: SourceRange = {
+		const commentRange = createRange({
+			codeLines,
 			start: isOnSingleLineBeforeCode ? match.openingRange.start : match.openingRangeWithWhitespace.start,
 			end: match.closingRangeWithWhitespace.end,
-		}
-		const innerRange: SourceRange = {
+		})
+		// By default, assume that the annotation is the only content of the current comment
+		// (this will be adjusted later if another annotation or non-annotation content is found)
+		const annotationRange = createRange({
+			codeLines,
+			start: commentRange.start,
+			end: commentRange.end,
+		})
+
+		// Now determine and go through the comment's inner range to collect all contents
+		const commentInnerRange = createRange({
+			codeLines,
 			start: match.openingRangeWithWhitespace.end,
 			end: match.closingRangeWithWhitespace.start,
-		}
+		})
 		// If the opening sequence ends at a line boundary, adjust the inner range to exclude it
-		if (!innerRange.start.column && !isOnSingleLine) {
-			innerRange.start = { line: innerRange.start.line + 1 }
+		if (!commentInnerRange.start.column && !isOnSingleLine) {
+			commentInnerRange.start = { line: commentInnerRange.start.line + 1 }
 		}
 		// If the closing sequence starts on a line boundary, adjust the inner range to exclude it
-		if (!innerRange.end.column && !isOnSingleLine) {
-			innerRange.end = { line: innerRange.end.line - 1 }
+		if (!commentInnerRange.end.column && !isOnSingleLine) {
+			commentInnerRange.end = { line: commentInnerRange.end.line - 1 }
 		}
+
 		const contents: string[] = []
 		const contentRanges: SourceRange[] = []
 
-		for (let lineIndex = innerRange.start.line; lineIndex <= innerRange.end.line; lineIndex++) {
-			const startColumn = lineIndex === tag.range.end.line ? tag.range.end.column : lineIndex === innerRange.start.line ? innerRange.start.column : undefined
-			const endColumn = lineIndex === innerRange.end.line ? innerRange.end.column : undefined
+		for (let lineIndex = commentInnerRange.start.line; lineIndex <= commentInnerRange.end.line; lineIndex++) {
+			const startColumn = lineIndex === tag.range.end.line ? tag.range.end.column : lineIndex === commentInnerRange.start.line ? commentInnerRange.start.column : undefined
+			const endColumn = lineIndex === commentInnerRange.end.line ? commentInnerRange.end.column : undefined
 
 			const lineContent = getTextContentInLine({
 				codeLines,
@@ -286,26 +296,26 @@ function getCommentFromMatchingSyntaxPair(options: {
 			})
 			if (lineIndex < tag.range.end.line) {
 				// If the current comment line has content and is located before the annotation tag,
-				// we need to reduce the comment range to exclude any non-annotation content
+				// we need to reduce the annotation range to exclude any non-annotation content
 				// including the opening and closing comment syntaxes, so removing the annotation
 				// later doesn't break the commment
 				if (lineContent.content.length) {
-					commentRange.start = { line: tag.range.start.line }
-					commentRange.end = { ...innerRange.end }
+					annotationRange.start = { line: tag.range.start.line }
+					annotationRange.end = { ...commentInnerRange.end }
 				}
 			} else if (lineIndex >= tag.range.end.line && lineContent.content === '---') {
 				// We encountered a separator line after the annotation tag, so this is a mixed
-				// comment with multiple pieces of content and we must limit the comment range
+				// comment with multiple pieces of content and we must limit the annotation range
 				// to the current annotation (however, we still include the separator line)
-				commentRange.start = { line: tag.range.start.line }
-				commentRange.end = { line: lineIndex }
+				annotationRange.start = { line: tag.range.start.line }
+				annotationRange.end = { line: lineIndex }
 				break
 			} else if (lineIndex >= tag.range.end.line && lineContent.content.startsWith('[!')) {
 				// We encountered the beginning of another annotation tag, so this is a mixed
-				// comment with multiple pieces of content and we must limit the comment range
+				// comment with multiple pieces of content and we must limit the annotation range
 				// to the current annotation
-				commentRange.start = { line: tag.range.start.line }
-				commentRange.end = { line: lineIndex - 1 }
+				annotationRange.start = { line: tag.range.start.line }
+				annotationRange.end = { line: lineIndex - 1 }
 				break
 			} else {
 				contents.push(lineContent.content)
@@ -327,6 +337,7 @@ function getCommentFromMatchingSyntaxPair(options: {
 			tag,
 			contents,
 			commentRange,
+			annotationRange,
 			contentRanges,
 			targetRanges: [],
 		}

packages/annotation-comments/src/parsers/comment-types/single-line.ts

@@ -1,7 +1,8 @@
-import type { AnnotationComment } from '../../core/types'
+import type { AnnotationComment, SourceRange } from '../../core/types'
 import type { ParseParentCommentOptions } from '../parent-comment'
 import { escapeRegExp } from '../../internal/escaping'
 import { getTextContentInLine } from '../text-content'
+import { createRange } from '../../internal/ranges'
 
 const singleLineCommentSyntaxes: string[] = [
 	// JS, TS, Java, C, C++, C#, F#, Rust, Go, etc.
@@ -47,20 +48,17 @@ export function parseSingleLineParentComment(options: ParseParentCommentOptions)
 	const singleLineCommentSyntax = singleLineCommentSyntaxMatches.find((match) => match.endColumn === tag.range.start.column)
 	if (singleLineCommentSyntax) {
 		// We found a single-line annotation comment, so start collecting its details
-		const comment: AnnotationComment = {
-			tag,
-			contents: [],
-			commentRange: {
-				start: { line: tagLineIndex },
-				end: { line: tagLineIndex },
-			},
-			contentRanges: [],
-			targetRanges: [],
-		}
+		const commentRange = createRange({
+			codeLines,
+			start: { line: tagLineIndex },
+			end: { line: tagLineIndex },
+		})
+		const contents: string[] = []
+		const contentRanges: SourceRange[] = []
 		// If there is code before the comment, remember the comment start column
 		// to avoid deleting the entire line when removing the comment
 		if (tagLine.slice(0, singleLineCommentSyntax.startColumn).trim() !== '') {
-			comment.commentRange.start.column = singleLineCommentSyntax.startColumn
+			commentRange.start.column = singleLineCommentSyntax.startColumn
 		}
 		// For common Shiki transformer syntax compatibility, support chaining multiple
 		// single-line annotation comments on the same line
@@ -74,14 +72,14 @@ export function parseSingleLineParentComment(options: ParseParentCommentOptions)
 				tagLine.slice(match.endColumn).startsWith('[!')
 		)
 		if (chainedSingleLineCommentSyntax) {
-			comment.commentRange.end.column = chainedSingleLineCommentSyntax.startColumn
+			commentRange.end.column = chainedSingleLineCommentSyntax.startColumn
 		}
 		// If there is any non-whitespace content between the end of the annotation tag
 		// and the current end of the comment, add it to the contents and contentRanges arrays
-		const tagLineContent = getTextContentInLine({ codeLines, lineIndex: tagLineIndex, startColumn: tagEndColumn, endColumn: comment.commentRange.end.column })
+		const tagLineContent = getTextContentInLine({ codeLines, lineIndex: tagLineIndex, startColumn: tagEndColumn, endColumn: commentRange.end.column })
 		if (tagLineContent.content) {
-			comment.contents.push(tagLineContent.content)
-			comment.contentRanges.push(tagLineContent.contentRange)
+			contents.push(tagLineContent.content)
+			contentRanges.push(tagLineContent.contentRange)
 		}
 		// For supported annotation comments, allow expanding the comment end location
 		// and annotation content to subsequent comment lines
@@ -107,27 +105,37 @@ export function parseSingleLineParentComment(options: ParseParentCommentOptions)
 					// Stop if the line has `---` as its only text content
 					if (lineContent.content === '---') {
 						// Make the line part of the comment, but don't add its content
-						comment.commentRange.end = { line: lineIndex }
+						commentRange.end = { line: lineIndex }
 						break
 					}
 					// Stop if the line starts with an annotation tag opening sequence `[!`
 					if (lineContent.content.startsWith('[!')) break
 					// Otherwise, add the content and expand the comment range
 					// to cover the additional full line
-					comment.contents.push(lineContent.content)
-					comment.contentRanges.push(lineContent.contentRange)
-					comment.commentRange.end = { line: lineIndex }
+					contents.push(lineContent.content)
+					contentRanges.push(lineContent.contentRange)
+					commentRange.end = { line: lineIndex }
 				} else {
 					// Comment lines without content are allowed, so an empty string to the content
 					// and expand the comment range to cover the additional full line
 					const column = Math.min(possibleContentStart, line.length)
-					comment.contents.push('')
-					comment.contentRanges.push({ start: { line: lineIndex, column }, end: { line: lineIndex, column } })
-					comment.commentRange.end = { line: lineIndex }
+					contents.push('')
+					contentRanges.push({ start: { line: lineIndex, column }, end: { line: lineIndex, column } })
+					commentRange.end = { line: lineIndex }
 				}
 			}
 		}
 
-		return comment
+		// For single-line comments, the annotation range is always equal to the comment range
+		const annotationRange = createRange({ codeLines, start: commentRange.start, end: commentRange.end })
+
+		return {
+			tag,
+			contents,
+			commentRange,
+			annotationRange,
+			contentRanges,
+			targetRanges: [],
+		}
 	}
 }