@knip/mcp 0.0.20 → 0.0.21

package/src/docs/docs/reference/faq.md

@@ -0,0 +1,493 @@
+---
+title: FAQ
+date: 2024-08-20
+---
+
+## Introduction
+
+Knip finds and fixes unused dependencies, exports and files. As a "kitchen sink"
+in the npm ecosystem, it creates comprehensive module and dependency graphs of
+your project.
+
+:::note[Rationale]
+
+The JavaScript/TypeScript ecosystem has a vast amount of frameworks and tools.
+Additionally, file locations, configuration semantics, command-line arguments
+and so on vary wildly. Files and dependencies are referenced in many ways. Knip
+tries harder than you think to cover it all.
+
+:::
+
+This FAQ is an attempt to provide some perspective on a few design decisions and
+why certain things work the way they do. Here and there it's intentionally a bit
+more in-depth than the rest of the docs.
+
+## Why should I even bother to do all this?
+
+Because the payoff is huge. While it might take a bit of effort to configure
+Knip correctly initially, a clean module graph gives you absolute confidence in
+your codebase. You can delete dead code, remove unused dependencies, and
+refactor with certainty. It prevents the slow accumulation of technical debt and
+keeps your project lean and fast. Once configured, Knip runs quickly in CI and
+keeps your codebase pristine automatically.
+
+:::tip
+
+Try the [Knip MCP Server][1] or the [Knip Editor Extension][2]. Let your coding
+agent use the built-in MCP Server and create a custom `knip.json` for you, so
+you don't have to.
+
+:::
+
+## Common Pitfalls
+
+### Why shouldn't I ignore or disable configuration hints?
+
+Configuration hints are critical for building a healthy and accurate module
+graph. They usually indicate that Knip cannot resolve a dependency, plugin, or
+entry file. If you ignore or disable these hints, Knip's understanding of your
+project will be incomplete, which inevitably leads to false positives (reporting
+used code as unused). Always address configuration hints first before looking at
+other reported issues.
+
+### Why is it a bad idea to use `ignore` patterns like I do in ESLint?
+
+Knip is not a regular file-based linter like ESLint. It works by analyzing the
+entire interconnected module graph of your project. Using `ignore` patterns does
+not exclude files from the analysis, it only suppresses the reporting of issues
+in those files. This hides real issues and creates blind spots. Instead of
+ignoring files, ensure your entry points and plugins are configured correctly,
+and use `project` patterns to define the boundaries of your codebase. Read more:
+[Configuring Project Files][3].
+
+If you have specific exports (such as types) that are only used within the file
+they are defined, use the [ignoreExportsUsedInFile][4] configuration option
+rather than ignoring the file entirely.
+
+### How should I exclude tests and development tools from the analysis?
+
+A common mistake is trying to exclude test files, storybooks, or development
+tools using `project` or `ignore` patterns. The correct approach is to use
+[production mode][5]. This mode is specifically designed to strictly analyze
+only your production source code and `dependencies`, automatically excluding
+tests and `devDependencies` without requiring complex ignore rules.
+
+### Why shouldn't I run `knip --fix` immediately?
+
+Running `knip --fix` before your configuration is fully settled is dangerous. If
+your configuration is missing entry points or has unresolved hints, Knip might
+think perfectly valid, actively used code is unused. Auto-fixing in this state
+can lead to deleting code that your application relies on. Always verify the
+reported issues manually and ensure your configuration is solid before using the
+`--fix` flag.
+
+## Comparison
+
+### Why isn't Knip an ESLint plugin?
+
+Linters like ESLint analyze files separately, while Knip lints projects as a
+whole.
+
+Knip requires full module and dependency graphs to find clutter across the
+project. Creating these comprehensive graphs is not a trivial task and it seems
+no such tool exists today, even more so when it comes to monorepos.
+
+File-oriented linters like ESLint are complementary to Knip.
+
+### Isn't tree-shaking enough?
+
+In short: no. They share an important goal: improve UX by removing unused code.
+But tree-shaking and Knip are different and complementary tools.
+
+Tree-shaking is a build or compile-time activity to reduce production bundle
+size. It typically operates on bundled production code, which might include
+external/third-party code. A build time optimization and "out of your hands".
+
+On the other hand, Knip is a project linter that should be part of the
+development and QA phase. It lints, reports and fixes only your own source code.
+Moreover, in contrast with other linters, focuses on inter-file dependencies, so
+dead code within a file may not be caught by Knip.
+
+Issues reported by the linter are for you to handle and review.
+
+Besides those differences, Knip has a broader scope:
+
+- Improve DX (see [less is more][6]).
+- Unless using [production mode][5], also lint all source code like tests,
+  scripts and Storybook stories.
+- Handle more [types of issues][7] (such as unlisted dependencies).
+
+## Synergy
+
+### Why does Knip have plugins?
+
+Plugins are an essential part of Knip. They prevent you from a lot of
+configuration out of the box, by adding entry files as accurately as possible
+and only for the tools actually installed. Yet the real magic is in their custom
+parsers for configuration files and command-line argument definitions.
+
+For instance, Vitest has the `environment` configuration option. The Vitest
+plugin knows `"node"` is the default value for `environment` which does not
+require an extra package, but will translate `"edge-runtime"` to the
+`@edge-runtime/vm` package. This allows Knip to report it if this package is not
+listed in `package.json`, or when it is no longer used after changes in the
+Vitest configuration.
+
+Configuration files may also contain references to entry files. For instance,
+Jest has `setupFilesAfterEnv: "<rootDir>/jest.setup.js"` or a reference may
+point to a file in another workspace in the same monorepo, e.g.
+`setupFiles: ['@org/shared/jest-setup.ts']`. Those entry files may also contain
+imports of internal modules or external dependencies, and so on.
+
+### Why is Knip so heavily engineered?
+
+Even though a modular approach has its merits, for Knip it makes sense to have
+all the pieces in a single tool.
+
+Building up the module and dependency graphs requires non-standard module
+resolution and not only static but also dynamic analysis (i.e. actually load and
+execute modules), such as for parsers of plugins to receive the exported value
+of dynamic tooling configuration files. Additionally, [exports consumed by
+external libraries][8] require type information, as supported by the TypeScript
+backend. Last but not least, shell script parsing is required to find the right
+entry files, configuration files and dependencies accurately.
+
+The rippling effect of plugins and recursively adding entry files and
+dependencies to build up the graphs is also exactly what's meant by
+["comprehensive" here][9].
+
+## Building the graphs
+
+### Where does Knip look for entry files?
+
+- In default locations such as `index.js` and `src/index.ts`
+- In `main`, `bin` and `exports` fields in `package.json`
+- In the entry files as configured by enabled plugins
+- In `config` files as configured and parsed by enabled plugins
+- The `config` files themselves are entry files
+- In dynamic imports (i.e. `require()` and `import()` calls)
+- In `require.resolve('./entry.js')`
+- In `import.meta.resolve('./entry.mjs')`
+- Through scripts inside template strings in source files such as:
+
+```ts
+await $({ stdio: 'inherit' })`c8 node hydrate.js`; // execa
+await $`node scripts/parse.js`; // bun/zx
+```
+
+- Through scripts in `package.json` such as:
+
+```json
+{
+  "name": "my-lib",
+  "scripts": {
+    "start": "node --import tsx/esm run.ts",
+    "start": "vitest -c config/vitest.config.ts"
+  }
+}
+```
+
+- Through plugins handling CI workflow files like `.github/workflows/ci.yml`:
+
+```yaml
+jobs:
+  test:
+    steps:
+      run: playwright test e2e/**/*.spec.ts --config playwright.e2e.config.ts
+      run: node --import tsx/esm run.ts
+```
+
+Scripts like the ones shown here may also contain references to configuration
+files (`config/vitest.config.ts` and `playwright.e2e.config.ts` in the examples
+above). They're recognized as configuration files and passed to their respective
+plugins, and may contain additional entry files.
+
+Entry files are added to the module graph. [Module resolution][10] might result
+in additional entry files recursively until no more entry files are found.
+
+### What does Knip look for in source files?
+
+The TypeScript source file parser is powerful and fault-tolerant. Knip visits
+all nodes of the generated AST to find:
+
+- Imports and dynamic imports of internal modules and external dependencies
+- Exports
+- Accessed properties on namespace imports and re-exports to track individual
+  export usage
+- Calls to `require.resolve` and `import.meta.resolve`
+- Scripts in template strings (passed to [script parser][11])
+
+### What's in the graphs?
+
+Once the module and dependency graphs are created, they contain the information
+required to create the report including all issue types:
+
+- Unused files
+- Unused dependencies
+- Unused devDependencies
+- Referenced optional peerDependencies
+- Unlisted dependencies
+- Unlisted binaries
+- Unresolved imports
+- Unused exports
+- Unused exported types
+- Unused exported enum members
+- Duplicate exports
+
+And optionally more issue types like individual exports and exported types in
+namespace imports, and unused class members.
+
+The graphs allows to report more interesting details, such as:
+
+- Circular references
+- Usage numbers per export
+- Export usage across workspaces in a monorepo
+- List of all binaries used
+- List of all used (OS) binaries not installed in `node_modules`
+
+### Why doesn't Knip just read the lockfile?
+
+Knip reads the `package.json` file of each dependency. Most of the information
+required is in the lockfile as well, which would be more efficient. However,
+there are a few issues with this approach:
+
+- It requires lockfile parsing for each lockfile format and version of each
+  package manager.
+- The lockfile doesn't contain whether the package [has types included][12].
+
+## Module Resolution
+
+### Why doesn't Knip use an existing module resolver?
+
+Runtimes like Node.js provide `require.resolve` and `import.meta.resolve`.
+TypeScript comes with module resolution built-in. More module resolvers are out
+there and bundlers are known to use or come with module resolvers. None of them
+seem to meet all requirements to be usable on its own by Knip:
+
+- Support non-standard extensions like `.css`, `.svelte` and `.png`
+- Support path aliases
+- Support `exports` map in `package.json`
+- Support self-referencing imports
+- Rewire `package.json#main` build artifacts like `dist/module.js` to its source
+  at `src/module.ts`
+- Don't resolve to type definition paths like `module.d.ts` but source code at
+  `module.js`
+
+A few strategies have been tried and tweaked, and Knip currently uses a
+combination of [oxc-resolver][13], the TypeScript module resolver and a few
+customizations. This single custom module resolver function is hooked into the
+TypeScript compiler and language service hosts.
+
+Everything else is handled by `oxc-resolver` for things like [script
+parsing][11] and resolving references to files in other workspaces.
+
+### How does Knip handle non-standard import syntax?
+
+Knip tries to be resilient against import syntax like what's used by e.g.
+webpack loaders or Vite asset imports. Knip strips off the prefixes and suffixes
+in import specifiers like this:
+
+```ts title="component.ts"
+import Icon from './icon.svg?raw';
+import Styles from '-!style-loader!css-loader?modules!./styles.css';
+```
+
+In this example, the `style-loader` and `css-loader` dependencies should be
+dependencies found in webpack configuration, handled by Knip's webpack plugin.
+
+## TypeScript
+
+### What's the difference between workspaces, projects and programs?
+
+A workspace is a directory with a `package.json` file. They're configured in
+`package.json#workspaces` (or `pnpm-workspaces.yml`). In case a directory has a
+`package.json` file, but is not a workspace (from a package manager
+perspective), it can be added as a workspace to the Knip configuration.
+
+Projects - in the context of TypeScript - are directories with a `tsconfig.json`
+file. They're not a concept in Knip.
+
+A TypeScript program has a 1-to-1 relationship with workspaces if they're
+analyzed in isolation. However, by default Knip optimizes for performance and
+utilizes [workspace sharing][14]. That's why debug output contains messages like
+"Installed 2 programs for 29 workspaces".
+
+### Why doesn't Knip match my TypeScript project structure?
+
+Repositories and workspaces in a monorepo aren't necessarily structured like
+TypeScript projects. Put simply, the location of `package.json` files isn't
+always adjacent to `tsconfig.json` files. Knip follows the structure of
+workspaces in a monorepo.
+
+An additional layering of TypeScript projects would complicate things. The
+downside is that a `tsconfig.json` file not used by Knip may have conflicting
+module resolution settings, potentially resulting in missed files.
+
+In practice, this is rarely an issue. Knip sticks to the workspaces structure
+and installs a single "kitchen sink" module resolver function per workspace.
+Different strategies might add more complexity and performance penalties, while
+the current strategy is simple, fast and good enough.
+
+Note that any directory with a `package.json` not listed in the root
+`package.json#workspaces` can be added to the Knip configuration manually to
+have it handled as a separate workspace.
+
+### Why doesn't Knip analyze workspaces in isolation by default?
+
+Knip creates TypeScript programs to create a module graph and traverse file
+ASTs. In a monorepo, it would make a lot of sense to create one program per
+workspace. However, this slows down the whole process considerably. That's why
+Knip shares the files of multiple workspaces in a single program if their
+configuration allows it. This optimization is enabled by default, while it also
+allows the module resolver (one per program) to do some more caching.
+
+Also see [workspace sharing][14].
+
+### Why doesn't Knip just use `ts.findReferences`?
+
+TypeScript has a very good "Find references" feature, that you might be using in
+your IDE as well. Yet at scale this becomes too slow. That's why Knip builds up
+its own module graph to look up export usages. Additional benefits for this
+comprehensive graph include:
+
+- serializable and cacheable
+- enables more features
+- usable for other tools to build upon as well
+
+Without sacrificing these benefits, Knip does use `ts.findReferences` to find
+references to class members (i.e. when the issue type `classMembers` is
+included). In case analysis of exports requires type information of external
+dependencies, the [`--include-libs ` flag][8] will trigger the same.
+
+### Why can't I use path aliases to reference other workspaces?
+
+Projects can use `compilerOptions.paths` to alias paths in other workspaces in
+the same monorepo. Knip doesn't understand those paths might represent internal
+workspaces and might report false positives.
+
+The recommendation and best practice is to list such workspaces/dependencies in
+`package.json`, and import them as such. Other tooling should not have any
+issues with this standard approach either.
+
+Also see the example in [TypeScript path aliases in monorepos][15].
+
+### What's up with that configurable `tsconfig.json` location?
+
+There's a difference between `--tsConfig [file]` as a CLI argument and the
+`typescript.config` option in Knip configuration.
+
+The [`--tsConfig [file]` option][16] is used to provide an alternative location
+for the default root `tsconfig.json` file. Relevant `compilerOptions` include
+`paths` and `moduleResolution`. This setting is only available at the root
+level.
+
+On the other hand, the [`config` option of the plugin][17] can be set per
+workspace. The TypeScript plugin extracts referenced external dependencies such
+as those in `extends`, `compilerOptions.types` and JSX settings:
+
+```json title="tsconfig.json"
+{
+  "extends": "@tsconfig/node20/tsconfig.json",
+  "compilerOptions": {
+    "jsxImportSource": "hastscript/svg"
+  }
+}
+```
+
+From this example, Knip can determine whether the `@tsconfig/node20` and
+`hastscript` dependencies are properly listed in `package.json`.
+
+#### Notes
+
+- The TypeScript plugin doesn't add support for TypeScript to Knip (that's
+  already built-in). Like other plugins, it extracts dependencies from
+  `tsconfig.json`. With the `typescript.config` option an alternative location
+  for `tsconfig.json` can be set per workspace.
+- In case path aliases from `compilerOptions.paths` aren't picked up by Knip,
+  either use `--tsConfig [file]` to target a different `tsconfig.json`, or
+  manually add [paths][18] to the Knip configuration. The latter can be done per
+  workspace.
+
+## Compilers
+
+### How does Knip handle Svelte or Astro files?
+
+To further increase the coverage of the module graph, non-standard files other
+than JavaScript and TypeScript modules should be included as well. For instance,
+`.mdx` and `.astro` files can import each other, internal modules and external
+dependencies.
+
+Knip includes basic "compilers" for a few common file types (Astro, MDX, Svelte,
+Vue). Knip does not include actual compilers for reasons of potential
+incompatibility with the existing compiler, and dependency size. Knip allows to
+override them with the compilers in your project, and add additional ones for
+other file types.
+
+### Why are the exports of my `.vue` files not used?
+
+Knip comes with basic "compilers" for a few common non-standard file types.
+They're not actual compilers, they're regular expressions only to extract import
+statements. Override the built-in Vue "compiler" with the real one in your
+project. Also see the answer to the previous question and [Compilers][19].
+
+## Miscellaneous
+
+### Why isn't production mode the default?
+
+The default mode of Knip includes all source files, tests, dependencies, dev
+dependencies and tooling configuration.
+
+On the other hand, production mode considers only source files and production
+dependencies. Plugins add only production entry files.
+
+Which mode should've been the default? They both have their merits:
+
+- Production mode catches dead production code and dependencies. This mode has
+  the most impact on UX, since less code tends to be faster and safer.
+- Default mode potentially catches more issues, e.g. lots of unused plugins of
+  tooling, including most issues found in production mode. This mode has the
+  most impact on DX, for the same reason.
+
+Also see [production mode][5].
+
+### Why doesn't Knip have...?
+
+Examples of features that have been requested include:
+
+- Expose programmatic API
+- Add local/custom plugins
+- Expose the module and dependency graphs
+- Custom AST visitors, e.g. to find and return:
+  - Unused interface/type members
+  - Unused object members (and e.g. React component props)
+  - Unused object props in function return values
+- Analyze workspaces in parallel
+- Support Deno
+- Improve internal code structures and accessibility to support contributions
+- Replace dependencies for better performance and correctness, such as for shell
+  script parsing and globbing with "unignores".
+
+These are all interesting ideas, but most increase the API surface area, and all
+require more development efforts and maintenance. Time is limited and
+[sponsorships][20] currently don't cover - this can change though!
+
+[1]: ../reference/integrations.md#mcp-server
+[2]: ../reference/integrations.md#vs-code-extension
+[3]: ../guides/configuring-project-files.md
+[4]: ../reference/configuration.md#ignoreexportsusedinfile
+[5]: ../features/production-mode.md
+[6]: ../explanations/why-use-knip.md#less-is-more
+[7]: ./issue-types.md
+[8]: ../guides/handling-issues.mdx#external-libraries
+[9]: ../explanations/why-use-knip.md#comprehensive
+[10]: #module-resolution
+[11]: ../features/script-parser.md
+[12]: ../guides/handling-issues.mdx#type-definition-packages
+[13]: https://oxc.rs/docs/guide/usage/resolver.html
+[14]: ../guides/performance.md#workspace-sharing
+[15]: ../guides/handling-issues.mdx#typescript-path-aliases-in-monorepos
+[16]: ../reference/cli.md#--tsconfig-file
+[17]: ../explanations/plugins.md#configuration-files
+[18]: ../reference/configuration.md#paths
+[19]: ../features/compilers.md
+[20]: /sponsors

