Add plugin-contributed source-map rules

Author: webpro

packages/knip/src/ConfigurationChief.ts

@@ -7,6 +7,7 @@ import type {
   PluginsConfiguration,
   RawConfiguration,
   RawPluginConfiguration,
+  SourceMap,
   WorkspaceConfiguration,
 } from './types/config.ts';
 import type { ConfigurationHint } from './types/issues.ts';
@@ -72,8 +73,7 @@ export type Workspace = {
   manifestPath: string;
   manifestStr: string;
   ignoreMembers: IgnorePatterns;
-  srcDir?: string;
-  outDir?: string;
+  sourceMaps?: SourceMap[];
 };
 
 /**

packages/knip/src/WorkspaceWorker.ts

@@ -12,6 +12,7 @@ import type {
   Plugin,
   RegisterCompiler,
   RegisterVisitorsOptions,
+  SourceMap,
   WorkspaceConfiguration,
 } from './types/config.ts';
 import type { ConfigurationHint } from './types/issues.ts';
@@ -258,6 +259,23 @@ export class WorkspaceWorker {
     }
   }
 
+  public async resolveSourceMaps() {
+    const options = {
+      cwd: this.dir,
+      rootCwd: this.options.cwd,
+      manifest: this.manifest,
+      rootManifest: this.rootManifest,
+      dependencies: this.dependencies,
+    };
+    const pairs: SourceMap[] = [];
+    for (const pluginName of this.enabledPlugins) {
+      const plugin = Plugins[pluginName];
+      if (!plugin.resolveSourceMap) continue;
+      for (const pair of await plugin.resolveSourceMap(options)) pairs.push(pair);
+    }
+    return pairs;
+  }
+
   public registerVisitors(options: RegisterVisitorsOptions) {
     for (const pluginName of this.enabledPlugins) {
       if (options.registeredPlugins.has(pluginName)) continue;

packages/knip/src/graph/build.ts

@@ -36,7 +36,7 @@ import { getPackageNameFromModuleSpecifier, isStartsLikePackageName, sanitizeSpe
 import { perfObserver } from '../util/Performance.ts';
 import { getEntrySpecifiersFromManifest, getManifestImportDependencies } from '../util/package-json.ts';
 import { dirname, extname, isAbsolute, isInNodeModules, join, relative } from '../util/path.ts';
-import { augmentWorkspace, getToSourcePathsHandler } from '../util/to-source-path.ts';
+import { augmentWorkspace, getToSourcePathsHandler, toSourceMappedSpecifiers } from '../util/to-source-path.ts';
 import { WorkspaceWorker } from '../WorkspaceWorker.ts';
 
 interface BuildOptions {
@@ -117,8 +117,6 @@ export async function build({
     const { isFile, compilerOptions, fileNames } = await loadTSConfig(tsConfigFilePath);
     const [definitionPaths, tscSourcePaths] = partition(fileNames, filePath => IS_DTS.test(filePath));
 
-    if (isFile) augmentWorkspace(workspace, dir, compilerOptions);
-
     const worker = new WorkspaceWorker({
       name,
       dir,
@@ -154,6 +152,9 @@ export async function build({
     const config = chief.getConfigForWorkspace(name, extensions);
     worker.config = config;
 
+    const pluginSourceMaps = await worker.resolveSourceMaps();
+    augmentWorkspace(workspace, dir, isFile ? compilerOptions : undefined, pluginSourceMaps);
+
     const inputs = new Set<Input>();
 
     if (definitionPaths.length > 0) {
@@ -180,9 +181,12 @@ export async function build({
         const packageName = getPackageNameFromModuleSpecifier(identifier);
         if (packageName && dependencies.has(packageName)) continue;
       }
-      const exists = identifier.includes('*')
-        ? _syncGlob({ patterns: [identifier], cwd: dir }).length > 0
-        : existsSync(join(dir, identifier));
+      const abs = prependDir(dir, identifier);
+      const mapped = toSourceMappedSpecifiers(workspace, abs, extensionGlobStr);
+      const hasWildcard = identifier.includes('*');
+      const exists = hasWildcard
+        ? _syncGlob({ patterns: [identifier, ...mapped], cwd: dir }).length > 0
+        : existsSync(abs) || mapped.some(pattern => _syncGlob({ patterns: [pattern], cwd: dir }).length > 0);
       if (!exists) {
         collector.addConfigurationHint({ type: 'package-entry', filePath, identifier, workspaceName: name });
       }

packages/knip/src/types/config.ts

@@ -134,6 +134,18 @@ export type ResolveConfig<T = any> = (config: T, options: PluginOptions) => Prom
 
 export type Resolve = (options: PluginOptions) => Promise<Input[]> | Input[];
 
+export type SourceMap = { srcDir: string; outDir: string };
+
+export interface ResolveSourceMapOptions {
+  cwd: string;
+  manifest: PackageJson;
+  dependencies: Set<string>;
+  rootCwd: string;
+  rootManifest: PackageJson | undefined;
+}
+
+export type ResolveSourceMap = (options: ResolveSourceMapOptions) => Promise<SourceMap[]> | SourceMap[];
+
 export type HandleInput = (input: Input) => string | undefined;
 
 export type RegisterCompilerInput = {
@@ -191,6 +203,13 @@ export interface Plugin {
   isLoadConfig?: IsLoadConfig;
   resolveConfig?: ResolveConfig;
   resolve?: Resolve;
+  /**
+   * Contributes src↔out mappings so knip can rewire files in the emitted output tree back to
+   * their source counterparts (e.g. `package.json#exports` pointing into `dist/`). Runs per
+   * workspace, before any other plugin hook, so it cannot depend on state populated by
+   * `resolveConfig`/`resolveFromAST`/`resolve`.
+   */
+  resolveSourceMap?: ResolveSourceMap;
   resolveFromAST?: ResolveFromAST;
   isFilterTransitiveDependencies?: boolean;
   registerCompilers?: RegisterCompilers;

