Visualize and Analyze your TypeScript-based Architecture!
Detective leverages forensic code analysis at the architectural level to uncover hidden patterns in your codebase.
Gain an overview of your modules, domains, and layers:
The Change Coupling analysis reveals which modules have often been changed together, indicating a non-obvious type of coupling.
The Team Alignment Analysis shows whether your team structure and module/domain boundaries are aligned:
A Hotspot is a complex file with that was previously changed quite often and hence comes with a higher risk for bugs.
For each region, Detective calculates a hotspot score which is the product of the amount of changes and the complexity. You can see it as an sort index. Please keep in mind that this score is local to your analysis and hence cannot be compared with scores resulting from other analyses.
The slider on the top left defines when a region is identified as a hotspot. For instance, 33% defines that each region having 33% or more of the maximum hotspot score is a hotspot. For a better overview, these hotspots are seperated into two equal areas: the lower half is displayed yellow and the upper half is red.
When clicking on an region, the files in this region are displayed:
The tree can be resized horizontally. Also, each entry has a context menu that allows to focus the current entry (making the current entry the root entry) and selecting all children:
You can try it out quickly by running Detective in your project's root directory:
npm i @softarc/detective -D
npx detectiveIn case users have used multiple names, as appearing in the git log, use the aliases option in the file .detective/config.json created the first time detective runs:
{
[...]
"aliases": {
"jdoe": "John Doe",
"janedoe": "Jane Doe"
}
[...]
}For the Team Alignment Analysis, you need to map team names to the names of your team members as found in git log. This is done in the file .detective/config.json created the first time detective runs:
{
[...]
"teams": {
"alpha": ["John Doe", "Jane Doe"],
"beta": ["Max Muster", "Susi Sorglos"]
}
[...]
}Detective probes a set of default entry points by looking at files with the names index.ts and main.ts in several directories. If your project structure is different, you can add this entry with respective globs to your .detectice/config.json:
{
[...]
"entries": [
"packages/*/index.ts"
],
[...]
}By default, Detective uses all the entries in the git log and analyzes all .ts files. You can change this by filtering log entries out that contain a given string and by defining globs pointing to the files you want to analyze.
In the following example, commit messages containing the substring prettier formatting will be skipped and also files ending with *.spec.ts are not looked at.
{
[...]
"filter": {
"logs": [
"prettier formatting"
],
"files": [
"**/*.ts",
"!**/*.spec.ts"
]
},
[...]
}Please note that excluding tests can help to regarding to your goals. However, there are situations where you also want to analze the coupling between tests and the tested code.
To keep the git log cache small, only the first line of git commit messages, the user name and their email address, the commit hash and the date is respected by the filter.
Detective works with all TypeScript projects. If it's executed within an Nx project, it will use typical Nx patterns to retrieve the entry points into your apps and libs.
Detective stand on the shoulders of giants:
- Inspired by the Nx Dependency Graph.
- Inspired by Adam Tornhill's book Your Code as a Crime Scene, Second Edition
- Powered by Rainer Hahnekamp's awesome and high-quality work on our open source project Sheriff
If you like the idea of forensic code analysis, you'll love Adam Tornhill's product Code Scene that goes far beyond the scope of Detective.