Add contents section to more docs + minor edits

.vscode/settings.json

@@ -3,6 +3,8 @@
   "markdown.extension.toc.levels": "2..3",
   "markdown.extension.toc.omittedFromToc": {
     "README.md": ["## Contents"],
-    "docs/reporters-and-preprocessors.md": ["## Contents"]
+    "docs/handling-issues.md": ["## Contents"],
+    "docs/reporters-and-preprocessors.md": ["## Contents"],
+    "docs/writing-a-plugin.md": ["## Contents"]
   }
 }

docs/handling-issues.md

@@ -3,6 +3,16 @@
 How to handle reported issues? A long list of reported issues with many false positives may be caused by several things.
 This document aims to help out with handling all of that.
 
+## Contents
+
+- [Unused files][1]
+- [Unused dependencies][2]
+- [Unlisted dependencies][3]
+- [Unlisted binaries][4]
+- [npx][5]
+- [Unused exports][6]
+- [Start using Knip in CI with lots of reported issues][7]
+
 ## Unused files
 
 Here are a few things to consider when Knip reports unused files:
@@ -14,12 +24,13 @@ Here are a few things to consider when Knip reports unused files:
   happens when a tool or framework has its own locations regarding entry files. For example, Next.js has `pages/**/*.js`
   and Remix has `app/routes/**/*.ts`. Potential solutions:
 
-  - [Override plugin configuration][1] to customize default patterns for existing plugins.
-  - [Create a new plugin][2] for tools or frameworks that are not [in the list][3] yet (or open an issue to request it).
+  - [Override plugin configuration][8] to customize default patterns for existing plugins.
+  - [Create a new plugin][9] for tools or frameworks that are not [in the list][10] yet (or open an issue to request
+    it).
   - In the meantime, such file patterns can be added manually to the `entry` patterns of any workspace
 
 - When working in a repository that is not a package-based monorepo and contains many configuration files across the
-  repository, see [multi-project repositories][4] to also match those files.
+  repository, see [multi-project repositories][11] to also match those files.
 
 - Files and/or directories should be ignored when they are not used by other source code and configuration files. Or
   when they are magically imported by other tooling, such as fixtures, mocks or templates. Here are a few examples of
@@ -51,15 +62,15 @@ Here are a few things to consider when Knip reports unused files:
 Dependencies imported in unused files are reported as unused dependencies. So it's good to remedy too many unused files
 first.
 
-- If unused dependencies are related to dependencies having a Knip [plugin][3], the `config` and/or `entry` files for
+- If unused dependencies are related to dependencies having a Knip [plugin][10], the `config` and/or `entry` files for
   that dependency may be at custom locations. The default values are in the plugin's documentation and can be overridden
   to match the custom path(s).
 
 - If a dependency doesn't have a Knip plugin yet, this might result in false positives. For instance, when
   `tool.config.js` refers to `@tool/package` then this dependency will be reported as an unused. Please file an issue or
-  [create a new plugin][2].
+  [create a new plugin][9].
 
-- Dependencies might be imported only from files with extensions like `.mdx`, `.vue` or `.svelte`. See [compilers][5]
+- Dependencies might be imported only from files with extensions like `.mdx`, `.vue` or `.svelte`. See [compilers][12]
   for more details on how to include them.
 
 - Problematic dependencies can be ignored:
@@ -83,17 +94,20 @@ which in turn has `micromatch` as a (transitive) dependency. Knip uses both `fas
 
 Binaries are supposed to come from listed (dev) dependencies. Binaries not in the `bin` field of any those
 `package.json` files will be reported as unlisted binaries, except for those listed as `IGNORED_GLOBAL_BINARIES` in
-[constants.ts][6].
+[constants.ts][13].
 
 Sometimes binaries are used like `commitlint`, but listed as `@commitlint/cli` in `devDependencies`. When the command
 looks like `npx commitlint` or `commitlint`, `@commitlint/cli` might be reported as unused and `commitlint` as unlisted
 (as it's technically a transitive dependency). This can usually be prevented by using the same package name in both
 locations.
 
-### npx
+## npx
+
+For `npx` scripts, Knip assumes that `--yes` (as in `npx --yes package`) means that the package is not listed. Knip
+expects the dependency to be listed with `--no` or no flag at all.
 
-For `npx` scripts, Knip assumes with `--yes` (as in `npx --yes package`) that the package is not listed. Knip expects
-the package to be listed with `--no` or no flag at all.
+The recommendation here is to be explicit: use `--yes` if the dependency is not supposed to be listed in `package.json`
+(and vice versa).
 
 ## Unused exports
 
@@ -105,8 +119,8 @@ consider in this case:
 - Move the export(s) to an entry file.
 - Add the containing file to the `entry` array in the configuration.
 - Re-export the export(s) from an existing entry file.
-- Mark the export(s) [using the JSDoc `@public` tag][7].
-- [Ignore exports used in file][8].
+- Mark the export(s) [using the JSDoc `@public` tag][14].
+- [Ignore exports used in file][15].
 
 Note that entries in the `exports` map in `package.json` are automatically added as entry files by Knip (except when
 they are ignored by a `.gitignore` entry).
@@ -116,20 +130,27 @@ they are ignored by a `.gitignore` entry).
 This type of QA only really works when it's tied to an automated workflow. But with too many issues to resolve in a
 large codebase this might not be feasible right away. Here are a few options that may help in the meantime:
 
-- Use `--no-exit-code` for exit code 0 in CI.
-- Use `--include` (or `--exclude`) [output filters][9] to report only the issue types that have little or no errors.
-- Use [`rules`][10] configuration to report only the issue types that have little or no errors.
+- Use `--no-exit-code` for exit code `0` in CI.
+- Use `--include` (or `--exclude`) [output filters][16] to report only the issue types that have little or no errors.
+- Use [`rules`][17] configuration to report only the issue types that have little or no errors.
 - Use separate Knip commands to analyze e.g. only `--dependencies` or `--exports`.
-- Use [ignore patterns][11] to filter out the most problematic areas.
-
-[1]: ../README.md#override-plugin-configuration
-[2]: ./writing-a-plugin.md
-[3]: ../README.md#plugins
-[4]: ../README.md#multi-project-repositories
-[5]: ./compilers.md
-[6]: ../src/constants.ts
-[7]: ../README.md#public-exports
-[8]: ../README.md#ignore-exports-used-in-file
-[9]: ../README.md#filters
-[10]: ../README.md#rules
-[11]: ../README.md#ignore
+- Use [ignore patterns][18] to filter out the most problematic areas.
+
+[1]: #unused-files
+[2]: #unused-dependencies
+[3]: #unlisted-dependencies
+[4]: #unlisted-binaries
+[5]: #npx
+[6]: #unused-exports
+[7]: #start-using-knip-in-ci-with-lots-of-reported-issues
+[8]: ../README.md#override-plugin-configuration
+[9]: ./writing-a-plugin.md
+[10]: ../README.md#plugins
+[11]: ../README.md#multi-project-repositories
+[12]: ./compilers.md
+[13]: ../src/constants.ts
+[14]: ../README.md#public-exports
+[15]: ../README.md#ignore-exports-used-in-file
+[16]: ../README.md#filters
+[17]: ../README.md#rules
+[18]: ../README.md#ignore

docs/writing-a-plugin.md

@@ -17,11 +17,13 @@ This document also serves as a reference to each of the exported values.
   - [`isEnabled`][8]
   - [`CONFIG_FILE_PATTERNS`][9]
   - [`findDependencies`][10]
-  - [`ENTRY_FILE_PATTERNS`][11]
-  - [`PRODUCTION_ENTRY_FILE_PATTERNS`][12]
-  - [`PROJECT_FILE_PATTERNS`][13]
-- [Tests][14]
-- [Documentation][15]
+  - [Notes][11]
+  - [`ENTRY_FILE_PATTERNS`][12]
+  - [`PRODUCTION_ENTRY_FILE_PATTERNS`][13]
+  - [`PROJECT_FILE_PATTERNS`][14]
+- [Tests][15]
+- [Documentation][16]
+- [Wrapping Up][17]
 
 ## Scaffold a new plugin
 
@@ -41,7 +43,7 @@ or empty can be removed.
 
 ### `NAME`
 
-The name of the plugin to display in the [docs][16] and debug output (ie. when running `knip --debug`).
+The name of the plugin to display in the [docs][18] and debug output (ie. when running `knip --debug`).
 
 ```ts
 export const NAME = 'Cool Linter';