package/src/docs/docs/reference/integrations.md

@@ -0,0 +1,105 @@
+---
+title: Integrations
+---
+
+- [VS Code/VSX Extension][1]
+- [JetBrains Plugin][2]
+- [MCP Server][3]
+- [Language Server][4]
+
+## VS Code Extension
+
+The official VS Code extension provides a rich integration with the [Knip
+Language Server][4]:
+
+- **Diagnostics**: Inline warnings for unused dependencies, exports and files
+- **Hover Information**: Hover over exports to see import and usage locations
+- **Imports Tree View**: Direct links to implementations
+- **Exports Tree View**: Direct links to import and usage locations
+- **Contention Detection**: Warnings for circular dependencies, conflicts and
+  branched import chains
+- **Built-in MCP Server**: Automated configuration support for coding agents
+
+Find [Knip on the VS Code Marketplace][5] and find [Knip in the Open VSX
+Registry][6].
+
+See below for [screenshots][7].
+
+## JetBrains Plugin
+
+A community plugin is available for JetBrains IDEs including WebStorm, IntelliJ
+IDEA, and others. The plugin is powered by the [Knip Language Server][4] and
+provides diagnostics. Find [Knip on the JetBrains Marketplace][8].
+
+## MCP Server
+
+The standalone MCP Server enables coding agents to configure Knip automatically.
+Tell your agent to "configure knip" and it will use the available tools to
+create, analyze and optimize your `knip.json` configuration.
+
+The [Knip MCP Server][9] is available separately and built into the [Knip VS
+Code Extension][1].
+
+Start:
+
+```sh
+npx @knip/mcp
+```
+
+Note: The VS Code extension has this MCP Server built-in.
+
+## Language Server
+
+The IDE integrations are powered by the Knip Language Server. It builds the full
+module graph of your project and provides a session with a graph explorer. See
+the [Knip Language Server documentation][10] for more details and information on
+integrating Knip.
+
+## VS Code Extension Screenshots
+
+### Lint Findings
+
+![Lint Findings][11]
+
+### Imports & Exports
+
+![Hover over imports and exports][12]
+
+### Contention
+
+The IDE extension shows extra issues in the tree views like circular
+dependencies.
+
+#### Circular Dependencies
+
+![Circular Dependencies][13]
+
+#### Conflicts
+
+![Conflicts][14]
+
+#### Branching
+
+![Branching][15]
+
+### Settings
+
+![VS Code Extension Settings][16]
+
+[1]: #vs-code-extension
+[2]: #jetbrains-plugin
+[3]: #mcp-server
+[4]: #language-server
+[5]: https://marketplace.visualstudio.com/items?itemName=webpro.vscode-knip
+[6]: https://open-vsx.org/extension/webpro/vscode-knip
+[7]: #vs-code-extension-screenshots
+[8]: https://plugins.jetbrains.com/plugin/29765-knip
+[9]: https://www.npmjs.com/package/@knip/mcp
+[10]:
+  https://github.com/webpro-nl/knip/blob/main/packages/language-server/README.md
+[11]: /screenshots/editors-and-agents/diagnostics.webp
+[12]: /screenshots/editors-and-agents/imports-exports.webp
+[13]: /screenshots/editors-and-agents/circular-dependency.webp
+[14]: /screenshots/editors-and-agents/conflict.webp
+[15]: /screenshots/editors-and-agents/branch.webp
+[16]: /screenshots/editors-and-agents/vscode-extension-settings.webp

