@knip/mcp 0.0.4 → 0.0.6

package/docs/docs/guides/issue-reproduction.md

@@ -0,0 +1,94 @@
+---
+title: Issue Reproduction
+sidebar:
+  order: 4
+---
+
+If you encounter an issue or false positives when using Knip, you can [open an
+issue on GitHub][1]. This will help you in your project, and will also improve
+Knip for everyone else!
+
+Think of Knip as a kitchen sink, it handles a large amount of projects and
+configurations, and your project is different from all others. Many factors may
+influence the issue at hand, such as:
+
+- Code syntax, import and export structure in source files
+- Dependencies, scripts and entry files in `package.json`
+- TypeScript configuration in `tsconfig.json`
+- Enabled plugins and related configuration files
+- Dependent or depending workspaces in a monorepo
+- Knip configuration in `knip.json`
+
+Create the minimum of source code and configuration with a few files to
+reproduce and demonstrate the issue. Having this as a basis has many benefits:
+
+- Minimize barriers and unrelated contextual overhead
+- Optimize shared understanding of the situation
+- Serves as a "contract" to fix the actual issue
+- Files serve as a fixture to the project
+
+Providing this with an issue description will help us help you and improve the
+chances the issue can be looked into efficiently and in a timely manner.
+
+## Before opening an issue
+
+Before opening an issue, please make sure you:
+
+- are using the latest version
+- have read the relevant documentation
+- have searched [existing issues][1]
+- have checked the list of [known issues][2]
+
+Please file only a single issue at a time, so each of them can be labeled and
+tracked separately.
+
+## Templates
+
+A convenient way to create a minimal reproduction is by starting with one of
+these templates in CodeSandbox or StackBlitz:
+
+| Template |                  |                 |
+| :------- | ---------------- | --------------- |
+| Basic    | [CodeSandbox][3] | [StackBlitz][4] |
+| Monorepo | [CodeSandbox][5] | [StackBlitz][6] |
+
+Shoutout to [CodeSandbox][7] and [StackBlitz][8] for generously providing these
+free dev containers!
+
+## Alternatives
+
+Other solutions to share a minimal and reproducible case may work well too,
+including:
+
+- A public repository on e.g. GitHub or GitLab.
+- A new [fixtures folder in the Knip repository][9].
+
+The goal is to have an easy and common understanding and reproduction. A link to
+your existing project repository will likely not be considered "minimal". Issues
+containing just a screenshot, or snippets of output or source code don't provide
+the full picture and aren't complete nor actionable.
+
+If you're unable to create a reproduction using one of the methods described
+then please clearly explain this in the issue or [contact me][10].
+
+## Pull Request
+
+The optimal way is to add fixtures and failing tests to the Knip repository, and
+open a pull request to discuss the issue! Also see [instructions for
+development][11].
+
+[1]: https://github.com/webpro-nl/knip/issues?q=is%3Aissue
+[2]: https://knip.dev/reference/known-issues
+[3]:
+  https://codesandbox.io/p/devbox/github/webpro-nl/knip/main/templates/issue-reproduction/basic
+[4]:
+  https://stackblitz.com/github/webpro-nl/knip/tree/main/templates/issue-reproduction/basic
+[5]:
+  https://codesandbox.io/p/devbox/github/webpro-nl/knip/main/templates/issue-reproduction/monorepo
+[6]:
+  https://stackblitz.com/github/webpro-nl/knip/tree/main/templates/issue-reproduction/monorepo
+[7]: https://codesandbox.io
+[8]: https://stackblitz.com
+[9]: https://github.com/webpro-nl/knip/tree/main/packages/knip/fixtures
+[10]: https://github.com/webpro
+[11]: https://github.com/webpro-nl/knip/blob/main/.github/DEVELOPMENT.md

package/docs/docs/guides/namespace-imports.md

