feat: enhance deps-graph command with collapse and exclude options for improved dependency visualization, close #46

Author: MichaelKreil

README.md

@@ -41,6 +41,18 @@ You need to configure the scripts in the package.json:
 - `scripts.prepack` is **recommended** to ensure that all files are up-to-date before releasing. Here you can build code and documentation.
 - `scripts.release` is **recommended** to make it easy to release a new version.
 
+# Trimming a noisy dependency graph
+
+For repos with high fan-out, `deps-graph` accepts repeatable globs to collapse or drop nodes:
+
+```bash
+# Merge all region scrapers into a single labelled node ("regions/*.ts (24 files)").
+vrt deps-graph --collapse-dir 'src/regions/*.ts'
+
+# Drop trivial barrels and stubs from the graph entirely.
+vrt deps-graph --exclude '**/_planned.ts' --exclude '**/index.ts'
+```
+
 # Command `vrt`
 
 <!--- This chapter is generated automatically --->
@@ -58,7 +70,7 @@ Options:
 
 Commands:
   check                                     Check repo for required scripts and other stuff.
-  deps-graph                                Analyze project files and output a dependency graph as Mermaid markup.
+  deps-graph [options]                      Analyze project files and output a dependency graph as Mermaid markup.
   deps-upgrade                              Upgrade all dependencies in the current project to their latest versions.
   doc-command <command>                     Generate Markdown documentation for a specified command and output the result.
   doc-insert <readme> [heading] [foldable]  Insert Markdown from stdin into a specified section of a Markdown file.
@@ -89,7 +101,11 @@ Usage: vrt deps-graph [options]
 Analyze project files and output a dependency graph as Mermaid markup.
 
 Options:
-  -h, --help  display help for command
+  --collapse-dir <glob>  Collapse all files matching the glob into a single node
+                         (repeatable). (default: [])
+  --exclude <glob>       Drop files matching the glob from the graph entirely
+                         (repeatable). (default: [])
+  -h, --help             display help for command
 ```
 
 ## Subcommand: `vrt deps-upgrade`

package-lock.json

@@ -44,6 +44,7 @@
     "@schemastore/package": "^1.0.5",
     "@types/mdast": "^4.0.4",
     "@types/node": "^25.6.0",
+    "@types/picomatch": "^4.0.3",
     "@typescript-eslint/eslint-plugin": "^8.59.2",
     "@typescript-eslint/parser": "^8.59.2",
     "@vitest/coverage-v8": "^4.1.5",
@@ -62,6 +63,7 @@
     "dependency-cruiser": "^17.4.0",
     "mdast-util-to-markdown": "^2.1.2",
     "npm-check-updates": "^22.1.0",
+    "picomatch": "^4.0.4",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
     "remark-stringify": "^11.0.0",

package.json

@@ -1,9 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, MockInstance, vi } from 'vitest';
-import type { IReporterOutput } from 'dependency-cruiser';
+import type { ICruiseResult, IModule, IReporterOutput } from 'dependency-cruiser';
 
-// 1. Mock dependency-cruiser to control the output of `cruise`
+// 1. Mock dependency-cruiser to control the output of `cruise` and `format`
 vi.mock('dependency-cruiser', () => ({
 	cruise: vi.fn(),
+	format: vi.fn(),
 }));
 
 // 2. Mock the log/panic module
@@ -14,70 +15,149 @@ vi.mock('../lib/log.js', () => ({
 }));
 
 // 3. Import the mocked modules and the function under test
-const { cruise } = await import('dependency-cruiser');
+const { cruise, format } = await import('dependency-cruiser');
 const { panic } = await import('../lib/log.js');
 const { generateDependencyGraph } = await import('./deps-graph.js');
 
+/** Build a minimal ICruiseResult with the given modules; all other fields stubbed. */
+function fakeCruiseResult(modules: Pick<IModule, 'source' | 'dependencies'>[]): ICruiseResult {
+	return {
+		modules: modules.map((m) => ({
+			source: m.source,
+			dependencies: m.dependencies,
+			dependents: [],
+			valid: true,
+		})) as IModule[],
+		summary: {} as ICruiseResult['summary'],
+	};
+}
+
 describe('generateDependencyGraph', () => {
 	let mockStdoutWrite: MockInstance<typeof process.stdout.write>;
 
 	beforeEach(() => {
-		// Reset and clear mocks before each test
 		vi.clearAllMocks();
-
-		// Spy on process.stdout.write to check what gets written
 		mockStdoutWrite = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+		// Default: cruise returns the modules-shaped result the new code expects
+		vi.mocked(cruise).mockResolvedValue({
+			output: fakeCruiseResult([{ source: 'src/a.ts', dependencies: [] }]),
+		} as IReporterOutput);
+
+		// Default: format returns a minimal mermaid string the post-processor can rewrite
+		vi.mocked(format).mockResolvedValue({ output: 'flowchart LR\nA-->B' } as IReporterOutput);
 	});
 
 	afterEach(() => {
-		// Restore any spied methods
 		mockStdoutWrite.mockRestore();
 	});
 
 	it('generates a mermaid diagram, replacing flowchart LR with flowchart TB', async () => {
-		// Mock a successful result from dependency-cruiser
-		vi.mocked(cruise).mockResolvedValueOnce({
-			output: 'flowchart LR\nA-->B',
-		} as IReporterOutput);
-
 		await expect(generateDependencyGraph('src')).resolves.toBeUndefined();
 
-		// Verify the call to `cruise` used the expected arguments
-		expect(cruise).toHaveBeenCalledWith(['src'], expect.any(Object));
+		expect(cruise).toHaveBeenCalledWith(['src'], expect.objectContaining({ outputType: 'json' }));
 
-		// After modification, we expect flowchart TB in the output
 		expect(mockStdoutWrite).toHaveBeenCalledTimes(1);
-		// The actual argument passed to stdout.write
-		const writtenBuffer = mockStdoutWrite.mock.calls[0][0] as Buffer;
-		const writtenString = writtenBuffer.toString();
-
+		const writtenString = (mockStdoutWrite.mock.calls[0][0] as Buffer).toString();
 		expect(writtenString).toMatch(/^```mermaid\n/);
 		expect(writtenString).toMatch(/\nflowchart TB\nA-->B\n/);
 		expect(writtenString).toMatch(/\n```\n$/);
 	});
 
 	it('panics if dependency-cruiser throws an error', async () => {
-		// Simulate a thrown error from `cruise`
 		vi.mocked(cruise).mockImplementationOnce(async () => {
 			throw new Error('Some error from dependency-cruiser');
 		});
 
 		await expect(generateDependencyGraph('bad/path')).rejects.toThrow('Some error from dependency-cruiser');
 
-		// Confirm the panic function was called with the thrown error message
 		expect(panic).toHaveBeenCalledWith('Error: Some error from dependency-cruiser');
-		// No output should be written
 		expect(mockStdoutWrite).not.toHaveBeenCalled();
 	});
 
-	it('panics if the returned output is not a string', async () => {
-		// Mock an invalid result (missing or incorrect `output` field)
-		vi.mocked(cruise).mockResolvedValueOnce({
-			output: null,
-		} as unknown as IReporterOutput);
+	it('panics if the formatted output is not a string', async () => {
+		vi.mocked(format).mockResolvedValueOnce({ output: null } as unknown as IReporterOutput);
 
 		await expect(generateDependencyGraph('src')).rejects.toThrow('no output');
 		expect(panic).toHaveBeenCalledWith('no output');
 		expect(mockStdoutWrite).not.toHaveBeenCalled();
 	});
+
+	describe('--exclude', () => {
+		it('passes user-provided globs (as regex) to cruise alongside built-in excludes', async () => {
+			await generateDependencyGraph('src', { exclude: ['**/_planned.ts'] });
+
+			const opts = vi.mocked(cruise).mock.calls[0][1];
+			expect(opts).toBeDefined();
+			const excludePatterns = (opts!.exclude ?? []) as string[];
+			// built-in excludes are still present
+			expect(excludePatterns).toContain('\\.(test|d|mock)\\.ts$');
+			// user glob translated to a regex
+			expect(excludePatterns.some((p) => /_planned/.test(p))).toBe(true);
+		});
+	});
+
+	describe('--collapse-dir', () => {
+		it('merges files matching a glob into a single node and reports the count', async () => {
+			vi.mocked(cruise).mockResolvedValueOnce({
+				output: fakeCruiseResult([
+					{
+						source: 'src/regions/index.ts',
+						dependencies: [
+							{ resolved: 'src/regions/de.ts' },
+							{ resolved: 'src/regions/fr.ts' },
+							{ resolved: 'src/regions/it.ts' },
+							{ resolved: 'src/regions/lib.ts' },
+						] as IModule['dependencies'],
+					},
+					{
+						source: 'src/regions/de.ts',
+						dependencies: [{ resolved: 'src/regions/lib.ts' }] as IModule['dependencies'],
+					},
+					{
+						source: 'src/regions/fr.ts',
+						dependencies: [{ resolved: 'src/regions/lib.ts' }] as IModule['dependencies'],
+					},
+					{
+						source: 'src/regions/it.ts',
+						dependencies: [{ resolved: 'src/regions/lib.ts' }] as IModule['dependencies'],
+					},
+					{ source: 'src/regions/lib.ts', dependencies: [] },
+				]),
+			} as IReporterOutput);
+
+			await generateDependencyGraph('src', { collapseDir: ['src/regions/{de,fr,it}.ts'] });
+
+			// The collapsed result is what `format` receives.
+			const formatArg = vi.mocked(format).mock.calls[0][0] as ICruiseResult;
+			const sources = formatArg.modules.map((m) => m.source).sort();
+
+			// Original 5 files reduced to 3: index, lib, and one merged regions/{de,fr,it}.ts node
+			expect(formatArg.modules).toHaveLength(3);
+			expect(sources).toEqual(['src/regions/index.ts', 'src/regions/lib.ts', 'src/regions/{de,fr,it}.ts (3 files)']);
+
+			// Edges from index.ts: the three collapsed files become a single deduped edge to the merged node.
+			const indexNode = formatArg.modules.find((m) => m.source === 'src/regions/index.ts')!;
+			const indexResolved = indexNode.dependencies.map((d) => d.resolved).sort();
+			expect(indexResolved).toEqual(['src/regions/lib.ts', 'src/regions/{de,fr,it}.ts (3 files)']);
+
+			// The merged node depends on lib.ts (deduped from the three originals) — and has no self-loop.
+			const merged = formatArg.modules.find((m) => m.source.startsWith('src/regions/{de,fr,it}.ts'))!;
+			expect(merged.dependencies.map((d) => d.resolved)).toEqual(['src/regions/lib.ts']);
+		});
+
+		it('does nothing when no files match the collapse glob', async () => {
+			vi.mocked(cruise).mockResolvedValueOnce({
+				output: fakeCruiseResult([
+					{ source: 'src/a.ts', dependencies: [{ resolved: 'src/b.ts' }] as IModule['dependencies'] },
+					{ source: 'src/b.ts', dependencies: [] },
+				]),
+			} as IReporterOutput);
+
+			await generateDependencyGraph('src', { collapseDir: ['src/no-match/*.ts'] });
+
+			const formatArg = vi.mocked(format).mock.calls[0][0] as ICruiseResult;
+			expect(formatArg.modules.map((m) => m.source).sort()).toEqual(['src/a.ts', 'src/b.ts']);
+		});
+	});
 });