@trycore/spec-build-harness 0.11.1 → 0.13.0

package/scripts/lib/graph-bundle.py

@@ -14,8 +14,17 @@ como string POR ÉPICA (las `release_lines` de la entrada se pliegan aquí). As
 objeto sirve para la pantalla de import del grafo y para embeberse como sección `graph`
 del bundle de estado (`trycore-build migrate`).
 
+[issue #56] Las dependencias entre épicas viven como PROSA en `docs/03-backlog/epicas.md`
+(`**Depende de**: EP-001 (…)`), y delegar su lectura al modelo las dejó VACÍAS en el piloto
+(41/41 épicas con `depends_on: []`, Lienzo sin una sola arista). `--from-docs` extrae ese
+grafo de forma DETERMINISTA — regex de códigos `EP-…` sobre el campo `Depende de` de cada
+sección de épica, excluyendo la propia — y lo une a lo que traiga el JSON de entrada. Si la
+épica declara el campo estructurado `depende_de: [EP-001, …]`, ese gana sobre la prosa.
+
 Uso:
     python3 graph-bundle.py < epics.json > bundle.json      # avisos por stderr
+    python3 graph-bundle.py --from-docs docs/03-backlog/epicas.md < epics.json > bundle.json
+    python3 graph-bundle.py --print-deps docs/03-backlog/epicas.md   # solo el grafo extraído
 
 Entrada (stdin, JSON — formato de discovery, sin cambios):
     {"project_ref": "…",
@@ -27,9 +36,12 @@ Salida (stdout, JSON): el bundle normalizado y DETERMINISTA (orden estable por c
 los problemas no bloquean: se listan como avisos en stderr y en `warnings` del bundle, con
 el criterio del arnés — nada se pierde en silencio, nada bloquea la preparación.
 
-Códigos de salida: 0 = bundle generado (con o sin avisos) · 1 = entrada ilegible.
+Códigos de salida: 0 = bundle generado (con o sin avisos) · 1 = entrada ilegible
+(incluye una ruta `--from-docs` que no se puede leer: se pidió extraer y no se pudo, y un
+grafo sin aristas no falla solo — empobrece en silencio, que es justo lo que causó #56).
 """
 import json
+import re
 import sys
 import datetime
 
@@ -43,8 +55,128 @@ def norm_list(v):
     return [x for x in v if isinstance(x, str)] if isinstance(v, list) else []
 
 
+# ── Extractor determinista de dependencias desde los docs de discovery [issue #56] ──
+# Códigos de épica: EP-001 y también los compuestos del estilo EP-OR-08.
+RE_CODIGO = re.compile(r"\bEP-(?:[A-Za-z]{1,6}-)?\d{1,4}\b")
+# Encabezado de sección de épica: `## EP-001 — Título` (cualquier nivel).
+RE_ENCABEZADO = re.compile(r"^\s{0,3}(#{1,6})\s+(.*)$")
+# El campo en prosa que escribe la metodología: `**Depende de**: …` (puede ir a mitad de
+# línea, p. ej. `**Anexo A**: Fase 3 · **Depende de**: EP-002`).
+RE_DEPENDE_DE = re.compile(r"depende\s+de", re.IGNORECASE)
+# El campo estructurado (frontmatter o cuerpo): `depende_de: [EP-001, EP-002]`.
+RE_DEPENDE_DE_ESTRUCTURADO = re.compile(r"^\s*(?:-\s*)?depende_de\s*:", re.IGNORECASE)
+# Fin del párrafo del campo: encabezado, regla horizontal, viñeta/cita/tabla o campo nuevo.
+RE_FIN_DE_CAMPO = re.compile(r"^\s*(?:#{1,6}\s|-{3,}\s*$|\*{3,}\s*$|[-*+>|]\s|\*\*)")
+
+
+def extraer_dependencias(texto):
+    """Devuelve ({codigo: [deps ordenadas]}, {códigos con sección}, avisos).
+
+    Solo entran las épicas que DECLARAN el campo (en prosa o estructurado): "no lo declara"
+    y "declara que no depende de nada" son cosas distintas y ninguna se inventa aquí.
+    """
+    avisos = []
+    lineas = texto.splitlines()
+    # (código de la épica, línea donde abre su sección)
+    secciones = []
+    for i, linea in enumerate(lineas):
+        m = RE_ENCABEZADO.match(linea)
+        if not m:
+            continue
+        codigos = RE_CODIGO.findall(m.group(2))
+        if codigos:
+            secciones.append((codigos[0], i))
+    if not secciones:
+        avisos.append("no se reconoció ninguna sección de épica en los docs "
+                      "(se esperaban encabezados del estilo `## EP-001 — Título`)")
+        return {}, set(), avisos
+
+    deps = {}
+    for n, (codigo, inicio) in enumerate(secciones):
+        fin = secciones[n + 1][1] if n + 1 < len(secciones) else len(lineas)
+        cuerpo = lineas[inicio + 1:fin]
+        prosa, estructurado = None, None
+        for j, linea in enumerate(cuerpo):
+            if estructurado is None and RE_DEPENDE_DE_ESTRUCTURADO.match(linea):
+                estructurado = RE_CODIGO.findall(linea.split(":", 1)[1])
+                continue
+            if prosa is not None:
+                continue
+            m = RE_DEPENDE_DE.search(linea)
+            if not m:
+                continue
+            # El campo puede continuar en las líneas siguientes hasta el fin del párrafo.
+            trozos = [linea[m.end():]]
+            for siguiente in cuerpo[j + 1:]:
+                if not siguiente.strip() or RE_FIN_DE_CAMPO.match(siguiente):
+                    break
+                trozos.append(siguiente)
+            prosa = RE_CODIGO.findall(" ".join(trozos))
+        # El campo estructurado es determinista: gana sobre la heurística de la prosa.
+        encontrado = estructurado if estructurado is not None else prosa
+        if encontrado is None:
+            continue
+        deps[codigo] = sorted({c for c in encontrado if c != codigo})
+    return deps, {c for c, _ in secciones}, avisos
+
+
+def leer_dependencias_de_docs(ruta):
+    """Lee el fichero de épicas; lanza IOError/OSError si no se puede (rc 1 arriba)."""
+    with open(ruta, encoding="utf-8") as fh:
+        return extraer_dependencias(fh.read())
+
+
+def parsear_argumentos(argv):
+    """({from_docs, print_deps}, error) — sin dependencias, mismo estilo que el resto."""
+    opciones = {"from_docs": None, "print_deps": None}
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg in ("--from-docs", "--print-deps"):
+            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
+                return opciones, "%s exige la ruta del fichero de épicas" % arg
+            opciones["from_docs" if arg == "--from-docs" else "print_deps"] = argv[i + 1]
+            i += 2
+            continue
+        return opciones, "opción desconocida: %s" % arg
+    if opciones["from_docs"] and opciones["print_deps"]:
+        # Ignorar una de las dos en silencio es exactamente el error que corrige #56.
+        return opciones, "--from-docs y --print-deps son excluyentes"
+    return opciones, None
+
+
 def main():
     avisos = []
+    opciones, error = parsear_argumentos(sys.argv[1:])
+    if error:
+        print("graph-bundle: %s" % error, file=sys.stderr)
+        return 1
+
+    # `--print-deps`: solo el grafo extraído (diagnóstico; no toca stdin ni arma bundle).
+    if opciones["print_deps"]:
+        try:
+            deps, _, avisos_docs = leer_dependencias_de_docs(opciones["print_deps"])
+        except (IOError, OSError) as e:
+            print("graph-bundle: no se pudo leer %s: %s" % (opciones["print_deps"], e),
+                  file=sys.stderr)
+            return 1
+        json.dump(deps, sys.stdout, indent=2, ensure_ascii=False, sort_keys=True)
+        sys.stdout.write("\n")
+        for a in avisos_docs:
+            print("aviso: %s" % a, file=sys.stderr)
+        return 0
+
+    deps_docs = None
+    if opciones["from_docs"]:
+        try:
+            deps_docs, secciones_docs, avisos_docs = \
+                leer_dependencias_de_docs(opciones["from_docs"])
+        except (IOError, OSError) as e:
+            print("graph-bundle: no se pudo leer %s: %s" % (opciones["from_docs"], e),
+                  file=sys.stderr)
+            return 1
+        avisos.extend(avisos_docs)
+
     try:
         raw = json.load(sys.stdin)
     except Exception as e:
@@ -113,6 +245,36 @@ def main():
             epica["docs_ref"] = e["docs_ref"]
         epicas[code] = epica
 
+    # [issue #56] Las dependencias de los docs se UNEN a las declaradas: el extractor es la
+    # fuente fiable, y lo que ya venía en el JSON no se pierde (se avisa si no está en docs).
+    if deps_docs is not None:
+        aristas = 0
+        for code, e in epicas.items():
+            if code not in deps_docs:
+                if code in secciones_docs:
+                    avisos.append("%s tiene sección en %s pero no declara el campo "
+                                  "`Depende de`: sus dependencias quedan como vinieran en el "
+                                  "JSON" % (code, opciones["from_docs"]))
+                else:
+                    avisos.append("%s no aparece como sección de épica en %s: sus "
+                                  "dependencias no se pudieron extraer de los docs"
+                                  % (code, opciones["from_docs"]))
+                continue
+            solo_json = [d for d in e["depends_on"] if d not in deps_docs[code]]
+            if solo_json:
+                avisos.append("%s: %s viene del JSON de entrada pero no del campo `Depende de` "
+                              "de los docs: verifica cuál manda"
+                              % (code, ", ".join(solo_json)))
+            e["depends_on"] = sorted(set(e["depends_on"]) | set(deps_docs[code]))
+            aristas += len(e["depends_on"])
+        for code in sorted(deps_docs):
+            if code not in epicas:
+                avisos.append("%s está en %s pero no en el JSON de entrada: el grafo del hub "
+                              "quedaría sin esa épica" % (code, opciones["from_docs"]))
+        print("info: dependencias extraídas de %s -> %d épicas con campo `Depende de`, "
+              "%d aristas en el grafo" % (opciones["from_docs"], len(deps_docs), aristas),
+              file=sys.stderr)
+
     for code, e in epicas.items():
         for dep in e["depends_on"]:
             if dep not in epicas:
@@ -167,6 +329,8 @@ def main():
         "generated_at": datetime.datetime.now(datetime.timezone.utc)
                         .strftime("%Y-%m-%dT%H:%M:%SZ"),
         "generated_by": "trycore-build-harness/graph-bundle.py",
+        "depends_on_source": ("docs:%s" % opciones["from_docs"]) if deps_docs is not None
+                             else "input",
         "epics": [epicas[c] for c in sorted(epicas)],
         "warnings": avisos,
     }