git-workreport/README.md

A powerful GitHub plugin that generates AI-powered work reports from Git commit history for specified dates. Perfect for DevOps teams and development companies to track and validate work progress with intelligent summaries.

# Git Work Report

A powerful GitHub plugin that generates AI-powered work reports from Git commit history for specified dates. Perfect for DevOps teams and development companies to track and validate work progress with intelligent summaries.

## Features

- 🤖 **AI-Powered Summaries**: Generate intelligent summaries using Anthropic's Claude AI
- 📅 **Date-based reporting**: Generate reports for any specific date
- 📊 **Comprehensive statistics**: Track commits, total lines changed, and authors
- 🎨 **Multiple formats**: Output in text, JSON, or Markdown formats
- ⚡ **Fast and efficient**: Built with TypeScript and optimized for performance
- 🌍 **Timezone support**: Handle different timezones for accurate reporting

## Installation

```bash
npm install -g git-workreport
```

## Quick Start

### Basic Usage

Generate a work report for today:
```bash
git-workreport
```

Generate a work report for a specific date:
```bash
git-workreport 11/08/2025
```

### AI-Powered Summaries

Generate a report with AI-generated summary (requires Anthropic API key):
```bash
git-workreport 11/08/2025 --anthropic-key YOUR_API_KEY
```

### Advanced Usage

Generate a report in JSON format:
```bash
git-workreport 11/08/2025 --format json
```

Save report to a file:
```bash
git-workreport 11/08/2025 --output reports/work-report.txt
```

Generate Markdown report with AI summary:
```bash
git-workreport 11/08/2025 --format markdown --output report.md --anthropic-key YOUR_API_KEY
```

## Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `[date]` | Date in DD/MM/YYYY format | Today |
| `-f, --format <format>` | Output format: text, json, or markdown | text |
| `-o, --output <file>` | Output file path | Console output |
| `--no-stats` | Exclude statistics from the report | false |
| `--no-files` | Exclude file lists from the report | false |
| `--timezone <tz>` | Timezone for date parsing | local |
| `--repo <path>` | Path to Git repository | Current directory |
| `--anthropic-key <key>` | Anthropic API key for AI-generated summaries | None |

## Examples

### Example 1: Daily Work Report with AI Summary
```bash
git-workreport 15/08/2025 --anthropic-key YOUR_API_KEY
```

**Output:**
```
================================================================================
GIT WORK REPORT - 15/08/2025
================================================================================

SUMMARY:
  Date: 15/08/2025
  Total Commits: 8
  Total Lines Changed: 312
  Authors: John Doe, Jane Smith

AI-GENERATED SUMMARY:
  Implemented user authentication system with login/logout functionality and 
  responsive design improvements. Added comprehensive test coverage and fixed 
  several UI bugs across the application.

STATISTICS:
  Insertions: 245 lines
  Deletions: 67 lines
  Net Changes: 178 lines
  Average Commits per Author: 4.00

================================================================================
Report generated on 8/15/2025, 5:30:45 PM
```

### Example 2: JSON Report
```bash
git-workreport 15/08/2025 --format json --output report.json
```

**Output:**
```json
{
  "date": "15/08/2025",
  "totalCommits": 8,
  "totalInsertions": 245,
  "totalDeletions": 67,
  "authors": ["John Doe", "Jane Smith"],
  "aiSummary": "Implemented user authentication system with login/logout functionality and responsive design improvements. Added comprehensive test coverage and fixed several UI bugs across the application.",
  "totalLinesChanged": 312
}
```

### Example 3: Markdown Report
```bash
git-workreport 15/08/2025 --format markdown --output report.md
```

**Output:**
```markdown
# Git Work Report - 15/08/2025

**Generated:** 8/15/2025, 5:30:45 PM

## Summary

| Metric | Value |
|--------|-------|
| Date | 15/08/2025 |
| Total Commits | 8 |
| Total Lines Changed | 312 |
| Authors | John Doe, Jane Smith |

## AI-Generated Summary

> Implemented user authentication system with login/logout functionality and 
> responsive design improvements. Added comprehensive test coverage and fixed 
> several UI bugs across the application.

## Statistics

- **Insertions:** 245 lines
- **Deletions:** 67 lines
- **Net Changes:** 178 lines
- **Average Commits per Author:** 4.00
```

## AI Summary Features

The AI-powered summary feature uses Anthropic's Claude AI to analyze commit messages and generate intelligent summaries of daily work. The AI:

- **Analyzes commit messages** to understand what work was accomplished
- **Provides context** about the types of changes made
- **Summarizes in simple language** that's easy to understand
- **Focuses on the most important changes** from the day
- **Falls back gracefully** to basic summaries when AI is not available

To use AI summaries, you'll need an Anthropic API key. Get one at [https://console.anthropic.com/](https://console.anthropic.com/).

## Use Cases

### For Development Companies
- **Client Reporting**: Generate intelligent daily/weekly work summaries for clients
- **Progress Tracking**: Monitor team productivity with AI-generated insights
- **Project Validation**: Verify work completed on specific dates with clear summaries
- **Time Tracking**: Support time tracking systems with intelligent commit analysis

### For DevOps Teams
- **Deployment Validation**: Verify what code was deployed with AI summaries
- **Release Notes**: Generate intelligent release notes from commit history
- **Audit Trails**: Create audit reports with clear work descriptions
- **Performance Monitoring**: Track code changes with contextual summaries

## Programmatic Usage

You can also use the package programmatically:

```typescript
import { GitAnalyzer, ReportGenerator } from 'git-workreport';

async function generateReport() {
  const analyzer = new GitAnalyzer();
  const generator = new ReportGenerator();
  
  const report = await analyzer.generateWorkReport('15/08/2025', {
    anthropicApiKey: 'YOUR_API_KEY'
  });
  const formattedReport = generator.generateReport(report, { format: 'markdown' });
  
  console.log(formattedReport);
}
```

## Requirements

- Node.js >= 16.0.0
- Git repository (local or remote)
- Git command line tools
- Anthropic API key (optional, for AI summaries)

## Troubleshooting

### Common Issues

1. **"not a git repository" error**
   - Make sure you're in a Git repository directory
   - Use `--repo <path>` to specify repository location

2. **"Invalid date format" error**
   - Use DD/MM/YYYY format (e.g., 15/08/2025)
   - Alternative formats: YYYY-MM-DD, MM/DD/YYYY

3. **No commits found**
   - Verify the date has commits
   - Check timezone settings with `--timezone` option

4. **AI summary not working**
   - Ensure you have a valid Anthropic API key
   - Check your internet connection
   - The tool will fall back to basic summaries if AI is unavailable

### Getting Help

```bash
git-workreport --help
```

## 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