package/src/docs/docs/reference/issue-types.md

@@ -0,0 +1,45 @@
+---
+title: Issue Types
+tableOfContents: false
+---
+
+Knip reports the following types of issues:
+
+| Title                                | Description                                           |       | Key                        |
+| :----------------------------------- | :---------------------------------------------------- | ----- | :------------------------- |
+| Unused files                         | Unable to find a reference to this file               | 🔧    | `files`                    |
+| Unused dependencies                  | Unable to find a reference to this dependency         | 🔧    | `dependencies`             |
+| Unused devDependencies               | Unable to find a reference to this devDependency      | 🔧    | `devDependencies`          |
+| Referenced optional peerDependencies | Optional peer dependency is used                      |       | `optionalPeerDependencies` |
+| Unlisted dependencies                | Used dependencies not listed in package.json          |       | `unlisted`                 |
+| Unlisted binaries                    | Binaries from dependencies not listed in package.json |       | `binaries`                 |
+| Unused catalog entries               | Unable to find a reference to this catalog entry      | 🔧    | `catalog`                  |
+| Unresolved imports                   | Unable to resolve this (import) specifier             |       | `unresolved`               |
+| Unused exports                       | Unable to find a reference to this export             | 🔧    | `exports`                  |
+| Unused exported types                | Unable to find a reference to this exported type      | 🔧    | `types`                    |
+| Exports in used namespace            | Namespace with export is used, but not export itself  | 🔧 🟠 | `nsExports`                |
+| Exported types in used namespace     | Namespace with type is used, but not type itself      | 🔧 🟠 | `nsTypes`                  |
+| Unused exported enum members         | Unable to find a reference to this enum member        | 🔧    | `enumMembers`              |
+| Unused exported class members        | Unable to find a reference to this class member       | 🔧 🟠 | `classMembers`             |
+| Duplicate exports                    | This is exported more than once                       |       | `duplicates`               |
+
+## Legend
+
+|     | Description                                         |
+| --- | :-------------------------------------------------- |
+| 🔧  | [Auto-fixable][1] issue types                       |
+| 🟠  | Not included by default (include with [filters][2]) |
+
+## Notes
+
+- When an issue type has zero issues, it is not shown.
+- Including or excluding `dependencies` (via CLI or configuration) automatically
+  includes or excludes `devDependencies` and `optionalPeerDependencies`. In
+  [rules][3], each key can be set individually.
+- In [strict production mode][4], `devDependencies` are not included.
+- The `types` issue type includes `enum`, `interface` and `type` exports.
+
+[1]: ../features/auto-fix.mdx
+[2]: ../features/rules-and-filters.md#filters
+[3]: ../features/rules-and-filters.md#rules
+[4]: ../features/production-mode.md#strict-mode