Metadata-Version: 2.4
Name: git-forensic
Version: 0.1.0
Summary: Audit AI-authored code quality in git repositories
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: gitpython>=3.1
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# git-forensic

**Git 저장소에서 AI가 작성한 코드의 품질을 감사합니다.**

2026년, 공개 GitHub 커밋의 ~4%가 AI가 작성한 것이며, 연말까지 20%에 도달할 전망입니다.
`git-forensic`은 **"우리 레포의 AI 코드 품질은 몇 점인가?"** 라는 질문에 답합니다.

### 대시보드 — 품질 트렌드 & 파일 타입 분석
![Dashboard Overview](https://raw.githubusercontent.com/hyunseung1119/forensic/main/report-screenshot.png)

### 커밋별 품질 점수 상세
![Commit Table](https://raw.githubusercontent.com/hyunseung1119/forensic/main/report-screenshot-table.png)

---

## 설치 방법

### macOS / Linux

```bash
# 1. uv 설치 (미설치 시)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 설치 없이 바로 실행
uvx git-forensic /path/to/repo

# 또는 전역 설치 후 실행
uv tool install git-forensic
git-forensic /path/to/repo
```

### Windows (PowerShell)

```powershell
# 1. uv 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 터미널 재시작 후:
uvx git-forensic C:\path\to\repo

# 또는 전역 설치 후 실행
uv tool install git-forensic
git-forensic C:\path\to\repo
```

### Windows (CMD)

```cmd
:: 1. uv 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

:: 2. CMD 재시작 후:
uvx git-forensic C:\path\to\repo

:: 또는 전역 설치 후 실행
uv tool install git-forensic
git-forensic C:\path\to\repo
```

### pip (모든 플랫폼)

```bash
pip install git-forensic
git-forensic /path/to/repo
```

> **요구사항:** Python 3.11 이상, Git이 설치되어 PATH에 등록되어 있어야 합니다.

---

## 빠른 시작

```bash
# 현재 디렉토리 스캔
git-forensic .

# 특정 레포 스캔
git-forensic /path/to/my-project
```

바로 터미널에 등급과 품질 점수가 출력됩니다.

---

## 명령어 & 옵션

| 플래그 | 단축 | 설명 |
|--------|------|------|
| `--html FILE` | `-h` | HTML 대시보드 리포트 내보내기 |
| `--open` | | HTML 리포트를 브라우저에서 자동 열기 |
| `--json-out FILE` | `-o` | JSON 리포트 내보내기 |
| `--since DATE` | `-s` | 특정 날짜 이후 커밋만 스캔 (YYYY-MM-DD) |
| `--branch NAME` | `-b` | 특정 브랜치만 스캔 (기본: 전체) |
| `--min-confidence N` | `-c` | 신뢰도 임계값 0-1 (기본: 0.5) |
| `--limit N` | `-n` | 표시할 최대 커밋 수 (기본: 30) |
| `--name NAME` | | 리포트에 표시할 커스텀 레포 이름 |
| `--all-commits` | | 낮은 신뢰도의 휴리스틱 매치도 포함 |
| `--help` | | 도움말 표시 |

---

## 사용 예시

### 기본 스캔 (터미널 출력)

```bash
git-forensic .
```

### HTML 대시보드 + 브라우저 자동 열기

```bash
# macOS / Linux
git-forensic ./my-project --html report.html --open

# Windows
git-forensic C:\projects\my-app --html report.html --open
```

### 날짜 범위 필터링

```bash
# 2026년 이후 커밋만
git-forensic . --since 2026-01-01

# 최근 3개월
git-forensic . --since 2025-12-01
```

### CI/CD용 JSON 내보내기

```bash
git-forensic . --json-out audit.json
```

### 특정 브랜치 스캔

```bash
git-forensic . --branch main
git-forensic . --branch feature/auth
```

### 모든 커밋 표시 (낮은 신뢰도 포함)

```bash
git-forensic . --all-commits
```

### 레포 이름 익명화 (보안)

```bash
git-forensic . --html report.html --name "my-project"
```

### 옵션 조합 사용

```bash
git-forensic /path/to/repo \
  --since 2026-01 \
  --html report.html \
  --json-out report.json \
  --name "project-x" \
  --open
```

---

## 터미널 출력 예시

```
┌──────────────────────────── git-forensic ────────────────────────────┐
│ Total Commits:    168                                                │
│ AI Commits:       12 (7.1%)                                          │
│ AI Lines Added:   +1,212                                             │
│ Quality Grade:    B (78.5/100)                                       │
│ Models:           Claude Opus: 7 | Claude Sonnet: 5                  │
└──────────────────────────────────────────────────────────────────────┘

Quality Breakdown:
  Commit Message  97.9  ████████████████████████░  25%
  Change Size     96.2  ████████████████████████░  30%
  Test Coverage   45.0  ███████████░░░░░░░░░░░░░░  30%  ← 약점
  Documentation   77.5  ████████████████████░░░░░  15%
```

---

## 품질 측정 기준

| 항목 | 비중 | 측정 내용 |
|------|------|----------|
| Commit Message | 25% | Conventional Commit 형식, 길이, 설명성 |
| Change Size | 30% | 집중된 변경 vs 대규모 리팩토링 |
| Test Coverage | 30% | 코드 변경에 테스트가 동반되었는지 |
| Documentation | 15% | 문서 커밋 여부, 자기 설명적 메시지 |

## AI 감지 시그널

| 시그널 | 신뢰도 | 예시 |
|--------|--------|------|
| `Co-Authored-By: Claude` | 95% | Claude Code 커밋 |
| `Co-Authored-By: GitHub Copilot` | 95% | Copilot 제안 |
| `Generated by Claude/GPT` | 85% | 명시적 AI 태그 |
| `aider:` 접두사 | 90% | Aider CLI 커밋 |
| Conventional Commit + 구조화된 설명 | <40% | 휴리스틱 (낮은 신뢰도) |

---

## 기술 스택

- **Python 3.11+** — **uv**로 빠른 패키지 관리
- **GitPython** — 커밋 히스토리 파싱
- **Rich** — 터미널 UI (테이블, 바, 색상)
- **Click** — CLI 인터페이스
- 외부 API 호출 없음 — 100% 로컬 실행

## 라이선스

MIT
