knip 2.19.3 → 2.19.5

package/README.md

@@ -32,20 +32,57 @@ Knip shines in both small and large projects. It's a fresh take on keeping your
 [![An orange cow with scissors, Van Gogh style][7]][6] <sup>_“An orange cow with scissors, Van Gogh style” - generated
 with OpenAI_</sup>
 
-## Installation
+📡 For updates, watch this repository or follow [@webprolific (Twitter)][8] or [@webpro (fosstodon.org)][9].
+
+## Contents
+
+- [Getting Started][10]
+  - [Installation][11]
+  - [Default Configuration][12]
+  - [Let's Go!][13]
+- [Configuration][14]
+  - [Entry Files][15]
+  - [Workspaces][1]
+  - [Plugins][2]
+  - [Compilers][3]
+  - [Ignore files, binaries, dependencies and workspaces][16]
+  - [Public exports][17]
+  - [Ignore exports used in file][18]
+  - [Include exports in entry files][19]
+  - [Paths][20]
+- [Production Mode][21]
+  - [Strict][22]
+  - [Plugins][23]
+- [Output][24]
+  - [Screenshots][25]
+  - [Reading the report][26]
+  - [Rules & Filters][27]
+  - [Reporters][4]
+- [Fixing Issues][28]
+- [Command Line Options][29]
+- [Potential boost with `--no-gitignore`][30]
+- [Comparison & Migration][31]
+  - [depcheck][32]
+  - [unimported][33]
+  - [ts-unused-exports][34]
+  - [ts-prune][35]
+- [Projects using Knip][36]
+- [Articles, etc.][37]
+- [Why "Knip"?][38]
+- [Really, another unused file/dependency/export finder?][39]
+- [Contributors][40]
+
+## Getting Started
+
+### Installation
 
     npm install -D knip
 
 Knip supports LTS versions of Node.js, and currently requires at least Node.js v16.17 or v18.6.
 
-## Experimental: knowledge base
+### Default Configuration
 
-You might want to ask your questions in the [Knip knowledge base][8] (powered by OpenAI and [7-docs][9]). This is an
-experimental knowledge base, answers may be incorrect.
-
-## Configuration
-
-Knip has good defaults and you can run it without any configuration. Here's the default:
+Knip has good defaults and you can run it without any configuration. The (simplified) default config:
 
 ```json
 {
@@ -54,37 +91,7 @@ Knip has good defaults and you can run it without any configuration. Here's the
 }
 ```
 
-In addition to `index.js`, the following file names and extensions are also considered entry files:
-
-- `index`, `main` and `cli`
-- `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts` and `tsx`
-
-This means files like `main.cjs` and `src/cli.ts` are automatically added as entry files.
-
-### Entry Files
-
-Knip looks for entry files at those default locations, but also in other places:
-
-- The `main`, `bin` and `exports` fields of `package.json`.
-- [Plugins][2] such as for Next.js, Remix, Gatsby or Svelte add entry files.
-- The `scripts` in package.json or other scripts may provide entry files.
-
-Knip does this for each [workspace][1] it finds, trying to minimize the configuration to suit your project. In a
-perfectly boring world where everything is according to defaults you wouldn't even need a `knip.json` file at all.
-
-Larger projects tend to have more things customized, and therefore probably get more out of Knip with a configuration
-file. Let's say you are using `.ts` files exclusively and have all source files only in the `src` directory:
-
-```json
-{
-  "$schema": "https://unpkg.com/knip@2/schema.json",
-  "entry": ["src/index.ts"],
-  "project": ["src/**/*.ts"]
-}
-```
-
-The `entry` files target the starting point(s) to resolve the rest of the imported code. The `project` files should
-contain all files to match against the files resolved from the entry files, including potentially unused files.
+There's more, jump to [Entry Files][15] for details.
 
 Places where Knip looks for configuration (ordered by priority):
 
@@ -96,7 +103,7 @@ Places where Knip looks for configuration (ordered by priority):
 - `knip.js`
 - `package.json#knip`
 
-So you can use a dynamic `knip.ts` with TypeScript if you prefer:
+You can use a dynamic `knip.ts` with TypeScript if you prefer:
 
 ```ts
 import type { KnipConfig } from 'knip';
@@ -109,191 +116,59 @@ const config: KnipConfig = {
 export default config;
 ```
 
-Then run the checks with `npx knip`. Or first add this script to `package.json`:
-
-```json
-{
-  "scripts": {
-    "knip": "knip"
-  }
-}
-```
-
-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][1] for more details about configuring them.
-
-## Command-line options
-
-    $ npx knip --help
-    ✂️  Find unused files, dependencies and exports in your JavaScript and TypeScript projects
-
-    Usage: knip [options]
-
-    Options:
-      -c, --config [file]      Configuration file path (default: [.]knip.json[c], knip.js, knip.ts or package.json#knip)
-      -t, --tsConfig [file]    TypeScript configuration path (default: tsconfig.json)
-      --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 [dir]        Analyze a single workspace (default: analyze all configured workspaces)
-      --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,unresolved
-      --exports                Shortcut for --include exports,nsExports,classMembers,types,nsTypes,enumMembers,duplicates
-      --include-entry-exports  Include entry files when reporting unused exports
-      -n, --no-progress        Don't show dynamic progress updates (automatically enabled in CI environments)
-      --reporter               Select reporter: symbols, compact, codeowners, json (default: symbols)
-      --reporter-options       Pass extra options to the reporter (as JSON string, see example)
-      --no-config-hints        Suppress configuration hints
-      --no-exit-code           Always exit with code zero (0)
-      --max-issues             Maximum number of issues before non-zero exit code (default: 0)
-      -d, --debug              Show debug output
-      --debug-file-filter      Filter for files in debug output (regex as string)
-      --performance            Measure count and running time of expensive functions and display stats table
-      -h, --help               Print this help text
-      -V, --version            Print version
-
-    (1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, classMembers, types, nsTypes, enumMembers, duplicates
-
-    Examples:
-
-    $ knip
-    $ knip --production
-    $ knip --workspace packages/client --include files,dependencies
-    $ knip -c ./config/knip.json --reporter compact
-    $ knip --reporter codeowners --reporter-options '{"path":".github/CODEOWNERS"}'
-    $ knip --debug --debug-file-filter '(specific|particular)-module'
-
-    More documentation and bug reports: https://github.com/webpro/knip
-
-## Screenshots
-
-Here's an example run using the default reporter:
-
-<img src="./assets/screenshot-exports.png" alt="example output of exported values and types" width="578">
-
-This example shows more output related to unused and unlisted dependencies:
-
-<img src="./assets/screenshot-dependencies.png" alt="example output of dependencies" width="578">
+Use `--config path/to/knip.json` to use a different location.
 
-## Reading the report
+### Let's Go!
 
-The report contains the following types of issues:
-
-| Key               | Title                               | Description                                           |
-| :---------------- | :---------------------------------- | :---------------------------------------------------- |
-| `files`           | Unused files                        | unable to find references to this file                |
-| `dependencies`    | Unused dependencies                 | unable to find references to this dependency          |
-| `devDependencies` | Unused devDependencies              | unable to find references to this devDependency       |
-| `unlisted`        | Unlisted dependencies               | used dependencies not listed in package.json          |
-| `binaries`        | Unlisted binaries                   | binaries from dependencies not in package.json        |
-| `unresolved`      | Unresolved imports                  | unable to resolve this (import) specifier             |
-| `exports`         | Unused exports                      | unable to find references to this export              |
-| `nsExports`       | Unused exports in namespaces        | unable to find direct references to this export _(1)_ |
-| `types`           | Unused exported types               | unable to find references to this exported type       |
-| `nsTypes`         | Unused exported types in namespaces | unable to find direct references to this export _(1)_ |
-| `enumMembers`     | Unused exported enum members        | unable to find references to this enum member         |
-| `classMembers`    | Unused exported class members       | unable to find references to this class member        |
-| `duplicates`      | Duplicate exports                   | the same thing is exported more than once             |
-
-When an issue type has zero issues, it is not shown.
-
-Getting too many reported issues and false positives? Read more about [handling issues][10].
-
-_(1)_ The variable or type is not referenced directly and has become a member of a namespace. Knip can't find a
-reference to it, so you can _probably_ remove it.
-
-## Output
-
-### Rules
-
-Use `rules` in the configuration to customize the issue types that count towards the total error count, or to exclude
-them altogether.
-
-- `error` (default): printed, adds to total error count (similar to the `--include` filter)
-- `warn`: printed in faded/grey color, does not add to error count (i.e. the exit code)
-- `off`: not printed, does not add to error count (similar to the `--exclude` filter)
-
-Example:
+Run the checks with `npx knip`. Or first add this script to `package.json`:
 
 ```json
 {
-  "rules": {
-    "files": "warn",
-    "classMembers": "off",
-    "duplicates": "off"
+  "scripts": {
+    "knip": "knip"
   }
 }
 ```
 
-See [reading the report][11] for the list of issue types.
-
-The rules are modeled after the ESLint `rules` configuration, and could be extended in the future. For instance, to
-apply filters or configurations only to a specific issue type.
-
-### Filters
-
-You can `--include` or `--exclude` any of the reported issue types to slice & dice the report to your needs.
-Alternatively, they can be added to the configuration (e.g. `"exclude": ["dependencies"]`).
-
-Use `--include` to report only specific issue types (the following example commands do the same):
-
-    knip --include files --include dependencies
-    knip --include files,dependencies
+Then 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.
 
-Use `--exclude` to ignore reports you're not interested in:
+See [Command Line Options][29] for an overview of available CLI options.
 
-    knip --include files --exclude classMembers,enumMembers
+## Configuration
 
-Use `--dependencies` or `--exports` as shortcuts to combine groups of related types.
+### Entry Files
 
-See [reading the report][11] for the list of issue types.
+In addition to `index.js`, the following file names and extensions are also considered entry files:
 
-### When to use rules or filters
+- `index`, `main` and `cli`
+- `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts` and `tsx`
 
-Filters are meant to be used as command-line flags, rules allow for more fine-grained configuration.
+This means files like `main.cjs` and `src/cli.ts` are automatically added as entry files. Knip looks for entry files at
+those default locations, but also in other places:
 
-- Rules are more fine-grained since they also have "warn".
-- Rules could be extended in the future.
-- Filters can be set in configuration and from CLI, rules only in configuration.
-- Filters have two groups (`--dependencies` and `--types`), rules don't have any grouping.
+- The `main`, `bin` and `exports` fields of `package.json`.
+- [Plugins][2] such as for Next.js, Remix, Gatsby or Svelte add entry files.
+- The `scripts` in package.json or other scripts may provide entry files.
 
-## Ignore
+Knip does this for each [workspace][1] it finds, trying to minimize the configuration to suit your project. In a
+perfectly boring world where everything is according to defaults you wouldn't even need a `knip.json` file at all.
 
-There are a few ways to tell Knip to ignore certain packages, binaries, dependencies and workspaces. Some examples:
+Larger projects tend to have more things customized, and therefore probably get more out of Knip with a configuration
+file. Let's say you are using `.ts` files exclusively and have all source files only in the `src` directory:
 
 ```json
 {
-  "ignore": ["**/*.d.ts", "**/fixtures"],
-  "ignoreBinaries": ["zip", "docker-compose"],
-  "ignoreDependencies": ["hidden-package"],
-  "ignoreWorkspaces": ["packages/ignore", "packages/examples/**"]
+  "$schema": "https://unpkg.com/knip@2/schema.json",
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"]
 }
 ```
 
-These can also be configured per workspace (except for `ignoreWorkspaces`).
-
-## What's next?
-
-This is the fun part! Knip, knip, knip ✂️
-
-As always, make sure to back up files or use Git before deleting files or making changes. Run tests to verify results.
-
-- Unused files can be removed.
-- Unused dependencies can be removed from `package.json`.
-- Unlisted dependencies should be added to `package.json`.
-- Unresolved imports should be reviewed.
-- Unused exports and types: remove the `export` keyword in front of unused exports. Then you can see whether the
-  variable or type is used within the same file. If this is not the case, it can be removed.
-- Duplicate exports can be removed so they're exported only once.
-
-🔁 Repeat the process to reveal new unused files and exports. Sometimes it's so liberating to remove things!
-
-Getting too many reported issues and false positives? Read more about [handling issues][10].
+The `entry` files target the starting point(s) to resolve the rest of the imported code. The `project` files should
+contain all files to match against the files resolved from the entry files, including potentially unused files.
 
-## Workspaces
+### Workspaces
 
 Workspaces are handled out-of-the-box by Knip. Every workspace is part of the analysis.
 
@@ -321,22 +196,20 @@ Here's an example `knip.json` configuration with some custom `entry` and `projec
 ```
 
 It might be useful to run Knip first with no or little configuration to see where it needs custom `entry` and/or
-`project` files. Each workspace has the same [default configuration][12].
+`project` files. Each workspace has the same [default configuration][14].
 
 The root workspace is named `"."` under `workspaces` (like in the example).
 
 Knip supports workspaces as defined in three possible locations:
 
 - In the `workspaces` array in `package.json` (npm, Yarn, Lerna).
-- In the `workspaces.packages` array in `package.json` (legacy).
 - In the `packages` array in `pnpm-workspace.yaml` (pnpm).
+- In the `workspaces.packages` array in `package.json` (legacy).
 - In the `workspaces` object in Knip configuration.
 
 The `workspaces` in Knip configuration not already defined in the root `package.json` or `pnpm-workspace.yaml` are
 added. Knip requires a `package.json` file in each workspace directory.
 
-The `ignore`, `ignoreBinaries` and `ignoreDependencies` options are available inside workspace configurations.
-
 Here's some example output when running Knip in a workspace:
 
 <img src="./assets/screenshot-workspaces.png" alt="example output in workspaces" width="578">
@@ -345,12 +218,14 @@ Use `--debug` to get more verbose output.
 
 Use `--workspace [dir]` to analyze a single workspace (including its ancestors).
 
-## Plugins
+The `ignore`, `ignoreBinaries` and `ignoreDependencies` options are available inside workspace configurations.
+
+### 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):
+To explain what they do, here's a quick example `.eslintrc.json` configuration file (for ESLint):
 
 ```json
 {
@@ -415,18 +290,18 @@ themselves and/or `entry` files for Knip to analyze.
 
 See each plugin's documentation for its default values.
 
-### `config`
+#### `config`
 
 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`
+#### `entry`
 
 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
+#### Override plugin configuration
 
 Usually, no custom configuration is required for plugins, but if your project uses custom file locations then Knip
 allows you to override any defaults. Let's take Cypress for example. By default it uses `cypress.config.js`, but your
@@ -441,10 +316,10 @@ has them at `e2e-tests/*.spec.ts`. Here's how to configure this:
 }
 ```
 
-### Multi-project repositories
+#### Multi-project repositories
 
 Some repositories have a single `package.json`, but consist of multiple projects with configuration files across the
-repository (such as the [Nx "intregrated repo" style][13]). Let's assume some of these projects are apps and have their
+repository (such as the [Nx "intregrated repo" style][41]). 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
@@ -455,24 +330,24 @@ own Cypress configuration and test files. In that case, we could configure the C
 }
 ```
 
-### Disable a plugin
+#### Disable a plugin
 
 In case a plugin causes issues, it can be disabled by using `false` as its value (e.g. `"webpack": false`).
 
-### Create a new plugin
+#### Create a new plugin
 
-Getting false positives because a plugin is missing? Want to help out? Please read more at [writing a plugin][14]. This
+Getting false positives because a plugin is missing? Want to help out? Please read more at [writing a plugin][42]. This
 guide also contains more details if you want to learn more about plugins and why they are useful.
 
-## Compilers
+### Compilers
 
-Knip v2 introduces compilers that allow to include files that are not JavaScript or TypeScript in the process of finding
-unused or missing dependencies. For instance, `.mdx`, `.vue` and `.svelte` files come to mind.
+Compilers allow to include files that are not JavaScript or TypeScript in the process of finding unused or missing
+dependencies (e.g. `.mdx`, `.vue` and `.svelte` files).
 
-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. Here is an example that compiles `.mdx` files to JavaScript so these files
-and their imports and exports become part of the analysis:
+This requires using a dynamic `knip.js` or `knip.ts` configuration file. 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. Here is an example that compiles `.mdx` files to JavaScript so
+these files and their imports and exports become part of the analysis:
 
 ```js
 import { compileSync } from 'mdx-js/mdx';
@@ -484,7 +359,95 @@ export default {
 };
 ```
 
-Read [Compilers][15] for more details and examples.
+Read [Compilers][43] for more details and examples.
+
+### Ignore files, binaries, dependencies and workspaces
+
+There are a few ways to tell Knip to ignore certain files, binaries, dependencies and workspaces. Some examples:
+
+```json
+{
+  "ignore": ["**/*.d.ts", "**/fixtures"],
+  "ignoreBinaries": ["zip", "docker-compose"],
+  "ignoreDependencies": ["hidden-package"],
+  "ignoreWorkspaces": ["packages/ignore", "packages/examples/**"]
+}
+```
+
+These can also be configured per workspace (except for `ignoreWorkspaces`).
+
+### Public exports
+
+Sometimes a file that's not an entry file has one or more exports that are public and should not be reported as unused.
+Such variables and types can be marked with the JSDoc `@public` tag:
+
+```js
+/**
+ * Merge two objects.
+ *
+ * @public
+ */
+
+export const merge = function () {};
+
+/** @public */
+export const split = function () {};
+```
+
+Knip does not report public exports and types as unused.
+
+### Ignore exports used in file
+
+In files with multiple exports, some of them might be used only internally. If these exports should not be reported,
+there is a `ignoreExportsUsedInFile` option available. With this option enabled, you don't need to mark everything
+`@public` separately and when something is no longer used internally, it will still be reported.
+
+```json
+{
+  "ignoreExportsUsedInFile": true
+}
+```
+
+In a more fine-grained manner, you can also ignore only specific issue types:
+
+```json
+{
+  "ignoreExportsUsedInFile": {
+    "interface": true,
+    "type": true
+  }
+}
+```
+
+### Include exports in entry files
+
+When a repository is self-contained or private, you may want to include entry files when reporting unused exports:
+
+    knip --include-entry-exports
+
+Knip will also report unused exports in entry source files and scripts (such as those referenced in `package.json`). But
+not in entry and configuration files from plugins, such as `next.config.js` or `src/routes/+page.svelte`.
+
+### Paths
+
+Tools like TypeScript, Webpack and Babel support import aliases in various ways. Knip automatically includes
+`compilerOptions.paths` from the TypeScript configuration, but does not (yet) automatically find other types of import
+aliases. They can be configured manually:
+
+```json
+{
+  "$schema": "https://unpkg.com/knip@2/schema.json",
+  "paths": {
+    "@lib": ["./lib/index.ts"],
+    "@lib/*": ["./lib/*"]
+  }
+}
+```
+
+Each workspace can also have its own `paths` configured. Knip `paths` follow the TypeScript semantics:
+
+- Path values are an array of relative paths.
+- Paths without an `*` are exact matches.
 
 ## Production Mode
 
@@ -521,110 +484,192 @@ Additionally, the `--strict` flag can be used to:
 ### Plugins
 
 Plugins also have this distinction. For instance, Next.js entry files for pages (`pages/**/*.tsx`) and Remix routes
-(`app/routes/**/*.tsx`) are production code, while Jest and Storybook entry files (e.g. `*.spec.ts` or `*.stories.js`)
-are not. All of this is handled automatically by Knip and its plugins.
+(`app/routes/**/*.tsx`) represent production code, while Jest and Storybook entry files (e.g. `*.spec.ts` or
+`*.stories.js`) do not. All of this is handled automatically by Knip and its plugins.
 
-## Paths
+## Output
 
-Tools like TypeScript, Webpack and Babel support import aliases in various ways. Knip automatically includes
-`compilerOptions.paths` from the TypeScript configuration, but does not (yet) automatically find other types of import
-aliases. They can be configured manually:
+### Screenshots
+
+Here's an example run using the default reporter:
+
+<img src="./assets/screenshot-exports.png" alt="example output of exported values and types" width="578">
+
+This example shows more output related to unused and unlisted dependencies:
+
+<img src="./assets/screenshot-dependencies.png" alt="example output of dependencies" width="578">
+
+### Reading the report
+
+The report contains the following types of issues:
+
+| Title                               | Description                                     | Key            |
+| :---------------------------------- | :---------------------------------------------- | :------------- |
+| Unused files                        | unable to find references to this file          | `files`        |
+| Unused dependencies                 | unable to find references to this dependency    | `dependencies` |
+| Unused devDependencies              | unable to find references to this devDependency | `dependencies` |
+| Unlisted dependencies               | used dependencies not listed in package.json    | `unlisted`     |
+| Unlisted binaries                   | binaries from deps not listed in package.json   | `binaries`     |
+| Unresolved imports                  | unable to resolve this (import) specifier       | `unresolved`   |
+| Unused exports                      | unable to find references to this export        | `exports`      |
+| Unused exports in namespaces        | unable to find direct references to this export | `nsExports`    |
+| Unused exported types               | unable to find references to this exported type | `types`        |
+| Unused exported types in namespaces | unable to find direct references to this export | `nsTypes`      |
+| Unused exported enum members        | unable to find references to this enum member   | `enumMembers`  |
+| Unused exported class members       | unable to find references to this class member  | `classMembers` |
+| Duplicate exports                   | the same thing is exported more than once       | `duplicates`   |
+
+When an issue type has zero issues, it is not shown.
+
+Getting too many reported issues and false positives? Read more about [handling issues][44].
+
+### Rules & Filters
+
+Use rules or filters if you don't (yet) want all issue types Knip reports.
+
+#### Rules
+
+Use `rules` in the configuration to customize the issue types that count towards the total error count, or to exclude
+them altogether.
+
+- `error` (default): printed, adds to total error count (similar to the `--include` filter)
+- `warn`: printed in faded/grey color, does not add to error count (i.e. the exit code)
+- `off`: not printed, does not add to error count (similar to the `--exclude` filter)
+
+Example:
 
 ```json
 {
-  "$schema": "https://unpkg.com/knip@2/schema.json",
-  "paths": {
-    "@lib": ["./lib/index.ts"],
-    "@lib/*": ["./lib/*"]
+  "rules": {
+    "files": "warn",
+    "classMembers": "off",
+    "duplicates": "off"
   }
 }
 ```
 
-Each workspace can also have its own `paths` configured. Note that Knip `paths` follow the TypeScript semantics:
+See [reading the report][26] for the list of issue types.
 
-- Path values are an array of relative paths.
-- Paths without an `*` are exact matches.
+The rules are modeled after the ESLint `rules` configuration, and could be extended in the future. For instance, to
+apply filters or configurations only to a specific issue type.
+
+#### Filters
+
+You can `--include` or `--exclude` any of the reported issue types to slice & dice the report to your needs.
+Alternatively, they can be added to the configuration (e.g. `"exclude": ["dependencies"]`).
+
+Use `--include` to report only specific issue types (the following example commands do the same):
 
-## Reporters
+    knip --include files --include dependencies
+    knip --include files,dependencies
+
+Use `--exclude` to ignore reports you're not interested in:
+
+    knip --include files --exclude classMembers,enumMembers
+
+Use `--dependencies` or `--exports` as shortcuts to combine groups of related types.
+
+See [reading the report][26] for the list of issue types.
+
+#### When to use rules or filters
+
+Filters are meant to be used as command-line flags, rules allow for more fine-grained configuration.
+
+- Rules are more fine-grained since they also have "warn".
+- Rules could be extended in the future.
+- Filters can be set in configuration and from CLI, rules only in configuration.
+- Filters have two groups (`--dependencies` and `--exports`), rules don't have any grouping.
+
+### Reporters
 
 Knip provides the following built-in reporters:
 
 - codeowners
 - compact
 - json
-- symbol
+- symbol (default)
 
-### Custom Reporters
+#### Custom Reporters
 
 When the provided built-in reporters are not sufficient, a custom reporter can be implemented.
 
-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.
+Pass something like `--reporter ./my-reporter` from the command line. The results are passed to the function from its
+default export and can 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][16].
+Find more details and ideas in [custom reporters][45].
 
-## Public exports
-
-Sometimes a file that's not an entry file has one or more exports that are public and should not be reported as unused.
-Such variables and types can be marked with the JSDoc `@public` tag:
+## Fixing Issues
 
-```js
-/**
- * Merge two objects.
- *
- * @public
- */
+This is the fun part! Knip, knip, knip ✂️
 
-export const merge = function () {};
+Tip: back up files or use an VCS like Git before deleting files or making changes. Run tests to verify results.
 
-/** @public */
-export const split = function () {};
-```
+- Unused files can be removed.
+- Unused dependencies can be removed from `package.json`.
+- Unlisted dependencies should be added to `package.json`.
+- Unresolved imports should be reviewed.
+- Unused exports and types: remove the `export` keyword in front of unused exports. Then you can see whether the
+  variable or type is used within the same file. If this is not the case, it can be removed.
+- Duplicate exports can be removed so they're exported only once.
 
-Knip does not report public exports and types as unused.
+Repeat the process to reveal new unused files and exports. It's so liberating to remove unused things!
 
-## Ignore exports used in file
+Getting too many reported issues and false positives? Read more about [handling issues][46] describing potential causes
+for false positives, and how to handle them.
 
-In files with multiple exports, some of them might be used only internally. If these exports should not be reported,
-there is a `ignoreExportsUsedInFile` option available. With this option enabled, you don't need to mark everything
-`@public` separately and when something is no longer used internally, it will still be reported.
+## Command Line Options
 
-```json
-{
-  "ignoreExportsUsedInFile": true
-}
-```
+    $ npx knip --help
+    ✂️  Find unused files, dependencies and exports in your JavaScript and TypeScript projects
 
-In a more fine-grained manner, you can also ignore only specific issue types:
+    Usage: knip [options]
 
-```json
-{
-  "ignoreExportsUsedInFile": {
-    "interface": true,
-    "type": true
-  }
-}
-```
+    Options:
+      -c, --config [file]      Configuration file path (default: [.]knip.json[c], knip.js, knip.ts or package.json#knip)
+      -t, --tsConfig [file]    TypeScript configuration path (default: tsconfig.json)
+      --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 [dir]        Analyze a single workspace (default: analyze all configured workspaces)
+      --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,unresolved
+      --exports                Shortcut for --include exports,nsExports,classMembers,types,nsTypes,enumMembers,duplicates
+      --include-entry-exports  Include entry files when reporting unused exports
+      -n, --no-progress        Don't show dynamic progress updates (automatically enabled in CI environments)
+      --reporter               Select reporter: symbols, compact, codeowners, json (default: symbols)
+      --reporter-options       Pass extra options to the reporter (as JSON string, see example)
+      --no-config-hints        Suppress configuration hints
+      --no-exit-code           Always exit with code zero (0)
+      --max-issues             Maximum number of issues before non-zero exit code (default: 0)
+      -d, --debug              Show debug output
+      --debug-file-filter      Filter for files in debug output (regex as string)
+      --performance            Measure count and running time of expensive functions and display stats table
+      -h, --help               Print this help text
+      -V, --version            Print version
 
-## Include exports in entry files
+    (1) Issue types: files, dependencies, unlisted, unresolved, exports, nsExports, classMembers, types, nsTypes, enumMembers, duplicates
 
-When a repository is self-contained or private, you may want to include entry files when reporting unused exports:
+    Examples:
 
-    knip --include-entry-exports
+    $ knip
+    $ knip --production
+    $ knip --workspace packages/client --include files,dependencies
+    $ knip -c ./config/knip.json --reporter compact
+    $ knip --reporter codeowners --reporter-options '{"path":".github/CODEOWNERS"}'
+    $ knip --debug --debug-file-filter '(specific|particular)-module'
 
-Knip will also report unused exports in entry source files and scripts (such as those referenced in `package.json`). But
-not in entry and configuration files from plugins, such as `next.config.js` or `src/routes/+page.svelte`.
+    More documentation and bug reports: https://github.com/webpro/knip
 
-## Handling Issues
+## Potential boost with `--no-gitignore`
 
-How to handle a long list of reported issues? Seeing too many false positives? Read more about [handling issues][17]
-describing potential causes for false positives, and how to handle them.
+To increase performance in a large monorepo, check out [Potential boost with `--no-gitignore`][47].
 
-## Comparison
+## Comparison & Migration
 
 This table is an ongoing comparison. Based on their docs (please report any mistakes):
 
-| Feature                 | **knip** | [depcheck][18] | [unimported][19] | [ts-unused-exports][20] | [ts-prune][21] |
+| Feature                 | **knip** | [depcheck][48] | [unimported][49] | [ts-unused-exports][50] | [ts-prune][51] |
 | :---------------------- | :------: | :------------: | :--------------: | :---------------------: | :------------: |
 | Unused files            |    ✅    |       -        |        ✅        |            -            |       -        |
 | Unused dependencies     |    ✅    |       ✅       |        ✅        |            -            |       -        |
@@ -644,7 +689,7 @@ This table is an ongoing comparison. Based on their docs (please report any mist
 
 ✅ = Supported, ❌ = Not supported, - = Out of scope
 
-### Migrating from other tools
+Below some similar commands to get another idea of what Knip does in comparison:
 
 ### depcheck
 
@@ -660,7 +705,7 @@ The following commands are similar:
     unimported
     knip --production --dependencies --include files
 
-Also see [production mode][22].
+Also see [production mode][21].
 
 ### ts-unused-exports
 
@@ -682,37 +727,25 @@ The following commands are similar:
 
 Many thanks to some of the early adopters of Knip:
 
-- [Block Protocol][23]
-- [DeepmergeTS][24]
-- [eslint-plugin-functional][25]
-- [freeCodeCamp.org][26]
-- [is-immutable-type][27]
-- [IsaacScript][28]
-- [Owncast][29]
-- [release-it][30]
-- [Template TypeScript Node Package][31]
-
-## Potential boost with `--no-gitignore`
-
-Running Knip on large workspaces with many packages may feel a bit sluggish. Knip looks up `.gitignore` files and uses
-them to filter out matching entry and project files. This increases correctness. However, you might want to disable that
-with `--no-gitignore` and enjoy a significant performance boost. Depending on the contents of the `.gitignore` files,
-the reported issues may be the same. To help determine whether this trade-off might be worth it for you, first check the
-difference in unused files:
-
-```shell
-diff <(knip --no-gitignore --include files) <(knip --include files)
-```
-
-And to measure the difference of this flag in seconds:
+- [Block Protocol][52]
+- [DeepmergeTS][53]
+- [eslint-plugin-functional][54]
+- [freeCodeCamp.org][55]
+- [is-immutable-type][56]
+- [IsaacScript][57]
+- [Nuxt][58]
+- [Owncast][59]
+- [release-it][60]
+- [Template TypeScript Node Package][61]
+- [Tipi][62]
 
-```shell
-SECONDS=0; knip > /dev/null; t1=$SECONDS; SECONDS=0; knip --no-gitignore > /dev/null; t2=$SECONDS; echo "Difference: $((t1 - t2)) seconds"
-```
+## Articles, etc.
 
-⏲️ Analysis on a large project went from 33 down to 9 seconds (that's >70% faster).
+- Ask your questions in the [Knip knowledge base][63] (powered by OpenAI and [7-docs][64], experimental!)
+- Smashing Magazine: [Knip: An Automated Tool For Finding Unused Files, Exports, And Dependencies][65]
+- Effective TypeScript: [Recommendation Update: ✂️ Use knip to detect dead code and types][66]
 
-## Knip
+## Why "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! ✂️
@@ -728,7 +761,7 @@ each file, and traversing all of this, why not collect the various issues in one
 
 Special thanks to the wonderful people who have contributed to this project:
 
-[![Contributors][33]][32]
+[![Contributors][68]][67]
 
 [1]: #workspaces
 [2]: #plugins
@@ -737,32 +770,67 @@ Special thanks to the wonderful people who have contributed to this project:
 [5]: #custom-reporters
 [6]: https://labs.openai.com/s/xZQACaLepaKya0PRUPtIN5dC
 [7]: ./assets/cow-with-orange-scissors-van-gogh-style.webp
-[8]: https://knip.deno.dev
-[9]: https://github.com/7-docs/7-docs
-[10]: #handling-issues
-[11]: #reading-the-report
-[12]: #configuration
-[13]: https://nx.dev/concepts/integrated-vs-package-based
-[14]: ./docs/writing-a-plugin.md
-[15]: ./docs/compilers.md
-[16]: ./docs/custom-reporters.md
-[17]: ./docs/handling-issues.md
-[18]: https://github.com/depcheck/depcheck
-[19]: https://github.com/smeijer/unimported
-[20]: https://github.com/pzavolinsky/ts-unused-exports
-[21]: https://github.com/nadeesha/ts-prune
-[22]: #production-mode
-[23]: https://github.com/blockprotocol/blockprotocol
-[24]: https://github.com/RebeccaStevens/deepmerge-ts
-[25]: https://github.com/eslint-functional/eslint-plugin-functional
-[26]: https://github.com/freeCodeCamp/freeCodeCamp
-[27]: https://github.com/RebeccaStevens/is-immutable-type
-[28]: https://github.com/IsaacScript/isaacscript
-[29]: https://github.com/owncast/owncast
-[30]: https://github.com/release-it/release-it
-[31]: https://github.com/JoshuaKGoldberg/template-typescript-node-package
-[32]: https://github.com/webpro/knip/graphs/contributors
-[33]: https://contrib.rocks/image?repo=webpro/knip
+[8]: https://twitter.com/webprolific
+[9]: https://fosstodon.org/@webpro
+[10]: #getting-started
+[11]: #installation
+[12]: #default-configuration
+[13]: #lets-go
+[14]: #configuration
+[15]: #entry-files
+[16]: #ignore-files-binaries-dependencies-and-workspaces
+[17]: #public-exports
+[18]: #ignore-exports-used-in-file
+[19]: #include-exports-in-entry-files
+[20]: #paths
+[21]: #production-mode
+[22]: #strict
+[23]: #plugins-1
+[24]: #output
+[25]: #screenshots
+[26]: #reading-the-report
+[27]: #rules--filters
+[28]: #fixing-issues
+[29]: #command-line-options
+[30]: #potential-boost-with---no-gitignore
+[31]: #comparison--migration
+[32]: #depcheck
+[33]: #unimported
+[34]: #ts-unused-exports
+[35]: #ts-prune
+[36]: #projects-using-knip
+[37]: #articles-etc
+[38]: #why-knip
+[39]: #really-another-unused-filedependencyexport-finder
+[40]: #contributors
+[41]: https://nx.dev/concepts/integrated-vs-package-based
+[42]: ./docs/writing-a-plugin.md
+[43]: ./docs/compilers.md
+[44]: #handling-issues
+[45]: ./docs/custom-reporters.md
+[46]: ./docs/handling-issues.md
+[47]: ./docs/perf-boost-with-no-gitignore.md
+[48]: https://github.com/depcheck/depcheck
+[49]: https://github.com/smeijer/unimported
+[50]: https://github.com/pzavolinsky/ts-unused-exports
+[51]: https://github.com/nadeesha/ts-prune
+[52]: https://github.com/blockprotocol/blockprotocol
+[53]: https://github.com/RebeccaStevens/deepmerge-ts
+[54]: https://github.com/eslint-functional/eslint-plugin-functional
+[55]: https://github.com/freeCodeCamp/freeCodeCamp
+[56]: https://github.com/RebeccaStevens/is-immutable-type
+[57]: https://github.com/IsaacScript/isaacscript
+[58]: https://github.com/nuxt/nuxt
+[59]: https://github.com/owncast/owncast
+[60]: https://github.com/release-it/release-it
+[61]: https://github.com/JoshuaKGoldberg/template-typescript-node-package
+[62]: https://github.com/meienberger/runtipi
+[63]: https://knip.deno.dev
+[64]: https://github.com/7-docs/7-docs
+[65]: https://www.smashingmagazine.com/2023/08/knip-automated-tool-find-unused-files-exports-dependencies/
+[66]: https://effectivetypescript.com/2023/07/29/knip/
+[67]: https://github.com/webpro/knip/graphs/contributors
+[68]: https://contrib.rocks/image?repo=webpro/knip
 [plugin-ava]: ./src/plugins/ava
 [plugin-babel]: ./src/plugins/babel
 [plugin-capacitor]: ./src/plugins/capacitor

package/dist/ConfigurationValidator.js

@@ -21,6 +21,17 @@ const issueTypeSchema = z.union([
     z.literal('classMembers'),
 ]);
 const rulesSchema = z.record(issueTypeSchema, z.enum(['error', 'warn', 'off']));
+const ignoreExportsUsedInFileSchema = z.union([
+    z.boolean(),
+    z.record(z.union([
+        z.literal('class'),
+        z.literal('enum'),
+        z.literal('function'),
+        z.literal('interface'),
+        z.literal('member'),
+        z.literal('type'),
+    ]), z.boolean()),
+]);
 const rootConfigurationSchema = z.object({
     rules: rulesSchema.optional(),
     entry: globSchema.optional(),
@@ -28,19 +39,7 @@ const rootConfigurationSchema = z.object({
     paths: pathsSchema.optional(),
     ignore: globSchema.optional(),
     ignoreBinaries: z.array(z.string()).optional(),
-    ignoreExportsUsedInFile: z
-        .union([
-        z.boolean(),
-        z.record(z.union([
-            z.literal('class'),
-            z.literal('enum'),
-            z.literal('function'),
-            z.literal('interface'),
-            z.literal('member'),
-            z.literal('type'),
-        ]), z.boolean()),
-    ])
-        .optional(),
+    ignoreExportsUsedInFile: ignoreExportsUsedInFileSchema.optional(),
     ignoreDependencies: z.array(z.string()).optional(),
     ignoreWorkspaces: z.array(z.string()).optional(),
     compilers: compilersSchema.optional(),

package/dist/ProjectPrincipal.js

@@ -1,3 +1,4 @@
+import { isGitIgnoredSync } from 'globby';
 import ts from 'typescript';
 import { DEFAULT_EXTENSIONS } from './constants.js';
 import { IGNORED_FILE_EXTENSIONS } from './constants.js';
@@ -6,7 +7,7 @@ import { createHosts } from './typescript/createHosts.js';
 import { getImportsAndExports } from './typescript/getImportsAndExports.js';
 import { SourceFileManager } from './typescript/SourceFileManager.js';
 import { isMaybePackageName } from './util/modules.js';
-import { extname, isInNodeModules } from './util/path.js';
+import { extname, isInNodeModules, join } from './util/path.js';
 import { timerify } from './util/Performance.js';
 const baseCompilerOptions = {
     allowJs: true,
@@ -22,6 +23,7 @@ const baseCompilerOptions = {
     moduleResolution: ts.ModuleResolutionKind.NodeNext,
 };
 const tsCreateProgram = timerify(ts.createProgram);
+const isGitIgnored = isGitIgnoredSync();
 export class ProjectPrincipal {
     entryPaths = new Set();
     projectPaths = new Set();
@@ -125,13 +127,17 @@ export class ProjectPrincipal {
                 }
             }
             else {
-                if (isMaybePackageName(specifier)) {
-                    external.add(specifier);
+                const sanitizedSpecifier = specifier.replace(/^([?!|-]+)?([^!?]+).*/, '$2');
+                if (isMaybePackageName(sanitizedSpecifier)) {
+                    external.add(sanitizedSpecifier);
                 }
                 else {
-                    const ext = extname(specifier);
-                    if (!ext || (ext !== '.json' && !IGNORED_FILE_EXTENSIONS.includes(ext))) {
-                        unresolvedImports.add(specifier);
+                    const isIgnored = isGitIgnored(join(filePath, sanitizedSpecifier));
+                    if (!isIgnored) {
+                        const ext = extname(sanitizedSpecifier);
+                        if (!ext || (ext !== '.json' && !IGNORED_FILE_EXTENSIONS.includes(ext))) {
+                            unresolvedImports.add(specifier);
+                        }
                     }
                 }
             }

package/dist/plugins/commitizen/index.js

@@ -3,7 +3,7 @@ import { hasDependency, load } from '../../util/plugin.js';
 export const NAME = 'Commitizen';
 export const ENABLERS = ['commitizen'];
 export const isEnabled = ({ dependencies }) => hasDependency(dependencies, ENABLERS);
-export const CONFIG_FILE_PATTERNS = ['.czrc', 'package.json'];
+export const CONFIG_FILE_PATTERNS = ['.czrc', '.cz.json', 'package.json'];
 const findPluginDependencies = async (configFilePath, { manifest }) => {
     const config = configFilePath.endsWith('package.json')
         ? manifest.config?.commitizen

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.19.3";
+export declare const version = "2.19.5";

package/dist/version.js

@@ -1 +1 @@
-export const version = '2.19.3';
+export const version = '2.19.5';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knip",
-  "version": "2.19.3",
+  "version": "2.19.5",
   "description": "Find unused files, dependencies and exports in your TypeScript and JavaScript projects",
   "homepage": "https://github.com/webpro/knip",
   "repository": "github:webpro/knip",
@@ -62,26 +62,26 @@
   },
   "devDependencies": {
     "@jest/types": "29.6.1",
-    "@npmcli/package-json": "4.0.1",
+    "@npmcli/package-json": "5.0.0",
     "@release-it/bumper": "5.1.0",
     "@swc/cli": "0.1.62",
-    "@swc/core": "1.3.76",
+    "@swc/core": "1.3.77",
     "@types/eslint": "8.44.2",
     "@types/js-yaml": "4.0.5",
     "@types/micromatch": "4.0.2",
     "@types/minimist": "1.2.2",
-    "@types/node": "20.4.9",
+    "@types/node": "20.5.0",
     "@types/npmcli__map-workspaces": "3.0.1",
     "@types/webpack": "5.28.1",
-    "@typescript-eslint/eslint-plugin": "6.3.0",
-    "@typescript-eslint/parser": "6.3.0",
+    "@typescript-eslint/eslint-plugin": "6.4.0",
+    "@typescript-eslint/parser": "6.4.0",
     "c8": "8.0.1",
-    "eslint": "8.46.0",
+    "eslint": "8.47.0",
     "eslint-import-resolver-typescript": "3.6.0",
     "eslint-plugin-import": "2.28.0",
     "eslint-plugin-n": "16.0.1",
-    "prettier": "3.0.1",
-    "release-it": "16.1.4",
+    "prettier": "3.0.2",
+    "release-it": "16.1.5",
     "remark-cli": "11.0.0",
     "remark-preset-webpro": "0.0.3",
     "tsx": "3.12.7",