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를 통한 의미 임베딩을 사용하여 CTPH 후보를 재순위화하여 거짓 양성을 제거합니다(`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]` (항상 존재)

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

```skt
[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:<version>:<hash1>:<hash2> — CTPH 핑거프린트
tokens:<hex> — 정규화된 본문 토큰 스트림

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

일반적인 패턴

# 기본 스캔
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 함수)은 매칭될 수 있지만, 언어별 패턴은 거짓 양성 저유사도 매치를 생성할 수 있습니다.
매치는 신호일 뿐, 판결이 아닙니다: 각 매치를 조사할 프롬프트로 취급하세요 — 자동 중복 증거가 아닙니다.```

Fingerprint 명령어

기능

기본 사용법

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

일반적인 패턴

유사도 범위 선택

팁

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