baobab-ai-dev-core 1.0.0__py3-none-any.whl

baobab_ai_dev_core/__init__.py

@@ -0,0 +1,27 @@
+"""baobab-ai-dev-core — noyau métier Python pur de l'écosystème baobab-ai-development.
+
+Ce package expose les briques de domaine (entités, objets de valeur, enums,
+exceptions, politiques et contrats ``Protocol``) consommées par les modules
+database, documents, git, quality, providers, workflow, API, CLI et workers.
+
+Convention d'API publique
+--------------------------
+- Point d'entrée unique : les consommateurs importent depuis ``baobab_ai_dev_core``
+  (``from baobab_ai_dev_core import ...``), jamais depuis les sous-modules internes.
+- Contrat explicite : seuls les symboles listés dans :data:`__all__` font partie de
+  l'API publique stable. Tout symbole absent de ``__all__`` est considéré interne et
+  peut changer sans préavis.
+- Compatibilité : ``__all__`` est maintenu trié pour limiter les diffs et garantir un
+  ordre déterministe. Les sous-packages du domaine (``domain.entities``,
+  ``domain.enums``, ``domain.value_objects``, ``domain.policies``,
+  ``domain.protocols``, ``domain.exceptions``) y seront re-exportés au fur et à mesure
+  de leur stabilisation dans les user stories suivantes.
+
+À ce stade, seul le numéro de version est exposé publiquement via ``__all__``.
+"""
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+]

baobab_ai_dev_core/domain/__init__.py

@@ -0,0 +1,5 @@
+"""Sous-package domaine de baobab-ai-dev-core.
+
+Regroupe les briques métier pures : ``entities``, ``value_objects``, ``enums``,
+``exceptions``, ``policies`` et ``protocols``.
+"""

baobab_ai_dev_core/domain/entities/__init__.py

@@ -0,0 +1,13 @@
+"""Entités métier du domaine baobab-ai-dev-core."""
+
+from baobab_ai_dev_core.domain.entities.backlog import Backlog
+from baobab_ai_dev_core.domain.entities.feature import Feature
+from baobab_ai_dev_core.domain.entities.project import Project
+from baobab_ai_dev_core.domain.entities.user_story import UserStory
+
+__all__ = [
+    "Backlog",
+    "Feature",
+    "Project",
+    "UserStory",
+]

baobab_ai_dev_core/domain/entities/ai_provider.py

@@ -0,0 +1,134 @@
+"""Entité métier représentant un provider IA au niveau domaine."""
+
+from baobab_ai_dev_core.domain.enums.ai_provider_status import AiProviderStatus
+from baobab_ai_dev_core.domain.enums.ai_provider_type import AiProviderType
+from baobab_ai_dev_core.domain.exceptions.domain_validation_error import (
+    DomainValidationError,
+)
+from baobab_ai_dev_core.domain.value_objects.domain_title import DomainTitle
+from baobab_ai_dev_core.domain.value_objects.entity_id import EntityId
+
+_PRIORITE_MIN = 1
+_QUOTA_OK = "ok"
+_QUOTA_EXHAUSTED = "usage_exhausted"
+
+
+def _valider_priorite(priorite: int) -> int:
+    if priorite < _PRIORITE_MIN:
+        raise DomainValidationError(
+            f"La priorité doit être >= {_PRIORITE_MIN} (reçue : {priorite})."
+        )
+    return priorite
+
+
+def _valider_quota_state(quota_state: str) -> str:
+    nettoye = quota_state.strip()
+    if nettoye not in {_QUOTA_OK, _QUOTA_EXHAUSTED}:
+        raise DomainValidationError(
+            f"quota_state invalide : '{quota_state}'. "
+            f"Valeurs attendues : '{_QUOTA_OK}', '{_QUOTA_EXHAUSTED}'."
+        )
+    return nettoye
+
+
+def _valider_coherence_statut_quota(
+    status: AiProviderStatus,
+    quota_state: str,
+) -> None:
+    """Vérifie l'alignement entre statut et quota."""
+    if status is AiProviderStatus.USAGE_EXHAUSTED and quota_state != _QUOTA_EXHAUSTED:
+        raise DomainValidationError(
+            "Le statut 'usage_exhausted' exige quota_state='usage_exhausted'."
+        )
+    if status is AiProviderStatus.AVAILABLE and quota_state != _QUOTA_OK:
+        raise DomainValidationError(
+            "Le statut 'available' exige quota_state='ok'."
+        )
+
+
+class AiProvider:
+    """Provider IA métier avec priorité, statut et état de quota.
+
+    Ne contient aucun client technique : l'intégration relève du module
+    ``providers``.
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        provider_id: EntityId,
+        name: DomainTitle,
+        provider_type: AiProviderType,
+        status: AiProviderStatus,
+        priority: int,
+        quota_state: str,
+    ) -> None:
+        """Construit un provider en validant priorité et quota."""
+        priorite = _valider_priorite(priority)
+        quota = _valider_quota_state(quota_state)
+        _valider_coherence_statut_quota(status, quota)
+        self._provider_id = provider_id
+        self._name = name
+        self._provider_type = provider_type
+        self._status = status
+        self._priority = priorite
+        self._quota_state = quota
+
+    @property
+    def provider_id(self) -> EntityId:
+        """Identifiant stable du provider."""
+        return self._provider_id
+
+    @property
+    def name(self) -> DomainTitle:
+        """Nom affiché du provider."""
+        return self._name
+
+    @property
+    def provider_type(self) -> AiProviderType:
+        """Famille technique du provider."""
+        return self._provider_type
+
+    @property
+    def status(self) -> AiProviderStatus:
+        """Statut de disponibilité courant."""
+        return self._status
+
+    @property
+    def priority(self) -> int:
+        """Priorité de sélection (1 = la plus haute)."""
+        return self._priority
+
+    @property
+    def quota_state(self) -> str:
+        """État du quota (``ok`` ou ``usage_exhausted``)."""
+        return self._quota_state
+
+    @property
+    def is_selectable(self) -> bool:
+        """Indique si le provider peut être sélectionné pour un run."""
+        return (
+            self._status is AiProviderStatus.AVAILABLE
+            and self._quota_state == _QUOTA_OK
+        )
+
+    def mark_usage_exhausted(self) -> None:
+        """Marque le quota comme épuisé (distinct de indisponible ou erreur)."""
+        self._status = AiProviderStatus.USAGE_EXHAUSTED
+        self._quota_state = _QUOTA_EXHAUSTED
+
+    def mark_error(self) -> None:
+        """Marque une erreur technique sans confondre avec quota épuisé."""
+        self._status = AiProviderStatus.ERROR
+
+    def disable(self) -> None:
+        """Désactive volontairement le provider."""
+        self._status = AiProviderStatus.DISABLED
+
+    def mark_unavailable(self) -> None:
+        """Marque une indisponibilité ponctuelle."""
+        self._status = AiProviderStatus.UNAVAILABLE
+
+    def restore_available(self) -> None:
+        """Restaure un provider disponible avec quota OK."""
+        self._status = AiProviderStatus.AVAILABLE
+        self._quota_state = _QUOTA_OK

baobab_ai_dev_core/domain/entities/artifact.py

@@ -0,0 +1,91 @@
+"""Entité métier représentant un livrable produit pendant une exécution."""
+
+import re
+from datetime import datetime
+
+from baobab_ai_dev_core.domain.enums.artifact_type import ArtifactType
+from baobab_ai_dev_core.domain.exceptions.domain_validation_error import (
+    DomainValidationError,
+)
+from baobab_ai_dev_core.domain.value_objects.entity_id import EntityId
+
+_CHEMIN_RELATIF_PATTERN = re.compile(r"^[a-zA-Z0-9_./-]+$")
+
+
+def _valider_chemin(path: str) -> str:
+    nettoye = path.strip()
+    if not nettoye:
+        raise DomainValidationError("Le chemin d'artefact ne peut pas être vide.")
+    if nettoye.startswith("/") or ".." in nettoye.split("/"):
+        raise DomainValidationError(
+            f"Le chemin '{nettoye}' doit être relatif et ne pas contenir '..'."
+        )
+    if not _CHEMIN_RELATIF_PATTERN.fullmatch(nettoye):
+        raise DomainValidationError(
+            f"Le chemin '{nettoye}' contient des caractères non autorisés."
+        )
+    return nettoye
+
+
+def _valider_checksum(checksum: str | None) -> str | None:
+    if checksum is None:
+        return None
+    nettoye = checksum.strip()
+    if not nettoye:
+        raise DomainValidationError(
+            "Le checksum ne peut pas être vide lorsqu'il est renseigné."
+        )
+    return nettoye
+
+
+class Artifact:
+    """Livrable généré pendant un workflow run (patch, rapport, fichier, etc.)."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        artifact_id: EntityId,
+        workflow_run_id: EntityId,
+        artifact_type: ArtifactType,
+        path: str,
+        checksum: str | None,
+        created_at: datetime,
+    ) -> None:
+        """Construit un artefact en validant le chemin relatif et le checksum."""
+        chemin = _valider_chemin(path)
+        empreinte = _valider_checksum(checksum)
+        self._artifact_id = artifact_id
+        self._workflow_run_id = workflow_run_id
+        self._artifact_type = artifact_type
+        self._path = chemin
+        self._checksum = empreinte
+        self._created_at = created_at
+
+    @property
+    def artifact_id(self) -> EntityId:
+        """Identifiant stable de l'artefact."""
+        return self._artifact_id
+
+    @property
+    def workflow_run_id(self) -> EntityId:
+        """Identifiant du run ayant produit l'artefact."""
+        return self._workflow_run_id
+
+    @property
+    def artifact_type(self) -> ArtifactType:
+        """Type métier de l'artefact."""
+        return self._artifact_type
+
+    @property
+    def path(self) -> str:
+        """Chemin relatif validé de l'artefact."""
+        return self._path
+
+    @property
+    def checksum(self) -> str | None:
+        """Empreinte facultative du contenu."""
+        return self._checksum
+
+    @property
+    def created_at(self) -> datetime:
+        """Horodatage de création."""
+        return self._created_at

