@knip/mcp 0.0.1

package/docs/docs/writing-a-plugin/inputs.md

@@ -0,0 +1,162 @@
+---
+title: Inputs
+sidebar:
+  order: 2
+---
+
+You may have noticed functions like `toDeferResolve` and `toEntry`. They're a
+way for plugins to tell what they've found and how Knip should handle those. The
+more precise a plugin can be, the better it is for results and performance.
+Here's an overview of all input type functions:
+
+- [toEntry][1]
+- [toProductionEntry][2]
+- [toProject][3]
+- [toDependency][4]
+- [toProductionDependency][5]
+- [toDeferResolve][6]
+- [toDeferResolveEntry][7]
+- [toConfig][8]
+- [toBinary][9]
+- [toAlias][10]
+- [Options][11]
+
+## toEntry
+
+An `entry` input is just like an `entry` in the configuration. It should either
+be an absolute or relative path, and glob patterns are allowed.
+
+## toProductionEntry
+
+A production `entry` input is just like an `production` in the configuration. It
+should either be an absolute or relative path, and it can have glob patterns.
+
+## toProject
+
+A `project` input is the equivalent of `project` patterns in the configuration.
+It should either be an absolute or relative path, and (negated) glob patterns
+are allowed.
+
+## toDependency
+
+The `dependency` indicates the entry is a dependency, belonging in either the
+`"dependencies"` or `"devDependencies"` section of `package.json`.
+
+## toProductionDependency
+
+The production `dependency` indicates the entry is a production dependency,
+expected to be listed in `"dependencies"`.
+
+## toDeferResolve
+
+The `deferResolve` input type is used to defer the resolution of a specifier.
+This could be resolved to a dependency or an entry file. For instance, the
+specifier `"input"` could be resolved to `"input.js"`, `"input.tsx"`,
+`"input/index.js"` or the `"input"` package name. Local files are added as entry
+files, package names are external dependencies.
+
+If this does not lead to a resolution, the specifier will be reported under
+"unresolved imports".
+
+## toDeferResolveEntry
+
+The `deferResolveEntry` input type is similar to `deferResolve`, but it's used
+for entry files only (not dependencies) and unresolved inputs are ignored. It's
+different from `toEntry` as glob patterns are not supported.
+
+## toConfig
+
+The `config` input type is a way for plugins to reference a configuration file
+that should be handled by a different plugin. For instance, Angular
+configurations might contain references to `tsConfig` and `karmaConfig` files,
+so these `config` files can then be handled by the TypeScript and Karma plugins,
+respectively.
+
+Example:
+
+```ts
+toConfig('typescript', './path/to/tsconfig.json');
+```
+
+For instance, the Angular plugin uses this to tell Knip about its `tsConfig`
+value in `angular.json` projects.
+
+## toBinary
+
+The `binary` input type isn't used by plugins directly, but by the shell script
+parser (through the `getInputsFromScripts` helper). Think of GitHub Actions
+workflow YAML files or husky scripts. Using this input type, a binary is
+"assigned" to the dependency that has it as a `"bin"` in their `package.json`.
+
+## toAlias
+
+The `alias` input type adds path aliases to the core module resolver. They're
+added to `compilerOptions.paths` so the syntax is identical.
+
+## Options
+
+When creating inputs from specifiers, an extra `options` object as the second
+argument can be provided.
+
+### dir
+
+The optional `dir` option assigns the input to a different workspace. For
+instance, GitHub Action workflows are always stored in the root workspace, and
+support `working-directory` in job steps. For example:
+
+```yaml
+jobs:
+  stylelint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npx esbuild
+        working-directory: packages/app
+```
+
+The GitHub Action plugin understands `working-directory` and adds this `dir` to
+the input:
+
+```ts
+toDependency('esbuild', { dir: 'packages/app' });
+```
+
+Knip now understands `esbuild` is a dependency of the workspace in the
+`packages/app` directory.
+
+### optional
+
+Use the `optional` flag to indicate the dependency is optional. Then, a
+dependency won't be flagged as unlisted if it isn't.
+
+### allowIncludeExports
+
+By default, exports of entry files such as `src/index.ts` or the files in
+`package.json#exports` are not reported as unused. When using the
+`--include-entry-exports` flag or `isIncludeExports: true` option, unused
+exports on such entry files are also reported.
+
+Exports of entry files coming from plugins are not included in the analysis,
+even with the option enabled. This is because certain tools and frameworks
+consume named exports from entry files, causing false positives.
+
+The `allowIncludeExports` option allows the exports of entry files to be
+reported as unused when using `--include-entry-exports`. This option is
+typically used with the [toProductionEntry][2] input type.
+
+Example:
+
+```ts
+toProductionEntry('./entry.ts', { allowIncludeExports: true });
+```
+
+[1]: #toentry
+[2]: #toproductionentry
+[3]: #toproject
+[4]: #todependency
+[5]: #toproductiondependency
+[6]: #todeferresolve
+[7]: #todeferresolveentry
+[8]: #toconfig
+[9]: #tobinary
+[10]: #toalias
+[11]: #options

