@knip/mcp 0.0.1

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

package/docs/features/production-mode.md

@@ -0,0 +1,95 @@
+---
+title: Production Mode
+sidebar:
+  order: 1
+---
+
+The default mode for Knip is comprehensive and targets all project code,
+including configuration files, test files, Storybook stories, and so on. Test
+files usually import production files. This prevents production files or their
+exports from being reported as unused, while sometimes both of them can be
+deleted. Knip features a "production mode" to focus only on the code that you
+ship.
+
+## Configuration
+
+To tell Knip what is production code, add an exclamation mark behind each
+`pattern!` that represents production code:
+
+```json title="knip.json"
+{
+  "entry": ["src/index.ts!", "build/script.js"],
+  "project": ["src/**/*.ts!", "build/*.js"]
+}
+```
+
+Depending on file structure and enabled plugins, you might not need to modify
+your configuration at all.
+
+Run Knip with the `--production` flag:
+
+```sh
+knip --production
+```
+
+Here's what's included in production mode:
+
+- Only `entry` and `project` patterns suffixed with `!`
+- Only production `entry` file patterns exported by plugins (such as Next.js and
+  Remix)
+- Only the `start` and `postinstall` scripts
+- Ignore exports with the [`@internal` tag][1]
+
+:::note
+
+The production run does not replace the default run. Depending on your needs you
+can run either of them or both separately. Usually both modes can share the same
+configuration.
+
+:::
+
+To see the difference between default and production mode in great detail, use
+the `--debug` flag and inspect what entry and project files are used, and the
+plugins that are enabled. For instance, in production mode this shows that files
+such as tests and Storybook files (stories) are excluded from the analysis.
+
+In case files like mocks and test helpers are reported as unused files, use
+negated patterns to exclude those files in production mode:
+
+```json title="knip.json"
+{
+  "entry": ["src/index.ts!"],
+  "project": ["src/**/*.ts!", "!src/test-helpers/**!"]
+}
+```
+
+Also see [configuring project files][2] to align `entry` and `project` with
+production mode.
+
+## Strict Mode
+
+In production mode, only `dependencies` (not `devDependencies`) are considered
+when finding unused or unlisted dependencies.
+
+Additionally, the `--strict` flag can be added to:
+
+- Verify isolation: workspaces should use strictly their own `dependencies`
+- Include `peerDependencies` when finding unused or unlisted dependencies
+- Report type-only imports listed in `dependencies`
+
+```sh
+knip --production --strict
+```
+
+Using `--strict` implies `--production`, so the latter can be omitted.
+
+## Types
+
+Add `--exclude types` if you don't want to include types in the report:
+
+```sh
+knip --production --exclude types
+```
+
+[1]: ../reference/jsdoc-tsdoc-tags.md#internal
+[2]: ../guides/configuring-project-files.md

package/docs/features/reporters.md

