knip 0.8.1 → 0.9.0

package/README.md

@@ -36,7 +36,7 @@ with OpenAI_</sup>
 
     npm install -D knip
 
-Knip requires at least Node.js v16.17 or v18. Knip is _cutting edge!_
+Knip supports LTS versions of Node.js, and currently requires at least Node.js v16.17 or v18.3. Knip is _cutting edge!_
 
 ## Usage
 
@@ -272,15 +272,18 @@ configuration can be tweaked further to the project structure.
 
 ## Reporters
 
-For starters, Knip already contains a few useful reporters:
+Knip provides the following built-in reporters:
 
-- `symbol` (default)
-- `compact`
-- `codeowners`
+- [`json`](#json)
+- [`symbol`](#symbol-default) (default)
+- [`compact`](#compact)
+- [`codeowners`](#code-owners)
 
 ### Custom Reporters
 
-When a `--reporter ./my-reporter` is passed, the default export of that module should have this interface:
+When the provided built-in reporters are not quite sufficient, a custom reporter can be implemented.
+
+Pass `--reporter ./my-reporter`, with the default export of that module having this interface:
 
 ```ts
 type Reporter = (options: ReporterOptions) => void;
@@ -297,7 +300,59 @@ type ReporterOptions = {
 
 The data can then be used to write issues to `stdout`, a JSON or CSV file, or sent to a service, anything really!
 
-### Example Output
+### JSON
+
+The `json` reporter output is meant to be consumed by other tools. It reports in JSON format as an array with one object
+per file like this:
+
+```json
+[
+  {
+    "file": "src/Registration.tsx",
+    "owners": ["@org/owner"],
+    "files": true,
+    "unlisted": ["react"],
+    "exports": ["lowercaseFirstLetter", "RegistrationBox"],
+    "types": ["RegistrationServices", "RegistrationAction"],
+    "duplicates": ["Registration", "default"]
+  }
+]
+```
+
+The keys match the [known issue types](#reading-the-report).
+
+#### Usage Ideas
+
+Use tools like [miller](https://github.com/johnkerl/miller) or [jtbl](https://github.com/kellyjonbrazil/jtbl) to consume
+the JSON and render a table in the terminal.
+
+##### Table
+
+```
+$ npx knip --reporter json | mlr --ijson --opprint --no-auto-flatten cat
+file                  owners      files  unlisted  exports                                types                                     duplicates
+src/Registration.tsx  @org/owner  true   react     lowercaseFirstLetter, RegistrationBox  RegistrationServices, RegistrationAction  Registration, default
+src/ProductsList.tsx  @org/team   false  -         -                                      ProductDetail                             -
+```
+
+##### Markdown Table
+
+```
+$ npx knip --reporter json | mlr --ijson --omd --no-auto-flatten cat
+| file | owners | files | duplicates |
+| --- | --- | --- | --- |
+| src/Registration.tsx | @org/owner | true | Registration, default |
+| src/ProductsList.tsx | @org/team | false |  |
+```
+
+Include specific issue types and/or replace the `cat` command with `put` for clean output:
+
+```
+npx knip --include files,duplicates --reporter json | mlr --ijson --opprint --no-auto-flatten put 'for (e in $*) { if(is_array($[e])) { $[e] = joinv($[e], ", ") } }'
+npx knip --reporter json | mlr --ijson --omd --no-auto-flatten put 'for (e in $*) { if(is_array($[e])) { $[e] = joinv($[e], ", ") } }'
+```
+
+### More Output Examples
 
 #### Symbol (default)
 

package/dist/cli.js

@@ -37,7 +37,7 @@ if (help) {
 }
 const cwd = process.cwd();
 const workingDir = dir ? node_path_1.default.resolve(dir) : cwd;
-const isShowProgress = noProgress === false ? process.stdout.isTTY && typeof process.stdout.cursorTo === 'function' : !noProgress;
+const isShowProgress = !isDebug && noProgress === false && process.stdout.isTTY && typeof process.stdout.cursorTo === 'function';
 const printReport = reporter in reporters_1.default ? reporters_1.default[reporter] : require(node_path_1.default.join(workingDir, reporter));
 const run = async () => {
     try {
@@ -59,14 +59,13 @@ const run = async () => {
                 level: isDebug ? Number(debugLevel) : 0,
             },
         });
-        printReport({ report, issues, cwd, workingDir, isDev, options: reporterOptions });
-        const reportGroup = report.files ? 'files' : Object.keys(report).find(key => report[key]);
-        const counterGroup = reportGroup === 'unlisted' ? 'unresolved' : reportGroup;
-        if (counterGroup) {
-            const count = counters[counterGroup];
-            if (count > Number(maxIssues))
-                process.exit(count);
-        }
+        await printReport({ report, issues, cwd, workingDir, isDev, options: reporterOptions });
+        const totalErrorCount = Object.keys(report)
+            .filter(reportGroup => report[reportGroup])
+            .map(reportGroup => (reportGroup === 'unlisted' ? 'unresolved' : reportGroup))
+            .reduce((errorCount, reportGroup) => errorCount + counters[reportGroup], 0);
+        if (totalErrorCount > Number(maxIssues))
+            process.exit(totalErrorCount);
     }
     catch (error) {
         if (error instanceof errors_1.ConfigurationError) {

package/dist/index.d.ts

@@ -2,16 +2,5 @@ import type { UnresolvedConfiguration } from './types';
 export declare const main: (options: UnresolvedConfiguration) => Promise<{
     report: import("./types").Report;
     issues: import("./types").Issues;
-    counters: {
-        files: number;
-        dependencies: number;
-        devDependencies: number;
-        unresolved: number;
-        exports: number;
-        types: number;
-        nsExports: number;
-        nsTypes: number;
-        duplicates: number;
-        processed: number;
-    };
+    counters: import("./types").Counters;
 }>;

package/dist/index.js

@@ -13,9 +13,12 @@ const project_1 = require("./util/project");
 const runner_1 = require("./runner");
 const errors_1 = require("./util/errors");
 const debug_1 = require("./util/debug");
+const progress_1 = require("./progress");
 const main = async (options) => {
     const { cwd, workingDir, configFilePath: configFilePathArg, tsConfigFilePath: tsConfigFilePathArg, include, exclude, ignore, gitignore, isIncludeEntryFiles, isDev, isShowProgress, jsDoc, debug, } = options;
+    const updateMessage = (0, progress_1.getMessageUpdater)(options);
     (0, debug_1.debugLogObject)(options, 1, 'Unresolved onfiguration', options);
+    updateMessage('Reading configuration and manifest files...');
     const manifestPath = await (0, fs_1.findFile)(cwd, workingDir, 'package.json');
     const manifest = manifestPath && require(manifestPath);
     const configFilePath = configFilePathArg ?? 'knip.json';
@@ -51,6 +54,7 @@ const main = async (options) => {
             const projectOptions = resolvedTsConfigFilePath
                 ? { tsConfigFilePath: resolvedTsConfigFilePath }
                 : { compilerOptions: { allowJs: true } };
+            updateMessage('Resolving entry files...');
             const entryPaths = await (0, path_1.resolvePaths)({
                 cwd,
                 workingDir,
@@ -65,6 +69,7 @@ const main = async (options) => {
             production.resolveSourceFileDependencies();
             const productionFiles = production.getSourceFiles();
             (0, debug_1.debugLogSourceFiles)(options, 1, 'Included production source files', productionFiles);
+            updateMessage('Resolving project files...');
             const projectPaths = await (0, path_1.resolvePaths)({
                 cwd,
                 workingDir,
@@ -79,6 +84,7 @@ const main = async (options) => {
             return { entryFiles, productionFiles, projectFiles };
         }
         else {
+            updateMessage('Resolving project files...');
             const project = (0, project_1.createProject)({ tsConfigFilePath: resolvedTsConfigFilePath });
             const files = project.getSourceFiles();
             return { entryFiles: files, productionFiles: files, projectFiles: files };

package/dist/progress.d.ts

@@ -0,0 +1,5 @@
+import type { Configuration, Counters, Issue } from './types';
+export declare const getMessageUpdater: (configuration: {
+    isShowProgress: boolean;
+}) => (message: string) => void;
+export declare const getCountersUpdater: (configuration: Configuration, counters: Counters) => (issue?: Issue) => void;

package/dist/progress.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCountersUpdater = exports.getMessageUpdater = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const log_1 = require("./log");
+const lineRewriter = new log_1.LineRewriter();
+const getMessageUpdater = (configuration) => {
+    const { isShowProgress } = configuration;
+    if (!isShowProgress)
+        return () => { };
+    return (message) => lineRewriter.update([message]);
+};
+exports.getMessageUpdater = getMessageUpdater;
+const getCountersUpdater = (configuration, counters) => {
+    const { workingDir, isShowProgress, report } = configuration;
+    if (!isShowProgress)
+        return () => { };
+    return (issue) => {
+        if (!issue)
+            return lineRewriter.resetLines();
+        const { processed, total } = counters;
+        const percentage = Math.floor((processed / total) * 100);
+        const messages = [(0, log_1.getLine)(`${percentage}%`, `of files processed (${processed} of ${total})`)];
+        report.files && messages.push((0, log_1.getLine)(counters.files, 'unused files'));
+        report.unlisted && messages.push((0, log_1.getLine)(counters.unresolved, 'unlisted dependencies'));
+        report.exports && messages.push((0, log_1.getLine)(counters.exports, 'unused exports'));
+        report.nsExports && messages.push((0, log_1.getLine)(counters.nsExports, 'unused exports in namespace'));
+        report.types && messages.push((0, log_1.getLine)(counters.types, 'unused types'));
+        report.nsTypes && messages.push((0, log_1.getLine)(counters.nsTypes, 'unused types in namespace'));
+        report.duplicates && messages.push((0, log_1.getLine)(counters.duplicates, 'duplicate exports'));
+        if (processed < total) {
+            messages.push('');
+            messages.push(`Processing: ${node_path_1.default.relative(workingDir, issue.filePath)}`);
+        }
+        lineRewriter.update(messages);
+    };
+};
+exports.getCountersUpdater = getCountersUpdater;

package/dist/reporters/index.d.ts

@@ -2,5 +2,6 @@ declare const _default: {
     symbols: ({ report, issues, workingDir, isDev }: import("../types").ReporterOptions) => void;
     compact: ({ report, issues, workingDir, isDev }: import("../types").ReporterOptions) => void;
     codeowners: ({ report, issues, cwd, isDev, options }: import("../types").ReporterOptions) => void;
+    json: ({ report, issues, cwd, options }: import("../types").ReporterOptions) => Promise<void>;
 };
 export default _default;

package/dist/reporters/index.js

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const symbols_1 = __importDefault(require("./symbols"));
 const compact_1 = __importDefault(require("./compact"));
 const codeowners_1 = __importDefault(require("./codeowners"));
+const json_1 = __importDefault(require("./json"));
 exports.default = {
     symbols: symbols_1.default,
     compact: compact_1.default,
     codeowners: codeowners_1.default,
+    json: json_1.default,
 };

package/dist/reporters/json.d.ts

@@ -0,0 +1,3 @@
+import type { ReporterOptions } from '../types';
+declare const _default: ({ report, issues, cwd, options }: ReporterOptions) => Promise<void>;
+export default _default;

package/dist/reporters/json.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../util/fs");
+const ownership_1 = require("@snyk/github-codeowners/dist/lib/ownership");
+exports.default = async ({ report, issues, cwd, options }) => {
+    let opts = {};
+    try {
+        opts = options ? JSON.parse(options) : opts;
+    }
+    catch (error) {
+        console.error(error);
+    }
+    const json = {};
+    const codeownersFilePath = node_path_1.default.resolve(opts.codeowners ?? '.github/CODEOWNERS');
+    const codeownersEngine = (await (0, fs_1.isFile)(codeownersFilePath)) && ownership_1.OwnershipEngine.FromCodeownersFile(codeownersFilePath);
+    const flatten = (issues) => Object.values(issues).map(Object.values).flat();
+    const initRow = (filePath) => {
+        const file = node_path_1.default.relative(cwd, filePath);
+        const row = {
+            file,
+            ...(codeownersEngine && { owners: codeownersEngine.calcFileOwnership(file) }),
+            ...(report.files && { files: false }),
+            ...(report.unlisted && { unlisted: [] }),
+            ...((report.exports || report.nsExports) && { exports: [] }),
+            ...((report.types || report.nsTypes) && { types: [] }),
+            ...(report.duplicates && { duplicates: [] }),
+        };
+        return row;
+    };
+    if (report.files) {
+        issues.files.forEach(filePath => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].files = true;
+        });
+    }
+    if (report.unlisted) {
+        flatten(issues.unresolved).forEach(({ filePath, symbol }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].unlisted?.push(symbol);
+        });
+    }
+    if (report.exports) {
+        flatten(issues.exports).forEach(({ filePath, symbol }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].exports?.push(symbol);
+        });
+    }
+    if (report.nsExports) {
+        flatten(issues.nsExports).forEach(({ filePath, symbol }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].exports?.push(symbol);
+        });
+    }
+    if (report.types) {
+        flatten(issues.types).forEach(({ filePath, symbol }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].types = json[filePath].types ?? [];
+            json[filePath].types?.push(symbol);
+        });
+    }
+    if (report.nsTypes) {
+        flatten(issues.nsTypes).forEach(({ filePath, symbol }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].types?.push(symbol);
+        });
+    }
+    if (report.duplicates) {
+        flatten(issues.duplicates).forEach(({ filePath, symbols }) => {
+            json[filePath] = json[filePath] ?? initRow(filePath);
+            json[filePath].duplicates?.push(...symbols);
+        });
+    }
+    console.log(JSON.stringify(Object.values(json)));
+};

package/dist/reporters/symbols.js

@@ -4,9 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_path_1 = __importDefault(require("node:path"));
-const logIssueLine = ({ issue, workingDir, padding }) => {
+const TRUNCATE_WIDTH = 40;
+const logIssueLine = (issue, workingDir, maxWidth) => {
     const symbols = issue.symbols ? issue.symbols.join(', ') : issue.symbol;
-    console.log(`${symbols.padEnd(padding + 2)}${issue.symbolType?.padEnd(11) || ''}${node_path_1.default.relative(workingDir, issue.filePath)}`);
+    const truncatedSymbol = symbols.length > maxWidth ? symbols.slice(0, maxWidth - 3) + '...' : symbols;
+    const filePath = node_path_1.default.relative(workingDir, issue.filePath);
+    console.log(`${truncatedSymbol.padEnd(maxWidth + 2)}${issue.symbolType?.padEnd(11) || ''}${filePath}`);
 };
 const logIssueGroupResult = (issues, workingDir, title) => {
     title && console.log(`--- ${title} (${issues.length})`);
@@ -17,12 +20,12 @@ const logIssueGroupResult = (issues, workingDir, title) => {
         console.log('Not found');
     }
 };
-const logIssueGroupResults = (issues, workingDir, title) => {
+const logIssueGroupResults = (issues, workingDir, title, isTruncate = false) => {
     title && console.log(`--- ${title} (${issues.length})`);
     if (issues.length) {
         const sortedByFilePath = issues.sort((a, b) => (a.filePath > b.filePath ? 1 : -1));
-        const padding = [...issues].sort((a, b) => b.symbol.length - a.symbol.length)[0].symbol.length;
-        sortedByFilePath.forEach(issue => logIssueLine({ issue, workingDir, padding }));
+        const maxWidth = isTruncate ? TRUNCATE_WIDTH : issues.reduce((max, issue) => Math.max(issue.symbol.length, max), 0);
+        sortedByFilePath.forEach(issue => logIssueLine(issue, workingDir, maxWidth));
     }
     else {
         console.log('Not found');
@@ -64,6 +67,6 @@ exports.default = ({ report, issues, workingDir, isDev }) => {
     }
     if (report.duplicates) {
         const unreferencedDuplicates = Object.values(issues.duplicates).map(Object.values).flat();
-        logIssueGroupResults(unreferencedDuplicates, workingDir, reportMultipleGroups && 'DUPLICATE EXPORTS');
+        logIssueGroupResults(unreferencedDuplicates, workingDir, reportMultipleGroups && 'DUPLICATE EXPORTS', true);
     }
 };

package/dist/runner.d.ts

@@ -1,16 +1,5 @@
-import type { Configuration, Issues } from './types';
+import type { Configuration, Issues, Counters } from './types';
 export declare function findIssues(configuration: Configuration): Promise<{
     issues: Issues;
-    counters: {
-        files: number;
-        dependencies: number;
-        devDependencies: number;
-        unresolved: number;
-        exports: number;
-        types: number;
-        nsExports: number;
-        nsTypes: number;
-        duplicates: number;
-        processed: number;
-    };
+    counters: Counters;
 }>;

package/dist/runner.js

@@ -10,12 +10,12 @@ const ts_morph_helpers_1 = require("ts-morph-helpers");
 const project_1 = require("./util/project");
 const type_1 = require("./util/type");
 const dependencies_1 = require("./util/dependencies");
-const log_1 = require("./log");
 const debug_1 = require("./util/debug");
-const lineRewriter = new log_1.LineRewriter();
+const progress_1 = require("./progress");
 async function findIssues(configuration) {
-    const { workingDir, isShowProgress, report, isDev, jsDocOptions } = configuration;
+    const { workingDir, report, isDev, jsDocOptions } = configuration;
     const { entryFiles, productionFiles, projectFiles, isIncludeEntryFiles } = configuration;
+    const updateMessage = (0, progress_1.getMessageUpdater)(configuration);
     const { getUnresolvedDependencies, getUnusedDependencies, getUnusedDevDependencies } = (0, dependencies_1.getDependencyAnalyzer)(configuration);
     const [usedProductionFiles, unreferencedProductionFiles] = (0, project_1.partitionSourceFiles)(projectFiles, productionFiles);
     const [usedEntryFiles, usedNonEntryFiles] = (0, project_1.partitionSourceFiles)(usedProductionFiles, entryFiles);
@@ -45,42 +45,25 @@ async function findIssues(configuration) {
         nsTypes: 0,
         duplicates: 0,
         processed: issues.files.size,
+        total: projectFiles.length,
     };
-    const updateProcessingOutput = (item) => {
-        if (!isShowProgress)
-            return;
-        const counter = counters.processed;
-        const total = projectFiles.length;
-        const percentage = Math.floor((counter / total) * 100);
-        const messages = [(0, log_1.getLine)(`${percentage}%`, `of files processed (${counter} of ${total})`)];
-        report.files && messages.push((0, log_1.getLine)(unreferencedProductionFiles.length, 'unused files'));
-        report.unlisted && messages.push((0, log_1.getLine)(counters.unresolved, 'unlisted dependencies'));
-        report.exports && messages.push((0, log_1.getLine)(counters.exports, 'unused exports'));
-        report.nsExports && messages.push((0, log_1.getLine)(counters.nsExports, 'unused exports in namespace'));
-        report.types && messages.push((0, log_1.getLine)(counters.types, 'unused types'));
-        report.nsTypes && messages.push((0, log_1.getLine)(counters.nsTypes, 'unused types in namespace'));
-        report.duplicates && messages.push((0, log_1.getLine)(counters.duplicates, 'duplicate exports'));
-        if (counter < total) {
-            messages.push('');
-            messages.push(`Processing: ${node_path_1.default.relative(workingDir, item.filePath)}`);
-        }
-        lineRewriter.update(messages);
-    };
+    const updateCounters = (0, progress_1.getCountersUpdater)(configuration, counters);
     const addSymbolIssue = (issueType, issue) => {
         const { filePath, symbol } = issue;
         const key = node_path_1.default.relative(workingDir, filePath);
         issues[issueType][key] = issues[issueType][key] ?? {};
         issues[issueType][key][symbol] = issue;
         counters[issueType]++;
-        updateProcessingOutput(issue);
+        updateCounters(issue);
     };
     const addProjectIssue = (issueType, issue) => {
         if (!issues[issueType].has(issue.symbol)) {
             issues[issueType].add(issue.symbol);
             counters[issueType]++;
         }
-        updateProcessingOutput(issue);
+        updateCounters(issue);
     };
+    updateMessage('Connecting the dots...');
     if (report.dependencies ||
         report.unlisted ||
         report.exports ||
@@ -197,8 +180,7 @@ async function findIssues(configuration) {
             unusedDevDependencies.forEach(symbol => addProjectIssue('devDependencies', { filePath: '', symbol }));
         }
     }
-    if (isShowProgress)
-        lineRewriter.resetLines();
+    updateCounters();
     return { issues, counters };
 }
 exports.findIssues = findIssues;

package/dist/types.d.ts

@@ -78,6 +78,7 @@ export declare type Configuration = {
         level: number;
     };
 };
+export declare type Counters = Record<IssueType | 'processed' | 'total', number>;
 export declare type ReporterOptions = {
     report: Report;
     issues: Issues;

package/dist/util/fs.d.ts

@@ -1 +1,2 @@
+export declare const isFile: (filePath: string) => Promise<boolean>;
 export declare const findFile: (cwd: string, workingDir: string, fileName: string) => Promise<string | undefined>;

package/dist/util/fs.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findFile = void 0;
+exports.findFile = exports.isFile = void 0;
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const isFile = async (filePath) => {
@@ -15,9 +15,10 @@ const isFile = async (filePath) => {
         return false;
     }
 };
+exports.isFile = isFile;
 const findFile = async (cwd, workingDir, fileName) => {
     const filePath = node_path_1.default.join(workingDir, fileName);
-    if (await isFile(filePath)) {
+    if (await (0, exports.isFile)(filePath)) {
         return filePath;
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knip",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Find unused files, dependencies and exports in your TypeScript and JavaScript project",
   "keywords": [
     "find",
@@ -24,7 +24,7 @@
     "knip": "dist/cli.js"
   },
   "scripts": {
-    "knip": "node ./dist/cli.js",
+    "knip": "node ./dist/cli.js --include files,dependencies,unlisted",
     "test": "node --loader tsx --test test/*.spec.ts",
     "watch": "tsc --watch",
     "build": "rm -rf dist && tsc",
@@ -49,10 +49,10 @@
   },
   "devDependencies": {
     "@types/micromatch": "4.0.2",
-    "@types/node": "18.8.5",
+    "@types/node": "18.11.2",
     "prettier": "2.7.1",
     "release-it": "15.5.0",
-    "tsx": "3.10.1",
+    "tsx": "3.10.3",
     "typescript": "4.8.4"
   },
   "release-it": {
@@ -61,7 +61,7 @@
     }
   },
   "engines": {
-    "node": ">=16.17.0"
+    "node": ">=16.17.0 <17 || >=18.3.0"
   },
   "engineStrict": true
 }