Add parent comment parsing and tests

Author: hippotastic

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

@@ -1,5 +1,6 @@
 import type { AnnotationComment } from './types'
-import { parseAnnotationTags } from '../internal/tag-parser'
+import { parseAnnotationTags } from '../parsers/annotation-tags'
+import { parseParentComment } from '../parsers/parent-comment'
 
 export type ParseAnnotationCommentsOptions = {
 	codeLines: string[]
@@ -10,36 +11,18 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 	const { codeLines, validateAnnotationName } = options
 	const annotationComments: AnnotationComment[] = []
 
-	// Parse annotation tags
+	// Find annotation tags
 	const annotationTags = parseAnnotationTags({ codeLines })
+	annotationTags.forEach((tag) => {
+		// Ensure that the current annotation tag has not been ignored by an ´ignore-tags` directive. If it has, it will skip the tag and continue searching
+		// If given, call the `validateAnnotationName` handler function to check if the annotation name is valid. If this function returns `false`, skip the tag and continue searching
 
-	// Go through all tags and...
-	// - Ensure that the current annotation tag has not been ignored by an ´ignore-tags` directive. If it has, it will skip the tag and continue searching
-	// - If given, call the `validateAnnotationName` handler function to check if the annotation name is valid. If this function returns `false`, skip the tag and continue searching
-	// - **Handle the current annotation tag if it's inside a single-line comment:** Try to find the beginning sequence of a single-line comment directly before the annotation tag, with no non-whitespace character before and after the beginning sequence. If found, it will:
-	// 	- Mark the location of the beginning sequence as beginning of the comment
-	// 	- Support chaining of single-line comments on the same line
-	// 	- After the current annotation tag, look for a repetition of the same comment beginning sequence + annotation tag syntax. If found, this is a case of chaining, so mark the location of the next beginning sequence as the end of the current comment.
-	// 	- If no chaining is found, mark the end of the line as the current end of the comment (this may change later)
-	// 	- Add any text after the annotation tag until the current end of the comment to the annotation's **contents**
-	// 	- If there was only whitespace before the beginning of the comment (= the comment was on its own line), and no chaining was detected (= end of comment matches end of line), try to expand the comment end location and annotation content to all subsequent lines until a line is found that either doesn't start with the same single-line comment beginning sequence (only preceded by optional whitespace characters), that starts with another valid annotation tag, or that has `---` as its only text content.
-	// 	- End processing the current annotation tag and continue searching for the next one
-	// - **Handle the current annotation tag if it's inside a multi-line comment:** No single-line comment was found, so now try to find a matching pair of beginning and ending sequence of a supported multi-line comment syntax around the match:
-	// 	- Walk backwards, passing each character into an array of parser functions that are each responsible for one supported comment syntax. If a parser function returns a definite result, which can either be a match or a failure, stop calling this parser.
-	// 	- In the JSDoc parser, on the first processed line, allow whitespace and require either a single `*` character or the opening sequence `/**` surrounded by whitespace to be present before the tag. If not, return a failure. If the opening is found, return a match. Otherwise, keep going with all previous lines and expect the same, except that there now can be arbitrary other content between the mandatory `*` and the beginning of the line.
-	// 	- In all other parsers, on the first processed line, allow only whitespace or the opening sequence surrounded by whitespace to be present before the tag. If not, return a failure. If the opening is found, return a match. Otherwise, keep going with all previous lines, but now also allow other arbitrary content. If the beginning of the code is reached, return a failure.
-	// 	- If none of the parsers returned a match, skip processing the current annotation tag and continue searching for the next one
-	// 	- Otherwise, walk forwards, passing each character into a new array of parser functions that are each responsible for one supported multi-line comment syntax. If a parser function returns a definite result, which can either be a match or a failure, stop calling this parser.
-	// 	- In the JSDoc parser, on the first processed line, allow arbitrary content or the closing sequence `*/` surrounded by whitespace. If the closing is found, return a match. Otherwise, keep going with all subsequent lines, and either expect whitespace followed by a mantatory `*` and then arbitrary content. If the closing sequence surrounded by whitespace is encountered at any point, return a match. If the end of the code is reached, return a failure.
-	// 	- In all other parsers, just accept any content while looking for the closing sequence surrounded by whitespace on all lines. If it is found, return a match. If the end of the code is reached, return a failure.
-	// 	- Now filter the backwards and forwards results, removing any non-pairs. If the opening and closing sequences of multiple pairs overlap, only keep the longest sequence (this ensures that we're capturing `{ /* */ }` instead of just the inner `/* */`). Finally, keep only the innermost pair.
-	// 	- If no pair was found, skip processing the current annotation tag and continue searching for the next one
-	// 	- Otherwise:
-	// 	- Check rule "Comments must not be placed between code on the same line"
-	// 		- If the comment starts and ends on the same line, and there is non-whitespace content both before and after the comment, skip processing the current annotation tag and continue searching for the next one
-	// 	- Check rule "Comments spanning multiple lines must not share any lines with code"
-	// 		- If the comment starts and ends on different lines, and there is non-whitespace content either before the start or after the end of the comment, skip processing the current annotation tag and continue searching for the next one
-	// 	- Finish processing the current annotation tag and continue searching for the next one
+		// Attempt to find a comment that the current annotation tag is located in
+		const comment = parseParentComment({ codeLines, tag })
+		if (!comment) return
+
+		// If a comment was found, add the tag and comment to the list of annotation comments
+	})
 
 	return annotationComments
 }

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

