diff --git a/packages/docs/src/content/docs/explanations/plugins.md b/packages/docs/src/content/docs/explanations/plugins.md index 54d6774bc..45aaf73fb 100644 --- a/packages/docs/src/content/docs/explanations/plugins.md +++ b/packages/docs/src/content/docs/explanations/plugins.md @@ -19,10 +19,11 @@ plugin will: - Handle [configuration files][4] like `astro.config.mjs` - Add [entry files][5] such as `src/pages/**/*.astro` +- Define [command-line arguments][6] ## Configuration files -Knip uses [entry files][6] as starting points to scan your source code and +Knip uses [entry files][7] as starting points to scan your source code and resolve other internal files and external dependencies. The dependency graph can be statically resolved through the `require` and `import` statements in those source files. However, configuration files reference external dependencies in @@ -31,7 +32,7 @@ find those dependencies. ### Example: ESLint -In the first example we look at [the ESLint plugin][7]. The default `config` +In the first example we look at [the ESLint plugin][8]. The default `config` file patterns include `.eslintrc.json`. Here's a minimal example: ```json title=".eslintrc.json" @@ -56,7 +57,7 @@ as unlisted. And vice versa, if there are any ESLint plugins listed in ### Example: Vitest -The second example uses [the Vitest plugin][7]. Here's a minimal example of a +The second example uses [the Vitest plugin][8]. Here's a minimal example of a Vitest configuration file: ```ts title="vitest.config.ts" @@ -85,8 +86,8 @@ plugins contain `package.json` in the list of `config` files. :::tip[Summary] -`config` files are parsed by plugins to find external dependencies. Knip uses -this to determine unused and unlisted dependencies. +Plugins parse `config` files to find external dependencies. Knip uses this to +determine unused and unlisted dependencies. ::: @@ -107,9 +108,8 @@ configured. :::tip[Plugins result in less configuration] -Plugins even consult the configuration files of these tools, in case alternative -entry files should be used. So you don't need to repeat this in your Knip -configuration. +Plugins uses entry file patterns as defined in the configuration files of these +tools. So you don't need to repeat this in your Knip configuration. ::: @@ -211,7 +211,7 @@ added as entry files by the GitHub Actions plugin. Additionally, the file `e2e/playwright.web.config.ts` is detected and will be handed over as a Playwright configuration file. -Read more about this in [Script Parser][8]. +Read more about this in [command-line arguments][6]. ### webpack @@ -283,14 +283,28 @@ automatically added as `entry` files for Knip to **statically** resolve the Additionally, `./setup-tests.ts` will be added as an `entry` file. +## Command-Line Arguments + +Plugins may define the arguments where Knip should look for entry files, +configuration files and dependencies. We've already seen some examples above: + +```sh +node --loader tsx scripts/deploy.ts +playwright test -c playwright.web.config.ts +``` + +Please see [script parser][9] for more details. + +## Summary + :::tip[Summary] Plugins are configured with two distinct types of files: - `config` files are dynamically loaded and parsed by the plugin -- `entry` files are statically analyzed by Knip to create a comprehensive - dependency graph -- Both can result in additional entry files and dependencies +- `entry` files are added to the module dependency graph +- Both can recursively lead to additional entry files, config files and + dependencies ::: @@ -299,6 +313,7 @@ Plugins are configured with two distinct types of files: [3]: ../guides/writing-a-plugin.md [4]: #configuration-files [5]: #entry-files -[6]: ./entry-files.md -[7]: ../reference/plugins/eslint.md -[8]: ../features/script-parser.md +[6]: #command-line-arguments +[7]: ./entry-files.md +[8]: ../reference/plugins/eslint.md +[9]: ../features/script-parser.md diff --git a/packages/docs/src/content/docs/explanations/why-use-knip.md b/packages/docs/src/content/docs/explanations/why-use-knip.md index 3143c754f..c0e96780c 100644 --- a/packages/docs/src/content/docs/explanations/why-use-knip.md +++ b/packages/docs/src/content/docs/explanations/why-use-knip.md @@ -71,8 +71,9 @@ strategy that addresses all of files, dependencies and exports is in their synergy: - Utilizing plugins to find their dependencies includes the capacity to find - additional entry files. This results in more resolved and used files. Better - coverage gives better insights into unused files and exports. + additional entry and configuration files. This results in more resolved and + used files. Better coverage gives better insights into unused files and + exports. - Analyzing more files reveals more unused exports and dependency usage, refining the list of both unused and unlisted dependencies. - This approach is amplified in a monorepo setting. In fact, files and internal diff --git a/packages/docs/src/content/docs/features/script-parser.md b/packages/docs/src/content/docs/features/script-parser.md index 8801adf4b..f54acc715 100644 --- a/packages/docs/src/content/docs/features/script-parser.md +++ b/packages/docs/src/content/docs/features/script-parser.md @@ -54,11 +54,14 @@ 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. -### Scripts parsing +### package.json -When parsing the `scripts` entries of `package.json`, Knip detects dependencies -of `-r`, `--require`, `--loader` or `--import` arguments. It also recognizes -configuration files. Example: +When parsing the `scripts` entries of `package.json`, 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 { @@ -74,11 +77,13 @@ configuration files. Example: This will have `tsx` marked as a referenced dependency, and adds `run.ts` as an entry file. -The following files are also detected as configuration files: +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 +The arguments are defined in plugins separately for fine-grained results. + ## Plugins Some plugins also use the script parser to extract entry files and dependencies @@ -93,6 +98,12 @@ from commands. A few examples: scripts - Release It: `hooks` contain commands +Plugins can also return configuration files. Some examples: + +- The Angular 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 diff --git a/packages/docs/src/content/docs/reference/faq.md b/packages/docs/src/content/docs/reference/faq.md index b685801df..9e50dac30 100644 --- a/packages/docs/src/content/docs/reference/faq.md +++ b/packages/docs/src/content/docs/reference/faq.md @@ -23,7 +23,7 @@ docs. Plugins are an essential part of Knip. They prevent you from a lot of configuration out of the box, by adding entry files as accurately as possible and only for the tools actually installed. Yet the real magic is in their custom -parsers for configuration files. +parsers for configuration files and command-line argument definitions. For instance, Vitest has the `environment` configuration option. The Vitest plugin knows `"node"` is the default value for `environment` which does not @@ -48,7 +48,8 @@ resolution and not only static but also dynamic analysis (i.e. actually load and execute modules), such as for parsers of plugins to receive the exported value of dynamic tooling configuration files. Additionally, [exports consumed by external libraries][1] require type information, as supported by the TypeScript -backend. +backend. Last but not least, shell script parsing is required to find the right +entry files, configuration files and dependencies accurately. The rippling effect of plugins and recursively adding entry files and dependencies to build up the graph is also exactly what's meant by