Pick up types used in module augmentations via path aliases (resolve #1850)

webpro · webpro · commit 9cc5a4132793 · 2026-07-04T15:08:16.000+02:00
Follow-up to #1843. A module augmented via a path alias (`declare module '#events'`) resolves its referenced types through that module's exports, same as a relative specifier. Register those references as type imports when the augmented specifier resolves to an internal module, so the exports aren't flagged as unused. External and ambient augmentations stay neutral (no dependency usage, no unresolved import), avoiding false positives for transitive-package augmentations like `declare module '@vue/runtime-core'`.
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/index.ts b/packages/knip/fixtures/types/declare-module-augmentation-external/index.ts
@@ -0,0 +1,13 @@
+declare module 'listed-lib' {
+  export interface Payload extends Base {
+    listed: number;
+  }
+}
+
+declare module 'transitive-lib' {
+  export interface Payload extends Base {
+    transitive: number;
+  }
+}
+
+export {};
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/listed-lib/index.d.ts b/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/listed-lib/index.d.ts
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/listed-lib/package.json b/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/listed-lib/package.json
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/transitive-lib/index.d.ts b/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/transitive-lib/index.d.ts
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/transitive-lib/package.json b/packages/knip/fixtures/types/declare-module-augmentation-external/node_modules/transitive-lib/package.json
diff --git a/packages/knip/fixtures/types/declare-module-augmentation-external/package.json b/packages/knip/fixtures/types/declare-module-augmentation-external/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "@fixtures/declare-module-augmentation-external",
+  "type": "module",
+  "dependencies": {
+    "listed-lib": "*"
+  }
+}
diff --git a/packages/knip/fixtures/types/declare-module-augmentation/events.augmentation.ts b/packages/knip/fixtures/types/declare-module-augmentation/events.augmentation.ts
@@ -7,4 +7,16 @@ declare module './events.js' {
   }
 }
 
+declare module '#events' {
+  export interface EventBusEvents {
+    'entity:audited': AuditTrail & { at: number };
+  }
+}
+
+declare module '#phantom' {
+  export interface EventBusEvents {
+    'entity:phantom': PhantomPayload;
+  }
+}
+
 export {};
diff --git a/packages/knip/fixtures/types/declare-module-augmentation/events.ts b/packages/knip/fixtures/types/declare-module-augmentation/events.ts
@@ -6,4 +6,8 @@ export interface EventEnvelope {
   at: number;
 }
 
+export interface AuditTrail {
+  actor: string;
+}
+
 export interface EventBusEvents {}
diff --git a/packages/knip/fixtures/types/declare-module-augmentation/tsconfig.json b/packages/knip/fixtures/types/declare-module-augmentation/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "module": "preserve",
+    "paths": {
+      "#events": ["./events.ts"]
+    }
+  },
+  "include": ["**/*.ts"]
+}
diff --git a/packages/knip/src/constants.ts b/packages/knip/src/constants.ts
@@ -260,4 +260,5 @@ export const IMPORT_FLAGS = {
   OPTIONAL: 1 << 4, // no error if not resolved
   SIDE_EFFECTS: 1 << 5,
   OPAQUE: 1 << 6,
+  AUGMENT: 1 << 7, // module augmentation ref, attribute only if it resolves internally
 } as const;
diff --git a/packages/knip/src/typescript/get-imports-and-exports.ts b/packages/knip/src/typescript/get-imports-and-exports.ts
@@ -144,6 +144,13 @@ const getImportsAndExports = (
 
     const module = preResolvedModule ?? resolveModule(specifier, filePath);
 
+    if (
+      modifiers & IMPORT_FLAGS.AUGMENT &&
+      (!module || module.isExternalLibraryImport || isInNodeModules(module.resolvedFileName))
+    ) {
+      return;
+    }
+
     if (module) {
       const resolvedFileName = module.resolvedFileName;
       if (resolvedFileName) {
diff --git a/packages/knip/src/typescript/visitors/walk.ts b/packages/knip/src/typescript/visitors/walk.ts
@@ -335,9 +335,15 @@ const coreVisitorObject: VisitorObject = {
     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);
+      for (const name of collectAugmentationRefs(node))
+        state.addImport(
+          specifier,
+          name,
+          undefined,
+          undefined,
+          node.id.start,
+          IMPORT_FLAGS.TYPE_ONLY | IMPORT_FLAGS.AUGMENT
+        );
     }
   },
   ClassDeclaration(node) {
diff --git a/packages/knip/test/types/declare-module-augmentation-external.test.ts b/packages/knip/test/types/declare-module-augmentation-external.test.ts
@@ -0,0 +1,23 @@
+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-external');
+
+test('A declare module augmentation does not count as external dependency usage', async () => {
+  const options = await createOptions({ cwd });
+  const { issues, counters } = await main(options);
+
+  assert(issues.dependencies['package.json']?.['listed-lib']);
+  assert(!issues.unlisted['index.ts']?.['transitive-lib']);
+
+  assert.deepEqual(counters, {
+    ...baseCounters,
+    dependencies: 1,
+    processed: 1,
+    total: 1,
+  });
+});
diff --git a/packages/knip/test/types/declare-module-augmentation.test.ts b/packages/knip/test/types/declare-module-augmentation.test.ts
@@ -7,12 +7,13 @@ 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 () => {
+test('Type used only in a declare module augmentation is not reported unused', 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(!issues.types['events.ts']?.['AuditTrail']);
 
   assert.deepEqual(counters, {
     ...baseCounters,

Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,8 @@ export interface EventEnvelope {`
`6`	`6`	`at: number;`
`7`	`7`	`}`
`8`	`8`
	`9`	`+export interface AuditTrail {`
	`10`	`+ actor: string;`
	`11`	`+}`
	`12`	`+`
`9`	`13`	`export interface EventBusEvents {}`