A powerful, free command-line tool that goes beyond simple linters. It acts as an architectural health monitoring system for your codebase, using dependency analysis, Git history, and AI to find deep, systemic issues before they become major problems.
Perfect for developers onboarding to a new project, conducting a tech-debt audit, or wanting to maintain high architectural quality over time.
-
🕵️♂️ Architectural Smell Detection: Automatically "sniffs" your codebase for common architectural problems:
- 💥 High Blast Radius: Finds "god files" that are imported everywhere and are risky to change.
- 👻 Ghost Files: Identifies critical source code in
src/that has no corresponding test file. - 🔗 Entanglement: Detects when different feature modules are improperly coupled.
- 🔄 Circular Dependencies: Finds and reports dependency loops that complicate your code.
- 👀 Stale Tests: Warns you when source code changes but its tests don't, indicating a potential gap in test coverage.
- 🔥 High Churn & 🕰️ Stale Logic: Uses Git history to find both unstable, rapidly changing files and abandoned code that may contain outdated logic.
-
🤖 AI-Powered Interactive Deep Dive: Don't just find problems—solve them. After identifying issues, the analyzer lets you select any smell for a deep-dive analysis with Google's Gemini AI, providing expert, context-specific refactoring advice.
-
🚀 Monorepo-Aware Dependency Analysis: Accurately builds a dependency graph for complex JavaScript/TypeScript projects by understanding
tsconfig.json/jsconfig.jsonpath aliases and monorepo workspaces (Yarn, Lerna, PNPM, NX). -
📊 Comprehensive Reporting:
- Console: A clean, color-coded report highlighting critical issues.
- File Tree: An optional, detailed view of your project structure with size warnings.
- Multiple Formats: Supports
JSON,Markdown, andHTMLoutputs for integration and documentation.
-
🧪 Test Coverage Integration: Automatically runs and displays your Jest test coverage summary.
- Python 3.8+
- Node.js and npm (for Jest coverage feature)
- Git command line (for history-based analysis)
- A Google API key (for all AI features)
-
Clone the repository:
git clone https://github.com/your-username/Project_Analyzer.git cd Project_Analyzer -
Run the quick setup script:
# This will create a virtual environment, install dependencies, and set up your .env file python setup.pyFollow the prompts to add your Google API key.
-
Activate the environment:
# On macOS/Linux source venv/bin/activate # On Windows .\venv\Scripts\activate
The analyzer is designed to be a "sniffer" first. The default command gives you the most important architectural health report.
# Run the default architectural analysis
python analyzer_main.py .After listing the issues, it will prompt you for an interactive AI deep dive.
# Get a visual tree of the entire project
python analyzer_main.py . --tree
# Run all analyses: architecture, coverage, and file tree
python analyzer_main.py . --full
# Generate a standalone HTML report
python analyzer_main.py . --html-reportFor detailed command-line options and configuration (like setting up custom rules for architectural boundaries or untestable files), please see USAGE.md.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
Please see CONTRIBUTING.md for our contribution guidelines and development setup.
This project is licensed under the MIT License. See the LICENSE file for details.
- Google's Gemini AI for powering the intelligent analysis features.
- The GitPython and Jinja2 communities for their excellent libraries.
- All contributors who help make this tool better.
Made with ❤️ for the developer community.
If this tool helps you understand or improve your project, please consider giving it a ⭐ star on GitHub!