@@ -1,9 +1,9 @@
 export type AnnotationComment = {
 	tag: AnnotationTag
 	contents: string[]
-	commentRange: CodeRange
-	contentRanges: CodeRange[]
-	targetRanges: CodeRange[]
+	commentRange: SourceRange
+	contentRanges: SourceRange[]
+	targetRanges: SourceRange[]
 }
 
 export type AnnotationTag = {
@@ -42,24 +42,25 @@ export type AnnotationTag = {
 	relativeTargetRange?: number | undefined
 	rawTag: string
 	/**
-	 * The tag's location within the parsed code.
+	 * The tag's range within the parsed source code.
 	 */
-	location: CodeRange
+	range: SourceRange
 }
 
-export type CodeRange = {
-	/** Zero-based index of the range's starting line. */
-	startLineIndex: number
-	/** Zero-based index of the range's ending line. */
-	endLineIndex: number
+export type SourceLocation = {
+	/** Zero-based line index. */
+	line: number
 	/**
-	 * Zero-based index of the range's starting column.
-	 * If not provided, the range covers the full starting line.
-	 */
-	startColIndex?: number | undefined
-	/**
-	 * Zero-based index of the range's ending column.
-	 * If not provided, the range covers the full ending line.
+	 * Zero-based column index inside the line.
+	 *
+	 * If not provided, the location references the full line.
 	 */
-	endColIndex?: number | undefined
+	column?: number | undefined
+}
+
+export type SourceRange = {
+	/** The beginning (line & optional column) of the range. */
+	start: SourceLocation
+	/** The end (line & optional column) of the range. */
+	end: SourceLocation
 }

packages/annotation-comments/src/index.ts

@@ -2,4 +2,5 @@ export type * from './core/types'
 export * from './core/parse'
 export * from './core/remove'
 
-export * from './internal/tag-parser'
+export * from './parsers/annotation-tags'
+export * from './parsers/parent-comment'

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

@@ -7,7 +7,7 @@ import { coerceError } from './errors'
  * 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 {
+export function createGlobalRegExp(pattern: string | RegExp, extraFlags?: string): RegExp {
 	let regExp: RegExp | undefined
 	try {
 		// Try to use regular expressions with capture group indices

…tion-comments/src/internal/tag-parser.ts …-comments/src/parsers/annotation-tags.tspackages/annotation-comments/src/internal/tag-parser.ts renamed to packages/annotation-comments/src/parsers/annotation-tags.ts packages/annotation-comments/src/internal/tag-parser.ts renamed to packages/annotation-comments/src/parsers/annotation-tags.ts

@@ -1,8 +1,8 @@
 import { AnnotationTag } from '../core/types'
-import { getEscapeSequenceRegExp } from './escaping'
-import { parseAsGlobalRegExp } from './regexps'
+import { getEscapeSequenceRegExp } from '../internal/escaping'
+import { createGlobalRegExp } from '../internal/regexps'
 
-type ParseAnnotationTagsOptions = {
+export type ParseAnnotationTagsOptions = {
 	codeLines: string[]
 }
 
@@ -91,7 +91,7 @@ function parseTargetSearchQuery(rawTargetSearchQuery: string | undefined): strin
 
 	// If the delimiter was a slash, try to parse the value as a regular expression and return it
 	if (delimiter === '/') {
-		return parseAsGlobalRegExp(unescapedQuery)
+		return createGlobalRegExp(unescapedQuery)
 	}
 
 	// Otherwise, return the unescaped query as a string
@@ -115,11 +115,9 @@ export function parseAnnotationTags(options: ParseAnnotationTagsOptions): Annota
 				targetSearchQuery,
 				relativeTargetRange: relativeTargetRange !== undefined ? Number(relativeTargetRange) : undefined,
 				rawTag,
-				location: {
-					startLineIndex: lineIndex,
-					endLineIndex: lineIndex,
-					startColIndex,
-					endColIndex,
+				range: {
+					start: { line: lineIndex, column: startColIndex },
+					end: { line: lineIndex, column: endColIndex },
 				},
 			})
 		})