@@ -0,0 +1,125 @@
+---
+title: Namespace Imports
+---
+
+The intention of exports used through namespace imports may not always be clear
+to Knip. Here's a guide to better understand how Knip handles such exports.
+
+## Example
+
+We start off by having two exports:
+
+```ts title="my-namespace.js"
+export const version = 'v5';
+export const getRocket = () => '🚀';
+```
+
+The next snippet shows how to import all the exports above on a namespace. All
+exports of the `my-namespace.js` module will be members on the `NS` object:
+
+```ts title="my-module.ts"
+import * as NS from './my-namespace.js';
+import send from 'stats';
+send(NS);
+```
+
+The intention of export usage is not always clear. In the example above is
+`version` or `getRocket` used? We're not sure, but we _probably_ don't want them
+to be reported as unused. The same goes for the next example:
+
+```ts title="my-module.ts"
+import * as NS from './my-namespace.js';
+
+export { NS };
+```
+
+If this all usage of the `NS` namespace object, we also don't know whether
+individual exports like `version` or `getRocket` will be used. However, if at
+least one reference to a property such as `NS.version` is found, then the
+individual exports are considered separately again and `getRocket` will be
+marked as unused:
+
+```ts title="index.ts"
+import { NS } from './my-module.js';
+
+const version = NS.version;
+```
+
+## The default heuristic
+
+Knip uses the following heuristic to determine which of the individual exports
+are used:
+
+- If there's one or more references to the import namespace object, but without
+  any property access, all exports on that namespace are considered used.
+- Otherwise, exports are considered separately.
+
+Below are a few more examples, and a way to disable this default behavior.
+
+## Examples
+
+Let's take a look at more examples:
+
+```ts title="my-namespace.ts"
+export const start = 1;
+
+export const end = 1;
+```
+
+In the following cases all exports of `my-namespace.ts` are considered used:
+
+```ts title="index.ts"
+import * as NS from './my-namespace.js';
+import send from 'stats';
+
+send(NS);
+
+const spread = { ...NS };
+
+const shorthand = { NS };
+
+const assignment = NS;
+
+const item = [NS];
+
+type TypeOf = typeof NS;
+
+Object.values(NS);
+
+for (const fruit in Fruits) {
+  //
+}
+
+export { NS };
+
+export { NS as AliasedNS };
+
+export = NS;
+```
+
+However, this is no longer the case when one of the properties is accessed:
+
+```ts title="index.js"
+import * as NS from './namespace.js';
+
+const begin = NS.start;
+
+send(NS);
+```
+
+In this case, the `end` export will be reported as unused, even though the `NS`
+object itself is referenced on its own as well.
+
+## Include `nsExports` and `nsTypes`
+
+To disable the heuristic as explained above, and enforce Knip to consider each
+export on a namespace individually, include the `nsExports` issue type:
+
+```json
+{
+  "include": ["nsExports"]
+}
+```
+
+Or use the `--include nsExports` argument from the CLI. The `nsTypes` can be
+added as well to do the same for exported types.

package/docs/docs/guides/performance.md

@@ -0,0 +1,97 @@
+---
+title: Performance
+---
+
+This page describes a few topics around Knip's performance, and how you might
+improve it.
+
+Knip does not want to tell you how to structure files or how to write your code,
+but it might still be good to understand inefficient patterns for Knip.
+
+Use the `--debug` and `--performance` flags to find potential bottlenecks.
+
+## Cache
+
+Use `--cache` to speed up consecutive runs.
+
+## Ignoring files
+
+Files matching the `ignore` patterns are not excluded from the analysis. They're
+just not printed in the report. Use negated `entry` and `project` patterns to
+exclude files from the analysis.
+
+Read [configuring project files][1] for details and examples. Improving
+configuration may have a significant impact on performance.
+
+## Workspace sharing
+
+Knip shares files from separate workspaces if the configuration in
+`tsconfig.json` allows this. This aims to reduce memory consumption and run
+duration. Relevant compiler options include `baseUrl`, `paths` and
+`moduleResolution`.
+
+With the `--debug` flag you can see how many programs Knip uses. Look for
+messages like this:
+
+```sh
+...
+[*] Installed 2 programs for 29 workspaces
+...
+[*] Analyzing used resolved files [P1/1] (123)
+...
+[*] Analyzing used resolved files [P1/2] (8)
+...
+[*] Analyzing used resolved files [P2/1] (41)
+...
+```
+
+The first number in `P1/1` is the number of the programs, the second number
+indicates additional entry files were found so it does another round of analysis
+on those files.
+
+Use [--isolate-workspaces][2] to disable this behavior. This is usually not
+necessary, but more of an escape hatch in cases with memory usage issues or
+incompatible `compilerOptions` across workspaces. Workspaces are analyzed
+sequentially to spread out memory usage more evenly, which may prevent crashes
+on large monorepos.
+
+## Language Service
+
+Knip does not install the TypeScript Language Service (LS) by default. This is
+expensive, as TypeScript needs to set up symbols and caching for the rather slow
+`findReferences` function.
+
+There are two cases that enforce Knip to install the LS.
+
+### 1. Class members
+
+The `findReferences` function is used to find unused members of imported classes
+(i.e. when the issue type `classMembers` is included).
+
+### 2. Include external type definitions
+
+When [`--include-libs`][3] is enabled, Knip enables loading type definitions of
+external dependencies. This will also install the LS to access its
+`findReferences` function. It acts as an extra line of defense: only exports
+that weren't referenced to during default procedure go through this.
+
+## Metrics
+
+Use [the `--performance` flag][4] to see how many times potentially expensive
+functions (e.g. `findReferences`) are invoked and how much time is spent in
+those functions. Example usage:
+
+```sh
+knip --include classMembers --performance
+```
+
+## A last resort
+
+In case Knip is unbearably slow (or even crashes), you could resort to [lint
+individual workspaces][5].
+
+[1]: ./configuring-project-files.md
+[2]: ../reference/cli.md#--isolate-workspaces
+[3]: ../guides/handling-issues.mdx#external-libraries
+[4]: ../reference/cli.md#--performance
+[5]: ../features/monorepos-and-workspaces.md#lint-a-single-workspace

