DiffCatcher

🎯 주요 기능

• 저장소 검색: 구성 가능한 필터로 디렉터리를 재귀적으로 스캔하여 Git 저장소 탐색
• 상태 추적: 커밋 해시, 메시지, 더티(dirty) 감지를 포함한 pull 전/후 상태 캡처
• 차이 생성: 파일 매니페스트와 함께 자동 N vs N-1 및 과거 차이 생성
• 요소 추출: 10개 이상의 언어에 대해 함수, 구조체, 클래스, 임포트 등을 식별하는 차이 파싱
• 코드 조각: 경계 탐지 및 컨텍스트 윈도우로 전체 전/후 코드 추출
• 보안 태깅: 18개의 내장 보안 패턴 (암호화, 인증, 비밀, SQL 인젝션, XSS 등)
• 다중 형식 보고서: JSON, Markdown, 텍스트 및 SARIF 출력 (저장소 간 보안 개요 포함)
• 브랜치 차이 모드: 단일 저장소에서 두 개의 ref(브랜치, 태그, 커밋) 차이 — PR 리뷰에 이상적
• 성능: 진행률 표시줄, LRU 캐싱, 증분 모드를 사용한 병렬 처리

왜 bash만 사용하지 않나요?

ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done 같은 원라이너는 원시 차이만 보여줍니다. DiffCatcher는 재귀적 탐색, 코드 요소 추출, 보안 패턴 감지, CI/CD를 위한 SARIF 출력, 병렬 처리, 저장소 간 보안 집계를 추가합니다. 아래의 전체 비교를 참조하세요.

📋 목차

• 설치
• 빠른 시작
• 사용법
  • 기본 스캔
  • Pull 모드
  • 추출 옵션
  • 보안 태깅
  • 설정 파일
  • 플러그인 시스템
  • 브랜치 차이 모드 (PR 리뷰)
  • SARIF 출력
  • 고급 기능
• 보고서 구조
• 설정
• 아키텍처
• 테스트
• 문서
• 기여

🚀 설치

소스에서 설치

git clone https://github.com/Teycir/DiffCatcher.git
cd DiffCatcher
cargo build --release
./target/release/diffcatcher --help

요구 사항

• Rust 1.70+
• Git 2.0+

⚡ 빠른 시작

# 디렉터리 내 모든 저장소 스캔 (fetch 전용, 수정 없음)
diffcatcher ~/projects

# 업데이트 pull 및 보안 보고서 생성
diffcatcher ~/projects --pull -o ./report

# 단일 저장소에서 두 브랜치 차이 (PR 리뷰 모드)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# GitHub Code Scanning용 SARIF 출력 생성
diffcatcher ~/projects --summary-format sarif,json -o ./report

# 스캔할 항목을 확인하는 드라이런
diffcatcher ~/projects --dry-run

# 8개의 병렬 워커로 빠른 스캔
diffcatcher ~/projects -j 8 --quiet

📖 사용법

기본 스캔

# 기본 설정으로 스캔 (fetch 전용)
diffcatcher <ROOT_DIR>

# 사용자 지정 출력 디렉터리
diffcatcher ~/projects -o ./my-report

# 중첩 저장소 포함 및 심볼릭 링크 따라가기
diffcatcher ~/projects --nested --follow-symlinks

# 숨김 디렉터리 건너뛰기
diffcatcher ~/projects --skip-hidden

Pull 모드

# Fetch만 (기본값 - 워킹 트리 변경 없음)
diffcatcher ~/projects

# 실제로 변경 사항 pull
diffcatcher ~/projects --pull

# 더티 저장소에 대해 stash/pop으로 강제 pull
diffcatcher ~/projects --pull --force-pull

# 리베이스 전략 사용
diffcatcher ~/projects --pull --pull-strategy rebase

# fetch/pull 완전히 건너뛰기 (과거 차이만)
diffcatcher ~/projects --no-pull

추출 옵션

# 요소 추출 건너뛰기 (원시 차이만)
diffcatcher ~/projects --no-summary-extraction

# 요소는 추출하지만 코드 조각은 건너뛰기
diffcatcher ~/projects --no-snippets

# 조각 컨텍스트 및 제한 조정
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# 차이당 요소 제한
diffcatcher ~/projects --max-elements 1000

보안 태깅

# 보안 태깅 건너뛰기
diffcatcher ~/projects --no-security-tags

# 보안 분석에 테스트 파일 포함
diffcatcher ~/projects --include-test-security

# 사용자 지정 보안 패턴 사용
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

설정 파일

DiffCatcher는 다음 위치에서 프로젝트 로컬 설정을 자동으로 로드할 수 있습니다:

• <ROOT_DIR>/.diffcatcher.toml (기본값)
• --config <FILE>을 통한 사용자 지정 파일
• --no-config로 비활성화

