@knip/mcp 0.0.1

package/docs/explanations/why-use-knip.md

@@ -0,0 +1,128 @@
+---
+title: Why use Knip?
+sidebar:
+  order: 3
+---
+
+The value of removing clutter is clear, but finding it manually is tedious. This
+is where Knip comes in: comprehensive and accurate results at any scale.
+
+:::tip[TL;DR]
+
+Knip finds and fixes unused dependencies, exports and files.
+
+Deep analysis from [fine-grained entry points][1] based on the actual frameworks
+and tooling in [(mono)repos][2] for accurate and actionable results. Advanced
+features for maximum coverage:
+
+- [Custom module resolution][3]
+- [Configuration file parsers][4]
+- [Advanced shell script parser][5]
+- [Built-in and custom compilers][6]
+- [Auto-fix most issues][7]
+
+:::
+
+## Less is more
+
+There are plenty of reasons to delete unused files, dependencies and "dead
+code":
+
+- Easier maintenance: things are easier to manage when there's less of it.
+- Improved performance: startup time, build time and/or bundle size can be
+  negatively impacted when unused code, files and/or dependencies are included.
+  Relying on tree-shaking when bundling code helps, but it's not a silver
+  bullet.
+- Easier onboarding: there should be no doubts about whether files, dependencies
+  and exports are actually in use or not. Especially for people new to the
+  project and/or taking over responsibilities this is harder to grasp.
+- Prevent regressions: tools like TypeScript, ESLint and Prettier do all sorts
+  of checks and linting to report violations and prevent regressions. Knip does
+  the same for dependencies, exports and files that are obsolete.
+- Keeping dead code around has a negative value on readability, as it can be
+  misleading and distracting. Even if it serves no purpose it will need to be
+  maintained (source: [Safe dead code removal → YAGNI][8]).
+- Also see [Why are unused dependencies a problem?][9] and [Why are unused
+  exports a problem?][10].
+
+## Automation
+
+Code and dependency management is usually not the most exciting task for most of
+us. Knip's mission is to automate finding clutter. This is such a tedious job if
+you were to do it manually, and where would you even start? Knip applies many
+techniques and heuristics to report what you need and save a lot of time.
+
+:::tip
+
+Knip not only finds clutter, it can also [remove clutter][7]!
+
+Use Knip next to a linter like ESLint or Biome: after removing unused variables
+inside files, Knip might find even more unused code. Rinse and repeat!
+
+:::
+
+## Comprehensive
+
+You can use alternative tools that do the same. However, the advantage of a
+strategy that addresses all of dependencies, exports and files is in their
+synergy:
+
+- Utilizing plugins to find their dependencies includes the capacity to find
+  additional entry and configuration files. This results in more resolved and
+  used files. Better coverage gives better insights into unused files and
+  exports.
+- Analyzing more files reveals more unused exports and dependency usage,
+  refining the list of both unused and unlisted dependencies.
+- This approach is amplified in a monorepo setting. In fact, files and internal
+  dependencies can recursively reference each other (across workspaces).
+
+## Greenfield or Legacy
+
+Installing Knip in greenfield projects ensures the project stays neat and tidy
+from the start. Add it to your CI workflow and prevent any regressions from
+entering the codebase.
+
+:::tip
+
+Use Knip in a CI environment to prevent future regressions.
+
+:::
+
+In large and/or legacy projects, Knip may report false positives and require
+some configuration. It aims to be a great assistant when cleaning up parts of
+the project or doing large refactors. Even a list of results with a few false
+positives is many times better and faster than if you were to do it manually.
+
+## Unobtrusive
+
+Knip does not introduce new syntax for you to learn. This may sound obvious, but
+consider comments like the following:
+
+```js
+// eslint-disable-next-line
+// prettier-ignore
+// @ts-expect-error
+```
+
+Maybe you wonder why Knip does not have similar comments like `// knip-ignore`
+so you can get rid of false positives? A variety of reasons:
+
+1. A false positive may be a bug in Knip, and should be reported, not dismissed.
+2. Instead of proprietary comments, use [standardized annotations][11] that also
+   serve as documentation.
+3. In the event you want to remove Knip, just uninstall `knip` without having to
+   remove useless comments scattered throughout the codebase.
+
+Tip: use `@lintignore` in JSDoc comments, so other linters can use the same.
+
+[1]: ./entry-files.md
+[2]: ../features/monorepos-and-workspaces.md
+[3]: ../reference/faq.md#why-doesnt-knip-use-an-existing-module-resolver
+[4]: ./plugins.md#configuration-files
+[5]: ../features/script-parser.md
+[6]: ../features/compilers.md
+[7]: ../features/auto-fix.mdx
+[8]: https://jfmengels.net/safe-dead-code-removal/#yagni-you-arent-gonna-need-it
+[9]: ../typescript/unused-dependencies.md#why-are-unused-dependencies-a-problem
+[10]: ../typescript/unused-exports.md#why-are-unused-exports-a-problem
+[11]: ../reference/jsdoc-tsdoc-tags.md