package/docs/docs/guides/troubleshooting.md

@@ -0,0 +1,136 @@
+---
+title: Troubleshooting
+sidebar:
+  order: 2
+---
+
+We can distinguish two types of issues:
+
+- [Lint issues reported by Knip][1]
+- [Exceptions thrown by Knip][2]
+
+Also see the [debug][3] and [trace][4] options below that can help to
+troubleshoot issues.
+
+:::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.
+
+Knip is intentionally strict to maximize its potential. It may initially report
+many unused files. However, getting this right will result in great reports and
+tidy codebases.
+
+If it doesn't come your way at the first try, remember that often only a small
+change go a long way towards success.
+
+:::
+
+## Lint issues reported by Knip
+
+Knip reports lint issues in your codebase. See [handling issues][5] to deal with
+the reported issues.
+
+If Knip reports false positives and you're considering filing a GitHub issue,
+please do! It'll make Knip better for everyone. Please read [issue
+reproduction][6] first.
+
+Exit code 1 indicates a successful run, but lint issues were found.
+
+## Exceptions thrown by Knip
+
+Knip may throw an exception, resulting in an unsuccessful run.
+
+See [known issues][7] as it may be listed there and a workaround may be
+available. If it isn't clear what's throwing the exception, try another run with
+`--debug` to locate the cause of the issue with more details.
+
+If Knip throws an exception and you're considering filing a GitHub issue, please
+do! It'll make Knip better for everyone. Please read [issue reproduction][6]
+first.
+
+Exit code 2 indicates an exception was thrown by Knip.
+
+## Debug
+
+To better understand why Knip reports what it does, run it in debug mode by
+adding `--debug` to the command:
+
+```sh
+knip --debug
+```
+
+This will give a lengthy output, including:
+
+- Included workspaces
+- Used configuration per workspace
+- Enabled plugins per workspace
+- Glob patterns and options followed by matching file paths
+- Plugin config file paths and found dependencies per plugin
+- Compiled non-standard source files
+
+## Trace
+
+Use `--trace` to see where exports or dependencies are used:
+
+- Use `--trace-file [path]` to output this only for the given file.
+- Use `--trace-export [name]` to output this only for the given export name.
+- Use `--trace-dependency [name]` to find where a dependency is imported
+- Use both to trace a specific named or default export of a certain file.
+
+This works across re-exports, barrel files and workspaces. Here's an example
+screenshot:
+
+<img src="/screenshots/trace-export.png" alt="trace export" class="mw500" />
+
+It's like a reversed module graph. Instead of traversing imports it goes in the
+opposite direction and shows where exports are imported.
+
+The `--trace-dependency` accepts strings for exact matches, but if it looks like
+a regex that works too:
+
+<img src="/screenshots/trace-dependency.png" alt="trace dependency" class="mw500" />
+
+Use [--workspace \[dir\]][8] to filter accordingly.
+
+#### Legend
+
+|     | Description                                 |
+| --- | :------------------------------------------ |
+| `✓` | Contains import and reference to the export |
+| `x` | Is not imported                             |
+| `◯` | Entry file                                  |
+
+## Opening an issue
+
+If you want to open an issue, please see [issue reproduction][6].
+
+## Understanding Knip
+
+Looking to better understand how Knip works? The [entry files][9] and
+[plugins][10] explanations cover two core concepts. After this you might want to
+check out features like [production mode][11] and [monorepos & workspaces][12].
+
+In a more general sense, [Why use Knip?][13] explains what Knip can do for you.
+
+## Asking for help
+
+If you can't find your answer in any of the aforementioned resources, feel free
+to [open an issue on GitHub][14].
+
+[1]: #lint-issues-reported-by-knip
+[2]: #exceptions-thrown-by-knip
+[3]: #debug
+[4]: #trace
+[5]: ../guides/handling-issues.md
+[6]: ./issue-reproduction.md
+[7]: ../reference/known-issues.md
+[8]: ../reference/cli.md#--workspace-dir
+[9]: ../explanations/entry-files.md
+[10]: ../explanations/plugins.md
+[11]: ../features/production-mode.md
+[12]: ../features/monorepos-and-workspaces.md
+[13]: ../explanations/why-use-knip.md
+[14]: https://github.com/webpro-nl/knip/issues

