🛠️ Technical Debt Hotspot Analyzer

In Software Engineering, Technical Debt is the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer.

Everyone talks about it, but very few teams know how to quantify it. Managers often ask: "Where exactly is our technical debt, and how much is it costing us?"

This tool is designed to answer that question empirically. It acts as an autonomous Static Analysis CLI tool that runs against any Git Repository and mathematically calculates the "Hotspots"—the specific files and dependencies that are silently draining your engineering team's time and money.

The analyzer evaluates your codebase across three distinct dimensions of software decay:

Not all messy code is technical debt. If you wrote a horrible, complex script 5 years ago, but it works perfectly and no one ever needs to touch it, that is Legacy Code, not dangerous Technical Debt. It costs you nothing today.

However, if a highly complex file is being edited by developers every single week, it is a Ticking Time Bomb. It causes bugs, slows down feature delivery, and burns out developers.

The tool calculates a mathematical Debt Score for every Python file by combining:

• Cyclomatic Complexity (via radon): How convoluted and difficult to read the code is (if/else branching, loops, nested logic).
• Git Churn (via git log): How frequently the file is modified by developers.

The Formula:

(We use logarithmic churn because 100 commits vs 10 commits is a big deal, but 1000 commits vs 900 commits is just normal activity).

Developers often leave "IOUs" in the codebase disguised as comments like # TODO, # FIXME, # HACK, or # XXX. Over time, these accumulate and are forgotten. The analyzer scans the entire codebase to sum up this unresolved human debt, giving you a stark reminder of corners that were cut.

Software rots over time if not maintained. Old libraries introduce security vulnerabilities, missing features, and compatibility issues. The analyzer parses your requirements.txt, connects to the PyPI API (Python Package Index) in real-time, fetches the absolute latest available versions of your packages, and flags dependencies that are outdated.

Clone this repository (or copy the analyzer.py into your own project) and install the dependencies:

git clone https://github.com/karidasd/technical-debt-analyzer.git
cd technical-debt-analyzer
pip install -r requirements.txt

Run the tool against any Git Repository on your machine.

# Analyze the current directory
python analyzer.py .

# Analyze a specific project folder
python analyzer.py /path/to/my/awesome/project

The tool will process your history and output two things:

1. A Stunning Terminal UI: Powered by rich, showing progress bars and color-coded tables of your top hotspots directly in your console.
2. A Markdown Report (debt_report.md): A persistent file saved to the target directory containing your Top 10 Hotspot tables and your Outdated Dependencies, perfect for attaching to Jira tickets or GitHub Issues.

When you run the tool on a messy repository, you will get an exported debt_report.md that looks like this:

(In this example, auth.py is an absolute disaster: highly complex and constantly changing. helpers.py, despite having high churn, is very simple (complexity 12), so it is not heavily penalized).

You can integrate this script into your CI/CD pipeline (e.g., GitHub Actions). Have the pipeline run analyzer.py on every Friday night, and if the Debt Score of any file exceeds a certain threshold (e.g., > 300), automatically create a GitHub Issue assigning the engineering team to refactor it!

Once the Analyzer finds your Hotspots, what do you do?

1. Refactor High-Scoring Files: Break down the massive auth.py into smaller, single-purpose modules (Single Responsibility Principle).
2. Resolve Human Debt: Dedicate a "Tech Debt Friday" to actually fixing the # TODO items scattered in your code.
3. Bump Dependencies: Run a suite of unit tests, bump your requirements.txt to the latest versions, and patch the security holes.

If you want to dive deeper into managing Technical Debt and writing maintainable software, here are some highly recommended resources:

1. Refactoring: Improving the Design of Existing Code by Martin Fowler - The absolute bible on how to safely clean up messy code without breaking it.
2. Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin (Uncle Bob) - Essential reading for writing code that doesn't generate debt in the first place.
3. Working Effectively with Legacy Code by Michael C. Feathers - The ultimate guide for dealing with large, untested codebases (which is the definition of Technical Debt).

1. Coursera: Software Architecture (University of Alberta) - Excellent course on architectural patterns and how to prevent architectural debt.
2. Udemy: Clean Code - Practical examples of writing cleaner, more maintainable code in various languages.
3. Pluralsight: Managing Technical Debt - A specialized course on how to identify, measure, and communicate technical debt to management.

Built for true software engineering observability by DARKAIS.