alex/g3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(analysis): update dependency analysis artifacts

Browse Source 
Authored by: Structural Analysis Agent (Euler)

Updated all dependency analysis artifacts with fresh extraction:
- graph.json: Canonical dependency graph with 10 crates, 139 files, 16 crate edges, 72 file edges
- graph.summary.md: Overview with fan-in/fan-out rankings and crate inventory
- sccs.md: SCC analysis confirming no cycles at crate or file level (clean DAG)
- layers.observed.md: 5-layer architecture diagram derived from dependencies
- hotspots.md: Coupling hotspots (g3-config highest fan-in, g3-cli highest fan-out)
- limitations.md: Documented extraction limitations (conditional compilation, macros, etc.)

Key findings:
- All 10 workspace crates form a directed acyclic graph
- g3-core/src/ui_writer.rs has highest file-level fan-in (10 dependents)
- g3-console is standalone with no workspace dependencies
- Clean layered architecture with no violations detected
This commit is contained in:
Dhanji R. Prasanna
2026-01-07 09:36:52 +11:00
parent ff08a622eb
commit f0bd7959b1
6 changed files with 1185 additions and 675 deletions
Download Patch File Download Diff File Expand all files Collapse all files

990
analysis/deps/graph.json
View File

File diff suppressed because it is too large Load Diff

100
analysis/deps/graph.summary.md
View File

@@ -1,33 +1,30 @@
# G3 Dependency Graph Summary
# 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 |
| Total Source Files | 139 |
| Crate-Level Dependency Edges | 16 |
| File-Level Dependency Edges | 72 |
## 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 |
| Crate | Type | File Count | Path |
|-------|------|------------|------|
| g3 | binary | 2 | . |
| g3-cli | library | 11 | crates/g3-cli |
| g3-core | library | 55 | crates/g3-core |
| g3-config | library | 3 | crates/g3-config |
| g3-providers | library | 9 | crates/g3-providers |
| g3-planner | library | 12 | crates/g3-planner |
| g3-execution | library | 2 | crates/g3-execution |
| g3-computer-control | library | 28 | crates/g3-computer-control |
| g3-console | binary+library | 18 | crates/g3-console |
| g3-ensembles | library | 5 | crates/g3-ensembles |
## Dependency Structure
### Internal Crate Dependencies (16 edges)
## Crate Dependency Structure
```
g3 (root binary)
@@ -47,27 +44,24 @@ g3 (root binary)
│ ├── g3-core
│ └── g3-config
└── g3-providers
g3-console (standalone binary)
(no internal dependencies - uses g3 via process spawning)
```
### Fan-In (Dependents Count)
## Fan-In Analysis (Crates Depended Upon)
| 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-config | 5 | g3-cli, g3-core, g3-planner, g3-ensembles |
| g3-providers | 4 | g3, g3-cli, g3-core, g3-planner |
| g3-core | 3 | g3-cli, g3-planner, g3-ensembles |
| g3-cli | 1 | g3 |
| g3-planner | 1 | g3-cli |
| g3-ensembles | 1 | g3-cli |
| 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) |
| g3 | 0 | (root) |
### Fan-Out (Dependencies Count)
## Fan-Out Analysis (Crates Depending On Others)
| Crate | Fan-Out | Dependencies |
|-------|---------|-------------|
@@ -77,30 +71,44 @@ g3-console (standalone binary)
| g3-ensembles | 2 | g3-core, g3-config |
| g3 | 2 | g3-cli, g3-providers |
| g3-config | 0 | (leaf) |
| g3-providers | 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`
| Binary | Entry File |
|--------|------------|
| g3 | src/main.rs |
| g3-console | crates/g3-console/src/main.rs |
## Layering (Observed)
## High Fan-In Files (Within Crates)
```
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
```
| File | Fan-In | Role |
|------|--------|------|
| g3-core/src/ui_writer.rs | 10 | UI abstraction trait |
| g3-core/src/lib.rs | 8 | Core agent types (Agent, ToolCall, etc.) |
| g3-providers/src/lib.rs | 7 | Provider types (Message, MessageRole, etc.) |
| g3-config/src/lib.rs | 5 | Configuration (Config) |
| g3-core/src/utils.rs | 2 | Utility functions |
| g3-core/src/paths.rs | 2 | Path utilities |
| g3-core/src/webdriver_session.rs | 2 | WebDriver session management |
| g3-computer-control/src/types.rs | 5 | Type definitions |
| g3-console/src/models/mod.rs | 5 | Data models |
## Leaf Crates (No Internal Dependencies)
- g3-config
- g3-providers
- g3-execution
- g3-computer-control
- g3-console
## 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
1. **Dynamic imports**: Conditional compilation (`#[cfg(...)]`) may hide platform-specific dependencies
2. **Macro-generated imports**: Imports generated by macros are not captured
3. **Re-exports**: Transitive re-exports through `pub use` are not fully traced
4. **Test dependencies**: Test-only dependencies (dev-dependencies) are included but not distinguished in file-level analysis
5. **Build scripts**: build.rs dependencies are not analyzed for import relationships

