@knip/mcp 0.0.4 → 0.0.6

package/docs/docs/features/source-mapping.md

@@ -0,0 +1,100 @@
+---
+title: Source Mapping
+sidebar:
+  order: 4
+---
+
+Knip is mostly interested in source code. Analyzing build artifacts hurts
+performance and often leads to false positives, as they potentially contain
+bundled code and unresolvable imports.
+
+That's why Knip tries to map such build artifacts back to their original source
+files and analyze those instead. This is done based on `tsconfig.json` settings.
+
+## Example 1: package.json
+
+Let's look at an example case with `package.json` and `tsconfig.json` files, and
+see how "dist" files are mapped to "src" files.
+
+```jsonc title="package.json"
+{
+  "name": "my-workspace",
+  "main": "index.js",
+  "exports": {
+    ".": "./src/entry.js",
+    "./feat": "./lib/feat.js",
+    "./public": "./dist/app.js",
+    "./public/*": "./dist/*.js",
+    "./public/*.js": "./dist/*.js",
+    "./dist/internal/*": null,
+  },
+}
+```
+
+With this TypeScript configuration:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": "src",
+    "outDir": "dist"
+  }
+}
+```
+
+- `./src/entry.js` is not in an `outDir` folder, so it's added as an entry file
+- `./lib/feat.js` is not in an `outDir` folder, so it's added as an entry file
+- `./dist/app.js` is in a `dist` folder and mapped to `./src/app.{js,ts}` (¹)
+- `./dist/*.js` is in a `dist` folder and mapped to `./src/**/*.{js,ts}` (¹)
+- `./dist/internal/*` is translated to `./dist/internal/**` and files in this
+  directory and deeper are ignored when globbing entry files
+
+(¹) full extensions list is actually: `js`, `mjs`, `cjs`, `jsx`, `ts`, `tsx`,
+`mts`, `cts`
+
+In `--debug` mode, look for "Source mapping" to see this in action.
+
+:::tip
+
+Using `./dist/*.js` means that all files matching `./src/**/*.{js,ts}` are added
+as entry files. By default, unused exports of entry files are not reported. Use
+[includeEntryExports][1] to include them.
+
+:::
+
+## Example 2: monorepo
+
+Let's say we have this module in a monorepo that imports `helper` from another
+workspace in the same monorepo:
+
+```ts title="index.js"
+import { helper } from '@org/shared';
+```
+
+The target workspace `@org/shared` has this `package.json`:
+
+```json title="package.json"
+{
+  "name": "@org/shared",
+  "main": "dist/index.js"
+}
+```
+
+The module resolver will resolve `@org/shared` to `dist/index.js`. That file is
+usually compiled and git-ignored, while Knip wants the source file instead.
+
+:::tip
+
+You may need to compile build artifacts to `outDir` first before Knip can
+successfully apply source mapping for internal references in a monorepo.
+
+:::
+
+If the target workspace has a `tsconfig.json` file with an `outDir` option, Knip
+will try to map the "dist" file to the "src" file. Then if `src/index.ts`
+exists, Knip will use that file instead of `dist/index.js`.
+
+Currently this only works based on `tsconfig.json`, in the future more source
+mappings may be added.
+
+[1]: ../reference/configuration.md#includeentryexports

package/docs/docs/guides/configuring-project-files.md

@@ -0,0 +1,205 @@
+---
+title: Configuring Project Files
+sidebar:
+  order: 1
+---
+
+The `entry` and `project` file patterns are the first and most important
+options. Getting those right is essential to help you delete more code and make
+Knip faster:
+
+- Start with defaults. Only add targeted `entry` overrides when needed.
+- Use `project` patterns (with negations) to define the scope for Knip.
+- Use production mode to exclude tests and other non-production files.
+- Use `ignore` only to suppress issues in specific files. It does not exclude
+  files from analysis.
+
+Let's dive in and expand on all of these.
+
+## Entry files
+
+Avoid adding too many files as `entry` files:
+
+1. Knip does not report [unused exports][1] in entry files by default.
+2. Proper `entry` and `project` patterns allow Knip to find unused files and
+   exports.
+
+## Unused files
+
+Files are reported as unused if they are in the set of `project` files, but are
+not resolved from the `entry` files:
+
+```
+unused files = project files - (entry files + resolved files)
+```
+
+See [entry files][2] to see where Knip looks for entry files. Fine-tune `entry`
+and adjust `project` to fit your codebase.
+
+:::tip
+
+Use negated `project` patterns to precisely include/exclude files for unused
+files detection.
+
+Use `ignore` to suppress issues in matching files; it does not remove those
+files from analysis.
+
+:::
+
+## Negated patterns
+
+When there are too many files in the analysis, start here.
+
+For instance, routes are entry files except those prefixed with an underscore:
+
+```json
+{
+  "entry": ["src/routes/*.ts", "!src/routes/_*.ts"]
+}
+```
+
+Some files are not part of your source and are reported as unused (false
+positives)? Use negated `project` patterns:
+
+```json
+{
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts", "!src/exclude/**"]
+}
+```
+
+❌   Don't use `ignore` for generated artifacts:
+
+```json title="knip.json"
+{
+  "entry": ["src/index.ts", "scripts/*.ts"],
+  "ignore": ["build/**", "dist/**", "src/generated.ts"]
+}
+```
+
+✅   Do define your project boundaries:
+
+```json title="knip.json"
+{
+  "entry": ["src/index.ts", "scripts/*.ts"],
+  "project": ["src/**", "scripts/**"],
+  "ignore": ["src/generated.ts"]
+}
+```
+
+Why is this better:
+
+- `project` defines "what belongs to the codebase" so build outputs are not part
+  of the analysis and don't appear in unused file detection at all
+- `ignore` is for the few files that should be analyzed but contain exceptions
+- increases performance by analyzing only source files
+
+## Ignore issues in specific files
+
+Use `ignore` when a specific analyzed file is not handled properly by Knip or
+intentionally contains unused exports (e.g. generated files exporting
+"everything"):
+
+```json
+{
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"],
+  "ignore": ["src/generated.ts"]
+}
+```
+
+Also see [ignoreExportsUsedInFile][3] for a more targeted approach.
+
+## Production Mode
+
+Default mode includes tests and other non-production files in the analysis. To
+focus on production code, use [production mode][4].
+
+Don't try to exclude tests via `ignore` or negated `project` patterns. That's
+inefficient and ineffective due to entries added by plugins. Use production mode
+instead.
+
+❌   Don't do this:
+
+```json
+{
+  "ignore": ["**/*.test.js"]
+}
+```
+
+Why not: `ignore` only hides issues from the report; it does not exclude files
+from analysis.
+
+❌   Also don't do this:
+
+```json
+{
+  "entry": ["index.ts", "!**/*.test.js"]
+}
+```
+
+Why not: plugins for test frameworks add test file as `entry` files, you can't
+and shouldn't override that globally.
+
+❌   Or this:
+
+```json
+{
+  "project": ["**/*.ts", "!**/*.spec.ts"]
+}
+```
+
+Why not: `project` is used for unused file detection. Negating test files here
+is ineffective, because they're `entry` files.
+
+✅   Do this instead:
+
+```shell
+knip --production
+```
+
+To fine-tune the resulting production file set, for instance to exclude test
+helper files that still show as unused, use the exclamation mark suffix on
+production patterns:
+
+```json
+{
+  "entry": ["src/index.ts!"],
+  "project": ["src/**/*.ts!", "!src/test-helpers/**!"]
+}
+```
+
+Remember to keep adding the exclamation mark `suffix!` for production file
+patterns.
+
+:::tip
+
+Use the exclamation mark (`!`) on both ends (`!`) to exclude files in production
+mode.
+
+:::
+
+## Defaults & Plugins
+
+To reiterate, the default `entry` and `project` files for each workspace:
+
+```json
+{
+  "entry": [
+    "{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}",
+    "src/{index,cli,main}.{js,cjs,mjs,jsx,ts,cts,mts,tsx}"
+  ],
+  "project": ["**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}!"]
+}
+```
+
+Next to this, there are other places where [Knip looks for entry files][2].
+
+Additionally, [plugins have plenty of entry files configured][5] that are
+automatically added as well.
+
+[1]: ../typescript/unused-exports.md
+[2]: ../explanations/entry-files.md
+[3]: ../reference/configuration#ignoreexportsusedinfile
+[4]: ../features/production-mode.md
+[5]: ../explanations/plugins.md#entry-files

package/docs/docs/guides/contributing.md

@@ -0,0 +1,24 @@
+---
+title: Contributing to Knip
+---
+
+Here are some ways to contribute to Knip:
+
+- Spread the word!
+- [Star the project][1]
+- [File an issue with a reproduction][2]
+- [Pull requests are welcome][3]
+
+[Writing a plugin][4] is a great and fun way to get started.
+
+The [CONTRIBUTING.md][3] and [DEVELOPMENT.md][5] guides should get you up and
+running quickly.
+
+The main goal of Knip is to keep projects clean & tidy. Everything that
+contributes to that goal is welcome!
+
+[1]: https://github.com/webpro-nl/knip
+[2]: ./issue-reproduction.md
+[3]: https://github.com/webpro-nl/knip/blob/main/.github/CONTRIBUTING.md
+[4]: ./writing-a-plugin.md
+[5]: https://github.com/webpro-nl/knip/blob/main/.github/DEVELOPMENT.md