Add structural dependency analysis artifacts

- graph.json: Canonical dependency graph (10 crates, 16 edges, 76 files) - graph.summary.md: One-page overview with fan-in/fan-out rankings - sccs.md: Strongly Connected Components analysis (no cycles) - layers.observed.md: 5-layer architecture diagram - hotspots.md: Coupling hotspots (g3-config, g3-cli) - limitations.md: Extraction limitations and validity conditions
2026-01-06 13:23:24 +11:00
parent 764d1bf67e
commit 6d6aed563d
5 changed files with 516 additions and 0 deletions
--- a/analysis/deps/graph.summary.md
+++ b/analysis/deps/graph.summary.md
@@ -0,0 +1,106 @@
+# G3 Dependency Graph Summary
+
+## Overview
+
+| Metric | Value |
+|--------|-------|
+| Total Crates | 10 |
+| Internal Dependency Edges | 16 |
+| Total Source Files | 76 |
+| Leaf Crates (no internal dependents) | 4 |
+| Root Crates (no internal dependencies except leaves) | 2 |
+
+## Crate Inventory
+
+| Crate | Type | Path | Files |
+|-------|------|------|-------|
+| g3 | binary | . | 1 |
+| g3-cli | library | crates/g3-cli | 8 |
+| g3-core | library | crates/g3-core | 27 |
+| g3-providers | library | crates/g3-providers | 6 |
+| g3-config | library | crates/g3-config | 1 |
+| g3-execution | library | crates/g3-execution | 1 |
+| g3-computer-control | library | crates/g3-computer-control | 14 |
+| g3-console | library+binary | crates/g3-console | 15 |
+| g3-ensembles | library | crates/g3-ensembles | 3 |
+| g3-planner | library | crates/g3-planner | 8 |
+
+## Dependency Structure
+
+### Internal Crate Dependencies (16 edges)
+
+```
+g3 (root binary)
+├── g3-cli
+│   ├── g3-core
+│   │   ├── g3-providers
+│   │   ├── g3-config
+│   │   ├── g3-execution
+│   │   └── g3-computer-control
+│   ├── g3-config
+│   ├── g3-planner
+│   │   ├── g3-providers
+│   │   ├── g3-core
+│   │   └── g3-config
+│   ├── g3-providers
+│   └── g3-ensembles
+│       ├── g3-core
+│       └── g3-config
+└── g3-providers
+
+g3-console (standalone binary)
+    (no internal dependencies - uses g3 via process spawning)
+```
+
+### Fan-In (Dependents Count)
+
+| Crate | Fan-In | Dependents |
+|-------|--------|------------|
+| g3-config | 5 | g3-cli, g3-core, g3-ensembles, g3-planner |
+| g3-core | 4 | g3-cli, g3-ensembles, g3-planner |
+| g3-providers | 4 | g3, g3-cli, g3-core, g3-planner |
+| g3-cli | 1 | g3 |
+| g3-execution | 1 | g3-core |
+| g3-computer-control | 1 | g3-core |
+| g3-ensembles | 1 | g3-cli |
+| g3-planner | 1 | g3-cli |
+| g3 | 0 | (root) |
+| g3-console | 0 | (standalone) |
+
+### Fan-Out (Dependencies Count)
+
+| Crate | Fan-Out | Dependencies |
+|-------|---------|-------------|
+| g3-cli | 5 | g3-core, g3-config, g3-planner, g3-providers, g3-ensembles |
+| g3-core | 4 | g3-providers, g3-config, g3-execution, g3-computer-control |
+| g3-planner | 3 | g3-providers, g3-core, g3-config |
+| g3-ensembles | 2 | g3-core, g3-config |
+| g3 | 2 | g3-cli, g3-providers |
+| g3-config | 0 | (leaf) |
+| g3-execution | 0 | (leaf) |
+| g3-computer-control | 0 | (leaf) |
+| g3-providers | 0 | (leaf) |
+| g3-console | 0 | (standalone) |
+
+## Entrypoints
+
+1. **g3** (main binary) - `src/main.rs` delegates to `g3-cli`
+2. **g3-console** (standalone binary) - `crates/g3-console/src/main.rs`
+
+## Layering (Observed)
+
+```
+Layer 4 (Entry):      g3, g3-console
+Layer 3 (CLI/UI):     g3-cli
+Layer 2 (Features):   g3-ensembles, g3-planner
+Layer 1 (Core):       g3-core
+Layer 0 (Foundation): g3-config, g3-providers, g3-execution, g3-computer-control
+```
+
+## Extraction Limitations
+
+- Graph derived from Cargo.toml `[dependencies]` sections only
+- File-level dependencies inferred from `use` statements (not fully traced)
+- Conditional compilation (`#[cfg(...)]`) dependencies not distinguished
+- Test dependencies excluded from analysis
+- Dynamic/runtime dependencies not captured
--- a/analysis/deps/hotspots.md
+++ b/analysis/deps/hotspots.md
@@ -0,0 +1,120 @@
+# Coupling Hotspots
+
+## High Fan-In Nodes
+
+Nodes with disproportionate incoming dependencies (dependents).
+
+| Crate | Fan-In | % of Crates | Classification |
+|-------|--------|-------------|----------------|
+| g3-config | 5 | 50% | **High** - shared foundation |
+| g3-core | 4 | 40% | **High** - central hub |
+| g3-providers | 4 | 40% | **High** - shared foundation |
+| g3-cli | 1 | 10% | Normal |
+| g3-execution | 1 | 10% | Normal |
+| g3-computer-control | 1 | 10% | Normal |
+| g3-ensembles | 1 | 10% | Normal |
+| g3-planner | 1 | 10% | Normal |
+
+### g3-config (Fan-In: 5)
+
+**Dependents:** g3-cli, g3-core, g3-ensembles, g3-planner, (implicit: g3)
+
+**Evidence:**
+- `g3-cli/Cargo.toml`: `g3-config = { path = "../g3-config" }`
+- `g3-core/Cargo.toml`: `g3-config = { path = "../g3-config" }`
+- `g3-ensembles/Cargo.toml`: `g3-config = { path = "../g3-config" }`
+- `g3-planner/Cargo.toml`: `g3-config = { path = "../g3-config" }`
+
+**Coupling Pattern:** Configuration struct (`Config`) is passed through the call stack. Changes to `Config` fields propagate to all dependents.
+
+### g3-core (Fan-In: 4)
+
+**Dependents:** g3-cli, g3-ensembles, g3-planner
+
+**Evidence:**
+- `g3-cli/Cargo.toml`: `g3-core = { path = "../g3-core" }`
+- `g3-ensembles/Cargo.toml`: `g3-core = { path = "../g3-core" }`
+- `g3-planner/Cargo.toml`: `g3-core = { path = "../g3-core" }`
+
+**Coupling Pattern:** `Agent` struct is the primary interface. Feature modules create and orchestrate agents.
+
+### g3-providers (Fan-In: 4)
+
+**Dependents:** g3, g3-cli, g3-core, g3-planner
+
+**Evidence:**
+- `Cargo.toml`: `g3-providers = { path = "crates/g3-providers" }`
+- `g3-cli/Cargo.toml`: `g3-providers = { path = "../g3-providers" }`
+- `g3-core/Cargo.toml`: `g3-providers = { path = "../g3-providers" }`
+- `g3-planner/Cargo.toml`: `g3-providers = { path = "../g3-providers" }`
+
+**Coupling Pattern:** `Message`, `MessageRole`, `LLMProvider` trait are widely used types.
+
+## High Fan-Out Nodes
+
+Nodes with disproportionate outgoing dependencies.
+
+| Crate | Fan-Out | % of Crates | Classification |
+|-------|---------|-------------|----------------|
+| g3-cli | 5 | 50% | **High** - orchestrator |
+| g3-core | 4 | 40% | **High** - integrator |
+| g3-planner | 3 | 30% | Moderate |
+| g3-ensembles | 2 | 20% | Normal |
+| g3 | 2 | 20% | Normal |
+
+### g3-cli (Fan-Out: 5)
+
+**Dependencies:** g3-core, g3-config, g3-planner, g3-providers, g3-ensembles
+
+**Coupling Pattern:** CLI orchestrates all major features. This is expected for a top-level UI crate.
+
+### g3-core (Fan-Out: 4)
+
+**Dependencies:** g3-providers, g3-config, g3-execution, g3-computer-control
+
+**Coupling Pattern:** Core integrates all foundation crates. This is the expected role of a "core" module.
+
+## File-Level Hotspots
+
+### g3-core/src/lib.rs
+
+**Lines:** ~3366 (largest file in codebase)
+
+**Concerns:**
+- Contains the entire `Agent` struct implementation
+- High cyclomatic complexity
+- Multiple responsibilities (streaming, tools, context management)
+
+**Evidence:** File contains 19 public module declarations and the main `Agent` implementation.
+
+### g3-cli/src/lib.rs
+
+**Lines:** ~2888
+
+**Concerns:**
+- Contains multiple mode implementations (autonomous, interactive, planning, agent)
+- Large `run_autonomous` function
+- Mixed concerns (UI, orchestration, error handling)
+
+## Cross-Crate Type Dependencies
+
+### Most Shared Types
+
+| Type | Defined In | Used By |
+|------|------------|--------|
+| `Config` | g3-config | g3-cli, g3-core, g3-ensembles, g3-planner |
+| `Message` | g3-providers | g3-core, g3-cli, g3-planner |
+| `MessageRole` | g3-providers | g3-core, g3-cli, g3-planner |
+| `Agent` | g3-core | g3-cli, g3-ensembles, g3-planner |
+| `LLMProvider` | g3-providers | g3-core, g3-planner |
+| `UiWriter` | g3-core | g3-cli |
+
+## Metrics Summary
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Max Fan-In | 5 (g3-config) | ≤6 | ✅ OK |
+| Max Fan-Out | 5 (g3-cli) | ≤6 | ✅ OK |
+| Largest File | 3366 lines | ≤1000 | ⚠️ Large |
+| Crates with Fan-In > 3 | 3 | ≤4 | ✅ OK |
+| Crates with Fan-Out > 3 | 2 | ≤3 | ✅ OK |
--- a/analysis/deps/layers.observed.md
+++ b/analysis/deps/layers.observed.md
@@ -0,0 +1,124 @@
+# Observed Layering
+
+## Layer Structure
+
+The G3 codebase exhibits a 5-layer architecture derived mechanically from dependency direction:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Layer 4: Entry Points                                          │
+│  ┌─────────┐  ┌─────────────┐                                   │
+│  │   g3    │  │  g3-console │                                   │
+│  └────┬────┘  └─────────────┘                                   │
+│       │            (standalone)                                 │
+├───────┼─────────────────────────────────────────────────────────┤
+│  Layer 3: CLI/UI                                                │
+│       │                                                         │
+│       ▼                                                         │
+│  ┌─────────┐                                                    │
+│  │ g3-cli  │                                                    │
+│  └────┬────┘                                                    │
+│       │                                                         │
+├───────┼─────────────────────────────────────────────────────────┤
+│  Layer 2: Feature Modules                                       │
+│       │                                                         │
+│       ├──────────────┬──────────────┐                           │
+│       ▼              ▼              │                           │
+│  ┌───────────┐  ┌───────────┐       │                           │
+│  │g3-ensembles│ │g3-planner │       │                           │
+│  └─────┬─────┘  └─────┬─────┘       │                           │
+│        │              │             │                           │
+├────────┼──────────────┼─────────────┼───────────────────────────┤
+│  Layer 1: Core Engine                                           │
+│        │              │             │                           │
+│        └──────┬───────┘             │                           │
+│               ▼                     │                           │
+│          ┌─────────┐                │                           │
+│          │ g3-core │◄───────────────┘                           │
+│          └────┬────┘                                            │
+│               │                                                 │
+├───────────────┼─────────────────────────────────────────────────┤
+│  Layer 0: Foundation                                            │
+│               │                                                 │
+│    ┌──────────┼──────────┬──────────────┬───────────────┐       │
+│    ▼          ▼          ▼              ▼               │       │
+│ ┌────────┐ ┌──────────┐ ┌───────────┐ ┌─────────────────┴─┐     │
+│ │g3-config│ │g3-providers│ │g3-execution│ │g3-computer-control│  │
+│ └────────┘ └──────────┘ └───────────┘ └───────────────────┘     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Layer Definitions
+
+### Layer 0: Foundation
+**Crates:** g3-config, g3-providers, g3-execution, g3-computer-control
+
+- No internal dependencies
+- Provide fundamental capabilities:
+  - Configuration loading and management
+  - LLM provider abstractions (Anthropic, OpenAI, Databricks, embedded)
+  - Code execution engine
+  - Computer control (mouse, keyboard, screenshots)
+
+### Layer 1: Core Engine
+**Crates:** g3-core
+
+- Depends on all Layer 0 crates
+- Central orchestration:
+  - Agent state machine
+  - Context window management
+  - Tool dispatch and execution
+  - Streaming response parsing
+  - Session management
+
+### Layer 2: Feature Modules
+**Crates:** g3-ensembles, g3-planner
+
+- Depend on Layer 0 (g3-config) and Layer 1 (g3-core)
+- Specialized functionality:
+  - g3-ensembles: Multi-agent parallel development (flock mode)
+  - g3-planner: Requirements-driven planning workflow
+
+### Layer 3: CLI/UI
+**Crates:** g3-cli
+
+- Depends on Layers 0, 1, and 2
+- User interface:
+  - Command-line parsing
+  - Interactive REPL
+  - Output formatting
+  - Mode orchestration (autonomous, chat, planning, agent)
+
+### Layer 4: Entry Points
+**Crates:** g3, g3-console
+
+- Binary entry points
+- g3: Main CLI binary (delegates to g3-cli)
+- g3-console: Standalone web console (no internal deps)
+
+## Layer Violations
+
+**None detected.**
+
+All dependencies flow downward (higher layers depend on lower layers).
+
+## Cross-Layer Dependencies
+
+| From Layer | To Layer | Count | Edges |
+|------------|----------|-------|-------|
+| 4 → 3 | Entry → CLI | 1 | g3 → g3-cli |
+| 4 → 0 | Entry → Foundation | 1 | g3 → g3-providers |
+| 3 → 2 | CLI → Features | 2 | g3-cli → g3-ensembles, g3-cli → g3-planner |
+| 3 → 1 | CLI → Core | 1 | g3-cli → g3-core |
+| 3 → 0 | CLI → Foundation | 2 | g3-cli → g3-config, g3-cli → g3-providers |
+| 2 → 1 | Features → Core | 2 | g3-ensembles → g3-core, g3-planner → g3-core |
+| 2 → 0 | Features → Foundation | 3 | g3-ensembles → g3-config, g3-planner → g3-config, g3-planner → g3-providers |
+| 1 → 0 | Core → Foundation | 4 | g3-core → g3-config, g3-core → g3-providers, g3-core → g3-execution, g3-core → g3-computer-control |
+
+## Observations
+
+1. **Clean layering**: No upward dependencies detected
+2. **g3-console isolation**: Standalone binary with no internal dependencies
+3. **g3-config ubiquity**: Used by 5 crates across all layers
+4. **g3-core centrality**: Hub for all feature modules
+5. **Skip-layer dependencies**: g3-cli directly depends on Layer 0 crates (g3-config, g3-providers) - this is acceptable for configuration and provider access
--- a/analysis/deps/limitations.md
+++ b/analysis/deps/limitations.md
@@ -0,0 +1,102 @@
+# Extraction Limitations
+
+## Scope of Analysis
+
+This structural analysis was performed using static extraction methods only.
+
+## What Was Observed
+
+| Source | Method | Confidence |
+|--------|--------|------------|
+| Crate dependencies | Cargo.toml `[dependencies]` parsing | High |
+| Module structure | `pub mod` declarations in lib.rs files | High |
+| File inventory | Filesystem traversal of `src/` directories | High |
+| Use statements | `grep` for `^use ` patterns | Medium |
+| External dependencies | Cargo.toml `[dependencies]` sections | High |
+
+## What Was NOT Observed
+
+### 1. Conditional Compilation
+
+`#[cfg(...)]` attributes were not parsed. Dependencies that only exist under certain feature flags or target platforms are included unconditionally.
+
+**Example:** `g3-computer-control` has platform-specific dependencies:
+- `core-graphics`, `cocoa`, `objc` (macOS only)
+- `x11` (Linux only)
+- `windows` (Windows only)
+
+These are all listed as dependencies but only one set compiles per platform.
+
+### 2. Test Dependencies
+
+`[dev-dependencies]` were excluded from the graph. Test-only coupling is not represented.
+
+### 3. Build Dependencies
+
+`[build-dependencies]` were excluded. Build script dependencies are not represented.
+
+### 4. Dynamic/Runtime Dependencies
+
+The following cannot be detected statically:
+- Process spawning (e.g., `g3-console` spawns `g3` processes)
+- Plugin loading
+- Configuration-driven provider selection
+- WebDriver browser automation targets
+
+### 5. Trait Implementation Coupling
+
+Trait implementations create implicit coupling not captured by `use` statements:
+- `UiWriter` implementations in `g3-cli`
+- `LLMProvider` implementations in `g3-providers`
+- `ComputerController` implementations in `g3-computer-control`
+
+### 6. Re-exports
+
+`pub use` re-exports create transitive dependencies not fully traced:
+- `g3-core` re-exports types from `g3-providers`
+- `g3-computer-control` re-exports WebDriver types
+
+### 7. Macro Expansion
+
+Macro-generated code (e.g., `#[derive(...)]`, `async_trait`) creates dependencies not visible in source.
+
+### 8. Workspace Inheritance
+
+`workspace = true` dependencies inherit versions from root `Cargo.toml`. The actual version constraints are not captured in crate-level analysis.
+
+## Inference Notes
+
+### Inferred: g3-console Isolation
+
+`g3-console` has no internal crate dependencies in its `Cargo.toml`. It interacts with `g3` via:
+- Process spawning (`std::process::Command`)
+- Log file parsing
+- Filesystem monitoring
+
+This runtime coupling is not represented in the dependency graph.
+
+### Inferred: g3 → g3-providers Direct Dependency
+
+The root `g3` crate depends directly on `g3-providers` despite `g3-cli` also depending on it. This may be for:
+- Type re-exports
+- Direct provider access in main.rs
+- Historical reasons
+
+The actual usage was not verified.
+
+## Recommendations for Future Analysis
+
+1. **cargo-depgraph**: Use `cargo depgraph` for authoritative Cargo-resolved dependencies
+2. **cargo-tree**: Use `cargo tree` for transitive dependency analysis
+3. **rust-analyzer**: Use LSP for precise type-level dependency tracking
+4. **cargo-udeps**: Identify unused dependencies
+5. **cargo-machete**: Detect potentially unused dependencies
+
+## Validity Conditions
+
+This analysis is valid as of the extraction date. It may be invalidated by:
+
+- Adding/removing crates from the workspace
+- Changing `[dependencies]` in any Cargo.toml
+- Restructuring module hierarchies
+- Adding conditional compilation features
--- a/analysis/deps/sccs.md
+++ b/analysis/deps/sccs.md
@@ -0,0 +1,64 @@
+# Strongly Connected Components Analysis
+
+## Summary
+
+**No cycles detected in the crate-level dependency graph.**
+
+The G3 workspace exhibits a clean DAG (Directed Acyclic Graph) structure at the crate level.
+
+## Analysis Method
+
+Cycle detection performed via manual topological sort verification of the 16 internal dependency edges.
+
+## Topological Order (Valid)
+
+The following topological ordering confirms acyclicity:
+
+1. g3-config (leaf)
+2. g3-execution (leaf)
+3. g3-computer-control (leaf)
+4. g3-providers (leaf)
+5. g3-core (depends on 1-4)
+6. g3-ensembles (depends on 1, 5)
+7. g3-planner (depends on 1, 4, 5)
+8. g3-cli (depends on 1, 4, 5, 6, 7)
+9. g3 (depends on 4, 8)
+10. g3-console (standalone)
+
+## Potential Coupling Concerns
+
+While no cycles exist, the following patterns warrant attention:
+
+### Diamond Dependencies
+
+```
+g3-cli ──────────────────────────────┐
+   │                                  │
+   ├── g3-core ── g3-config ◄─────────┤
+   │                                  │
+   ├── g3-planner ── g3-config ◄──────┤
+   │                                  │
+   └── g3-ensembles ── g3-config ◄────┘
+```
+
+`g3-config` is reached via multiple paths from `g3-cli`. This is not a cycle but indicates `g3-config` is a shared foundation.
+
+### Similar Diamond for g3-core
+
+```
+g3-cli ──────────────────────────────┐
+   │                                  │
+   ├── g3-core ◄──────────────────────┤
+   │                                  │
+   ├── g3-planner ── g3-core ◄────────┤
+   │                                  │
+   └── g3-ensembles ── g3-core ◄──────┘
+```
+
+## Module-Level Analysis
+
+Module-level cycle detection was not performed. The `use crate::` statements within each crate suggest internal module dependencies but these are expected within a single compilation unit.
+
+## Conclusion
+
+The crate dependency structure is healthy with no circular dependencies.