baobab-ai-dev-documents 0.1.0

Librairie de gouvernance documentaire de l'écosystème baobab-ai-development.

baobab-ai-dev-documents

Librairie Python de gouvernance documentaire de l'écosystème baobab-ai-development.

Elle transforme les documents Markdown utilisés pour piloter les développements IA (cahiers des charges, user stories, features, backlogs, prompts, ADR) en données structurées, validées, traçables et synchronisables avec le reste de la plateforme.

Le module fait la passerelle entre :

• la documentation rédigée par l'utilisateur ou par une IA ;
• les entités métier de baobab-ai-dev-core ;
• les repositories de baobab-ai-dev-database ;
• les futurs usages CLI, API, workflow IA et dashboard.

Statut : socle initial (v0.1.0). Voir la roadmap dans le cahier des charges (docs/01-cahier-des-charges/).

Installation

Le package cible Python ≥ 3.12.

# Installation applicative
pip install baobab-ai-dev-documents

# Installation en développement (outils qualité inclus)
pip install -e ".[dev]"

Dépendances runtime :

• baobab-ai-dev-core >= 0.2.0
• baobab-ai-dev-database >= 0.1.0

Usage minimal

import baobab_ai_dev_documents as docs
from baobab_ai_dev_documents import PACKAGE_METADATA, RuntimeMetadata

# Version du package (résolue depuis les métadonnées de distribution).
print(docs.__version__)

# Métadonnées descriptives du package et de ses sous-modules internes.
print(PACKAGE_METADATA.name)
print(PACKAGE_METADATA.modules)
print(PACKAGE_METADATA.has_module("parsing"))  # True

# Résolution de la version d'une distribution installée.
print(RuntimeMetadata.version(fallback="0.1.0"))
print(RuntimeMetadata.is_installed("baobab-ai-dev-core"))

Les services de scan, parsing, validation, mapping, import et génération de prompts sont livrés progressivement (voir la roadmap du cahier des charges). L'API cible complète est décrite dans docs/01-cahier-des-charges/.

Conventions d'arborescence

Le code source suit un src layout ; les tests forment une arborescence miroir de src/.

src/baobab_ai_dev_documents/
├── domain/        # Objets documentaires purs (entités, value objects)
├── scanning/      # Découverte et classification des fichiers Markdown
├── parsing/       # Front matter YAML et sections Markdown
├── validation/    # Validation structurelle et de cohérence
├── mapping/       # Mapping vers les entités de baobab-ai-dev-core
├── importing/     # Plan et service d'import documentaire
├── prompts/       # Génération de prompts IA
├── sync/          # Adaptateurs de synchronisation database
└── exports/       # Rapports et exports (JSON, Markdown)

tests/baobab_ai_dev_documents/
└── ...            # Un fichier test_<module>.py par classe applicative

Règles de structure :

• une classe applicative principale par fichier ;
• nom de fichier en snake_case correspondant à la classe (PascalCase) ;
• imports absolus ;
• chaque classe possède un test miroir test_<fichier_source>.py ;
• classes de test Test<NomDeClasse>, méthodes test_<comportement> ;
• typage strict (le package expose py.typed).

Qualité

La chaîne qualité est configurée dans pyproject.toml. Commandes attendues avant toute Pull Request :

pytest                              # tests unitaires
coverage run -m pytest && coverage report   # couverture ≥ 90 %
ruff check .                        # lint
black --check src tests            # format
mypy src                           # type-check (strict)
pylint src/baobab_ai_dev_documents # qualité (≥ 8.5/10)
bandit -c pyproject.toml -r src/baobab_ai_dev_documents -ll  # sécurité

Workflow de développement

Le développement suit la hiérarchie de branches :

main → us/* → feat/* → bl/*

• développement uniquement sur une branche bl/FEAT-XXX/BL-XXX-* ;
• Pull Requests : BL-XXX → FEAT-XXX → US-XXX → main ;
• aucun merge si un gate qualité, sécurité, QA ou fonctionnel est en NO GO.

La spécification complète (cahier des charges, user stories, features, backlogs) est versionnée dans docs/.

Licence

Distribué sous licence MIT. Voir le fichier LICENSE.