knip 2.0.0-beta.1 → 2.0.0

package/README.md

@@ -7,23 +7,23 @@ dependencies leads to improved performance, less maintenance and easier refactor
 export const myVar = true;
 ```
 
-ESLint handles files in isolation, so it does not know whether `myVar` is actually used somewhere else. Knip lints the
-project as a whole, and finds unused exports, files and dependencies.
+This is where ESLint stops: it handles files in isolation, so it does not know whether `myVar` is used somewhere else.
+This is where Knip starts: it lints the project as a whole, and finds unused exports, files and dependencies.
 
-It's only human to forget removing things that you no longer use. But how do you find out? Where to even start finding
+It's only human to forget removing things that you no longer use. But how do you find out? Where do you start finding
 things that can be removed?
 
 The dots don't connect themselves. This is where Knip comes in:
 
 - [x] Finds **unused files, dependencies and exports**
 - [x] Finds used dependencies not listed in `package.json`
-- [x] Finds duplicate exports
-- [x] Finds unused members of classes and enums
-- [x] Built-in support for [monorepos/workspaces][1]
+- [x] Built-in support for [workspaces (monorepos)][1]
 - [x] Growing list of [built-in plugins][2]
-- [x] Use [compilers][3] to include other file types (e.g. MDX, Vue, Svelte)
+- [x] Use [compilers][3] to include other file types (e.g. `.mdx`, `.vue`, `.svelte`)
 - [x] Checks npm scripts for used and unlisted dependencies
-- [x] Supports JavaScript (without `tsconfig.json`, or TypeScript `allowJs: true`)
+- [x] Finds unused members of classes and enums
+- [x] Finds duplicate exports
+- [x] Supports any combination of JavaScript and TypeScript
 - [x] Features multiple [reporters][4] and supports [custom reporters][5]
 - [x] Run Knip as part of your CI environment to detect issues and prevent regressions
 
@@ -34,8 +34,8 @@ with OpenAI_</sup>
 
 ## Migrating to v2.0.0
 
-Migrating from v1 to v2 requires no changes in configuration. Please see [https://github.com/webpro/knip/issues/73][8]
-for the full story.
+Migrating from v1 to v2 requires no changes in configuration. Mostly it's just a whole lot faster! The [release notes
+for v2][8] provide more details.
 
 ## Installation
 
@@ -63,7 +63,7 @@ file. Let's say you are using `.ts` files excusively and have all source files o
 
 ```json
 {
-  "$schema": "https://unpkg.com/knip@next/schema.json",
+  "$schema": "https://unpkg.com/knip@2/schema.json",
   "entry": ["src/index.ts"],
   "project": ["src/**/*.ts"]
 }
@@ -107,7 +107,7 @@ Then run the checks with `npx knip`. Or first add this script to `package.json`:
 Use `npm run knip` to analyze the project and output unused files, dependencies and exports. Knip works just fine with
 `yarn` or `pnpm` as well.
 
-Using workspaces in a monorepo? Please see [workspaces & monorepos][1] for more details about configuring them.
+Using workspaces in a monorepo? Please see [workspaces][1] for more details about configuring them.
 
 ## Command-line options
 
@@ -122,11 +122,10 @@ Using workspaces in a monorepo? Please see [workspaces & monorepos][1] for more
       --production             Analyze only production source files (e.g. no tests, devDependencies, exported types)
       --strict                 Consider only direct dependencies of workspace (not devDependencies, not other workspaces)
       --workspace              Analyze a single workspace (default: analyze all configured workspaces)
-      --ignore                 Ignore files matching this glob pattern, can be repeated
       --no-gitignore           Don't use .gitignore
       --include                Report only provided issue type(s), can be comma-separated or repeated (1)
       --exclude                Exclude provided issue type(s) from report, can be comma-separated or repeated (1)
