95d9847354
- hotspots.md: Added specific dependent file lists for each hotspot - hotspots.md: Added cross-crate coupling points table - hotspots.md: Added crate-level coupling scores - limitations.md: Expanded coverage of unobservable patterns - limitations.md: Added confidence levels for inferences - limitations.md: Added extraction method details table Agent: euler
115 lines
3.8 KiB
Markdown
115 lines
3.8 KiB
Markdown
# 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
|