Metadata-Version: 2.4
Name: git-hotspot-ai
Version: 0.1.0
Summary: Analyze git hotspots and trigger AI post-processing
Home-page: https://github.com/yourusername/git-hotspot-ai
Author: Your Name
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/git-hotspot-ai
Project-URL: Repository, https://github.com/yourusername/git-hotspot-ai
Project-URL: Issues, https://github.com/yourusername/git-hotspot-ai/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Git Hotspot AI

A lightweight CLI tool for analyzing git hotspots and triggering AI post-processing tasks.

## Features

- **Git Hotspot Analysis**: Identify the most frequently modified files in your repository
- **Flexible Filtering**: Filter by time range, file patterns, and minimum commit counts
- **AI Task Integration**: Trigger AI-powered analysis tasks on hotspot files
- **Configurable Output**: Select top files by percentage or absolute count
- **Dry Run Mode**: Preview results without executing AI tasks

## Installation

### From Source

```bash
git clone https://github.com/yourusername/git-hotspot-ai.git
cd git-hotspot-ai
pip install -e .
```

### Development Installation

```bash
git clone https://github.com/yourusername/git-hotspot-ai.git
cd git-hotspot-ai
pip install -e ".[dev]"
```

### Environment Setup

**Required**: Before using git-hotspot-ai, you must configure the cursor-agent path:

```bash
# Set the environment variable to point to your cursor-agent executable
export CURSOR_AGENT_PATH=/path/to/cursor-agent

# Or if cursor-agent is in your PATH:
export CURSOR_AGENT_PATH=$(which cursor-agent)

# Add to your shell profile for persistence:
echo 'export CURSOR_AGENT_PATH=$(which cursor-agent)' >> ~/.bashrc
# or for zsh:
echo 'export CURSOR_AGENT_PATH=$(which cursor-agent)' >> ~/.zshrc
```

## Usage

### Basic Usage

```bash
# analyze current directory
git-hotspot-ai

# analyze specific repository
git-hotspot-ai --repo /path/to/repo

# show top 20 files
git-hotspot-ai --top 20

# show top 15% of files
git-hotspot-ai --top 15%

# dry run (preview without AI tasks)
git-hotspot-ai --dry-run
```

### Advanced Options

```bash
# analyze files modified in the last 6 months
git-hotspot-ai --since "6 months ago"

# ignore test files and documentation
git-hotspot-ai --ignore "tests/*,docs/*,*.md"

# only consider files with at least 5 commits
git-hotspot-ai --min-commits 5

# run specific AI tasks
git-hotspot-ai --tasks "annotate,structure,performance"
```

### Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--repo` | Path to git repository | Current directory |
| `--top` | Top files to select (count or percentage) | `10%` |
| `--tasks` | Comma-separated AI tasks | `annotate,structure,skills,performance,mvp` |
| `--since` | Git time filter (e.g., "6 months ago") | None |
| `--dry-run` | Preview without AI tasks | False |
| `--ignore` | Glob patterns to ignore | Empty |
| `--min-commits` | Minimum commit count | 1 |
| `--cursor-agent-path` | Path to cursor-agent executable | `CURSOR_AGENT_PATH` env var |

## AI Tasks

The tool supports the following AI tasks:

- **annotate**: 为代码添加详细的注释和文档，提高代码可读性
- **structure**: 分析代码结构，识别重构机会和架构改进建议
- **skills**: 识别代码所需的技能和专业知识，分析技术栈和最佳实践
- **performance**: 分析性能特征，识别瓶颈并提出优化建议
- **mvp**: 生成最小可行产品建议，分析核心功能和简化方案

Each task generates specific prompts tailored to the file's git hotspot metrics (commit frequency, line changes, etc.).

## How It Works

1. **Git Analysis**: Uses `git log --numstat` to collect file modification statistics
2. **Scoring**: Combines commit count and line changes to score files
3. **Filtering**: Applies time range, ignore patterns, and minimum commit filters
4. **Selection**: Selects top files based on percentage or count
5. **AI Dispatch**: Triggers configured AI tasks on selected files

## Scoring Algorithm

Files are scored using the formula:
```
score = commit_count + 0.1 * line_changes
```

This balances the frequency of changes with the magnitude of changes.

## Examples

### Find Most Active Files

```bash
# top 10 most active files
git-hotspot-ai --top 10

# top 5% of files with at least 3 commits
git-hotspot-ai --top 5% --min-commits 3
```

### Analyze Recent Changes

```bash
# files modified in last 3 months
git-hotspot-ai --since "3 months ago"

# recent changes excluding tests
git-hotspot-ai --since "1 month ago" --ignore "test_*,*_test.py"
```

### Development Workflow

```bash
# preview what would be analyzed
git-hotspot-ai --dry-run --top 20

# run AI analysis on top files
git-hotspot-ai --top 20 --tasks "annotate,structure"

# use custom cursor-agent path
git-hotspot-ai --cursor-agent-path /usr/local/bin/cursor-agent --tasks "performance"
```

### Cursor Agent Integration

The tool integrates with cursor-agent CLI to perform AI analysis tasks:

```bash
# ensure cursor-agent is available
export CURSOR_AGENT_PATH=$(which cursor-agent)

# run analysis with specific tasks
git-hotspot-ai --tasks "annotate,performance" --top 5

# dry run to see what files would be processed
git-hotspot-ai --dry-run --tasks "structure,skills"
```

Each task generates contextual prompts that include:
- File path and git hotspot metrics
- Task-specific analysis requirements
- Chinese language instructions for better AI understanding

## Development

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black git_hotspot_ai/
isort git_hotspot_ai/
```

### Type Checking

```bash
mypy git_hotspot_ai/
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Changelog

### 0.1.0
- Initial release
- Basic git hotspot analysis
- CLI interface
- AI task dispatch framework