-      --dependencies           Shortcut for --include dependencies,unlisted
+      --dependencies           Shortcut for --include dependencies,unlisted,unresolved
       --exports                Shortcut for --include exports,nsExports,classMembers,types,nsTypes,enumMembers,duplicates
       --no-progress            Don't show dynamic progress updates
       --reporter               Select reporter: symbols, compact, codeowners, json (default: symbols)
@@ -233,7 +232,7 @@ As always, make sure to backup files or use Git before deleting files or making
 
 🔁 Repeat the process to reveal new unused files and exports. Sometimes it's so liberating to remove things!
 
-## Workspaces & Monorepos
+## Workspaces (monorepos)
 
 Workspaces and monorepos are handled out-of-the-box by Knip. Every workspace is part of the analysis.
 
@@ -282,6 +281,22 @@ Use `--debug` to get more verbose output.
 
 ## Plugins
 
+Plugins tell Knip where to look for configuration and entry files, and if necessary have a custom dependency finder.
+Knip plugins are automatically activated, you don't need to install or configure anything.
+
+To explain what they do, here's a quick example from a `.eslintrc.json` configuration file (for ESLint):
+
+```json
+{
+  "extends": ["airbnb"],
+  "plugins": ["prettier"]
+}
+```
+
+Knip's ESLint plugin reads `.eslintrc.json` and will return `eslint-config-airbnb` and `eslint-plugin-prettier` from
+this example to Knip, so it can tell you whether `package.json` is out of sync. In a nutshell, this is how plugins work.
+This is especially useful over time when such configuration files change (and they will)!
+
 Knip contains a growing list of plugins:
 
 - [Ava][plugin-ava]
@@ -317,32 +332,60 @@ Knip contains a growing list of plugins:
 - [Storybook][plugin-storybook]
 - [Stryker][plugin-stryker]
 - [Svelte][plugin-svelte]
+- [Tailwind][plugin-tailwind]
 - [TypeDoc][plugin-typedoc]
 - [TypeScript][plugin-typescript]
 - [Vitest][plugin-vitest]
 - [Webpack][plugin-webpack]
 
 Plugins are automatically activated. Each plugin is automatically enabled based on simple heuristics. Most of them check
-whether one or one of a few (dev) dependencies are listed in `package.json`. Once enabled, they add a set of
-configuration and/or entry files for Knip to analyze. These defaults can be overriden.
-
-Most plugins use one or both of the following file types:
+whether one of a few dependencies are listed in `package.json`. Once enabled, they add a set of `config` files for
+itself and/or `entry` files for Knip to analyze.
 
-- `config` - custom dependency resolvers are applied to the [config files][11]
-- `entry` - files to include with the analysis of the rest of the source code
+- `config` files are given to the plugin's dependency finder
+- `entry` files are given to Knip to include with the analysis of the rest of the source code
 
 See each plugin's documentation for its default values.
 
 ### `config`
 
-Plugins may include `config` files. They are parsed by the plugin's custom dependency finder. Custom dependency finders
-return all dependencies referenced in the configuration files it is given. Knip handles the rest to determine which of
-those dependencies are unused or missing.
+Plugins usually include `config` files. They are handled by the plugin's custom dependency finder, which returns all
+dependencies referenced in the files it is given. Knip handles the rest to determine which of those dependencies are
+unused or missing.
 
 ### `entry`
 
-Other configuration files use `require` or `import` statements to use dependencies, so they can be analyzed like the
-rest of the source files. These configuration files are also considered `entry` files.
+Other configuration files use `require` or `import` statements to use dependencies, so they don't need special handing
+and can be analyzed like any other source file. That's why these configuration files are also used as `entry` files.
+
+### Override plugin configuration
+
+Usually no custom configuration is required for plugins, but if your project uses custom file locations then Knip allows
+to override any defaults. Let's take Cypress for example. By default it uses `cypress.config.js`, but your project uses
+`config/cypress.js`. Also, the default pattern for test files is `cypress/e2e/**/*.cy.js`, but your project has them at
+`e2e-tests/*.spec.ts`. Here's how to configure this:
+
+```json
+{
+  "cypress": {
+    "entry": ["config/cypress.js", "e2e-tests/*.spec.js"]
+  }
+}
+```
+
+### Multi-project repositories
+
+Some repositories have a single `package.json`, but consist of multiple projects with potentially lots of configuration
+files (such as the [Nx "intregrated repo" style][11]). Let's assume some of these projects are apps and have their own
+Cypress configuration and test files. In that case, we could configure the Cypress plugin like this:
+
+```json
+{
+  "cypress": {
+    "entry": ["apps/**/cypress.config.ts", "apps/**/cypress/e2e/*.spec.ts"]
+  }
+}
+```
 
 ### Disable a plugin
 
