feat: adds skipAnalysisNotInRules option (schema, types and docs)

sverweij · Jan 4, 2025 · 5567905 · 5567905
1 parent d2550e4
commit 5567905
Show file tree

Hide file tree

Showing 8 changed files with 52 additions and 6 deletions.
diff --git a/doc/options-reference.md b/doc/options-reference.md
@@ -36,6 +36,7 @@
   - [enhancedResolveOptions](#enhancedresolveoptions)
   - [forceDeriveDependents](#forcederivedependents)
   - [experimentalStats](#experimentalstats)
+  - [skipAnalysisNotInRules](#skipanalysisnotinrules)
   - [parser](#parser)
   - [cache](#cache)
   - [progress](#progress)
@@ -1679,6 +1680,19 @@ in the result for each module. This feature is not yet used by any of the
 reporters dependency-cruiser ships with. The feature is also _experimental_
 which means it might disappear or change in the future.
 
+### `skipAnalysisNotInRules`
+
+When this flag is set to `true`, dependency-cruiser will skip all analysis that 
+don't serve a rule. E.g. if there's no 'circular' rule in the rule set it won't 
+analyse cycles. This flag affects cycle, dependents, orphan, and reachability 
+analysis. If you have a rule set that doesn't use one of these features, 
+switching it to true will make cruises faster. 
+
+Defaults to `false` for backwards compatibility. However, we recommend to switch 
+this option to `true`, unless you have a specific use case (i.e. use the json
+output for further analysis, using the API).
+
+
 ### `parser`
 
 With this _EXPERIMENTAL_ feature you can specify which parser you want to use

diff --git a/src/schema/configuration.schema.json b/src/schema/configuration.schema.json
diff --git a/src/schema/configuration.schema.mjs b/src/schema/configuration.schema.mjs
diff --git a/src/schema/cruise-result.schema.json b/src/schema/cruise-result.schema.json
diff --git a/src/schema/cruise-result.schema.mjs b/src/schema/cruise-result.schema.mjs
diff --git a/tools/schema/options-used.mjs b/tools/schema/options-used.mjs
@@ -64,6 +64,9 @@ export default {
         experimentalStats: {
           type: "boolean",
         },
+        skipAnalysisNotInRules: {
+          type: "boolean",
+        },
         // for backwards compatibility reasons can be either a string, false
         // or an object in the input, but for internal processing and output
         // always put as an object

diff --git a/tools/schema/options.mjs b/tools/schema/options.mjs
@@ -434,6 +434,17 @@ export default {
             "Will be renamed when the 'experimental' state is lifted. " +
             "Defaults to false.",
         },
+        skipAnalysisNotInRules: {
+          type: "boolean",
+          description:
+            "When this flag is set to true, dependency-cruiser will skip all analysis " +
+            "that don't serve a rule. E.g. if there's no 'circular' rule in the rule set " +
+            "it won't analyse cycles. This flag affects cycle, dependents, orphan, and " +
+            "reachability analysis. If you have a rule set that doesn't use one of these " +
+            "features, switching it to true will make cruises faster. " +
+            "Defaults to false for backwards compatibility. For most uses of dependency-cruiser " +
+            "we recommend to switch this option to true, though.",
+        },
         baseDir: {
           type: "string",
           description:

diff --git a/types/options.d.mts b/types/options.d.mts
@@ -383,13 +383,26 @@ export interface ICruiseOptions {
   metrics?: boolean;
 
   /**
-   * When this flag is set to true, dependency-cruiser will calculate some " +
-   * stats for each module. Has some performance impact. EXPERIMENTAL " +
-   * Will be renamed when the 'experimental' state is lifted." +
-   * Defaults to false.",*
+   * When this flag is set to true, dependency-cruiser will calculate some
+   * stats for each module. Has some performance impact. EXPERIMENTAL
+   * Will be renamed when the 'experimental' state is lifted.
+   *
+   * Defaults to false.
    */
   experimentalStats?: boolean;
 
+  /**
+   * When this flag is set to true, dependency-cruiser will skip all analysis
+   * that don't serve a rule. E.g. if there's no 'circular' rule in the rule set
+   * it won't analyse cycles. This flag affects cycle, dependents, orphan, and
+   * reachability analysis. If you have a rule set that doesn't use one of these
+   * features, switching it to true will make cruises faster.
+   *
+   * Defaults to false for backwards compatibility - for most uses of
+   * dependency-cruiser we recommend to switch this option to true, though.
+   */
+  skipAnalysisNotInRules?: boolean;
+
   /**
    * - false: don't use caching.
    * - true or empty object: use caching with the default settings