Update dependency analysis artifacts with detailed evidence
- 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
This commit is contained in:
Dhanji R. Prasanna
@@ -1,67 +1,114 @@
|
||||
# Analysis Limitations
|
||||
|
||||
## What Was Observed
|
||||
|
||||
| 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 |
|
||||
**Generated**: 2025-02-02
|
||||
|
||||
## What Could Not Be Observed
|
||||
|
||||
### 1. Implicit Dependencies
|
||||
### 1. Dynamic/Runtime Dependencies
|
||||
|
||||
- **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(...)]`
|
||||
- **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. Dynamic Patterns
|
||||
### 2. Macro-Generated Code
|
||||
|
||||
- **Trait objects**: `dyn Trait` usage creates runtime dependencies
|
||||
- **Generic bounds**: `T: SomeTrait` constraints
|
||||
- **Associated types**: Dependencies through associated type resolution
|
||||
- **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 not evaluated
|
||||
- **Feature flags**: `#[cfg(feature = "...")]` dependencies not traced
|
||||
- **Test-only code**: `#[cfg(test)]` modules excluded
|
||||
- **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. Build System
|
||||
### 4. Re-exports and Transitive Dependencies
|
||||
|
||||
- **build.rs**: Build script dependencies not analyzed
|
||||
- **Procedural macros**: Macro crate dependencies not traced
|
||||
- **Workspace-level features**: Feature unification effects not modeled
|
||||
- **`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. Excluded Files
|
||||
### 5. External Crate Dependencies
|
||||
|
||||
| Category | Count | Reason |
|
||||
|----------|-------|--------|
|
||||
| Test files (`/tests/`) | ~40 | Out of scope |
|
||||
| Example files (`/examples/`) | ~10 | Out of scope |
|
||||
| Worktree copies | ~100 | Duplicates |
|
||||
- **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
|
||||
|
||||
| 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 |
|
||||
### 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. **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
|
||||
### 1. Code Changes
|
||||
|
||||
## Recommendations for Improved Analysis
|
||||
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
|
||||
|
||||
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
|
||||
### 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
|
||||
|
||||
Reference in New Issue
Block a user