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

Update dependency analysis artifacts

Browse Source 
Generated comprehensive static dependency analysis for g3 workspace:

- graph.json: 108 nodes (9 crates, 99 files), 186 edges
- graph.summary.md: Overview with metrics, entrypoints, fan-in/fan-out rankings
- sccs.md: No cycles detected (DAG structure confirmed)
- layers.observed.md: 4-layer crate hierarchy identified
- hotspots.md: ui_writer.rs (15 fan-in), agent_mode.rs (13 fan-out) as key nodes
- limitations.md: Documents extraction methodology and caveats

Updated AGENTS.md with artifact documentation table.

Agent: euler
This commit is contained in:
Dhanji R. Prasanna
2026-01-29 11:46:39 +11:00
parent cba7d31996
commit 853237e62e
7 changed files with 2234 additions and 2146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
AGENTS.md
View File

@@ -67,3 +67,18 @@ These areas have subtle bugs if modified incorrectly:
3. **"Tool results are always small"** - File reads can return megabytes
4. **"Sessions persist across runs"** - Sessions are ephemeral by default
5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility)
## Dependency Analysis Artifacts
The `analysis/deps/` directory contains static analysis artifacts generated by the euler agent:
| File | Purpose |
|------|--------|
| `graph.json` | Canonical dependency graph with nodes (crates, files) and edges (imports) |
| `graph.summary.md` | One-page overview with metrics, entrypoints, and top fan-in/fan-out nodes |
| `sccs.md` | Strongly connected components (dependency cycles) analysis |
| `layers.observed.md` | Observed layering structure derived from dependency direction |
| `hotspots.md` | Files with disproportionate coupling (high fan-in or fan-out) |
| `limitations.md` | What could not be observed and what may invalidate conclusions |
These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.

3492
analysis/deps/graph.json
View File

File diff suppressed because it is too large Load Diff

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

