Don't report types used only in module augmentations as unused (resolve #1843)

Types referenced inside `declare module './x'` resolve to that module's
exports via TS augmentation scope without an import statement; register
them as type imports so those exports aren't flagged as unused.

Author: webpro

packages/knip/fixtures/types/declare-module-augmentation/events.augmentation.ts

@@ -0,0 +1,10 @@
+declare module './events.js' {
+  type EntityWithMeta = BaseEntity & { meta: string };
+
+  export interface EventBusEvents extends EventEnvelope {
+    'entity:created': EntityWithMeta;
+    'entity:updated': BaseEntity & { revision: number };
+  }
+}
+
+export {};

packages/knip/fixtures/types/declare-module-augmentation/events.ts

@@ -0,0 +1,9 @@
+export interface BaseEntity {
+  id: string;
+}
+
+export interface EventEnvelope {
+  at: number;
+}
+
+export interface EventBusEvents {}

packages/knip/fixtures/types/declare-module-augmentation/index.ts

@@ -0,0 +1,4 @@
+import './events.augmentation.js';
+import type { EventBusEvents } from './events.js';
+
+export const handled: (keyof EventBusEvents)[] = [];

packages/knip/fixtures/types/declare-module-augmentation/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fixtures/declare-module-augmentation",
+  "type": "module"
+}

packages/knip/src/typescript/ast-nodes.ts

@@ -4,6 +4,7 @@ import {
   type TSEnumDeclaration,
   type TSEnumMember,
   type TSModuleDeclaration,
+  visitorKeys,
 } from 'oxc-parser';
 import { DEFAULT_EXTENSIONS, FIX_FLAGS, SYMBOL_TYPE } from '../constants.ts';
 import { extname } from '../util/path.ts';
@@ -158,6 +159,46 @@ export function extractNamespaceMembers(
   return members;
 }
 
+export const collectAugmentationRefs = (node: TSModuleDeclaration): string[] => {
+  if (!node.body || node.body.type !== 'TSModuleBlock') return [];
+  const body = node.body.body;
+
+  const declared = new Set<string>();
+  for (const stmt of body) {
+    const decl = stmt.type === 'ExportNamedDeclaration' && stmt.declaration ? stmt.declaration : stmt;
+    if ('id' in decl && decl.id?.type === 'Identifier') declared.add(decl.id.name);
+    else if (decl.type === 'VariableDeclaration')
+      for (const d of decl.declarations) if (d.id.type === 'Identifier') declared.add(d.id.name);
+  }
+
+  const refs: string[] = [];
+  const seen = new Set<string>();
+  const add = (ref: any) => {
+    if (ref?.type === 'Identifier' && !declared.has(ref.name) && !seen.has(ref.name)) {
+      seen.add(ref.name);
+      refs.push(ref.name);
+    }
+  };
+  const visit = (n: any) => {
+    const type = n?.type;
+    if (!type) return;
+    if (type === 'TSTypeReference') add(n.typeName);
+    else if (type === 'TSInterfaceHeritage') add(n.expression);
+    const keys = visitorKeys[type];
+    if (!keys) return;
+    for (const key of keys) {
+      const val = n[key];
+      if (!val) continue;
+      if (Array.isArray(val)) {
+        for (const item of val) if (item) visit(item);
+      } else visit(val);
+    }
+  };
+  for (const stmt of body) visit(stmt);
+
+  return refs;
+};
+
 export function extractEnumMembers(
   decl: TSEnumDeclaration,
   options: GetImportsAndExportsOptions,

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

@@ -18,7 +18,13 @@ import type { Export, ExportMember, ImportMap, ImportMaps } from '../../types/mo
 import { addValue } from '../../util/module-graph.ts';
 import { isInNodeModules } from '../../util/path.ts';
 import { timerify } from '../../util/Performance.ts';
-import { getLineAndCol, getStringValue, isStringLiteral, type ResolveModule } from '../ast-nodes.ts';
+import {
+  collectAugmentationRefs,
+  getLineAndCol,
+  getStringValue,
+  isStringLiteral,
+  type ResolveModule,
+} from '../ast-nodes.ts';
 import { EMPTY_TAGS } from './jsdoc.ts';
 import { handleCallExpression, handleNewExpression, trackCustomElementRegistry } from './calls.ts';
 import {
@@ -327,6 +333,12 @@ const coreVisitorObject: VisitorObject = {
   },
   TSModuleDeclaration(node) {
     state.nsRanges.push([node.start, node.end]);
+    if (node.kind !== 'global' && isStringLiteral(node.id)) {
+      const specifier = getStringValue(node.id)!;
+      if (specifier.startsWith('.'))
+        for (const name of collectAugmentationRefs(node))
+          state.addImport(specifier, name, undefined, undefined, node.id.start, IMPORT_FLAGS.TYPE_ONLY);
+    }
   },
   ClassDeclaration(node) {
     state.classNameStack.push(node.id?.name ?? '');

packages/knip/test/types/declare-module-augmentation.test.ts

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { main } from '../../src/index.ts';
+import baseCounters from '../helpers/baseCounters.ts';
+import { createOptions } from '../helpers/create-options.ts';
+import { resolve } from '../helpers/resolve.ts';
+
+const cwd = resolve('fixtures/types/declare-module-augmentation');
+
+test('Type used only in a declare module augmentation is not reported unused (#1843)', async () => {
+  const options = await createOptions({ cwd });
+  const { issues, counters } = await main(options);
+
+  assert(!issues.types['events.ts']?.['BaseEntity']);
+  assert(!issues.types['events.ts']?.['EventEnvelope']);
+
+  assert.deepEqual(counters, {
+    ...baseCounters,
+    processed: 3,
+    total: 3,
+  });
+});