packages/knip/src/util/to-source-path.ts

@@ -1,3 +1,4 @@
+import type { SourceMap } from '../types/config.ts';
 import type { CompilerOptions } from '../types/project.ts';
 import type { ConfigurationChief, Workspace } from '../ConfigurationChief.ts';
 import { DEFAULT_EXTENSIONS } from '../constants.ts';
@@ -12,11 +13,34 @@ const matchExt = /(\.d)?\.(m|c)?(j|t)s$/;
 
 const sourceExtensions = [...DEFAULT_EXTENSIONS];
 
-export const augmentWorkspace = (workspace: Workspace, dir: string, compilerOptions: CompilerOptions) => {
+const tsconfigSourceMap = (dir: string, compilerOptions: CompilerOptions): SourceMap => {
   const srcDir = join(dir, 'src');
   const outDirHasSrc = compilerOptions.outDir && isDirectory(compilerOptions.outDir, 'src');
-  workspace.srcDir = compilerOptions.rootDir ?? (outDirHasSrc ? dir : isDirectory(srcDir) ? srcDir : dir);
-  workspace.outDir = compilerOptions.outDir || workspace.srcDir;
+  const resolvedSrc = compilerOptions.rootDir ?? (outDirHasSrc ? dir : isDirectory(srcDir) ? srcDir : dir);
+  return { srcDir: resolvedSrc, outDir: compilerOptions.outDir || resolvedSrc };
+};
+
+export const augmentWorkspace = (
+  workspace: Workspace,
+  dir: string,
+  compilerOptions: CompilerOptions | undefined,
+  pluginSourceMaps: SourceMap[] = []
+) => {
+  const all = compilerOptions ? [...pluginSourceMaps, tsconfigSourceMap(dir, compilerOptions)] : pluginSourceMaps;
+  if (all.length === 0) return;
+  workspace.sourceMaps = all.sort((a, b) => b.outDir.length - a.outDir.length);
+};
+
+const isUnderOutDir = (absPath: string, outDir: string) => absPath === outDir || absPath.startsWith(`${outDir}/`);
+
+const isUnderSrcDir = (absPath: string, srcDir: string) => absPath === srcDir || absPath.startsWith(`${srcDir}/`);
+
+const rewritePattern = (sourceMaps: SourceMap[], absSpecifier: string, extensions: string) => {
+  for (const { srcDir, outDir } of sourceMaps) {
+    if (!isUnderSrcDir(absSpecifier, srcDir) && isUnderOutDir(absSpecifier, outDir)) {
+      return srcDir + absSpecifier.slice(outDir.length).replace(matchExt, extensions);
+    }
+  }
 };
 
 export const getModuleSourcePathHandler = (chief: ConfigurationChief) => {
@@ -26,16 +50,16 @@ export const getModuleSourcePathHandler = (chief: ConfigurationChief) => {
     if (!isInternal(filePath) || hasTSExt.test(filePath)) return;
     if (toSourceMapCache.has(filePath)) return toSourceMapCache.get(filePath);
     const workspace = chief.findWorkspaceByFilePath(filePath);
-    if (workspace?.srcDir && workspace.outDir) {
-      if (filePath.startsWith(workspace.outDir) || workspace.srcDir === workspace.outDir) {
-        const basePath = filePath.replace(workspace.outDir, workspace.srcDir).replace(matchExt, '');
-        const srcFilePath = findFileWithExtensions(basePath, sourceExtensions);
-        if (srcFilePath) {
-          toSourceMapCache.set(filePath, srcFilePath);
-          if (srcFilePath !== filePath) {
-            debugLog('*', `Source mapping ${toRelative(filePath, chief.cwd)} → ${toRelative(srcFilePath, chief.cwd)}`);
-            return srcFilePath;
-          }
+    if (!workspace?.sourceMaps) return;
+    for (const { srcDir, outDir } of workspace.sourceMaps) {
+      if (!(isUnderOutDir(filePath, outDir) || srcDir === outDir)) continue;
+      const basePath = (srcDir + filePath.slice(outDir.length)).replace(matchExt, '');
+      const srcFilePath = findFileWithExtensions(basePath, sourceExtensions);
+      if (srcFilePath) {
+        toSourceMapCache.set(filePath, srcFilePath);
+        if (srcFilePath !== filePath) {
+          debugLog('*', `Source mapping ${toRelative(filePath, chief.cwd)} → ${toRelative(srcFilePath, chief.cwd)}`);
+          return srcFilePath;
         }
       }
     }
@@ -49,12 +73,8 @@ export const getToSourcePathsHandler = (chief: ConfigurationChief) => {
     for (const specifier of specifiers) {
       const absSpecifier = isAbsolute(specifier) ? specifier : prependDirToPattern(dir, specifier);
       const ws = chief.findWorkspaceByFilePath(absSpecifier);
-      if (ws?.srcDir && ws.outDir && !absSpecifier.startsWith(ws.srcDir) && absSpecifier.startsWith(ws.outDir)) {
-        const pattern = absSpecifier.replace(ws.outDir, ws.srcDir).replace(matchExt, extensions);
-        patterns.add(pattern);
-      } else {
-        patterns.add(absSpecifier);
-      }
+      const mapped = ws?.sourceMaps && rewritePattern(ws.sourceMaps, absSpecifier, extensions);
+      patterns.add(mapped ?? absSpecifier);
     }
 
     const filePaths = await _glob({ patterns: Array.from(patterns), cwd: dir, label });
@@ -65,4 +85,19 @@ export const getToSourcePathsHandler = (chief: ConfigurationChief) => {
   };
 };
 
+export const toSourceMappedSpecifiers = (
+  ws: Workspace | undefined,
+  absSpecifier: string,
+  extensions = defaultExtensions
+) => {
+  const out: string[] = [];
+  if (!ws?.sourceMaps) return out;
+  for (const { srcDir, outDir } of ws.sourceMaps) {
+    if (!isUnderSrcDir(absSpecifier, srcDir) && isUnderOutDir(absSpecifier, outDir)) {
+      out.push(srcDir + absSpecifier.slice(outDir.length).replace(matchExt, extensions));
+    }
+  }
+  return out;
+};
+
 export type ToSourceFilePath = ReturnType<typeof getModuleSourcePathHandler>;