Add circular dependencies as opt-in cycles issue type (resolve #1734) (#1812)

Author: webpro

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

@@ -10,10 +10,11 @@ Knip provides the following built-in reporters:
 - [`codeclimate`][1]
 - [`codeowners`][2]
 - `compact`
-- [`disclosure`][3]
-- [`github-actions`][4]
-- [`json`][5]
-- [`markdown`][6]
+- [`cycles`][3]
+- [`disclosure`][4]
+- [`github-actions`][5]
+- [`json`][6]
+- [`markdown`][7]
 - `symbols` (default)
 
 Example usage:
@@ -54,16 +55,44 @@ $ knip --reporter codeclimate
 ### CODEOWNERS
 
 When a `.github/CODEOWNERS` file exists, each entry gains an `owners` array.
-Point the reporter at a different path through [`--reporter-options`][7]:
+Point the reporter at a different path through [`--reporter-options`][8]:
 
 ```sh
 knip --reporter json --reporter-options '{"codeowners":"docs/CODEOWNERS"}'
 ```
 
-For a typed object instead of JSON to parse, write a [custom reporter][8].
-Coding agents can also call Knip through the [MCP server][9], which returns
+For a typed object instead of JSON to parse, write a [custom reporter][9].
+Coding agents can also call Knip through the [MCP server][10], which returns
 structured results and configuration hints directly.
 
+### Cycles
+
+A verbose, multi-line tree view of [circular dependencies][11]. Each file path
+is suffixed with the location of the import that continues the cycle. Each edge
+shows the import kind and specifier, descends one file per level, and closes
+(`↩`) back to the file it started from. Enable the `cycles` issue type (e.g.
+with `--cycles`) and select the reporter:
+
+```text
+$ knip --cycles --reporter cycles
+
+Circular dependencies (1)
+
+src/i18n/index.ts:1:28
+└── import ./middleware → src/i18n/middleware.ts:3:15
+    └── re-export ../core/i18n/handler → src/core/i18n/handler.ts:5:10
+        └── import ../../i18n → src/i18n/index.ts:1:28 ↩
+```
+
+Knip reports representative cycle paths found while walking the module graph.
+This is not an exhaustive list of every possible simple cycle in a cyclic
+subgraph, because that can produce a noisy and very large report. If the same
+file participates in multiple distinct reported paths, each path is shown
+separately. Dynamic imports are ignored by default because they are commonly
+used to avoid synchronous circular loads; set [`cycles.dynamicImports`][12] to
+include them. Repeated starting imports are grouped under one heading. Use
+[`cycles.allow`][12] to accept known cycle paths.
+
 ### Disclosure
 
 This reporter is useful for sharing large reports. Groups of issues are rendered
@@ -169,9 +198,9 @@ every issue found in one file:
 | `owners`     | `{ name }[]` | Code owners, only when a `CODEOWNERS` file is found |
 | _issue type_ | array        | One key per enabled issue type (see below)          |
 
-Each entry carries a key for **every enabled [issue type][10]**, so the keys are
+Each entry carries a key for **every enabled [issue type][11]**, so the keys are
 the same across entries. An array is empty when that file has no issues of that
-type. Drop a type's key by disabling it with [filters or rules][11].
+type. Drop a type's key by disabling it with [filters or rules][13].
 
 Issue-type items are objects with position info:
 
@@ -183,7 +212,7 @@ Issue-type items are objects with position info:
 | `col`       | `number?` | 1-based column                                 |
 | `pos`       | `number?` | Character offset                               |
 
-See [Issue types][10] for the full set of issue-type keys.
+See [Issue types][11] for the full set of issue-type keys.
 
 ### Markdown
 
@@ -311,12 +340,14 @@ knip --preprocessor ./preprocess.ts
 
 [1]: #codeclimate
 [2]: #codeowners
-[3]: #disclosure
-[4]: #github-actions
-[5]: #json
-[6]: #markdown
-[7]: ../reference/cli.md#--reporter-options-json
-[8]: #custom-reporters
-[9]: ../reference/integrations.md
-[10]: ../reference/issue-types.md
-[11]: ./rules-and-filters.md
+[3]: #cycles
+[4]: #disclosure
+[5]: #github-actions
+[6]: #json
+[7]: #markdown
+[8]: ../reference/cli.md#--reporter-options-json
+[9]: #custom-reporters
+[10]: ../reference/integrations.md
+[11]: ../reference/issue-types.md
+[12]: ../reference/configuration.md#cycles
+[13]: ./rules-and-filters.md

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

@@ -56,6 +56,9 @@ Knip has shortcuts to include only specific issue types.
 
 3. The `--files` flag is a shortcut for `--include files`
 
+4. The `--cycles` flag is a shortcut for `--include cycles` (circular
+   dependencies, off by default)
+
 ## Rules
 
 Use `rules` in the configuration to customize the issue types that count towards

packages/docs/src/content/docs/reference/cli.md

@@ -233,6 +233,14 @@ Shortcut to include file issues:
 --include files
 ```
 
+### `--cycles`
+
+Shortcut to include circular dependencies (off by default):
+
+```sh
+--include cycles
+```
+
 ### `--tags`
 
 Exports can be tagged with known or arbitrary JSDoc/TSDoc tags:

packages/docs/src/content/docs/reference/configuration.md

@@ -386,6 +386,27 @@ reporting other issues in those same files.
 }
 ```
 
+### `cycles`
+
+Configure circular dependency (`cycles`) detection.
+
+Set `dynamicImports` to include dynamic `import()` edges, which are excluded by
+default (a dynamic import defers evaluation, so it does not cause the
+initialization hazard cycles are meant to catch).
+
+Use `allow` to accept specific cycles by exact path while keeping other `cycles`
+issues enabled. Path entries are relative to the project root and omit the
+closing repeat of the first file.
+
+```json title="knip.json"
+{
+  "cycles": {
+    "dynamicImports": true,
+    "allow": [["src/i18n/index.ts", "src/i18n/middleware.ts"]]
+  }
+}
+```
+
 ## Exports
 
 ### `ignoreExportsUsedInFile`

packages/docs/src/content/docs/reference/issue-types.md

@@ -23,6 +23,7 @@ Knip reports the following types of issues:
 | Unused exported enum members         | Unable to find a reference to this enum member             | 🔧    | `enumMembers`      |
 | Unused exported namespace members    | Unable to find a reference to this namespace member        | 🔧    | `namespaceMembers` |
 | Duplicate exports                    | This is exported more than once                            |       | `duplicates`       |
+| Circular dependencies                | These files (in)directly import each other at runtime      | 🟠    | `cycles`           |
 
 ## Legend
 
@@ -39,6 +40,8 @@ Knip reports the following types of issues:
    `optionalPeerDependencies`. In [rules][3], each key can be set individually.
 3. In [strict production mode][4], `devDependencies` are not included.
 4. The `types` issue type includes `enum`, `interface` and `type` exports.
+5. `cycles` defaults to the `warn` [rule][3] (reported, but not counted as an
+   error). Set `rules.cycles` to `error` to fail on circular dependencies.
 
 [1]: ../features/auto-fix.mdx
 [2]: ../features/rules-and-filters.md#filters

packages/docs/src/content/docs/reference/related-tooling.md

@@ -28,22 +28,23 @@ values and types on imported namespaces.
 
 ## Circular dependencies
 
-See [Circular Dependencies][5].
-
-Other tools that support this include [DPDM][6], [Madge][7] and [skott][8].
+Knip detects circular dependencies as an opt-in [`cycles`][5] issue type, and
+the [editor integrations][6] visualize them inline. Other dedicated tools
+include [DPDM][7], [Madge][8] and [skott][9].
 
 ## Cleanup
 
-The [e18e.dev][9] website and in particular the [Cleanup][10] section is a great
-resource when dealing with technical debt.
+The [e18e.dev][10] website and in particular the [Cleanup][11] section is a
+great resource when dealing with technical debt.
 
 [1]: https://eslint.org
 [2]: https://biomejs.dev/linter/
 [3]: https://oxc.rs/docs/guide/usage/linter.html
 [4]: https://github.com/webpro-nl/remove-unused-vars
-[5]: ./integrations.md#circular-dependencies
-[6]: https://github.com/acrazing/dpdm
-[7]: https://github.com/pahen/madge
-[8]: https://github.com/antoine-coulon/skott
-[9]: https://e18e.dev
-[10]: https://e18e.dev/guide/cleanup.html
+[5]: ./issue-types.md
+[6]: ./integrations.md
+[7]: https://github.com/acrazing/dpdm
+[8]: https://github.com/pahen/madge
+[9]: https://github.com/antoine-coulon/skott
+[10]: https://e18e.dev
+[11]: https://e18e.dev/guide/cleanup.html

packages/knip/fixtures/imports/circular-dependencies/allow-cycle-path.json

@@ -0,0 +1,5 @@
+{
+  "cycles": {
+    "allow": [["apricot.ts", "banana.ts"]]
+  }
+}

packages/knip/fixtures/imports/circular-dependencies/apricot.ts

@@ -0,0 +1,3 @@
+import { banana } from './banana';
+
+export const apricot = () => banana();

packages/knip/fixtures/imports/circular-dependencies/banana.ts

@@ -0,0 +1,3 @@
+import { apricot } from './apricot';
+
+export const banana = () => apricot();

packages/knip/fixtures/imports/circular-dependencies/citrus.ts

@@ -0,0 +1,3 @@
+import { lemon } from './lemon';
+
+export const citrus = () => lemon;