package/docs/features/auto-fix.mdx

@@ -0,0 +1,333 @@
+---
+title: Auto-fix
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { Badge } from '@astrojs/starlight/components';
+
+Run Knip as you normally would, and if the report looks good then run it again
+with the `--fix` flag to let Knip automatically apply fixes. It fixes the
+following [issue types][1]:
+
+- Remove `export` keyword for unused exports and exported types
+- Remove `export default` keywords for unused default exports
+- Remove exports, re-exports and exported types
+- Remove unused enum members
+- Remove unused class members (disabled by default)
+- Remove unused `dependencies` and `devDependencies` from `package.json`
+- Remove unused files
+
+:::caution
+
+Use a VCS (version control system) like Git to review and undo changes as
+necessary.
+
+:::
+
+## Flags
+
+### Fix
+
+Add the `--fix` flag to remove unused exports and dependencies:
+
+```sh
+knip --fix
+```
+
+Add `--allow-remove-files` to allow Knip to remove unused files:
+
+```sh
+knip --fix --allow-remove-files
+```
+
+Use `--fix-type` to fix only specific issue types:
+
+- `files`
+- `exports`
+- `types`
+- `dependencies`
+- `catalog`
+
+Example:
+
+```sh
+knip --fix-type exports,types
+knip --fix-type exports --fix-type types   # same as above
+```
+
+### Format
+
+Add `--format` to format the modified files using the formatter and
+configuration in your project. Supports Biome, deno fmt, dprint and Prettier
+(using [Formatly][2]):
+
+```sh
+knip --fix --format
+```
+
+## Demo
+
+<video controls width="500">
+  <source src="/screenshots/fix.mp4" type="video/mp4" />
+
+  <source src="/screenshots/fix.webm" type="video/webm" />
+</video>
+
+## Post-fix
+
+After Knip has fixed issues, there are four things to consider:
+
+### 1. Use a formatter
+
+Use a tool like Prettier or Biome if the code needs formatting. Knip removes the
+minimum amount of code while leaving it in a working state.
+
+:::tip
+
+Add the `--format` flag to format the modified files using the formatter and
+configuration in your project.
+
+:::
+
+### 2. Unused variables
+
+Use a tool like ESLint or Biome to find and remove unused variables inside
+files. Even better, try [remove-unused-vars][3] to remove unused variables
+within files.
+
+This may result in more deleted code, and Knip may then find more unused code.
+Rinse and repeat!
+
+### 3. Unused dependencies
+
+Verify changes in `package.json` and update dependencies using your package
+manager.
+
+<Tabs syncKey="pm">
+  <TabItem label="npm">
+    ```shell
+    npm install
+    ```
+  </TabItem>
+
+  <TabItem label="pnpm">
+    ```shell
+    pnpm install
+    ```
+  </TabItem>
+
+  <TabItem label="bun">
+    ```shell
+    bun install
+    ```
+  </TabItem>
+
+  <TabItem label="yarn">
+    ```shell
+    yarn
+    ```
+  </TabItem>
+</Tabs>
+
+### 4. Install unlisted dependencies
+
+If Knip reports unlisted dependencies or binaries, they should be installed
+using the package manager in the project, for example:
+
+<Tabs syncKey="pm">
+  <TabItem label="npm">
+    ```shell
+    npm install unlisted-package
+    ```
+  </TabItem>
+
+  <TabItem label="pnpm">
+    ```shell
+    pnpm add unlisted-package
+    ```
+  </TabItem>
+
+  <TabItem label="bun">
+    ```shell
+    bun add unlisted-package
+    ```
+  </TabItem>
+
+  <TabItem label="yarn">
+    ```shell
+    yarn add unlisted-package
+    ```
+  </TabItem>
+</Tabs>
+
+## Example results
+
+### Exports
+
+The `export` keyword for unused exports is removed:
+
+```diff title="module.ts"
+-export const unused = 1;
+-export default class MyClass {}
++const unused = 1;
++class MyClass {}
+```
+
+The `default` keyword was also removed here.
+
+Knip removes the whole or part of export declarations:
+
+```diff title="module.ts"
+type Snake = 'python' | 'anaconda';
+const Owl = 'Hedwig';
+const Hawk = 'Tony';
+-export type { Snake };
+-export { Owl, Hawk };
++;
++;
+```
+
+### Re-exports
+
+Knip removes the whole or part of re-exports:
+
+```diff title="file.js"
+-export { Cat, Dog } from './pets';
+-export { Lion, Elephant } from './jungle';
++export { Elephant } from './jungle'
+```
+
+Also across any chain of re-exports:
+
+<Tabs>
+  <TabItem label="module.ts">
+    ```diff
+    export const Hawk = 'Tony';
+    -export const Owl = 'Hedwig';
+    +const Owl = 'Hedwig';
+    ```
+  </TabItem>
+
+  <TabItem label="barrel.ts">
+    ```diff
+    export * from './module.js';
+    ```
+  </TabItem>
+
+  <TabItem label="index.ts">
+    ```diff
+    -export { Hawk, Owl } from './barrel.js';
+    +export { Hawk } from './barrel.js'
+    ```
+  </TabItem>
+</Tabs>
+
+### Export assignments
+
+Knip removes individual exported items in "export assignments", but does not
+remove the entire export declaration if it's empty:
+
+```diff title="file.js"
+-export const { a, b  } = fn();
++export const {   } = fn();
+
+-export const [c, d] = [c, d];
++export const [, ] = [c, d];
+```
+
+Reason: the right-hand side of the assignment might have side-effects. It's not
+safe to always remove the whole declaration. This could be improved in the
+future (feel free to open an issue/RFC).
+
+### Enum members
+
+Unused members of enums are removed:
+
+```diff title="file.ts"
+export enum Directions {
+  North = 1,
+  East = 2,
+-  South = 3,
+  West = 4,
+}
+```
+
+### CommonJS
+
+Knip supports CommonJS and removes unused exports:
+
+```diff title="common.js"
+-module.exports = { identifier, unused };
++module.exports = { identifier,  };
+
+-module.exports.UNUSED = 1;
+-module.exports['ACCESS'] = 1;
++
++
+```
+
+Warning: the right-hand side of such an assignment might have side-effects. Knip
+currently removes the whole declaration (feel free to open an issue/RFC).
+
+### Dependencies
+
+Unused dependencies are removed from `package.json`:
+
+```diff title="package.json"
+ {
+   "name": "my-package",
+   "dependencies": {
+-    "rimraf": "*",
+-    "unused-dependency": "*"
++    "rimraf": "*"
+   },
+-  "devDependencies": {
+-    "unreferenced-package": "5.3.3"
+-  }
++  "devDependencies": {}
+ }
+```
+
+### Class members   <Badge text="experimental" variant="caution" />
+
+Unused members of classes can be removed:
+
+```diff title="file.ts"
+export class Rectangle {
+  constructor(public width: number, public height: number) {}
+
+-  static Key = 1;
++
+
+  area() {
+    return this.width * this.height;
+  }
+
+-  public get unusedGetter(): string {
+-    return 'unusedGetter';
+-  }
+}
+```
+
+Currently Knip might be too eager removing class members when they're not
+referenced internally but meant to be called by an external library. For
+instance, Knip might think `componentDidMount` and `render` in React class
+component are unused and will remove those.
+
+Note that [`classMembers` aren't included by default][4].
+
+## What's not included
+
+Operations that auto-fix does not (yet) perform and why:
+
+- Add unlisted (dev) dependencies to `package.json` (should it go into
+  `dependencies` or `devDependencies`? For monorepos in current workspace or
+  root?)
+- Add unlisted binaries (which package and package version contains the used
+  binary?)
+- Fix duplicate exports (which one should be removed?)
+
+[1]: ../reference/issue-types.md
+[2]: https://github.com/JoshuaKGoldberg/formatly
+[3]: https://github.com/webpro-nl/remove-unused-vars
+[4]: ../guides/handling-issues.mdx#class-members

package/docs/features/compilers.md

@@ -0,0 +1,172 @@
+---
+title: Compilers
+---
+
+Projects may have source files that are not JavaScript or TypeScript, and thus
+require compilation (or transpilation, or pre-processing, you name it). Files
+like `.mdx`, `.astro`, `.vue` and `.svelte` may also import other source files
+and external dependencies. So ideally, these files are included when linting the
+project. That's why Knip supports compilers.
+
+## Built-in compilers
+
+Knip has built-in "compilers" for the following file extensions:
+
+- `.astro`
+- `.css` (only enabled by `tailwindcss`)
+- `.mdx`
+- `.prisma`
+- `.sass` + `.scss`
+- `.svelte`
+- `.vue`
+
+Knip does not include real compilers for those files, but regular expressions to
+collect `import` statements. This is fast, requires no dependencies, and enough
+for Knip to build the module graph.
+
+On the other hand, real compilers may expose their own challenges in the context
+of Knip. For instance, the Svelte compiler keeps `exports` intact, while they
+might represent component properties. This results in those exports being
+reported as unused by Knip.
+
+The built-in functions seem to do a decent job, but override them however you
+like.
+
+Compilers are enabled only if certain dependencies are found. If that's not
+working for your project, set `true` and enable any compiler manually:
+
+```ts title="knip.ts"
+export default {
+  compilers: {
+    mdx: true,
+  },
+};
+```
+
+## Custom compilers
+
+Built-in compilers can be overridden, and additional compilers can be added.
+Since compilers are functions, the Knip configuration file must be a dynamic
+`.js` or `.ts` file.
+
+### Interface
+
+The compiler function interface is straightforward. Text in, text out:
+
+```ts
+(source: string, filename: string) => string;
+```
+
+This may also be an `async` function.
+
+:::tip[Note]
+
+Compilers will automatically have their extension added as a default extension
+to Knip. This means you don't need to add something like `**/*.{ts,vue}` to the
+`entry` or `project` file patterns manually.
+
+:::
+
+### Examples
+
+- [CSS][1]
+- [MDX][2]
+- [Svelte][3]
+- [Vue][4]
+
+#### CSS
+
+Here's an example, minimal compiler for CSS files:
+
+```ts title="knip.ts"
+export default {
+  compilers: {
+    css: (text: string) => [...text.matchAll(/(?<=@)import[^;]+/g)].join('\n'),
+  },
+};
+```
+
+You may wonder why the CSS compiler is not included by default. It's currently
+not clear if it should be included. And if so, what would be the best way to
+determine it should be enabled, and what syntax(es) it should support. Note that
+Tailwind CSS and SASS/SCSS compilers are included.
+
+#### MDX
+
+Another example, in case the built-in MDX compiler is not enough:
+
+```ts
+import { compile } from '@mdx-js/mdx';
+
+export default {
+  compilers: {
+    mdx: async text => (await compile(text)).toString(),
+  },
+};
+```
+
+#### Svelte
+
+In a Svelte project, the compiler is automatically enabled. Override and use
+Svelte's compiler for better results if the built-in "compiler" is not enough:
+
+```ts
+import type { KnipConfig } from 'knip';
+import { compile } from 'svelte/compiler';
+
+export default {
+  compilers: {
+    svelte: (source: string) => compile(source, {}).js.code,
+  },
+} satisfies KnipConfig;
+```
+
+#### Vue
+
+In a Vue project, the compiler is automatically enabled. Override and use Vue's
+parser for better results if the built-in "compiler" is not enough:
+
+```ts
+import type { KnipConfig } from 'knip';
+import {
+  parse,
+  type SFCScriptBlock,
+  type SFCStyleBlock,
+} from 'vue/compiler-sfc';
+
+function getScriptBlockContent(block: SFCScriptBlock | null): string[] {
+  if (!block) return [];
+  if (block.src) return [`import '${block.src}'`];
+  return [block.content];
+}
+
+function getStyleBlockContent(block: SFCStyleBlock | null): string[] {
+  if (!block) return [];
+  if (block.src) return [`@import '${block.src}';`];
+  return [block.content];
+}
+
+function getStyleImports(content: string): string {
+  return [...content.matchAll(/(?<=@)import[^;]+/g)].join('\n');
+}
+
+const config = {
+  compilers: {
+    vue: (text: string, filename: string) => {
+      const { descriptor } = parse(text, { filename, sourceMap: false });
+      return [
+        ...getScriptBlockContent(descriptor.script),
+        ...getScriptBlockContent(descriptor.scriptSetup),
+        ...descriptor.styles.flatMap(getStyleBlockContent).map(getStyleImports),
+      ].join('\n');
+    },
+  },
+} satisfies KnipConfig;
+
+export default config;
+```
+
+[1]: #css
+[2]: #mdx
+[3]: #svelte
+[4]: #vue

package/docs/features/integrated-monorepos.md

@@ -0,0 +1,52 @@
+---
+title: Integrated Monorepos
+sidebar:
+  order: 3
+---
+
+Some repositories have a single `package.json`, but consist of multiple projects
+with configuration files across the repository. A good example is the [Nx
+integrated monorepo style][1].
+
+:::tip
+
+An integrated monorepo is a single workspace.
+
+:::
+
+## Entry Files
+
+The default entrypoints files might not be enough. Here's an idea that might fit
+this type of monorepo:
+
+```json title="knip.json"
+{
+  "entry": ["{apps,libs}/**/src/index.{ts,tsx}"],
+  "project": ["{apps,libs}/**/src/**/*.{ts,tsx}"]
+}
+```
+
+## Plugins
+
+Let's assume some of these projects are applications ("apps") which have their
+own ESLint configuration files and Cypress configuration and test files. This
+may result in those files getting reported as unused, and consequently also the
+dependencies they import and refer to.
+
+In that case, we could configure the ESLint and Cypress plugins like this:
+
+```json title="knip.json"
+{
+  "eslint": {
+    "config": ["{apps,libs}/**/.eslintrc.json"]
+  },
+  "cypress": {
+    "entry": ["apps/**/cypress.config.ts", "apps/**/cypress/e2e/*.spec.ts"]
+  }
+}
+```
+
+Adapt the file patterns to your project, and the relevant `config` and `entry`
+files and dependencies should no longer be reported as unused.
+
+[1]: https://nx.dev/getting-started/tutorials/integrated-repo-tutorial