Comando Fingerprint

El comando codeknit fingerprint detecta código duplicado y casi duplicado en tu base de código utilizando Context-Triggered Piecewise Hashing (CTPH). Funciona entre archivos e incluso entre lenguajes de programación al normalizar nombres de variables, literales de cadena y anotaciones de tipos antes de calcular las huellas estructurales normalizadas.

Qué hace

codeknit fingerprint analiza cada función, método, variable y tipo en tu base de código y calcula una huella estructural normalizada basada en:

• Flujo de control (if, for, while, switch)
• Operaciones (=, +, ==, &&, ||)
• Llamadas, retornos, asignaciones y creación de objetos
• Constructores del lenguaje como try/catch, yield, await, defer

Esta normalización significa que copiar y pegar con cambios de nombre, refactorizaciones triviales y lógica equivalente en diferentes lenguajes aún pueden ser detectados como duplicados.

El algoritmo utiliza CTPH (una variante de hash rodante) para encontrar casi duplicados de manera eficiente. Código similar produce huellas similares, permitiendo la coincidencia difusa incluso cuando el código ha sido ligeramente modificado.

Uso básico

codeknit fingerprint ./src

Este comando:

• Analiza todos los archivos fuente en ./src
• Calcula huellas estructurales
• Genera resultados en ./skeleton/fingerprints.skt
• Reporta coincidencias con similitud entre 65% y 95% (rango predeterminado)

Flags

Flag	Valor predeterminado	Descripción
-o, --output	./skeleton/fingerprints.skt	Ruta del archivo .skt de salida
--min-similarity	65	Porcentaje mínimo de similitud para reportar (0–100)
--max-similarity	95	Porcentaje máximo de similitud para reportar (0–100)
--show-all	false	Incluir la sección [fingerprints] con datos de tokens sin procesar
--rerank	false	Encontrar vecinos semánticos y reordenar candidatos utilizando embeddings de Ollama (requiere: ollama serve y ollama pull qwen3-embedding:0.6b)
--model	qwen3-embedding:0.6b	Modelo de embedding de Ollama a utilizar con --rerank
--collect-test	false	Incluir archivos de prueba en el análisis
--workers	NumCPU	Máximo de goroutines de análisis concurrentes (0 = usar todos los núcleos de CPU)
--verbose	false	Mostrar información de progreso durante el procesamiento

Formato de salida

La salida es un archivo .skt con las siguientes secciones:

[duplicates] (siempre presente)

Lista pares de símbolos con similitud por encima del umbral:

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

Cada línea muestra:

• Porcentaje de similitud
• Símbolo izquierdo (ruta del archivo, ámbito, nombre)
• Símbolo derecho (ruta del archivo, ámbito, nombre)

[fingerprints] (solo con --show-all)

Contiene datos sin procesar de huellas para cada símbolo:

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

Campos:

• Nombre del símbolo
• FP:<versión>:<hash1>:<hash2> — huella CTPH
• tokens:<hex> — flujo de tokens normalizado del cuerpo

Esta sección es útil para depuración o la creación de herramientas posteriores.

Patrones comunes

# Análisis predeterminado
codeknit fingerprint ./src

# Encontrar solo duplicados exactos
codeknit fingerprint ./src --min-similarity 100

# Encontrar código moderadamente similar (ej. mismo algoritmo, nombres diferentes)
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

# Usar coincidencia semántica para encontrar candidatos adicionales y reducir falsos positivos
# Requiere: ollama serve && ollama pull qwen3-embedding:0.6b
codeknit fingerprint ./src --rerank

# Usar un modelo de embedding diferente para la coincidencia semántica
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

# Generar listado completo de huellas (para herramientas de análisis)
codeknit fingerprint ./src --show-all

# Archivo de salida personalizado
codeknit fingerprint ./src -o duplicates.skt

Selección de rango de similitud

Rango	Guía
96–100%	Duplicados estructurales exactos o casi exactos. Casi con certeza copiar y pegar.
85–95%	Casi duplicados. Usualmente copiar y pegar con ediciones menores (ej. variables renombradas, logging añadido).
65–84%	Rango predeterminado. Fuerte similitud estructural. Buenos candidatos para refactorización.
50–64%	Similitud moderada. Misma forma algorítmica pero con detalles diferentes. Revisar manualmente.
< 50%	Usualmente ruido. No es un duplicado significativo.

Consejos

• Las huellas miden estructura, no significado: Una puntuación alta de similitud significa que el código se ve similar, no que hace lo mismo. Siempre revisa ambos símbolos.
• Usa --rerank para coincidencia semántica: Los embeddings añaden vecinos semánticos que la recuperación estructural puede pasar por alto y filtran candidatos que no coinciden semánticamente.
• Se omiten cuerpos cortos: Los símbolos con menos de 4 tokens normalizados (ej. getters simples) se ignoran para evitar ruido.
• Funciona la coincidencia entre lenguajes: Constructores equivalentes (ej. una función en Python y una función en Go con la misma lógica) pueden coincidir, pero patrones específicos del lenguaje pueden producir coincidencias espurias de baja similitud.
• Una coincidencia es una señal, no un veredicto: Trata cada coincidencia como un indicio para investigar — no como prueba automática de duplicado.