Metadata-Version: 2.4
Name: baobab-ai-dev-git
Version: 0.1.0
Summary: Librairie Python de gestion Git pour l'écosystème Baobab AI Dev.
Author: Baobab AI Dev
License: MIT
Project-URL: Homepage, https://github.com/baobabgit/baobab-ai-dev-git
Project-URL: Documentation, https://github.com/baobabgit/baobab-ai-dev-git/blob/main/README.md
Project-URL: Repository, https://github.com/baobabgit/baobab-ai-dev-git
Project-URL: Issues, https://github.com/baobabgit/baobab-ai-dev-git/issues
Project-URL: Changelog, https://github.com/baobabgit/baobab-ai-dev-git/blob/main/CHANGELOG.md
Keywords: git,github,baobab,workflow,branches,pull-request,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: baobab-ai-dev-core<2,>=1.1.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: pylint>=3.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# baobab-ai-dev-git

Librairie Python de gestion Git pour l'écosystème **Baobab AI Dev**.

Elle permet à une IA de développement (ou à un outil CLI/workflow) de piloter les opérations Git d'un projet structuré en **user stories**, **features** et **backlogs**, avec des règles hiérarchiques explicites et testables.

Spécification complète : [`docs/01-cahier-des-charges.md`](docs/01-cahier-des-charges.md).

## Rôle dans l'écosystème

| Module | Rôle |
|---|---|
| `baobab-ai-dev-core` | Objets métier partagés (`UserStory`, `Feature`, `Backlog`, …) |
| **`baobab-ai-dev-git`** | Conventions de branches, validation PR, éligibilité au merge, Git local |
| `baobab-ai-dev-workflow` | Orchestration des runs IA |
| `baobab-ai-dev-cli` | Interface en ligne de commande |

Cette librairie **ne dépend pas** du backend API, du frontend, de la base de données ni des providers IA.

## Dépendance `baobab-ai-dev-core`

