@knip/mcp 0.0.4 → 0.0.5

package/docs/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/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/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

package/docs/docs/features/monorepos-and-workspaces.md

@@ -0,0 +1,134 @@
+---
+title: Monorepos & Workspaces
+sidebar:
+  order: 2
+---
+
+Workspaces are handled out-of-the-box by Knip.
+
+Workspaces are sometimes also referred to as package-based monorepos, or as
+packages in a monorepo. Knip uses the term workspace exclusively to indicate a
+directory that has a `package.json`.
+
+## Configuration
+
+Here's example configuration with custom `entry` and `project` patterns:
+
+```json title="knip.json"
+{
+  "workspaces": {
+    ".": {
+      "entry": "scripts/*.js",
+      "project": "scripts/**/*.js"
+    },
+    "packages/*": {
+      "entry": "{index,cli}.ts",
+      "project": "**/*.ts"
+    },
+    "packages/cli": {
+      "entry": "bin/cli.js"
+    }
+  }
+}
+```
+
+:::tip
+
+Run Knip without any configuration to see if and where custom `entry` and/or
+`project` files are necessary per workspace.
+
+:::
+
+Each workspace has the same [default configuration][1].
+
+The root workspace is named `"."` under `workspaces` (like in the example
+above).
+
+:::caution
+
+In a project with workspaces, the `entry` and `project` options at the root
+level are ignored. Use the workspace named `"."` for those (like in the example
+above).
+
+:::
+
+## Workspaces
+
+Knip reads workspaces from four possible locations:
+
+1. The `workspaces` array in `package.json` (npm, Bun, Yarn, Lerna)
+2. The `packages` array in `pnpm-workspace.yaml` (pnpm)
+3. The `workspaces.packages` array in `package.json` (legacy)
+4. The `workspaces` object in Knip configuration
+
+The `workspaces` in Knip configuration (4) not already defined in the root
+`package.json` or `pnpm-workspace.yaml` (1, 2, 3) are added to the analysis.
+
+:::caution
+
+A workspace must have a `package.json` file.
+
+:::
+
+For projects with only a root `package.json`, please see [integrated
+monorepos][2].
+
+## Additional workspaces
+
+If a workspaces is not configured as such in `package.json#workspaces` (or
+`pnpm-workspace.yaml`) it can be added to the Knip configuration manually. Add
+their path to the `workspaces` configuration object the same way as
+`"packages/cli": {}` in the example above.
+
+## Source mapping
+
+See [Source Mapping][3].
+
+## Additional options
+
+The following options are available inside workspace configurations:
+
+- [ignore][4]
+- [ignoreBinaries][5]
+- [ignoreDependencies][6]
+- [ignoreMembers][7]
+- [ignoreUnresolved][8]
+- [includeEntryExports][9]
+
+[Plugins][10] can be configured separately per workspace.
+
+Use `--debug` for verbose output and see the workspaces Knip includes, their
+configurations, enabled plugins, glob options and resolved files.
+
+## Lint a single workspace
+
+Use the `--workspace` (or `-W`) argument to focus on a single workspace (and let
+Knip run faster). Example:
+
+```sh
+knip --workspace packages/my-lib
+```
+
+This will include the target workspace, but also ancestor and dependent
+workspaces. For two reasons:
+
+- Ancestor workspaces may list dependencies in `package.json` the linted
+  workspace uses.
+- Dependent workspaces may reference exports from the linted workspace.
+
+To lint the workspace in isolation, there are two options:
+
+- Combine the `workspace` argument with [strict production mode][11].
+- Run Knip from inside the workspace directory.
+
+[1]: ../overview/configuration.md#defaults
+[2]: ./integrated-monorepos.md
+[3]: ./source-mapping.md
+[4]: ../reference/configuration.md#ignore
+[5]: ../reference/configuration.md#ignorebinaries
+[6]: ../reference/configuration.md#ignoredependencies
+[7]: ../reference/configuration.md#ignoremembers
+[8]: ../reference/configuration.md#ignoreunresolved
+[9]: ../reference/configuration.md#includeentryexports
+[10]: ../reference/configuration.md#plugins
+[11]: ./production-mode.md#strict-mode