@techdebtgpt/maintsight

🔍 MaintSight

AI-powered maintenance degradation predictor for git repositories using XGBoost machine learning

MaintSight analyzes your git repository's commit history and code patterns to predict maintenance degradation at the file level. Using a trained XGBoost model, it identifies code quality trends and helps prioritize refactoring efforts by detecting files that are degrading over time.

📋 Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Output Formats
• Degradation Categories
• Command Reference
• Model Information
• Development
• Testing
• Contributing
• License

✨ Features

• 🤖 XGBoost ML Predictions: Pre-trained model for maintenance degradation scoring
• 📊 Git History Analysis: Analyzes commits, changes, and collaboration patterns
• 📈 Multiple Output Formats: JSON, CSV, Markdown, or interactive HTML reports
• 🎯 Degradation Categorization: Four-level classification (Improved/Stable/Degraded/Severely Degraded)
• 🔍 Threshold Filtering: Focus on degraded files only
• 🌐 Interactive HTML Reports: Rich, interactive analysis with visualizations
• ⚡ Fast & Efficient: Analyzes hundreds of files in seconds
• 🛠️ Easy Integration: Simple CLI interface and npm package

🚀 Quick Start

# Install globally
npm install -g @techdebtgpt/maintsight

# Run predictions on current directory (generates interactive HTML report)
maintsight predict

# Show only degraded files
maintsight predict -t 0.1

# Generate markdown report
maintsight predict -f markdown -o report.md

# Generate standalone HTML report
maintsight predict -f html -o report.html

📦 Installation

Global Installation (Recommended)

npm install -g @techdebtgpt/maintsight

Local Installation

npm install @techdebtgpt/maintsight

From Source

git clone https://github.com/techdebtgpt/maintsight.git
cd maintsight-cli
npm install
npm run build
npm link

📖 Usage

Basic Prediction

# Analyze current directory
maintsight predict

# Analyze specific repository
maintsight predict /path/to/repo

# Save results to file
maintsight predict -o results.json

Advanced Options

# Analyze specific branch
maintsight predict -b develop

# Limit commit analysis window
maintsight predict -w 90  # Analyze last 90 days

# Limit number of commits
maintsight predict -n 5000

# Filter by degradation threshold
maintsight predict -t 0.1  # Show only degraded files

# Generate CSV for Excel
maintsight predict -f csv -o analysis.csv

# Generate standalone HTML report
maintsight predict -f html -o report.html

# Verbose output for debugging
maintsight predict -v

📊 Output Formats

JSON (Default)

[
  {
    "module": "src/legacy/parser.ts",
    "degradation_score": 0.3456,
    "raw_prediction": 0.3456,
    "risk_category": "severely_degraded"
  },
  {
    "module": "src/utils/helpers.ts",
    "degradation_score": -0.1234,
    "raw_prediction": -0.1234,
    "risk_category": "improved"
  }
]

CSV

module,degradation_score,raw_prediction,risk_category
"src/legacy/parser.ts","0.3456","0.3456","severely_degraded"
"src/utils/helpers.ts","-0.1234","-0.1234","improved"

Markdown Report

Generates a comprehensive report with:

• Degradation distribution summary
• Top 20 most degraded files
• Category breakdown with percentages
• Actionable recommendations

Interactive HTML Report

Always generated automatically in .maintsight/ folder with:

• Visual degradation trends
• Interactive file explorer
• Detailed metrics per file
• Commit history analysis

🎯 Degradation Categories

Score Range	Category	Description	Action
< 0.0	🟢 Improved	Code quality improving over time	Continue good practices
0.0-0.1	🔵 Stable	Code quality stable	Regular maintenance
0.1-0.2	🟡 Degraded	Code quality declining	Schedule for refactoring
> 0.2	🔴 Severely Degraded	Rapid quality decline	Immediate attention needed

📚 Command Reference

maintsight predict

Analyze repository and predict maintenance degradation.

maintsight predict [path] [options]

Options:

• -b, --branch <branch> - Git branch to analyze (default: "main")
• -n, --max-commits <n> - Maximum commits to analyze (default: 10000)
• -w, --window-size-days <n> - Time window in days for analysis (default: 150)
• -o, --output <path> - Output file path
• -f, --format <fmt> - Output format: json|csv|markdown|html (default: "json")
• -t, --threshold <n> - Degradation threshold filter (show files above this score)
• -v, --verbose - Verbose output

maintsight help

Show help information.

maintsight help

🧠 Model Information

MaintSight uses an XGBoost model trained on software maintenance degradation patterns. The model predicts how code quality changes over time by analyzing git commit patterns and code evolution metrics.

Key Features Analyzed

The model considers multiple dimensions of code evolution:

• Commit patterns: Frequency, size, and timing of changes
• Author collaboration: Number of contributors and collaboration patterns
• Code churn: Lines added, removed, and modified over time
• Change consistency: Regularity and predictability of modifications
• Bug indicators: Patterns suggesting defects or fixes
• Temporal factors: File age and time since last modification

Prediction Output

• degradation_score: Numerical score indicating code quality trend
  • Negative values: Quality improving
  • Positive values: Quality degrading
  • Higher magnitude = stronger trend
• risk_category: Classification based on degradation severity
• raw_prediction: Unprocessed model output

🔧 Development

Prerequisites

• Node.js >= 18.0.0
• TypeScript >= 5.3.0
• Git

Setup

# Clone repository
git clone https://github.com/techdebtgpt/maintsight.git
cd maintsight-cli

# Install dependencies
npm install

# Build project
npm run build

# Run in development mode
npm run cli:dev predict ./test-repo

Project Structure

maintsight-cli/
├── src/
│   ├── services/          # Core services
│   │   ├── git-commit-collector.ts
│   │   ├── feature-engineer.ts
│   │   └── xgboost-predictor.ts
│   ├── interfaces/       # TypeScript interfaces
│   │   ├── risk-prediction.interface.ts
│   │   ├── risk-category.enum.ts
│   │   └── ...
│   ├── utils/            # Utilities
│   │   └── simple-logger.ts
│   └── index.ts          # Main exports
├── cli/
│   ├── commands/         # CLI commands
│   │   └── predict.command.ts
│   ├── utils/           # CLI utilities
│   │   └── html-generator.ts
│   └── maintsight-cli.ts # CLI entry point
├── cli/models/
│   └── xgboost-model.json # XGBoost model
└── tests/               # Test files

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:cov

# Run specific test
npm test -- git-commit-collector.spec.ts

# Watch mode
npm run test:watch

Test Coverage Goals

• Services: 80%+
• Utils: 90%+
• CLI Commands: 70%+

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Write tests for your changes
• Ensure all tests pass (npm test)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Code Style

• Use TypeScript strict mode
• Follow ESLint rules
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed

🐛 Bug Reports

Found a bug? Please open an issue with:

• MaintSight version
• Node.js version
• Steps to reproduce
• Expected vs actual behavior
• Error messages/stack traces

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• XGBoost community for the excellent gradient boosting framework
• Git community for robust version control
• All contributors who help improve MaintSight

Made with ❤️ by the TechDebtGPT Team

Repository | Documentation | Issues