package/docs/explanations/comparison-and-migration.md

@@ -0,0 +1,129 @@
+---
+title: Comparison & Migration
+---
+
+First of all, Knip owes a lot to the projects on this page and they've all been
+inspirational in their own way. For best results, Knip has [a vision embracing
+comprehensiveness][1] which is larger in scope than any of the alternatives. So
+if any of those tools has the right scope for your requirements, then by all
+means, use what suits you best. Note that most projects are no longer
+maintained.
+
+All tools have in common that they have less features and don't support the
+concept of [monorepos/workspaces][2]. Feel free to send in projects that Knip
+does not handle better, Knip loves to be challenged!
+
+## Migration
+
+A migration consists of deleting the dependency and its configuration file and
+[getting started with Knip][3]. You should end up with less configuration.
+
+## Comparison
+
+### depcheck
+
+> [Depcheck][4] is a tool for analyzing the dependencies in a project to see:
+> how each dependency is used, which dependencies are useless, and which
+> dependencies are missing from package.json.
+
+The project has plugins (specials), yet not as many as Knip has and they're not
+as advanced. It also supports compilers (parsers) for non-standard files.
+
+The following commands are similar:
+
+```sh
+depcheck
+knip --dependencies
+```
+
+### unimported
+
+> Find and fix dangling files and unused dependencies in your JavaScript
+> projects.
+
+[unimported][5] is fast and works well. It works in what Knip calls "production
+mode" exclusively. If you're fine with a little bit of configuration and don't
+want or need to deal with non-production items (such as `devDependencies` and
+test files), then this might work well for you.
+
+The following commands are similar:
+
+```sh
+unimported
+knip --production --dependencies --files
+```
+
+**Project status**: The project is archived and recommends Knip.
+
+### ts-prune
+
+> Find unused exports in a typescript project. 🛀
+
+[ts-prune][6] aims to find potentially unused exports in your TypeScript project
+with zero configuration.
+
+The following commands are similar:
+
+```sh
+ts-prune
+knip --include exports,types,nsExports,nsTypes
+```
+
+Use `knip --exports` to also include class and enum members.
+
+**Project status**: The project is archived and recommends Knip.
+
+### ts-unused-exports
+
+> [ts-unused-exports][7] finds unused exported symbols in your Typescript
+> project
+
+The following commands are similar:
+
+```sh
+ts-unused-exports
+knip --include exports,types,nsExports,nsTypes
+```
+
+Use `knip --exports` to also include class and enum members.
+
+### tsr
+
+> Remove unused code from your TypeScript Project
+
+[tsr][8] (previously `ts-remove-unused`) removes unused exports, and works based
+on a single `tsconfig.json` file (`includes` and `excludes`) and requires no
+configuration. It removes the `export` keyword or the whole export declaration.
+
+## Related projects
+
+Additional alternative and related projects include:
+
+- [deadfile][9]
+- [DepClean][10]
+- [dependency-check][11]
+- [find-unused-exports][12]
+- [next-unused][13]
+- [npm-check][14]
+- [renoma][15]
+
+In general, the [e18e.dev][16] website and in particular the [Cleanup][17]
+section is a great resource when dealing with technical debt.
+
+[1]: ./why-use-knip.md#comprehensive
+[2]: ../features/monorepos-and-workspaces.md
+[3]: ../overview/getting-started.mdx
+[4]: https://github.com/depcheck/depcheck
+[5]: https://github.com/smeijer/unimported
+[6]: https://github.com/nadeesha/ts-prune
+[7]: https://github.com/pzavolinsky/ts-unused-exports
+[8]: https://github.com/line/tsr
+[9]: https://github.com/M-Izadmehr/deadfile
+[10]: https://github.com/mysteryven/depclean
+[11]: https://github.com/dependency-check-team/dependency-check
+[12]: https://github.com/jaydenseric/find-unused-exports
+[13]: https://github.com/pacocoursey/next-unused
+[14]: https://github.com/dylang/npm-check
+[15]: https://github.com/bluwy/renoma
+[16]: https://e18e.dev
+[17]: https://e18e.dev/guide/cleanup.html