@@ -0,0 +1,302 @@
+---
+title: Reporters & Preprocessors
+---
+
+## Built-in Reporters
+
+Knip provides the following built-in reporters:
+
+- `codeowners`
+- `compact`
+- [`disclosure`][1]
+- [`github-actions`][2]
+- [`json`][3]
+- [`markdown`][4]
+- [`codeclimate`][5]
+- `symbols` (default)
+
+Example usage:
+
+```sh
+knip --reporter compact
+```
+
+### JSON
+
+The built-in `json` reporter output is meant to be consumed by other tools. It
+reports in JSON format with unused `files` and `issues` as an array with one
+object per file structured like this:
+
+```json
+{
+  "files": ["src/unused.ts"],
+  "issues": [
+    {
+      "file": "package.json",
+      "owners": ["@org/admin"],
+      "dependencies": [{ "name": "jquery", "line": 5, "col": 6, "pos": 71 }],
+      "devDependencies": [{ "name": "lodash", "line": 9, "col": 6, "pos": 99 }],
+      "unlisted": [{ "name": "react" }, { "name": "@org/unresolved" }],
+      "exports": [],
+      "types": [],
+      "duplicates": []
+    },
+    {
+      "file": "src/Registration.tsx",
+      "owners": ["@org/owner"],
+      "dependencies": [],
+      "devDependencies": [],
+      "binaries": [],
+      "unresolved": [
+        { "name": "./unresolved", "line": 8, "col": 23, "pos": 407 }
+      ],
+      "exports": [{ "name": "unusedExport", "line": 1, "col": 14, "pos": 13 }],
+      "types": [
+        { "name": "unusedEnum", "line": 3, "col": 13, "pos": 71 },
+        { "name": "unusedType", "line": 8, "col": 14, "pos": 145 }
+      ],
+      "enumMembers": {
+        "MyEnum": [
+          { "name": "unusedMember", "line": 13, "col": 3, "pos": 167 },
+          { "name": "unusedKey", "line": 15, "col": 3, "pos": 205 }
+        ]
+      },
+      "classMembers": {
+        "MyClass": [
+          { "name": "unusedMember", "line": 40, "col": 3, "pos": 687 },
+          { "name": "unusedSetter", "line": 61, "col": 14, "pos": 1071 }
+        ]
+      },
+      "duplicates": ["Registration", "default"]
+    }
+  ]
+}
+```
+
+The keys match the [reported issue types][6]. Example usage:
+
+```sh
+knip --reporter json
+```
+
+### Github Actions
+
+TODO
+
+Example usage:
+
+```sh
+knip --reporter github-actions
+```
+
+### Markdown
+
+The built-in `markdown` reporter output is meant to be saved to a Markdown file.
+This allows following the changes in issues over time. It reports issues in
+Markdown tables separated by issue types as headings, for example:
+
+```md
+# Knip report
+
+## Unused files (1)
+
+- src/unused.ts
+
+## Unlisted dependencies (2)
+
+| Name            | Location          | Severity |
+| :-------------- | :---------------- | :------- |
+| unresolved      | src/index.ts:8:23 | error    |
+| @org/unresolved | src/index.ts:9:23 | error    |
+
+## Unresolved imports (1)
+
+| Name         | Location           | Severity |
+| :----------- | :----------------- | :------- |
+| ./unresolved | src/index.ts:10:12 | error    |
+```
+
+### Disclosure
+
+This reporter is useful for sharing large reports. Groups of issues are rendered
+in a closed state initially. The reporter renders this:
+
+````text
+$ knip --reporter disclosure
+
+<details>
+<summary>Unused files (2)</summary>
+
+```
+unused.ts
+dangling.js
+```
+
+</details>
+
+<details>
+<summary>Unused dependencies (2)</summary>
+
+```
+unused-dep     package.json
+my-package     package.json
+```
+
+</details>
+````
+
+The above can be copy-pasted where HTML and Markdown is supported, such as a
+GitHub issue or pull request, and renders like so:
+
+<details>
+  <summary>Unused files (2)</summary>
+
+```
+unused.ts
+dangling.js
+```
+
+</details>
+
+<details>
+  <summary>Unused dependencies (2)</summary>
+
+```
+unused-dep     package.json
+my-package     package.json
+```
+
+</details>
+
+### CodeClimate
+
+The built-in `codeclimate` reporter generates output in the Code Climate Report
+JSON format. Example usage:
+
+```text
+$ knip --reporter codeclimate
+
+[
+  {
+    "type": "issue",
+    "check_name": "Unused exports",
+    "description": "isUnused",
+    "categories": ["Bug Risk"],
+    "location": {
+      "path": "path/to/file.ts",
+      "positions": {
+        "begin": {
+          "line": 6,
+          "column": 1
+        }
+      }
+    }
+    "severity": "major",
+    "fingerprint": "e9789995c1fe9f7d75eed6a0c0f89e84",
+  }
+]
+```
+
+## Custom Reporters
+
+When the provided built-in reporters are not sufficient, a custom local reporter
+can be implemented or an external reporter can be used. Multiple reporters can
+be used at once by repeating the `--reporter` argument.
+
+The results are passed to the function from its default export and can be used
+to write issues to `stdout`, a JSON or CSV file, or sent to a service. It
+supports a local JavaScript or TypeScript file or an external dependency.
+
+### Local
+
+The default export of the reporter should be a function with this interface:
+
+```ts
+type Reporter = async (options: ReporterOptions): void;
+
+type ReporterOptions = {
+  report: Report;
+  issues: Issues;
+  counters: Counters;
+  configurationHints: ConfigurationHints;
+  isDisableConfigHints: boolean;
+  isTreatConfigHintsAsErrors: boolean;
+  cwd: string;
+  isProduction: boolean;
+  isShowProgress: boolean;
+  options: string;
+};
+```
+
+The data can then be used to write issues to `stdout`, a JSON or CSV file, or
+sent to a service.
+
+Here's a most minimal reporter example:
+
+```ts title="./my-reporter.ts"
+import type { Reporter } from 'knip';
+
+const reporter: Reporter = function (options) {
+  console.log(options.issues);
+  console.log(options.counters);
+};
+
+export default reporter;
+```
+
+Example usage:
+
+```sh
+knip --reporter ./my-reporter.ts
+```
+
+### External
+
+Pass `--reporter [pkg-name]` to use an external reporter. The default exported
+function of the `main` script (default: `index.js`) will be invoked with the
+`ReporterOptions`, just like a local reporter.
+
+## Preprocessors
+
+A preprocessor is a function that runs after the analysis is finished. It
+receives the results from the analysis and should return data in the same
+shape/structure (unless you pass it to only your own reporter).
+
+The data goes through the preprocessors before the final data is passed to the
+reporters. There are no built-in preprocessors. Just like reporters, use e.g.
+`--preprocessor ./my-preprocessor` from the command line (can be repeated).
+
+The default export of the preprocessor should be a function with this interface:
+
+```ts
+type Preprocessor = async (options: ReporterOptions) => ReporterOptions;
+```
+
+Like reporters, you can use local JavaScript or TypeScript files and external
+npm packages as preprocessors.
+
+Example preprocessor:
+
+```ts title="./preprocess.ts"
+import type { Preprocessor } from 'knip';
+
+const preprocess: Preprocessor = function (options) {
+  // modify options.issues and options.counters
+  return options;
+};
+
+export default preprocess;
+```
+
+Example usage:
+
+```sh
+knip --preprocessor ./preprocess.ts
+```
+
+[1]: #disclosure
+[2]: #github-actions
+[3]: #json
+[4]: #markdown
+[5]: #codeclimate
+[6]: ../reference/issue-types.md

