Flag stale @internal tags in production mode (resolve #1658)

Author: webpro

packages/knip/fixtures/stale-internal-tag/index.ts

@@ -0,0 +1,3 @@
+import { usedInProdInternal } from './module';
+
+usedInProdInternal();

packages/knip/fixtures/stale-internal-tag/module.test.js

@@ -0,0 +1,6 @@
+import { test } from 'node:test';
+import { usedInTestInternal } from './module';
+
+test('used in test', () => {
+  usedInTestInternal();
+});

packages/knip/fixtures/stale-internal-tag/module.ts

@@ -0,0 +1,8 @@
+/** @internal */
+export const usedInProdInternal = () => {};
+
+/** @internal */
+export const usedInTestInternal = () => {};
+
+/** @internal */
+export const unusedInternal = () => {};

packages/knip/fixtures/stale-internal-tag/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@fixtures/stale-internal-tag",
+  "scripts": {
+    "test": "node --test"
+  }
+}

packages/knip/src/cli.ts

@@ -70,6 +70,7 @@ const main = async () => {
       cwd: options.cwd,
       configFilePath: options.configFilePath,
       isDisableConfigHints: options.isDisableConfigHints,
+      isDisableTagHints: options.isDisableTagHints,
       isProduction: options.isProduction,
       isShowProgress: options.isShowProgress,
       isTreatConfigHintsAsErrors: options.isTreatConfigHintsAsErrors,

packages/knip/src/graph-explorer/operations/build-exports-tree.ts

@@ -3,7 +3,6 @@ import { CONTINUE } from '../constants.ts';
 import type { Via } from '../walk-down.ts';
 import { walkDown } from '../walk-down.ts';
 
-/** @internal */
 export interface ExportsTreeNode {
   filePath: string;
   identifier: string;

packages/knip/src/graph/analyze.ts

@@ -12,7 +12,8 @@ import type { MainOptions } from '../util/create-options.ts';
 import { getPackageNameFromModuleSpecifier } from '../util/modules.ts';
 import { perfObserver } from '../util/Performance.ts';
 import { findMatch } from '../util/regex.ts';
-import { getShouldIgnoreHandler, getShouldIgnoreTagHandler } from '../util/tag.ts';
+import { getShouldIgnoreHandler, getShouldIgnoreTagHandler, isAlwaysIgnored } from '../util/tag.ts';
+import { INTERNAL_TAG } from '../constants.ts';
 
 interface AnalyzeOptions {
   analyzedFiles: Set<string>;
@@ -97,10 +98,11 @@ export const analyze = async ({
           const importsForExport = file.importedBy;
 
           for (const [identifier, exportedItem] of exportItems) {
-            // Skip tagged exports
-            if (shouldIgnore(exportedItem.jsDocTags)) continue;
+            // Skip exports tagged @public/@beta/@alias entirely (no refs check)
+            if (isAlwaysIgnored(exportedItem.jsDocTags)) continue;
 
-            const isIgnored = shouldIgnoreTags(exportedItem.jsDocTags);
+            const isInternalProd = options.isProduction && exportedItem.jsDocTags.has(INTERNAL_TAG);
+            const isIgnored = shouldIgnoreTags(exportedItem.jsDocTags) || isInternalProd;
 
             if (importsForExport) {
               const [isReferenced, reExportingEntryFile] = explorer.isReferenced(filePath, identifier, {
@@ -112,7 +114,7 @@ export const analyze = async ({
                 (isReferenced || isReferencedInUsedExport(exportedItem, filePath, isIncludeEntryExports))
               ) {
                 for (const tagName of exportedItem.jsDocTags) {
-                  if (options.tags[1].includes(tagName)) {
+                  if (options.tags[1].includes(tagName) || (isInternalProd && tagName === INTERNAL_TAG)) {
                     collector.addTagHint({ type: 'tag', filePath, identifier, tagName });
                   }
                 }
@@ -233,7 +235,8 @@ export const analyze = async ({
           for (const extImport of file.imports.external) {
             const packageName = getPackageNameFromModuleSpecifier(extImport.specifier);
             const isHandled =
-              packageName && deputy.maybeAddReferencedExternalDependency(ws, packageName, undefined, extImport.isTypeOnly);
+              packageName &&
+              deputy.maybeAddReferencedExternalDependency(ws, packageName, undefined, extImport.isTypeOnly);
             if (!isHandled)
               collector.addIssue({
                 type: 'unlisted',

packages/knip/src/reporters/symbols.ts

@@ -1,10 +1,10 @@
 import type { Entries } from '../types/entries.ts';
 import type { ReporterOptions } from '../types/issues.ts';
-import { printConfigurationHints } from './util/configuration-hints.ts';
+import { printConfigurationHints, printTagHints } from './util/configuration-hints.ts';
 import { dim, flattenIssues, getColoredTitle, getIssueTypeTitle, getTableForType } from './util/util.ts';
 
 export default (options: ReporterOptions) => {
-  const { report, issues, isDisableConfigHints, isShowProgress } = options;
+  const { report, issues, isDisableConfigHints, isDisableTagHints, isShowProgress } = options;
   const reportMultipleGroups = Object.values(report).filter(Boolean).length > 1;
   let totalIssues = 0;
 
@@ -31,6 +31,10 @@ export default (options: ReporterOptions) => {
     printConfigurationHints(options);
   }
 
+  if (!isDisableTagHints) {
+    printTagHints(options);
+  }
+
   if (
     totalIssues === 0 &&
     isShowProgress &&

packages/knip/src/reporters/util/configuration-hints.ts

@@ -180,7 +180,9 @@ export const printConfigurationHints = ({
     console.log(getTitle('Configuration hints', configurationHints.length));
     console.warn(getTableForHints(rows).toString());
   }
+};
 
+export const printTagHints = ({ cwd, tagHints }: ReporterOptions) => {
   if (tagHints.size > 0) {
     console.log(getDimmedTitle('Tag hints', tagHints.size));
     for (const hint of tagHints) {

packages/knip/src/types/issues.ts

@@ -63,6 +63,7 @@ export type ReporterOptions = {
   configurationHints: ConfigurationHint[];
   enabledPlugins: Record<string, string[]>;
   isDisableConfigHints: boolean;
+  isDisableTagHints: boolean;
   isTreatConfigHintsAsErrors: boolean;
   cwd: string;
   isProduction: boolean;