knip 0.8.2 → 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

@@ -59,10 +59,10 @@ const run = async () => {
                 level: isDebug ? Number(debugLevel) : 0,
             },
         });
-        printReport({ report, issues, cwd, workingDir, isDev, options: reporterOptions });
+        await printReport({ report, issues, cwd, workingDir, isDev, options: reporterOptions });
         const totalErrorCount = Object.keys(report)
-            .filter((reportGroup) => report[reportGroup])
-            .map(reportGroup => reportGroup === 'unlisted' ? 'unresolved' : reportGroup)
+            .filter(reportGroup => report[reportGroup])
+            .map(reportGroup => (reportGroup === 'unlisted' ? 'unresolved' : reportGroup))
             .reduce((errorCount, reportGroup) => errorCount + counters[reportGroup], 0);
         if (totalErrorCount > Number(maxIssues))
             process.exit(totalErrorCount);

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/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.2",
+  "version": "0.9.0",
   "description": "Find unused files, dependencies and exports in your TypeScript and JavaScript project",
   "keywords": [
     "find",
@@ -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
 }