Implement line targeting & search logic, tests

hippotastic · hippotastic · commit 9f4a9a8de4db · 2024-09-20T01:18:08.000+02:00
diff --git a/packages/annotation-comments/src/core/find-targets.ts b/packages/annotation-comments/src/core/find-targets.ts
@@ -1,5 +1,6 @@
 import type { AnnotationComment, SourceRange } from './types'
-import { compareRanges, createSingleLineRange } from '../internal/ranges'
+import { compareRanges, createRange, createSingleLineRange } from '../internal/ranges'
+import { getGroupIndicesFromRegExpMatch } from '../internal/regexps'
 
 export type FindAnnotationTargetsOptions = {
 	codeLines: string[]
@@ -9,71 +10,102 @@ export type FindAnnotationTargetsOptions = {
 export function findAnnotationTargets(options: FindAnnotationTargetsOptions) {
 	const { codeLines, annotationComments } = options
 
-	// TODO: Finish implementation
 	annotationComments.forEach((comment) => {
-		const annotationLineIndex = comment.annotationRange.start.line
-		const annotationLineContents = getNonAnnotationCommentLineContents(annotationLineIndex, options)
-
-		// If the annotation has no relative target range and no target search query,
-		// try to find a nearby target line that is not empty and not an annotation comment
-		if (comment.tag.relativeTargetRange === undefined && comment.tag.targetSearchQuery === undefined) {
-			// Check if the annotation line itself is a valid target
-			if (annotationLineContents.hasNonWhitespaceContent) {
-				return comment.targetRanges.push(createSingleLineRange(annotationLineIndex))
-			}
-			// Otherwise, scan for a target line below
-			const potentialTargetBelow = getFirstNonAnnotationCommentLineContents(annotationLineIndex, 'below', options)
-			if (potentialTargetBelow?.hasNonWhitespaceContent) {
-				return comment.targetRanges.push(createSingleLineRange(potentialTargetBelow.lineIndex))
+		const { tag, commentRange, annotationRange, targetRanges } = comment
+
+		// We don't need to search for `ignore-tags` annotation targets
+		// as ignores are handled by the annotation comment parser
+		if (tag.name === 'ignore-tags') return
+
+		const commentLineIndex = commentRange.start.line
+		const commentLineContents = getNonAnnotationCommentLineContents(commentLineIndex, options)
+		let { relativeTargetRange } = tag
+		const { targetSearchQuery } = tag
+
+		// Handle annotations without a target search query (they target full lines)
+		if (targetSearchQuery === undefined) {
+			// If the annotation has no relative target range, try to find a nearby target line
+			// that is not empty and not an annotation comment
+			if (relativeTargetRange === undefined) {
+				// Check if the annotation comment line itself is a valid target
+				if (commentLineContents.hasNonWhitespaceContent) {
+					return targetRanges.push(createSingleLineRange(commentLineIndex))
+				}
+				// Otherwise, scan for a target line below
+				const potentialTargetBelow = getFirstNonAnnotationCommentLineContents(commentLineIndex, 'below', options)
+				if (potentialTargetBelow?.hasNonWhitespaceContent) {
+					return targetRanges.push(createSingleLineRange(potentialTargetBelow.lineIndex))
+				}
+				// Finally, scan for a target line above
+				const potentialTargetAbove = getFirstNonAnnotationCommentLineContents(commentLineIndex, 'above', options)
+				if (potentialTargetAbove?.hasNonWhitespaceContent) {
+					return targetRanges.push(createSingleLineRange(potentialTargetAbove.lineIndex))
+				}
+				// If we arrive here, there is no target range (same as the relative range `:0`),
+				// so don't do anything
+				return
 			}
-			// Finally, scan for a target line above
-			const potentialTargetAbove = getFirstNonAnnotationCommentLineContents(annotationLineIndex, 'above', options)
-			if (potentialTargetAbove?.hasNonWhitespaceContent) {
-				return comment.targetRanges.push(createSingleLineRange(potentialTargetAbove.lineIndex))
+			// It has a relative target range, so select the number of non-annotation lines
+			// in the given direction, starting with the comment line
+			const step = relativeTargetRange > 0 ? 1 : -1
+			let lineIndex = commentLineIndex
+			let remainingLines = Math.abs(relativeTargetRange)
+			while (lineIndex >= 0 && lineIndex < codeLines.length && remainingLines > 0) {
+				// Check if the line is a valid target
+				const lineContents = getNonAnnotationCommentLineContents(lineIndex, options)
+				if (lineContents.contentRanges.length) {
+					targetRanges.push(createSingleLineRange(lineIndex))
+					remainingLines--
+				}
+				lineIndex += step
 			}
-			// If we arrive here, there is no target range (same as the relative range `:0`),
-			// so don't do anything
-			return
 		}
 
 		// If a target search query is present, perform the search to determine the target range(s)
-		if (comment.tag.targetSearchQuery) {
+		if (targetSearchQuery) {
 			// Read the direction and number of matches to find from the tag,
 			// or auto-detect this in case no relative target range was given
-			let relativeTargetRange = comment.tag.relativeTargetRange
 			if (relativeTargetRange === undefined) {
-				if (annotationLineContents.hasNonWhitespaceContent) {
+				if (commentLineContents.hasNonWhitespaceContent) {
 					// The annotation comment is on the same line as content, so the direction
-					// depends on where the content is in relation to the comment
-					const hasContentBeforeAnnotation = annotationLineContents.nonWhitespaceContentRanges.some(
-						(contentRange) => compareRanges(comment.annotationRange, contentRange, 'start') < 0
+					// depends on where the content is in relation to the annotation
+					const hasContentBeforeAnnotation = commentLineContents.nonWhitespaceContentRanges.some(
+						// Check for non-whitespace content that starts before the annotation
+						(contentRange) => compareRanges(annotationRange, contentRange, 'start') < 0
 					)
 					relativeTargetRange = hasContentBeforeAnnotation ? -1 : 1
 				} else {
 					// Otherwise, the direction defaults to downwards, unless the annotation comment
 					// is visually grouped with content above it (= there no content directly below
 					// the annotation comment(s), but there is content directly above)
 					const isGroupedWithContentAbove =
-						!getFirstNonAnnotationCommentLineContents(annotationLineIndex, 'below', options)?.hasNonWhitespaceContent &&
-						getFirstNonAnnotationCommentLineContents(annotationLineIndex, 'above', options)?.hasNonWhitespaceContent
+						!getFirstNonAnnotationCommentLineContents(commentLineIndex, 'below', options)?.hasNonWhitespaceContent &&
+						getFirstNonAnnotationCommentLineContents(commentLineIndex, 'above', options)?.hasNonWhitespaceContent
 					relativeTargetRange = isGroupedWithContentAbove ? -1 : 1
 				}
 			}
 
-			// - Perform the search:
-			//   - The target search query can be a simple string, a single-quoted string, a double-quoted
-			//     string, or a regular expression. Regular expressions can optionally contain capture groups,
-			//     which will then be used to determine the target range(s) instead of the full match.
-			//   - The search is performed line by line, starting at the start or end of the annotation comment
-			//     and going in the direction determined by the relative target range that was either given or
-			//     automatically determined as described above.
-			//   - Before searching a line for matches, all characters that lie within the `outerRange` of any
-			//     annotation comment are removed from the line. If matches are found, the matched ranges are
-			//     adjusted to include the removed characters.
-			//   - Each match is added to the `targetRanges` until the number of matches equals the absolute
-			//     value of the relative target range, or the end of the code is reached.
-			//   - In the case of regular expressions with capture groups, a single match can result in multiple
-			//     target ranges, one for each capture group.
+			// Perform the search
+			const step = relativeTargetRange > 0 ? 1 : -1
+			let lineIndex = commentLineIndex
+			let remainingMatches = Math.abs(relativeTargetRange)
+			while (lineIndex >= 0 && lineIndex < codeLines.length && remainingMatches > 0) {
+				// Search all ranges of the line that are not part of an annotation comment
+				// for matches of the target search query
+				const lineContents = getNonAnnotationCommentLineContents(lineIndex, options)
+				const matches = lineContents.contentRanges.flatMap((contentRange) => findSearchQueryMatchesInLine(targetSearchQuery, contentRange, options))
+				if (matches.length) {
+					// Go through the matches in the direction of the relative target range
+					// until we have found the required number of matches
+					let matchIndex = relativeTargetRange > 0 ? 0 : matches.length - 1
+					while (matchIndex >= 0 && matchIndex < matches.length && remainingMatches > 0) {
+						targetRanges.push(matches[matchIndex])
+						remainingMatches--
+						matchIndex += step
+					}
+				}
+				lineIndex += step
+			}
 		}
 	})
 }
@@ -145,3 +177,65 @@ function getFirstNonAnnotationCommentLineContents(startLineIndex: number, search
 		lineIndex += step
 	}
 }
+
+/**
+ * Searches the given column range on a single line for matches of the given search query,
+ * and returns an array of source ranges that represent the matches.
+ */
+function findSearchQueryMatchesInLine(searchQuery: string | RegExp, rangeToSearch: SourceRange, options: FindAnnotationTargetsOptions) {
+	const { codeLines } = options
+	const lineIndex = rangeToSearch.start.line
+	const startColumn = rangeToSearch.start.column ?? 0
+	const content = codeLines[lineIndex].slice(startColumn, rangeToSearch.end.column)
+
+	const ranges: SourceRange[] = []
+
+	// Handle plaintext string search terms
+	if (typeof searchQuery === 'string') {
+		let idx = content.indexOf(searchQuery, 0)
+		while (idx > -1) {
+			ranges.push(
+				createRange({
+					codeLines,
+					start: { line: lineIndex, column: startColumn + idx },
+					end: { line: lineIndex, column: startColumn + idx + searchQuery.length },
+				})
+			)
+			idx = content.indexOf(searchQuery, idx + searchQuery.length)
+		}
+	}
+
+	// Handle regular expression search terms
+	if (searchQuery instanceof RegExp) {
+		const matches = content.matchAll(searchQuery)
+		for (const match of matches) {
+			const rawGroupIndices = getGroupIndicesFromRegExpMatch(match)
+			// Remove null group indices
+			let groupIndices = rawGroupIndices.flatMap((range) => (range ? [range] : []))
+			// If there are no non-null indices, use the full match instead
+			// (capture group feature fallback, impossible to cover in tests)
+			/* c8 ignore start */
+			if (!groupIndices.length) {
+				groupIndices = [[match.index, match.index + match[0].length]]
+			}
+			/* c8 ignore end */
+			// If there are multiple non-null indices, remove the first one
+			// as it is the full match and we only want to mark capture groups
+			if (groupIndices.length > 1) {
+				groupIndices.shift()
+			}
+			// Create marked ranges from all remaining group indices
+			groupIndices.forEach((range) => {
+				ranges.push(
+					createRange({
+						codeLines,
+						start: { line: lineIndex, column: startColumn + range[0] },
+						end: { line: lineIndex, column: startColumn + range[1] },
+					})
+				)
+			})
+		}
+	}
+
+	return ranges
+}
diff --git a/packages/annotation-comments/src/core/parse.ts b/packages/annotation-comments/src/core/parse.ts
@@ -2,6 +2,7 @@ import type { AnnotationComment, SourceRange } from './types'
 import { parseAnnotationTags } from '../parsers/annotation-tags'
 import { parseParentComment } from '../parsers/parent-comment'
 import { secondRangeIsInFirst } from '../internal/ranges'
+import { findAnnotationTargets } from './find-targets'
 
 export type ParseAnnotationCommentsOptions = {
 	codeLines: string[]
@@ -57,7 +58,8 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 		previousContentRanges = comment.contentRanges
 	})
 
-	// TODO: Call findAnnotationTargets() here
+	// Find the target ranges for all annotations
+	findAnnotationTargets({ codeLines, annotationComments })
 
 	return annotationComments
 }
diff --git a/packages/annotation-comments/src/core/types.ts b/packages/annotation-comments/src/core/types.ts
@@ -6,8 +6,7 @@ export type AnnotationComment = {
 	 * 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}.
+	 * In such cases, the comment range is larger than {@link AnnotationComment.annotationRange}.
 	 */
 	commentRange: SourceRange
 	/**
diff --git a/packages/annotation-comments/src/internal/regexps.ts b/packages/annotation-comments/src/internal/regexps.ts
@@ -23,3 +23,34 @@ export function createGlobalRegExp(pattern: string | RegExp, extraFlags?: string
 	}
 	return regExp
 }
+
+/**
+ * Retrieves all group indices from the given RegExp match. Group indices are ranges
+ * defined by start & end positions. The first group index refers to the full match,
+ * and the following indices to RegExp capture groups (if any).
+ *
+ * If the RegExp flag `d` was enabled (and supported), it returns the native group indices.
+ *
+ * Otherwise, it uses fallback logic to manually search for the group contents inside the
+ * full match. Note that this can be wrong if a group's contents can be found multiple times
+ * inside the full match, but that's probably a rare case and still better than failing.
+ */
+export function getGroupIndicesFromRegExpMatch(match: RegExpMatchArray) {
+	// Read the start and end ranges from the `indices` property,
+	// which is made available through the RegExp flag `d`
+	let groupIndices = match.indices as ([start: number, end: number] | null)[]
+	if (groupIndices?.length) return groupIndices
+
+	// We could not access native group indices, so we need to use fallback logic
+	// to find the position of each capture group match inside the full match
+	const fullMatchIndex = match.index as number
+	groupIndices = match.map((groupValue) => {
+		const groupIndex = groupValue ? match[0].indexOf(groupValue) : -1
+		if (groupIndex === -1) return null
+		const groupStart = fullMatchIndex + groupIndex
+		const groupEnd = groupStart + groupValue.length
+		return [groupStart, groupEnd]
+	})
+
+	return groupIndices
+}
diff --git a/packages/annotation-comments/test/parent-comment.test.ts b/packages/annotation-comments/test/parent-comment.test.ts
@@ -2,43 +2,41 @@ import { describe, expect, test } from 'vitest'
 import type { AnnotationComment, SourceRange } from '../src/core/types'
 import { parseAnnotationTags } from '../src/parsers/annotation-tags'
 import { parseParentComment } from '../src/parsers/parent-comment'
-import { splitCodeLines } from './utils'
+import { splitCodeLines, validateAnnotationComment } from './utils'
 
 describe('parseParentComment()', () => {
 	describe('Returns undefined when no valid parent comment is found', () => {
 		describe('Single-line comment syntax', () => {
 			test('No comment syntax in the same line', () => {
-				expect(getParentComment(`console.log('This is [!ins] in a string')`)).toEqual(undefined)
+				expect(getParentComment([`console.log('This is [!ins] in a string'])`])).toEqual(undefined)
 			})
 			test('Comment syntax located after the annotation tag', () => {
-				expect(getParentComment(`console.log('More [!test] text') // Hi!`)).toEqual(undefined)
+				expect(getParentComment([`console.log('More [!test] text') // Hi!]`])).toEqual(undefined)
 			})
 			test('Missing whitespace before comment opening syntax', () => {
-				expect(getParentComment(`someCode()// [!note] Invalid syntax`)).toEqual(undefined)
+				expect(getParentComment([`someCode()// [!note] Invalid syntax`])).toEqual(undefined)
 			})
 			test('Missing whitespace before annotation tag', () => {
-				expect(getParentComment(`someCode() //[!note] Invalid syntax`)).toEqual(undefined)
+				expect(getParentComment([`someCode() //[!note] Invalid syntax`])).toEqual(undefined)
 			})
 			test('Content between comment opening and annotation tag', () => {
-				expect(getParentComment(`someCode() // Hi [!note] This will not work`)).toEqual(undefined)
+				expect(getParentComment([`someCode() // Hi [!note] This will not work`])).toEqual(undefined)
 			})
 		})
 		describe('Multi-line comment syntax', () => {
 			test('Content between the opening syntax and the annotation tag', () => {
-				expect(getParentComment(`/* Hi [!note] This will not work */`)).toEqual(undefined)
-				expect(getParentComment(`someCode() /* Hi [!note] This will not work */`)).toEqual(undefined)
+				expect(getParentComment([`/* Hi [!note] This will not work */`])).toEqual(undefined)
+				expect(getParentComment([`someCode() /* Hi [!note] This will not work */`])).toEqual(undefined)
 			})
 			test('Content between the beginning of the line and the annotation tag', () => {
 				expect(
-					getParentComment(
-						[
-							'someCode()',
-							'/*',
-							// Content before the annotation tag
-							'Hi [!note] This will not work',
-							'*/',
-						].join('\n')
-					)
+					getParentComment([
+						'someCode()',
+						'/*',
+						// Content before the annotation tag
+						'Hi [!note] This will not work',
+						'*/',
+					])
 				).toEqual(undefined)
 			})
 		})
@@ -616,7 +614,6 @@ describe('parseParentComment()', () => {
 					validateParentComment({
 						lines,
 						contents: ['Look, a note!'],
-						// Expect the space between the code and the comment to be included
 						commentRange: { start: { line: 4 }, end: { line: 4 } },
 					})
 				})
@@ -636,7 +633,6 @@ describe('parseParentComment()', () => {
 					validateParentComment({
 						lines,
 						contents: ['Look, a note!'],
-						// Expect the space between the code and the comment to be included
 						commentRange: { start: { line: 4 }, end: { line: 6 } },
 					})
 				})
@@ -716,30 +712,17 @@ console.log('Done!')
 		`
 	}
 
-	function getParentComment(code: string) {
-		const codeLines = splitCodeLines(code)
+	function getParentComment(codeLines: string[]) {
 		const annotationTags = parseAnnotationTags({ codeLines })
 		expect(annotationTags.length, 'No annotation tag was found in test code').toBeGreaterThanOrEqual(1)
 		const tag = annotationTags[0]
 		return parseParentComment({ codeLines, tag })
 	}
 
 	function validateParentComment(options: { lines: string[]; contents: string[]; commentRange: SourceRange; annotationRange?: SourceRange | undefined }) {
-		const comment = getParentComment(getTestCode(options.lines.join('\n'))) as AnnotationComment
-		expect(comment.contents).toEqual(options.contents)
-		expect(comment.commentRange).toEqual(options.commentRange)
-		expect(comment.annotationRange).toEqual(options.annotationRange ?? options.commentRange)
+		const codeLines = splitCodeLines(getTestCode(options.lines.join('\n')))
+		const comment = getParentComment(codeLines) as AnnotationComment
 
-		const contentToSourceRange = (content: string) => {
-			for (let lineIndex = 0; lineIndex < options.lines.length; lineIndex++) {
-				const column = options.lines[lineIndex].indexOf(content)
-				if (column === -1) continue
-				const range: SourceRange = { start: { line: lineIndex + 2 }, end: { line: lineIndex + 2 } }
-				if (column > 0) range.start.column = column
-				if (column + content.length < options.lines[lineIndex].length) range.end.column = column + content.length
-				return range
-			}
-		}
-		expect(comment.contentRanges).toEqual(options.contents.map(contentToSourceRange))
+		validateAnnotationComment(comment, codeLines, options)
 	}
 })
diff --git a/packages/annotation-comments/test/parse.test.ts b/packages/annotation-comments/test/parse.test.ts
diff --git a/packages/annotation-comments/test/utils.ts b/packages/annotation-comments/test/utils.ts