@@ -2,92 +2,85 @@
## Overview
| Metric | Count |
| Metric | Value |
|--------|-------|
| Workspace crates | 10 |
| Crate-level edges | 17 |
| Source files (non-test) | 95 |
| File-level edges | 123 |
| Cross-crate imports | 43 |
| Strongly connected components | 0 |
| Total nodes | 108 |
| Total edges | 186 |
| Crate nodes | 9 |
| File nodes | 99 |
| Crate-level edges | 14 |
| File-level edges | 172 |
## Crate-Level Structure
## Crate Structure
### Crates by Type
| Crate | Type | Files |
|-------|------|-------|
| g3 | bin (root) | 1 |
| g3-cli | lib | 16 |
| g3-core | lib | 38 |
| g3-providers | lib | 7 |
| g3-config | lib | 2 |
| g3-execution | lib | 1 |
| g3-computer-control | lib | 16 |
| g3-planner | lib | 8 |
| g3-ensembles | lib | 4 |
| studio | bin | 3 |
### Fan-In (Most Depended Upon)
| Crate | Dependents |
|-------|------------|
| g3-config | 4 |
| g3-providers | 4 |
| g3-core | 3 |
| g3-computer-control | 2 |
| g3-cli | 1 |
| g3-ensembles | 1 |
| g3-execution | 1 |
| g3-planner | 1 |
### Fan-Out (Most Dependencies)
| Crate | Dependencies |
|-------|-------------|
| g3-cli | 6 |
| g3-core | 4 |
| g3-planner | 3 |
| g3 | 2 |
| g3-ensembles | 2 |
## File-Level Structure
### Top Fan-Out Files (Most Outgoing Edges)
| File | Edges | Description |
|------|-------|-------------|
| crates/g3-core/src/lib.rs | 29 | Core library root |
| crates/g3-cli/src/lib.rs | 17 | CLI library root |
| crates/g3-core/src/tools/mod.rs | 9 | Tools module root |
| crates/g3-planner/src/lib.rs | 8 | Planner library root |
| crates/g3-providers/src/lib.rs | 6 | Providers library root |
| crates/g3-computer-control/src/lib.rs | 5 | Computer control root |
| crates/g3-planner/src/llm.rs | 5 | LLM integration |
### Top Fan-In (Most Imported)
| Target | Imports |
|--------|--------|
| g3-core (crate) | 21 |
| g3-providers (crate) | 11 |
| g3-config (crate) | 9 |
| g3-computer-control (crate) | 2 |
| Crate | Path | Direct Dependencies |
|-------|------|---------------------|
| g3 | `.` | g3-cli, g3-providers |
| g3-cli | `crates/g3-cli` | g3-core, g3-config, g3-planner, g3-computer-control, g3-providers |
| g3-core | `crates/g3-core` | g3-providers, g3-config, g3-execution, g3-computer-control |
| g3-providers | `crates/g3-providers` | (none) |
| g3-config | `crates/g3-config` | (none) |
| g3-execution | `crates/g3-execution` | (none) |
| g3-planner | `crates/g3-planner` | g3-providers, g3-core, g3-config |
| g3-computer-control | `crates/g3-computer-control` | (none) |
| studio | `crates/studio` | (none) |
## Entrypoints
| File | Type |
|------|------|
| src/main.rs | Binary entrypoint (g3) |
| crates/studio/src/main.rs | Binary entrypoint (studio) |
| crates/g3-cli/src/lib.rs | Library root |
| crates/g3-core/src/lib.rs | Library root |
| Type | Location | Evidence |
|------|----------|----------|
| Binary | `crates/g3-cli/src/lib.rs` | `run()` function, CLI dispatch |
| Binary | `crates/studio/src/main.rs` | `main()` function |
| Library | `crates/g3-core/src/lib.rs` | `Agent` struct, core API |
## Top Fan-In Nodes (Most Depended Upon)
| Node | Fan-In | Type |
|------|--------|------|
| crate:g3-core | 35 | crate |
| crate:g3-providers | 19 | crate |
| file:crates/g3-core/src/ui_writer.rs | 15 | file |
| crate:g3-config | 13 | crate |
| file:crates/g3-cli/src/g3_status.rs | 10 | file |
| file:crates/g3-cli/src/simple_output.rs | 8 | file |
| file:crates/g3-core/src/context_window.rs | 6 | file |
| file:crates/g3-cli/src/template.rs | 6 | file |
| file:crates/g3-core/src/paths.rs | 5 | file |
| crate:g3-computer-control | 4 | crate |
## Top Fan-Out Nodes (Most Dependencies)
| Node | Fan-Out | Type |
|------|---------|------|
| file:crates/g3-cli/src/agent_mode.rs | 13 | file |
| file:crates/g3-core/src/lib.rs | 13 | file |
| file:crates/g3-cli/src/commands.rs | 12 | file |
| file:crates/g3-cli/src/interactive.rs | 12 | file |
| file:crates/g3-cli/src/accumulative.rs | 11 | file |
| file:crates/g3-planner/src/planner.rs | 8 | file |
| file:crates/g3-cli/src/autonomous.rs | 8 | file |
| file:crates/g3-core/src/tools/acd.rs | 7 | file |
| file:crates/g3-planner/src/llm.rs | 6 | file |
| file:crates/g3-cli/src/utils.rs | 5 | file |
## File Counts by Crate
| Crate | Source Files |
|-------|-------------|
| g3-cli | 23 |
| g3-core | 42 |
| g3-providers | 9 |
| g3-config | 2 |
| g3-execution | 1 |
| g3-planner | 8 |
| g3-computer-control | 11 |
| studio | 3 |
## Extraction Limitations
- Only `use` and `mod` statements at line start are parsed
- Conditional compilation (`#[cfg(...)]`) not evaluated
- Macro-generated imports not detected
- Re-exports through `pub use` not fully traced
- Test modules (`mod tests`) excluded from graph
- Test files (`*_test.rs`, `tests/`) excluded from graph
1. **Static analysis only**: Dynamic dispatch and trait objects not traced
2. **Use statement parsing**: Only `use g3_*` and `use crate::` patterns captured
3. **Conditional compilation**: `#[cfg(...)]` blocks not evaluated
4. **Re-exports**: `pub use` chains not fully resolved
5. **Test files excluded**: Files in `/tests/` directories not included
6. **Examples excluded**: Files in `/examples/` directories not included

141
analysis/deps/hotspots.md
View File