175
analysis/deps/hotspots.md
View File

@@ -1,120 +1,95 @@
# Coupling Hotspots
# Dependency Hotspots
## High Fan-In Nodes
## Definition
Nodes with disproportionate incoming dependencies (dependents).
Hotspots are code artifacts with disproportionate coupling, measured by:
- **Fan-in**: Number of files/crates that depend on this artifact
- **Fan-out**: Number of files/crates this artifact depends on
- **Cross-group edges**: Dependencies that cross module/crate boundaries
| 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 |
## Crate-Level Hotspots
### g3-config (Fan-In: 5)
### High Fan-In Crates
**Dependents:** g3-cli, g3-core, g3-ensembles, g3-planner, (implicit: g3)
| Crate | Fan-In | Evidence |
|-------|--------|----------|
| g3-config | 5 | Depended on by: g3-cli, g3-core, g3-planner, g3-ensembles, (tests) |
| g3-providers | 4 | Depended on by: g3, g3-cli, g3-core, g3-planner |
| g3-core | 3 | Depended on by: g3-cli, g3-planner, g3-ensembles |
**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" }`
### High Fan-Out Crates
**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.
| Crate | Fan-Out | Evidence |
|-------|---------|----------|
| g3-cli | 5 | Depends on: g3-core, g3-config, g3-planner, g3-providers, g3-ensembles |
| g3-core | 4 | Depends on: g3-providers, g3-config, g3-execution, g3-computer-control |
| g3-planner | 3 | Depends on: g3-providers, g3-core, g3-config |
## File-Level Hotspots
### g3-core/src/lib.rs
### High Fan-In Files
**Lines:** ~3366 (largest file in codebase)
| File | Fan-In | Importing Files |
|------|--------|----------------|
| `g3-core/src/ui_writer.rs` | 10 | lib.rs, tool_dispatch.rs, retry.rs, feedback_extraction.rs, tools/file_ops.rs, tools/shell.rs, tools/misc.rs, tools/todo.rs, tools/webdriver.rs, tools/executor.rs |
| `g3-core/src/lib.rs` | 8 | streaming_parser.rs, feedback_extraction.rs, retry.rs, task_result_comprehensive_tests.rs, (external: g3-cli, g3-planner, g3-ensembles) |
| `g3-providers/src/lib.rs` | 7 | anthropic.rs, databricks.rs, openai.rs, embedded.rs, (external: g3-core, g3-planner, examples) |
| `g3-config/src/lib.rs` | 5 | (external: g3-core, g3-cli, g3-planner, g3-ensembles, tools/executor.rs) |
| `g3-computer-control/src/types.rs` | 5 | platform/macos.rs, platform/linux.rs, platform/windows.rs, ocr/mod.rs, ocr/vision.rs, ocr/tesseract.rs |
| `g3-console/src/models/mod.rs` | 5 | api/instances.rs, api/control.rs, logs.rs, process/controller.rs, process/detector.rs |
**Concerns:**
- Contains the entire `Agent` struct implementation
- High cyclomatic complexity
- Multiple responsibilities (streaming, tools, context management)
### High Fan-Out Files
**Evidence:** File contains 19 public module declarations and the main `Agent` implementation.
| File | Fan-Out | Dependencies |
|------|---------|-------------|
| `g3-core/src/tools/executor.rs` | 5 | background_process.rs, paths.rs, ui_writer.rs, webdriver_session.rs, g3-config |
| `g3-core/src/tool_dispatch.rs` | 4 | tools/executor.rs, tools/mod.rs, ui_writer.rs, ToolCall |
| `g3-core/src/retry.rs` | 4 | error_handling.rs, ui_writer.rs, lib.rs (Agent, TaskResult) |
| `g3-planner/src/llm.rs` | 5 | g3-config, g3-core/project, g3-core/Agent, g3-core/error_handling, g3-providers, prompts.rs |
| `g3-console/src/api/instances.rs` | 3 | logs.rs, models, process/detector.rs |
### g3-cli/src/lib.rs
## Cross-Boundary Dependencies
**Lines:** ~2888
### External Crate Imports (Cross-Crate)
**Concerns:**
- Contains multiple mode implementations (autonomous, interactive, planning, agent)
- Large `run_autonomous` function
- Mixed concerns (UI, orchestration, error handling)
| From Crate | To Crate | Import Count | Key Types |
|------------|----------|--------------|----------|
| g3-core | g3-providers | 5 | Message, MessageRole, Usage, CacheControl, Tool, CompletionRequest, ProviderRegistry |
| g3-core | g3-config | 3 | Config |
| g3-core | g3-computer-control | 2 | WebDriverController, ChromeDriver, SafariDriver, WebElement |
| g3-cli | g3-core | 3 | Agent, UiWriter, DiscoveryOptions, Project, error_handling |
| g3-planner | g3-core | 3 | Agent, Project, error_handling |
| g3-planner | g3-providers | 2 | Message, MessageRole, LLMProvider, CompletionRequest |
| g3-ensembles | g3-core | 1 | (via g3-config) |
## 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
## Coupling 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 |
| Max crate fan-in | 5 (g3-config) | - | Expected for config |
| Max crate fan-out | 5 (g3-cli) | - | Expected for CLI |
| Max file fan-in | 10 (ui_writer.rs) | - | Trait abstraction |
| Max file fan-out | 5 (executor.rs, llm.rs) | - | Orchestration files |
| Cross-crate edges | 16 | - | Moderate |
## Observations
1. **ui_writer.rs** has highest file-level fan-in (10 dependents)
- This is a trait definition, high fan-in is expected
- Implements dependency inversion pattern
2. **g3-config** has highest crate-level fan-in (5 dependents)
- Configuration is appropriately centralized
- No code duplication observed
3. **g3-cli** has highest crate-level fan-out (5 dependencies)
- Expected for application entry point
- Orchestrates all major subsystems
4. **tools/executor.rs** has high fan-out within g3-core
- Central tool execution context
- Coordinates background processes, paths, webdriver, config
5. **g3-console** is isolated
- No dependencies on other workspace crates
- Standalone monitoring application

