@knip/mcp 0.0.1

package/docs/docs/blog/slim-down-to-speed-up.md

@@ -0,0 +1,269 @@
+---
+title: Slim down to speed up
+date: 2023-12-14
+sidebar:
+  order: 6
+---
+
+_Published: 2023-12-14_
+
+**tl;dr;** Memory usage is up to 50% lower, runs are up to 60% faster and you
+can start using v4 canary today. No "unused class members" for the time being,
+but this feature is planned to be restored.
+
+## Introduction
+
+Honestly, performance has always been a challenge for Knip. A longstanding
+bottleneck has finally been eliminated and Knip is going to be a lot faster.
+Skip straight to the bottom to install v4 canary and try it out! Or grab
+yourself a nice drink and read on if you're interested in where we are coming
+from, and where we are heading.
+
+## Projects & Workspaces
+
+From the start, Knip has relied on TypeScript for its robust parser for
+JavaScript and TypeScript files. And on lots of machinery important to Knip,
+like module resolution and accurately finding references to exported values.
+Parts of it can be customized, such as the (virtual) file system and the module
+resolver.
+
+In TypeScript terms, a "project" is like a workspace in a monorepo. Same as each
+workspace has a `package.json`, each project has a `tsconfig.json`. The
+`ts.createProgram()` method is used to create a program based on a
+`tsconfig.json` and the machinery starts to read and parse source code files,
+resolve modules, and so on.
+
+Up until v2, when Knip wanted to find unused things in a monorepo, all programs
+for all workspaces were loaded into memory. Workspaces often depend on each
+other, so Knip couldn't load one project, analyze it and dispose it. This way,
+connections across workspaces would be lost.
+
+## Shared Workspaces
+
+Knip v2 said goodbye to this approach and implemented its own TypeScript backend
+(after using `ts-morph` for this). Based on the compatibility of
+`compilerOptions`, workspaces were merged into shared programs whenever
+possible. Having less programs in memory led to significant performance
+improvements. Yet ultimately it was still a stopgap, since everything was still
+kept in memory for the duration of the process.
+
+"Why does everything need to stay in memory?", you may wonder. The answer is
+that Knip uses `findReferences` at the end of the process. Knip relied on this
+TypeScript Language Server method for everything that's not easy to find. More
+about that later in [the story of findReferences][1]
+
+## Serialization
+
+Fortunately, everything that's imported and exported from source files
+(including things like members of namespaces and enums) can be found relatively
+easily during AST traversal. This way, references to exports don't have to be
+"traced back" later on.
+
+It's mostly class members that are harder to find due to their dynamic nature.
+Without these, all information can be serialized for storage and retrieval (in
+memory or on disk). Slimming down by taking class members out of the equation
+simplifies things a lot and paves the way for all sorts of improvements.
+
+## We Have To Slim Down
+
+The relevant part in the linting process can be summarized in 5 steps:
+
+1. Collect entry files and feed them to TypeScript
+2. Read files, resolve modules, and create ASTs
+3. Traverse ASTs and collect imports & exports
+4. Match exports against imports to determine what's unused
+5. Find references to hard-to-find exported values and members
+
+If we would hold on to reporting unused class members, then especially steps 2
+and 5 are hard to decouple. The program and the language service containing the
+source files used to eventually trace back references can't really be decoupled.
+So class members had to go. Sometimes you have to slim down to keep moving. One
+step back, two steps forward.
+
+If you rely on this feature, fear not. I plan to bring it back before the final
+v4, but possibly behind a flag.
+
+## What's In Store?
+
+So with this out of the way, everything becomes a lot clearer and we can finally
+really start thinking about significant memory and performance improvements. So
+what's in store here? A lot!
+
+- We no longer need to keep everything in memory, so workspaces are read and
+  disposed in isolation, one at a time. Memory usage will be spread out more
+  even. This does not make it faster, but reducing "out of memory" issues is
+  definitely a Good Thing™️ in my book.
+- Knip could recover from unexpected exits and continue from the last completed
+  workspace.
+- The imports and exports are in a format that can be serialized for storage and
+  retrieval. This opens up interesting opportunities, such as local caching on
+  disk, skipping work in subsequent runs, remote caching, and so on.
+- Handling workspaces in isolation and serialization result in parallelization
+  becoming a possibility. This becomes essential, as module resolution and AST
+  creation and traversal are now the slowest parts of the process and are not
+  easy to optimize significantly (unless perhaps switching to e.g Rust).
+- No longer relying on `findReferences` speeds up the export/import matching
+  part part significantly. So far I've seen **improvements of up to 60% on total
+  runtime**, and my guess is that some larger codebases may profit even more.
+- The serialization format is still being explored and there is no caching yet,
+  but having the steps more decoupled is another Good Thing™️ that future me
+  should be happy about.
+
+## Back It Up, Please
+
+I heard you. Here's some example data. You can get it directly from Knip using
+the `--performance` flag when running it on any codebase. Below we have some
+data after linting the [Remix monorepo][2].
+
+### Knip v3
+
+```sh
+$ knip --performance
+
+Name                           size  min     max      median   sum
+-----------------------------  ----  ------  -------  -------  -------
+findReferences                  223    0.55  2252.35     8.46  5826.95
+createProgram                     2   50.78  1959.92  1005.35  2010.70
+getTypeChecker                    2    5.04   667.45   336.24   672.48
+getImportsAndExports            396    0.00     7.19     0.11   104.46
+
+Total running time: 9.7s (mem: 1487.39MB)
+```
+
+### Knip v4
+
+```sh
+$ knip --performance
+
+...
+
+Name                           size  min     max      median   sum
+-----------------------------  ----  ------  -------  -------  -------
+createProgram                     2   54.36  2138.45  1096.40  2192.81
+getTypeChecker                    2    7.40   664.83   336.12   672.23
+getImportsAndExports            396    0.00    36.36     0.16   224.37
+getSymbolAtLocation            2915    0.00    29.71     0.00    65.63
+
+Total running time: 4.3s (mem: 729.67MB)
+```
+
+### Takeaways
+
+The main takeaways here:
+
+- In v3,`findReferences` is where Knip potentially spends most of its time
+- In v4, total running time is down over 50%
+- In v4, memory usage is down 50% (calculated using
+  `process.memoryUsage().heapUsage`)
+- In v4, `getImportsAndExports` is more comprehensive to compensate for the
+  absence of `findReferences` - more on that below
+
+Remember, unused class members are no longer reported by default in v4.
+
+## The story of `findReferences`
+
+Did I mention Knip uses `findReferences`...? Knip relied on it for everything
+that's not easy to find. Here's an example of an export/import match that **is**
+easy to find:
+
+```ts title="import.ts"
+import { MyThing } from './thing.ts';
+```
+
+```ts title="export.ts"
+export const MyThing = 'cool';
+```
+
+In v2 and v3, Knip collects many of such easy patterns. Other patterns are
+harder to find with static analysis. This is especially true for class members.
+Let's take a look at the next example:
+
+```ts title="MyClass.ts"
+class MyClass {
+  constructor() {
+    this.method();
+  }
+  method() {}
+  do() {}
+}
+
+export const OtherName = MyClass;
+```
+
+```ts title="instance.ts"
+import * as MyNamespace from './MyClass.ts';
+
+const { OtherName } = MyNamespace;
+
+const instance = new OtherName();
+
+instance.do();
+```
+
+Without a call or `new` expression to instantiate `OtherName`, its `method`
+member would not be used (since the constructor would not be executed). To
+figure this out using static analysis goes a long way. Through export
+declarations, import declarations, aliases, initializers, call expressions...
+the list goes on and on. Yet all this magic is exactly what happens when you use
+"Find all references" or "Go to definition" in VS Code.
+
+Knip used `findReferences` extensively, but it's what makes a part of Knip
+rather slow. TypeScript needs to wire things up (through
+`ts.createLanguageService` and `program.getTypeChecker`) before it can use this,
+and then it tries hard to find all references to anything you throw at it. It
+does this very well, but the more class members, enum members and namespaced
+imports your codebase has, the longer it inevitably takes to complete the
+process.
+
+Besides letting go of class members, a slightly more comprehensive AST traversal
+is required to compensate for the absence of `findReferences` (it's the
+`getImportsAndExports` function in the metrics above). I'd like to give you an
+idea of what "more comprehensive" means here.
+
+In the following example, `referencedExport` was stored as export from
+`namespace.ts`, but it was not imported directly as such:
+
+```ts title="namespace.ts"
+export const referencedExport = () => {};
+```
+
+```ts title="index.ts"
+import * as NS from './namespace.ts';
+
+NS.referencedExport();
+```
+
+Previously, Knip used `findReferences()` to "trace back" the usage of the
+exported `referencedExport`.
+
+The gist of the optimization is to pre-determine all imports and exports. During
+AST traversal of `index.ts` , Knip sees that `referencedExport` is attached to
+the imported `NS` namespace, and stores that as an imported identifier of
+`namespace.ts`. When matching exports against imports, this lookup comes at no
+extra cost. Additionally, this can be stored as strings, so it can be serialized
+too. And that means it can be cached.
+
+Knip already did this for trivial cases as shown in the first example of this
+article. This has now been extended to cover more patterns. This is also what
+needs to be tested more extensively before v4 can be released. Its own test
+suite and the projects in the integration tests are already covered so we're
+well on our way.
+
+For the record, `findReferences` is an absolute gem of functionality provided by
+TypeScript. Knip is still backed by TypeScript, and tries to speed things up by
+shaking things off. In the end it's all about trade-offs.
+
+## Let's Go!
+
+You can start using Knip v4 today, feel free to try it out! You might find a
+false positive that wasn't there in v3, please [report this][3].
+
+```sh
+npm install -D knip@canary
+```
+
+Remember, Knip it before you ship it! Have a great day ☀️
+
+[1]: #the-story-of-findreferences
+[2]: https://github.com/remix-run/remix
+[3]: https://github.com/webpro-nl/knip/issues

