detective
A forensic code analysis tool that visualizes and analyzes TypeScript-based architecture to uncover hidden patterns and coupling.
What is detective?
Detective is a forensic code analysis tool that visualizes and analyzes TypeScript-based architecture to uncover hidden patterns, coupling, and hotspots in your codebase. It helps teams understand their project structure, identify architectural issues, and align team boundaries with code organization by analyzing git history and code complexity.
TypeScript developers and teams working on large-scale Angular or Nx projects who need to understand architectural dependencies, improve code maintainability, and align team structures with code organization.
Detective provides unique forensic analysis capabilities that go beyond static dependency graphs by incorporating git history to reveal hidden coupling and team alignment issues, helping teams make data-driven architectural decisions.
Overview
Detective is a forensic code analysis tool that visualizes and analyzes TypeScript-based architecture to uncover hidden patterns, coupling, and hotspots in your codebase. It helps teams understand their project structure, identify architectural issues, and align team boundaries with code organization.
Key Features
- Project Structure Visualization — Provides an overview of modules, domains, and layers to understand code organization.
- Change Coupling Analysis — Reveals which modules are frequently changed together, indicating hidden architectural coupling.
- Team/Code Alignment Analysis — Shows whether team structures align with module and domain boundaries.
- Hotspot Detection — Identifies complex, frequently changed files with higher bug risk using a calculated hotspot score.
- Git Log Integration — Analyzes commit history to derive insights about code evolution and team contributions.
- Configurable Analysis — Supports custom entry points, team definitions, aliases, and filtering of git logs and files.
Philosophy
Detective applies forensic analysis techniques to code architecture, treating the codebase as a crime scene to uncover hidden patterns and improve maintainability through data-driven insights.
Use Cases
Best For
- Identifying hidden architectural coupling between TypeScript modules
- Visualizing project structure and dependencies in large codebases
- Analyzing team alignment with code ownership boundaries
- Detecting high-risk code hotspots that need refactoring
- Understanding code evolution patterns through git history analysis
- Improving maintainability of Angular and Nx-based projects
Not Ideal For
- Projects not using TypeScript or with minimal TypeScript code
- Teams requiring real-time architectural feedback during active development
- Codebases with sparse or poorly maintained git history
- Organizations needing cross-language dependency analysis beyond TypeScript
Pros & Cons
Pros
Integrates commit history to uncover hidden coupling and team contributions, as shown in change coupling and team alignment visualizations that rely on git log data.
Allows custom entry points via globs in config.json, supporting non-standard project structures beyond default index.ts files, as detailed in the configuration section.
Calculates hotspot scores from change frequency and complexity to prioritize refactoring, with visual treemaps and sliders for interactive analysis, as explained in the hotspot detection feature.
Visualizes alignment between team structures and code modules using configurable team definitions from git logs, helping improve organizational efficiency, as demonstrated in the team alignment analysis.
Cons
Exclusively analyzes TypeScript files, ignoring JavaScript, CSS, or other assets, which restricts usefulness in polyglot projects or those transitioning from JavaScript.
Requires manual setup of aliases, teams, and filters in config.json, which can be time-consuming for large teams or projects with complex git histories.
Analysis accuracy hinges on clean, consistent git logs; noisy commit messages or incomplete history can skew results, as noted in the filtering limitations section.
Open Source Alternative To
detective is an open-source alternative to the following products:
Frequently Asked Questions
Related Projects
sondaUniversal visualizer and analyzer for JavaScript and CSS. Compatible with most bundlers and frameworks
microwaveCutleries to help you cook better apps.
ng-event-pluginsA tiny library for improving DX around events handling in Angular apps
ngx-unusedFind declared but unused Angular classes in your codebase.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.