TL;DR

  • treepeat는 Tree-sitter 추상 구문 트리(AST) 분석과 지역 민감 해싱(LSH)을 사용해 코드베이스에서 중복·유사 코드 블록을 찾는 도구임
  • 언어에 의미 있는 클래스·함수 단위의 중복부터 공백·문자열·상위 AST 노드를 무시한 근접 중복, 식별자·상수 등을 익명화한 구조적 유사성까지 탐지함
  • none, default, loose 규칙 세트와 1~100% 유사도 임계값, 최소 5줄 매치 기준으로 비교 방식을 조정함
  • astro, bash, css, go, html, javascript, lua, markdown, python, sql, typescript, java, kotlin, rust, yaml을 지원함
  • 콘솔·SARIF 출력, 유사 블록 비교, 진행률 표시, 단계별 실행 시간 등 대규모 코드베이스 분석과 CI 연동을 위한 기능을 제공함

개요

  • treepeat는 코드베이스에서 유사성을 찾는 도구임
  • 단순히 줄 단위가 아닌 언어에 의미 있는 코드 블록인 클래스·함수의 중복을 탐지하며, --ruleset none으로 사용함
  • 공백, 문자열, 함수와 이름 같은 상위 수준 AST 노드를 무시해 근접 중복을 탐지하며, --ruleset default로 사용함
  • 식별자·상수 등을 익명화해 구조적으로 유사한 코드를 탐지하며, --ruleset loose로 사용함
  • 현재 지원 언어 수가 많지 않은 개념 증명 단계이며, 풀 리퀘스트를 환영함
  • 지원 언어는 astro, bash, css, go, html, javascript, lua, markdown, python, sql, typescript, java, kotlin, rust, yaml임

사용법

설치

  • pip install treepeat 명령으로 설치함

`detect`

  • Tree-sitter AST 분석과 지역 민감 해싱을 사용해 코드베이스에서 유사하거나 중복된 코드 블록을 검색함
  • --ruleset은 비교 전에 코드를 정규화하는 규칙 세트이며, none, default, loose 중 하나를 사용함
  • --similarity는 유사도 백분율을 1~100으로 지정하며, 기본값은 정확히 중복된 코드를 찾는 100임
  • --min-lines는 매치에 필요한 최소 줄 수이며, 기본값은 5줄임
  • --diff는 유사 블록을 나란히 비교해 표시함
  • --format은 출력 형식으로 기본값인 console 또는 CI 연동용 sarif를 사용함
  • --verbose는 추가 실행 지표를 표시하며, 가능한 경우 단계별 실행 시간을 포함함
  • --progress는 오래 걸리는 파이프라인 단계의 진행률 표시줄을 제공함
  • 코드베이스 경로를 treepeat detect /path/to/codebase 형식으로 지정해 정확히 중복된 코드를 검색함
  • treepeat detect --similarity 80 /path/to/codebase 형식으로 80% 유사도 임계값의 근접 중복을 검색함
  • treepeat --ruleset loose detect --diff --min-lines 10 /path/to/codebase 형식으로 느슨한 규칙 세트를 사용하고, 비교 차이를 표시하며, 최소 10줄 블록을 검색함
  • treepeat detect --progress --verbose /path/to/codebase 형식으로 구문 분석 진행률과 상세 단계별 실행 시간을 표시함
  • treepeat detect --format sarif -o results.sarif /path/to/codebase 형식으로 CI 도구용 SARIF 형식 결과를 results.sarif에 출력함
  • --progress는 주로 대화형 CLI 피드백용이며, 현재 구현에서는 tqdm 진행률 표시줄을 표준 오류(stderr)에 기록하고 일반 명령 출력은 표준 출력(stdout) 또는 --output에 남김

기타 하위 명령

`list-ruleset`

  • 규칙 세트에 포함된 모든 규칙과 설명을 나열함
  • --language를 사용하면 특정 언어에 적용되는 규칙을 확인함

`treesitter`

  • 유사성 탐지를 위해 treepeat가 소스 코드를 Tree-sitter 토큰으로 정규화하는 방식을 표시함
  • 파일의 특정 구간이 다른 구간과 유사하게 판단되는 이유를 디버깅하는 데 활용함
  • 원본 소스 코드와 정규화된 토큰 표현을 나란히 표시함

개발 환경 설정

  • make setup으로 개발 환경을 설정함
  • make test로 테스트를 실행함
  • 실제 저장소를 벤치마킹하기 위한 성능 하네스는 tools/perf/harness.py에 있으며, 관련 문서는 docs에 있음

아키텍처 결정 기록

  • 아키텍처 결정 기록(ADR)은 docs/adr에 저장됨