Entanglement Engine
Find files that change together
The Entanglement Engine discovers files that frequently change together in commits, revealing implicit dependencies that import statements can't show. If two files change together more than 15% of the time, they're likely coupled.
Overview
The Entanglement Engine analyzes your git history to find files that tend to change together, even when they have no direct import relationship. This reveals 'spooky action at a distance' - when modifying File A usually requires changes to File B, even though there's no obvious connection in the code.
How It Works
- Co-Change Analysis: Analyzes all commits to find pairs of files that are modified in the same commit.
- Frequency Calculation: Calculates the percentage of times each file pair changes together relative to total changes.
- Threshold Filtering: Filters to show only significant relationships (default >15% co-change rate).
- Coupling Report: Generates a report showing coupled files with their co-change percentage and last shared commit.
Technical Details
Uses `git log --name-only` to extract file lists from each commit. Builds an adjacency matrix of file co-occurrences and normalizes by individual file change frequency. Supports configurable thresholds and can exclude test files from analysis.
Use Cases
Prevent Breaking Changes
When your AI modifies a file, it sees which other files typically change with it and can proactively check them.
Architecture Discovery
Reveal hidden architectural dependencies that should perhaps be made explicit through proper interfaces.
Refactoring Safety
Understand the true blast radius of changes before refactoring interconnected components.
Configuration Options
| Option | Default | Description |
|---|---|---|
couplingThreshold | 15 | Minimum co-change percentage to consider files coupled |
minCommits | 3 | Minimum shared commits required to establish coupling |
excludeTests | false | Exclude test files from coupling analysis |