@knip/mcp 0.0.1

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

package/docs/docs/features/script-parser.md

@@ -0,0 +1,156 @@
+---
+title: Script Parser
+---
+
+Knip parses shell commands and scripts to find additional dependencies, entry
+files and configuration files in various places:
+
+- In [`package.json`][1]
+- In [CLI arguments][2]
+- In [scripts][3]
+- In [source code][4]
+
+Shell scripts can be read and statically analyzed, but they're not executed.
+
+## package.json
+
+The `main`, `bin`, `exports` and `scripts` fields may contain entry files. Let's
+take a look at this example:
+
+```json title="package.json"
+{
+  "name": "my-package",
+  "main": "index.js",
+  "exports": {
+    "./lib": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "program": "bin/cli.js"
+  },
+  "scripts": {
+    "build": "rollup src/entry.ts",
+    "start": "node --loader tsx server.ts"
+  }
+}
+```
+
+From this example, Knip automatically adds the following files as entry files:
+
+- `index.js`
+- `./dist/index.mjs`
+- `./dist/index.cjs`
+- `bin/cli.js`
+- `src/entry.ts`
+- `server.ts`
+
+### Excluded files
+
+Knip would not add the `exports` if the `dist` folder is matching a pattern in a
+relevant `.gitignore` file or `ignore` option.
+
+Knip does not add scripts without a standard extension. For instance, the
+`bin/tool` file might be a valid executable for Node.js, but wouldn't be added
+or parsed by Knip.
+
+### CLI Arguments
+
+When parsing the `scripts` of `package.json` and other files, Knip detects
+various types of inputs. Some examples:
+
+- The first positional argument is usually an entry file
+- Configuration files are often in the `-c` or `--config` argument
+- The `--require`, `--loader` or `--import` arguments are often dependencies
+
+```json
+{
+  "name": "my-lib",
+  "scripts": {
+    "start": "node --import tsx/esm run.ts",
+    "bundle": "tsup -c tsup.lib.config.ts",
+    "type-check": "tsc -p tsconfig.app.json"
+  }
+}
+```
+
+The `"start"` script will have `tsx` marked as a referenced dependency, and adds
+`run.ts` as an entry file.
+
+Additionally, the following files are detected as configuration files:
+
+- `tsup.lib.config.ts` - to be handled by the tsup plugin
+- `tsconfig.app.json` - to be handled by the TypeScript plugin
+
+Such executables and their arguments are all defined in plugins separately for
+fine-grained results.
+
+## Scripts
+
+Plugins may also use the script parser to extract entry files and dependencies
+from commands. A few examples:
+
+- GitHub Actions: workflow files may contain `run` commands (e.g.
+  `.github/workflows/ci.yml`)
+- Husky & Lefthook: Git hooks such as `.git/hooks/pre-push` contain scripts;
+  also `lefthook.yml` has `run` commands
+- Lint Staged: configuration values are all commands
+- Nx: task executors and `nx:run-commands` executors in `project.json` contains
+  scripts
+- Release It: `hooks` contain commands
+
+Plugins can also return configuration files. Some examples:
+
+- The Angular plugin detects `options.tsConfig` as a TypeScript config file
+- The GitHub Actions plugin parses `run` commands which may contain
+  configuration file paths
+
+## Source Code
+
+When Knip is walking the abstract syntax trees (ASTs) of JavaScript and
+TypeScript source code files, it looks for imports and exports. But there's a
+few more (rather obscure) things that Knip detects in the process. Below are
+examples of additional scripts Knip parses to find entry files and dependencies.
+
+### bun
+
+If the `bun` dependency is imported in source code, Knip considers the contents
+of `$` template tags to be scripts:
+
+```ts
+import { $ } from 'bun';
+await $`bun boxen I ❤ unicorns`;
+await $`boxen I ❤ unicorns`;
+```
+
+Parsing the script results in the `boxen` binary (the `boxen-cli` dependency) as
+referenced (twice).
+
+### execa
+
+If the `execa` dependency is imported in source code, Knip considers the
+contents of `$` template tags to be scripts:
+
+```ts
+await $({ stdio: 'inherit' })`c8 node hydrate.js`;
+```
+
+Parsing the script results in `hydrate.js` added as an entry file and the `c8`
+binary/dependency as referenced.
+
+### zx
+
+If the `zx` dependency is imported in source code, Knip considers the contents
+of `$` template tags to be scripts:
+
+```ts
+await $`node scripts/parse.js`;
+```
+
+This will add `scripts/parse.js` as an entry file.
+
+[1]: #packagejson
+[2]: #cli-arguments
+[3]: #scripts
+[4]: #source-code