disensor 0.1.0__py3-none-any.whl

disensor/render.py

@@ -0,0 +1,123 @@
+"""Render de la declaracion de residuo como comentario de PR (Markdown).
+
+Principio de la seccion 9 del protocolo: la declaracion lista residuo, no
+cobertura. El comentario dirige el escrutinio del revisor humano hacia lo que
+el ciclo no pudo cerrar, en lugar de leerse como sello de calidad.
+"""
+from __future__ import annotations
+
+MARCADOR = "<!-- disensor-gate -->"
+
+NOMBRE_CLASE = {
+    "escalado_sin_decision": "Escalado sin decision",
+    "refutacion_del_principal": "Refutacion del modelo principal",
+    "gap_de_ejecucion": "Gap de ejecucion",
+}
+
+NOMBRE_ESTADO = {
+    "incorporado": "incorporados",
+    "deuda_registrada": "deuda registrada",
+    "decision_del_dueno": "decision del dueno",
+    "refutado_verificable": "refutados con evidencia",
+    "refutado_interpretativo": "refutados por criterio",
+    "escalado_abierto": "escalados abiertos",
+}
+
+
+def _linea_item(item: dict, perfil: str) -> str:
+    clase = NOMBRE_CLASE[item["clase"]]
+    atencion = " **(requiere atencion humana)**" if item.get("requiere_atencion_humana") else ""
+    ref = f" (hallazgo {item['ref_hallazgo']})" if item.get("ref_hallazgo") else ""
+    detalle = ""
+    if perfil == "completo" and item.get("descripcion"):
+        detalle = f": {item['descripcion']}"
+    elif item["clase"] == "refutacion_del_principal" and item.get("tipo_refutacion"):
+        detalle = f" ({item['tipo_refutacion']})"
+    elif item["clase"] == "gap_de_ejecucion" and item.get("motivo_gap"):
+        detalle = f" ({item['motivo_gap'].replace('_', ' ')})"
+    evidencia = item.get("evidencia", {})
+    enlace = f" [evidencia]({evidencia['enlace']})" if evidencia.get("enlace") else ""
+    aceptacion = ""
+    if item.get("aceptacion_referente"):
+        ar = item["aceptacion_referente"]
+        aceptacion = f" Aceptado por escrito por {ar['referente']} ({ar['registro']})."
+    return f"- **{clase}**{ref}{detalle}{atencion}{enlace}{aceptacion}"
+
+
+def _resumen_conteos(a: dict) -> str:
+    c = a["metricas"]["conteos"]
+    v = c["validos"]
+    fp = c["falsos_positivos"]
+    partes = []
+    if v["incorporado"]:
+        partes.append(f"{v['incorporado']} incorporados")
+    if v["deuda_registrada"]:
+        partes.append(f"{v['deuda_registrada']} a deuda registrada")
+    if v["decision_del_dueno"]:
+        partes.append(f"{v['decision_del_dueno']} con decision del dueno")
+    if fp["refutado_verificable"]:
+        partes.append(f"{fp['refutado_verificable']} refutados con evidencia")
+    if fp["refutado_interpretativo"]:
+        partes.append(f"{fp['refutado_interpretativo']} refutados por criterio")
+    if c["escalados_abiertos"]:
+        partes.append(f"{c['escalados_abiertos']} escalados abiertos")
+    detalle = ", ".join(partes) if partes else "sin hallazgos"
+    return f"{c['total_hallazgos']} hallazgos: {detalle}."
+
+
+def render_artefacto(a: dict) -> str:
+    ev = a["evento"]
+    ac = a["actores"]
+    lineas = []
+    revisores = ", ".join(f"{r['modelo']} ({r['familia']})" for r in ac["revisores"])
+    confinamientos = ", ".join(
+        f"{r['confinamiento']['modo'].replace('_', ' ')}"
+        + (" verificado" if r["confinamiento"]["verificado"] else " SIN VERIFICAR")
+        for r in ac["revisores"]
+    )
+    lineas.append(
+        f"### Evento `{a['evento']['id_evento'][:8]}` "
+        f"(compuerta {ev['compuerta']}, Nivel {ev['nivel_criticidad']}, commit `{ev['commit_cabeza'][:7]}`)"
+    )
+    lineas.append("")
+    lineas.append(
+        f"Generador {ac['generador']['modelo']} ({ac['generador']['familia']}); "
+        f"revisor {revisores}; confinamiento: {confinamientos}. "
+        f"{_resumen_conteos(a)}"
+    )
+    if ev["ruta_abreviada"].get("usada"):
+        lineas.append(f"Ruta abreviada usada. Justificacion: {ev['ruta_abreviada'].get('justificacion', '')}")
+    lineas.append("")
+    residuo = a["residuo"]
+    if residuo.get("ausencia_declarada"):
+        lineas.append(f"**Sin residuo.** Declaracion expresa: {residuo['declaracion']}")
+    else:
+        lineas.append("**Residuo declarado** (lo que el ciclo no pudo cerrar por si mismo):")
+        for item in residuo["items"]:
+            lineas.append(_linea_item(item, a["perfil"]))
+    return "\n".join(lineas)
+
+
+def render_comentario(validos: list[dict], errores_por_archivo: dict[str, list[str]],
+                      errores_gate: list[str]) -> str:
+    """Comentario completo del PR, con marcador para actualizarlo en el lugar."""
+    lineas = [MARCADOR, "## Declaracion de residuo", ""]
+    if errores_gate or errores_por_archivo:
+        lineas.append("**El gate fallo.** El PR no declara residuo en forma valida:")
+        for msg in errores_gate:
+            lineas.append(f"- {msg}")
+        for archivo, errs in errores_por_archivo.items():
+            for msg in errs:
+                lineas.append(f"- `{archivo}`: {msg}")
+        lineas.append("")
+    for a in validos:
+        lineas.append(render_artefacto(a))
+        lineas.append("")
+    lineas.append("---")
+    lineas.append(
+        "Esta declaracion lista residuo, no cobertura: dirige el escrutinio del revisor humano "
+        "hacia lo que quedo abierto en lugar de leerse como sello de calidad. "
+        "La maquina valida forma y coherencia; que el residuo declarado sea el residuo real "
+        "se controla por muestreo humano, no por este gate."
+    )
+    return "\n".join(lineas)

