Fingerprint 명령어

codeknit fingerprint 명령어는 **Context-Triggered Piecewise Hashing(CTPH)**를 사용하여 코드베이스 전체에서 중복 및 근사 중복 코드를 탐지합니다. 변수 이름, 문자열 리터럴, 타입 주석을 정규화하여 구조적 핑거프린트를 계산하기 때문에 파일 간, 심지어 프로그래밍 언어 간에도 작동합니다.

기능

codeknit fingerprint는 코드베이스의 모든 함수, 메서드, 변수, 타입을 분석하고 다음을 기반으로 정규화된 구조적 핑거프린트를 계산합니다:

• 제어 흐름 (if, for, while, switch)
• 연산 (=, +, ==, &&, ||)
• 호출, 반환, 할당, 객체 생성
• try/catch, yield, await, defer와 같은 언어 구성 요소

이 정규화는 이름 변경된 복사-붙여넣기, 사소한 리팩터링, 다른 언어에서의 동등한 논리가 여전히 중복으로 탐지될 수 있음을 의미합니다.

이 알고리즘은 CTPH(롤링 해시 변형)를 사용하여 근사 중복을 효율적으로 찾습니다. 유사한 코드는 유사한 핑거프린트를 생성하여 코드가 약간 수정되었더라도 퍼지 매칭이 가능합니다.

기본 사용법

codeknit fingerprint ./src

이 명령어는:

• ./src 내의 모든 소스 파일을 파싱합니다.
• 구조적 핑거프린트를 계산합니다.
• 결과를 ./skeleton/fingerprints.skt에 출력합니다.
• 65%에서 95% 사이의 유사도를 가진 일치 항목을 보고합니다(기본 범위).

플래그

플래그	기본값	설명
-o, --output	./skeleton/fingerprints.skt	출력 .skt 파일 경로
--min-similarity	65	보고할 최소 유사도 비율(0–100)
--max-similarity	95	보고할 최대 유사도 비율(0–100)
--show-all	false	원시 토큰 데이터를 포함하는 [fingerprints] 섹션 포함
--rerank	false	의미론적 이웃을 찾고 Ollama 임베딩을 사용하여 후보를 재순위화합니다(필요: ollama serve 및 ollama pull qwen3-embedding:0.6b)
--model	qwen3-embedding:0.6b	--rerank와 함께 사용할 Ollama 임베딩 모델
--collect-test	false	분석에 테스트 파일 포함
--workers	NumCPU	최대 동시 파싱 고루틴 수(0 = 모든 CPU 코어 사용)
--verbose	false	처리 중 진행 정보 출력

출력 형식

출력은 다음 섹션을 포함하는 .skt 파일입니다:

[duplicates] (항상 존재)

임계값 이상의 유사도를 가진 심볼 쌍을 나열합니다:

[duplicates]
similarity:96%  pkg/user.go::GetUser <-> pkg/admin.go::GetAdmin
similarity:88%  utils/str.go::TrimSpaces <-> lib/text.go::CleanString

각 줄은 다음을 보여줍니다:

• 유사도 비율
• 왼쪽 심볼(파일 경로, 범위, 이름)
• 오른쪽 심볼(파일 경로, 범위, 이름)

[fingerprints] ( --show-all 사용 시에만 포함)

각 심볼에 대한 원시 핑거프린트 데이터를 포함합니다:

[fingerprints]
validateToken  FP:3:a1b2c3...:d4e5f6...  tokens:8e0f1a2b...

필드:

• 심볼 이름
• FP:<버전>:<해시1>:<해시2> — CTPH 핑거프린트
• tokens:<16진수> — 정규화된 본문 토큰 스트림

이 섹션은 디버깅이나 다운스트림 도구 구축에 유용합니다.

일반적인 패턴

# 기본 스캔
codeknit fingerprint ./src

# 정확한 중복만 찾기
codeknit fingerprint ./src --min-similarity 100

# 중간 정도의 유사한 코드 찾기(예: 같은 알고리즘, 다른 이름)
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

# 의미론적 매칭을 사용하여 추가 후보 찾기 및 거짓 양성 줄이기
# 필요: ollama serve && ollama pull qwen3-embedding:0.6b
codeknit fingerprint ./src --rerank

# 의미론적 매칭을 위한 다른 임베딩 모델 사용
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

# 전체 핑거프린트 목록 출력(분석 도구용)
codeknit fingerprint ./src --show-all

# 사용자 정의 출력 파일
codeknit fingerprint ./src -o duplicates.skt

유사도 범위 선택

범위	가이드라인
96–100%	정확하거나 거의 정확한 구조적 중복. 거의 확실한 복사-붙여넣기.
85–95%	근사 중복. 보통 복사-붙여넣기 후 사소한 편집(예: 변수 이름 변경, 로깅 추가).
65–84%	기본 범위. 강한 구조적 유사성. 리팩터링의 좋은 후보.
50–64%	중간 정도의 유사성. 같은 알고리즘 형태지만 세부 사항이 다름. 수동 검토 필요.
< 50%	보통 노이즈. 의미 있는 중복이 아님.

팁

• 핑거프린트는 구조를 측정하며 의미를 측정하지 않습니다: 높은 유사도 점수는 코드가 _비슷해 보임_을 의미하며, _같은 일을 함_을 의미하지는 않습니다. 항상 두 심볼을 검토하세요.
• --rerank를 사용하여 의미론적 매칭 활용: 임베딩은 구조적 검색에서 놓칠 수 있는 의미론적 이웃을 추가하고 의미론적으로 일치하지 않는 후보를 필터링합니다.
• 짧은 본문은 건너뜁니다: 정규화된 토큰이 4개 미만인 심볼(예: 단순한 getter)은 노이즈를 피하기 위해 무시됩니다.
• 언어 간 매칭이 작동합니다: 동등한 구성 요소(예: 같은 논리를 가진 Python 함수와 Go 함수)는 일치할 수 있지만, 언어별 패턴은 거짓된 낮은 유사도 일치를 생성할 수 있습니다.
• 일치는 신호이지 판결이 아닙니다: 각 일치를 조사할 프롬프트로 취급하세요 — 자동 중복 증명이 아닙니다.