Pier-Jean Malandrino efc27932dd refactor(audit): remediate 0.5.0 audit findings — clean architecture, security, DRY, SOLID, perf

Closes the 12 MAJ raised by the release/0.5.0 audit pipeline (cf.
docs/audit/reports/release-0.5.0/summary.md → summary-reaudit.md).

Volet 1 — Reasoning architecture (audits 01/02/06/07 strengthening)
  * Domain ports: LLMProvider, ReasoningRunner, ReasoningParseError
  * Domain DTOs: LLMProviderType, ReasoningResult, ReasoningIteration
  * infra/llm/ollama_provider.py — OllamaProvider with health_check
  * infra/docling_agent_reasoning.py — runner adapter, encapsulates the
    private _rag_loop call (tracked at docling-project/docling-agent#26),
    commits OLLAMA_HOST once at boot (eliminates the per-request env race),
    translates upstream IndexError into ReasoningParseError
  * api/reasoning.py — zero coupling to docling-agent / mellea / docling-core,
    consumes app.state.reasoning_runner via the port
  * main.py — DI wires OllamaProvider + DoclingAgentReasoningRunner at boot
    when REASONING_ENABLED=true and deps are importable
  * Rename RAG_* env vars → REASONING_*, endpoint /rag → /reasoning,
    type RAGResult → ReasoningResult, frontend feature flag wiring,
    i18n strings, tests, docs (BREAKING — pre-1.0 surface, no external
    consumers in production)
  * 17 new tests: adapter unit tests with sys.modules stubs, OllamaProvider
    httpx tests, R3 concurrent-host isolation, R6 multi-iteration trace
    serialization, R13 Protocol conformance via isinstance
  * E2E Karate scenario: nav-reasoning hidden when REASONING_ENABLED=false
  * README — Live Reasoning section (env vars, archi, link to issue #26)

Bloc B — Security (audit 08, dev-only context)
  * docker-compose.yml — DEV DEFAULTS header, OpenSearch DISABLE_SECURITY_PLUGIN
    flagged as dev-only with link to OpenSearch security docs
  * main.py — boot warning if NEO4J_URI is set with the default 'changeme'
    password, so prod operators can't silently inherit it

Bloc C — DRY frontend (audit 05)
  * shared/storage/keys.ts — STORAGE_KEYS centralised (theme, locale)
  * features/settings/store.ts — dead apiUrl ref + orphan i18n keys removed
  * api/schemas.py — DOCUMENT_STATUS_UPLOADED constant

Bloc D — Quality (audits 02/06/07/09/10/12)
  * domain/ports.py — DocumentConverter.supports_page_batching property
    (LSP fix, replaces isinstance(ServeConverter) check)
  * domain/ports.py — VectorStore.ping() (encapsulation, replaces
    _vector_store._client.info() reach-around)
  * api/analyses.py + api/ingestion.py — path params {job_id} → {analysis_id}
    aligned with the user-facing terminology (URLs unchanged)
  * api/documents.py — Path.read_bytes() + generate_preview() wrapped in
    asyncio.to_thread, unblocks the FastAPI event loop on /preview
  * infra/docling_tree.py — PEP 604 union for isinstance (Ruff UP038)
  * src/__tests__/integration/ — cross-feature integration test relocated
    out of features/history/ so feature folders stay self-contained
  * Tightened terminal `assert X is not None` checks (isinstance(.., datetime),
    exact value comparisons)

Validation
  * 446 backend pytest, 202 frontend vitest — all green
  * ruff + ruff format + ESLint + Prettier + vue-tsc clean
  * Re-audit verdict: 0 CRIT / 0 MAJ, score ~94/100, GO

Closes #200

2026-04-29 14:00:00 +02:00

4.8 KiB

Raw Blame History

Rapport d'audit : Tests

Release : 0.5.0
Date : 2026-04-28
Auditeur : claude-code

Score de compliance

Metrique	Valeur
Items conformes	17 / 18
Score	94 / 100
Ecarts CRITICAL	0
Ecarts MAJOR	1
Ecarts MINOR	0
Ecarts INFO	0

Ecarts constates

[MAJ] 18 assertions vagues "assert X is not None"

Localisation : document-parser/tests/test_local_converter.py:70, test_repos.py:42,95,124,190,192, test_ingestion_service.py:119, test_analysis_service.py:354, test_models.py:61,77,87, test_chunking.py:276, test_api_endpoints.py:199, test_vector_store_port.py:47, test_pipeline_options.py:56, neo4j/test_document_roundtrip.py:24, neo4j/test_tree_writer.py:204, neo4j/test_chunk_writer.py:97, test_opensearch_store.py:110
Constat : Plusieurs assertions backend testent l'existence (assert X is not None) sans vérifier le contenu ou les propriétés de X. Ces assertions ne capturent que la présence, pas la correction.
Regle violee : 9.3.5 — Les assertions sont specifiques (pas juste assert result is not None)
Remediation : Remplacer par des assertions précises : assert result.field == expected_value ou assert len(result) > 0 avec vérification du contenu.
Poids : 2 (MAJOR) — Impact modéré sur la qualité des tests d'intégration

Points positifs

Couverture d'endpoints robuste (9.2.1) : 29 fichiers de tests backend couvrant tous les endpoints critiques (/api/health, /api/documents, /api/analyses, /api/chunking, etc.). Chaque endpoint a au moins un happy path avec TestClient.
Test d'erreurs complets (9.2.2) : Les tests couvrent 400, 404, et gestion d'erreurs métier. Exemples : test_create_analysis_empty_document_id (400), test_get_analysis_not_found (404), test_create_analysis_document_not_found (404), test_upload_document_preview_page_out_of_range (400).
Services bien testés (9.2.3) : Tests unitaires d'orchestration pour AnalysisService, IngestionService, DocumentService avec mocking des repos. Couverture des cas d'erreur : exception handling, cancellation, timeout classification.
Domain value objects testes (9.2.4) : test_bbox.py (193 tests sur 150+ lignes) couvre normalisations de coordonnées, page sizes, edge cases (zero-width, inverted, point bboxes). test_chunking.py teste ChunkingOptions avec defaults et custom values. test_models.py teste les state transitions.
Composants Vue et stores critiques testes (9.2.5) : 23 tests frontend colocalises (*.test.ts) couvrant stores Pinia (ingestion/store.test.ts, analysis/store.test.ts, document/store.test.ts, feature-flags/store.test.ts), composables (useFeatureFlag.test.ts), et API layers (ingestion/api.test.ts, analysis/api.test.ts).
Pas d'anti-patterns de test (9.3.1, 9.3.2) : Aucun .only, fdescribe, fit, ou .skip() sans justification trouvé. Tous les tests actifs et exécutés.
Determinisme garanti (9.3.3) :
- Backend : pytest avec asyncio_mode = auto. Pas de sleep() ou dépendances réseau brutes trouvées.
- Frontend : Vitest avec vi.useFakeTimers() / vi.useRealTimers() dans tests d'orchestration (polling, intervals). Mocks d'API systématiques (vi.mock('./api')).
Mocking vs integration equilibre (9.3.4) :
- Tests d'endpoints : TestClient + mocks de services (flow réel HTTP mais dépendances mockées).
- Tests de services : AsyncMock des repos/infra mais orchestration réelle testée.
- E2E Karate UI : vrais workflows UI ; Karate API tests : vrais appels HTTP.
Nommage explicite (9.3.6) : Tous les tests ont des noms clairs décrivant le comportement. Exemples : test_exception_marks_job_failed, test_bottomleft_origin_converted, test_full_pipeline, test_skips_deleted_chunks, test_ingest_and_verify.
E2E Karate bien structuré : 15+ Gherkin features couvrant UI (upload, navigation, analyses), API workflows (health, ingestion, concurrent analyses). Conventions respectées (Background, waitFor, cleanup). UIRunner et E2ERunner organisent tests par tags (@critical, @ui, @smoke).

Verdict partiel : GO

Justification :

Score 94/100 dépasse le seuil GO (>= 80).
Zero écarts CRITICAL — aucune violation bloquante.
Un écart MAJOR (assertions vagues) est non-bloquant selon master.md §3 ("GO CONDITIONNEL si <= 3 MAJOR et 0 CRITICAL"). Cet écart est facilement corrigible en post-release.
Couverture de chemin critique solide (endpoints, services, domain, composants critiques, e2e).
Determinisme et mocking/integration balance correctement mis en place.

Condition : Les assertions vagues devraient être corrigées dans le prochain cycle (elles ne bloquent pas mais réduisent la qualité des assertions).

4.8 KiB Raw Blame History