feat: add dependency graph visualization

- Add CLI command 'graph' to generate dependency graphs
- Support Mermaid, ASCII, JSON and HTML output formats
- Add toMermaid() and toAscii() methods to DependencyGraph
- Add generateGraph() and generateHtmlGraph() helper functions
- Update documentation with graph visualization guide
- Restructure docs to match api-spy format

Author: typeghostx

README.md

@@ -19,6 +19,7 @@
 - 🔄 **Auto-ordering** - Tests run in dependency order automatically
 - ⚡ **Cached Results** - Each test runs once, results are cached
 - 🎯 **Zero Config** - Works out of the box with Playwright
+- 📊 **Dependency Graph** - Visualize test dependencies with Mermaid diagrams
 
 ## Installation
 
@@ -96,6 +97,21 @@ interface Relay {
 | Playwright annotations | `test.info().annotations` | ✅ Yes |
 | `relay.require()` | `await relay.require('test')` | At runtime |
 
+## Dependency Graph
+
+Visualize your test dependencies:
+
+```bash
+# Mermaid diagram
+npx playwright-relay graph "tests/**/*.spec.ts"
+
+# ASCII diagram
+npx playwright-relay graph "tests/**/*.spec.ts" --format ascii
+
+# Interactive HTML
+npx playwright-relay graph "tests/**/*.spec.ts" --format html --output graph.html
+```
+
 ## Documentation
 
 📖 **[Full Documentation](https://damianovsky.github.io/playwright-relay)**

docs/examples/graph.md

@@ -0,0 +1,126 @@
+# Dependency Graph
+
+Generate visual dependency graphs from your test files.
+
+## CLI Usage
+
+```bash
+# Generate Mermaid diagram
+npx playwright-relay graph "tests/**/*.spec.ts"
+
+# Generate ASCII diagram
+npx playwright-relay graph "tests/**/*.spec.ts" --format ascii
+
+# Generate HTML page with interactive graph
+npx playwright-relay graph "tests/**/*.spec.ts" --format html --output graph.html
+
+# Generate JSON
+npx playwright-relay graph "tests/**/*.spec.ts" --format json
+
+# Change direction (TB, BT, LR, RL)
+npx playwright-relay graph "tests/**/*.spec.ts" --direction LR
+```
+
+## Output Formats
+
+### Mermaid (default)
+
+```bash
+npx playwright-relay graph "tests/**/*.spec.ts"
+```
+
+Output:
+```mermaid
+flowchart TB
+  N0["create user"]
+  N1["update user"]
+  N2["delete user"]
+  N0 --> N1
+  N1 --> N2
+```
+
+### ASCII
+
+```bash
+npx playwright-relay graph "tests/**/*.spec.ts" --format ascii
+```
+
+Output:
+```
+○ create user
+● update user
+  └─ depends on: create user
+● delete user
+  └─ depends on: update user
+```
+
+### HTML
+
+```bash
+npx playwright-relay graph "tests/**/*.spec.ts" --format html --output graph.html
+```
+
+Generates an HTML page with an interactive Mermaid diagram.
+
+### JSON
+
+```bash
+npx playwright-relay graph "tests/**/*.spec.ts" --format json
+```
+
+Output:
+```json
+{
+  "nodes": [
+    { "id": "test.spec.ts > create user", "title": "create user", "file": "test.spec.ts" },
+    { "id": "test.spec.ts > update user", "title": "update user", "file": "test.spec.ts" }
+  ],
+  "edges": [
+    { "from": "test.spec.ts > create user", "to": "test.spec.ts > update user" }
+  ]
+}
+```
+
+## Programmatic Usage
+
+```typescript
+import { generateGraph, generateHtmlGraph, buildGraphFromFiles } from 'playwright-relay';
+
+// Generate graph output
+const result = generateGraph('tests/**/*.spec.ts', {
+  format: 'mermaid',
+  direction: 'TB',
+  includeOrphans: true,
+});
+
+console.log(result.output);
+console.log(`Tests: ${result.testCount}, Dependencies: ${result.dependencyCount}`);
+
+// Generate HTML
+const html = generateHtmlGraph('tests/**/*.spec.ts', {
+  direction: 'LR',
+});
+
+// Build graph object for custom processing
+const graph = buildGraphFromFiles(['tests/auth.spec.ts', 'tests/user.spec.ts']);
+console.log(graph.toMermaid());
+console.log(graph.toAscii());
+```
+
+## Graph Directions
+
+| Direction | Description |
+|-----------|-------------|
+| `TB` | Top to bottom (default) |
+| `BT` | Bottom to top |
+| `LR` | Left to right |
+| `RL` | Right to left |
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | `string` | `'mermaid'` | Output format: `mermaid`, `ascii`, `json`, `html` |
+| `direction` | `string` | `'TB'` | Graph direction for Mermaid |
+| `includeOrphans` | `boolean` | `true` | Include tests without dependencies |
+| `output` | `string` | - | Write to file instead of stdout |

mkdocs.yml

@@ -40,6 +40,7 @@ nav:
   - Examples:
     - Basic Patterns: examples/basic.md
     - Advanced Patterns: examples/advanced.md
+    - Dependency Graph: examples/graph.md
 
 markdown_extensions:
   - pymdownx.highlight: