napkinstack 0.1.0__py3-none-any.whl

napkinstack/__init__.py

@@ -0,0 +1,5 @@
+"""NapkinStack — moteur : fitness functions, skills et scaffold de module."""
+
+from importlib.metadata import version
+
+__version__ = version("napkinstack")

napkinstack/cli.py

@@ -0,0 +1,103 @@
+"""Point d'entrée unique `nstack` (chantier C1, PDR-0001)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+from pathlib import Path
+
+from napkinstack import __version__, doctor, modules, skills
+from napkinstack.fitness import boundaries, manifests
+
+PACKAGE = Path(__file__).resolve().parent
+
+
+def _root(value: str) -> Path:
+    root = Path(value).resolve()
+    if not root.is_dir():
+        raise argparse.ArgumentTypeError(f"racine introuvable : {value}")
+    return root
+
+
+def _script(relative: str, *args: str, root: Path) -> int:
+    env = {**os.environ, "NSTACK_ROOT": str(root)}
+    return subprocess.run(["bash", str(PACKAGE / relative), *args], cwd=root, env=env).returncode
+
+
+def _fitness(root: Path) -> int:
+    results = [manifests.run(root), boundaries.run(root), skills.run(root, check_only=True)]
+    return 1 if any(results) else 0
+
+
+def _add(sub, name: str, help_: str, func) -> argparse.ArgumentParser:
+    parser = sub.add_parser(name, help=help_)
+    parser.add_argument("--root", type=_root, default=Path.cwd(),
+                        help="racine du projet (défaut : dossier courant)")
+    parser.set_defaults(func=func)
+    return parser
+
+
+def _init(args: argparse.Namespace) -> int:
+    from napkinstack import project  # Copier ne se charge que pour init et update
+
+    answers = {"project_name": args.project_name, "github_repo": args.github_repo,
+               "owner_team": args.owner_team}
+    return project.init(args.destination, answers, args.source or project.SOURCE,
+                        args.ref or project.default_ref())
+
+
+def _update(args: argparse.Namespace) -> int:
+    from napkinstack import project
+
+    return project.update(args.root, args.ref or project.default_ref())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nstack", description="Moteur NapkinStack.")
+    parser.add_argument("--version", action="version", version=f"nstack {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="commande")
+    _add(sub, "manifests", "manifests, cycles de vie, dépréciations (M1–M9)",
+         lambda a: manifests.run(a.root))
+    _add(sub, "boundaries", "graphe déclaré contre graphe réel (B1–B5)",
+         lambda a: boundaries.run(a.root))
+    sk = _add(sub, "skills", "génère ou vérifie les skills (S1–S4)",
+              lambda a: skills.run(a.root, check_only=a.check))
+    sk.add_argument("--check", action="store_true", help="vérifier sans écrire")
+    _add(sub, "fitness", "manifests + frontières + skills",
+         lambda a: _fitness(a.root))
+    _add(sub, "doctor", "diagnostique le poste et les réglages GitHub, en lecture seule (PDR-0001)",
+         lambda a: doctor.run(a.root))
+    nm = _add(sub, "new-module", "crée un module et ses garde-fous, sans stack imposée",
+              lambda a: modules.nouveau(a.root, a.name, a.owner, a.criticality))
+    nm.add_argument("name", help="nom du module, kebab-case")
+    nm.add_argument("owner", help="équipe GitHub, organisation/équipe")
+    nm.add_argument("criticality", choices=["prototype", "standard", "eleve", "critique"])
+    for nom_verbe, aide in (("bootstrap", "prépare un module, ou tous (commands.bootstrap)"),
+                            ("check", "format, lint, types d'un module, ou de tous (commands.check)"),
+                            ("test", "tests d'un module, ou de tous (commands.test)")):
+        vb = _add(sub, nom_verbe, aide, lambda a, v=nom_verbe: modules.verbe(a.root, v, a.module))
+        vb.add_argument("module", nargs="?", help="nom du module (défaut : tous)")
+    rn = _add(sub, "run", "démarre un module en local (commands.run)",
+              lambda a: modules.verbe(a.root, "run", a.module))
+    rn.add_argument("module")
+    ps = _add(sub, "pr-scope", "une PR = un module, budget de revue (P1–P2)",
+              lambda a: _script("fitness/pr_scope.sh", a.base, root=a.root))
+    ps.add_argument("--base", default="origin/main")
+    ini = sub.add_parser("init", help="crée un projet à partir du squelette (PDR-0001)")
+    ini.add_argument("destination", type=Path, help="dossier du projet, absent ou vide")
+    ini.add_argument("--project-name", help="nom du projet (demandé si absent)")
+    ini.add_argument("--github-repo", help="dépôt GitHub, organisation/nom (demandé si absent)")
+    ini.add_argument("--owner-team", help="équipe GitHub du socle, organisation/équipe (demandé si absent)")
+    ini.add_argument("--source", help="gabarit : URL ou chemin (défaut : dépôt NapkinStack)")
+    ini.add_argument("--ref", help="version du squelette, tag vX.Y.Z (défaut : celle de nstack)")
+    ini.set_defaults(func=_init)
+    up = _add(sub, "update", "fusionne une version de NapkinStack sur une branche à relire (PDR-0001)",
+              _update)
+    up.add_argument("--ref", help="version cible, tag vX.Y.Z (défaut : celle de nstack)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)

napkinstack/doctor.py

@@ -0,0 +1,278 @@
+"""
+Diagnostic d'un projet, en lecture seule : le poste et les réglages GitHub (PDR-0001).
+
+Les workflows informent ; ce sont les réglages GitHub qui bloquent, et ils ne se copient
+pas avec le projet. CHECKLIST est affichée par nstack init, vérifiée ici, et recopiée mot
+pour mot dans le README du squelette (un test le vérifie).
+
+GitHub se lit avec un jeton fourni par l'humain (GH_TOKEN, sinon GITHUB_TOKEN) : à grain
+fin, limité au dépôt, permission Administration : lecture. Sans jeton, ou si l'API refuse
+une lecture, le réglage est « non vérifié », jamais conforme. Aucune écriture.
+
+Contrôles :
+  L1  nstack installé à la version du projet (_commit de .copier-answers.yml)
+  L2  git et pre-commit disponibles
+  L3  hooks pre-commit installés
+  L4  PRODUCT.md absent : contexte de développement de NapkinStack (R6)
+  L5  README personnalisé : phrase de présentation écrite
+  G1–G11  réglages GitHub de CHECKLIST ; G6 non applicable hors dépôt public, et en privé
+          G1–G5 nomment l'offre ou l'option GitHub requise
+
+Usage :  nstack doctor [--root RACINE]
+Sortie :  0 si tout est vérifié et conforme, 1 sinon.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from pathlib import Path
+
+import yaml
+
+from napkinstack import __version__
+from napkinstack.project import ANSWERS
+
+OK, ECART, INCONNU, SANS_OBJET = "OK", "ÉCHEC", "NON VÉRIFIÉ", "NON APPLICABLE"
+API_VERSION = "2026-03-10"
+MARQUEUR = "<Une phrase : ce que fait ce projet.>"
+JOBS = ("Fitness functions", "Périmètre et budget de revue", "Hooks et secrets")
+ACTIONS_TIERCES = ("astral-sh/setup-uv",)  # actions hors GitHub des workflows du squelette
+LABELS = ("cross-module", "hors-budget")
+PUBLIEE = re.compile(r"v\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?")
+
+RULESET = "Settings → Rules → Rulesets, branche main"
+SECURITE = "Settings → Advanced Security"
+ACTIONS = "Settings → Actions → General"
+
+CHECKLIST = [  # (règle, réglage, action)
+    ("G1", "Pull request obligatoire : aucun push direct sur main",
+     f"{RULESET} : exiger une pull request avant la fusion"),
+    ("G2", "Au moins 1 relecture approuvée", f"{RULESET} : au moins 1 approbation requise"),
+    ("G3", "Revue des CODEOWNERS obligatoire", f"{RULESET} : exiger la revue des Code Owners"),
+    ("G4", "Checks obligatoires : " + ", ".join(f"`{job}`" for job in JOBS),
+     f"{RULESET} : exiger ces checks de statut"),
+    ("G5", "Secret Protection et protection au push",
+     f"{SECURITE} : activer Secret Protection et la protection au push"),
+    ("G6", "Signalement privé de vulnérabilités, dépôt public (canal de `SECURITY.md`)",
+     f"{SECURITE} : activer le signalement privé de vulnérabilités"),
+    ("G7", "Actions autorisées : celles de GitHub, plus " + ", ".join(f"`{a}`" for a in ACTIONS_TIERCES),
+     f"{ACTIONS} : n'autoriser que les actions de GitHub et " + ", ".join(f"{a}@*" for a in ACTIONS_TIERCES)),
+    ("G8", "Actions épinglées par SHA obligatoires", f"{ACTIONS} : exiger l'épinglage des actions par SHA"),
+    ("G9", "Approbation des workflows pour tout contributeur externe",
+     f"{ACTIONS} : exiger l'approbation pour tous les contributeurs externes"),
+    ("G10", "Jeton des workflows en lecture seule ; Actions ne crée ni n'approuve de PR",
+     f"{ACTIONS} : permissions des workflows en lecture, sans création ni approbation de PR"),
+    ("G11", "Labels " + " et ".join(f"`{label}`" for label in LABELS),
+     "Issues → Labels : créer " + " et ".join(LABELS)),
+]
+
+# Réglages propres aux dépôts publics, et réglages qu'un dépôt privé paie (doc GitHub, 2026-09-15).
+PUBLIC_SEULEMENT = {"G6": "le signalement privé de vulnérabilités n'existe que pour un dépôt public ; "
+                          "indiquer un canal interne dans SECURITY.md"}
+OFFRE_PRIVEE = dict.fromkeys(("G1", "G2", "G3", "G4"),
+                             "Dépôt privé : les rulesets exigent l'offre GitHub Team (organisation) ou Pro "
+                             "(compte personnel) ; sans elle, rien ne bloque la fusion.")
+OFFRE_PRIVEE["G5"] = ("Dépôt privé : Secret Protection est une option payante ; sans elle, seuls les hooks "
+                      "et la CI cherchent les secrets.")
+
+
+class NonVerifie(Exception):
+    """Réglage illisible : jeton, permission ou réseau."""
+
+
+class GitHub:
+    """Lectures de l'API REST de GitHub, mises en cache ; jamais d'écriture."""
+
+    def __init__(self, repo: str, token: str, api: str) -> None:
+        self.repo, self.token, self.api = repo, token, api.rstrip("/")
+        self.cache: dict[str, tuple[int, object]] = {}
+
+    def get(self, path: str, missing: bool = False):
+        """JSON de /repos/<dépôt><path> ; None si `missing` et 404 ; NonVerifie sinon."""
+        if path not in self.cache:
+            request = urllib.request.Request(f"{self.api}/repos/{self.repo}{path}", headers={
+                "Accept": "application/vnd.github+json", "Authorization": f"Bearer {self.token}",
+                "X-GitHub-Api-Version": API_VERSION, "User-Agent": f"nstack/{__version__}"})
+            try:
+                with urllib.request.urlopen(request, timeout=10) as response:
+                    self.cache[path] = (response.status, json.load(response))
+            except urllib.error.HTTPError as error:
+                self.cache[path] = (error.code, None)
+            except (OSError, ValueError):
+                self.cache[path] = (0, None)
+        status, data = self.cache[path]
+        if status == 200:
+            return data
+        if status == 404 and missing:
+            return None
+        if status == 0:
+            raise NonVerifie(f"API GitHub injoignable ({self.api})")
+        if status == 401:
+            raise NonVerifie("jeton refusé (HTTP 401)")
+        raise NonVerifie(f"lecture refusée (HTTP {status}) : dépôt inaccessible, ou permission "
+                         "Administration : lecture absente du jeton")
+
+
+def _regle(gh: GitHub, kind: str) -> dict | None:
+    return next((rule for rule in gh.get("/rules/branches/main") if rule.get("type") == kind), None)
+
+
+def _parametres(gh: GitHub, kind: str) -> dict:
+    return (_regle(gh, kind) or {}).get("parameters") or {}
+
+
+def _securite(gh: GitHub) -> bool:
+    analysis = gh.get("").get("security_and_analysis")
+    if analysis is None:
+        raise NonVerifie("réglages de sécurité non visibles : permission Administration : lecture "
+                         "absente du jeton")
+    return all((analysis.get(key) or {}).get("status") == "enabled"
+               for key in ("secret_scanning", "secret_scanning_push_protection"))
+
+
+def _actions_autorisees(gh: GitHub) -> bool:
+    if gh.get("/actions/permissions").get("allowed_actions") != "selected":
+        return False
+    selection = gh.get("/actions/permissions/selected-actions")
+    patterns = selection.get("patterns_allowed") or []
+    return bool(selection.get("github_owned_allowed")) and all(
+        any(fnmatch.fnmatch(f"{action}@0", pattern) for pattern in patterns) for action in ACTIONS_TIERCES)
+
+
+def _workflows(gh: GitHub) -> bool:
+    permissions = gh.get("/actions/permissions/workflow")
+    return (permissions.get("default_workflow_permissions") == "read"
+            and permissions.get("can_approve_pull_request_reviews") is False)
+
+
+VERIFICATIONS: dict[str, Callable[[GitHub], bool]] = {
+    "G1": lambda gh: _regle(gh, "pull_request") is not None,
+    "G2": lambda gh: _parametres(gh, "pull_request").get("required_approving_review_count", 0) >= 1,
+    "G3": lambda gh: _parametres(gh, "pull_request").get("require_code_owner_review") is True,
+    "G4": lambda gh: set(JOBS) <= {check.get("context") for check in _parametres(
+        gh, "required_status_checks").get("required_status_checks", [])},
+    "G5": _securite,
+    "G6": lambda gh: gh.get("/private-vulnerability-reporting").get("enabled") is True,
+    "G7": _actions_autorisees,
+    "G8": lambda gh: gh.get("/actions/permissions").get("sha_pinning_required") is True,
+    "G9": lambda gh: gh.get("/actions/permissions/fork-pr-contributor-approval").get(
+        "approval_policy") == "all_external_contributors",
+    "G10": _workflows,
+    "G11": lambda gh: all(gh.get(f"/labels/{label}", missing=True) is not None for label in LABELS),
+}
+
+
+def _poste(root: Path, answers: dict) -> list[tuple[str, str, str, str]]:
+    commit = str(answers.get("_commit") or "")
+    projet = commit.removeprefix("v")
+    installer = f'uv tool install "napkinstack=={projet}" --with-executables-from pre-commit'
+    resultats = []
+
+    if not PUBLIEE.fullmatch(commit):
+        l1 = (INCONNU, f"Raison : le projet vient d'une version non publiée ({commit or 'inconnue'}).")
+    elif projet != __version__:
+        l1 = (ECART, f"nstack {__version__} installé, projet en {projet} (PDR-0001 R3).\nAction : {installer}")
+    else:
+        l1 = (OK, "")
+    resultats.append(("L1", "nstack à la version du projet", *l1))
+
+    absents = [outil for outil in ("git", "pre-commit") if shutil.which(outil) is None]
+    resultats.append(("L2", "git et pre-commit disponibles", ECART if absents else OK,
+                      f"Absents : {', '.join(absents)}.\nAction : installer git ; pre-commit vient avec "
+                      f"{installer}" if absents else ""))
+
+    if "git" in absents:
+        l3 = (INCONNU, "Raison : git absent.")
+    else:
+        hook = subprocess.run(["git", "rev-parse", "--git-path", "hooks/pre-commit"], cwd=root,
+                              capture_output=True, text=True)
+        chemin = root / hook.stdout.strip()
+        installe = (hook.returncode == 0 and chemin.is_file()
+                    and "generated by pre-commit" in chemin.read_text(errors="replace"))
+        l3 = (OK, "") if installe else (ECART, "Action : pre-commit install")
+    resultats.append(("L3", "Hooks pre-commit installés", *l3))
+
+    produit = (root / "PRODUCT.md").exists()
+    resultats.append(("L4", "PRODUCT.md absent", ECART if produit else OK,
+                      "PRODUCT.md décrit le développement de NapkinStack (PDR-0001 R6).\n"
+                      "Action : le supprimer." if produit else ""))
+
+    readme = root / "README.md"
+    marque = readme.is_file() and MARQUEUR in readme.read_text(encoding="utf-8", errors="replace")
+    resultats.append(("L5", "README personnalisé", ECART if marque else OK,
+                      f"README.md contient encore « {MARQUEUR} ».\n"
+                      "Action : écrire la phrase qui présente le projet." if marque else ""))
+    return resultats
+
+
+def _prive(gh: GitHub) -> bool:
+    """Dépôt non public (privé ou interne) ; visibilité illisible : traité comme public."""
+    try:
+        return (gh.get("").get("visibility") or "public") != "public"
+    except NonVerifie:
+        return False
+
+
+def _afficher(regle: str, reglage: str, statut: str, detail: str) -> None:
+    print(f"  {statut:<14} [{regle}] {reglage}")
+    for ligne in detail.splitlines():
+        print(f"                 {ligne}")
+
+
+def run(root: Path) -> int:
+    if not (root / ANSWERS).is_file():
+        print(f"ÉCHEC [doctor] {ANSWERS} introuvable dans {root} : ce dossier n'est pas un projet "
+              "créé par nstack init.\n      Action : lancer la commande à la racine du projet, "
+              "ou préciser --root.")
+        return 1
+    answers = yaml.safe_load((root / ANSWERS).read_text(encoding="utf-8")) or {}
+
+    resultats = _poste(root, answers)
+    print("Poste")
+    for resultat in resultats:
+        _afficher(*resultat)
+
+    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    print(f"\nGitHub : {answers.get('github_repo')}")
+    if token:
+        gh = GitHub(str(answers.get("github_repo")), token,
+                    os.environ.get("GITHUB_API_URL") or "https://api.github.com")
+    else:
+        gh = None
+        print("  Aucun jeton (GH_TOKEN ou GITHUB_TOKEN) : aucun réglage n'est lu.\n"
+              "  Action : fournir un jeton à grain fin limité au dépôt, permission "
+              "Administration : lecture, puis relancer.")
+    prive = gh is not None and _prive(gh)
+    for regle, reglage, action in CHECKLIST:
+        if gh is None:
+            statut, detail = INCONNU, ""
+        elif prive and regle in PUBLIC_SEULEMENT:
+            statut, detail = SANS_OBJET, f"Raison : {PUBLIC_SEULEMENT[regle]}."
+        else:
+            try:
+                statut, detail = (OK, "") if VERIFICATIONS[regle](gh) else (ECART, f"Action : {action}")
+            except NonVerifie as raison:
+                statut, detail = INCONNU, f"Raison : {raison}"
+            if prive and statut != OK and regle in OFFRE_PRIVEE:
+                detail += f"\n{OFFRE_PRIVEE[regle]}"
+        resultats.append((regle, reglage, statut, detail))
+        _afficher(regle, reglage, statut, detail)
+
+    ecarts = sum(statut == ECART for _, _, statut, _ in resultats)
+    inconnus = sum(statut == INCONNU for _, _, statut, _ in resultats)
+    sans_objet = sum(statut == SANS_OBJET for _, _, statut, _ in resultats)
+    suffixe = f", {sans_objet} non applicable(s)" if sans_objet else ""
+    if not ecarts and not inconnus:
+        print(f"\nnstack doctor : conforme{suffixe}.")
+        return 0
+    print(f"\nnstack doctor : {ecarts} écart(s), {inconnus} non vérifié(s){suffixe}.\nLes workflows informent ; "
+          "ce sont les réglages GitHub qui bloquent, et ils ne se copient pas avec le projet.")
+    return 1

