Removed madge and updated readme

elastic · Nov 8, 2024 · 60103aa · 60103aa
1 parent ee0dffb
commit 60103aa
Show file tree

Hide file tree

Showing 3 changed files with 89 additions and 137 deletions.
diff --git a/packages/kbn-dependency-usage/README.md b/packages/kbn-dependency-usage/README.md
@@ -1,73 +1,106 @@
+
 # @kbn/dependency-usage
 
-#### 1. Show all packages/plugins within a directory that use a specific dependency
+A CLI tool for analyzing dependencies across packages and plugins. This tool provides commands to check dependency usage, aggregate it, debug dependency graphs, and more.
+
+---
+
+## Table of Contents
+1. [Usage](#usage)
+   - [Show all packages/plugins using a dependency](#show-all-packagesplugins-using-a-dependency)
+   - [Show dependencies grouped by code owner](#show-dependencies-grouped-by-code-owner)
+   - [List all dependencies for a package or directory](#list-all-dependencies-for-a-package-or-directory)
+   - [Group by code owner with adjustable collapse depth](#group-by-code-owner-with-adjustable-collapse-depth)
+   - [Show dependencies matching a pattern](#show-dependencies-matching-a-pattern)
+   - [Verbose flag to debug dependency graph issues](#verbose-flag-to-debug-dependency-graph-issues)
+2. [Examples](#examples)
+
+---
+
+## Usage
+
+### 1. Show all packages/plugins using a specific dependency
+
+Use this command to list all packages or plugins within a directory that use a specified dependency.
 
 ```sh
-bash scripts/dependency_usage.sh -d rxjs -p x-pack/plugins/security_solution
+bash scripts/dependency_usage.sh -d <dependency> -p <path_to_directory>
 ```
 or
-
 ```sh
-bash scripts/dependency_usage.sh --dependency-name rxjs --paths x-pack/plugins/security_solution
+bash scripts/dependency_usage.sh --dependency-name <dependency> --paths <path_to_directory>
 ```
 
 **Example**:
+```sh
+bash scripts/dependency_usage.sh -d rxjs -p x-pack/plugins/security_solution
+```
+
 - `-d rxjs`: Specifies the dependency to look for (`rxjs`).
 - `-p x-pack/plugins/security_solution`: Sets the directory to search within (`x-pack/plugins/security_solution`).
 
-#### 2. Show all packages/plugins within a directory grouped by code owner
+---
+
+### 2. Show dependencies grouped by code owner
 
-Use this command to find all packages or plugins within a directory that include a specific dependency, grouped by code owner.
+Group the dependencies used within a directory by code owner.
 
 ```sh
-bash scripts/dependency_usage.sh -d rxjs -p x-pack/plugins -g owner
+bash scripts/dependency_usage.sh -p <path_to_directory> -g owner
 ```
 or
 ```sh
-bash scripts/dependency_usage.sh --dependency-name rxjs --paths x-pack/plugins --group-by owner
+bash scripts/dependency_usage.sh --paths <path_to_directory> --group-by owner
+```
+
+**Example**:
+```sh
+bash scripts/dependency_usage.sh -p x-pack/plugins -g owner
 ```
 
-**Explanation**:
-- `-d rxjs`: Specifies the dependency to search for (`rxjs`).
 - `-p x-pack/plugins`: Sets the directory to scan for plugins using this dependency.
 - `-g owner`: Groups results by code owner.
-- **Output**: Lists plugins within `x-pack/plugins` that use `rxjs`, organized by code owner.
+- **Output**: Lists all dependencies for `x-pack/plugins`, organized by code owner.
 
 ---
 
-#### 3. Show all dependencies for a specific package/plugin or directory
+### 3. List all dependencies for source directory
 
-Use this command to display all dependencies used within a specific package, plugin, or directory.
+To display all dependencies used within a specific directory.
 
 ```sh
-bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution
+bash scripts/dependency_usage.sh -p <path_to_directory>
 ```
 or
 ```sh
-bash scripts/dependency_usage.sh --paths x-pack/plugins/security_solution
+bash scripts/dependency_usage.sh --paths <path_to_directory>
+```
+
+**Example**:
+```sh
+bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution
 ```
 
-**Explanation**:
 - `-p x-pack/plugins/security_solution`: Specifies the package or directory for which to list all dependencies.
 - **Output**: Lists all dependencies for `x-pack/plugins/security_solution`.
 
 ---
 
-#### 4. Group by code owner with adjustable collapse depth for fine-grained grouping
+### 4. Group by code owner with adjustable collapse depth
 
-When a package or plugin has multiple subteams, adjust the `--collapse-depth` option to define how granular or the grouping by code owner should be.
+When a package or plugin has multiple subteams, use the `--collapse-depth` option to control how granular the grouping by code owner should be.
 
-**Detailed Subteam Grouping**:
+#### Detailed Subteam Grouping
 Shows all subteams within `security_solution`.
 
 ```sh
 bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution -g owner --collapse-depth 4
 ```
 
-**Collapsed Grouping**:
+#### Collapsed Grouping
 Groups the results under a higher-level owner (e.g., `security_solution` as a single group).
 
-```bash
+```sh
 bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution -g owner --collapse-depth 1
 ```
 
@@ -79,46 +112,45 @@ bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution -g owner --
 
 ---
 
-#### 5. Show all dependencies matching a pattern (e.g., `react-*`) within a package
+### 5. Show dependencies matching a pattern
 
-Use this command to search for dependencies that match a specific pattern (such as `react-*`) within a package, and output the results to a specified file.
+Search for dependencies that match a specific pattern (such as `react-*`) within a package and output the results to a specified file.
 
-```bash
-bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution -d 'react-*' -o ./tmp/results.json
+```sh
+bash scripts/dependency_usage.sh -p <path_to_directory> -d '<pattern>' -o <output_file>
+```
+
+**Example**:
+```sh
+bash scripts/dependency_usage.sh -d 'react-*' -p x-pack/plugins/security_solution -o ./tmp/results.json
 ```
 
-**Explanation**:
 - `-p x-pack/plugins/security_solution`: Specifies the directory or package to search within.
 - `-d 'react-*'`: Searches for dependencies that match the pattern `react-*`.
 - `-o ./tmp/results.json`: Outputs the results to a specified file (`results.json` in the `./tmp` directory).
 - **Output**: Saves a list of all dependencies matching `react-*` in `x-pack/plugins/security_solution` to `./tmp/results.json`.
 
 ---
 
-### Using `madge` for building dependency graph
-Added for comparison. Supports only full scan for third-party dependencies, no proper groping by codeowner/package.
+### 6. Verbose flag to debug dependency graph issues
 
-By default, Madge outputs paths relative to the `baseDir`, which can vary depending on how you run the command or set the directory structure. There are multiple problems with that:
-1. `baseDir` set to `.` results in empty graph
-2. Having paths that are relative makes it challenging to perform reliable lookups or aggregations, i. e. grouping by codeowners
+Enable verbose mode to log additional details for debugging dependency graphs. This includes generating a non-aggregated dependency graph in `.dependency-graph-log.json`.
 
-#### Show all dependencies
+```sh
+bash scripts/dependency_usage.sh -p <path_to_directory> -o <output_file> -v
+```
 
+**Example**:
 ```sh
-bash scripts/dependency_usage.sh -p x-pack/plugins -o ./tmp/deps-result-madge.json -t madge
+bash scripts/dependency_usage.sh -p x-pack/plugins/security_solution -o ./tmp/results.json
 ```
+- `-p x-pack/plugins/security_solution`: Specifies the target directory or package to analyze.
+- `-o ./tmp/results.json`: Saves the output to the `results.json` file in the `./tmp` directory.
+- `-v`: Enables verbose mode.
+
+**Output**: Saves a list of all dependencies in `x-pack/plugins/security_solution` to `./tmp/results.json`. Additionally, it logs a detailed, non aggregated dependency graph to `.dependency-graph-log.json` for debugging purposes.
+
+---
+
+For further information on additional flags and options, refer to the script's inline documentation or help command.
 
-# Dependency cruiser vs Madge perf stats
-
-| Analysis                                | Real Time   | User Time   | Sys Time   |
-|-----------------------------------------|-------------|-------------|------------|
-| All plugins (dependency-cruiser)        | 7m 21.126s  | 7m 53.099s  | 20.581s    |           
-| All plugins (madge)                     | 4m 38.998s  | 4m 26.131s  | 39.043s    |           
-| Single plugin (dependency-cruiser)      | 31.360s     | 45.352s     | 2.208s     |           
-| Single plugin (madge)                   | 1m 8.398s   | 1m 14.524s  | 11.065s    |           
-| Multiple plugins (dependency-cruiser)   | 36.403s     | 50.563s     | 2.814s     |           
-| Multiple plugins (madge)                | 1m 11.620s  | 1m 18.473s  | 11.334s    |
-| x-pack/packages (dependency-cruiser)    | 6.638s      | 12.646s     | 0.654s     |
-| x-pack/packages (madge)                 | 9.148s      | 10.827s     | 1.425s     |
-| packages (dependency-cruiser)           | 25.744s     | 39.073s     | 2.191s     |
-| packages (madge)                        | 16.299s     | 22.242s     | 2.235s     |
diff --git a/packages/kbn-dependency-usage/src/cli.ts b/packages/kbn-dependency-usage/src/cli.ts
@@ -13,7 +13,6 @@ import chalk from 'chalk';
 import fs from 'fs';
 
 import { identifyDependencyUsageWithCruiser } from './dependency_graph/providers/cruiser.ts';
-import { identifyDependencyUsageWithMadge } from './dependency_graph/providers/madge.ts';
 
 interface CLIArgs {
   dependencyName?: string;
@@ -51,12 +50,6 @@ export const configureYargs = () => {
             describe: chalk.magenta('Group results by either owner or source (package/plugin)'),
             choices: ['owner', 'source'],
           })
-          .option('tool', {
-            alias: 't',
-            describe: chalk.magenta('Use madge or dependency-cruiser to identify dependencies'),
-            choices: ['madge', 'cruiser'],
-            default: 'cruiser',
-          })
           .option('summary', {
             alias: 's',
             describe: chalk.magenta(
@@ -108,7 +101,6 @@ export const configureYargs = () => {
           summary,
           collapseDepth,
           outputPath,
-          tool,
           verbose: isVerbose,
         } = argv;
         if (dependencyName) {
@@ -128,25 +120,20 @@ export const configureYargs = () => {
         }
 
         try {
-          console.log(`${chalk.bold.magenta(tool)} is used for building dependency graph`);
+          console.log(`${chalk.bold.magenta('cruiser')} is used for building dependency graph`);
 
-          const result =
-            tool === 'madge'
-              ? await identifyDependencyUsageWithMadge(paths, dependencyName, {
-                  groupBy,
-                  summary,
-                  collapseDepth,
-                })
-              : await identifyDependencyUsageWithCruiser(paths, dependencyName, {
-                  groupBy,
-                  summary,
-                  collapseDepth,
-                  isVerbose,
-                });
+          const result = await identifyDependencyUsageWithCruiser(paths, dependencyName, {
+            groupBy,
+            summary,
+            collapseDepth,
+            isVerbose,
+          });
 
           if (outputPath) {
             const isJsonFile = nodePath.extname(outputPath) === '.json';
-            const outputFile = isJsonFile ? outputPath : nodePath.join(outputPath, 'results.json');
+            const outputFile = isJsonFile
+              ? outputPath
+              : nodePath.join(outputPath, 'dependency-usage.json');
 
             const outputDir = nodePath.dirname(outputFile);
 

diff --git a/packages/kbn-dependency-usage/src/dependency_graph/providers/madge.ts b/packages/kbn-dependency-usage/src/dependency_graph/providers/madge.ts