package/docs/docs/blog/state-of-knip.md

@@ -0,0 +1,191 @@
+---
+title: The State of Knip
+date: 2025-02-28
+sidebar:
+  order: 2
+---
+
+_Published: 2025-02-28_
+
+Honestly, Knip was a bit of a "cursed" project from the get-go. Getting anywhere
+near a level of being broadly-ish valuable requires a good amount of
+~~foolishness~~ determination, and it has always been clear it would stay far
+from perfect. It's telling that most of [similar projects][1] have been
+abandoned.
+
+And even though Knip is in its infancy, this update is meant as a sign we feel
+we're still on to something. External indicators include increased usage looking
+at numbers such as dependent repositories on GitHub and weekly downloads on npm,
+and bug reports about increasingly less rudimentary issues.
+
+## Two Cases
+
+For those interested, let's take a look at two cases that hopefully give an
+impression of how Knip works under the hood and the level of issues we're
+currently dealing with. It's assumed you already have a basic understanding of
+Knip (otherwise please consider to read at least [entry files][2] and
+[plugins][3] first).
+
+### Case 1: Next.js
+
+Let's say this default configuration represents, greatly simplified, [the
+default `entry` patterns][4] for projects using Next.js:
+
+```json
+{
+  "next": {
+    "entry": ["next.config.ts", "src/pages/**/*.tsx"]
+  }
+}
+```
+
+Those files will be searched for and then statically analyzed to collect
+`import` statements and find other local files and external dependencies. This
+is the generic way Knip handles all source files.
+
+However, the game changes if the project uses the following Next.js
+configuration:
+
+```ts title="next.config.ts"
+const nextConfig = {
+  pageExtensions: ['page.tsx'],
+};
+
+export default nextConfig;
+```
+
+Next.js will now look for files matching `src/pages/**/*.page.tsx` instead (note
+the subtle change of the glob pattern). Knip should respect this to find used
+and unused files properly.
+
+Moving the burden to users for them to either not notice at all and get
+incorrect results, or having to override the `next.entry` patterns and include
+`src/pages/**/*.page.tsx` isn't good DX. Knip should take care of it.
+
+To get the configuration object and the value of `pageExtensions`, Knip has to
+actually load and execute `next.config.ts` ¹... and trouble is right around the
+corner:
+
+```ts title="next.config.ts"
+const nextConfig = {
+  pageExtensions: ['page.tsx'],
+  env: {
+    BASE_URL: process.env.BASE_URL.toLowerCase(),
+  },
+};
+
+export default nextConfig;
+```
+
+```shell
+$ knip
+💥 LoaderError: Error loading next.config.ts
+💥 Reason: Cannot read properties of undefined (reading 'toLowerCase')
+```
+
+Obviously a contrived example, but the gist is that lots of tooling
+configuration expects environment variables to be defined. But when running Knip
+there might not be a mechanism to set those. Clearly a breaking change when Knip
+starts doing this, only for Next.js projects with a configuration file that
+doesn't read environment variables safely (or has other contextual
+dependencies).
+
+By the way, [the ESLint v9 plugin][5] has a similar issue.
+
+¹ Another approach could be to statically analyze the `next.config.ts`
+configuration file. That would require some additional efforts and get us only
+so far, but is definitely useful in some cases and on the radar.
+
+**EDIT:** This has been solved in the Next.js plugin in v5.48.0.
+
+### Case 2: Knip does that?!
+
+To further bring down user configuration and the number of false positives, the
+system required more components. New components have been introduced to keep
+improving and nail it for an increasing number of projects. This case is an
+illustration of some of those components.
+
+Let's just dive into this example and find out what's happening:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "yarn --cwd packages/frontend vitest -c vitest.components.config.ts"
+  }
+}
+```
+
+Orchestration is necessary between various components within Knip, such as:
+
+- Plugins, the Vitest plugin parses `vitest.components.config.ts`
+- Custom CLI argument parsing for executables, e.g. `yarn --cwd [dir]` and
+  `vitest --config [file]`
+- The workspace graph, to see `packages/frontend` is a descendant workspace of
+  the root workspace
+
+Patterns like in the script above do not occur only in `package.json` files, but
+could be anywhere. Here's a similar example in a GitHub Actions workflow:
+
+```yaml title=".github/workflows/test.yml"
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - run: playwright test -c playwright.e2e.config.ts
+        working-directory: e2e
+```
+
+The pattern is very similar, because Knip needs to assign a configuration file
+to a specific workspace (assuming there's one in `./e2e`) and apply the Vitest
+configuration to that particular workspace with its own set of directory and
+entry file patterns.
+
+An essential part of Knip is to build up the module graph for source files. With
+the configuration files still in mind, this is the pattern Knip follows towards
+this goal:
+
+- Find configuration files at default and custom locations
+- Assign them to the right workspace
+- Run plugins in their own workspace to take entry file patterns from the
+  configuration objects
+- Load and parse configuration files to get referenced dependencies
+
+The referenced dependencies are stored in the `DependencyDeputy` class to
+eventually determine what dependencies are unused or missing in `package.json`
+in each workspace.
+
+Both the configuration and entry files are then used to start building up the
+module graph.
+
+## Comprehensive
+
+Discussing the two cases briefly covers only part of the whole process. This
+might give a sense of the reason why Knip is pretty comprehensive. After all,
+building the module graph for internal source files to find unused files and
+exports requires the list of external dependencies including internal
+workspaces. And on the other hand, a complete module graph is required to find
+unused or missing external dependencies.
+
+The comprehensiveness also requires a range of components in the system, such as
+the aforementioned ones, [compilers for popular frameworks][6] and a [script
+parser][7], and other affordances such as [auto-fix][8].
+
+That said, code organization could be improved to make it more accessible for
+contributions and, for instance, expose programmatic APIs to use the generated
+module graph outside of Knip. Additionally, existing plugins can better take
+advantage of existing components in the system, and new plugins can be developed
+to further reduce user configuration and false positives.
+
+## The End
+
+That's all for today, thanks for reading! Have a great one, and don't forget:
+Knip it before you ship it! ✂️
+
+[1]: ../explanations/comparison-and-migration.md
+[2]: ../explanations/entry-files.md
+[3]: ../explanations/plugins.md
+[4]: ../reference/plugins/next.md#default-configuration
+[5]: ../reference/plugins/eslint.md#eslint-v9
+[6]: ../features/compilers.md
+[7]: ../features/script-parser.md
+[8]: ../features/auto-fix.mdx

package/docs/docs/blog/two-years.mdx

@@ -0,0 +1,107 @@
+---
+title: Two Years
+date: 2024-10-04
+sidebar:
+  order: 3
+---
+
+_Published: 2024-10-04_
+
+import EmojiBlastButton from '../../../components/EmojiBlastButton.astro';
+import Projects from '../../../components/Projects.astro';
+import Sponsors from '../../../components/Sponsors.astro';
+
+Exactly two years ago the first commit was pushed to GitHub and the first
+version of Knip was published to the npm registry. The name was initially
+[Exportman][1]! We've come a loooong way... The JavaScript ecosystem is highly
+dynamic and I've been crazy enough to even start, try and keep up with it! But
+here we are.
+
+October 4th is World Animal Day, so there was really no choice but bring in the
+crazy mascot that early adopters may remember:
+
+![Crazy cow with orange scissors in Van Gogh style][2]
+
+Today we celebrate an unknown but CRAZY amount of clutter removed from so many
+codebases with Knip's help. Every single day I see many of those little red
+blocks for thousands of lines of deleted code and dependencies. Call me crazy,
+but to me this is pure joy and never gets old!    🟩 🟥 🟥 🟥 🟥
+
+<EmojiBlastButton />
+
+## Smiling faces
+
+The actual amount of code and dependencies removed and the number of smiling
+faces this brings is what matters most, but also remain a good mystery. Clearly
+more and more projects add Knip to their projects and CI workflows to keep
+ever-growing codebases tidy. It's wonderful to see if Knip plays its part in
+today's ecosystem to help with that. Thanks for bearing with me, here's to a lot
+more little red blocks in your PRs!    🟩 🟥 🟥 🟥 🟥
+
+## Updates
+
+Why not throw in some freshly cooked updates in [v5.31.0][3] for you while we're
+at it:
+
+- [The auto-fix feature][4] has been completely revamped, it's much better and a
+  lot more comprehensive! You have to see it to believe it.
+- Knip has upgraded to [Jiti v2][5], resolving a bunch of known issues when
+  loading configuration files authored in TypeScript and ESM, such as:
+
+```
+Cannot use 'import.meta' outside a module
+await is only valid in async functions and the top level bodies of modules
+Unexpected identifier 'Promise'
+Reflect.metadata is not a function
+```
+
+And that pesky "CJS build of Vite's Node API is deprecated" warning is finally
+gone!
+
+Thanks to everyone involved in making this happen, it's truly much appreciated.
+
+## Stable
+
+If you haven't tried Knip recently, it's worth taking another look! Version 5
+was released 8 months ago, and even though there were no breaking changes, it
+includes many enhancements. In fact, Knip has been largely stable since version
+3, which came out a year ago. Many releases have a compound effect, as Knip has
+kept the pace for two years now.
+
+## Projects using Knip
+
+This list of projects using Knip to keep their codebases tidy is something I
+couldn't be more proud of:
+
+:::section{.columns.min200}
+
+<Projects />
+
+:::
+
+And so many more on and off the radar. Very, very cool!
+
+## Sponsors
+
+Last but not least, eternal gratitude for all the sponsors that have been
+supporting me along the way. THANK YOU, THANK YOU, THANK YOU!
+
+And eh.. gotta take my chances: how about [joining this awesome club][6]?
+
+:::section{.columns.min300.mt}
+
+<Sponsors />
+
+:::
+
+## Acknowledgements
+
+Thanks to Joshua Goldberg for [emoji-blast][7]! 🎉
+
+[1]: https://www.npmjs.com/package/exportman/v/0.0.1
+[2]: /cow-with-orange-scissors-van-gogh-style.webp
+[3]: https://github.com/webpro-nl/knip/releases/tag/5.31.0
+[4]: ../features/auto-fix.md
+[5]: https://github.com/unjs/jiti
+[6]: /sponsors
+[7]: https://www.emojiblast.dev

package/docs/docs/explanations/comparison-and-migration.md

@@ -0,0 +1,129 @@
+---
+title: Comparison & Migration
+---
+
+First of all, Knip owes a lot to the projects on this page and they've all been
+inspirational in their own way. For best results, Knip has [a vision embracing
+comprehensiveness][1] which is larger in scope than any of the alternatives. So
+if any of those tools has the right scope for your requirements, then by all
+means, use what suits you best. Note that most projects are no longer
+maintained.
+
+All tools have in common that they have less features and don't support the
+concept of [monorepos/workspaces][2]. Feel free to send in projects that Knip
+does not handle better, Knip loves to be challenged!
+
+## Migration
+
+A migration consists of deleting the dependency and its configuration file and
+[getting started with Knip][3]. You should end up with less configuration.
+
+## Comparison
+
+### depcheck
+
+> [Depcheck][4] is a tool for analyzing the dependencies in a project to see:
+> how each dependency is used, which dependencies are useless, and which
+> dependencies are missing from package.json.
+
+The project has plugins (specials), yet not as many as Knip has and they're not
+as advanced. It also supports compilers (parsers) for non-standard files.
+
+The following commands are similar:
+
+```sh
+depcheck
+knip --dependencies
+```
+
+### unimported
+
+> Find and fix dangling files and unused dependencies in your JavaScript
+> projects.
+
+[unimported][5] is fast and works well. It works in what Knip calls "production
+mode" exclusively. If you're fine with a little bit of configuration and don't
+want or need to deal with non-production items (such as `devDependencies` and
+test files), then this might work well for you.
+
+The following commands are similar:
+
+```sh
+unimported
+knip --production --dependencies --files
+```
+
+**Project status**: The project is archived and recommends Knip.
+
+### ts-prune
+
+> Find unused exports in a typescript project. 🛀
+
+[ts-prune][6] aims to find potentially unused exports in your TypeScript project
+with zero configuration.
+
+The following commands are similar:
+
+```sh
+ts-prune
+knip --include exports,types,nsExports,nsTypes
+```
+
+Use `knip --exports` to also include class and enum members.
+
+**Project status**: The project is archived and recommends Knip.
+
+### ts-unused-exports
+
+> [ts-unused-exports][7] finds unused exported symbols in your Typescript
+> project
+
+The following commands are similar:
+
+```sh
+ts-unused-exports
+knip --include exports,types,nsExports,nsTypes
+```
+
+Use `knip --exports` to also include class and enum members.
+
+### tsr
+
+> Remove unused code from your TypeScript Project
+
+[tsr][8] (previously `ts-remove-unused`) removes unused exports, and works based
+on a single `tsconfig.json` file (`includes` and `excludes`) and requires no
+configuration. It removes the `export` keyword or the whole export declaration.
+
+## Related projects
+
+Additional alternative and related projects include:
+
+- [deadfile][9]
+- [DepClean][10]
+- [dependency-check][11]
+- [find-unused-exports][12]
+- [next-unused][13]
+- [npm-check][14]
+- [renoma][15]
+
+In general, the [e18e.dev][16] website and in particular the [Cleanup][17]
+section is a great resource when dealing with technical debt.
+
+[1]: ./why-use-knip.md#comprehensive
+[2]: ../features/monorepos-and-workspaces.md
+[3]: ../overview/getting-started.mdx
+[4]: https://github.com/depcheck/depcheck
+[5]: https://github.com/smeijer/unimported
+[6]: https://github.com/nadeesha/ts-prune
+[7]: https://github.com/pzavolinsky/ts-unused-exports
+[8]: https://github.com/line/tsr
+[9]: https://github.com/M-Izadmehr/deadfile
+[10]: https://github.com/mysteryven/depclean
+[11]: https://github.com/dependency-check-team/dependency-check
+[12]: https://github.com/jaydenseric/find-unused-exports
+[13]: https://github.com/pacocoursey/next-unused
+[14]: https://github.com/dylang/npm-check
+[15]: https://github.com/bluwy/renoma
+[16]: https://e18e.dev
+[17]: https://e18e.dev/guide/cleanup.html