Commande Fingerprint
codeknit fingerprint calcule un hachage contextuel par morceaux déclenché (CTPH) sur les jetons normalisés du corps de chaque fonction, méthode, variable et type. Les noms de variables, les littéraux de chaîne et les annotations de type sont normalisés avant le hachage. Les copier-coller renommés et les ports vers d’autres langages peuvent donc toujours correspondre.
Ce guide montre comment trouver des doublons, ajuster la plage de similarité, réduire les faux positifs et décider des éléments à refactoriser.
Avant de commencer
Section intitulée « Avant de commencer »codeknitest installé. Voir Installation.- Vous disposez d’un répertoire source à analyser, tel que
./src.
Trouver des doublons dans un projet
Section intitulée « Trouver des doublons dans un projet »Exécutez la commande sur le répertoire que vous souhaitez vérifier :
codeknit fingerprint ./srcLa commande écrit ./skeleton/fingerprints.skt et signale les paires avec une similarité comprise entre 65 % et 95 %.
Ouvrez le fichier. La section [duplicates] est toujours présente, avec les correspondances les plus fortes en premier :
[duplicates]# similarity range: 65%-95%similarity:93% pkg/user.go::GetUser <-> pkg/admin.go::GetAdminsimilarity:88% src/auth.ts::validateToken <-> src/session.ts::validateSessionsimilarity:81% lib/math.py::compute_tax <-> lib/math.py::compute_vatChaque ligne a la forme similarity:<N>% <fichier>::<symbole> <-> <fichier>::<symbole>. Si rien ne correspond à la plage, la section contient uniquement # no duplicates found.
Pour la grammaire complète de la sortie, consultez la référence du format de sortie.
Trouver uniquement les doublons exacts
Section intitulée « Trouver uniquement les doublons exacts »La plage par défaut s’arrête à 95 %, donc les correspondances à 100 % sont exclues. Pour lister les correspondances exactes, définissez les deux bornes à 100 :
codeknit fingerprint ./src --min-similarity 100 --max-similarity 100“Exact” signifie que les flux de jetons normalisés complets sont identiques au sein de la même catégorie de symbole. Cela ne signifie pas que le texte source est identique, ni que les deux symboles sont prouvés équivalents.
Élargir la plage pour trouver des correspondances plus lâches
Section intitulée « Élargir la plage pour trouver des correspondances plus lâches »Réduisez le minimum pour inclure du code qui partage une forme algorithmique mais diffère dans les détails :
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80Les résultats inférieurs à 50 % sont généralement du bruit.
Réduire les faux positifs avec un réordonnancement sémantique
Section intitulée « Réduire les faux positifs avec un réordonnancement sémantique »Si les résultats structurels sont bruyants, réordonnez les candidats avec des embeddings provenant d’un serveur Ollama local.
-
Démarrez Ollama et téléchargez le modèle d’embedding par défaut :
Fenêtre de terminal ollama serveollama pull qwen3-embedding:0.6b -
Exécutez la commande avec
--rerank:Fenêtre de terminal codeknit fingerprint ./src --rerank
Pour utiliser un autre modèle d’embedding, passez --model :
codeknit fingerprint ./src --rerank --model qwen3-embedding:4bLe réordonnancement ajoute des candidats sémantiques et filtre sur un score combiné. Il réduit les faux positifs mais ne les élimine pas tous. Il peut également supprimer un candidat qui est structurellement exact, et la plage de similarité s’applique toujours. Les embeddings sont calculés à partir du même instantané de source analysé utilisé pour l’extraction.
Inspecter les empreintes brutes
Section intitulée « Inspecter les empreintes brutes »Pour voir l’empreinte de chaque symbole, ajoutez --show-all :
codeknit fingerprint ./src --show-allCela ajoute une section [fingerprints], regroupée par fichier source, une ligne par symbole :
[fingerprints]## src/auth.tsvalidateToken FP:3:a1b2c3...:d4e5f6... tokens:8e0f1a2b...Le format de la ligne est <nom-du-symbole> FP:<taille-bloc>:<hash1>:<hash2> tokens:<hex>. tokens est le flux de jetons normalisé encodé en hexadécimal.
Écrire le rapport ailleurs
Section intitulée « Écrire le rapport ailleurs »codeknit fingerprint ./src -o duplicates.sktContrôler les fichiers analysés
Section intitulée « Contrôler les fichiers analysés »Les fichiers de test sont ignorés par défaut. Incluez-les avec --collect-test :
codeknit fingerprint ./src --collect-testPour affiner l’analyse, utilisez les indicateurs de sélection de source. Placez les motifs entre guillemets pour que votre shell ne les développe pas :
codeknit fingerprint ./src --include '**/*.ts' --exclude '**/generated/'Autres contrôles de sélection :
--max-file-size BYTESignore les fichiers plus volumineux. La valeur par défaut est10485760(10 Mio).0désactive la limite.--strictéchoue avant d’écrire la sortie si l’analyse ou l’analyse syntaxique est incomplète.--header-language c|cppsélectionne l’analyseur pour les fichiers.hambigus. Voir Prise en charge des langages.
Les liens symboliques ignorés, les fichiers trop volumineux et les avertissements de syntaxe apparaissent sur stderr. Les inclusions ne remplacent pas .gitignore ou le filtrage des tests, et les exclusions ont priorité sur les inclusions. Consultez la référence de fiabilité de l’analyse pour les garanties exactes.
Choisir une plage de similarité
Section intitulée « Choisir une plage de similarité »| Plage | Ce qu’elle révèle généralement |
|---|---|
96-100% |
Doublons structurels exacts ou quasi-exacts ; copier-coller évident |
85-95% |
Quasi-doublons ; généralement copier-coller avec des modifications mineures |
65-84% |
Plage par défaut ; forte similarité structurelle, souvent candidats à la refactorisation |
50-64% |
Même forme algorithmique avec des détails différents |
| En dessous de 50% | Généralement du bruit |
Pour voir les deux premières lignes, augmentez --max-similarity à 100.
Décider quoi refactoriser
Section intitulée « Décider quoi refactoriser »- Commencez par la plage par défaut et lisez les paires les plus importantes.
- Ouvrez les deux symboles de chaque paire et comparez-les.
- Considérez une correspondance comme un signal, pas comme une preuve. Les empreintes mesurent la forme structurelle, pas les noms d’identificateurs ou l’intention. La même logique écrite de manière itérative et récursive obtient un score faible, et du code sans rapport avec la même forme peut obtenir un score élevé.
- Les paires dans la plage 85–95 % sont généralement les candidats les plus sûrs à consolider. Les paires dans la plage 65–84 % nécessitent souvent un examen plus approfondi.
- Si la liste est bruyante, réduisez la plage ou ajoutez
--rerank.
Les correspondances inter-langages fonctionnent pour les constructions équivalentes. Les fonctionnalités spécifiques à un langage peuvent produire des correspondances de faible similarité erronées.
Les pourcentages de similarité sont une heuristique de classement, pas une distance d’édition. Le projet de calibration étiqueté rapporte la précision et le rappel séparément des scores de similarité. Il s’agit d’un contrôle de régression, pas d’une estimation de la précision sur votre code.
Grands projets
Section intitulée « Grands projets »- En dessous de 500 symboles éligibles, codeknit évalue chaque paire de même catégorie.
- À partir de 500 symboles ou plus, les groupes complets de jetons normalisés exacts sont toujours conservés. Les autres paires utilisent environ 50 voisins les plus proches par symbole, donc les résultats de quasi-doublons peuvent être incomplets.
- Pour les doublons exacts, utilisez la commande 100/100 ci-dessus. Elle n’est pas affectée par l’approximation.
- L’ordre est déterministe pour des entrées et des scores stables.
Dépannage
Section intitulée « Dépannage »| Symptôme | Cause et solution |
|---|---|
# no duplicates found |
Aucune paire ne correspond à la plage. Réduisez --min-similarity ou augmentez --max-similarity. |
| Une fonction courte connue est manquante | Les symboles avec moins de 4 jetons normalisés sont ignorés. |
| Des copies exactes sont manquantes | Le maximum par défaut est 95 %. Utilisez --min-similarity 100 --max-similarity 100. Avec --rerank, le filtre sémantique peut également les supprimer. |
--rerank échoue |
Vérifiez que ollama serve est en cours d’exécution et que le modèle est téléchargé. |
| Résultats partiels avec des avertissements sur stderr | Corrigez les fichiers signalés, ou ajoutez --strict pour échouer au lieu de publier une sortie incomplète. |
Indicateurs utilisés dans ce guide
Section intitulée « Indicateurs utilisés dans ce guide »| Indicateur | Valeur par défaut | Description |
|---|---|---|
-o, --output |
./skeleton/fingerprints.skt |
Chemin du fichier .skt de sortie. |
--min-similarity |
65 |
Pourcentage de similarité minimum à signaler (0–100). |
--max-similarity |
95 |
Pourcentage de similarité maximum à signaler (0–100). |
--show-all |
false |
Émet également la section [fingerprints] avec les données de jetons brutes. |
--rerank |
false |
Réordonne les candidats avec des embeddings sémantiques via Ollama. Nécessite ollama serve et ollama pull qwen3-embedding:0.6b. |
--model |
qwen3-embedding:0.6b |
Modèle d’embedding Ollama à utiliser avec --rerank. |
--collect-test |
false |
Inclut les fichiers de test dans l’analyse. |
--workers |
NumCPU |
Nombre maximal de goroutines d’analyse concurrentes. |
--verbose |
false |
Affiche les informations de progression. |
Pour la liste complète, y compris --include, --exclude, --max-file-size, --strict et --header-language, consultez la référence des indicateurs CLI.