@@ -360,7 +403,8 @@ finding unused or missing dependencies. For instance, `.mdx`, `.vue` and `.svelt
 
 Currently this is only supported by using `knip.js` or `knip.ts`. Provide a `compilers` object in the configuration
 where each key represents the extension and the value is a function that takes the contents of these files as input and
-returns JavaScript or TypeScript as output. For example:
+returns JavaScript or TypeScript as output. Here is an example that compiles `.mdx` files to JavaScript so these files
+and their imports and exports become part of the analyis:
 
 ```js
 import { compileSync } from 'mdx-js/mdx';
@@ -421,7 +465,7 @@ aliases. They can be configured manually:
 
 ```json
 {
-  "$schema": "https://unpkg.com/knip@next/schema.json",
+  "$schema": "https://unpkg.com/knip@2/schema.json",
   "paths": {
     "@lib": ["./lib/index.ts"],
     "@lib/*": ["./lib/*"]
@@ -447,22 +491,8 @@ Knip provides the following built-in reporters:
 
 When the provided built-in reporters are not 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;
-
-type ReporterOptions = {
-  report: Report;
-  issues: Issues;
-  cwd: string;
-  workingDir: string;
-  isProduction: boolean;
-  options: string;
-};
-```
-
-The data can then be used to write issues to `stdout`, a JSON or CSV file, or sent to a service.
+Pass `--reporter ./my-reporter` from the command-line. The data can then be used to write issues to `stdout`, a JSON or
+CSV file, or sent to a service.
 
 Find more details and ideas in [custom reporters][14].
 
@@ -537,23 +567,23 @@ All of this is hiding problems, so please make sure to plan for fixing them and/
 
 This table is an ongoing comparison. Based on their docs (please report any mistakes):
 
