g3/analysis/deps/limitations.md

Analysis Limitations

Generated: 2025-02-02

What Could Not Be Observed

1. Dynamic/Runtime Dependencies

• Plugin loading: Any runtime module loading via dlopen or similar
• Reflection-based imports: Dependencies resolved at runtime
• Configuration-driven imports: Modules loaded based on config values

2. Macro-Generated Code

• Procedural macros: Code generated by #[derive(...)] and custom proc macros
• Declarative macros: macro_rules! expansions that generate use statements
• Build script outputs: Code generated by build.rs files

3. Conditional Compilation

• Platform-specific code: #[cfg(target_os = "...")] blocks are included regardless of target
• Feature flags: #[cfg(feature = "...")] gated code is included unconditionally
• Test-only code: #[cfg(test)] modules are excluded from analysis

4. Re-exports and Transitive Dependencies

• pub use chains: Transitive re-exports are not fully traced
• Glob imports: use module::* does not enumerate specific items
• Prelude imports: Implicit prelude items are not tracked

5. External Crate Dependencies

• Third-party crates: Only internal g3 workspace crates are analyzed
• Workspace dependency versions: Version constraints not analyzed
• Optional dependencies: Not distinguished from required dependencies

What Was Inferred

1. Module Hierarchy

Module parent-child relationships inferred from:

• mod declarations in lib.rs and mod.rs files
• File system structure (foo/mod.rs implies foo module)

Confidence: High - Rust module system is deterministic

2. Crate Dependencies

Crate-level dependencies extracted from:

• Cargo.toml [dependencies] sections
• path = "..." declarations for workspace crates

Confidence: High - Cargo.toml is authoritative

3. File-Level Imports

File imports extracted via regex pattern matching:

• ^use (g3_|crate::) for internal imports
• ^(pub )?mod for module declarations

Confidence: Medium-High - May miss unusual import patterns

4. Fan-In/Fan-Out Counts

Coupling metrics derived from edge counts in dependency graph.

Confidence: Medium - Depends on completeness of edge extraction

What May Invalidate Conclusions

1. Code Changes

This analysis reflects the codebase state at generation time. Any of the following invalidate the analysis:

• New files added
• Import statements changed
• Module structure reorganized
• Cargo.toml dependencies modified

2. Incomplete Extraction

The regex-based extraction may miss:

• Multi-line use statements with unusual formatting
• Imports inside function bodies
• Imports in macro invocations
• extern crate declarations (deprecated but valid)

3. Test Code Exclusion

Test files (tests/*.rs, #[cfg(test)] modules) are excluded. Test-only dependencies and coupling patterns are not reflected.

4. Example Code Exclusion

Example files (examples/*.rs) are excluded from the graph.

5. Build Script Dependencies

build.rs files may introduce compile-time dependencies not reflected in the import graph.

Extraction Method Details

Aspect	Method	Tool
Crate dependencies	Cargo.toml parsing	Manual inspection
Module declarations	Regex: ^(pub )?mod	ripgrep
Internal imports	Regex: ^use (g3_|crate::)	ripgrep
File enumeration	find crates -name "*.rs"	find
Cycle detection	Manual graph traversal	N/A

Recommendations for Future Analysis

1. Use cargo metadata: cargo metadata --format-version 1 provides authoritative dependency information
2. Use rust-analyzer: LSP-based analysis would capture macro expansions
3. Use cargo-depgraph: Specialized tool for Rust dependency visualization
4. Include test coverage: Analyze test files separately for test-specific coupling