예시:

output = "reports-local"
no_pull = true
history_depth = 2
summary_formats = ["json", "txt"]
no_security_tags = false

[plugins]
security_pattern_files = ["plugins/security-extra.json"]
extractor_files = ["plugins/extractors.json"]

CLI 플래그는 명시적으로 설정될 때 여전히 설정 값을 덮어씁니다.

플러그인 시스템

DiffCatcher는 두 가지 플러그인 유형을 지원합니다:

• 보안 패턴 플러그인: --security-plugin-file <FILE> (반복 가능)
• 추출기 플러그인: --extractor-plugin-file <FILE> (반복 가능)

보안 플러그인 형식은 --security-tags-file JSON(version, mode, tags)과 일치합니다.

추출기 플러그인 형식:

{
  "version": 1,
  "extractors": [
    {
      "name": "policy-rule",
      "kind": "Config",
      "regex": "^policy\\s+([A-Za-z_][A-Za-z0-9_]*)"
    }
  ]
}

브랜치 차이 모드 (PR 리뷰)

# 단일 저장소에서 두 브랜치 차이
diffcatcher ./my-repo --diff main..feature/auth

# 특정 커밋 차이
diffcatcher ./my-repo --diff abc123..def456

# CI 통합용 SARIF 출력으로 차이
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

--diff BASE..HEAD 플래그는 저장소 검색 및 fetch/pull을 건너뜁니다. 두 ref(브랜치, 태그 또는 커밋 SHA)를 직접 비교하고 결과에 대해 전체 추출 + 보안 태깅 파이프라인을 실행합니다.

SARIF 출력

# 다른 형식과 함께 SARIF 생성
diffcatcher ~/projects --summary-format sarif,json,md

# CI/CD 업로드용 SARIF 전용
diffcatcher ~/projects --summary-format sarif -o ./report

--summary-format에 sarif가 포함되면 results.sarif 파일이 보고서 루트에 생성됩니다. 이 파일은 SARIF 2.1.0 표준을 따르며 GitHub Code Scanning, VS Code SARIF Viewer, Azure DevOps 및 기타 SARIF 호환 도구와 통합됩니다.

고급 기능

# 증분 모드 (변경되지 않은 저장소 건너뛰기)
diffcatcher ~/projects --incremental -o ./report

# 브랜치 패턴으로 필터링
diffcatcher ~/projects --branch-filter "main"

# 과거 깊이 조정
diffcatcher ~/projects --history-depth 5

# CI/CD용 JSON 출력
diffcatcher ~/projects --quiet --json > result.json

# 발견된 경로를 포함한 자세한 출력
diffcatcher ~/projects --verbose

📁 보고서 구조

<report_dir>/
├── summary.json                    # 전체 요약
├── summary.md                      # Markdown 요약
├── results.sarif                   # SARIF 2.1.0 출력 (--summary-format sarif일 때)
├── security_overview.json          # 저장소 간 보안 집계
├── security_overview.md
├── <repo-name>/
│   ├── status.json                 # 저장소 상태
│   ├── pull_log.txt
│   └── diffs/
│       ├── diff_N_vs_N-1.patch     # 원시 통합 차이
│       ├── changes_N_vs_N-1.txt    # 파일 매니페스트
│       ├── summary_N_vs_N-1.json   # 요소 추출
│       ├── summary_N_vs_N-1.md
│       └── snippets/
│           ├── 001_validate_token_ADDED.rs
│           ├── 002_check_permissions_BEFORE.rs
│           ├── 002_check_permissions_AFTER.rs
│           └── 002_check_permissions.diff
└── ...

⚙️ 설정

CLI 플래그

플래그	기본값	설명
-o, --output	./reports/<timestamp>	보고서 출력 디렉터리
-j, --parallel	4	동시 저장소 처리
-t, --timeout	120	Git 작업 시간 제한 (초)
-d, --history-depth	2	차이를 생성할 과거 커밋 수
--snippet-context	5	변경 주변 컨텍스트 라인
--max-snippet-lines	200	조각당 최대 라인 수
--max-elements	500	차이당 최대 요소 수
--diff	—	단일 저장소에서 두 ref 차이 (BASE..HEAD)
--summary-format	json,md	출력 형식: json, md, txt, sarif

모든 옵션은 diffcatcher --help를 참조하세요.

사용자 지정 보안 패턴

사용자 지정 패턴을 포함한 JSON 파일을 생성하세요:

{
  "version": 1,
  "mode": "extend",
  "tags": [
    {
      "tag": "pii-handling",
      "description": "PII 데이터 처리",
      "severity": "High",
      "patterns": ["ssn", "social_security", "passport"]
    }
  ]
}

--security-tags-file ./patterns.json과 함께 사용합니다.

🏗️ 아키텍처