@@ -70,7 +72,7 @@ This will check whether a match is found in the `dependencies` or `devDependenci
 #### Note
 
 In some cases, you might want to check for something else, such as the presence of a file. You can implement any
-(`async`) function and return a boolean. Here is the full [function signature for `IsPluginEnabledCallback`][17].
+(`async`) function and return a boolean. Here is the full [function signature for `IsPluginEnabledCallback`][19].
 
 ### `CONFIG_FILE_PATTERNS`
 
@@ -100,7 +102,7 @@ the file path as the first argument.
 
 Configuration files are sometimes `.js` or `.ts` files such as `cool-linter.config.js`. The **exported configuration**
 will be handled by `findDependencies`. But these files may also **require/import** dependencies. That's why they're also
-automatically added to [`ENTRY_FILE_PATTERNS`][11].
+automatically added to [`ENTRY_FILE_PATTERNS`][12].
 
 ### `findDependencies`
 
@@ -181,7 +183,7 @@ export const PRODUCTION_ENTRY_FILE_PATTERNS = [
 ];
 ```
 
-When running the [production mode][18] of Knip, these files are included in the analysis. They're also included in the
+When running the [production mode][20] of Knip, these files are included in the analysis. They're also included in the
 default mode.
 
 Cool Linter does not require such files, so we can remove them from our plugin.
@@ -205,7 +207,7 @@ Let's update the tests to verify our plugin implementation is working correctly.
 1.  Let's save the example `cool-linter.config.json` in the fixtures directory. Create the file in your IDE, and save it
     at `fixtures/plugins/cool-linter/cool-linter.config.json`.
 
-2.  Update the test at [tests/plugins/cool-linter.test.ts][19]:
+2.  Update the test at `tests/plugins/cool-linter.test.ts`:
 
 ```ts
 test('Find dependencies in cool-linter configuration (json)', async () => {
@@ -240,7 +242,7 @@ This command also formats the generated Markdown files and updates the [list of
 Thanks for reading this far. If you have been following this guide to create a new plugin, this might be the right time
 to open a pull request!
 
-[![An orange cow with scissors, Van Gogh style][21]][20] <sup>_“An orange cow with scissors, Van Gogh style” - generated
+[![An orange cow with scissors, Van Gogh style][22]][21] <sup>_“An orange cow with scissors, Van Gogh style” - generated
 with OpenAI_</sup>
 
 [1]: ../README.md#plugins
@@ -253,14 +255,15 @@ with OpenAI_</sup>
 [8]: #isenabled
 [9]: #config_file_patterns
 [10]: #finddependencies
-[11]: #entry_file_patterns
-[12]: #production_entry_file_patterns
-[13]: #project_file_patterns
-[14]: #tests
-[15]: #documentation
-[16]: ../README.md
-[17]: ../src/types//plugins.ts
-[18]: ../README.md#production-mode
-[19]: ../tests/plugins/cool-linter.test.ts
-[20]: https://labs.openai.com/s/xZQACaLepaKya0PRUPtIN5dC
-[21]: ../assets/cow-with-orange-scissors-van-gogh-style.webp
+[11]: #notes
+[12]: #entry_file_patterns
+[13]: #production_entry_file_patterns
+[14]: #project_file_patterns
+[15]: #tests
+[16]: #documentation
+[17]: #wrapping-up
+[18]: ../README.md
+[19]: ../src/types//plugins.ts
+[20]: ../README.md#production-mode
+[21]: https://labs.openai.com/s/xZQACaLepaKya0PRUPtIN5dC
+[22]: ../assets/cow-with-orange-scissors-van-gogh-style.webp