-| Feature                           | **knip** | [depcheck][17] | [unimported][18] | [ts-unused-exports][19] | [ts-prune][20] |
-| :-------------------------------- | :------: | :------------: | :--------------: | :---------------------: | :------------: |
-| Unused files                      |    ✅    |       -        |        ✅        |            -            |       -        |
-| Unused dependencies               |    ✅    |       ✅       |        ✅        |            -            |       -        |
-| Unlisted dependencies             |    ✅    |       ✅       |        ✅        |            -            |       -        |
-| [Plugins][2]                      |    ✅    |       ✅       |        ❌        |            -            |       -        |
-| [Compilers][3]                    |    ✅    |       -        |        -         |            -            |       -        |
-| Unused exports                    |    ✅    |       -        |        -         |           ✅            |       ✅       |
-| Unused class members              |    ✅    |       -        |        -         |            -            |       -        |
-| Unused enum members               |    ✅    |       -        |        -         |            -            |       -        |
-| Duplicate exports                 |    ✅    |       -        |        -         |           ❌            |       ❌       |
-| Search namespaces                 |    ✅    |       -        |        -         |           ✅            |       ❌       |
-| Custom reporters                  |    ✅    |       -        |        -         |            -            |       -        |
-| JavaScript support                |    ✅    |       ✅       |        ✅        |            -            |       -        |
-| Configure entry files             |    ✅    |       ❌       |        ✅        |           ❌            |       ❌       |
-| [Support workspaces/monorepos][1] |    ✅    |       ❌       |        ❌        |            -            |       -        |
-| ESLint plugin available           |    -     |       -        |        -         |           ✅            |       -        |
+| Feature                 | **knip** | [depcheck][17] | [unimported][18] | [ts-unused-exports][19] | [ts-prune][20] |
+| :---------------------- | :------: | :------------: | :--------------: | :---------------------: | :------------: |
+| Unused files            |    ✅    |       -        |        ✅        |            -            |       -        |
+| Unused dependencies     |    ✅    |       ✅       |        ✅        |            -            |       -        |
+| Unlisted dependencies   |    ✅    |       ✅       |        ✅        |            -            |       -        |
+| [Plugins][2]            |    ✅    |       ✅       |        ❌        |            -            |       -        |
+| [Compilers][3]          |    ✅    |       -        |        -         |            -            |       -        |
+| Unused exports          |    ✅    |       -        |        -         |           ✅            |       ✅       |
+| Unused class members    |    ✅    |       -        |        -         |            -            |       -        |
+| Unused enum members     |    ✅    |       -        |        -         |            -            |       -        |
+| Duplicate exports       |    ✅    |       -        |        -         |           ❌            |       ❌       |
+| Search namespaces       |    ✅    |       -        |        -         |           ✅            |       ❌       |
+| Custom reporters        |    ✅    |       -        |        -         |            -            |       -        |
+| JavaScript support      |    ✅    |       ✅       |        ✅        |            -            |       -        |
+| Configure entry files   |    ✅    |       ❌       |        ✅        |           ❌            |       ❌       |
+| [Support workspaces][1] |    ✅    |       ❌       |        ❌        |            -            |       -        |
+| ESLint plugin available |    -     |       -        |        -         |           ✅            |       -        |
 
 ✅ = Supported, ❌ = Not supported, - = Out of scope
 
@@ -591,22 +621,34 @@ The following commands are similar:
     knip --include exports,types
     knip --exports  # Adds unused exports/types in namespaces and unused enum/class members
 
+## Projects using Knip
+
+Many thanks to some of the early adopters of Knip:
+
+- [Block Protocol][22]
+- [DeepmergeTS][23]
+- [eslint-plugin-functional][24]
+- [freeCodeCamp.org][25]
+- [is-immutable-type][26]
+- [release-it][27]
+- [Template TypeScript Node Package][28]
+
 ## Knip?!
 
 Knip is Dutch for a "cut". A Dutch expression is "to be ge**knip**t for something", which means to be perfectly suited
 for the job. I'm motivated to make knip perfectly suited for the job of cutting projects to perfection! ✂️
 
-[1]: #workspaces--monorepos
+[1]: #workspaces-monorepos
 [2]: #plugins
 [3]: #compilers
 [4]: #reporters
 [5]: #custom-reporters
 [6]: https://labs.openai.com/s/xZQACaLepaKya0PRUPtIN5dC
 [7]: ./assets/cow-with-orange-scissors-van-gogh-style.webp
-[8]: https://github.com/webpro/knip/issues/73
+[8]: ./docs/release-notes-v2.md
 [9]: #faq
 [10]: #ignore
-[11]: #config
+[11]: https://nx.dev/concepts/integrated-vs-package-based
 [12]: ./docs/writing-a-plugin.md
 [13]: ./docs/compilers.md
 [14]: ./docs/custom-reporters.md
@@ -617,6 +659,13 @@ for the job. I'm motivated to make knip perfectly suited for the job of cutting
 [19]: https://github.com/pzavolinsky/ts-unused-exports
 [20]: https://github.com/nadeesha/ts-prune
 [21]: #production-mode
+[22]: https://github.com/blockprotocol/blockprotocol
+[23]: https://github.com/RebeccaStevens/deepmerge-ts
+[24]: https://github.com/eslint-functional/eslint-plugin-functional
+[25]: https://github.com/freeCodeCamp/freeCodeCamp
+[26]: https://github.com/RebeccaStevens/is-immutable-type
+[27]: https://github.com/release-it/release-it
+[28]: https://github.com/JoshuaKGoldberg/template-typescript-node-package
 [plugin-ava]: ./src/plugins/ava
 [plugin-babel]: ./src/plugins/babel
 [plugin-capacitor]: ./src/plugins/capacitor
