@imolko/ultra-agent 0.2.0-beta → 1.0.0

package/scripts/verify-adr-consistency.py

@@ -1,250 +0,0 @@
-#!/usr/bin/env python3
-"""Gate de consistencia del registro ADR (ADR-0000).
-
-Valida cinco reglas y sale con código 0 solo si no hay violaciones:
-  - jerarquia    los ADRs no referencian tiers prohibidos (A solo cita A; T cita A y T;
-                 P cita A y P). Detecta tanto enlaces markdown como citas en texto plano a
-                 IDs `<PREFIJO>-NNN`: una cita con un prefijo no permitido para el tier —o
-                 con cualquier otro prefijo, incluidos G y PJ— es una violación, porque
-                 ningún ADR A/T/P referencia el tier de proyecto. Una misma referencia
-                 prohibida se reporta una sola vez aunque aparezca como enlace y como ID.
-  - enlaces      todos los enlaces markdown internos (relativos, *.md) resuelven a un
-                 archivo existente.
-  - frontmatter  el título H1 sigue `# <TIER>-<NNN>: Título` y los campos `originally` /
-                 `Enriquecido desde` usan la ortografía exacta.
-  - indices      cada ADR aparece en el índice de su tier y el índice no lista ADRs
-                 inexistentes.
-  - hardcoded    los ADRs activos no duplican listas cuya fuente canónica vive en el
-                 paquete (skills → @imolko/ultra-agent) ni en docs/agents/ (punteros).
-
-Uso: python3 scripts/verify-adr-consistency.py
-"""
-
-import re
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-ADR_DIR = ROOT / "docs" / "adr"
-
-TIER_DIRS = {
-    "A": ADR_DIR / "foundational",
-    "T": ADR_DIR / "typescript",
-    "P": ADR_DIR / "python",
-}
-
-H1_RE = re.compile(r"^# (A|T|P)-\d{3}: .+")
-ORIGINALLY_RE = re.compile(r"^\*\*originally\*\*:", flags=re.MULTILINE)
-ORIGINALLY_WRONG_RE = re.compile(r"^\*\*[Oo]riginally\*\*:", flags=re.MULTILINE)
-ENRICHED_RE = re.compile(r"^\*\*Enriquecido desde\*\*:", flags=re.MULTILINE)
-ENRICHED_WRONG_RE = re.compile(r"^\*\*[Ee]nriquecido [Dd]esde\*\*:", flags=re.MULTILINE)
-
-# Anchors caducados: la fuente canónica de los skills pasó al paquete y el hub de
-# punteros pasó a docs/agents/ (A-052). Un ADR activo no debe repetirlos.
-STALE_ANCHORS = (".pi/skills/", ".pi/repo-config.md")
-
-violations = []
-
-
-def report(rule: str, message: str) -> None:
-    violations.append(f"[{rule}] {message}")
-
-
-def is_active_adr(text: str) -> bool:
-    match = re.search(r"^\*\*Estado\*\*: ?(.+)$", text, flags=re.MULTILINE)
-    if not match:
-        return True
-    state = match.group(1).strip()
-    return state not in ("Reemplazado", "Deprecado")
-
-
-def tier_adr_files(tier: str):
-    return sorted(TIER_DIRS[tier].glob(f"{tier}-*.md"))
-
-
-def link_targets(text: str):
-    """Devuelve los destinos de los enlaces markdown inline `](dest)`. """
-    return re.findall(r"\]\(([^)]+)\)", text)
-
-
-def resolve_link(adir_file: Path, target: str):
-    """Resuelve un target de enlace relativo contra el directorio del ADR."""
-    target = target.strip()
-    if target.startswith(("<", ">")) or "://" in target or target.startswith("#"):
-        return None  # URL externa, autolink o ancla pura — fuera del gate
-    # Ignorar fragmentos (#ancla)
-    target = target.split("#", 1)[0]
-    if not target:
-        return None
-    if not target.endswith(".md"):
-        return None
-    return (adir_file.parent / target).resolve()
-
-
-def target_tier(resolved: Path):
-    """Clasifica un archivo resuelto en su tier (o None si está fuera del registro)."""
-    try:
-        rel = resolved.relative_to(ADR_DIR)
-    except ValueError:
-        return None
-    parts = rel.parts
-    if len(parts) >= 2:
-        if parts[0] == "foundational":
-            return "A"
-        if parts[0] == "typescript":
-            return "T"
-        if parts[0] == "python":
-            return "P"
-    if rel.name.startswith("ADR-0000") or rel.name == "index.md":
-        return "meta"
-    return "project"
-
-
-ALLOWED_TARGETS = {
-    "A": {"A", "meta"},
-    "T": {"A", "T", "meta"},
-    "P": {"A", "P", "meta"},
-}
-
-# Citas en texto plano a un ID de ADR. Una a dos letras mayúsculas evita falsos
-# positivos con identificadores de tres letras (ISO-8601, RFC-2119, SHA-256).
-PLAIN_ID_RE = re.compile(r"\b([A-Z]{1,2})-\d{3}\b")
-
-# Destino de un enlace markdown inline `](destino)`. Se elimina antes del escaneo
-# de texto plano para que una referencia no se reporte también como cita.
-LINK_TARGET_RE = re.compile(r"\]\([^)]*\)")
-
-# Enlace markdown inline completo: etiqueta y destino. La etiqueta puede citar el
-# ID cuando el destino no lo contiene (p. ej. `[T-001](../typescript/index.md)`).
-LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]*)\)")
-
-
-def rule_jerarquia() -> None:
-    for tier, allowed in ALLOWED_TARGETS.items():
-        allowed_prefixes = {t for t in allowed if t in TIER_DIRS}
-        for adr in tier_adr_files(tier):
-            text = adr.read_text(encoding="utf-8")
-            reported_ids = set()
-
-            for label, target in LINK_RE.findall(text):
-                resolved = resolve_link(adr, target)
-                if resolved is None:
-                    continue
-                resolved_tier = target_tier(resolved)
-                if resolved_tier is None or resolved_tier in allowed:
-                    continue
-                # Los IDs citados por el enlace —en la etiqueta o en el destino—
-                # quedan cubiertos por esta violación y no se reportan otra vez.
-                for match in PLAIN_ID_RE.finditer(f"{label} {target}"):
-                    reported_ids.add(match.group(0))
-                report(
-                    "jerarquia",
-                    f"{adr.relative_to(ROOT)} referencia al tier {resolved_tier} ({target}), prohibido para el tier {tier}",
-                )
-
-            plain_text = LINK_TARGET_RE.sub("", text)
-            for match in PLAIN_ID_RE.finditer(plain_text):
-                prefix, ident = match.group(1), match.group(0)
-                if prefix in allowed_prefixes or ident in reported_ids:
-                    continue
-                reported_ids.add(ident)
-                report(
-                    "jerarquia",
-                    f"{adr.relative_to(ROOT)} cita en texto plano {ident} (prefijo {prefix}), prohibido para el tier {tier}",
-                )
-
-
-def rule_enlaces() -> None:
-    for md in sorted(ADR_DIR.rglob("*.md")):
-        text = md.read_text(encoding="utf-8")
-        for target in link_targets(text):
-            resolved = resolve_link(md, target)
-            if resolved is None:
-                continue
-            if not resolved.exists():
-                report("enlaces", f"{md.relative_to(ROOT)} enlaza a un archivo inexistente: {target}")
-
-
-def rule_frontmatter() -> None:
-    for tier in ("A", "T", "P"):
-        for adr in tier_adr_files(tier):
-            text = adr.read_text(encoding="utf-8")
-            rel = adr.relative_to(ROOT)
-
-            first_line = text.splitlines()[0] if text.splitlines() else ""
-            if not H1_RE.match(first_line):
-                report("frontmatter", f"{rel}: el título H1 no sigue `# <TIER>-<NNN>: Título`")
-
-            if not ORIGINALLY_RE.search(text):
-                report("frontmatter", f"{rel}: falta el campo `**originally**:` (minúsculas)")
-
-            # Detectar ortografía incorrecta del campo
-            for line in text.splitlines():
-                stripped = line.strip()
-                if ORIGINALLY_WRONG_RE.match(stripped) and not ORIGINALLY_RE.match(stripped):
-                    report("frontmatter", f"{rel}: `originally` debe ir en minúsculas")
-                    break
-
-            for line in text.splitlines():
-                stripped = line.strip()
-                if ENRICHED_WRONG_RE.match(stripped) and not ENRICHED_RE.match(stripped):
-                    report("frontmatter", f"{rel}: el campo opcional debe escribirse `**Enriquecido desde**:`")
-                    break
-
-
-def rule_indices() -> None:
-    for tier in ("A", "T", "P"):
-        index = TIER_DIRS[tier] / "index.md"
-        if not index.exists():
-            report("indices", f"falta el índice del tier {tier}: {index.relative_to(ROOT)}")
-            continue
-
-        index_text = index.read_text(encoding="utf-8")
-        # Enlaces dentro del tier (`./<nombre>.md`)
-        index_targets = {t for t in link_targets(index_text) if t.startswith("./") and t.endswith(".md")}
-
-        adr_files = tier_adr_files(tier)
-        for adr in adr_files:
-            target = f"./{adr.name}"
-            if target not in index_targets:
-                report("indices", f"{adr.relative_to(ROOT)} no aparece en el índice de su tier")
-
-        for target in index_targets:
-            resolved = (TIER_DIRS[tier] / target[2:]).resolve()
-            if not resolved.exists():
-                report("indices", f"el índice {index.relative_to(ROOT)} lista un ADR inexistente: {target}")
-
-
-def rule_hardcoded() -> None:
-    for tier in ("A", "T", "P"):
-        for adr in tier_adr_files(tier):
-            text = adr.read_text(encoding="utf-8")
-            if not is_active_adr(text):
-                continue
-            for anchor in STALE_ANCHORS:
-                if anchor in text:
-                    report(
-                        "hardcoded",
-                        f"{adr.relative_to(ROOT)} duplica el ancla caducada `{anchor}` (fuente canónica: paquete/docs/agents)",
-                    )
-
-
-def main() -> int:
-    rule_jerarquia()
-    rule_enlaces()
-    rule_frontmatter()
-    rule_indices()
-    rule_hardcoded()
-
-    if violations:
-        for v in violations:
-            print(v, file=sys.stderr)
-        print(f"{len(violations)} violación(es) en el registro ADR.", file=sys.stderr)
-        return 1
-
-    print("Registro ADR consistente: 0 violaciones.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())