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 : SOLID

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

Score de compliance

Metrique	Valeur
Items conformes	18 / 20
Score	85 / 100
Ecarts CRITICAL	0
Ecarts MAJOR	1
Ecarts MINOR	1
Ecarts INFO	0

Ecarts constates

[MAJ] Liskov Substitution Principle — isinstance check sur adaptateur

Localisation : document-parser/services/analysis_service.py:356
Constat : Le service AnalysisService utilise isinstance(self._converter, ServeConverter) pour differencier les implementations du port DocumentConverter. Ceci viole LSP car :
1. Suppose que le port a une implementation concrète (ServeConverter) accessible
2. Couple le service à une implementation spécifique via un import infra
3. Empeche la substitution transparente d'autres adaptateurs (e.g., mock, Docling Cloud)
Regle violee : 6.3.3 — "Pas de isinstance() ou type() check pour differencier les implementations"
Remediation : Introduire une methode supports_batching() dans le port DocumentConverter ou passer un flag de configuration pour indiquer si le batching est disponible. Supprimer l'import infra du service.

[MIN] Interface Segregation Principle — aperture OpenSearch directe

Localisation : document-parser/services/ingestion_service.py:197
Constat : ping() accede directement à self._vector_store._client.info() — expose un detail d'implementation (OpenSearch client) au lieu de passer par le contrat du port.
Regle violee : 6.4.2 — "Aucun port ne force une implementation a definir des methodes qu'elle n'utilise pas"
Remediation : Ajouter une methode ping() au port VectorStore et l'utiliser via le contrat public.

Points positifs

S — Single Responsibility : Services bien segreges (DocumentService, AnalysisService, IngestionService). Chaque service a une responsabilité unique.
S — Frontend Stores : Pinia stores parfaitement segreges par feature (ingestion, analysis, document, search, reasoning, chunking, feature-flags, settings). Aucun store god-object.
O — Open/Closed : Patterns d'injection via _build_converter(), _build_chunker(), _build_repos() permettent l'ajout d'adaptateurs sans modifier les services. Architecture très extensible.
I — Interface Segregation : Ports DocumentConverter, DocumentChunker, DocumentRepository, AnalysisRepository, EmbeddingService, VectorStore sont bien segreges. Aucune god interface.
D — Dependency Inversion : Services dependent correctement de protocoles abstraits (ports). Injection se fait en composition root (main.py:_build_*). Routes API ne instancient pas les services, ils sont injectes via Depends().
API Router Organization : Routes groupees par ressource (documents.py, analyses.py, ingestion.py, reasoning.py, graph.py) — pure OCP.
Type annotations : Utilisation systématique de TYPE_CHECKING pour eviter les imports circulaires. Protocols comme ports — excellent design.
Frontend composables/stores : Separation claire entre logique et UI. Chaque store est independant et recomposable.

Verdict partiel : GO

Conditions:

[MAJ] Refactorer _is_remote_converter() pour utiliser une methode de configuration ou un flag au lieu de isinstance() infra.
[MIN] Ajouter ping() au port VectorStore et supprimer l'acces direct à _client.

Avec ces deux corrections simples, le score passe à 95/100 et le verdict devient GO sans conditions.

3.5 KiB Raw Blame History