baobab_ai_dev_core/domain/entities/backlog.py

@@ -0,0 +1,171 @@
+"""Entité métier représentant un backlog exécutable par une IA."""
+
+from baobab_ai_dev_core.domain.enums.branch_type import BranchType
+from baobab_ai_dev_core.domain.enums.work_item_status import WorkItemStatus
+from baobab_ai_dev_core.domain.exceptions.domain_validation_error import (
+    DomainValidationError,
+)
+from baobab_ai_dev_core.domain.value_objects.backlog_code import BacklogCode
+from baobab_ai_dev_core.domain.value_objects.branch_name import BranchName
+from baobab_ai_dev_core.domain.value_objects.domain_description import DomainDescription
+from baobab_ai_dev_core.domain.value_objects.domain_title import DomainTitle
+from baobab_ai_dev_core.domain.value_objects.entity_id import EntityId
+
+_COMPLEXITE_MIN = 1
+_COMPLEXITE_MAX = 13
+
+
+def _valider_acceptance_criteria(criteres: tuple[str, ...]) -> tuple[str, ...]:
+    """Normalise et valide les critères d'acceptation d'un backlog."""
+    if not criteres:
+        raise DomainValidationError(
+            "Les acceptance_criteria doivent contenir au moins un critère non vide."
+        )
+    normalises: list[str] = []
+    for index, critere in enumerate(criteres):
+        nettoye = critere.strip()
+        if not nettoye:
+            raise DomainValidationError(
+                f"Le critère d'acceptation à l'index {index} ne peut pas être vide."
+            )
+        normalises.append(nettoye)
+    return tuple(normalises)
+
+
+def _valider_chemins_attendus(
+    chemins: tuple[str, ...],
+    libelle: str,
+) -> tuple[str, ...]:
+    """Valide une liste non vide de chemins relatifs attendus."""
+    if not chemins:
+        raise DomainValidationError(
+            f"Les {libelle} doivent contenir au moins un chemin non vide."
+        )
+    normalises: list[str] = []
+    for index, chemin in enumerate(chemins):
+        nettoye = chemin.strip()
+        if not nettoye:
+            raise DomainValidationError(
+                f"Le chemin {libelle} à l'index {index} ne peut pas être vide."
+            )
+        normalises.append(nettoye)
+    return tuple(normalises)
+
+
+def _valider_complexite_estimee(complexite: int) -> int:
+    """Valide la complexité estimée sur une échelle de story points 1 à 13."""
+    if complexite < _COMPLEXITE_MIN or complexite > _COMPLEXITE_MAX:
+        raise DomainValidationError(
+            f"estimated_complexity doit être entre {_COMPLEXITE_MIN} et "
+            f"{_COMPLEXITE_MAX} (reçu : {complexite})."
+        )
+    return complexite
+
+
+def _valider_branche_backlog(code: BacklogCode, branch_name: BranchName) -> None:
+    """Vérifie que la branche Git correspond au code du backlog."""
+    if branch_name.branch_type is not BranchType.BACKLOG:
+        raise DomainValidationError(
+            f"La branche '{branch_name.value}' n'est pas une branche backlog (bl/*)."
+        )
+    branche_code = branch_name.backlog_code
+    if branche_code is None or branche_code != code:
+        raise DomainValidationError(
+            f"Le code de branche ({branche_code}) ne correspond pas au code "
+            f"du backlog ({code})."
+        )
+
+
+class Backlog:
+    """Unité de travail exécutable portée par une branche ``bl/FEAT-XXX/BL-XXX-*``.
+
+    Définit un périmètre strict via les fichiers et tests attendus, une complexité
+    estimée et des critères d'acceptation pour guider l'IA de développement.
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        backlog_id: EntityId,
+        feature_id: EntityId,
+        code: BacklogCode,
+        title: DomainTitle,
+        description: DomainDescription,
+        status: WorkItemStatus,
+        acceptance_criteria: tuple[str, ...],
+        branch_name: BranchName,
+        estimated_complexity: int,
+        expected_files: tuple[str, ...],
+        expected_tests: tuple[str, ...],
+    ) -> None:
+        """Construit un backlog en validant branche, périmètre et critères."""
+        criteres = _valider_acceptance_criteria(acceptance_criteria)
+        fichiers = _valider_chemins_attendus(expected_files, "expected_files")
+        tests = _valider_chemins_attendus(expected_tests, "expected_tests")
+        complexite = _valider_complexite_estimee(estimated_complexity)
+        _valider_branche_backlog(code, branch_name)
+        self._backlog_id = backlog_id
+        self._feature_id = feature_id
+        self._code = code
+        self._title = title
+        self._description = description
+        self._status = status
+        self._acceptance_criteria = criteres
+        self._branch_name = branch_name
+        self._estimated_complexity = complexite
+        self._expected_files = fichiers
+        self._expected_tests = tests
+
+    @property
+    def backlog_id(self) -> EntityId:
+        """Identifiant stable du backlog."""
+        return self._backlog_id
+
+    @property
+    def feature_id(self) -> EntityId:
+        """Identifiant de la feature parente."""
+        return self._feature_id
+
+    @property
+    def code(self) -> BacklogCode:
+        """Code métier au format ``BL-XXX``."""
+        return self._code
+
+    @property
+    def title(self) -> DomainTitle:
+        """Titre du backlog."""
+        return self._title
+
+    @property
+    def description(self) -> DomainDescription:
+        """Description métier et périmètre fonctionnel."""
+        return self._description
+
+    @property
+    def status(self) -> WorkItemStatus:
+        """Statut courant du work item."""
+        return self._status
+
+    @property
+    def acceptance_criteria(self) -> tuple[str, ...]:
+        """Critères d'acceptation normalisés."""
+        return self._acceptance_criteria
+
+    @property
+    def branch_name(self) -> BranchName:
+        """Branche Git conforme ``bl/FEAT-XXX/BL-XXX-*``."""
+        return self._branch_name
+
+    @property
+    def estimated_complexity(self) -> int:
+        """Complexité estimée (story points de 1 à 13)."""
+        return self._estimated_complexity
+
+    @property
+    def expected_files(self) -> tuple[str, ...]:
+        """Chemins des fichiers source attendus dans le périmètre."""
+        return self._expected_files
+
+    @property
+    def expected_tests(self) -> tuple[str, ...]:
+        """Chemins des fichiers de test attendus dans le périmètre."""
+        return self._expected_tests

