Improve readme structure, add todos

Author: hippotastic

packages/annotation-comments/README.md

@@ -0,0 +1,31 @@
+import type { AnnotationComment } from './types'
+
+export type CleanCodeOptions = {
+	codeLines: string[]
+	annotationComments: AnnotationComment[]
+	removeAnnotationContents?: boolean | ((context: RemoveAnnotationContentsContext) => boolean)
+	updateTargetRanges?: boolean
+	handleRemoveLine?: (context: HandleRemoveLineContext) => boolean
+	handleEditLine?: (context: HandleEditLineContext) => boolean
+}
+
+export type RemoveAnnotationContentsContext = {
+	comment: AnnotationComment
+}
+
+export type HandleRemoveLineContext = {
+	lineIndex: number
+	codeLines: string[]
+}
+
+export type HandleEditLineContext = {
+	lineIndex: number
+	startColumn: number
+	endColumn: number
+	codeLines: string[]
+}
+
+export function cleanCode(options: CleanCodeOptions) {
+	const { annotationComments, codeLines, updateTargetRanges, handleRemoveLine, handleEditLine: handleRemoveInlineRange } = options
+	// TODO: Implement cleanCode()
+}

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

@@ -0,0 +1,25 @@
+/*
+- Now, the function goes through all identified annotation comments and does the following:
+  - If the annotation has **no relative target range** given, automatically determine it:
+    - If the annotation has **no target search query**, it attempts to target full lines:
+      - If the **annotation comment is on the same line as content** (= annotation start line contains content other than whitespace or other annotation comments), the target range is the annotation comment line.
+      - Otherwise, find the first line above and first line below that don't fully consist of annotation comments
+        - If the **line below has content**, it is the target range.
+        - Otherwise, if the **line above has content**, it is the target range.
+        - Otherwise (**both lines are empty**), there is no target range (same as the relative range `:0`).
+    - Otherwise, the annotation **has a target search query**, so determine the search direction:
+      - If the **annotation comment is on the same line as content** (= annotation start line contains content other than whitespace or other annotation comments), the direction depends on where the content is in relation to the comment.
+      - Otherwise, find the first line above and first line below that don't fully consist of annotation comments
+        - If the **line above has content** and the **line below is empty**, the relative range is `:-1`.
+        - Otherwise, the relative range is `:1`.
+  - If a target search query is present, **perform the search** to determine the target range(s):
+    - 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.
+*/
+
+export function findAnnotationTargets() {
+	// TODO: Implement findAnnotationTargets()
+}

packages/annotation-comments/src/core/find-targets.ts

@@ -56,5 +56,7 @@ export function parseAnnotationComments(options: ParseAnnotationCommentsOptions)
 		previousContentRanges = comment.contentRanges
 	})
 
+	// TODO: Call findAnnotationTargets() here
+
 	return annotationComments
 }

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

@@ -254,6 +254,7 @@ countdown(5)
 					tag: { name: 'before', targetSearchQuery: undefined },
 					contents: [`This is before any ignores`],
 				},
+				// TODO: Expect the ignore-tags annotation comment to be present as well
 				{
 					tag: { name: 'after', targetSearchQuery: undefined },
 					contents: [`This should be parsed again`],
@@ -276,6 +277,7 @@ countdown(5)
 					tag: { name: 'before', targetSearchQuery: undefined },
 					contents: [`This is before any ignores`],
 				},
+				// TODO: Expect the ignore-tags annotation comment to be present as well
 				{
 					tag: { name: 'after', targetSearchQuery: undefined },
 					contents: [`This should be parsed again`],
@@ -297,6 +299,7 @@ countdown(5)
 					tag: { name: 'before', targetSearchQuery: undefined },
 					contents: [`This is before any ignores`],
 				},
+				// TODO: Expect the ignore-tags annotation comment to be present as well
 				{
 					tag: { name: 'note', targetSearchQuery: undefined },
 					contents: [`This should be parsed again`],
@@ -321,6 +324,7 @@ countdown(5)
 					tag: { name: 'before', targetSearchQuery: undefined },
 					contents: [`This is before any ignores`],
 				},
+				// TODO: Expect the ignore-tags annotation comment to be present as well
 				{
 					tag: { name: 'ins', targetSearchQuery: undefined },
 					contents: [],
@@ -351,6 +355,7 @@ countdown(5)
 					commentRange: { start: { line: 0 }, end: { line: 5 } },
 					annotationRange: { start: { line: 1 }, end: { line: 1 } },
 				},
+				// TODO: Expect the ignore-tags annotation comment to be present as well
 				{
 					tag: { name: 'note', targetSearchQuery: undefined },
 					contents: [`This should be parsed again`],