Use Cases¶
Concrete scenarios where drift provides actionable insight. Each case follows the pattern: Problem → Solution with drift → Command → What you see.
1. Pattern Fragmentation in a Connector Layer¶
Problem: A service has 4+ API connectors. Each implements error handling
differently — bare except, custom exceptions, retry decorators, silent
fallbacks. Code reviews don't catch this because each file looks fine in
isolation.
Solution: drift's PFS signal detects that the same concern is implemented N different ways within a directory.
What you see: A PFS finding with score 0.96: "26 error_handling variants in connectors/" — listing every file that diverges.
Next step: Agree on one error-handling pattern, extract a shared base, and refactor the outliers.
2. Architecture Boundary Violation¶
Problem: A database model file imports directly from the API layer, creating a hidden circular dependency. Tests still pass, but test isolation is fragile and refactoring becomes risky.
Solution: drift's AVS signal detects imports that cross defined or inferred layer boundaries.
What you see: AVS finding — "DB import in API layer at src/api/auth.py:18". CI blocks the merge until the import direction is fixed.
Next step: Move the shared type or function to a neutral module (e.g.
shared/types.py) and update both layers to import from there.
3. Duplicate Utility Code from AI Scaffolding¶
Problem: AI code generation created 6 identical _run_async() helper
functions across separate Celery task files instead of finding the existing
shared utility.
Solution: drift's MDS signal detects near-identical functions with AST structural similarity ≥ 0.80.
drift analyze --repo . --format json | python -c "
import json, sys
for f in json.load(sys.stdin)['findings']:
if f['signal'] == 'mutant_duplicates':
print(f['title'], f['location'])
"
What you see: MDS findings listing all 6 locations with similarity scores ≥ 0.95.
Next step: Extract the function into a shared module
(e.g. tasks/utils.py) and replace all copies.
4. Complex Undocumented Functions¶
Problem: A rapidly growing codebase has accumulated several functions with 8+ parameters, deep nesting, and no docstrings. New team members spend hours understanding them before making changes.
Solution: drift's EDS signal flags functions whose complexity exceeds a threshold while lacking documentation.
What you see: EDS findings with score ≥ 0.7 pointing to specific functions and their file locations.
Next step: Add docstrings and type annotations to the flagged functions, or refactor them into smaller, self-documenting units.
5. Monitoring Drift Score in CI¶
Problem: The team wants to track whether their codebase is getting more or less coherent over time, without blocking PRs on day one.
Solution: Use drift in report-only mode in the GitHub Actions pipeline.
# .github/workflows/drift.yml
name: Drift
on: [push, pull_request]
jobs:
drift:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: mick-gsk/drift@v1
with:
fail-on: none
upload-sarif: "true"
What you see: Findings appear as PR annotations in GitHub Code Scanning. The drift score is logged in the action output for trend tracking.
Next step: After reviewing findings for 2–3 sprints, tighten the gate:
fail-on: high.
6. Running drift on a Demo Project¶
Problem: You want to see what drift output looks like before running it on a production codebase.
Solution: The repository includes a demo project with intentional drift patterns.
git clone https://github.com/mick-gsk/drift.git
cd drift/examples/demo-project
pip install -q drift-analyzer
drift analyze --repo .
What you see: Findings for pattern fragmentation (PFS), architecture violation (AVS), and mutant duplicates (MDS) — all intentionally planted.
Next step: Try on your own repository: drift analyze --repo /path/to/your/project.