217
analysis/deps/layers.observed.md
View File

@@ -2,123 +2,126 @@
## Layer Structure
The G3 codebase exhibits a 5-layer architecture derived mechanically from dependency direction:
Based on crate dependencies and file imports, the following layers are observed:
```
┌─────────────────────────────────────────────────────────────────┐
│ 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 5: Binaries │
│ │
│ g3 (src/main.rs) g3-console (src/main.rs) │
│ │ │ │
└─────────┼───────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ LAYER 4: Application │
│ │
│ g3-cli g3-console (lib) │
│ ├── Interactive CLI ├── Web API │
│ ├── TUI rendering ├── Process management │
│ └── Session management └── Log parsing │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LAYER 3: Orchestration │
│ │
│ g3-planner g3-ensembles │
│ ├── Planning workflow ├── Flock mode │
│ ├── Git integration └── Multi-agent status │
│ └── LLM coordination │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LAYER 2: Core │
│ │
│ g3-core │
│ ├── Agent engine (lib.rs) │
│ ├── Context window management │
│ ├── Tool dispatch & execution │
│ ├── Streaming parser │
│ ├── Error handling & retry │
│ └── Code search (tree-sitter) │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LAYER 1: Foundation │
│ │
│ g3-providers g3-config g3-execution │
│ ├── Anthropic ├── TOML └── Coverage tools │
│ ├── Databricks │ parsing │
│ ├── OpenAI └── Settings g3-computer-control │
│ ├── Embedded ├── Platform (macOS/ │
│ └── OAuth │ Linux/Windows) │
│ ├── OCR │
│ ├── WebDriver │
│ └── MacAX │
│ │
└─────────────────────────────────────────────────────────────┘
```
## Layer Definitions
## Layer Dependency Rules
### Layer 0: Foundation
**Crates:** g3-config, g3-providers, g3-execution, g3-computer-control
| From Layer | May Depend On |
|------------|---------------|
| 5 (Binaries) | 4, 1 |
| 4 (Application) | 3, 2, 1 |
| 3 (Orchestration) | 2, 1 |
| 2 (Core) | 1 |
| 1 (Foundation) | (none - leaf) |
- 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
## Observed Violations
**None detected.**
All dependencies flow downward (higher layers depend on lower layers).
All observed dependencies follow the layering rules:
- Higher layers depend only on lower layers
- No skip-level violations that bypass intermediate layers inappropriately
- No upward dependencies
## Cross-Layer Dependencies
## Cross-Cutting Concerns
| 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 |
### g3-config
Used by: g3-cli, g3-core, g3-planner, g3-ensembles
- Provides `Config` struct across all layers
- Appropriate as foundation-level shared configuration
## Observations
### g3-providers
Used by: g3, g3-cli, g3-core, g3-planner
- Provides `Message`, `MessageRole`, `LLMProvider` types
- Core abstraction for LLM communication
- Appropriate as foundation-level abstraction
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
### UiWriter trait (g3-core/src/ui_writer.rs)
Used by: 10 files within g3-core, implemented by g3-cli
- Abstraction for output rendering
- Defined in core, implemented in application layer
- Follows dependency inversion principle
## Module Groupings by Path Convention
| Path Pattern | Purpose | Crates |
|--------------|---------|--------|
| `src/tools/*` | Tool implementations | g3-core |
| `src/api/*` | HTTP API handlers | g3-console |
| `src/models/*` | Data structures | g3-console |
| `src/process/*` | Process management | g3-console |
| `src/platform/*` | OS-specific code | g3-computer-control |
| `src/ocr/*` | OCR implementations | g3-computer-control |
| `src/webdriver/*` | Browser automation | g3-computer-control |
| `src/macax/*` | macOS accessibility | g3-computer-control |
| `src/code_search/*` | Tree-sitter search | g3-core |
## Confidence Assessment
| Aspect | Confidence | Notes |
|--------|------------|-------|
| Crate-level layering | High | Derived from Cargo.toml |
| File-level layering | Medium | Based on import analysis |
| Violation detection | Medium | May miss dynamic/conditional deps |
| Module groupings | High | Based on path conventions |

