docs: add coverage reference files and flag architectural drift

These files catalog test coverage for Rust modules across architecture, implementation, and theory sections. They track recent structural changes, flag areas prone to documentation drift, and mandate verification of key parameters and routing logic to maintain alignment with the active codebase.
2026-05-23 13:19:31 +02:00
parent b2a52bfb37
commit b7db3a33ed
22 changed files with 335 additions and 0 deletions
@@ -0,0 +1,12 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/chunkreader.md
+
+## Code couvert
+
+- `obiread/src/chunk.rs` — SeqChunkIter, détection de frontières FASTA/FASTQ, state machines
+- `obikrope/src/lib.rs` — type Rope (Vec<Bytes>), opérations zero-copy
+
+## Notes
+
+Document stable (la stratégie de chunking rope ne devrait pas avoir changé).
+Vérifier que le split FASTA/FASTQ reste correct si de nouveaux formats ont été ajoutés.
@@ -0,0 +1,22 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/evidence_elimination.md
+
+## Code couvert
+
+- `obilayeredmap/src/fingerprint.rs` — FingerprintVec, FingerprintVecWriter, stockage b bits/slot, matches()
+- `obilayeredmap/src/mphf_layer.rs` — build_approx_evidence(dir, b, z), find_approx()
+- `obilayeredmap/src/meta.rs` — EvidenceKind::Approx { b, z }, LayerMeta
+- `obikindex/src/reindex.rs` — KmerIndex::reindex(), conversion exact↔approx en place
+- `obikmer/src/cmd/reindex.rs` — CLI reindex, options --approx, -z, --evidence-bits, --fp, --block-size
+- `obikmer/src/cmd/index.rs` — resolve_approx_params(), options --approx, -z, --evidence-bits, --fp
+- `obikmer/src/cmd/estimate.rs` — commande estimate (dry-run des paramètres)
+
+## Notes
+
+Ce document était à l'origine une discussion de design (4 approches). L'implémentation
+a maintenant convergé vers l'approche fingerprint (Findere-style).
+FORT RISQUE DE DÉRIVE — le contenu est probablement un mélange de design et d'implémentation :
+- Le modèle FP = 1/2^(b·z) et les règles de résolution (2-of-3 parmi b, z, fp) sont implémentés
+- La commande `reindex` permet la conversion a posteriori exact↔approx
+- La commande `estimate` fait le dry-run des paramètres
+Cette page doit être réécrite pour documenter l'implémentation Findere réelle plutôt que les alternatives abandonnées.
@@ -0,0 +1,13 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/kmer.md
+
+## Code couvert
+
+- `obikseq/src/kmer.rs` — layout mémoire (repr(transparent) u64), encodage/décodage, revcomp, forme canonique
+- `obikseq/src/params.rs` — k global (set_k / k())
+
+## Notes
+
+Document d'implémentation stable. L'algorithme de revcomp bit-à-bit est décrit —
+vérifier qu'il correspond à `revcomp_raw` dans `obiskio/src/unitig_index.rs` (copie locale)
+et à l'implémentation dans `obikseq/src/kmer.rs`.
@@ -0,0 +1,19 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/merge.md
+
+## Code couvert
+
+- `obikindex/src/merge.rs` — `KmerIndex::merge()`, validation de compatibilité d'évidence, `validate_evidence_compat()`
+- `obikpartitionner/src/merge_layer.rs` — `merge_partition()`, construction de la nouvelle layer, paramètre `block_bits`
+- `obikpartitionner/src/rebuild_layer.rs` — `rebuild_partition()`, paramètre `block_bits`
+- `obilayeredmap/src/layer.rs` — `Layer::append_genome_column()` (PersistentCompactIntMatrix et PersistentBitMatrix)
+- `obicompactvec/src/intmatrix.rs` — `append_column` pour PersistentCompactIntMatrix
+- `obicompactvec/src/bitmatrix.rs` — `append_column` pour PersistentBitMatrix
+
+## Notes
+
+FORT RISQUE DE DÉRIVE. Changements récents :
+- Ajout de la validation de compatibilité d'évidence : merge exact+approx → erreur (OKIError::IncompatibleEvidence)
+- `merge_partition` reçoit maintenant `block_bits: u8`
+- La commande `reindex` a été ajoutée comme outil de conversion exact↔approx avant merge
+Vérifier que la doc décrit la politique de merge mixed-evidence et le recours à `reindex`.
@@ -0,0 +1,16 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/mphf.md
+
+## Code couvert
+
+- `obilayeredmap/src/mphf_layer.rs` — type Mphf (PtrHash + CubicEps + CachelineEfVec + Xx64), construction en 2 passes, `build()`, `build_exact_evidence()`, `build_approx_evidence()`, `build_evidence()`
+- `obikpartitionner/src/index_layer.rs` — `build_index_layer()` avec passage de `block_bits`
+
+## Notes
+
+FORT RISQUE DE DÉRIVE. Changements récents :
+- `build_exact_evidence(dir, block_bits)` — `block_bits` maintenant paramétrisé (défaut 0)
+- `build_approx_evidence(dir, b, z)` — nouvelle fonction pour l'évidence fingerprint
+- `build_evidence(dir, kind, block_bits)` — dispatch selon EvidenceKind
+- Construction en 2 phases : pass 1 (Rayon parallèle) + pass 2 (callback `fill_slot`)
+Vérifier que la doc décrit correctement les deux nouvelles routes d'évidence et le paramètre `block_bits`.
@@ -0,0 +1,22 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/obilayeredmap.md
+
+## Code couvert
+
+- `obilayeredmap/src/mphf_layer.rs` — MphfLayer, LayerEvidence enum (Exact/Approx), find(), find_exact(), find_approx()
+- `obilayeredmap/src/layer.rs` — Layer<D>, trait LayerData, modes () / PersistentCompactIntMatrix / PersistentBitMatrix, build(), build_evidence(), append_genome_column()
+- `obilayeredmap/src/map.rs` — LayeredMap<D>, push_layer(), query()
+- `obilayeredmap/src/evidence.rs` — Evidence, EvidenceWriter, encodage chunk_id:rank
+- `obilayeredmap/src/fingerprint.rs` — FingerprintVec, FingerprintVecWriter, matches()
+- `obilayeredmap/src/meta.rs` — LayerMeta, EvidenceKind (Exact / Approx { b, z })
+
+## Notes
+
+FORT RISQUE DE DÉRIVE. C'est le fichier le plus affecté par les changements récents :
+- EvidenceKind (Exact / Approx) est désormais un concept de premier plan — toute la sémantique de query en dépend
+- `LayerEvidence` enum interne à `MphfLayer` : dispatch transparent find() → find_exact() ou find_approx()
+- `fingerprint.rs` : module entièrement nouveau (FingerprintVec + FingerprintVecWriter)
+- `build_evidence()` / `build_exact_evidence()` / `build_approx_evidence()` sont nouveaux
+- `block_bits` dans les fonctions build : O(1) garanti avec le chemin chaud explicit pour block_bits=0
+- Séparation open() (accès aléatoire, requiert .idx) vs open_sequential() (itération seule)
+Pratiquement toute cette page est à réécrire.
@@ -0,0 +1,13 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/obipipeline.md
+
+## Code couvert
+
+- `obipipeline/src/lib.rs` — WorkerPool, Pipeline, macro make_pipeline!
+- `obipipeline/src/scheduler.rs` — Scheduler avec Select biaisé sur les entrées de canaux
+
+## Notes
+
+Document stable (librairie générique, peu de risque de dérive).
+Vérifier si `obipipeline` est toujours utilisé dans la phase scatter de `obikpartitionner`
+ou s'il a été remplacé par Rayon dans certains chemins.
@@ -0,0 +1,13 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/persistent_bit_vec.md
+
+## Code couvert
+
+- `obicompactvec/src/bitvec.rs` — PersistentBitVec, opérations mot u64, invariant de padding
+- `obicompactvec/src/bitmatrix.rs` — PersistentBitMatrix, wrapper colonne-major, append_column
+- `obicompactvec/src/bitmatrix.rs` — PersistentBitMatrixBuilder
+
+## Notes
+
+Document d'implémentation stable. Vérifier que `PersistentBitMatrixBuilder` et `append_column`
+sont couverts (utilisés dans `Layer::<PersistentBitMatrix>::build_presence` et `append_genome_column`).
@@ -0,0 +1,14 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/persistent_compact_int_vec.md
+
+## Code couvert
+
+- `obicompactvec/src/builder.rs` — PersistentCompactIntVecBuilder, cycle de vie
+- `obicompactvec/src/reader.rs` — PersistentCompactIntVec, accès aléatoire et séquentiel
+- `obicompactvec/src/intmatrix.rs` — PersistentCompactIntMatrix, wrapper colonne-major, append_column
+- `obicompactvec/src/format.rs` — format de fichier (magic PCIV, header, primary u8, overflow, index)
+
+## Notes
+
+Document d'implémentation stable. Vérifier que `append_column` (utilisé dans merge et reindex)
+est décrit. Vérifier que `PersistentCompactIntMatrixBuilder` est couvert (utilisé dans `layer.rs`).
@@ -0,0 +1,19 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/pipeline.md
+
+## Code couvert
+
+- `obikpartitionner/src/partition.rs` — estimation des paramètres (phase 0)
+- `obiskbuilder/src/iter.rs` — scatter : filtre entropie, extraction superkmers, routage partition (phase 1)
+- `obikpartitionner/src/filter.rs` — déduplication bucket-sort (phase 2)
+- `obikpartitionner/src/kmer_sort.rs` — tri externe + agrégation de comptages (phase 3)
+- `obidebruinj/src/debruijn.rs` — graphe De Bruijn, extraction des unitigs (phase 5)
+- `obikpartitionner/src/index_layer.rs` — construction MPHF + évidence (phase 6), paramètre `block_bits`
+- `obikindex/src/index.rs` — `build_layers()`, `dereplicate_and_count()`
+
+## Notes
+
+RISQUE DE DÉRIVE modéré. Vérifier :
+- Phase 6 : la doc mentionne-t-elle le filtre d'abondance (`min_ab`, `max_ab`) ?
+- Phase 6 : `block_bits` passé à `build_index_layer` depuis `IndexConfig`
+- Phase 6 : dispatch exact/approx selon `EvidenceKind` dans `build_index_layer`
@@ -0,0 +1,18 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/storage.md
+
+## Code couvert
+
+- `obikindex/src/meta.rs` — IndexMeta, IndexConfig (version, config, genomes)
+- `obikindex/src/index.rs` — layout sur disque : partitions/, index.meta
+- `obilayeredmap/src/meta.rs` — LayerMeta (evidence kind), PartitionMeta (n_layers)
+- `obiskio/src/unitig_index.rs` — fichiers unitigs.bin + unitigs.bin.idx
+
+## Notes
+
+FORT RISQUE DE DÉRIVE. Nombreux champs ajoutés :
+- `IndexConfig` : champs `evidence` (EvidenceKind) et `block_bits` ajoutés
+- Nouveau fichier `fingerprint.bin` pour l'évidence approximative
+- `LayerMeta` / `layer_meta.json` introduit pour stocker EvidenceKind par layer
+- Structure du répertoire layer : `evidence.bin` vs `fingerprint.bin` selon le mode
+Mettre à jour le schéma de layout sur disque en conséquence.
@@ -0,0 +1,13 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/superkmer.md
+
+## Code couvert
+
+- `obikseq/src/superkmer.rs` — layout mémoire SuperKmer (header 32 bits + séquence byte-alignée), encodage ASCII, revcomp, deque minimiseur
+- `obiskbuilder/src/lib.rs` — fenêtre glissante monotone pour le maintien du minimiseur
+
+## Notes
+
+Document d'implémentation détaillé. Vérifier que le layout header (longueur, orientation,
+position minimiseur) n'a pas changé. La doc mentionne un revcomp SIMD — vérifier si c'est
+toujours le cas ou si l'implémentation est scalaire.
@@ -0,0 +1,18 @@
+<!-- coverage sidecar — ne pas ajouter au nav mkdocs -->
+# Coverage: implementation/unitig_evidence.md
+
+## Code couvert
+
+- `obiskio/src/unitig_index.rs` — format unitigs.bin + unitigs.bin.idx, UnitigFileWriter, UnitigFileReader, build_unitig_idx(), DEFAULT_BLOCK_BITS=0, chemin chaud block_bits=0 dans chunk_start()
+- `obilayeredmap/src/evidence.rs` — encodage Evidence (chunk_id 25 bits | rank 7 bits), EvidenceWriter
+- `obidebruinj/src/debruijn.rs` — extraction unitigs, chunking à MAX_KMERS_PER_CHUNK
+
+## Notes
+
+FORT RISQUE DE DÉRIVE. Changements récents :
+- `DEFAULT_BLOCK_BITS` est passé de 6 à 0 (accès O(1) par défaut)
+- `block_bits` est maintenant un paramètre runtime de `build_unitig_idx()` et `UnitigFileWriter`
+- `chunk_start()` a un chemin chaud explicite pour block_bits=0 (accès tableau direct, 0 scan)
+- `open()` vs `open_sequential()` : distinction nouvelle, importante pour la compréhension du coût
+- `iter_unitigs()` ajouté comme alias public de `iter_chunks_sequential()`
+Mettre à jour la description du format .idx et le modèle de coût d'accès aléatoire.