Add parseAnnotationComments tests, handle chaining & nesting

hippotastic · hippotastic · commit 08fda18053ba · 2024-09-09T00:08:42.000+02:00
diff --git a/packages/annotation-comments/src/core/parse.ts b/packages/annotation-comments/src/core/parse.ts
@@ -1,27 +1,34 @@
-import type { AnnotationComment } from './types'
+import type { AnnotationComment, SourceRange } from './types'
 import { parseAnnotationTags } from '../parsers/annotation-tags'
 import { parseParentComment } from '../parsers/parent-comment'
+import { secondRangeIsInFirst } from '../internal/ranges'
 
 export type ParseAnnotationCommentsOptions = {
 	codeLines: string[]
-	validateAnnotationName?: (name: string) => boolean
 }
 
 export function parseAnnotationComments(options: ParseAnnotationCommentsOptions): AnnotationComment[] {
-	const { codeLines, validateAnnotationName } = options
+	const { codeLines } = options
 	const annotationComments: AnnotationComment[] = []
 
-	// Find annotation tags
+	// Find annotation tags in the code
 	const annotationTags = parseAnnotationTags({ codeLines })
+
+	let previousCommentRanges: SourceRange[] = []
 	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
+		// 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
+
+		// TODO: Handle `[!ignore-tags]` logic
 
 		// 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
+		annotationComments.push(comment)
+		previousCommentRanges = comment.contentRanges
 	})
 
 	return annotationComments
diff --git a/packages/annotation-comments/src/internal/ranges.ts b/packages/annotation-comments/src/internal/ranges.ts
@@ -0,0 +1,49 @@
+import type { SourceRange } from '../core/types'
+
+export function createRange(options: { line: string; lineIndex: number; startColumn: number; endColumn: number }) {
+	const { line, lineIndex, startColumn, endColumn } = options
+	const range: SourceRange = {
+		start: { line: lineIndex },
+		end: { line: lineIndex },
+	}
+	if (startColumn > 0) range.start.column = startColumn
+	if (endColumn < line.length) range.end.column = endColumn
+	return range
+}
+
+/**
+ * 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 they are equal.
+ */
+export function compareRanges(a: SourceRange, b: SourceRange, prop: 'start' | 'end'): number {
+	// Compare line numbers first
+	const lineResult = b[prop].line - a[prop].line
+	if (lineResult !== 0) return lineResult
+
+	// Line numbers are equal, so compare columns
+	const aCol = a[prop].column
+	const bCol = b[prop].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
+
+	return bCol - aCol
+}
+
+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 &&
+		// ...and end at or before potentialOuterRange
+		compareRanges(potentialOuterRange, rangeToTest, 'end') <= 0
+	)
+}
diff --git a/packages/annotation-comments/src/parsers/comment-types/multi-line.ts b/packages/annotation-comments/src/parsers/comment-types/multi-line.ts
@@ -1,6 +1,7 @@
 import type { AnnotationComment, AnnotationTag, SourceRange } from '../../core/types'
 import type { ParseParentCommentOptions } from '../parent-comment'
 import { escapeRegExp } from '../../internal/escaping'
+import { compareRanges, createRange } from '../../internal/ranges'
 import { getTextContentInLine } from '../text-content'
 
 type MultiLineCommentSyntax = {
@@ -391,28 +392,3 @@ function isValidFullMatch(match: Partial<MultiLineCommentSyntaxMatch>): match is
 
 	return true
 }
-
-function createRange(options: { line: string; lineIndex: number; startColumn: number; endColumn: number }) {
-	const { line, lineIndex, startColumn, endColumn } = options
-	const range: SourceRange = {
-		start: { line: lineIndex },
-		end: { line: lineIndex },
-	}
-	if (startColumn > 0) range.start.column = startColumn
-	if (endColumn < line.length) range.end.column = endColumn
-	return range
-}
-
-/**
- * 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 they are equal.
- */
-function compareRanges(a: SourceRange, b: SourceRange, prop: 'start' | 'end'): number {
-	const aCol = a[prop].column ?? 0
-	const bCol = b[prop].column ?? 0
-	return a[prop].line - b[prop].line || aCol - bCol
-}
diff --git a/packages/annotation-comments/test/parse.test.ts b/packages/annotation-comments/test/parse.test.ts
@@ -1,12 +1,241 @@
 import { describe, expect, test } from 'vitest'