Les entités métier `UserStory`, `Feature` et `Backlog` sont fournies par [`baobab-ai-dev-core`](https://pypi.org/project/baobab-ai-dev-core/) (≥ 1.1.0), réexportées via `baobab_ai_dev_git.domain` pour compatibilité.

```python
from baobab_ai_dev_git.domain import Backlog, Feature, UserStory
```

Les services Git (`BranchNameBuilder`, `BranchService`, …) consomment ces entités officielles. Consultez la documentation de `baobab-ai-dev-core` pour la construction complète (identifiants, statuts, critères d'acceptation, branche Git associée).

## Installation

Prérequis : Python **≥ 3.12** (requis par `baobab-ai-dev-core`), Git disponible dans le `PATH`.

Depuis PyPI :

```bash
pip install baobab-ai-dev-git
```

Depuis les sources (développement) :

```bash
git clone https://github.com/baobabgit/baobab-ai-dev-git.git
cd baobab-ai-dev-git
python -m pip install -e ".[dev]"
```

Publication : voir [`docs/RELEASE.md`](docs/RELEASE.md).

Vérification rapide :

```bash
python -c "import baobab_ai_dev_git as git; print(git.__version__)"
pytest -q
```

## API publique

Les symboles stables sont exportés depuis le package racine :

```python
import baobab_ai_dev_git as git

print(git.__all__)
```

Services et types principaux :

| Symbole | Rôle |
|---|---|
| `BranchNameBuilder` | Génère un nom de branche conforme à partir d'un objet métier |
| `BranchNameValidator` | Valide le format d'un nom de branche |
| `BranchService` | Crée des branches locales en respectant la hiérarchie |
| `PullRequestValidator` | Vérifie la cible d'une Pull Request |
| `PullRequestService` | Prépare et crée une PR (port GitHub injectable) |
| `MergePolicyService` | Évalue l'éligibilité au merge |
| `GitOperationResult`, `MergeEligibilityResult`, … | Résultats typés sérialisables |
| `GitComplianceReport`, `GitComplianceReportBuilder` | Diagnostic de conformité Git |
| `GithubClientPort`, `GithubPullRequestAdapter`, `GithubRepositoryAdapter` | Intégration GitHub abstraite |
| `MergeNotAllowedError`, `BranchNotFoundError`, `BranchAlreadyExistsError`, `RepositoryDirtyError`, `GithubIntegrationError`, … | Exceptions métier explicites |

## Conventions de branches

Hiérarchie obligatoire :

```text
main
 └── us/<US-ID>-<slug>
      └── feat/<US-ID>/<FEAT-ID>-<slug>
           └── bl/<FEAT-ID>/<BL-ID>-<slug>
```

Règles de Pull Request :

| Branche source | Branche cible attendue |
|---|---|
| `bl/...` | Sa branche feature parente |
| `feat/...` | Sa branche user story parente |
| `us/...` | `main` |

Exemples de noms générés :

```python
from baobab_ai_dev_git import BranchNameBuilder
from baobab_ai_dev_git.domain import Backlog, Feature, UserStory

builder = BranchNameBuilder()

# Entités baobab-ai-dev-core — champs requis : code, title, branch_name, etc.
# Voir tests/helpers/core_entities.py pour des factories de test minimales.
us = ...  # UserStory avec code US-001 et titre normalisé
feat = ...  # Feature liée à us/US-001/...
bl = ...  # Backlog lié à feat/FEAT-001/...

print(builder.build_user_story_branch(us))
# us/US-001-initialiser-module-git

print(builder.build_feature_branch(feat))
# feat/US-001/FEAT-001-gestion-branches

print(builder.build_backlog_branch(bl))
# bl/FEAT-001/BL-001-validator
```

Les slugs sont normalisés : minuscules, sans accents, espaces → tirets.

## Exemples d'usage

### Valider une cible de Pull Request

```python
from baobab_ai_dev_git import PullRequestValidator

validator = PullRequestValidator()
known = [
    "main",
    "us/US-001-initialiser-module-git",
    "feat/US-001/FEAT-001-gestion-branches",
    "bl/FEAT-001/BL-001-validator",
]

result = validator.validate(
    "bl/FEAT-001/BL-001-validator",
    "feat/US-001/FEAT-001-gestion-branches",
    known_branches=known,
)

if result.is_valid:
    print("Cible PR conforme")
else:
    print(result.errors)
```

### Évaluer l'éligibilité au merge

```python
from baobab_ai_dev_git import MergePolicyService

service = MergePolicyService()
eligibility = service.evaluate_merge_eligibility(
    source_branch="bl/FEAT-001/BL-001-validator",
    target_branch="feat/US-001/FEAT-001-gestion-branches",
    known_branches=known,
    quality_checks={"pytest": True, "ruff": True, "mypy": True},
    open_branches=[],
)

print(eligibility.merge_allowed)
print(eligibility.to_dict())
```

Un merge est refusé si des branches enfants restent ouvertes (ex. backlogs non mergés avant leur feature).

### Créer une branche backlog locale

```python
from baobab_ai_dev_git import BranchService
from baobab_ai_dev_git.domain import Backlog

service = BranchService()
backlog = ...  # Backlog core FEAT-008 / BL-022

result = service.create_backlog_branch(
    backlog,
    parent_branch="feat/US-008/FEAT-008-socle-technique-transversal",
    cwd="/chemin/vers/le/depot",
)

if result.success:
    print(f"Branche créée : {result.branch_name}")
else:
    print(result.errors)
```

## Exemple de workflow IA

Scénario type pour une IA qui développe un backlog :

```text
1. Lire le backlog (ex. BL-022) et sa feature parente (FEAT-008).
2. Construire le nom de branche avec BranchNameBuilder.
3. Créer la branche via BranchService.create_backlog_branch().
4. Développer sur bl/<FEAT-ID>/<BL-ID>-<slug> uniquement.
5. Avant d'ouvrir une PR :
   - PullRequestValidator → vérifier la cible feat/<US-ID>/...
   - MergePolicyService → vérifier checks qualité + absence de branches enfants ouvertes.
6. Si merge_allowed est False → corriger (tests, branches dépendantes) sans tenter le merge.
7. Sérialiser les résultats (to_dict()) pour les rapports du workflow IA.
```

Pseudo-code :

```python
import baobab_ai_dev_git as git

backlog = ...  # Backlog core
parent = "feat/US-008/FEAT-008-socle-technique-transversal"

branch_name = git.BranchNameBuilder().build_backlog_branch(backlog)
creation = git.BranchService().create_backlog_branch(backlog, parent_branch=parent)

pr_check = git.PullRequestValidator().validate(branch_name, parent, known_branches=[parent, branch_name])
merge_check = git.MergePolicyService().evaluate_merge_eligibility(
    branch_name,
    parent,
    known_branches=[parent, branch_name],
    quality_checks={"pytest": True, "ruff": True},
    open_branches=[],
)

report = {
    "branch": branch_name,
    "created": creation.to_dict(),
    "pr_valid": pr_check.to_dict(),
    "merge_eligible": merge_check.to_dict(),
}
```

## Qualité et tests

```bash
pytest
ruff check .
mypy src
black --check src tests
```

Couverture minimale attendue : **90 %** (voir `pyproject.toml`).

## Documentation

- Cahier des charges : [`docs/01-cahier-des-charges.md`](docs/01-cahier-des-charges.md)
- Backlogs et features : [`docs/04-backlogs/`](docs/04-backlogs/), [`docs/03-features/`](docs/03-features/)
- Décisions d'architecture : [`docs/ia_workflow/decisions/`](docs/ia_workflow/decisions/)
