feat: add dependency graph generation

Author: lukasniessen-bain

README.md

@@ -102,6 +102,20 @@ it('should generate HTML reports', async () => {
 });
 ```
 
+You can also export dependency graph reports as CI artifacts:
+
+```typescript
+it('should generate dependency graph reports', async () => {
+  await projectGraph()
+    .collapseToFolderDepth(2)
+    .exportAsHTML('reports/dependency-graph.html');
+
+  await projectGraph().exportAsMermaid('reports/dependency-graph.mmd');
+
+  expect(0).toBe(0);
+});
+```
+
 In your `gitlab-ci.yml`:
 
 ```yml
@@ -378,6 +392,42 @@ it('should not contain forbidden dependencies', async () => {
 });
 ```
 
+### Dependency Graph Reports
+
+Generate dependency graph reports in multiple formats and narrow them to the part of the codebase you want to inspect.
+
+```typescript
+import { projectGraph } from 'archunit';
+
+it('should export dependency graph reports', async () => {
+  const graph = projectGraph().titled('Application Architecture');
+
+  await graph.collapseToFolderDepth(2).exportAsMermaid('reports/dependencies.mmd');
+
+  await graph.focusOn('src/**', 1).exportAsHTML('reports/source-dependencies.html');
+
+  expect(0).toBe(0);
+});
+```
+
+Supported formats:
+
+- DOT (`exportAsDOT`, `toDOT`)
+- Mermaid (`exportAsMermaid`, `toMermaid`)
+- D2 (`exportAsD2`, `toD2`)
+- CSV (`exportAsCSV`, `toCSV`)
+- JSON (`exportAsJSON`, `toJSON`)
+- HTML (`exportAsHTML`, `toHTML`)
+
+Graph exploration options:
+
+- `focusOn(pattern, depth)` keeps matching files and their neighbors.
+- `reachableFrom(pattern)` keeps matching files and their transitive dependencies.
+- `dependentsOf(pattern)` keeps files that transitively depend on the matching files.
+- `collapseToFolderDepth(depth)` aggregates files to folder-level graph nodes.
+- `collapseByPattern(pattern, replacement)` maps files to custom graph nodes.
+- `includeExternalDependencies()` includes external edges when graph extraction provides them.
+
 ### Reports
 
 Generate beautiful HTML reports for your metrics. The default output path is `/reports`. _Note that this features is in beta._
@@ -1307,6 +1357,7 @@ ArchUnitTS has the following core modules.
 | **Files**   | File and folder based rules          | Stable       | [`src/files/`](src/files/) • [README](src/files/README.md)                       |
 | **Metrics** | Code quality metrics                 | Stable       | [`src/metrics/`](src/metrics/) • [README](src/metrics/README.md)                 |
 | **Slices**  | Architecture slicing                 | Stable       | [`src/slices/`](src/slices/) • [README](src/slices/README.md)                    |
+| **Graph**   | Dependency graph reports and queries | Experimental | [`src/graph/`](src/graph/)                                                       |
 | **Testing** | Universal test framework integration | Stable       | [`src/testing/`](src/testing/) • [README](src/testing/README.md)                 |
 | **Common**  | Shared utilities                     | Stable       | [`src/common/`](src/common/)                                                     |
 | **Reports** | Generate reports                     | Experimental | [`src/metrics/fluentapi/export-utils.ts`](src/metrics/fluentapi/export-utils.ts) |

index.ts

@@ -5,6 +5,7 @@ import './src/testing/setup';
 export * from './src/slices';
 export * from './src/files';
 export * from './src/metrics';
+export * from './src/graph';
 
 // Graph extraction and debugging
 export { extractGraph, clearGraphCache } from './src/common/extraction';

src/graph/graph-reporter.spec.ts

@@ -0,0 +1,175 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { Edge } from '../common/extraction/graph';
+import { ImportKind } from '../common/util/import-kinds';
+import { GraphReporter } from './graph-reporter';
+
+const graph: Edge[] = [
+	{
+		source: 'src/app/controller.ts',
+		target: 'src/domain/service.ts',
+		external: false,
+		importKinds: [ImportKind.NAMED],
+	},
+	{
+		source: 'src/app/controller.ts',
+		target: 'src/domain/service.ts',
+		external: false,
+		importKinds: [ImportKind.TYPE],
+	},
+	{
+		source: 'src/domain/service.ts',
+		target: 'src/infra/repository.ts',
+		external: false,
+		importKinds: [ImportKind.DEFAULT],
+	},
+	{
+		source: 'src/app/controller.ts',
+		target: 'src/infra/repository.ts',
+		external: false,
+		importKinds: [ImportKind.DEFAULT],
+	},
+	{
+		source: 'src/infra/repository.ts',
+		target: 'src/infra/repository.ts',
+		external: false,
+		importKinds: [],
+	},
+	{
+		source: 'src/app/controller.ts',
+		target: 'node_modules/react/index.d.ts',
+		external: true,
+		importKinds: [ImportKind.DEFAULT],
+	},
+];
+
+describe('GraphReporter', () => {
+	it('aggregates duplicate edges and excludes self/external edges by default', () => {
+		const snapshot = GraphReporter.createSnapshot(graph);
+
+		expect(snapshot.summary.nodeCount).toBe(3);
+		expect(snapshot.summary.edgeCount).toBe(3);
+		expect(snapshot.summary.rawEdgeCount).toBe(4);
+		expect(snapshot.summary.externalEdgeCount).toBe(0);
+		expect(snapshot.edges).toContainEqual({
+			source: 'src/app/controller.ts',
+			target: 'src/domain/service.ts',
+			count: 2,
+			external: false,
+			importKinds: ['named', 'type'],
+		});
+	});
+
+	it('can include external dependencies when requested', () => {
+		const snapshot = GraphReporter.createSnapshot(graph, {
+			includeExternalDependencies: true,
+		});
+
+		expect(snapshot.summary.externalEdgeCount).toBe(1);
+		expect(snapshot.edges).toContainEqual({
+			source: 'src/app/controller.ts',
+			target: 'node_modules/react/index.d.ts',
+			count: 1,
+			external: true,
+			importKinds: ['default'],
+		});
+	});
+
+	it('focuses on matching nodes and configurable neighbor depth', () => {
+		const focused = GraphReporter.createSnapshot(graph, {
+			focus: 'src/domain/**',
+			focusDepth: 0,
+		});
+
+		expect(focused.nodes.map((node) => node.label)).toEqual([
+			'src/domain/service.ts',
+		]);
+		expect(focused.edges).toEqual([]);
+
+		const withNeighbors = GraphReporter.createSnapshot(graph, {
+			focus: 'src/domain/**',
+			focusDepth: 1,
+		});
+
+		expect(withNeighbors.nodes.map((node) => node.label)).toEqual([
+			'src/app/controller.ts',
+			'src/domain/service.ts',
+			'src/infra/repository.ts',
+		]);
+		expect(withNeighbors.summary.edgeCount).toBe(3);
+	});
+
+	it('filters to reachable dependencies and dependents', () => {
+		const reachable = GraphReporter.createSnapshot(graph, {
+			reachableFrom: 'src/domain/**',
+		});
+
+		expect(reachable.nodes.map((node) => node.label)).toEqual([
+			'src/domain/service.ts',
+			'src/infra/repository.ts',
+		]);
+		expect(reachable.edges).toHaveLength(1);
+
+		const dependents = GraphReporter.createSnapshot(graph, {
+			dependentsOf: 'src/infra/**',
+		});
+
+		expect(dependents.nodes.map((node) => node.label)).toEqual([
+			'src/app/controller.ts',
+			'src/domain/service.ts',
+			'src/infra/repository.ts',
+		]);
+		expect(dependents.summary.edgeCount).toBe(3);
+	});
+
+	it('collapses nodes to folder depth before aggregating edges', () => {
+		const snapshot = GraphReporter.createSnapshot(graph, {
+			collapse: {
+				type: 'folder-depth',
+				depth: 2,
+			},
+		});
+
+		expect(snapshot.nodes.map((node) => node.label)).toEqual([
+			'src/app',
+			'src/domain',
+			'src/infra',
+		]);
+		expect(snapshot.edges).toContainEqual({
+			source: 'src/app',
+			target: 'src/domain',
+			count: 2,
+			external: false,
+			importKinds: ['named', 'type'],
+		});
+	});
+
+	it('renders supported text formats', () => {
+		const mermaid = GraphReporter.toMermaid(graph);
+		const dot = GraphReporter.toDOT(graph);
+		const d2 = GraphReporter.toD2(graph);
+		const csv = GraphReporter.toCSV(graph);
+		const json = GraphReporter.toJSON(graph);
+		const html = GraphReporter.toHTML(graph, { title: 'Architecture Report' });
+
+		expect(mermaid).toContain('flowchart LR');
+		expect(mermaid).toContain('|2|');
+		expect(dot).toContain('digraph dependencies');
+		expect(dot).toContain('"src/app/controller.ts" -> "src/domain/service.ts"');
+		expect(d2).toContain('"src/app/controller.ts" -> "src/domain/service.ts"');
+		expect(csv.split('\n')[0]).toBe('source,target,count,external,importKinds');
+		expect(JSON.parse(json).summary.edgeCount).toBe(3);
+		expect(html).toContain('<title>Architecture Report</title>');
+		expect(html).toContain('Generated by ArchUnitTS graph reporting');
+	});
+
+	it('writes reports to disk', async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archunit-graph-'));
+		const outputPath = path.join(dir, 'dependencies.mmd');
+
+		await GraphReporter.exportAsMermaid(graph, outputPath);
+
+		expect(fs.readFileSync(outputPath, 'utf8')).toContain('flowchart LR');
+	});
+});