+import type { AnnotationComment, AnnotationTag } from '../src/core/types'
+import { parseAnnotationComments } from '../src/core/parse'
+import { splitCodeLines } from './utils'
+
+type PartialAnnotationComment = Partial<Omit<AnnotationComment, 'tag'>> & { tag: Partial<AnnotationTag> }
 
 describe('parseAnnotationComments()', () => {
-	// TODO: We need to test if the parser properly skips processing the second annotation tag
-	// in the following code, which requires checking the comment range of the previously processed
-	// annotation comment and skipping all tags located before the end of the comment range:
-	// "someCode() // [!note] Mismatching comment # [!syntax] also prevents chaining"
-	test('Todo', () => {
-		expect(true).toBe(true)
+	describe('Successfully parses code examples in various languages', () => {
+		test('JavaScript (including JSDoc)', () => {
+			const jsTestCode = `
+import { defineConfig } from 'astro/config';
+
+/**
+ * Some JSDoc test.
+ *
+ * [!note:test] The \`test\` function here is just an example
+ * and doesn't do anything meaningful.
+ *
+ * Also note that we just added a [!note] tag to an existing
+ * JSDoc comment to create this note.
+ */
+export async function test(a, b, c) {
+  let x = true
+  let y = a.toString()
+  const z = \`hello\${a === true ? 'x' : 'y'}\`
+  const fn = () => "test\\nanother line"
+}
+
+// Single-line comment
+var v = 300 // [!ins]
+test(1, Math.min(6, 2), defineConfig.someProp || v)
+
+export default defineConfig({
+  markdown: {
+    // [!note:"'some.example'"] This setting does not actually exist.
+    'some.example': 2048,
+    smartypants: false, // [!ins]
+    /* [!ins] */ gfm: false,
+  }
+});
+			`.trim()
+			const comments = getComments(jsTestCode)
+			expect(comments).toHaveLength(5)
+			expect(comments).toMatchObject([
+				{
+					tag: { name: 'note', targetSearchQuery: 'test' },
+					contents: [
+						`The \`test\` function here is just an example`,
+						`and doesn't do anything meaningful.`,
+						``,
+						`Also note that we just added a [!note] tag to an existing`,
+						`JSDoc comment to create this note.`,
+					],
+				},
+				{
+					tag: { name: 'ins', targetSearchQuery: undefined },
+					contents: [],
+				},
+				{
+					tag: { name: 'note', targetSearchQuery: "'some.example'" },
+					contents: [`This setting does not actually exist.`],
+				},
+				{
+					tag: { name: 'ins', targetSearchQuery: undefined },
+					contents: [],
+				},
+				{
+					tag: { name: 'ins', targetSearchQuery: undefined },
+					contents: [],
+				},
+			] as PartialAnnotationComment[])
+		})
+
+		test('CSS', () => {
+			const cssTestCode = `
+@media (min-width: 50em) {
+  :root {
+    --min-spacing-inline: calc(0.5vw - 1.5rem); /* [!ins] */
+    /* [!del] */ color: blue;
+  }
+  body, html, .test[data-size="large"], #id {
+    /* [!note:linear-gradient]
+       As this [!note] points out, we let the browser
+       create a gradient for us here. */
+    background: linear-gradient(to top, #80f 1px, rgb(30, 90, 130) 50%);
+  }
+  .frame:focus-within :focus-visible ~ .copy button:not(:hover) {
+    content: 'Hello \\000026 welcome!';
+    opacity: 0.75;
+  }
+}
+			`.trim()
+			const comments = getComments(cssTestCode)
+			expect(comments).toHaveLength(3)
+			expect(comments).toMatchObject([
+				{
+					tag: { name: 'ins', targetSearchQuery: undefined },
+					contents: [],
+				},
+				{
+					tag: { name: 'del', targetSearchQuery: undefined },
+					contents: [],
+				},
+				{
+					tag: { name: 'note', targetSearchQuery: 'linear-gradient' },
+					contents: [
+						// Content lines
+						`As this [!note] points out, we let the browser`,
+						`create a gradient for us here.`,
+					],
+				},
+			] as PartialAnnotationComment[])
+		})
+
+		test('Astro', () => {
+			const astroTestCode = `
+---
+import Header from './Header.astro';
+import Logo from './Logo.astro';
+import Footer from './Footer.astro';
+
+// [!note:title] By destructuring the \`Astro.props\` object,
+// we can access the \`title\` prop passed to this component.
+const { title } = Astro.props
+---
+<div id="content-wrapper" class="test">
+  <Header />
+  <Logo size="large"/>
+  <!-- [!note:{title}] By wrapping any variable name in curly braces,
+       we can output its value in the HTML template,
+       as explained by this [!note] annotation. -->
+  <h1>{title} &amp; some text</h1>
+  <slot />  <!-- [!note] Children passed to the component will be inserted here -->
+  <Footer />
+</div>
+			`.trim()
+			const comments = getComments(astroTestCode)
+			expect(comments).toHaveLength(3)
+			expect(comments).toMatchObject([
+				{
+					tag: { name: 'note', targetSearchQuery: 'title' },
+					contents: [
+						// Content lines
+						`By destructuring the \`Astro.props\` object,`,
+						`we can access the \`title\` prop passed to this component.`,
+					],
+				},
+				{
+					tag: { name: 'note', targetSearchQuery: '{title}' },
+					contents: [
+						// Content lines
+						`By wrapping any variable name in curly braces,`,
+						`we can output its value in the HTML template,`,
+						`as explained by this [!note] annotation.`,
+					],
+				},
+				{
+					tag: { name: 'note', targetSearchQuery: undefined },
+					contents: [`Children passed to the component will be inserted here`],
+				},
+			] as PartialAnnotationComment[])
+		})
+
+		test('Python', () => {
+			const pythonTestCode = `
+import time
+
+# [!note] This function will print a countdown from the given time,
+# as explained by this # [!note] annotation.
+def countdown(time_sec):
+  while time_sec:
+    mins, secs = divmod(time_sec, 60)
+    timeformat = '{:02d}:{:02d}'.format(mins, secs)
+    print(timeformat, end='\\r')
+    time.sleep(1)
+    time_sec -= 1 # [!note] This is important to actually count down
+  print("stop")
+
+countdown(5)
+			`.trim()
+			const comments = getComments(pythonTestCode)
+			expect(comments).toMatchObject([
+				{
+					tag: { name: 'note', targetSearchQuery: undefined },
+					contents: [
+						// Content lines
+						`This function will print a countdown from the given time,`,
+						`as explained by this # [!note] annotation.`,
+					],
+				},
+				{
+					tag: { name: 'note', targetSearchQuery: undefined },
+					contents: [`This is important to actually count down`],
+				},
+			] as PartialAnnotationComment[])
+		})
 	})
+
+	test('Supports chaining multiple matching single-line annotations on the same line', () => {
+		const lines = [
+			`// [!note] This is the note content. // [!ins]`,
+			`console.log('Inserted line with an attached note')`,
+			`testCode() // [!mark] // [!note] It also works at the end of a line.`,
+		]
+		const comments = getComments(lines.join('\n'))
+		expect(comments).toHaveLength(4)
+		expect(comments).toMatchObject([
+			{
+				tag: { name: 'note', targetSearchQuery: undefined },
+				commentRange: { start: { line: 0 }, end: { line: 0, column: lines[0].indexOf(' // [!ins]') } },
+				contents: [`This is the note content.`],
+			},
+			{
+				tag: { name: 'ins', targetSearchQuery: undefined },
+				commentRange: { start: { line: 0, column: lines[0].indexOf(' // [!ins]') }, end: { line: 0 } },
+				contents: [],
+			},
+			{
+				tag: { name: 'mark', targetSearchQuery: undefined },
+				commentRange: {
+					start: { line: 2, column: lines[2].indexOf(' // [!mark]') },
+					end: { line: 2, column: lines[2].indexOf(' // [!note]') },
+				},
+				contents: [],
+			},
+			{
+				tag: { name: 'note', targetSearchQuery: undefined },
+				commentRange: { start: { line: 2, column: lines[2].indexOf(' // [!note]') }, end: { line: 2 } },
+				contents: [`It also works at the end of a line.`],
+			},
+		] as PartialAnnotationComment[])
+	})
+
 	// TODO: We also need to implement and test the `[!ignore-tags]` logic
+
+	function getComments(code: string) {
+		const codeLines = splitCodeLines(code)
+		return parseAnnotationComments({ codeLines })
+	}
 })
