chore(analysis): update dependency analysis artifacts
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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user