napkinstack/fitness/boundaries.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Fitness function 2 — Frontières entre modules.
+
+Compare le graphe DÉCLARÉ (manifests) au graphe RÉEL (références dans le code),
+puis vérifie l'absence de cycles (docs/os/02-modules.md §8, docs/os/07-gouvernance.md §3).
+
+Contrôles :
+  B1  aucune référence vers un module non déclaré dans `consumes`
+  B2  aucun import direct de l'implémentation d'un autre module (src/, internal/)
+  B3  aucune dépendance circulaire entre modules
+  B4  dépendance déclarée mais jamais utilisée (avertissement)
+  B5  aucun accès direct aux données d'un autre module (tables déclarées ailleurs)
+
+DÉTECTION — à calibrer pour ton langage.
+La détection est textuelle et volontairement simple : on cherche, dans les lignes
+ressemblant à un import, les jetons identifiant un autre module. Deux sources :
+  - le chemin du module   ("modules/billing", "@org/billing", "org.billing")
+  - le champ `code_name` du manifest, s'il diffère du nom de dossier.
+Ajuste IMPORT_HINTS et SOURCE_SUFFIXES selon ta stack. Un faux positif se corrige
+en déclarant la dépendance ; un faux négatif se corrige en enrichissant les motifs.
+
+Usage :  nstack boundaries [--root RACINE]
+"""
+
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+MODULE_DIRS = ["modules", "services", "apps", "packages"]
+SOURCE_SUFFIXES = {
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt",
+    ".rb", ".php", ".cs", ".swift", ".scala", ".ex", ".exs",
+}
+SKIP_DIRS = {"node_modules", "dist", "build", "target", "vendor", ".git",
+             "__pycache__", ".venv", "venv", "coverage", "generated"}
+IMPORT_HINTS = re.compile(
+    r"\b(import|from|require|use|using|include|#include|extern crate|go:import)\b|"
+    r"^\s*(import|from)\s", re.IGNORECASE
+)
+INTERNAL_MARKERS = ("/src/", "/internal/", "/lib/internal", "\\src\\")
+
+failures: list[str] = []
+warnings: list[str] = []
+
+
+def fail(rule: str, where: str, message: str) -> None:
+    failures.append(f"[{rule}] {where}\n      {message}")
+
+
+def warn(rule: str, where: str, message: str) -> None:
+    warnings.append(f"[{rule}] {where}\n      {message}")
+
+
+def load_modules(root: Path) -> dict[str, dict]:
+    modules: dict[str, dict] = {}
+    for base in MODULE_DIRS:
+        d = root / base
+        if not d.is_dir():
+            continue
+        for manifest in sorted(d.glob("*/MANIFEST.yaml")):
+            try:
+                data = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+            except yaml.YAMLError:
+                continue  # signalé par nstack manifests (M2)
+            mod = data.get("module") if isinstance(data, dict) else None
+            if not isinstance(mod, dict):
+                continue  # signalé par nstack manifests (M2)
+            consumes = data.get("consumes") if isinstance(data.get("consumes"), list) else []
+            section = data.get("data") if isinstance(data.get("data"), dict) else {}
+            owns = section.get("owns") if isinstance(section.get("owns"), list) else []
+            name = mod.get("name") or manifest.parent.name
+            modules[name] = {
+                "path": manifest.parent,
+                "dirname": manifest.parent.name,
+                "code_name": mod.get("code_name") or name,
+                "declared": {c.get("module") for c in consumes if isinstance(c, dict) and c.get("module")},
+                "owns_data": set(owns),
+                "raw": data,
+            }
+    return modules
+
+
+def iter_sources(module_path: Path):
+    for path in module_path.rglob("*"):
+        if not path.is_file() or path.suffix not in SOURCE_SUFFIXES:
+            continue
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        yield path
+
+
+def tokens_for(other: dict) -> list[str]:
+    """Jetons qui identifient un autre module dans une ligne d'import."""
+    return list({
+        f"modules/{other['dirname']}",
+        f"services/{other['dirname']}",
+        f"packages/{other['dirname']}",
+        f"/{other['code_name']}/",
+        f"@{other['code_name']}",
+        f".{other['code_name']}.",
+    })
+
+
+def analyse(root: Path, modules: dict[str, dict]) -> dict[str, set[str]]:
+    real: dict[str, set[str]] = {name: set() for name in modules}
+
+    for name, mod in modules.items():
+        for source in iter_sources(mod["path"]):
+            try:
+                lines = source.read_text(encoding="utf-8", errors="ignore").splitlines()
+            except OSError:
+                continue
+            for lineno, line in enumerate(lines, 1):
+                if not IMPORT_HINTS.search(line):
+                    continue
+                for other_name, other in modules.items():
+                    if other_name == name:
+                        continue
+                    if not any(tok in line for tok in tokens_for(other)):
+                        continue
+                    real[name].add(other_name)
+                    rel = source.relative_to(root)
+
+                    # B2 — import de l'implémentation interne
+                    if any(marker in line.replace("\\", "/") for marker in INTERNAL_MARKERS):
+                        fail("B2", f"{rel}:{lineno}",
+                             f"'{name}' importe l'implémentation interne de '{other_name}'. "
+                             f"Passer par son contrat (docs/os/03-contrats.md).")
+                    # B1 — dépendance non déclarée
+                    elif other_name not in mod["declared"]:
+                        fail("B1", f"{rel}:{lineno}",
+                             f"'{name}' référence '{other_name}' sans le déclarer dans "
+                             f"consumes du MANIFEST. Déclarer le contrat consommé, "
+                             f"ou supprimer la dépendance.")
+
+    # B5 — accès aux données d'autrui
+    for name, mod in modules.items():
+        others_tables = {t: o for o, m in modules.items() if o != name
+                         for t in m["owns_data"]}
+        if not others_tables:
+            continue
+        for source in iter_sources(mod["path"]):
+            text = source.read_text(encoding="utf-8", errors="ignore").lower()
+            for table, owner in others_tables.items():
+                if re.search(rf"\b(from|join|into|update|table)\s+[\"'`\[]?{re.escape(table.lower())}\b", text):
+                    fail("B5", str(source.relative_to(root)),
+                         f"'{name}' accède à la table '{table}' possédée par '{owner}'. "
+                         f"Couplage par la base (docs/os/08-qualite.md §8).")
+                    break
+
+    # B4 — déclaré mais inutilisé
+    for name, mod in modules.items():
+        for declared in mod["declared"]:
+            if declared in modules and declared not in real[name]:
+                warn("B4", name,
+                     f"dépendance déclarée vers '{declared}' mais aucune utilisation détectée. "
+                     f"Nettoyer le MANIFEST, ou ajuster les motifs de détection.")
+    return real
+
+
+def find_cycles(graph: dict[str, set[str]]) -> list[list[str]]:
+    cycles, stack, visiting, visited = [], [], set(), set()
+
+    def walk(node: str) -> None:
+        if node in visiting:
+            cycles.append(stack[stack.index(node):] + [node])
+            return
+        if node in visited:
+            return
+        visiting.add(node)
+        stack.append(node)
+        for nxt in sorted(graph.get(node, ())):
+            walk(nxt)
+        stack.pop()
+        visiting.discard(node)
+        visited.add(node)
+
+    for node in sorted(graph):
+        walk(node)
+    return cycles
+
+
+def run(root: Path) -> int:
+    failures.clear()
+    warnings.clear()
+    modules = load_modules(root)
+
+    if len(modules) < 2:
+        print(f"{len(modules)} module(s) : pas de frontière à vérifier.")
+        return 0
+
+    real = analyse(root, modules)
+
+    for cycle in find_cycles(real):
+        fail("B3", " → ".join(cycle),
+             "dépendance circulaire : ces modules sont devenus inséparables "
+             "(docs/os/02-modules.md §9).")
+
+    print(f"Modules analysés : {len(modules)}")
+    print("Graphe réel détecté :")
+    for name in sorted(real):
+        deps = ", ".join(sorted(real[name])) or "—"
+        print(f"  {name} → {deps}")
+
+    for w in warnings:
+        print(f"  AVERTISSEMENT {w}")
+    for f in failures:
+        print(f"  ÉCHEC {f}")
+
+    if failures:
+        print(f"\n{len(failures)} violation(s) de frontière.")
+        return 1
+    print("Frontières : conformes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run(Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()))