disensor 0.1.0__py3-none-any.whl

disensor/vectores.py

@@ -0,0 +1,189 @@
+"""Vectores de conformidad del esquema v0.1.
+
+Los vectores son la fuente de verdad compartida entre implementaciones del
+validador (Python de referencia, TypeScript del plano de evidencia, y las que
+vengan). Cada vector es un artefacto mas el veredicto esperado: valido o no,
+y el conjunto de etiquetas de regla que deben dispararse ("schema" para
+errores de forma, "R0" a "R10" para reglas estructurales).
+
+Se comparan etiquetas, no mensajes: los mensajes son libres por
+implementacion; las etiquetas no pueden divergir.
+
+Uso: python -m disensor.vectores <directorio_destino>
+"""
+from __future__ import annotations
+
+import copy
+import json
+import sys
+from pathlib import Path
+
+from .reglas import validar_artefacto
+
+RAIZ = Path(__file__).resolve().parents[2]
+EJEMPLOS = RAIZ / "spec" / "ejemplos"
+
+
+def _cargar(nombre: str) -> dict:
+    with open(EJEMPLOS / nombre, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _etiquetas(errores: list[str]) -> list[str]:
+    tags = set()
+    for e in errores:
+        if e.startswith("[") and "]" in e:
+            tags.add(e[1:e.index("]")])
+    return sorted(tags)
+
+
+def casos() -> list[tuple[str, dict, bool, set[str]]]:
+    """(nombre, artefacto, valido_esperado, reglas_que_deben_aparecer)."""
+    plan = _cargar("ejemplo_1_compuerta_plan.json")
+    diff = _cargar("ejemplo_2_compuerta_diff.json")
+    mini = _cargar("ejemplo_3_perfil_minimizado.json")
+    lista: list[tuple[str, dict, bool, set[str]]] = []
+
+    # Validos
+    lista.append(("valido_compuerta_plan", copy.deepcopy(plan), True, set()))
+    lista.append(("valido_compuerta_diff", copy.deepcopy(diff), True, set()))
+    lista.append(("valido_perfil_minimizado", copy.deepcopy(mini), True, set()))
+
+    m = copy.deepcopy(diff)
+    m["evento"]["nivel_criticidad"] = "A"
+    for i in m["residuo"]["items"]:
+        if i["clase"] == "gap_de_ejecucion":
+            i["aceptacion_referente"] = {
+                "referente": "referente-tecnico-01",
+                "fecha": "2026-07-15T19:00:00-03:00",
+                "registro": "actas/2026-07-15-aceptacion-gap.md",
+            }
+    lista.append(("valido_nivel_a_gap_con_referente", m, True, set()))
+
+    m = copy.deepcopy(mini)
+    m["hallazgos"] = []
+    m["residuo"] = {
+        "ausencia_declarada": True,
+        "declaracion": "El ciclo corrio completo sobre el diff y no quedo nada sin resolver: "
+                       "todo hallazgo se incorporo y sus correcciones pasaron pruebas especificas.",
+    }
+    m["metricas"]["conteos"] = {
+        "total_hallazgos": 0,
+        "validos": {"incorporado": 0, "deuda_registrada": 0, "decision_del_dueno": 0},
+        "falsos_positivos": {"refutado_verificable": 0, "refutado_interpretativo": 0},
+        "escalados_abiertos": 0,
+    }
+    lista.append(("valido_minimizado_ausencia_declarada", m, True, set()))
+
+    # Invalidos: reglas estructurales
+    m = copy.deepcopy(diff)
+    m["actores"]["arbitro_humano"]["presente"] = False
+    lista.append(("r0_sin_arbitro_humano", m, False, {"R0"}))
+
+    m = copy.deepcopy(diff)
+    m["residuo"]["items"] = [i for i in m["residuo"]["items"] if i["id"] != "r1"]
+    lista.append(("r1_escalado_sin_item", m, False, {"R1"}))
+
+    m = copy.deepcopy(diff)
+    m["residuo"]["items"][0]["ref_hallazgo"] = "h99"
+    lista.append(("r1_referencia_inexistente", m, False, {"R1"}))
+
+    m = copy.deepcopy(diff)
+    m["residuo"]["items"][0]["descripcion"] = "ninguno"
+    lista.append(("r2_marcador_generico", m, False, {"R2"}))
+
+    m = copy.deepcopy(diff)
+    m["actores"]["revisores"][0]["modelo"] = "COMPLETAR_modelo_del_revisor"
+    lista.append(("r2_marcador_de_plantilla", m, False, {"R2"}))
+
+    m = copy.deepcopy(diff)
+    m["actores"]["revisores"][0]["familia"] = "anthropic"
+    lista.append(("r4_sin_decorrelacion", m, False, {"R4"}))
+
+    m = copy.deepcopy(diff)
+    m["evento"]["nivel_criticidad"] = "A"
+    lista.append(("r5_gap_nivel_a_sin_referente", m, False, {"R5"}))
+
+    m = copy.deepcopy(diff)
+    m["metricas"]["conteos"]["validos"]["incorporado"] = 3
+    lista.append(("r6_conteo_inflado", m, False, {"R6"}))
+
+    m = copy.deepcopy(diff)
+    m["hallazgos"][0]["verificacion_de_la_correccion"] = {"tipo": "pendiente_en_compuerta_diff"}
+    lista.append(("r7_correccion_pendiente_en_diff", m, False, {"R7"}))
+
+    m = copy.deepcopy(mini)
+    m["hallazgos"][0]["titulo"] = "titulo que no deberia estar"
+    lista.append(("r9_fuga_de_texto_en_minimizado", m, False, {"R9"}))
+
+    m = copy.deepcopy(mini)
+    m["evento"]["repositorio"] = "https://github.com/ejemplo/repo"
+    lista.append(("r9_url_en_claro_en_minimizado", m, False, {"R9"}))
+
+    m = copy.deepcopy(diff)
+    m["hallazgos"] = []
+    lista.append(("r10_completo_sin_hallazgos", m, False, {"R10"}))
+
+    # Invalidos: solo schema (las reglas no se evaluan si la forma falla)
+    m = copy.deepcopy(diff)
+    m["evento"]["ruta_abreviada"] = {
+        "usada": True,
+        "justificacion": "cambio trivial de una linea en un helper",
+        "casos_protegidos_tocados": ["migracion_datos"],
+    }
+    lista.append(("schema_ruta_abreviada_sobre_caso_protegido", m, False, {"schema"}))
+
+    m = copy.deepcopy(diff)
+    m["hallazgos"][0]["estado_final"] = "deuda_registrada"
+    lista.append(("schema_deuda_sin_id", m, False, {"schema"}))
+
+    m = copy.deepcopy(diff)
+    m["residuo"]["items"][1]["tipo_refutacion"] = "interpretativa"
+    m["residuo"]["items"][1]["requiere_atencion_humana"] = False
+    lista.append(("schema_interpretativa_sin_atencion_humana", m, False, {"schema"}))
+
+    m = copy.deepcopy(diff)
+    m["evento"]["commit_cabeza"] = "ZZZZ"
+    lista.append(("schema_commit_invalido", m, False, {"schema"}))
+
+    m = copy.deepcopy(diff)
+    del m["residuo"]["items"]
+    lista.append(("schema_residuo_vacio", m, False, {"schema"}))
+
+    return lista
+
+
+def generar(destino: Path) -> int:
+    """Escribe los vectores con el veredicto de la implementacion de referencia.
+
+    El veredicto se registra desde la implementacion, pero cada caso lleva una
+    expectativa minima (valido si o no, y que reglas deben aparecer) que se
+    verifica antes de escribir: el generador no puede bendecir un bug propio.
+    """
+    destino.mkdir(parents=True, exist_ok=True)
+    indice = []
+    for nombre, artefacto, valido_esperado, reglas_minimas in casos():
+        errores = validar_artefacto(artefacto)
+        valido = not errores
+        etiquetas = _etiquetas(errores)
+        assert valido == valido_esperado, f"{nombre}: esperaba valido={valido_esperado}, dio {valido}: {errores}"
+        faltan = reglas_minimas - set(etiquetas)
+        assert not faltan, f"{nombre}: faltan reglas {faltan} en {etiquetas}"
+        vector = {
+            "nombre": nombre,
+            "esperado": {"valido": valido, "reglas": etiquetas},
+            "artefacto": artefacto,
+        }
+        with open(destino / f"{nombre}.json", "w", encoding="utf-8") as f:
+            json.dump(vector, f, ensure_ascii=False, indent=2)
+            f.write("\n")
+        indice.append(nombre)
+    with open(destino / "INDICE.json", "w", encoding="utf-8") as f:
+        json.dump({"esquema": "residuo/v0.1", "vectores": indice}, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+    print(f"{len(indice)} vectores escritos en {destino}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(generar(Path(sys.argv[1] if len(sys.argv) > 1 else "spec/vectores")))

disensor-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: disensor
+Version: 0.1.0
+Summary: disensor: adversarial plan & code review with a declared residue. Emite, valida y hace cumplir en CI declaraciones de residuo (esquema residuo/v0.1).
+Author-email: Nicolas Rocchia <nicolasrocchia@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# disensor
+
+Adversarial plan & code review with a declared residue.
+
+Declaración de residuo de revisión adversarial, con validación y gate de CI. Implementación de referencia del artefacto definido a partir del método de **desacuerdo controlado**: un modelo genera, un modelo de otra familia ataca, el generador verifica cada hallazgo, y el ciclo termina cuando todo hallazgo quedó resuelto, refutado con evidencia o escalado a un humano.
+
+El artefacto que este repo define y hace cumplir registra cómo terminó cada evento de revisión: los hallazgos con su estado terminal, y el **residuo**: lo que el ciclo no pudo cerrar por sí mismo y descansa sobre el juicio de alguien. La declaración lista residuo, no cobertura: dirige el escrutinio del revisor humano en lugar de leerse como sello de calidad.
+
+Paper del método: Rocchia, N. (2026), *Desacuerdo controlado: revisión adversarial automatizada con un segundo asistente de código en el desarrollo de software*, DOI [10.5281/zenodo.21633495](https://doi.org/10.5281/zenodo.21633495).
+
+## Qué hay acá
+
+- `spec/residuo.schema.json`: el esquema del artefacto (JSON Schema 2020-12), versión v0.1.
+- `spec/ejemplos/`: tres artefactos de ejemplo, incluido un evento real anonimizado y el perfil minimizado sin texto libre.
+- `src/disensor/`: paquete Python con el validador (reglas R0 a R10), el gate de CI (chequeos G1 a G5), el render del comentario de PR y el scaffolding de artefactos.
+- `action.yml`: GitHub Action compuesta, lista para usar.
+- `docs/integracion-claude-code.md`: cómo el flujo real (Claude Code + Codex) emite el artefacto al cierre de cada evento.
+
+## Uso rápido
+
+```bash
+pip install disensor     # para desarrollo, desde el repo clonado: pip install -e .
+
+disensor nuevo --compuerta diff --nivel B    # plantilla prellenada en .residuo/
+disensor validar .residuo/<id>.json          # schema + reglas R0 a R10
+disensor gate --sin-comentario               # lo que va a correr CI, en local
+```
+
+En el repositorio consumidor, `disensor.config.json` en la raíz declara el nivel de criticidad (el nivel viaja con el código, en un archivo versionado):
+
+```json
+{
+  "nivel_criticidad": "B",
+  "nivel_A_habilitado": false
+}
+```
+
+Y el workflow (ver `docs/ejemplo-workflow.yml`):
+
+```yaml
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: NicolasRocchia/disensor@v0.1.0
+```
+
+El gate valida todos los artefactos de `.residuo/` del PR, aplica la política y publica la declaración como comentario (se actualiza en el lugar en cada push).
+
+## Qué hace cumplir el gate
+
+Por artefacto (reglas R0 a R10): coherencia entre hallazgos y residuo, conteos que cierran, decorrelación de familias entre generador y revisor, evidencia obligatoria en refutaciones verificables, atención humana obligatoria en refutaciones interpretativas, corrección verificada antes de cerrar un hallazgo en compuerta de diff, rechazo de marcadores genéricos, y perfil minimizado sin fugas de texto.
+
+Por PR (chequeos G1 a G5): al menos una declaración válida en el rango, nivel del artefacto igual al declarado del repositorio, Nivel A bloqueado mientras la gobernanza no esté validada, política de confinamiento del revisor por nivel, y commit revisado dentro del rango del PR.
+
+Límite honesto, heredado del protocolo: la máquina detecta el campo vacío y el marcador genérico, no la declaración falsa. El muestreo humano de PR cerrados sigue siendo la única defensa real contra el cumplimiento cosmético.
+
+## Qué no hace
+
+No corre modelos, no pide claves de API en CI, y ningún código viaja a ningún servicio: valida un JSON que ya está versionado en el repo. La orquestación del loop vive donde el equipo ya trabaja; el perfil `minimizado` del artefacto permite ambientes donde ni siquiera el texto de los hallazgos puede salir del entorno.
+
+## Conformidad entre implementaciones
+
+`spec/vectores/` contiene los vectores de conformidad: 22 artefactos con su veredicto esperado (valido o no, y las etiquetas de regla que deben dispararse). Toda implementacion del validador tiene que pasarlos identicos: la referencia en Python los corre en la suite (`tests/test_vectores.py`) y el port TypeScript del plano de evidencia los corre con `npm run conformidad`. Se comparan etiquetas, no mensajes. Los vectores se regeneran con `python -m disensor.vectores spec/vectores`.
+
+`plano-evidencia/` contiene el Worker de ingesta (Cloudflare Workers mas D1) con el port TypeScript del validador y el recibo de integridad de solo agregado. Ver su README para el estado de verificacion y el despliegue.
+
+## Estado
+
+v0.1, borrador en uso. El esquema puede cambiar hasta v1.0; los cambios se declaran en el propio esquema. Dos decisiones abiertas antes de v0.2: claves del esquema en español o inglés, y licencia definitiva (hoy MIT; Apache-2.0 está en consideración por la concesión de patentes antes del release público).
+
+## Licencia
+
+MIT.

disensor-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+disensor/__init__.py,sha256=ZFrFd6fxbpAtqdhi5sj4RUH-lJSf3fxbVGaFvLixyig,110
+disensor/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+disensor/cli.py,sha256=na88_YQB9MhGHb4cn1JLjbrnY2xsAPsS8t2SuN6Pd18,2394
+disensor/gate.py,sha256=NsP1hrzV1lxVplJJHmMxmzH5XmA6Y1xKu6zJE6Qnv20,9869
+disensor/plantilla.py,sha256=R6oXu8FV1R99IBX9Yv8dnmdFB-FW_oPB-lRz0WjoGJo,3260
+disensor/reglas.py,sha256=fO9aEKg5-xggDF34Qb0JiWjLXydR5-x6tHChtdSjBcg,9055
+disensor/render.py,sha256=XlFOgRUn2Aj8dUB1CK1f34OLGOEZYkdVQaJsGlW1khM,5334
+disensor/residuo.schema.json,sha256=mHWXZCQqFKlw0E2thaDo-sijq-JZFJVyFrtQql1cFV0,19204
+disensor/vectores.py,sha256=_JjC2oV5IyIla3oi74fll35zyWckyGVOL3cGWo_9Bwg,7373
+disensor-0.1.0.dist-info/licenses/LICENSE,sha256=t4qKwdMVRVCTTjV9XDHfnKKtw7yjc13NzGZl3UTFRdk,1072
+disensor-0.1.0.dist-info/METADATA,sha256=8ZNJFnlm69A45UgyxPphyjVcv7odqsAvqJiAYYVzPk8,5552
+disensor-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+disensor-0.1.0.dist-info/entry_points.txt,sha256=cbPFH8kO5rduMHYMxYgtG91W0ScAn7_bkqsQBWlOttU,47
+disensor-0.1.0.dist-info/top_level.txt,sha256=HGsTycFBoef6Ov_p03H4FWufQWjP50AeIzDOCpE7rlQ,9
+disensor-0.1.0.dist-info/RECORD,,

disensor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

disensor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+disensor = disensor.cli:main

disensor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Rocchia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

disensor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+disensor