Support tags in line comments (resolve #1924)

Author: webpro

packages/docs/src/content/docs/reference/jsdoc-tsdoc-tags.md

@@ -18,8 +18,11 @@ report an issue with Knip for false positives).
 
 :::
 
-JSDoc comments always start with `/**` (not `//`) and can be single or
-multi-line.
+Tags also work in regular block comments (`/* ... */`) and standalone line
+comments (`// ...`) before a declaration. These comments keep suppression tags
+out of JSDoc hover information.
+
+Tags in consecutive comments are combined. Trailing `//` comments are ignored.
 
 ## Tags
 
@@ -30,7 +33,7 @@ Example:
 /** @lintignore */
 export const myUnusedExport = 1;
 
-/** @lintignore */
+// @lintignore
 import Unresolved from './generated/lib.js';
 ```
 

packages/knip/fixtures/tags-hints/tag-on-member/status.ts

@@ -4,12 +4,16 @@ export enum Fruit {
   banana = 'banana',
   /** @knipignore */
   cherry = 'cherry',
+  // @knipignore
+  date = 'date',
 }
 
 export namespace Basket {
   /** @knipignore */
   export const size = 1;
   export const color = 'red';
+  // @knipignore
+  export const depth = 2;
 }
 
 /** @knipignore */

packages/knip/fixtures/tags-hints/tags-exclude/tags.ts

@@ -5,3 +5,23 @@ export const tagged = 0;
 
 /** @tagged */
 export const taggedToo = 2;
+
+// @lintignore
+export const lineTagged = 3;
+
+// @unknown
+// @lintignore
+export const stackedTags = 4;
+
+// @lintignore
+/** Documentation for consumers. */
+export const documented = 5;
+
+// @public
+export const linePublic = 6;
+
+/* @lintignore */
+export const blockTagged = 7;
+
+// @lintignore
+import './generated.js';

packages/knip/src/typescript/visitors/jsdoc.ts

@@ -4,13 +4,28 @@ export const EMPTY_TAGS: Set<string> = new Set();
 
 export function buildJSDocTagLookup(comments: Comment[], sourceText: string) {
   const entries: { reach: number; tags: Set<string> }[] = [];
+  let reach = sourceText.length;
+
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const comment = comments[i];
+    let end = comment.end;
+    while (end < sourceText.length) {
+      const ch = sourceText.charCodeAt(end);
+      if (ch !== 32 && ch !== 9 && ch !== 10 && ch !== 13) break;
+      end++;
+    }
+    if (end !== comments[i + 1]?.start) reach = end;
 
-  for (const comment of comments) {
-    if (comment.type !== 'Block') continue;
     const value = comment.value;
     let index = value.indexOf('@');
     if (index === -1) continue;
 
+    if (comment.type === 'Line') {
+      let start = comment.start;
+      while (start > 0 && (sourceText.charCodeAt(start - 1) === 32 || sourceText.charCodeAt(start - 1) === 9)) start--;
+      if (start > 0 && sourceText.charCodeAt(start - 1) !== 10 && sourceText.charCodeAt(start - 1) !== 13) continue;
+    }
+
     let tags: Set<string> | undefined;
     while (index !== -1) {
       let end = index + 1;
@@ -29,31 +44,16 @@ export function buildJSDocTagLookup(comments: Comment[], sourceText: string) {
     }
     if (!tags) continue;
 
-    let reach = comment.end;
-    for (;;) {
-      while (reach < sourceText.length) {
-        const ch = sourceText.charCodeAt(reach);
-        if (ch === 32 || ch === 9 || ch === 10 || ch === 13) {
-          reach++;
-          continue;
-        }
-        break;
-      }
-      if (
-        reach + 1 < sourceText.length &&
-        sourceText.charCodeAt(reach) === 47 &&
-        sourceText.charCodeAt(reach + 1) === 47
-      ) {
-        const eol = sourceText.indexOf('\n', reach + 2);
-        reach = eol === -1 ? sourceText.length : eol + 1;
-        continue;
-      }
-      break;
+    const entry = entries[entries.length - 1];
+    if (entry?.reach === reach) {
+      for (const tag of tags) entry.tags.add(tag);
+    } else {
+      entries.push({ reach, tags });
     }
-    entries.push({ reach, tags });
   }
 
   if (entries.length === 0) return () => EMPTY_TAGS;
+  entries.reverse();
 
   return function getJSDocTags(nodeStart: number): Set<string> {
     let lo = 0;

packages/knip/test/util/comment-tags.test.ts

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parseSync } from 'oxc-parser';
+import { buildJSDocTagLookup } from '../../src/typescript/visitors/jsdoc.ts';
+
+const cases: [string, string, string[][]][] = [
+  ['JSDoc tags', '/** @public */\nexport const value = 1;', [['@public']]],
+  ['regular block tags', '/* @public */\nexport const value = 1;', [['@public']]],
+  ['line tags', '// @public\nexport const value = 1;', [['@public']]],
+  ['indented line tags', '\t // @lintignore\nexport const value = 1;', [['@lintignore']]],
+  ['stacked line tags', '// @internal\n// @public\nexport const value = 1;', [['@internal', '@public']]],
+  ['line tags after JSDoc', '/** @internal */\n// @public\nexport const value = 1;', [['@internal', '@public']]],
+  ['line tags before JSDoc', '// @public\n/** Description */\nexport const value = 1;', [['@public']]],
+  ['intervening line comment', '// @public\n// Explanation\nexport const value = 1;', [['@public']]],
+  ['CRLF line comments', '// @public\r\n// Explanation\r\nexport const value = 1;', [['@public']]],
+  ['CR line comments', '// @public\r// Explanation\rexport const value = 1;', [['@public']]],
+  ['blank line', '// @public\n\nexport const value = 1;', [['@public']]],
+  ['trailing line tags', 'export const first = 1; // @public\nexport const second = 2;', [[], []]],
+  ['intervening code', '// @public\nconst local = 1;\nexport const value = local;', [[]]],
+  ['next declaration', '// @public\nexport const first = 1;\nexport const second = 2;', [['@public'], []]],
+  ['string contents', 'export const value = "// @public";', [[]]],
+  ['untagged comment', '// Description\nexport const value = 1;', [[]]],
+];
+
+for (const [name, source, expected] of cases) {
+  test(`Read comment tags: ${name}`, () => {
+    const result = parseSync('module.ts', source);
+    assert.deepEqual(result.errors, []);
+    const getTags = buildJSDocTagLookup(result.comments, source);
+    const actual = result.program.body
+      .filter(node => node.type === 'ExportNamedDeclaration')
+      .map(node => getTags(node.start));
+    assert.deepEqual(
+      actual,
+      expected.map(tags => new Set(tags))
+    );
+  });
+}