@@ -1,112 +1,69 @@
# Coupling Hotspots
## Method
## High Fan-In Files (Most Depended Upon)
Hotspots identified by:
1. Fan-in > 2× average (high incoming dependencies)
2. Fan-out > 2× average (high outgoing dependencies)
3. Cross-group edge concentration
Files with disproportionately high incoming dependencies.
## Metrics
| File | Fan-In | Crate | Role |
|------|--------|-------|------|
| ui_writer.rs | 15 | g3-core | UI abstraction trait |
| g3_status.rs | 10 | g3-cli | Status message formatting |
| simple_output.rs | 8 | g3-cli | Output helper |
| context_window.rs | 6 | g3-core | Token/context management |
| template.rs | 6 | g3-cli | Template processing |
| paths.rs | 5 | g3-core | Path utilities |
### Crate Level
### Evidence: ui_writer.rs (fan-in: 15)
| Metric | Value |
|--------|-------|
| Average fan-in | 2.0 |
| Average fan-out | 1.7 |
| Threshold (2×) | 4.0 / 3.4 |
Depended on by:
- g3-cli: accumulative.rs, agent_mode.rs, autonomous.rs, commands.rs, interactive.rs, task_execution.rs, ui_writer_impl.rs, utils.rs
- g3-core: compaction.rs, feedback_extraction.rs, lib.rs, retry.rs, tool_dispatch.rs, tools/*.rs
### File Level
### Evidence: g3_status.rs (fan-in: 10)
| Metric | Value |
|--------|-------|
| Total edges | 123 |
| Total files | 95 |
| Average fan-out | 1.3 |
| Threshold (2×) | 2.6 |
Depended on by:
- commands.rs, interactive.rs, simple_output.rs, task_execution.rs, and others in g3-cli
## Crate-Level Hotspots
## High Fan-Out Files (Most Dependencies)
### High Fan-In (Most Depended Upon)
Files with disproportionately high outgoing dependencies.
| Crate | Fan-In | Status |
|-------|--------|--------|
| g3-config | 4 | **HOTSPOT** (2× avg) |
| g3-providers | 4 | **HOTSPOT** (2× avg) |
| g3-core | 3 | Near threshold |
| File | Fan-Out | Crate | Role |
|------|---------|-------|------|
| agent_mode.rs | 13 | g3-cli | Agent mode entry point |
| lib.rs | 13 | g3-core | Core library root |
| commands.rs | 12 | g3-cli | Command handlers |
| interactive.rs | 12 | g3-cli | Interactive REPL |
| accumulative.rs | 11 | g3-cli | Accumulative mode |
| planner.rs | 8 | g3-planner | Planning orchestration |
**Evidence for g3-config:**
- Depended on by: g3-cli, g3-core, g3-planner, g3-ensembles
- Contains: Configuration types, loading logic
### Evidence: agent_mode.rs (fan-out: 13)
**Evidence for g3-providers:**
- Depended on by: g3, g3-cli, g3-core, g3-planner
- Contains: LLM provider trait, message types, streaming
Depends on:
- g3-core: Agent, ui_writer::UiWriter
- Internal: project_files, display, language_prompts, simple_output, embedded_agents, ui_writer_impl, interactive, template
### High Fan-Out (Most Dependencies)
### Evidence: g3-core/lib.rs (fan-out: 13)
| Crate | Fan-Out | Status |
|-------|---------|--------|
| g3-cli | 6 | **HOTSPOT** (3.5× avg) |
| g3-core | 4 | **HOTSPOT** (2.4× avg) |
| g3-planner | 3 | Near threshold |
Depends on:
- External crates: g3-config, g3-providers
- Internal modules: ui_writer, context_window, paths, compaction, streaming, tools, etc.
**Evidence for g3-cli:**
- Depends on: g3-core, g3-config, g3-planner, g3-computer-control, g3-providers, g3-ensembles
- Role: Top-level integration point
## Cross-Crate Coupling
**Evidence for g3-core:**
- Depends on: g3-providers, g3-config, g3-execution, g3-computer-control
- Role: Central engine with multiple infrastructure dependencies
## File-Level Hotspots
### High Fan-Out Files
| File | Fan-Out | Threshold | Status |
|------|---------|-----------|--------|
| crates/g3-core/src/lib.rs | 29 | 2.6 | **HOTSPOT** (22× avg) |
| crates/g3-cli/src/lib.rs | 17 | 2.6 | **HOTSPOT** (13× avg) |
| crates/g3-core/src/tools/mod.rs | 9 | 2.6 | **HOTSPOT** (7× avg) |
| crates/g3-planner/src/lib.rs | 8 | 2.6 | **HOTSPOT** (6× avg) |
| crates/g3-providers/src/lib.rs | 6 | 2.6 | **HOTSPOT** (4.6× avg) |
| crates/g3-computer-control/src/lib.rs | 5 | 2.6 | **HOTSPOT** (3.8× avg) |
| crates/g3-planner/src/llm.rs | 5 | 2.6 | **HOTSPOT** (3.8× avg) |
**Note:** High fan-out in `lib.rs` files is expected (module re-exports). The `tools/mod.rs` and `llm.rs` hotspots are more significant as they represent actual coupling.
### Cross-Crate Import Concentration
| Source File | Cross-Crate Imports |
|-------------|--------------------|
| crates/g3-cli/src/lib.rs | 5 (g3-core, g3-config, g3-providers, g3-planner, g3-ensembles) |
| crates/g3-planner/src/llm.rs | 4 (g3-config, g3-core, g3-providers) |
| crates/g3-cli/src/autonomous.rs | 2 (g3-core) |
| crates/g3-cli/src/task_execution.rs | 2 (g3-core) |
| Source Crate | Target Crate | Edge Count |
|--------------|--------------|------------|
| g3-cli | g3-core | 35 |
| g3-core | g3-providers | 10 |
| g3-core | g3-config | 5 |
| g3-planner | g3-core | 4 |
| g3-planner | g3-providers | 3 |
| g3-core | g3-computer-control | 2 |
## Observations
1. **g3-core/src/lib.rs** has extreme fan-out (29 edges) due to declaring 22+ modules
2. **g3-config** and **g3-providers** are foundational crates with high fan-in
3. **g3-cli** is the integration hub, pulling together all subsystems
4. **tools/mod.rs** aggregates 9 tool modules - natural aggregation point
5. **g3-planner/src/llm.rs** has notable cross-crate coupling (imports from 3 other crates)
## Cross-Group Edges
Total cross-crate imports: 43
| From Crate | To Crate | Count |
|------------|----------|-------|
| g3-cli | g3-core | 21 |
| g3-cli | g3-config | 4 |
| g3-cli | g3-providers | 2 |
| g3-planner | g3-core | 5 |
| g3-planner | g3-providers | 4 |
| g3-planner | g3-config | 2 |
| g3-core | g3-providers | 8 |
| g3-core | g3-config | 3 |
| g3-core | g3-computer-control | 2 |
| g3-ensembles | g3-core | 1 |
| g3-ensembles | g3-config | 1 |
1. **ui_writer.rs** is a central abstraction point; changes here affect 15+ files
2. **g3-cli** files have high fan-out due to orchestration responsibilities
3. **g3-core/lib.rs** is the primary API surface with expected high coupling
4. **g3_status.rs** and **simple_output.rs** form a UI utility cluster in g3-cli
5. **tools/*.rs** files consistently depend on ui_writer and ToolCall types

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

@@ -1,172 +1,80 @@
# Observed Layering
## Derivation Method
## Crate-Level Layers
Layers derived mechanically from:
1. Crate dependency direction in Cargo.toml
2. Path-based module grouping
3. Import directionality analysis
## Crate Hierarchy
Based on dependency direction, the following layers are observed:
```
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: Binaries │
│ g3 (main entry) │
│ studio (standalone tool) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Application │
│ g3-cli (CLI interface, 16 files) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Orchestration │
│ g3-planner (planning logic, 8 files) │
│ g3-ensembles (multi-agent, 4 files) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Core Engine │
│ g3-core (agent engine, 38 files) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 4: Infrastructure │
│ g3-providers (LLM providers, 7 files) │
│ g3-config (configuration, 2 files) │
│ g3-execution (code execution, 1 file) │
│ g3-computer-control (desktop automation, 16 files) │
└─────────────────────────────────────────────────────────────┘
Layer 0 (Leaf crates - no internal dependencies):
├── g3-config
├── g3-execution
├── g3-providers
├── g3-computer-control
└── studio
Layer 1 (Depends on Layer 0):
└── g3-core
└── depends on: g3-providers, g3-config, g3-execution, g3-computer-control
Layer 2 (Depends on Layer 0 and 1):
├── g3-cli
│ └── depends on: g3-core, g3-config, g3-planner, g3-computer-control, g3-providers
└── g3-planner
└── depends on: g3-providers, g3-core, g3-config
Layer 3 (Application root):
└── g3
└── depends on: g3-cli, g3-providers
```
## Intra-Crate Module Structure
## Layer Metrics
### g3-core (38 files)
| Layer | Crates | Description |
|-------|--------|-------------|
| 0 | 5 | Foundation crates with no internal deps |
| 1 | 1 | Core engine |
| 2 | 2 | High-level orchestration |
| 3 | 1 | Application entry point |
```
lib.rs
├── acd.rs # Aggressive Context Dehydration
├── background_process.rs # Background process management
├── code_search/ # Tree-sitter code search
│ ├── mod.rs
│ └── searcher.rs
├── compaction.rs # Context compaction
├── context_window.rs # Context window management
├── error_handling.rs # Error classification
├── feedback_extraction.rs # Coach feedback extraction
├── paths.rs # Path utilities
├── project.rs # Project abstraction
├── prompts.rs # System prompts
├── provider_config.rs # Provider configuration
├── provider_registration.rs # Provider registration
├── retry.rs # Retry logic
├── session.rs # Session management
├── session_continuation.rs # Session continuation
├── streaming.rs # Streaming utilities
├── streaming_parser.rs # Tool call parser
├── task_result.rs # Task result types
├── tool_definitions.rs # Tool definitions
├── tool_dispatch.rs # Tool routing
├── tools/ # Tool implementations
│ ├── mod.rs
│ ├── acd.rs
│ ├── executor.rs
│ ├── file_ops.rs
│ ├── memory.rs
│ ├── misc.rs
│ ├── research.rs
│ ├── shell.rs
│ ├── todo.rs
│ └── webdriver.rs
├── ui_writer.rs # UI abstraction
├── utils.rs # General utilities
└── webdriver_session.rs # WebDriver session
```
## Observed Groupings by Path
### g3-cli (16 files)
### g3-core/src/tools/
Tool implementations grouped under `tools/` submodule:
- executor.rs (tool context and execution)
- acd.rs, file_ops.rs, memory.rs, misc.rs, research.rs, shell.rs, todo.rs, webdriver.rs
```
lib.rs
├── accumulative.rs # Accumulative mode
├── agent_mode.rs # Agent mode
├── autonomous.rs # Autonomous mode
├── cli_args.rs # CLI argument parsing
├── coach_feedback.rs # Coach feedback
├── filter_json.rs # JSON filtering
├── interactive.rs # Interactive mode
├── metrics.rs # Metrics/timing
├── project_files.rs # Project file loading
├── simple_output.rs # Simple output helper
├── streaming_markdown.rs # Markdown formatting
├── task_execution.rs # Task execution
├── theme.rs # UI theming
├── ui_writer_impl.rs # UiWriter implementation
└── utils.rs # CLI utilities
```
### g3-core/src/code_search/
Code search functionality:
- mod.rs (API types)
- searcher.rs (tree-sitter implementation)
### g3-computer-control (16 files)
### g3-computer-control/src/platform/
Platform-specific implementations:
- macos.rs, linux.rs, windows.rs (conditional compilation)
```
lib.rs
├── macax/ # macOS Accessibility
│ ├── mod.rs
│ └── controller.rs
├── ocr/ # OCR engines
│ ├── mod.rs
│ ├── tesseract.rs
│ └── vision.rs
├── platform/ # Platform implementations
│ ├── mod.rs
│ ├── linux.rs
│ ├── macos.rs
│ └── windows.rs
├── types.rs # Shared types
└── webdriver/ # WebDriver implementations
├── mod.rs
├── chrome.rs
├── diagnostics.rs
└── safari.rs
```
### g3-computer-control/src/webdriver/
Browser automation:
- safari.rs, chrome.rs, diagnostics.rs
### g3-providers (7 files)
### g3-providers/src/
LLM provider implementations:
- anthropic.rs, openai.rs, gemini.rs, databricks.rs, embedded.rs
- oauth.rs (authentication)
- mock.rs (testing)
```
lib.rs
├── anthropic.rs # Anthropic Claude
├── databricks.rs # Databricks
├── embedded.rs # Local llama.cpp
├── oauth.rs # OAuth flow
├── openai.rs # OpenAI-compatible
└── streaming.rs # Streaming utilities
```
## Directionality
### g3-planner (8 files)
```
lib.rs
├── code_explore.rs # Code exploration
├── git.rs # Git operations
├── history.rs # History management
├── llm.rs # LLM integration
├── planner.rs # Planning logic
├── prompts.rs # Planner prompts
└── state.rs # State management
```
## Layer Violations
**None detected.**
All dependencies flow downward through the layer hierarchy. No upward dependencies exist.
| From | To | Direction | Violations |
|------|----|-----------|------------|
| g3 | g3-cli | down | none |
| g3-cli | g3-core | down | none |
| g3-cli | g3-planner | lateral | none |
| g3-core | g3-providers | down | none |
| g3-core | g3-config | down | none |
| g3-planner | g3-core | lateral | none |
## Uncertainty
- Layer assignment is based on dependency direction, not semantic intent
- `studio` is isolated (no internal crate dependencies) - layer assignment is nominal
- Some crates at Layer 4 could arguably be split further (e.g., `g3-computer-control` is large)
- **studio**: Isolated crate with no detected internal dependencies; may have runtime integration not captured
- **g3-execution**: Minimal crate (1 file); purpose unclear from static analysis alone
- **Lateral dependencies**: g3-cli ↔ g3-planner relationship suggests potential for extraction or consolidation

128
analysis/deps/limitations.md
View File

@@ -1,103 +1,67 @@
# Analysis Limitations
## Extraction Method
## What Was Observed
Dependencies extracted via:
1. Cargo.toml parsing for crate-level dependencies
2. Regex-based `use` and `mod` statement extraction from source files
| Category | Method | Coverage |
|----------|--------|----------|
| Crate dependencies | Cargo.toml parsing | Complete |
| Module structure | `mod` declarations in lib.rs/main.rs | Complete |
| File imports | `use g3_*` and `use crate::` patterns | Partial |
| Submodule structure | mod.rs file inspection | Complete |
## Known Limitations
## What Could Not Be Observed
### 1. Conditional Compilation Not Evaluated
### 1. Implicit Dependencies
```rust
#[cfg(target_os = "macos")]
use core_graphics::window::*;
```
- **Trait implementations**: A file implementing a trait from another module creates a dependency not captured by `use` statements
- **Type aliases**: Types re-exported through `pub use` chains
- **Derive macros**: Dependencies introduced by `#[derive(...)]`
Platform-specific imports in `g3-computer-control` are included unconditionally. The actual dependency graph varies by target platform.
### 2. Dynamic Patterns
**Affected files:**
- `crates/g3-computer-control/src/platform/macos.rs`
- `crates/g3-computer-control/src/platform/linux.rs`
- `crates/g3-computer-control/src/platform/windows.rs`
- **Trait objects**: `dyn Trait` usage creates runtime dependencies
- **Generic bounds**: `T: SomeTrait` constraints
- **Associated types**: Dependencies through associated type resolution
### 2. Macro-Generated Imports Not Detected
### 3. Conditional Compilation
Imports generated by procedural macros (e.g., `#[derive(...)]`, `#[async_trait]`) are not captured. These may introduce implicit dependencies.
- **Platform-specific code**: `#[cfg(target_os = "...")]` blocks not evaluated
- **Feature flags**: `#[cfg(feature = "...")]` dependencies not traced
- **Test-only code**: `#[cfg(test)]` modules excluded
**Common macros in codebase:**
- `serde::Serialize`, `serde::Deserialize`
- `async_trait::async_trait`
- `clap::Parser`
### 4. Build System
### 3. Re-Exports Not Fully Traced
- **build.rs**: Build script dependencies not analyzed
- **Procedural macros**: Macro crate dependencies not traced
- **Workspace-level features**: Feature unification effects not modeled
```rust
pub use some_module::SomeType;
```
### 5. Excluded Files
Re-exports create transitive dependencies that are not fully traced. A file importing `SomeType` from a re-exporting module has an indirect dependency on the original module.
| Category | Count | Reason |
|----------|-------|--------|
| Test files (`/tests/`) | ~40 | Out of scope |
| Example files (`/examples/`) | ~10 | Out of scope |
| Worktree copies | ~100 | Duplicates |
### 4. Glob Imports Partially Resolved
## What Was Inferred
```rust
use crate::types::*;
```
Glob imports are recorded but individual items are not enumerated. The actual coupling may be higher or lower than represented.
### 5. Test Code Excluded
Files matching these patterns are excluded:
- `*_test.rs`
- `tests/*.rs`
- `mod tests { ... }` blocks
Test dependencies are not represented in the graph.
### 6. Build Scripts Not Analyzed
`build.rs` files are not included. Build-time dependencies (e.g., code generation) are not captured.
**Affected:**
- `crates/g3-computer-control/build.rs`
### 7. External Crate Dependencies Not Graphed
Only workspace-internal dependencies are represented. External crates (tokio, serde, etc.) are not included in the graph.
### 8. Inline Module Definitions
```rust
mod foo {
// inline definition
}
```
Inline module definitions without corresponding files are detected but may not resolve to file edges.
### 9. Path Aliases Not Resolved
```rust
use crate::foo as bar;
```
Aliased imports are recorded with original path, but alias usage elsewhere is not correlated.
| Inference | Basis | Confidence |
|-----------|-------|------------|
| Layer assignment | Topological sort of crate deps | High |
| Fan-in/fan-out metrics | Edge counting | High |
| Module-to-file mapping | Naming convention (mod.rs, *.rs) | High |
| Entrypoints | lib.rs/main.rs presence | High |
## What May Invalidate Conclusions
1. **Feature flags**: Cargo features may enable/disable entire modules
2. **Workspace changes**: Adding/removing crates changes the graph structure
3. **Refactoring**: Moving code between modules changes edges without changing functionality
4. **Dynamic dispatch**: Trait objects create runtime dependencies not visible statically
1. **Hidden re-exports**: If `g3-core/lib.rs` re-exports types from submodules, actual coupling may be higher
2. **Macro-generated code**: Macros like `#[derive(Serialize)]` add implicit serde dependency
3. **Runtime plugin loading**: If any crate loads code dynamically, static analysis misses it
4. **Workspace member changes**: Adding/removing crates from workspace invalidates crate-level graph
## Confidence Assessment
## Recommendations for Improved Analysis
| Aspect | Confidence |
|--------|------------|
| Crate-level dependencies | High (from Cargo.toml) |
| Module tree structure | High (from mod declarations) |
| Cross-crate imports | Medium (regex-based) |
| Intra-module coupling | Low (not analyzed) |
| Runtime dependencies | Not captured |
1. Use `cargo metadata` for authoritative crate graph
2. Use `cargo tree` for transitive dependency analysis
3. Use `rust-analyzer` for semantic import resolution
4. Parse AST for type references beyond `use` statements

53
analysis/deps/sccs.md
View File

@@ -1,44 +1,27 @@
# Strongly Connected Components Analysis
# Strongly Connected Components (Cycles)
## Method
## Summary
Tarjan's algorithm applied to file-level dependency graph.
| Metric | Value |
|--------|-------|
| Non-trivial SCCs | 0 |
| Total nodes in cycles | 0 |
Edge types considered:
- `mod_declaration`: Parent module declares child module
- `cross_crate_import`: File imports from another crate
## Analysis
## Results
No strongly connected components with more than one node were detected in the dependency graph.
**No non-trivial SCCs detected.**
This indicates the codebase has a **directed acyclic graph (DAG)** structure at both the crate and file level for the dependencies that were extracted.
The file-level dependency graph is acyclic. All `mod` declarations form a strict tree structure within each crate, and cross-crate imports follow the crate dependency DAG.
## Methodology
## Crate-Level Cycle Analysis
- Tarjan's algorithm applied to all 108 nodes and 186 edges
- Only SCCs with 2+ nodes reported (trivial single-node SCCs excluded)
- Analysis covers `use` statement imports only
The crate dependency graph was also analyzed:
## Caveats
```
g3 → g3-cli → g3-core → g3-providers
→ g3-config
→ g3-execution
→ g3-computer-control
→ g3-planner → g3-core
→ g3-providers
→ g3-config
→ g3-ensembles → g3-core
→ g3-config
```
**No cycles detected at crate level.**
The workspace forms a directed acyclic graph (DAG) with:
- Leaf crates: `g3-providers`, `g3-config`, `g3-execution`, `g3-computer-control`, `studio`
- Mid-tier crates: `g3-core`, `g3-planner`, `g3-ensembles`
- Top-tier crates: `g3-cli`, `g3`
## Implications
- No circular dependencies exist
- Build order is deterministic
- Crates can be compiled in parallel respecting the DAG
1. **Trait implementations**: Mutual trait dependencies not captured by `use` statements
2. **Type references**: Types referenced without explicit `use` not detected
3. **Macro expansions**: Dependencies introduced by macros not traced
4. **Build-time dependencies**: `build.rs` dependencies not included