package/docs/docs/guides/using-knip-in-ci.md

@@ -0,0 +1,54 @@
+---
+title: Using Knip in CI
+---
+
+Knip is your companion during local development. But it is even more valuable in
+a continuous integration (CI) environment to prevent regressions over time. Knip
+will notify you of unused dependencies, exports and files if you forgot to
+remove them.
+
+Knip will exit the process with code `1` if there are one or more issues.
+
+## GitHub Actions
+
+Here's an example workflow configuration for GitHub Actions:
+
+```yaml
+name: Lint project
+
+on: push
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Ubuntu/Node v20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+      - name: Run knip
+        run: npm run knip
+```
+
+## Notes
+
+In CI environments, the [--no-progress][1] flag is set automatically.
+
+## Related features
+
+- [--cache][2]
+- [--max-issues][3]
+- [--no-exit-code][4]
+- [--reporter][5]
+
+## Related reading
+
+- [Why use Knip?][6]
+
+[1]: ../reference/cli.md#--no-progress
+[2]: ../reference/cli.md#--cache
+[3]: ../reference/cli.md#--max-issues
+[4]: ../reference/cli.md#--no-exit-code
+[5]: ../reference/cli.md#--reporter-reporter
+[6]: ../explanations/why-use-knip.md

package/docs/docs/guides/working-with-commonjs.md

@@ -0,0 +1,72 @@
+---
+title: Working with CommonJS
+---
+
+CommonJS is the JavaScript module system using `require()` and `module.exports`
+statements.
+
+Knip works well with CommonJS. You don't need to use ES Modules or a
+`tsconfig.json` to use Knip.
+
+The dynamic nature of CommonJS leaves room for ambiguity: it's sometimes unclear
+whether an export is a default or a named export (and thus how it should be
+imported). So we'll have to agree on a few conventions to prevent false
+positives. Those conventions are designed to minimize impact on existing
+codebases, improve consistency, and ease migration to ES Modules or TypeScript.
+
+For **named exports**, the recommendation is to assign keys to `module.exports`:
+
+```js
+const B = function () {};
+
+module.exports.A = { option: true };
+module.exports.B = B;
+```
+
+Alternatively, assign an object with ONLY shorthand property assignments to
+`module.exports`:
+
+```js
+const A = function () {};
+const B = { option: true };
+
+module.exports = { A, B };
+```
+
+Anything else assigned to `module.exports` is considered a default export, and
+should be imported as such.
+
+The following **default import** of the **named exports** above will result in
+all those exports reported as unused, even when referenced like below:
+
+```js
+const DefaultImport = require('./common.js');
+const runtime = [DefaultImport.A, DefaultImport.B];
+```
+
+Instead, do this:
+
+```js
+const { A, B } = require('./common.js');
+const runtime = [A, B];
+```
+
+Not recommended per se, but the following import syntax also results in the
+named export `A` being used:
+
+```js
+const runtime = [require('./common.js').A];
+```
+
+Add a non-shorthand property to turn the named object notation into a single
+**default export**:
+
+```js
+const A = function () {};
+const B = { option: true };
+
+module.exports = { __esModule: true, A, B };
+```
+
+The `__esModule` key could be named differently (but makes sense given it's an
+informal "CJS/ESM interop" standard amongst compilers and bundlers).