155
analysis/deps/limitations.md
View File

@@ -1,102 +1,121 @@
# Extraction Limitations
# Analysis Limitations
## Scope of Analysis
## Extraction Method
This structural analysis was performed using static extraction methods only.
This analysis used static parsing of:
1. `Cargo.toml` files for crate-level dependencies
2. `use` statements in `.rs` files for file-level imports
3. `mod` declarations for module structure
## 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
## What Could Not Be Observed
### 1. Conditional Compilation
`#[cfg(...)]` attributes were not parsed. Dependencies that only exist under certain feature flags or target platforms are included unconditionally.
Dependencies gated by `#[cfg(...)]` attributes may be:
- Platform-specific (e.g., `#[cfg(target_os = "macos")]`)
- Feature-gated (e.g., `#[cfg(feature = "..." )]`)
- Test-only (e.g., `#[cfg(test)]`)
**Example:** `g3-computer-control` has platform-specific dependencies:
- `core-graphics`, `cocoa`, `objc` (macOS only)
- `x11` (Linux only)
- `windows` (Windows only)
**Impact**: Some edges may only exist on specific platforms or with specific features enabled.
These are all listed as dependencies but only one set compiles per platform.
**Affected crates**:
- `g3-computer-control`: Has platform-specific modules (macos.rs, linux.rs, windows.rs)
- `g3-providers`: May have feature-gated provider implementations
### 2. Test Dependencies
### 2. Macro-Generated Code
`[dev-dependencies]` were excluded from the graph. Test-only coupling is not represented.
Imports generated by procedural macros are not captured:
- `#[derive(...)]` macros
- `async_trait` macro expansions
- Custom derive macros
### 3. Build Dependencies
**Impact**: Some implicit dependencies on trait implementations may be missed.
`[build-dependencies]` were excluded. Build script dependencies are not represented.
### 3. Re-exports
### 4. Dynamic/Runtime Dependencies
Transitive re-exports via `pub use` are partially traced:
- Direct re-exports in `lib.rs` are captured
- Nested re-exports may not be fully resolved
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
**Example**: `g3-providers/src/lib.rs` likely re-exports types from submodules.
### 5. Trait Implementation Coupling
### 4. Dynamic Dispatch
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`
Trait object usage (`dyn Trait`) creates runtime dependencies not visible in imports:
- `Box<dyn LLMProvider>`
- `Arc<dyn UiWriter>`
### 6. Re-exports
**Impact**: Actual runtime coupling may be higher than static analysis shows.
`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
### 5. Build Script Dependencies
### 7. Macro Expansion
`build.rs` files were identified but not analyzed for:
- Generated code dependencies
- Native library linkage
- Environment-based configuration
Macro-generated code (e.g., `#[derive(...)]`, `async_trait`) creates dependencies not visible in source.
**Affected**: `g3-computer-control/build.rs`
### 8. Workspace Inheritance
### 6. External Crate Dependencies
`workspace = true` dependencies inherit versions from root `Cargo.toml`. The actual version constraints are not captured in crate-level analysis.
Only workspace-internal dependencies were analyzed. External crates from crates.io are listed in Cargo.toml but not traced at file level:
- `tokio`, `reqwest`, `serde`, etc.
- `tree-sitter-*` language grammars
- Platform-specific crates (`core-graphics`, `x11`, `windows`)
## Inference Notes
### 7. Test File Dependencies
### Inferred: g3-console Isolation
Test files in `tests/` directories were included but:
- May have different dependency patterns than production code
- Use `dev-dependencies` not distinguished from regular dependencies
- Integration tests may have broader access than unit tests
`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
### 8. Example File Dependencies
This runtime coupling is not represented in the dependency graph.
Files in `examples/` directories:
- Included in file counts
- May demonstrate usage patterns not representative of core dependencies
- Often have simplified or demonstration-only imports
### Inferred: g3 → g3-providers Direct Dependency
## What Was Inferred
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
### 1. Module-to-File Mapping
The actual usage was not verified.
`mod foo;` declarations were mapped to `foo.rs` or `foo/mod.rs` by convention.
## Recommendations for Future Analysis
**Confidence**: High (Rust standard convention)
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
### 2. Crate Root Identification
## Validity Conditions
`lib.rs` was assumed to be the crate root for libraries.
`main.rs` was assumed to be the binary entry point.
This analysis is valid as of the extraction date. It may be invalidated by:
**Confidence**: High (Cargo convention)
- Adding/removing crates from the workspace
- Changing `[dependencies]` in any Cargo.toml
- Restructuring module hierarchies
- Adding conditional compilation features
### 3. Import Target Resolution
`use crate::foo::Bar` was resolved to the file containing module `foo`.
**Confidence**: Medium (may miss re-exports)
### 4. Cross-Crate Import Resolution
`use g3_core::Agent` was mapped to `g3-core/src/lib.rs`.
**Confidence**: Medium (actual definition may be in submodule)
## What May Invalidate Conclusions
1. **Significant refactoring** since analysis date
2. **Feature flags** enabling/disabling major functionality
3. **Platform-specific builds** with different dependency graphs
4. **Workspace configuration changes** in Cargo.toml
5. **New crates added** to workspace
## Recommendations for Improved Analysis
1. Use `cargo metadata` for authoritative crate dependency graph
2. Use `cargo tree` for transitive dependency analysis
3. Use `rust-analyzer` for precise import resolution
4. Run analysis on each target platform separately
5. Analyze with all feature combinations

223
analysis/deps/sccs.md
View File

@@ -1,64 +1,169 @@
# Strongly Connected Components Analysis
## Crate-Level SCCs
**Result: No cycles detected**
All 10 crates form a directed acyclic graph (DAG). Each crate is its own trivial SCC of size 1.
### Topological Order (Bottom to Top)
1. **Leaf crates** (no internal dependencies):
- g3-config
- g3-providers
- g3-execution
- g3-computer-control
2. **Mid-level crates**:
- g3-core (depends on: g3-providers, g3-config, g3-execution, g3-computer-control)
- g3-console (standalone, no workspace dependencies)
3. **Higher-level crates**:
- g3-planner (depends on: g3-providers, g3-core, g3-config)
- g3-ensembles (depends on: g3-core, g3-config)
4. **Application layer**:
- g3-cli (depends on: g3-core, g3-config, g3-planner, g3-providers, g3-ensembles)
5. **Root binary**:
- g3 (depends on: g3-cli, g3-providers)
## File-Level SCCs Within Crates
### g3-core
No non-trivial SCCs detected. Internal module dependencies are acyclic:
```
lib.rs
├── ui_writer.rs
├── context_window.rs
│ └── paths.rs
├── streaming_parser.rs
├── tool_dispatch.rs
│ └── tools/mod.rs
│ ├── executor.rs
│ │ ├── background_process.rs
│ │ ├── paths.rs
│ │ └── webdriver_session.rs
│ ├── file_ops.rs → utils.rs, ui_writer.rs
│ ├── shell.rs → utils.rs, ui_writer.rs
│ ├── misc.rs → ui_writer.rs
│ ├── todo.rs → ui_writer.rs
│ └── webdriver.rs → webdriver_session.rs, ui_writer.rs
├── error_handling.rs
├── retry.rs → error_handling.rs, ui_writer.rs
├── feedback_extraction.rs → ui_writer.rs
├── task_result.rs → context_window.rs
└── provider_config.rs
```
### g3-providers
No non-trivial SCCs. Provider implementations depend on lib.rs types:
```
lib.rs (types: Message, MessageRole, LLMProvider, etc.)
├── anthropic.rs
├── databricks.rs
├── openai.rs
├── embedded.rs
└── oauth.rs
```
### g3-planner
No non-trivial SCCs:
```
lib.rs
├── planner.rs
│ ├── git.rs
│ ├── history.rs
│ ├── llm.rs → prompts.rs
│ └── state.rs
├── code_explore.rs
└── prompts.rs
```
### g3-computer-control
No non-trivial SCCs:
```
lib.rs
├── types.rs
├── platform/mod.rs
│ ├── macos.rs → ocr/mod.rs, types.rs
│ ├── linux.rs → types.rs
│ └── windows.rs → types.rs
├── ocr/mod.rs → types.rs
│ ├── vision.rs → types.rs
│ └── tesseract.rs → types.rs
├── webdriver/mod.rs
│ ├── safari.rs
│ └── chrome.rs
└── macax/mod.rs
└── controller.rs
```
### g3-console
No non-trivial SCCs:
```
lib.rs
├── models/mod.rs
│ ├── instance.rs
│ └── message.rs
├── api/mod.rs
│ ├── instances.rs → logs.rs, models, process/detector.rs
│ ├── control.rs → models, process/controller.rs
│ ├── logs.rs → logs.rs, process/detector.rs
│ └── state.rs → launch.rs
├── process/mod.rs
│ ├── controller.rs → models
│ └── detector.rs → models
├── logs.rs → models
└── launch.rs
```
### g3-ensembles
No non-trivial SCCs:
```
lib.rs
├── flock.rs → status.rs
└── status.rs
```
### g3-cli
No non-trivial SCCs:
```
lib.rs
├── filter_json.rs
├── ui_writer_impl.rs → filter_json.rs
├── machine_ui_writer.rs
├── retro_tui.rs → theme.rs
├── theme.rs
├── tui.rs
└── simple_output.rs
```
## Summary
**No cycles detected in the crate-level dependency graph.**
| Scope | Non-Trivial SCCs | Largest SCC Size |
|-------|------------------|------------------|
| Crate-level | 0 | 1 (all trivial) |
| File-level (g3-core) | 0 | 1 |
| File-level (g3-providers) | 0 | 1 |
| File-level (g3-planner) | 0 | 1 |
| File-level (g3-computer-control) | 0 | 1 |
| File-level (g3-console) | 0 | 1 |
| File-level (g3-ensembles) | 0 | 1 |
| File-level (g3-cli) | 0 | 1 |
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.
The codebase exhibits clean layered architecture with no circular dependencies.