คำสั่ง Fingerprint

คำสั่ง codeknit fingerprint จะตรวจจับโค้ดที่ซ้ำและรายการที่เกือบซ้ำข้ามโค้ดเบสของคุณโดยใช้ Context-Triggered Piecewise Hashing (CTPH) ทำงานข้ามไฟล์และแม้กระทั่งข้ามภาษาโปรแกรมโดยการทำให้ชื่อตัวแปร สตริง literal และการประกาศชนิดข้อมูลเป็นมาตรฐานก่อนที่จะคำนวณ fingerprint โครงสร้าง

สิ่งที่ทำได้

codeknit fingerprint วิเคราะห์ฟังก์ชัน เมธอด ตัวแปร และชนิดข้อมูลทุกอย่างในโค้ดเบสของคุณและคำนวณ fingerprint โครงสร้างที่ถูกทำให้เป็นมาตรฐาน โดยอิงจาก:

• การควบคุมการไหล (if, for, while, switch)
• การดำเนินการ (=, +, ==, &&, ||)
• การเรียกใช้งาน การส่งคืน การกำหนดค่า และการสร้างอ็อบเจกต์
• โครงสร้างภาษา เช่น try/catch, yield, await, defer

การทำให้เป็นมาตรฐานนี้หมายความว่า การคัดลอกและเปลี่ยนชื่อ, การรีแฟคเตอร์เล็กน้อย, และ ตรรกะที่เทียบเท่าในภาษาต่างๆ ยังสามารถถูกตรวจจับเป็นรายการซ้ำได้

อัลกอริทึมใช้ CTPH (ตัวแปรของ rolling hash) เพื่อค้นหารายการที่เกือบซ้ำได้อย่างมีประสิทธิภาพ โค้ดที่คล้ายกันจะสร้าง fingerprint ที่คล้ายกัน ทำให้สามารถจับคู่แบบ fuzzy ได้แม้ว่าโค้ดจะถูกแก้ไขเล็กน้อย

การใช้งานพื้นฐาน

codeknit fingerprint ./src

คำสั่งนี้:

• แยกวิเคราะห์ไฟล์ต้นฉบับทั้งหมดใน ./src
• คำนวณ fingerprint โครงสร้าง
• ส่งออกผลลัพธ์ไปยัง ./skeleton/fingerprints.skt
• รายงานการจับคู่ที่มีความคล้ายคลึงระหว่าง 65% ถึง 95% (ช่วงเริ่มต้น)

Flags

Flag	ค่าเริ่มต้น	คำอธิบาย
-o, --output	./skeleton/fingerprints.skt	เส้นทางไฟล์ .skt สำหรับเอาต์พุต
--min-similarity	65	เปอร์เซ็นต์ความคล้ายคลึงขั้นต่ำที่จะรายงาน (0–100)
--max-similarity	95	เปอร์เซ็นต์ความคล้ายคลึงสูงสุดที่จะรายงาน (0–100)
--show-all	false	รวมส่วน [fingerprints] พร้อมข้อมูลโทเค็นดิบ
--rerank	false	ค้นหาเพื่อนบ้านเชิงความหมายและจัดอันดับผู้สมัครใหม่โดยใช้ Ollama embeddings (ต้องการ: ollama serve และ ollama pull qwen3-embedding:0.6b)
--model	qwen3-embedding:0.6b	โมเดล Ollama embedding ที่จะใช้กับ --rerank
--collect-test	false	รวมไฟล์ทดสอบในการวิเคราะห์
--workers	NumCPU	จำนวน goroutines การแยกวิเคราะห์พร้อมกันสูงสุด (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)

ประกอบด้วยข้อมูล fingerprint ดิบสำหรับแต่ละสัญลักษณ์:

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

ฟิลด์:

• ชื่อสัญลักษณ์
• FP:<version>:<hash1>:<hash2> — fingerprint CTPH
• tokens:<hex> — สตรีมโทเค็นของเนื้อหาที่ถูกทำให้เป็นมาตรฐาน

ส่วนนี้มีประโยชน์สำหรับการดีบักหรือสร้างเครื่องมือปลายน้ำ

รูปแบบการใช้งานทั่วไป

# Default scan
codeknit fingerprint ./src

# Find only exact duplicates
codeknit fingerprint ./src --min-similarity 100

# Find moderately similar code (e.g. same algorithm, different names)
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

# Use semantic matching to find additional candidates and reduce false positives
# Requires: ollama serve && ollama pull qwen3-embedding:0.6b
codeknit fingerprint ./src --rerank

# Use a different embedding model for semantic matching
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

# Output full fingerprint listing (for analysis tools)
codeknit fingerprint ./src --show-all

# Custom output file
codeknit fingerprint ./src -o duplicates.skt

การเลือกช่วงความคล้ายคลึง

ช่วง	คำแนะนำ
96–100%	รายการซ้ำที่ตรงกันหรือเกือบตรงกันทางโครงสร้าง แน่นอนว่าเป็นการคัดลอกและวาง
85–95%	รายการที่เกือบซ้ำ โดยทั่วไปเป็นการคัดลอกและวางที่มีการแก้ไขเล็กน้อย (เช่น เปลี่ยนชื่อตัวแปร เพิ่มการบันทึก)
65–84%	ช่วงเริ่มต้น ความคล้ายคลึงทางโครงสร้างสูง ผู้สมัครที่ดีสำหรับการรีแฟคเตอร์
50–64%	ความคล้ายคลึงปานกลาง รูปแบบอัลกอริทึมเดียวกันแต่รายละเอียดต่างกัน ตรวจสอบด้วยตนเอง
< 50%	โดยทั่วไปเป็นสัญญาณรบกวน ไม่ใช่การซ้ำที่มีความหมาย

เคล็ดลับ

• Fingerprint วัดโครงสร้าง ไม่ใช่ความหมาย: คะแนนความคล้ายคลึงสูงหมายถึงโค้ด ดู คล้ายกัน ไม่ใช่ว่า ทำ สิ่งเดียวกัน อย่าลืมตรวจสอบสัญลักษณ์ทั้งสอง
• ใช้ --rerank สำหรับการจับคู่เชิงความหมาย: Embeddings เพิ่มเพื่อนบ้านเชิงความหมายที่การดึงข้อมูลเชิงโครงสร้างอาจพลาด และกรองผู้สมัครที่ไม่เห็นด้วยเชิงความหมาย
• ข้ามเนื้อหาสั้นๆ: สัญลักษณ์ที่มีโทเค็นที่ถูกทำให้เป็นมาตรฐานน้อยกว่า 4 โทเค็น (เช่น getter ง่ายๆ) จะถูกละเว้นเพื่อหลีกเลี่ยงสัญญาณรบกวน
• การจับคู่ข้ามภาษาทำงานได้: โครงสร้างที่เทียบเท่า (เช่น ฟังก์ชัน Python และฟังก์ชัน Go ที่มีตรรกะเดียวกัน) สามารถจับคู่ได้ แต่รูปแบบเฉพาะภาษาอาจสร้างการจับคู่ที่มีความคล้ายคลึงต่ำที่ไม่มีความหมาย
• การจับคู่เป็นสัญญาณ ไม่ใช่คำตัดสิน: ถือว่าการจับคู่แต่ละครั้งเป็นการกระตุ้นให้ตรวจสอบ — ไม่ใช่หลักฐานอัตโนมัติของการซ้ำ