Add some basic debugging and comments for future self (closes #6)

Author: webpro

README.md

@@ -93,6 +93,8 @@ Options:
   --max-issues           Maximum number of issues before non-zero exit code (default: 0)
   --reporter             Select reporter: symbols, compact (default: symbols)
   --jsdoc                Enable JSDoc parsing, with options: public
+  --debug                Show debug output
+  --debug-level          Set verbosity of debug output (default: 1, max: 2)
 
 Issue groups: files, dependencies, unlisted, exports, nsExports, types, nsTypes, duplicates
 

src/cli.ts

@@ -23,6 +23,8 @@ const {
     reporter = 'symbols',
     'max-issues': maxIssues = '0',
     jsdoc: jsDoc = [],
+    debug: isDebug = false,
+    'debug-level': debugLevel = '1',
   },
 } = parseArgs({
   options: {
@@ -39,6 +41,8 @@ const {
     'max-issues': { type: 'string' },
     reporter: { type: 'string' },
     jsdoc: { type: 'string', multiple: true },
+    debug: { type: 'boolean' },
+    'debug-level': { type: 'string' },
   },
 });
 
@@ -70,6 +74,10 @@ const run = async () => {
       isDev,
       isShowProgress,
       jsDoc,
+      debug: {
+        isEnabled: isDebug,
+        level: isDebug ? Number(debugLevel) : 0,
+      },
     });
 
     printReport({ report, issues, workingDir, isDev });

src/help.ts

@@ -14,6 +14,8 @@ Options:
   --max-issues           Maximum number of issues before non-zero exit code (default: 0)
   --reporter             Select reporter: symbols, compact (default: symbols)
   --jsdoc                Enable JSDoc parsing, with options: public
+  --debug                Show debug output
+  --debug-level          Set verbosity of debug output (default: 1, max: 2)
 
 Issue groups: files, dependencies, unlisted, exports, nsExports, types, nsTypes, duplicates
 

src/index.ts

@@ -6,6 +6,7 @@ import { resolvePaths } from './util/path';
 import { createProject } from './util/project';
 import { findIssues } from './runner';
 import { ConfigurationError } from './util/errors';
