Update docs, add "configuring project files"

packages/docs/src/content/docs/explanations/entry-files.md

@@ -4,15 +4,13 @@ sidebar:
   order: 1
 ---
 
-## Introduction
-
 Entry files are the starting point for Knip to determine what files are used in
 the codebase. More entry files lead to increased coverage of the codebase. This
 also leads to more dependencies to be discovered. This page explains how Knip
 and its plugins try to find entry files so you don't need to configure them
 yourself.
 
-## Default Entry File Patterns
+## Default entry file patterns
 
 For brevity, the [default configuration][1] on the previous page mentions only
 `index.js` and `index.ts`, but the default set of file names and extensions is
@@ -46,7 +44,7 @@ The `main`, `bin`, and `exports` fields may contain entry files. The `scripts`
 are also parsed to find entry files and dependencies. See [Script Parser][2] for
 more details.
 
-## Ignored Files
+## Ignored files
 
 Knip respects `.gitignore` files. By default, ignored files are not added as
 entry files. This behavior can be disabled by using the [`--no-gitignore`][3]
@@ -60,10 +58,12 @@ Glob patterns can also be negated, for example:
 }
 ```
 
-If issues for a certain file should not be reported, use the [ignore][4]
-configuration option.
+## Configuring project files
+
+See [configuring project files][4] for guidance with the `entry`, `project` and
+`ignore` options.
 
 [1]: ../overview/configuration.md#defaults
 [2]: ../features/script-parser.md
 [3]: ../reference/cli.md#--no-gitignore
-[4]: ../reference/configuration.md#ignore
+[4]: ../guides/configuring-project-files.md

packages/docs/src/content/docs/explanations/plugins.md

@@ -4,8 +4,6 @@ sidebar:
   order: 2
 ---
 
-## Introduction
-
 This page describes why Knip uses plugins and the difference between `config`
 and `entry` files.
 
@@ -18,7 +16,7 @@ Plugins are enabled if the related package is listed in the list of dependencies
 in `package.json`. For instance, if `astro` is listed in `dependencies` or
 `devDependencies`, then the Astro plugin is enabled.
 
-## Configuration Files
+## Configuration files
 
 Knip uses [entry files][2] as starting points to scan your source code and
 resolve other internal files and external dependencies. The dependency graph can
@@ -54,7 +52,7 @@ this to determine the unused and unlisted dependencies.
 
 :::
 
-## Entry Files
+## Entry files
 
 Many plugins have default `entry` files configured. When the plugin is enabled,
 Knip will add entry files as configured by the plugin to resolve used files and
@@ -113,7 +111,7 @@ Plugins try hard to automatically add the correct entry files.
 
 :::
 
-## Entry Files From Config Files
+## Entry files from config files
 
 Entry files are part of plugin configuration (as described in the previous
 section). Yet plugins can also return additional entry files after parsing
@@ -201,7 +199,7 @@ Plugins can find additional entry files when parsing config files.
 
 :::
 
-## Bringing It All Together
+## Bringing it all together
 
 Sometimes a configuration file is a JavaScript or TypeScript file that imports
 dependencies, but also contains configuration that needs to be parsed by a

packages/docs/src/content/docs/features/compilers.md

@@ -8,7 +8,7 @@ like `.mdx`, `.astro`, `.vue` and `.svelte` may also import other source files
 and external dependencies. So ideally, these files are included when linting the
 project. That's why Knip supports compilers.
 
-## Built-in Compilers
+## Built-in compilers
 
 Knip has built-in "compilers" for the following file extensions:
 
@@ -29,7 +29,7 @@ reported as unused by Knip.
 In short, the built-in functions seem to do a decent job, but you can override
 them however you like.
 
-## Custom Compilers
+## Custom compilers
 
 Additional custom compilers can be added, and built-in compilers can be
 overridden. Since compilers are functions, the Knip configuration file must be a

packages/docs/src/content/docs/features/integrated-monorepos.md

@@ -10,9 +10,8 @@ integrated monorepo style][1].
 
 Let's assume some of these projects are applications ("apps") which have their
 own ESLint configuration files and Cypress configuration and test files. This
-may result in a those files reported as unused, and consequently also the
-dependencies the ESLint and Cypress plugins would find (such as ESLint or
-Cypress plugins).
+may result in those files getting reported as unused, and consequently also the
+dependencies they import and refer to.
 
 In that case, we could configure the ESLint and Cypress plugins like this:
 
@@ -27,7 +26,7 @@ In that case, we could configure the ESLint and Cypress plugins like this:
 }
 ```
 
-Adapt the file patterns to your project and the relevant configuration and entry
+Adapt the file patterns to your project, and the relevant `config` and `entry`
 files and dependencies should no longer be reported as unused.
 
 [1]: https://nx.dev/getting-started/tutorials/integrated-repo-tutorial

packages/docs/src/content/docs/features/monorepos-and-workspaces.md

@@ -46,8 +46,8 @@ above).
 
 :::caution
 
-In a project with workspaces, customized `entry` and `project` options at the
-root level are ignored, they must be moved to the `"."` workspace.
+In a project with workspaces, the `entry` and `project` options at the root
+level are ignored. Use the workspace named `"."` for those.
 
 :::
 