@@ -650,6 +699,7 @@ for the job. I'm motivated to make knip perfectly suited for the job of cutting
 [plugin-storybook]: ./src/plugins/storybook
 [plugin-stryker]: ./src/plugins/stryker
 [plugin-svelte]: ./src/plugins/svelte
+[plugin-tailwind]: ./src/plugins/tailwind
 [plugin-typedoc]: ./src/plugins/typedoc
 [plugin-typescript]: ./src/plugins/typescript
 [plugin-vitest]: ./src/plugins/vitest

package/dist/binaries/resolvers/fallback.js

@@ -1,6 +1,7 @@
 import parseArgs from 'minimist';
-import { tryResolveFilePaths } from './node.js';
-const argResolvers = {
+import { compact } from '../../util/array.js';
+import { tryResolveFilePaths } from './util.js';
+const argFilters = {
     'babel-node': parsed => [parsed._[0], parsed.require].flat(),
     'ts-node': parsed => [parsed._[0], parsed.require].flat(),
     tsx: parsed => parsed._.filter(p => p !== 'watch'),
@@ -8,7 +9,7 @@ const argResolvers = {
 };
 export const resolve = (binary, args, { cwd }) => {
     const parsed = parseArgs(args, { string: ['r'], alias: { require: ['r', 'loader'] } });
-    const resolver = argResolvers[binary] ?? argResolvers.default;
-    const resolve = resolver(parsed);
-    return [binary, ...tryResolveFilePaths(cwd, resolve)];
+    const argFilter = argFilters[binary] ?? argFilters.default;
+    const filteredArgs = compact(argFilter(parsed));
+    return [binary, ...tryResolveFilePaths(cwd, filteredArgs)];
 };

package/dist/binaries/resolvers/index.d.ts

@@ -1,4 +1,5 @@
 export * as node from './node.js';
 export * as npx from './npx.js';
 export * as pnpm from './pnpm.js';
+export * as rollup from './rollup.js';
 export * as yarn from './yarn.js';

package/dist/binaries/resolvers/index.js

@@ -1,4 +1,5 @@
 export * as node from './node.js';
 export * as npx from './npx.js';
 export * as pnpm from './pnpm.js';
+export * as rollup from './rollup.js';
 export * as yarn from './yarn.js';

package/dist/binaries/resolvers/node.d.ts

@@ -1,3 +1,2 @@
 import type { Resolver } from '../types.js';
-export declare const tryResolveFilePaths: (cwd: string, specifiers: string[]) => string[];
 export declare const resolve: Resolver;

package/dist/binaries/resolvers/node.js

@@ -1,19 +1,5 @@
 import parseArgs from 'minimist';
-import { isInNodeModules, join } from '../../util/path.js';
-import { _tryResolve } from '../../util/require.js';
-const tryResolveFilePath = (cwd, specifier, fallback) => {
-    if (specifier) {
-        const filePath = join(cwd, specifier);
-        if (!isInNodeModules(filePath)) {
-            const resolvedFilePath = _tryResolve(filePath, cwd);
-            if (resolvedFilePath)
-                return [resolvedFilePath];
-        }
-        return fallback ? [fallback] : [];
-    }
-    return [];
-};
-export const tryResolveFilePaths = (cwd, specifiers) => specifiers.flatMap(specifier => tryResolveFilePath(cwd, specifier, specifier));
+import { tryResolveFilePath, tryResolveFilePaths } from './util.js';
 export const resolve = (binary, args, { cwd }) => {
     const parsed = parseArgs(args, { string: ['r'], alias: { require: ['r', 'loader', 'experimental-loader'] } });
     return [...tryResolveFilePath(cwd, parsed._[0]), ...tryResolveFilePaths(cwd, [parsed.require].flat())];

package/dist/binaries/resolvers/rollup.js

@@ -0,0 +1,10 @@
+import parseArgs from 'minimist';
+import { tryResolveFilePaths } from './util.js';
+export const resolve = (binary, args, { cwd, fromArgs }) => {
+    const safeArgs = args.filter(arg => arg !== '--watch');
+    const parsed = parseArgs(safeArgs, { alias: { plugin: 'p' } });
+    const watchers = parsed.watch ? fromArgs(Object.values(parsed.watch)) : [];
+    const plugins = parsed.plugin ? tryResolveFilePaths(cwd, [parsed.plugin].flat()) : [];
+    const configPlugins = parsed.configPlugin ? tryResolveFilePaths(cwd, [parsed.configPlugin].flat()) : [];
+    return [binary, ...watchers, ...plugins, ...configPlugins];
+};

package/dist/binaries/resolvers/util.d.ts

@@ -0,0 +1,2 @@
+export declare const tryResolveFilePath: (cwd: string, specifier: string, fallback?: string) => string[];
+export declare const tryResolveFilePaths: (cwd: string, specifiers: string[]) => string[];

package/dist/binaries/resolvers/util.js

@@ -0,0 +1,15 @@
+import { isInNodeModules, join } from '../../util/path.js';
+import { _tryResolve } from '../../util/require.js';
+export const tryResolveFilePath = (cwd, specifier, fallback) => {
+    if (specifier) {
+        const filePath = join(cwd, specifier);
+        if (!isInNodeModules(filePath)) {
+            const resolvedFilePath = _tryResolve(filePath, cwd);
+            if (resolvedFilePath)
+                return [resolvedFilePath];
+        }
+        return fallback ? [fallback] : [];
+    }
+    return [];
+};
+export const tryResolveFilePaths = (cwd, specifiers) => specifiers.flatMap(specifier => tryResolveFilePath(cwd, specifier, specifier));

package/dist/configuration-chief.js

@@ -11,10 +11,11 @@ import { findFile, loadJSON } from './util/fs.js';
 import { getIncludedIssueTypes } from './util/get-included-issue-types.js';
 import { _dirGlob } from './util/glob.js';
 import { _load } from './util/loader.js';
-import { join, relative } from './util/path.js';
+import { join, relative, toPosix } from './util/path.js';
 import { toCamelCase } from './util/plugin.js';
 import { byPathDepth } from './util/workspace.js';
 const { config: rawConfigArg, workspace: rawWorkspaceArg, include = [], exclude = [], dependencies = false, exports = false, } = parsedArgs.values;
+const workspaceArg = rawWorkspaceArg ? toPosix(rawWorkspaceArg).replace(/^\.\//, '').replace(/\/$/, '') : undefined;
 const getDefaultWorkspaceConfig = (extensions) => {
     const exts = [...DEFAULT_EXTENSIONS, ...(extensions ?? [])].map(ext => ext.slice(1)).join(',');
     return {
@@ -180,7 +181,6 @@ export class ConfigurationChief {
     }
     getEnabledWorkspaces() {
         const allWorkspaces = this.getAllWorkspaces();
-        const workspace = (rawWorkspaceArg ?? '').replace(/\/$/, '');
         const getAncestors = (name) => (ancestors, ancestorName) => {
             if (name === ancestorName)
                 return ancestors;
@@ -188,9 +188,7 @@ export class ConfigurationChief {
                 ancestors.push(ancestorName);
             return ancestors;
         };
-        const workspaces = rawWorkspaceArg
-            ? [workspace, ...allWorkspaces.reduce(getAncestors(workspace), [])]
-            : allWorkspaces;
+        const workspaces = workspaceArg ? [workspaceArg] : allWorkspaces;
         return workspaces.sort(byPathDepth).map((name) => ({
             name,
             pkgName: this.manifestWorkspaces.get(name) ?? this.manifest?.name,