baobab_ai_dev_core/domain/entities/blocker.py

@@ -0,0 +1,110 @@
+"""Entité métier représentant un blocage sur une exécution."""
+
+from datetime import datetime
+
+from baobab_ai_dev_core.domain.enums.blocker_severity import BlockerSeverity
+from baobab_ai_dev_core.domain.exceptions.domain_validation_error import (
+    DomainValidationError,
+)
+from baobab_ai_dev_core.domain.value_objects.entity_id import EntityId
+
+
+def _valider_message(message: str) -> str:
+    nettoye = message.strip()
+    if not nettoye:
+        raise DomainValidationError("Le message du blocker ne peut pas être vide.")
+    return nettoye
+
+
+def _valider_type_cible(target_type: str) -> str:
+    nettoye = target_type.strip()
+    if not nettoye:
+        raise DomainValidationError("Le target_type du blocker ne peut pas être vide.")
+    return nettoye
+
+
+class Blocker:
+    """Blocage métier ou technique empêchant la progression d'une exécution."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        blocker_id: EntityId,
+        target_id: EntityId,
+        target_type: str,
+        severity: BlockerSeverity,
+        message: str,
+        created_at: datetime,
+        resolved_at: datetime | None,
+    ) -> None:
+        """Construit un blocker en validant message, cible et résolution."""
+        type_cible = _valider_type_cible(target_type)
+        texte = _valider_message(message)
+        if resolved_at is not None and resolved_at < created_at:
+            raise DomainValidationError(
+                "resolved_at ne peut pas être antérieur à created_at pour un Blocker."
+            )
+        self._blocker_id = blocker_id
+        self._target_id = target_id
+        self._target_type = type_cible
+        self._severity = severity
+        self._message = texte
+        self._created_at = created_at
+        self._resolved_at = resolved_at
+
+    @property
+    def blocker_id(self) -> EntityId:
+        """Identifiant stable du blocker."""
+        return self._blocker_id
+
+    @property
+    def target_id(self) -> EntityId:
+        """Identifiant de la cible bloquée."""
+        return self._target_id
+
+    @property
+    def target_type(self) -> str:
+        """Type de la cible (run, step, job, etc.)."""
+        return self._target_type
+
+    @property
+    def severity(self) -> BlockerSeverity:
+        """Niveau de sévérité du blocage."""
+        return self._severity
+
+    @property
+    def message(self) -> str:
+        """Message explicite du blocage."""
+        return self._message
+
+    @property
+    def created_at(self) -> datetime:
+        """Horodatage de création."""
+        return self._created_at
+
+    @property
+    def resolved_at(self) -> datetime | None:
+        """Horodatage de résolution, le cas échéant."""
+        return self._resolved_at
+
+    @property
+    def is_resolved(self) -> bool:
+        """Indique si le blocker est résolu."""
+        return self._resolved_at is not None
+
+    @property
+    def is_critical(self) -> bool:
+        """Un blocker critique empêche la progression du run."""
+        return self._severity is BlockerSeverity.CRITICAL
+
+    def resolve(self, at: datetime) -> None:
+        """Marque le blocker comme résolu en conservant l'historique."""
+        if self._resolved_at is not None:
+            raise DomainValidationError(
+                f"Le blocker '{self._blocker_id}' est déjà résolu."
+            )
+        if at < self._created_at:
+            raise DomainValidationError(
+                f"resolved_at ({at.isoformat()}) ne peut pas être antérieur à "
+                f"created_at ({self._created_at.isoformat()})."
+            )
+        self._resolved_at = at