packages/docs/src/content/docs/features/production-mode.md

@@ -4,8 +4,6 @@ sidebar:
   order: 1
 ---
 
-## Introduction
-
 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

packages/docs/src/content/docs/features/rules-and-filters.md

@@ -72,7 +72,7 @@ Also see the [issue types overview][1].
 The rules are modeled after the ESLint `rules` configuration, and could be
 extended in the future.
 
-## Rules or Filters?
+## Rules or filters?
 
 Filters are meant to be used as command-line flags, rules allow for more
 fine-grained configuration.

packages/docs/src/content/docs/features/script-parser.md

@@ -2,8 +2,6 @@
 title: Script Parser
 ---
 
-## Introduction
-
 Knip parses scripts to find additional dependencies and entry files in various
 places:
 

packages/docs/src/content/docs/guides/configuring-project-files.md

@@ -0,0 +1,164 @@
+---
+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 get the most value and performance
+out of Knip.
+
+The key takeaways of this page include:
+
+- Start out by defining targeted `entry` and `project` files (if the defaults
+  aren't good enough).
+- To exclude test and other non-production files, use production mode.
+- Don't use `ignore` to exclude files from the analysis, but add negated `entry`
+  and `project` files instead.
+- Use `ignore` patterns only to exclude issues in matching files from the
+  report.
+
+Let's dive in and take a look at a few examples.
+
+## Unused files
+
+Files are reported as unused if they are in the set of project files, but not in
+the set of files resolved from the entry files:
+
+```
+project files - (entry files + resolved files) = unused files
+```
+
+You may want to read the [entry files][1] explainer first to learn how and where
+Knip looks for entry files.
+
+## Negated patterns
+
+Let's take a look at using negated patterns in `entry` and `project` patterns.
+If there are too many files in the analysis, this could be the first step in
+getting the right files in the analysis.
+
+Say we need to explicitly add route files as entry files, except those starting
+with an underscore. Then we can use a negated pattern like so:
+
+```json
+{
+  "entry": ["src/routes/*.ts", "!src/routes/_*.ts"]
+}
+```
+
+If certain files are not part of our project files and are unwantedly reported
+as unused files, we can use negated `project` patterns:
+
+```json
+{
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts", "!src/exclude/**"]
+}
+```
+
+By the way, we don't want to simply add all files as entry files for two
+reasons:
+
+1. Knip does not report unused exports in entry files.
+2. Configuring `entry` and `project` files properly allows Knip to find unused
+   files.
+
+## Ignore issues in specific files
+
+Use `ignore` if a certain file contain unused exports that we want to ignore.
+For example, this might happen with a generated file that exports "everything"
+and we don't want the unused exports of this file to be reported:
+
+```json
+{
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"],
+  "ignore": ["src/generated.ts"]
+}
+```
+
+## Exclude non-production files
+
+In default mode, Knip includes all test files and other non-production files in
+the analysis. To find out what files, dependencies and exports are unused in
+production source files, use [production mode][2].
+
+How NOT to exclude test files from the analysis? To better understand how Knip
+works, here's a list of options that don't work, and why.
+
+❌ Don't do this:
+
+```json
+{
+  "ignore": ["**/*.test.js"]
+}
+```
+
+This is not a good idea, since `ignore` patterns have only one goal: to exclude
+issues in matching files from the report. Files matching `ignore` patterns are
+not excluded from the analysis, only their issues are not reported. This also
+hurts performance, since the files are first analyzed, and eventually filtered
+out.
+
+❌ Also don't do this:
+
+```json
+{
+  "entry": ["!**/*.test.js"]
+}
+```
+
+This won't help if dependencies like Vitest or Ava are listed, because their
+plugins will add test files as entry files anyway, which you can't and shouldn't
+undo or override here.
+
+❌ Also don't do this:
+
+```json
+{
+  "project": ["!**/*.spec.ts"]
+}
+```
+
+This won't help either:
+
+1. The set of `project` files have only one goal: to find unused files. Negated
+   `project` patterns do not exclude files from the analysis.
+2. Enabled plugins add (test) files as entry files, and their configuration
+   remains unaffected. You'd need to disable the plugin or override its
+   configuration instead.
+
+✅ Do this:
+
+```shell
+knip --production
+```
+
+This will exclude test files from the analysis, so you can focus on production
+code.
+
+Now, Knip might still report certain files like test utilities as unused. That's
+because they're still part of the set of `project` files. Those files should
+then be excluded in production mode:
+
+```json
+{
+  "entry": ["src/index.ts!"],
+  "project": ["src/**/*.ts!", "!src/test-helpers/**!"]
+}
+```
+
+Remember to keep adding the exclamation mark `suffix!` for production file
+patterns.
+
+In large projects where a single configuration for both default and production
+mode gets unwieldy, it might be interesting to consider using a separate
+configuration file for production mode:
+
+```shell
+knip --production --config knip.production.json
+```
+
+[1]: ../explanations/entry-files.md
+[2]: ../features/production-mode.md