package/docs/features/rules-and-filters.md

@@ -0,0 +1,102 @@
+---
+title: Rules & Filters
+sidebar:
+  order: 5
+---
+
+Use rules or filters to customize Knip's output. This has various use cases, a
+few examples:
+
+- Temporarily focus on a specific issue type.
+- You don't want to see unused `type`, `interface` and `enum` exports reported.
+- Specific issue types should be printed, but not counted against the total
+  error count.
+
+If you're looking to handle one-off exceptions, also see [JSDoc tags][1].
+
+## Filters
+
+You can `--include` or `--exclude` any of the reported issue types to slice &
+dice the report to your needs. Alternatively, they can be added to the
+configuration (e.g. `"exclude": ["dependencies"]`).
+
+Use `--include` to report only specific issue types. The following example
+commands do the same:
+
+```sh
+knip --include files --include dependencies
+knip --include files,dependencies
+```
+
+Or the other way around, use `--exclude` to ignore the types you're not
+interested in:
+
+```sh
+knip --include files --exclude enumMembers,duplicates
+```
+
+Also see the [list of issue types][2].
+
+### Shorthands
+
+Knip has shortcuts to include only specific issue types.
+
+1. The `--dependencies` flag includes:
+   - `dependencies` (and `devDependencies` + `optionalPeerDependencies`)
+   - `unlisted`
+   - `binaries`
+   - `unresolved`
+   - `catalog`
+
+2. The `--exports` flag includes:
+   - `exports`
+   - `types`
+   - `enumMembers`
+   - `duplicates`
+
+3. The `--files` flag is a shortcut for `--include files`
+
+## Rules
+
+Use `rules` in the configuration to customize the issue types that count towards
+the total error count, or to exclude them altogether.
+
+| Value     | Default | Printed | Counted | Description                       |
+| :-------- | :-----: | :-----: | :-----: | :-------------------------------- |
+| `"error"` |    ✓    |    ✓    |    ✓    | Similar to the `--include` filter |
+| `"warn"`  |    -    |    ✓    |    -    | Printed in faded/gray color       |
+| `"off"`   |    -    |    -    |    -    | Similar to the `--exclude` filter |
+
+Example:
+
+```json title="knip.json"
+{
+  "rules": {
+    "files": "warn",
+    "classMembers": "off",
+    "duplicates": "off"
+  }
+}
+```
+
+Also see the [issue types overview][2].
+
+NOTE: If the `dependencies` issue type is included, the `devDependencies` and
+`optionalPeerDependencies` types can still be set to `"warn"` separately.
+
+The rules are modeled after the ESLint `rules` configuration, and could be
+extended in the future.
+
+## Rules or filters?
+
+Filters are meant to be used as command-line flags, rules allow for more
+fine-grained configuration.
+
+- Rules are more fine-grained since they also have "warn".
+- Rules could be extended in the future.
+- Filters can be set in configuration and from CLI (rules only in
+  configuration).
+- Filters have shorthands (rules don't have this).
+
+[1]: ../reference/jsdoc-tsdoc-tags.md
+[2]: ../reference/issue-types.md