baobab_ai_dev_core/domain/entities/feature.py

@@ -0,0 +1,114 @@
+"""Entité métier représentant une feature."""
+
+from baobab_ai_dev_core.domain.enums.branch_type import BranchType
+from baobab_ai_dev_core.domain.enums.work_item_status import WorkItemStatus
+from baobab_ai_dev_core.domain.exceptions.domain_validation_error import (
+    DomainValidationError,
+)
+from baobab_ai_dev_core.domain.value_objects.branch_name import BranchName
+from baobab_ai_dev_core.domain.value_objects.domain_description import DomainDescription
+from baobab_ai_dev_core.domain.value_objects.domain_title import DomainTitle
+from baobab_ai_dev_core.domain.value_objects.entity_id import EntityId
+from baobab_ai_dev_core.domain.value_objects.feature_code import FeatureCode
+
+
+def _valider_acceptance_criteria(criteres: tuple[str, ...]) -> tuple[str, ...]:
+    """Normalise et valide les critères d'acceptation d'une feature."""
+    if not criteres:
+        raise DomainValidationError(
+            "Les acceptance_criteria doivent contenir au moins un critère non vide."
+        )
+    normalises: list[str] = []
+    for index, critere in enumerate(criteres):
+        nettoye = critere.strip()
+        if not nettoye:
+            raise DomainValidationError(
+                f"Le critère d'acceptation à l'index {index} ne peut pas être vide."
+            )
+        normalises.append(nettoye)
+    return tuple(normalises)
+
+
+def _valider_branche_feature(code: FeatureCode, branch_name: BranchName) -> None:
+    """Vérifie que la branche Git correspond au code de la feature."""
+    if branch_name.branch_type is not BranchType.FEATURE:
+        raise DomainValidationError(
+            f"La branche '{branch_name.value}' n'est pas une branche feature (feat/*)."
+        )
+    branche_code = branch_name.feature_code
+    if branche_code is None or branche_code != code:
+        raise DomainValidationError(
+            f"Le code de branche ({branche_code}) ne correspond pas au code "
+            f"de la feature ({code})."
+        )
+
+
+class Feature:
+    """Capacité livrable portée par une branche ``feat/US-XXX/FEAT-XXX-*``.
+
+    Appartient à une user story, contient des backlogs et expose ses critères
+    d'acceptation et son statut de work item.
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        feature_id: EntityId,
+        user_story_id: EntityId,
+        code: FeatureCode,
+        title: DomainTitle,
+        description: DomainDescription,
+        status: WorkItemStatus,
+        acceptance_criteria: tuple[str, ...],
+        branch_name: BranchName,
+    ) -> None:
+        """Construit une feature en validant branche et critères."""
+        criteres = _valider_acceptance_criteria(acceptance_criteria)
+        _valider_branche_feature(code, branch_name)
+        self._feature_id = feature_id
+        self._user_story_id = user_story_id
+        self._code = code
+        self._title = title
+        self._description = description
+        self._status = status
+        self._acceptance_criteria = criteres
+        self._branch_name = branch_name
+
+    @property
+    def feature_id(self) -> EntityId:
+        """Identifiant stable de la feature."""
+        return self._feature_id
+
+    @property
+    def user_story_id(self) -> EntityId:
+        """Identifiant de la user story parente."""
+        return self._user_story_id
+
+    @property
+    def code(self) -> FeatureCode:
+        """Code métier au format ``FEAT-XXX``."""
+        return self._code
+
+    @property
+    def title(self) -> DomainTitle:
+        """Titre de la feature."""
+        return self._title
+
+    @property
+    def description(self) -> DomainDescription:
+        """Description métier."""
+        return self._description
+
+    @property
+    def status(self) -> WorkItemStatus:
+        """Statut courant du work item."""
+        return self._status
+
+    @property
+    def acceptance_criteria(self) -> tuple[str, ...]:
+        """Critères d'acceptation normalisés."""
+        return self._acceptance_criteria
+
+    @property
+    def branch_name(self) -> BranchName:
+        """Branche Git conforme ``feat/US-XXX/FEAT-XXX-*``."""
+        return self._branch_name