Add RegExp support to tag parser

Author: hippotastic

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

@@ -18,13 +18,12 @@ export type AnnotationTag = {
 	 * located inside the annotation tag.
 	 *
 	 * This query can be used to search for the target of the annotation.
-	 * It can be a plaintext term, optionally within single or double quotes,
-	 * or a regular expression within forward slashes `/`.
+	 * It can be a string or a regular expression.
 	 *
 	 * Example: The tag `[!ins:Astro.props]` targets the next occurrence
 	 * of the plaintext search term `Astro.props`.
 	 */
-	targetSearchQuery?: string | undefined
+	targetSearchQuery?: string | RegExp | undefined
 	/**
 	 * The optional relative target range of the annotation,
 	 * located inside the annotation tag.

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

@@ -0,0 +1,12 @@
+/**
+ * Converts possible try-catch error value types to a standard object format.
+ *
+ * @param error Error object, which could be string, Error, or ResolveMessage.
+ * @returns object containing message and, if present, error code.
+ */
+export function coerceError(error: unknown): { message: string; code?: string | undefined } {
+	if (typeof error === 'object' && error !== null && 'message' in error) {
+		return error as { message: string; code?: string | undefined }
+	}
+	return { message: error as string }
+}

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

@@ -12,5 +12,5 @@ export function escapeRegExp(input: string) {
  * to be escaped in the first place.
  */
 export function getEscapeSequenceRegExp(...valueEndDelimiters: string[]): RegExp {
-	return new RegExp(`\\\\(${['\\', ...valueEndDelimiters].map(escapeRegExp).join('|')})`, 'g')
+	return new RegExp(`\\\\(${valueEndDelimiters.map(escapeRegExp).join('|')})`, 'g')
 }

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

@@ -0,0 +1,25 @@
+import { coerceError } from './errors'
+
+/**
+ * Takes a string or existing regular expression as input and returns a regular expression
+ * that has the global flag set.
+ *
+ * If supported by the platform this code is running on, it will also set the `d` flag that
+ * enables capture group indices.
+ */
+export function parseAsGlobalRegExp(pattern: string | RegExp, extraFlags?: string): RegExp {
+	let regExp: RegExp | undefined
+	try {
+		// Try to use regular expressions with capture group indices
+		regExp = new RegExp(pattern, 'gd' + (extraFlags || ''))
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	} catch (_error) {
+		try {
+			// Use fallback if unsupported
+			regExp = new RegExp(pattern, 'g' + (extraFlags || ''))
+		} catch (error) {
+			throw new Error(`Failed to parse \`${pattern}\` as regular expression: ${coerceError(error).message}`)
+		}
+	}
+	return regExp
+}

packages/annotation-comments/src/internal/tag-parser.ts

@@ -1,5 +1,6 @@
 import { AnnotationTag } from '../core/types'
 import { getEscapeSequenceRegExp } from './escaping'
+import { parseAsGlobalRegExp } from './regexps'
 
 type ParseAnnotationTagsOptions = {
 	codeLines: string[]
@@ -73,20 +74,28 @@ const annotationTagRegex = new RegExp(
 	'g'
 )
 
-const unquotedValueEscapeSequence = getEscapeSequenceRegExp(':', ']')
-const quotedValueEscapeSequences = new Map<string, RegExp>([
-	['"', getEscapeSequenceRegExp('"')],
-	["'", getEscapeSequenceRegExp("'")],
+const plainValueEscapeSequence = getEscapeSequenceRegExp('\\', ':', ']')
+const delimitedValueEscapeSequences = new Map<string, RegExp>([
+	['"', getEscapeSequenceRegExp('\\', '"')],
+	["'", getEscapeSequenceRegExp('\\', "'")],
 	['/', getEscapeSequenceRegExp('/')],
 ])
 
-function parseTargetSearchQuery(rawTargetSearchQuery: string | undefined): string | undefined {
+function parseTargetSearchQuery(rawTargetSearchQuery: string | undefined): string | RegExp | undefined {
 	if (rawTargetSearchQuery === undefined || rawTargetSearchQuery === '') return
-	const quotedValueEscapeSequence = quotedValueEscapeSequences.get(rawTargetSearchQuery[0])
-	const escapeSequenceRegExp = quotedValueEscapeSequence || unquotedValueEscapeSequence
-	const unescapedQuery = rawTargetSearchQuery.replace(escapeSequenceRegExp, '$1')
-	const queryWithoutQuotes = quotedValueEscapeSequence === undefined ? unescapedQuery : unescapedQuery.slice(1, -1)
-	return queryWithoutQuotes
+	const delimiter = rawTargetSearchQuery[0]
+	const delimitedValueEscapeSequence = delimitedValueEscapeSequences.get(delimiter)
+	const escapeSequenceRegExp = delimitedValueEscapeSequence || plainValueEscapeSequence
+	const undelimitedQuery = delimitedValueEscapeSequence === undefined ? rawTargetSearchQuery : rawTargetSearchQuery.slice(1, -1)
+	const unescapedQuery = undelimitedQuery.replace(escapeSequenceRegExp, '$1')
+
+	// If the delimiter was a slash, try to parse the value as a regular expression and return it
+	if (delimiter === '/') {
+		return parseAsGlobalRegExp(unescapedQuery)
+	}
+
+	// Otherwise, return the unescaped query as a string
+	return unescapedQuery
 }
 
 export function parseAnnotationTags(options: ParseAnnotationTagsOptions): AnnotationTag[] {

packages/annotation-comments/test/tag-parser.test.ts

@@ -1,6 +1,7 @@
 import type { AnnotationTag } from 'annotation-comments'
 import { describe, expect, test } from 'vitest'
 import { parseAnnotationTags } from '../src/internal/tag-parser'
+import { parseAsGlobalRegExp } from '../src/internal/regexps'
 
 describe('parseAnnotationTags', () => {
 	test('Returns an empty array when no annotation tags are found', () => {
@@ -150,6 +151,15 @@ console.log('Some code');
 					relativeTargetRange: undefined,
 				})
 			})
+
+			test(`[!tag:"C:\\Users\\Test Path"]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: `C:\\Users\\Test Path`,
+					relativeTargetRange: undefined,
+				})
+			})
 		})
 
 		describe('Tags with quoted target search query and target range', () => {
@@ -171,6 +181,64 @@ console.log('Some code');
 				})
 			})
 		})
+
+		describe('Tags with RegExp target search query', () => {
+			test(`[!tag:/reg(exp)|regular (expression)/]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/reg(exp)|regular (expression)/),
+					relativeTargetRange: undefined,
+				})
+			})
+
+			test(`[!tag:/with escaped \\\\ backslash and \\/ slash/]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/with escaped \\ backslash and \/ slash/),
+					relativeTargetRange: undefined,
+				})
+			})
+
+			test(`[!tag:/regexp[s]?|"regular\\s+\\w{2}pressions?"/]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/regexp[s]?|"regular\s+\w{2}pressions?"/),
+					relativeTargetRange: undefined,
+				})
+			})
+		})
+
+		describe('Tags with RegExp target search query and target range', () => {
+			test(`[!tag:/reg(exp)|regular (expression)/:5]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/reg(exp)|regular (expression)/),
+					relativeTargetRange: 5,
+				})
+			})
+
+			test(`[!tag:/with escaped \\\\ backslash and \\/ slash/:-3]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/with escaped \\ backslash and \/ slash/),
+					relativeTargetRange: -3,
+				})
+			})
+
+			test(`[!tag:/regexp[s]?|"regular\\s+\\w{2}pressions?"/:1]`, ({ task }) => {
+				performTagTest({
+					rawTag: task.name,
+					name: 'tag',
+					targetSearchQuery: parseAsGlobalRegExp(/regexp[s]?|"regular\s+\w{2}pressions?"/),
+					relativeTargetRange: 1,
+				})
+			})
+		})
 	})
 
 	function performTagTest(test: Required<Omit<AnnotationTag, 'location'>>) {