disensor/residuo.schema.json

@@ -0,0 +1,354 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://www.pelatech.com.ar/specs/residuo/v0.1/residuo.schema.json",
+  "title": "Declaracion de residuo de un evento de revision adversarial (desacuerdo controlado)",
+  "description": "Artefacto que un evento de revision adversarial emite al cierre del ciclo. Declara residuo, no cobertura (protocolo, seccion 9): lista lo que el ciclo no pudo cerrar por si mismo, o declara expresamente su ausencia. Los hallazgos resueltos y verificados no son residuo; su evidencia es el diff. Version provisional v0.1, sujeta a ratificacion.",
+  "type": "object",
+  "required": ["esquema", "perfil", "evento", "actores", "residuo", "metricas"],
+  "additionalProperties": false,
+  "properties": {
+    "esquema": {
+      "const": "residuo/v0.1",
+      "description": "Identificador de version del esquema."
+    },
+    "perfil": {
+      "enum": ["completo", "minimizado"],
+      "description": "completo: incluye textos de hallazgos y evidencia (uso interno o SaaS con confianza plena). minimizado: solo clases, estados, conteos y hashes; ningun texto libre sale del entorno del cliente. Las prohibiciones de fuga del perfil minimizado las verifica el validador estructural (regla R9)."
+    },
+    "evento": {
+      "type": "object",
+      "required": ["id_evento", "creado_en", "repositorio", "commit_cabeza", "compuerta", "nivel_criticidad", "ruta_abreviada"],
+      "additionalProperties": false,
+      "properties": {
+        "id_evento": { "type": "string", "format": "uuid" },
+        "creado_en": { "type": "string", "format": "date-time" },
+        "repositorio": { "type": "string", "minLength": 1, "description": "URL o identificador estable del repo. En perfil minimizado puede ser un hash." },
+        "pr": { "type": "string", "description": "Numero o URL del pull request, si el evento cierra sobre un PR." },
+        "commit_base": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+        "commit_cabeza": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+        "compuerta": {
+          "enum": ["plan", "diff", "arquitectura"],
+          "description": "Que se sometio a revision: el plan antes de implementar, el diff antes de commitear, o una comparacion de arquitectura."
+        },
+        "nivel_criticidad": {
+          "enum": ["A", "B", "C"],
+          "description": "Nivel del protocolo (seccion 3.1). El nivel viaja con el codigo, no con la intencion original."
+        },
+        "ruta_abreviada": {
+          "type": "object",
+          "required": ["usada"],
+          "additionalProperties": false,
+          "properties": {
+            "usada": { "type": "boolean" },
+            "justificacion": { "type": "string", "minLength": 15, "description": "Obligatoria si usada = true. Una linea con la justificacion asentada en el PR (seccion 3.2)." },
+            "casos_protegidos_tocados": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "enum": ["autenticacion_autorizacion", "datos_personales", "calculo_economico", "migracion_datos", "integracion_core"]
+              },
+              "description": "Los cinco casos de la seccion 3.2 que el cambio toca. Si la lista no esta vacia, la ruta abreviada no se admite: lo verifica la regla R3 del validador y lo refuerza el if/then de este esquema."
+            }
+          },
+          "allOf": [
+            {
+              "if": { "properties": { "usada": { "const": true } }, "required": ["usada"] },
+              "then": { "required": ["justificacion"] }
+            },
+            {
+              "if": {
+                "properties": {
+                  "usada": { "const": true },
+                  "casos_protegidos_tocados": { "type": "array", "minItems": 1 }
+                },
+                "required": ["usada", "casos_protegidos_tocados"]
+              },
+              "then": { "properties": { "usada": { "const": false } } }
+            }
+          ]
+        }
+      }
+    },
+    "actores": {
+      "type": "object",
+      "required": ["generador", "revisores", "arbitro_humano"],
+      "additionalProperties": false,
+      "properties": {
+        "generador": {
+          "type": "object",
+          "required": ["familia", "modelo"],
+          "additionalProperties": false,
+          "properties": {
+            "familia": { "$ref": "#/$defs/familia" },
+            "modelo": { "type": "string", "minLength": 1 },
+            "version": { "type": "string" }
+          }
+        },
+        "revisores": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id_revisor", "familia", "modelo", "confinamiento"],
+            "additionalProperties": false,
+            "properties": {
+              "id_revisor": { "type": "string", "minLength": 1, "description": "Identificador local del revisor dentro del evento (r1, r2...). Los hallazgos lo referencian en origen." },
+              "familia": { "$ref": "#/$defs/familia" },
+              "modelo": { "type": "string", "minLength": 1 },
+              "id_sesion": { "type": "string", "description": "Identificador de sesion que reporta el CLI del revisor, si existe. Permite reconstruir la corrida." },
+              "consigna_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Hash de la consigna adversarial usada. Ancla la corrida a una version concreta de la consigna sin exponer su texto." },
+              "confinamiento": {
+                "type": "object",
+                "required": ["modo", "verificado"],
+                "additionalProperties": false,
+                "properties": {
+                  "modo": {
+                    "enum": ["permisos", "sandbox", "solo_lectura_por_instruccion", "sin_confinamiento"],
+                    "description": "Como se garantizo que el revisor solo lee. El protocolo (seccion 10) exige permisos y no consigna; declarar el modo real hace visible la brecha cuando existe."
+                  },
+                  "verificado": { "type": "boolean", "description": "Si se verifico despues de la corrida que el revisor no modifico el repositorio." },
+                  "metodo_verificacion": { "enum": ["git_status_limpio", "hash_del_arbol", "otro"] }
+                }
+              }
+            }
+          }
+        },
+        "tercera_revision": {
+          "type": "object",
+          "description": "Revision independiente adicional en cambios de alto riesgo (seccion 6): humana o de otra familia de modelo.",
+          "required": ["tipo"],
+          "additionalProperties": false,
+          "properties": {
+            "tipo": { "enum": ["humana", "modelo_tercera_familia"] },
+            "referencia": { "type": "string" }
+          }
+        },
+        "arbitro_humano": {
+          "type": "object",
+          "required": ["presente"],
+          "additionalProperties": false,
+          "properties": {
+            "presente": { "type": "boolean", "description": "El desarrollador entra al final del ciclo o antes si el loop escala. Un evento sin arbitro humano presente no cumple el protocolo." },
+            "id": { "type": "string", "description": "Identificador del dueno de la feature. Anonimizable (hash o alias) segun politica de la organizacion." }
+          }
+        }
+      }
+    },
+    "hallazgos": {
+      "type": "array",
+      "description": "Todos los hallazgos del evento con su estado final. Obligatorio en perfil completo (regla R10); en minimizado puede omitirse y valen los conteos de metricas.",
+      "items": { "$ref": "#/$defs/hallazgo" }
+    },
+    "residuo": {
+      "type": "object",
+      "description": "El corazon de la declaracion (seccion 6): lo que el ciclo no pudo cerrar por si mismo, en tres clases, o la declaracion expresa de ausencia. Lo comun a las tres clases: ninguna quedo respaldada por ejecucion; descansan sobre el juicio de alguien.",
+      "additionalProperties": false,
+      "oneOf": [
+        { "required": ["ausencia_declarada", "declaracion"] },
+        { "required": ["items"] }
+      ],
+      "properties": {
+        "ausencia_declarada": {
+          "const": true,
+          "description": "Solo si no quedo residuo. La ausencia se declara expresamente, nunca queda implicita en un campo vacio (seccion 12.2, falla 2)."
+        },
+        "declaracion": {
+          "type": "string",
+          "minLength": 30,
+          "description": "Texto de la declaracion expresa de ausencia. La regla R2 del validador rechaza marcadores genericos (N/A, ninguno, todo resuelto, aplicado). Limite honesto del control: la maquina detecta el campo vacio y el marcador generico, no la declaracion falsa; el muestreo humano sigue siendo la unica defensa real contra el cumplimiento cosmetico."
+        },
+        "items": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/item_residuo" }
+        }
+      }
+    },
+    "metricas": {
+      "type": "object",
+      "description": "Agregados para el panel de calibracion, definidos en la seccion 11 del protocolo. Presentes en ambos perfiles: no contienen texto libre.",
+      "required": ["conteos"],
+      "additionalProperties": false,
+      "properties": {
+        "conteos": {
+          "type": "object",
+          "required": ["total_hallazgos", "validos", "falsos_positivos", "escalados_abiertos"],
+          "additionalProperties": false,
+          "properties": {
+            "total_hallazgos": { "type": "integer", "minimum": 0 },
+            "validos": {
+              "type": "object",
+              "description": "Hallazgo valido: produjo cambio en plan o codigo, deuda tecnica registrada con identificador, o decision del dueno que modifica alcance, comportamiento o riesgo aceptado (seccion 11). Descartar nunca cuenta como valido.",
+              "required": ["incorporado", "deuda_registrada", "decision_del_dueno"],
+              "additionalProperties": false,
+              "properties": {
+                "incorporado": { "type": "integer", "minimum": 0 },
+                "deuda_registrada": { "type": "integer", "minimum": 0 },
+                "decision_del_dueno": { "type": "integer", "minimum": 0 }
+              }
+            },
+            "falsos_positivos": {
+              "type": "object",
+              "description": "Descartes. Con evidencia verificable: falso positivo. Interpretativo: falso positivo que ademas va al residuo.",
+              "required": ["refutado_verificable", "refutado_interpretativo"],
+              "additionalProperties": false,
+              "properties": {
+                "refutado_verificable": { "type": "integer", "minimum": 0 },
+                "refutado_interpretativo": { "type": "integer", "minimum": 0 }
+              }
+            },
+            "escalados_abiertos": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "No entran en ninguno de los dos numeradores: se cuentan aparte como residuo hasta que se resuelvan."
+            }
+          }
+        },
+        "tiempo_extra_seg": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Cronometro de punta a punta del ciclo: corridas del revisor, verificacion de cada hallazgo, reescritura del plan y tiempo de refutacion. No incluye la implementacion (seccion 11)."
+        },
+        "costo_tokens": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "revisores": { "type": "integer", "minimum": 0 },
+            "generador": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "extensiones": {
+      "type": "object",
+      "description": "Espacio para campos propios de la organizacion, con nombre de dominio invertido como prefijo. No participa de las reglas del protocolo."
+    }
+  },
+  "$defs": {
+    "familia": {
+      "enum": ["anthropic", "openai", "google", "meta", "mistral", "otra"],
+      "description": "Familia de modelo. La decorrelacion exige que la familia de cada revisor difiera de la del generador (regla R4). Sumar una familia baja la correlacion, no la elimina: por eso en Nivel A la diversidad de modelos nunca es el unico control."
+    },
+    "evidencia": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "texto": { "type": "string", "minLength": 10, "description": "Cita de codigo, dato contractual o comportamiento observable. Solo en perfil completo." },
+        "enlace": { "type": "string", "description": "Referencia estable (permalink a linea, test, log)." },
+        "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "Hash de la evidencia. Unico contenido admitido en perfil minimizado." }
+      }
+    },
+    "hallazgo": {
+      "type": "object",
+      "required": ["id", "origen", "severidad", "estado_final", "verificacion"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^h[0-9]+$" },
+        "origen": { "type": "string", "minLength": 1, "description": "id_revisor del revisor que lo produjo." },
+        "severidad": { "enum": ["critica", "mayor", "menor", "info"] },
+        "titulo": { "type": "string", "minLength": 5, "description": "Solo perfil completo." },
+        "descripcion": { "type": "string", "description": "Solo perfil completo." },
+        "ubicacion": { "type": "string", "description": "Ruta y lineas afectadas. Solo perfil completo." },
+        "estado_final": {
+          "enum": ["incorporado", "deuda_registrada", "decision_del_dueno", "refutado_verificable", "refutado_interpretativo", "escalado_abierto"],
+          "description": "Salida terminal del hallazgo al cierre del evento. Los tres primeros son las tres formas de hallazgo valido (seccion 11). Los dos refutados son falsos positivos; el interpretativo ademas integra el residuo. escalado_abierto integra el residuo y no cuenta en ningun numerador."
+        },
+        "verificacion": {
+          "type": "object",
+          "required": ["contra"],
+          "additionalProperties": false,
+          "properties": {
+            "contra": {
+              "enum": ["repositorio", "ejecucion", "ninguna"],
+              "description": "Contra que verifico el generador el hallazgo antes de aceptarlo o refutarlo (no creerle a ciegas al revisor; decorrelacion en ambas direcciones)."
+            },
+            "detalle": { "type": "string" }
+          }
+        },
+        "ajuste_al_remedio": {
+          "type": "string",
+          "description": "Cuando el hallazgo es valido pero el remedio propuesto por el revisor era incorrecto y se adopto con modificacion. El hallazgo cuenta como incorporado; el ajuste queda registrado."
+        },
+        "verificacion_de_la_correccion": {
+          "type": "object",
+          "description": "Un hallazgo incorporado no se cierra al aplicar la correccion sino cuando la correccion paso su propia verificacion: compuerta de diff sobre ese cambio o prueba especifica (seccion 6). Obligatoria en compuerta diff para estado incorporado (regla R7).",
+          "required": ["tipo"],
+          "additionalProperties": false,
+          "properties": {
+            "tipo": { "enum": ["compuerta_diff", "prueba_especifica", "pendiente_en_compuerta_diff"] },
+            "referencia": { "type": "string" }
+          }
+        },
+        "id_deuda": { "type": "string", "description": "Obligatorio si estado_final = deuda_registrada: identificador en el sistema de deuda tecnica." },
+        "registro_riesgo": { "type": "string", "description": "Obligatorio si estado_final = decision_del_dueno: registro del riesgo aceptado o del cambio de alcance." },
+        "evidencia": { "$ref": "#/$defs/evidencia" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "estado_final": { "const": "deuda_registrada" } }, "required": ["estado_final"] },
+          "then": { "required": ["id_deuda"] }
+        },
+        {
+          "if": { "properties": { "estado_final": { "const": "decision_del_dueno" } }, "required": ["estado_final"] },
+          "then": { "required": ["registro_riesgo"] }
+        },
+        {
+          "if": { "properties": { "estado_final": { "const": "refutado_verificable" } }, "required": ["estado_final"] },
+          "then": { "required": ["evidencia"] }
+        }
+      ]
+    },
+    "item_residuo": {
+      "type": "object",
+      "required": ["id", "clase", "requiere_atencion_humana"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^r[0-9]+$" },
+        "clase": {
+          "enum": ["escalado_sin_decision", "refutacion_del_principal", "gap_de_ejecucion"],
+          "description": "Las tres clases de la seccion 6: hallazgos escalados sin decision, hallazgos que el modelo principal refuto, y comportamiento que la ejecucion no pudo arbitrar."
+        },
+        "ref_hallazgo": { "type": "string", "pattern": "^h[0-9]+$", "description": "Hallazgo de origen, si aplica. Los gap_de_ejecucion pueden no nacer de un hallazgo." },
+        "requiere_atencion_humana": {
+          "type": "boolean",
+          "description": "true como minimo para toda refutacion interpretativa: es la que pide atencion humana (seccion 6)."
+        },
+        "tipo_refutacion": {
+          "enum": ["verificable", "interpretativa"],
+          "description": "Obligatorio si clase = refutacion_del_principal. Verificable: cita de codigo, dato contractual o comportamiento observable. Interpretativa: criterio de dominio o arquitectura. Las dos se declaran para que el revisor humano pueda no darlas por buenas."
+        },
+        "descripcion": { "type": "string", "description": "Solo perfil completo." },
+        "evidencia": { "$ref": "#/$defs/evidencia" },
+        "motivo_gap": {
+          "enum": ["entorno_no_reproduce", "tercero_sin_ambiente_prueba", "otro"],
+          "description": "Obligatorio si clase = gap_de_ejecucion."
+        },
+        "aceptacion_referente": {
+          "type": "object",
+          "description": "En Nivel A, un gap de ejecucion bloquea el merge hasta que un referente tecnico lo acepte por escrito (seccion 7). La regla R5 lo exige.",
+          "required": ["referente", "fecha", "registro"],
+          "additionalProperties": false,
+          "properties": {
+            "referente": { "type": "string" },
+            "fecha": { "type": "string", "format": "date-time" },
+            "registro": { "type": "string", "description": "Enlace o identificador del registro escrito de la aceptacion." }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "clase": { "const": "refutacion_del_principal" } }, "required": ["clase"] },
+          "then": { "required": ["tipo_refutacion"] }
+        },
+        {
+          "if": { "properties": { "clase": { "const": "gap_de_ejecucion" } }, "required": ["clase"] },
+          "then": { "required": ["motivo_gap"] }
+        },
+        {
+          "if": { "properties": { "tipo_refutacion": { "const": "interpretativa" } }, "required": ["tipo_refutacion"] },
+          "then": { "properties": { "requiere_atencion_humana": { "const": true } } }
+        }
+      ]
+    }
+  }
+}