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

3.5 KiB

Raw Blame History

Rapport d'audit : Documentation & Changelog

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

Score de compliance

Metrique	Valeur
Items conformes	5 / 9
Score	44 / 100
Ecarts CRITICAL	1
Ecarts MAJOR	2
Ecarts MINOR	0
Ecarts INFO	0

Detail

#	Item	Poids	Statut
11.1.1	`[Unreleased]` renommee en `[X.Y.Z] - YYYY-MM-DD`	3	KO
11.1.2	Modifications de la release listees	2	KO
11.1.3	Breaking changes identifies	3	OK
11.1.4	Format Keep a Changelog	1	OK
11.2.1	`package.json` a la bonne version	2	KO
11.2.2	Semantic Versioning	2	OK
11.3.1	Pas de TODO orphelin	1	OK
11.3.2	Pas de `console.log` de debug	2	OK
11.3.3	Pas de `print()` de debug	2	OK

Calcul : poids conformes 3+1+2+2 = 8 / poids total 18 = 44.4 → 44.

Ecarts constates

[CRIT] CHANGELOG.md sans section `[0.5.0]`

Localisation : CHANGELOG.md:7
Constat : la derniere section est ## [0.4.0] - 2026-04-13. Aucune section [Unreleased] ni [0.5.0] n'est presente. Pour une release nommee 0.5.0, la regle 11.1.1 (poids 3) exige une section [0.5.0] - YYYY-MM-DD.
Regle violee : 11.1.1.
Impact : aucune trace des nouveautes 0.5.0 (reasoning viewer, Neo4j integration, RAG endpoints). Un tag 0.5.0 cree depuis ce HEAD livrerait un changelog mensonger.
Remediation : ajouter section ## [0.5.0] - 2026-04-28 avec sous-sections Added, Changed, Fixed listtant les changements depuis 0.4.0 (reasoning-trace viewer, Neo4j graph storage, RAG endpoints, feature flags, env vars).

[MAJ] Modifications de la release 0.5.0 non documentees

Localisation : CHANGELOG.md
Constat : corollaire direct de l'ecart 11.1.1. Aucun bullet n'enumere les nouveautes de cette release (11.1.2, poids 2). Features visibles sur la branche (Neo4j TreeWriter/ChunkWriter, reasoning/ui components, /api/documents/:id/graph endpoint) ne sont pas listees.
Regle violee : 11.1.2.
Remediation : voir CRIT 11.1.1.

[MAJ] `frontend/package.json` toujours a `0.4.0`

Localisation : frontend/package.json:3
Constat : "version": "0.4.0". Pour une release 0.5.0, il faut bumper a "version": "0.5.0" (regle 11.2.1, poids 2).
Impact : la version du frontend reste 0.4.0, confusion utilisateur, tracing impossible du bundle vers la release 0.5.0.
Remediation : bumper a "version": "0.5.0" avant le tag final.

Points positifs

Zero console.log/console.debug dans le code frontend. Les 2 occurrences de console.warn (store.ts:85, ReasoningPanel.vue:150) respectent la convention permise.
Zero print() de debug dans le backend (hors tests).
Zero TODO/FIXME/HACK/XXX dans le code productif.
Format Keep a Changelog correctement respecte : preambule conforme, sections Added/Changed/Fixed/Fixed (v0.4.0), chronologie inverse.
Semantic Versioning suivi : sequence 0.1.0 → 0.2.0 → 0.3.0 → 0.3.1 → 0.4.0 → (0.5.0 en attente) coherente.

Verdict partiel : NO-GO

Score 44/100 < 60 (seuil minimum) et 1 ecart CRITICAL non resolu (regle absolue du master : tout [CRIT] non resolu = NO-GO).

Le release 0.5.0 ne peut pas partir (ne peut pas etre taguee) tant que :

CHANGELOG.md n'enumere pas les changements sous ## [0.5.0] - YYYY-MM-DD.
frontend/package.json n'est pas bumpe a 0.5.0.

Recommendation : apres avoir resolu ces deux points, relancer l'audit 11.

3.5 KiB Raw Blame History