g3/analysis/deps/limitations.md

Analysis Limitations

Extraction Method

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 Could Not Be Observed

1. Conditional Compilation

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)])

Impact: Some edges may only exist on specific platforms or with specific features enabled.

Affected crates:

• g3-computer-control: Has platform-specific modules (macos.rs, linux.rs, windows.rs)
• g3-providers: May have feature-gated provider implementations

2. Macro-Generated Code

Imports generated by procedural macros are not captured:

• #[derive(...)] macros
• async_trait macro expansions
• Custom derive macros

Impact: Some implicit dependencies on trait implementations may be missed.

3. Re-exports

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

Example: g3-providers/src/lib.rs likely re-exports types from submodules.

4. Dynamic Dispatch

Trait object usage (dyn Trait) creates runtime dependencies not visible in imports:

• Box<dyn LLMProvider>
• Arc<dyn UiWriter>

Impact: Actual runtime coupling may be higher than static analysis shows.

5. Build Script Dependencies

build.rs files were identified but not analyzed for:

• Generated code dependencies
• Native library linkage
• Environment-based configuration

Affected: g3-computer-control/build.rs

6. External Crate Dependencies

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)

7. Test File Dependencies

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

8. Example File Dependencies

Files in examples/ directories:

• Included in file counts
• May demonstrate usage patterns not representative of core dependencies
• Often have simplified or demonstration-only imports

What Was Inferred

1. Module-to-File Mapping

mod foo; declarations were mapped to foo.rs or foo/mod.rs by convention.

Confidence: High (Rust standard convention)

2. Crate Root Identification

lib.rs was assumed to be the crate root for libraries. main.rs was assumed to be the binary entry point.

Confidence: High (Cargo convention)

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