package/docs/explanations/entry-files.md

@@ -0,0 +1,70 @@
+---
+title: Entry Files
+sidebar:
+  order: 1
+---
+
+Entry files are the starting point for Knip to determine what files are used in
+the codebase. More entry files lead to increased coverage of the codebase. This
+also leads to more dependencies to be discovered. This page explains how Knip
+and its plugins try to find entry files so you don't need to configure them
+yourself.
+
+## Default entry file patterns
+
+For brevity, the [default configuration][1] on the previous page mentions only
+`index.js` and `index.ts`, but the default set of file names and extensions is
+actually a bit larger:
+
+- `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. Here's the default configuration in full:
+
+```json
+{
+  "entry": [
+    "{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}",
+    "src/{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}"
+  ],
+  "project": ["**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}!"]
+}
+```
+
+Next to the default locations, Knip looks for `entry` files in other places. In
+a monorepo, this is done for each workspace separately.
+
+The values you set override the default values, they are not merged.
+
+Also see [FAQ: Where does Knip look for entry files?][2]
+
+## Plugins
+
+Plugins often add entry files. For instance, if the Remix, Storybook and Vitest
+plugins are enabled in your project, they'll add additional entry files. See
+[the next page about plugins][3] for more details about this.
+
+## Scripts in package.json
+
+The `package.json` is scanned for entry files. The `main`, `bin`, and `exports`
+fields may contain entry files. The `scripts` are also parsed to find entry
+files and dependencies. See [Script Parser][4] for more details.
+
+## Ignored files
+
+Knip respects `.gitignore` files. By default, ignored files are not added as
+entry files. This behavior can be disabled by using the [`--no-gitignore`][5]
+flag on the CLI.
+
+## Configuring project files
+
+See [configuring project files][6] for guidance on tuning `entry` and `project`
+and when to use `ignore`.
+
+[1]: ../overview/configuration.md#defaults
+[2]: ../reference/faq.md#where-does-knip-look-for-entry-files
+[3]: ./plugins.md
+[4]: ../features/script-parser.md
+[5]: ../reference/cli.md#--no-gitignore
+[6]: ../guides/configuring-project-files.md

package/docs/explanations/plugins.md

@@ -0,0 +1,318 @@
+---
+title: Plugins
+sidebar:
+  order: 2
+---
+
+This page describes why Knip uses plugins and the difference between `config`
+and `entry` files.
+
+Knip has an extensive and growing [list of built-in plugins][1]. Feel free to
+[write a plugin][2] so others can benefit too!
+
+## What does a plugin do?
+
+Plugins are enabled if the related package is listed in the list of dependencies
+in `package.json`. For instance, if `astro` is listed in `dependencies` or
+`devDependencies`, then the Astro plugin is enabled. And this means that this
+plugin will:
+
+- Handle [configuration files][3] like `astro.config.mjs`
+- Add [entry files][4] such as `src/pages/**/*.astro`
+- Define [command-line arguments][5]
+
+## Configuration files
+
+Knip uses [entry files][6] as starting points to scan your source code and
+resolve other internal files and external dependencies. The module graph can be
+statically resolved through the `require` and `import` statements in those
+source files. However, configuration files reference external dependencies in
+various ways. Knip uses a plugin for each tool to parse configuration files and
+find those dependencies.
+
+### Example: ESLint
+
+In the first example we look at [the ESLint plugin][7]. The default `config`
+file patterns include `.eslintrc.json`. Here's a minimal example:
+
+```json title=".eslintrc.json"
+{
+  "extends": ["airbnb", "prettier"],
+  "plugins": ["@typescript-eslint"]
+}
+```
+
+Configuration files like this don't `import` or `require` anything, but they do
+require the referenced dependencies to be installed.
+
+In this case, the plugin will return three dependencies:
+
+- `eslint-config-airbnb`
+- `eslint-config-prettier`
+- `@typescript-eslint/eslint-plugin`
+
+Knip will then look for missing dependencies in `package.json` and report those
+as unlisted. And vice versa, if there are any ESLint plugins listed in
+`package.json`, but unused, those will be reported as well.
+
+### Example: Vitest
+
+The second example uses [the Vitest plugin][7]. Here's a minimal example of a
+Vitest configuration file:
+
+```ts title="vitest.config.ts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'istanbul',
+    },
+    environment: 'happy-dom',
+  },
+});
+```
+
+The Vitest plugin reads this configuration and return two dependencies:
+
+- `@vitest/coverage-istanbul`
+- `vitest-environment-happy-dom`
+
+Knip will look for missing and unused dependencies in `package.json` and report
+accordingly.
+
+Some tools allow configuration to be stored in `package.json`, that's why some
+plugins contain `package.json` in the list of `config` files.
+
+:::tip[Summary]
+
+Plugins parse `config` files to find external dependencies. Knip uses this to
+determine unused and unlisted dependencies.
+
+:::
+
+## Entry files
+
+Many plugins have default `entry` files configured. When the plugin is enabled,
+Knip will add entry files as configured by the plugin to resolve used files and
+dependencies.
+
+For example, if `next` is listed as a dependency in `package.json`, the Next.js
+plugin will automatically add multiple patterns as entry files, such as
+`pages/**/*.{js,jsx,ts,tsx}`. If `vitest` is listed, the Vitest plugin adds
+`**/*.{test,test-d,spec}.ts` as entry file patterns. Most plugins have entry
+files configured, so you don't have to.
+
+It's mostly plugins for meta frameworks and test runners that have `entry` files
+configured.
+
+:::tip[Plugins result in less configuration]
+
+Plugins uses entry file patterns as defined in the configuration files of these
+tools. So you don't need to repeat this in your Knip configuration.
+
+:::
+
+For example, let's say your Playwright configuration contains the following:
+
+```ts title="playwright.config.ts"
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  testDir: 'integration',
+  testMatch: ['**/*-test.ts'],
+};
+
+export default config;
+```
+
+The Playwright plugin will read this configuration file and return those entry
+patterns (`integration/**/*-test.ts`). Knip will then not use the default entry
+patterns.
+
+You can still override this behavior in your Knip configuration:
+
+```json title="knip.json"
+{
+  "playwright": {
+    "entry": "src/**/*.integration.ts"
+  }
+}
+```
+
+This should not be necessary though. Please consider opening a pull request or a
+bug report if any plugin is not behaving as expected.
+
+:::tip[Summary]
+
+Plugins try hard to automatically add the correct entry files.
+
+:::
+
+## Entry files from config files
+
+Entry files are part of plugin configuration (as described in the previous
+section). Yet plugins can also return additional entry files after parsing
+configuration files. Below are some examples of configuration files parsed by
+plugins to return additional entry files. The goal of these examples is to give
+you an idea about the various ways Knip and its plugins try to find entry files
+so you don't need to configure them yourself.
+
+### Angular
+
+The Angular plugin parses the Angular configuration file. Here's a fragment:
+
+```json title="angular.json"
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "projects": {
+    "knip-angular-example": {
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:browser",
+          "options": {
+            "outputPath": "dist/knip-angular-example",
+            "main": "src/main.ts",
+            "tsConfig": "tsconfig.app.json"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This will result in `src/main.ts` being added as an entry file (and
+`@angular-devkit/build-angular` as a referenced dependency).
+
+Additionally, the Angular plugin returns `tsconfig.app.json` as a configuration
+file for the TypeScript plugin.
+
+### GitHub Actions
+
+This plugin parses workflow YAML files. This fragment contains three `run`
+scripts:
+
+```yml title=".github/workflows/deploy.yml"
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm install
+      - run: node scripts/build.js
+      - run: node --loader tsx scripts/deploy.ts
+      - run: playwright test -c playwright.web.config.ts
+        working-dir: e2e
+```
+
+From these scripts, the `scripts/build.js` and `scripts/deploy.ts` files will be
+added as entry files by the GitHub Actions plugin.
+
+Additionally, the file `e2e/playwright.web.config.ts` is detected and will be
+handed over as a Playwright configuration file.
+
+Read more about this in [command-line arguments][5].
+
+### webpack
+
+Let's take a look at this example webpack configuration file:
+
+```js title="webpack.config.js"
+module.exports = env => {
+  return {
+    entry: {
+      main: './src/app.ts',
+      vendor: './src/vendor.ts',
+    },
+    module: {
+      rules: [
+        {
+          test: /\.(woff|ttf|ico|woff2|jpg|jpeg|png|webp)$/i,
+          use: 'base64-inline-loader',
+        },
+      ],
+    },
+  };
+};
+```
+
+The webpack plugin will parse this and add `./src/app.ts` and `./src/vendor.ts`
+as entry files. It will also add `base64-inline-loader` as a referenced
+dependency.
+
+:::tip[Summary]
+
+Plugins can find additional entry files when parsing config files.
+
+:::
+
+## Bringing it all together
+
+Sometimes a configuration file is a JavaScript or TypeScript file that imports
+dependencies, but also contains configuration that needs to be parsed by a
+plugin to find additional dependencies.
+
+Let's take a look at this example Vite configuration file:
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig(async ({ mode, command }) => {
+  return {
+    plugins: [react()],
+    test: {
+      setupFiles: ['./setup-tests.ts'],
+      environment: 'happy-dom',
+      coverage: {
+        provider: 'c8',
+      },
+    },
+  };
+});
+```
+
+This file imports `vite` and `@vitejs/plugin-react` directly, but also
+indirectly references the `happy-dom` and `@vitest/coverage-c8` packages.
+
+The Vite plugin of Knip will **dynamically** load this configuration file and
+parse the exported configuration. But it's not aware of the `vite` and
+`@vitejs/plugin-react` imports. This is why such `config` files are also
+automatically added as `entry` files for Knip to **statically** resolve the
+`import` and `require` statements.
+
+Additionally, `./setup-tests.ts` will be added as an `entry` file.
+
+## Command-Line Arguments
+
+Plugins may define the arguments where Knip should look for entry files,
+configuration files and dependencies. We've already seen some examples above:
+
+```sh
+node --loader tsx scripts/deploy.ts
+playwright test -c playwright.web.config.ts
+```
+
+Please see [script parser][8] for more details.
+
+## Summary
+
+:::tip[Summary]
+
+Plugins are configured with two distinct types of files:
+
+- `config` files are dynamically loaded and parsed by the plugin
+- `entry` files are added to the module graph
+- Both can recursively lead to additional entry files, config files and
+  dependencies
+
+:::
+
+[1]: ../reference/plugins.md
+[2]: ../guides/writing-a-plugin.md
+[3]: #configuration-files
+[4]: #entry-files
+[5]: #command-line-arguments
+[6]: ./entry-files.md
+[7]: ../reference/plugins/eslint.md
+[8]: ../features/script-parser.md