+import { debugLogObject, debugLogFiles, debugLogSourceFiles } from './util/debug';
 import type { UnresolvedConfiguration, Configuration } from './types';
 
 export const main = async (options: UnresolvedConfiguration) => {
@@ -21,8 +22,11 @@ export const main = async (options: UnresolvedConfiguration) => {
     isDev,
     isShowProgress,
     jsDoc,
+    debug,
   } = options;
 
+  debugLogObject(options, 1, 'Unresolved onfiguration', options);
+
   const localConfigurationPath = configFilePath && (await findFile(workingDir, configFilePath));
   const manifestPath = await findFile(workingDir, 'package.json');
   const localConfiguration = localConfigurationPath && require(localConfigurationPath);
@@ -36,6 +40,8 @@ export const main = async (options: UnresolvedConfiguration) => {
   const dir = path.relative(cwd, workingDir);
   const resolvedConfig = resolveConfig(manifest.knip ?? localConfiguration, { workingDir: dir, isDev });
 
+  debugLogObject(options, 1, 'Resolved onfiguration', resolvedConfig);
+
   if (!resolvedConfig) {
     throw new ConfigurationError('Unable to find `entryFiles` and/or `projectFiles` in configuration.');
   }
@@ -61,29 +67,38 @@ export const main = async (options: UnresolvedConfiguration) => {
 
   const projectOptions = tsConfigPath ? { tsConfigFilePath: tsConfigPath } : { compilerOptions: { allowJs: true } };
 
-  // Create workspace for entry files + resolved dependencies
   const entryPaths = await resolvePaths({
     cwd,
     workingDir,
     patterns: resolvedConfig.entryFiles,
     ignore,
     gitignore,
   });
+  debugLogFiles(options, 1, 'Globbed entry paths', entryPaths);
+
+  // Create workspace for entry files, but don't resolve dependencies yet
   const production = createProject({ projectOptions, paths: entryPaths });
   const entryFiles = production.getSourceFiles();
+  debugLogSourceFiles(options, 1, 'Included entry source files', entryFiles);
+
+  // Now resolve dependencies of entry files to find all production files
   production.resolveSourceFileDependencies();
   const productionFiles = production.getSourceFiles();
+  debugLogSourceFiles(options, 1, 'Included production source files', productionFiles);
 
-  // Create workspace for the entire project
   const projectPaths = await resolvePaths({
     cwd,
     workingDir,
     patterns: resolvedConfig.projectFiles,
     ignore,
     gitignore,
   });
+  debugLogFiles(options, 1, 'Globbed project paths', projectPaths);
+
+  // Create workspace for the entire project
   const project = createProject({ projectOptions, paths: projectPaths });
   const projectFiles = project.getSourceFiles();
+  debugLogSourceFiles(options, 1, 'Included project source files', projectFiles);
 
   const config: Configuration = {
     workingDir,
@@ -99,9 +114,12 @@ export const main = async (options: UnresolvedConfiguration) => {
     jsDocOptions: {
       isReadPublicTag: jsDoc.includes('public'),
     },
+    debug,
   };
 
   const { issues, counters } = await findIssues(config);
 
+  debugLogObject(options, 2, 'Issues', issues);
+
   return { report, issues, counters };
 };

src/runner.ts

@@ -5,6 +5,7 @@ import { partitionSourceFiles } from './util/project';
 import { getType } from './util/type';
 import { getDependencyAnalyzer } from './util/dependencies';
 import { getLine, LineRewriter } from './log';
+import { debugLogSourceFiles } from './util/debug';
 import type { Identifier } from 'ts-morph';
 import type { Configuration, Issues, Issue, ProjectIssueType, SymbolIssueType } from './types';
 
@@ -21,6 +22,11 @@ export async function findIssues(configuration: Configuration) {
   const [usedProductionFiles, unreferencedProductionFiles] = partitionSourceFiles(projectFiles, productionFiles);
   const [usedEntryFiles, usedNonEntryFiles] = partitionSourceFiles(usedProductionFiles, entryFiles);
 
+  debugLogSourceFiles(configuration, 1, 'usedProductionFiles', usedProductionFiles);
+  debugLogSourceFiles(configuration, 1, 'unreferencedProductionFiles', unreferencedProductionFiles);
+  debugLogSourceFiles(configuration, 1, 'usedEntryFiles', usedEntryFiles);
+  debugLogSourceFiles(configuration, 1, 'usedNonEntryFiles', usedNonEntryFiles);
+
   // Set up the results
   const issues: Issues = {
     files: new Set(unreferencedProductionFiles.map(file => file.getFilePath())),
@@ -86,14 +92,16 @@ export async function findIssues(configuration: Configuration) {
   };
 
   if (report.dependencies || report.unlisted) {
+    // Performance optimization: a separate traversal over only the entry files to find unused/unlisted dependencies,
+    // the rest will be done during the non-entry files traversal.
     usedEntryFiles.forEach(sourceFile => {
       counters.processed++;
       const unresolvedDependencies = getUnresolvedDependencies(sourceFile);
       unresolvedDependencies.forEach(issue => addSymbolIssue('unresolved', issue));
     });
   }
 
-  // Skip when only interested in unreferenced files
+  // Skip expensive traversal when only reporting unreferenced files
   if (
     report.dependencies ||
     report.unlisted ||
@@ -103,6 +111,7 @@ export async function findIssues(configuration: Configuration) {
     report.nsTypes ||
     report.duplicates
   ) {
+    // We only traverse the non-entry production files, since entry files and any exports are marked as used.
     usedNonEntryFiles.forEach(sourceFile => {
       counters.processed++;
       const filePath = sourceFile.getFilePath();
@@ -177,7 +186,8 @@ export async function findIssues(configuration: Configuration) {
 
                 if (!isReferencedOnlyBySelf) return; // This identifier is used somewhere else
 
-                // No more reasons left to think this identifier is used somewhere else, report it as unreferenced
+                // No more reasons left to think this identifier is used somewhere else, report it as unreferenced. If
+                // it's on a namespace somewhere, report it in a separate issue type.
                 if (findReferencingNamespaceNodes(sourceFile).length > 0) {
                   if (type) {
                     addSymbolIssue('nsTypes', { filePath, symbol: identifierText, symbolType: type });

src/types.ts

@@ -61,6 +61,10 @@ export type UnresolvedConfiguration = {
   isDev: boolean;
   isShowProgress: boolean;
   jsDoc: string[];
+  debug: {
+    isEnabled: boolean;
+    level: number;
+  };
 };
 
 export type Report = {
@@ -81,4 +85,8 @@ export type Configuration = {
   jsDocOptions: {
     isReadPublicTag: boolean;
   };
+  debug: {
+    isEnabled: boolean;
+    level: number;
+  };
 };

src/util/debug.ts

@@ -0,0 +1,48 @@
+import util from 'node:util';
+import type { SourceFile } from 'ts-morph';
+
+type Config = { debug: { isEnabled: boolean; level: number } };
+
+// Inspect arrays, otherwise Node [will, knip, ...n-100 more items]
+const logArray = (collection: string[]) => console.log(util.inspect(collection, { maxArrayLength: null }));
+
+export const debugLogObject = (config: Config, minimumLevel: number, name: string, obj: unknown) => {
+  if (minimumLevel > config.debug.level) return;
+  console.log(`[exportman] ${name}:`);
+  console.log(util.inspect(obj, { depth: null, colors: true }));
+};
+
+export const debugLogFiles = (config: Config, minimumLevel: number, name: string, filePaths: string[]) => {
+  if (minimumLevel > config.debug.level) return;
+  const { debug } = config;
+  if (debug.level > 1) {
+    console.debug(`[exportman] ${name} (${filePaths.length}):`);
+    logArray(filePaths);
+  } else {
+    console.debug(`[exportman] ${name} (${filePaths.length})`);
+  }
+};
+
+export const debugLogSourceFiles = (config: Config, minimumLevel: number, name: string, sourceFiles: SourceFile[]) => {
+  if (minimumLevel > config.debug.level) return;
+  const { debug } = config;
+  if (debug.level > 1) {
+    // let files = Array.from(sourceFiles);
+    console.debug(`[exportman] ${name} (${sourceFiles.length}):`);
+    logArray(sourceFiles.map(sourceFile => sourceFile.getFilePath()));
+  } else {
+    console.debug(`[exportman] ${name} (${sourceFiles.length})`);
+  }
+};
+
+export const debugLogDiff = (config: Config, minimumLevel: number, name: string, arrA: string[], arrB: string[]) => {
+  if (minimumLevel > config.debug.level) return;
+  const onlyInA = arrA.filter(itemA => !arrB.includes(itemA)).sort();
+  const onlyInB = arrB.filter(itemB => !arrA.includes(itemB)).sort();
+  console.log(`[exportman] ${name}`);
+  console.log(`[exportman] Only in left:`);
+  logArray(onlyInA);
+  console.log();
+  console.log(`[exportman] Only in right:`);
+  logArray(onlyInB);
+};

src/util/path.ts

@@ -29,6 +29,8 @@ export const resolvePaths = async ({
   gitignore: boolean;
 }) =>
   glob(
+    // Prepend relative --dir to patterns to use cwd (not workingDir), because
+    // we want to glob everything to include all (git)ignore patterns
     patterns.map(pattern => prependDirToPattern(path.relative(cwd, workingDir), pattern)),
     {
       cwd,

test/basic.spec.ts

@@ -11,10 +11,14 @@ test('Find unused files and exports', async () => {
     include: [],
     exclude: [],
     ignore: [],
-    isNoGitIgnore: true,
+    gitignore: false,
     isDev: false,
     isShowProgress: false,
     jsDoc: [],
+    debug: {
+      isEnabled: false,
+      level: 0,
+    },
   });
 
   assert(issues.files.size === 1);

test/dependencies.spec.ts

@@ -11,10 +11,14 @@ test('Find unused dependencies', async () => {
     include: [],
     exclude: [],
     ignore: [],
-    isNoGitIgnore: true,
+    gitignore: false,
     isDev: false,
     isShowProgress: false,
     jsDoc: [],
+    debug: {
+      isEnabled: false,
+      level: 0,
+    },
   });
 
   assert(Array.from(issues.files)[0].endsWith('unused.ts'));