@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/revision/hallazgo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hallazgo.js","sourceRoot":"","sources":["../../../src/core/revision/hallazgo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsBzC,gFAA6E;AAC7E,MAAM,UAAU,GAA8B;IAC7C,OAAO,EAAE,GAAG;IACZ,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,WAAW,EAAE,CAAC;CACd,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,SAAoB,EAAU;IAC1D,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC;AAAA,CAC7B;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,SAAoB,EAAyC;IACvF,QAAQ,SAAS,EAAE,CAAC;QACnB,KAAK,SAAS,CAAC;QACf,KAAK,MAAM;YACV,OAAO,OAAO,CAAC;QAChB,KAAK,OAAO;YACX,OAAO,SAAS,CAAC;QAClB,KAAK,MAAM;YACV,OAAO,MAAM,CAAC;QACf;YACC,OAAO,MAAM,CAAC;IAChB,CAAC;AAAA,CACD;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,QAA0D,EAAU;IAC5F,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,SAAS,QAAQ,CAAC,IAAI,SAAS,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAAA,CAClH;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,QAA2B,EAAiB;IACxE,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,gDAAgD,CAAC;IAC/E,IAAI,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAO,4CAA2C,CAAC;IACvE,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,EAAE;QAAE,OAAO,gDAA+C,CAAC;IACxF,IAAI,OAAO,QAAQ,CAAC,WAAW,KAAK,QAAQ,IAAI,QAAQ,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1E,OAAO,2DAAuD,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACjF,OAAO,yCAAwC,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AAAA,CACZ","sourcesContent":["/**\n * Un hallazgo de revisión, con evidencia obligatoria.\n *\n * La evidencia no es un adorno del tipo: es lo que separa una revisión de una\n * opinión. Un hallazgo que dice «esto podría tener una condición de carrera» sin\n * señalar las líneas que la producen no se puede comprobar, no se puede arreglar\n * y no se puede rebatir — y a las tres veces el equipo deja de leer la revisión\n * entera. Por eso `evidencia` es obligatoria y no opcional.\n *\n * El otro campo que importa es la HUELLA. Es lo que permite que un hallazgo\n * repetido entre ejecuciones se reconozca como el mismo aunque el fichero se\n * haya movido: se calcula sobre la regla, la ruta y la evidencia, y\n * deliberadamente NO sobre el número de línea. Un hallazgo que cambia de huella\n * cada vez que alguien añade un import aparece como nuevo en cada ejecución, y\n * eso convierte cualquier panel en ruido.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport type Severidad = \"critica\" | \"alta\" | \"media\" | \"baja\" | \"informativa\";\n\nexport interface Hallazgo {\n\t/** Identificador estable de la regla, p. ej. `ada/cruce-de-frontera`. */\n\treglaId: string;\n\ttitulo: string;\n\tresumen: string;\n\tseveridad: Severidad;\n\t/** Ruta relativa a la raíz del repositorio. */\n\truta: string;\n\tlineaInicio: number;\n\tlineaFin?: number;\n\t/** El fragmento exacto que lo justifica. Obligatorio a propósito. */\n\tevidencia: string;\n\t/** Qué hacer. Un hallazgo sin salida es una queja. */\n\tremedio?: string;\n\t/** CWE, OWASP, lo que sirva para clasificar. */\n\tetiquetas?: string[];\n}\n\n/** Puntuación 0–10, la escala que entiende GitHub en `security-severity`. */\nconst PUNTUACION: Record<Severidad, number> = {\n\tcritica: 9.5,\n\talta: 7.5,\n\tmedia: 5,\n\tbaja: 3,\n\tinformativa: 0,\n};\n\nexport function puntuacionDe(severidad: Severidad): number {\n\treturn PUNTUACION[severidad];\n}\n\n/** Nivel SARIF. `informativa` es `none`, que GitHub muestra pero no cuenta. */\nexport function nivelSarif(severidad: Severidad): \"error\" | \"warning\" | \"note\" | \"none\" {\n\tswitch (severidad) {\n\t\tcase \"critica\":\n\t\tcase \"alta\":\n\t\t\treturn \"error\";\n\t\tcase \"media\":\n\t\t\treturn \"warning\";\n\t\tcase \"baja\":\n\t\t\treturn \"note\";\n\t\tdefault:\n\t\t\treturn \"none\";\n\t}\n}\n\n/**\n * Huella estable del hallazgo.\n *\n * Sobre regla + ruta + evidencia normalizada. Sin número de línea: si lo\n * llevara, mover el bloque diez líneas más abajo crearía un hallazgo \"nuevo\" y\n * el anterior quedaría como \"resuelto\", que es mentira dos veces.\n *\n * La evidencia se normaliza en espacios porque un reformateo no cambia el\n * problema.\n */\nexport function huellaDe(hallazgo: Pick<Hallazgo, \"reglaId\" | \"ruta\" | \"evidencia\">): string {\n\tconst normalizada = hallazgo.evidencia.replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${hallazgo.reglaId}\\u0000${hallazgo.ruta}\\u0000${normalizada}`).digest(\"hex\");\n}\n\n/** Motivo por el que un hallazgo no vale, o `null` si vale. */\nexport function porQueNoVale(hallazgo: Partial<Hallazgo>): string | null {\n\tif (!hallazgo.reglaId) return \"sin reglaId: no se puede agrupar ni deduplicar\";\n\tif (!hallazgo.ruta) return \"sin ruta: no se puede anclar en el código\";\n\tif (!hallazgo.evidencia?.trim()) return \"sin evidencia: es una opinión, no un hallazgo\";\n\tif (typeof hallazgo.lineaInicio !== \"number\" || hallazgo.lineaInicio < 1) {\n\t\treturn \"sin línea de inicio válida: no se puede señalar dónde\";\n\t}\n\tif (hallazgo.lineaFin !== undefined && hallazgo.lineaFin < hallazgo.lineaInicio) {\n\t\treturn \"la línea final va antes que la inicial\";\n\t}\n\treturn null;\n}\n"]}

package/dist/core/revision/revisor.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Revisión de un diff, con los hallazgos anclados al código.
+ *
+ * Lo que separa esto de «pídele al modelo que revise» es el ANCLAJE: un
+ * hallazgo cuya evidencia no aparece en el diff se descarta, se cuente lo
+ * convincente que se cuente. Un revisor que inventa una línea plausible es peor
+ * que no tener revisor, porque cuesta tiempo comprobar que no existe y quema la
+ * confianza del equipo en la herramienta entera.
+ *
+ * El anclaje también es lo que hace la puerta de esta fase comprobable: sobre un
+ * diff limpio, un revisor honesto devuelve cero, y uno que inventa no puede
+ * porque no hay dónde anclar.
+ */
+import { type Hallazgo } from "./hallazgo.ts";
+/**
+ * Las líneas AÑADIDAS de un diff unificado, sin el `+` inicial.
+ *
+ * Solo las añadidas: revisar lo que el diff borra es señalar un problema que la
+ * propia edición ya resolvió, y ese ruido es de los que hacen que se deje de
+ * leer la revisión.
+ */
+export declare function lineasAnadidas(diff: string): string[];
+/**
+ * ¿La evidencia existe de verdad en lo que se ha añadido?
+ *
+ * Se compara sobre el texto normalizado y completo, y no línea a línea, porque
+ * una evidencia legítima puede abarcar varias.
+ */
+export declare function estaAnclado(evidencia: string, diff: string): boolean;
+export interface Descarte {
+    hallazgo: Partial<Hallazgo>;
+    motivo: string;
+}
+export interface Cribado {
+    aceptados: Hallazgo[];
+    descartados: Descarte[];
+}
+/**
+ * Deja pasar solo lo comprobable.
+ *
+ * Los descartes se devuelven, no se tiran: sin ellos no hay forma de saber si
+ * el revisor está afinado o si está tirando la mitad de lo que encuentra, y esa
+ * diferencia solo se ve con los números delante.
+ */
+export declare function cribar(candidatos: Array<Partial<Hallazgo>>, diff: string): Cribado;
+/**
+ * Resultado de leer la respuesta del modelo. Tres estados, no dos.
+ *
+ * `ok: false` es «NO HE PODIDO LEERLO», que no es lo mismo que «no hay
+ * hallazgos». Antes las dos cosas volvían como `[]` y el comando imprimía «El
+ * revisor no ha encontrado nada en este diff» con código 0 — la misma frase, el
+ * mismo código de salida y los mismos bytes que un diff genuinamente limpio.
+ * Medido ejecutando el comando: con el modelo contestando «No puedo ayudarte con
+ * eso.» y con el modelo contestando `[]`, la salida era IDÉNTICA.
+ *
+ * Es el defecto que este repositorio persigue —un fallo que se lee como éxito—
+ * y aquí era el peor de los casos: un certificado de limpieza sobre un diff que
+ * nadie revisó.
+ */
+export type Extraccion = {
+    ok: true;
+    candidatos: Array<Partial<Hallazgo>>;
+} | {
+    ok: false;
+    motivo: string;
+};
+/**
+ * Saca el JSON de la respuesta del modelo.
+ *
+ * Tolera que venga envuelto en un bloque de código o con texto alrededor,
+ * porque eso pasa a menudo y fallar por ello convertiría una revisión buena en
+ * un error. Lo que NO hace es inventarse la estructura: si no hay un array, eso
+ * es un fallo de contrato y sale como fallo, no como «cero hallazgos».
+ *
+ * `[]` sigue siendo una respuesta válida y frecuente: es `ok: true` con la lista
+ * vacía. La diferencia entre esa y la de abajo es justo lo que hay que conservar.
+ */
+export declare function extraerCandidatos(salida: string): Extraccion;
+/** Lo que se le pide al modelo. */
+export declare const PROMPT_REVISION: string;
+//# sourceMappingURL=revisor.d.ts.map

package/dist/core/revision/revisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revisor.d.ts","sourceRoot":"","sources":["../../../src/core/revision/revisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,QAAQ,EAAgC,MAAM,eAAe,CAAC;AAS5E;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKrD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpE;AAED,MAAM,WAAW,QAAQ;IACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACvB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,WAAW,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBlF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ5G;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAiB5D;AAED,mCAAmC;AACnC,eAAO,MAAM,eAAe,QAsBhB,CAAC","sourcesContent":["/**\n * Revisión de un diff, con los hallazgos anclados al código.\n *\n * Lo que separa esto de «pídele al modelo que revise» es el ANCLAJE: un\n * hallazgo cuya evidencia no aparece en el diff se descarta, se cuente lo\n * convincente que se cuente. Un revisor que inventa una línea plausible es peor\n * que no tener revisor, porque cuesta tiempo comprobar que no existe y quema la\n * confianza del equipo en la herramienta entera.\n *\n * El anclaje también es lo que hace la puerta de esta fase comprobable: sobre un\n * diff limpio, un revisor honesto devuelve cero, y uno que inventa no puede\n * porque no hay dónde anclar.\n */\n\nimport { type Hallazgo, porQueNoVale, type Severidad } from \"./hallazgo.ts\";\n\nconst SEVERIDADES: Severidad[] = [\"critica\", \"alta\", \"media\", \"baja\", \"informativa\"];\n\n/** Espacios normalizados: un reformateo no debe romper el anclaje. */\nfunction normalizar(texto: string): string {\n\treturn texto.replace(/\\s+/g, \" \").trim();\n}\n\n/**\n * Las líneas AÑADIDAS de un diff unificado, sin el `+` inicial.\n *\n * Solo las añadidas: revisar lo que el diff borra es señalar un problema que la\n * propia edición ya resolvió, y ese ruido es de los que hacen que se deje de\n * leer la revisión.\n */\nexport function lineasAnadidas(diff: string): string[] {\n\treturn diff\n\t\t.split(\"\\n\")\n\t\t.filter((l) => l.startsWith(\"+\") && !l.startsWith(\"+++\"))\n\t\t.map((l) => l.slice(1));\n}\n\n/**\n * ¿La evidencia existe de verdad en lo que se ha añadido?\n *\n * Se compara sobre el texto normalizado y completo, y no línea a línea, porque\n * una evidencia legítima puede abarcar varias.\n */\nexport function estaAnclado(evidencia: string, diff: string): boolean {\n\tconst aguja = normalizar(evidencia);\n\tif (aguja.length < 3) return false;\n\treturn normalizar(lineasAnadidas(diff).join(\" \")).includes(aguja);\n}\n\nexport interface Descarte {\n\thallazgo: Partial<Hallazgo>;\n\tmotivo: string;\n}\n\nexport interface Cribado {\n\taceptados: Hallazgo[];\n\tdescartados: Descarte[];\n}\n\n/**\n * Deja pasar solo lo comprobable.\n *\n * Los descartes se devuelven, no se tiran: sin ellos no hay forma de saber si\n * el revisor está afinado o si está tirando la mitad de lo que encuentra, y esa\n * diferencia solo se ve con los números delante.\n */\nexport function cribar(candidatos: Array<Partial<Hallazgo>>, diff: string): Cribado {\n\tconst aceptados: Hallazgo[] = [];\n\tconst descartados: Descarte[] = [];\n\tfor (const c of candidatos) {\n\t\tconst problema = porQueNoVale(c);\n\t\tif (problema) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: problema });\n\t\t\tcontinue;\n\t\t}\n\t\tif (!SEVERIDADES.includes(c.severidad as Severidad)) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: `severidad desconocida: ${String(c.severidad)}` });\n\t\t\tcontinue;\n\t\t}\n\t\tif (!estaAnclado(c.evidencia as string, diff)) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: \"la evidencia no aparece en el diff: no se puede comprobar\" });\n\t\t\tcontinue;\n\t\t}\n\t\taceptados.push(c as Hallazgo);\n\t}\n\treturn { aceptados, descartados };\n}\n\n/**\n * Resultado de leer la respuesta del modelo. Tres estados, no dos.\n *\n * `ok: false` es «NO HE PODIDO LEERLO», que no es lo mismo que «no hay\n * hallazgos». Antes las dos cosas volvían como `[]` y el comando imprimía «El\n * revisor no ha encontrado nada en este diff» con código 0 — la misma frase, el\n * mismo código de salida y los mismos bytes que un diff genuinamente limpio.\n * Medido ejecutando el comando: con el modelo contestando «No puedo ayudarte con\n * eso.» y con el modelo contestando `[]`, la salida era IDÉNTICA.\n *\n * Es el defecto que este repositorio persigue —un fallo que se lee como éxito—\n * y aquí era el peor de los casos: un certificado de limpieza sobre un diff que\n * nadie revisó.\n */\nexport type Extraccion = { ok: true; candidatos: Array<Partial<Hallazgo>> } | { ok: false; motivo: string };\n\n/** Un trozo de la respuesta, para que el motivo diga QUÉ llegó y no solo que no valía. */\nfunction recorte(texto: string): string {\n\tconst limpio = normalizar(texto);\n\treturn limpio.length > 160 ? `${limpio.slice(0, 160)}…` : limpio;\n}\n\n/**\n * Saca el JSON de la respuesta del modelo.\n *\n * Tolera que venga envuelto en un bloque de código o con texto alrededor,\n * porque eso pasa a menudo y fallar por ello convertiría una revisión buena en\n * un error. Lo que NO hace es inventarse la estructura: si no hay un array, eso\n * es un fallo de contrato y sale como fallo, no como «cero hallazgos».\n *\n * `[]` sigue siendo una respuesta válida y frecuente: es `ok: true` con la lista\n * vacía. La diferencia entre esa y la de abajo es justo lo que hay que conservar.\n */\nexport function extraerCandidatos(salida: string): Extraccion {\n\tconst cercado = salida.match(/```(?:json)?\\s*([\\s\\S]*?)```/);\n\tconst bruto = cercado ? cercado[1] : salida;\n\tconst inicio = bruto.indexOf(\"[\");\n\tconst fin = bruto.lastIndexOf(\"]\");\n\tif (inicio === -1 || fin <= inicio) {\n\t\treturn { ok: false, motivo: `la respuesta no traía ningún array JSON. Llegó esto: ${recorte(salida)}` };\n\t}\n\ttry {\n\t\t// El trozo empieza en `[` y acaba en `]`, así que si analiza es un array:\n\t\t// no hace falta una rama para «analizó pero no es array», que nunca se\n\t\t// dispararía.\n\t\treturn { ok: true, candidatos: JSON.parse(bruto.slice(inicio, fin + 1)) as Array<Partial<Hallazgo>> };\n\t} catch (error) {\n\t\tconst detalle = error instanceof Error ? error.message : String(error);\n\t\treturn { ok: false, motivo: `el array JSON venía roto (${detalle}). Llegó esto: ${recorte(salida)}` };\n\t}\n}\n\n/** Lo que se le pide al modelo. */\nexport const PROMPT_REVISION = [\n\t\"Eres un revisor de código. Revisas SOLO el diff que se te da.\",\n\t\"\",\n\t\"Devuelve un array JSON de hallazgos, y NADA más. Cada hallazgo:\",\n\t'  { \"reglaId\": \"ada/<categoria>\", \"titulo\": \"...\", \"resumen\": \"...\",',\n\t'    \"severidad\": \"critica|alta|media|baja|informativa\",',\n\t'    \"ruta\": \"<ruta del fichero>\", \"lineaInicio\": <n>, \"lineaFin\": <n>,',\n\t'    \"evidencia\": \"<el fragmento EXACTO del diff, copiado literalmente>\",',\n\t'    \"remedio\": \"<qué hacer>\" }',\n\t\"\",\n\t\"Reglas que no se negocian:\",\n\t\"- `evidencia` tiene que estar COPIADA LITERALMENTE de una línea añadida del\",\n\t\"  diff. Si no puedes copiarla, no tienes hallazgo: no lo inventes.\",\n\t\"- Revisa solo lo AÑADIDO. Señalar algo que el diff borra es ruido.\",\n\t\"- Si el diff está limpio, devuelve `[]`. Un array vacío es una respuesta\",\n\t\"  correcta y frecuente; rellenar con hallazgos menores para parecer útil es\",\n\t\"  la forma más rápida de que dejen de leer las revisiones.\",\n\t\"\",\n\t\"Qué buscar, por orden: fallos de corrección · fugas de seguridad o de\",\n\t\"secretos · errores que se tragan en silencio · cruces de frontera sin\",\n\t\"validar (dato externo que llega a una ruta de fichero, una consulta o un\",\n\t\"comando) · condiciones de carrera · recursos que no se cierran.\",\n].join(\"\\n\");\n"]}

package/dist/core/revision/revisor.js

@@ -0,0 +1,132 @@
+/**
+ * Revisión de un diff, con los hallazgos anclados al código.
+ *
+ * Lo que separa esto de «pídele al modelo que revise» es el ANCLAJE: un
+ * hallazgo cuya evidencia no aparece en el diff se descarta, se cuente lo
+ * convincente que se cuente. Un revisor que inventa una línea plausible es peor
+ * que no tener revisor, porque cuesta tiempo comprobar que no existe y quema la
+ * confianza del equipo en la herramienta entera.
+ *
+ * El anclaje también es lo que hace la puerta de esta fase comprobable: sobre un
+ * diff limpio, un revisor honesto devuelve cero, y uno que inventa no puede
+ * porque no hay dónde anclar.
+ */
+import { porQueNoVale } from "./hallazgo.js";
+const SEVERIDADES = ["critica", "alta", "media", "baja", "informativa"];
+/** Espacios normalizados: un reformateo no debe romper el anclaje. */
+function normalizar(texto) {
+    return texto.replace(/\s+/g, " ").trim();
+}
+/**
+ * Las líneas AÑADIDAS de un diff unificado, sin el `+` inicial.
+ *
+ * Solo las añadidas: revisar lo que el diff borra es señalar un problema que la
+ * propia edición ya resolvió, y ese ruido es de los que hacen que se deje de
+ * leer la revisión.
+ */
+export function lineasAnadidas(diff) {
+    return diff
+        .split("\n")
+        .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+        .map((l) => l.slice(1));
+}
+/**
+ * ¿La evidencia existe de verdad en lo que se ha añadido?
+ *
+ * Se compara sobre el texto normalizado y completo, y no línea a línea, porque
+ * una evidencia legítima puede abarcar varias.
+ */
+export function estaAnclado(evidencia, diff) {
+    const aguja = normalizar(evidencia);
+    if (aguja.length < 3)
+        return false;
+    return normalizar(lineasAnadidas(diff).join(" ")).includes(aguja);
+}
+/**
+ * Deja pasar solo lo comprobable.
+ *
+ * Los descartes se devuelven, no se tiran: sin ellos no hay forma de saber si
+ * el revisor está afinado o si está tirando la mitad de lo que encuentra, y esa
+ * diferencia solo se ve con los números delante.
+ */
+export function cribar(candidatos, diff) {
+    const aceptados = [];
+    const descartados = [];
+    for (const c of candidatos) {
+        const problema = porQueNoVale(c);
+        if (problema) {
+            descartados.push({ hallazgo: c, motivo: problema });
+            continue;
+        }
+        if (!SEVERIDADES.includes(c.severidad)) {
+            descartados.push({ hallazgo: c, motivo: `severidad desconocida: ${String(c.severidad)}` });
+            continue;
+        }
+        if (!estaAnclado(c.evidencia, diff)) {
+            descartados.push({ hallazgo: c, motivo: "la evidencia no aparece en el diff: no se puede comprobar" });
+            continue;
+        }
+        aceptados.push(c);
+    }
+    return { aceptados, descartados };
+}
+/** Un trozo de la respuesta, para que el motivo diga QUÉ llegó y no solo que no valía. */
+function recorte(texto) {
+    const limpio = normalizar(texto);
+    return limpio.length > 160 ? `${limpio.slice(0, 160)}…` : limpio;
+}
+/**
+ * Saca el JSON de la respuesta del modelo.
+ *
+ * Tolera que venga envuelto en un bloque de código o con texto alrededor,
+ * porque eso pasa a menudo y fallar por ello convertiría una revisión buena en
+ * un error. Lo que NO hace es inventarse la estructura: si no hay un array, eso
+ * es un fallo de contrato y sale como fallo, no como «cero hallazgos».
+ *
+ * `[]` sigue siendo una respuesta válida y frecuente: es `ok: true` con la lista
+ * vacía. La diferencia entre esa y la de abajo es justo lo que hay que conservar.
+ */
+export function extraerCandidatos(salida) {
+    const cercado = salida.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const bruto = cercado ? cercado[1] : salida;
+    const inicio = bruto.indexOf("[");
+    const fin = bruto.lastIndexOf("]");
+    if (inicio === -1 || fin <= inicio) {
+        return { ok: false, motivo: `la respuesta no traía ningún array JSON. Llegó esto: ${recorte(salida)}` };
+    }
+    try {
+        // El trozo empieza en `[` y acaba en `]`, así que si analiza es un array:
+        // no hace falta una rama para «analizó pero no es array», que nunca se
+        // dispararía.
+        return { ok: true, candidatos: JSON.parse(bruto.slice(inicio, fin + 1)) };
+    }
+    catch (error) {
+        const detalle = error instanceof Error ? error.message : String(error);
+        return { ok: false, motivo: `el array JSON venía roto (${detalle}). Llegó esto: ${recorte(salida)}` };
+    }
+}
+/** Lo que se le pide al modelo. */
+export const PROMPT_REVISION = [
+    "Eres un revisor de código. Revisas SOLO el diff que se te da.",
+    "",
+    "Devuelve un array JSON de hallazgos, y NADA más. Cada hallazgo:",
+    '  { "reglaId": "ada/<categoria>", "titulo": "...", "resumen": "...",',
+    '    "severidad": "critica|alta|media|baja|informativa",',
+    '    "ruta": "<ruta del fichero>", "lineaInicio": <n>, "lineaFin": <n>,',
+    '    "evidencia": "<el fragmento EXACTO del diff, copiado literalmente>",',
+    '    "remedio": "<qué hacer>" }',
+    "",
+    "Reglas que no se negocian:",
+    "- `evidencia` tiene que estar COPIADA LITERALMENTE de una línea añadida del",
+    "  diff. Si no puedes copiarla, no tienes hallazgo: no lo inventes.",
+    "- Revisa solo lo AÑADIDO. Señalar algo que el diff borra es ruido.",
+    "- Si el diff está limpio, devuelve `[]`. Un array vacío es una respuesta",
+    "  correcta y frecuente; rellenar con hallazgos menores para parecer útil es",
+    "  la forma más rápida de que dejen de leer las revisiones.",
+    "",
+    "Qué buscar, por orden: fallos de corrección · fugas de seguridad o de",
+    "secretos · errores que se tragan en silencio · cruces de frontera sin",
+    "validar (dato externo que llega a una ruta de fichero, una consulta o un",
+    "comando) · condiciones de carrera · recursos que no se cierran.",
+].join("\n");
+//# sourceMappingURL=revisor.js.map

package/dist/core/revision/revisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revisor.js","sourceRoot":"","sources":["../../../src/core/revision/revisor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Revisión de un diff, con los hallazgos anclados al código.\n *\n * Lo que separa esto de «pídele al modelo que revise» es el ANCLAJE: un\n * hallazgo cuya evidencia no aparece en el diff se descarta, se cuente lo\n * convincente que se cuente. Un revisor que inventa una línea plausible es peor\n * que no tener revisor, porque cuesta tiempo comprobar que no existe y quema la\n * confianza del equipo en la herramienta entera.\n *\n * El anclaje también es lo que hace la puerta de esta fase comprobable: sobre un\n * diff limpio, un revisor honesto devuelve cero, y uno que inventa no puede\n * porque no hay dónde anclar.\n */\n\nimport { type Hallazgo, porQueNoVale, type Severidad } from \"./hallazgo.ts\";\n\nconst SEVERIDADES: Severidad[] = [\"critica\", \"alta\", \"media\", \"baja\", \"informativa\"];\n\n/** Espacios normalizados: un reformateo no debe romper el anclaje. */\nfunction normalizar(texto: string): string {\n\treturn texto.replace(/\\s+/g, \" \").trim();\n}\n\n/**\n * Las líneas AÑADIDAS de un diff unificado, sin el `+` inicial.\n *\n * Solo las añadidas: revisar lo que el diff borra es señalar un problema que la\n * propia edición ya resolvió, y ese ruido es de los que hacen que se deje de\n * leer la revisión.\n */\nexport function lineasAnadidas(diff: string): string[] {\n\treturn diff\n\t\t.split(\"\\n\")\n\t\t.filter((l) => l.startsWith(\"+\") && !l.startsWith(\"+++\"))\n\t\t.map((l) => l.slice(1));\n}\n\n/**\n * ¿La evidencia existe de verdad en lo que se ha añadido?\n *\n * Se compara sobre el texto normalizado y completo, y no línea a línea, porque\n * una evidencia legítima puede abarcar varias.\n */\nexport function estaAnclado(evidencia: string, diff: string): boolean {\n\tconst aguja = normalizar(evidencia);\n\tif (aguja.length < 3) return false;\n\treturn normalizar(lineasAnadidas(diff).join(\" \")).includes(aguja);\n}\n\nexport interface Descarte {\n\thallazgo: Partial<Hallazgo>;\n\tmotivo: string;\n}\n\nexport interface Cribado {\n\taceptados: Hallazgo[];\n\tdescartados: Descarte[];\n}\n\n/**\n * Deja pasar solo lo comprobable.\n *\n * Los descartes se devuelven, no se tiran: sin ellos no hay forma de saber si\n * el revisor está afinado o si está tirando la mitad de lo que encuentra, y esa\n * diferencia solo se ve con los números delante.\n */\nexport function cribar(candidatos: Array<Partial<Hallazgo>>, diff: string): Cribado {\n\tconst aceptados: Hallazgo[] = [];\n\tconst descartados: Descarte[] = [];\n\tfor (const c of candidatos) {\n\t\tconst problema = porQueNoVale(c);\n\t\tif (problema) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: problema });\n\t\t\tcontinue;\n\t\t}\n\t\tif (!SEVERIDADES.includes(c.severidad as Severidad)) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: `severidad desconocida: ${String(c.severidad)}` });\n\t\t\tcontinue;\n\t\t}\n\t\tif (!estaAnclado(c.evidencia as string, diff)) {\n\t\t\tdescartados.push({ hallazgo: c, motivo: \"la evidencia no aparece en el diff: no se puede comprobar\" });\n\t\t\tcontinue;\n\t\t}\n\t\taceptados.push(c as Hallazgo);\n\t}\n\treturn { aceptados, descartados };\n}\n\n/**\n * Resultado de leer la respuesta del modelo. Tres estados, no dos.\n *\n * `ok: false` es «NO HE PODIDO LEERLO», que no es lo mismo que «no hay\n * hallazgos». Antes las dos cosas volvían como `[]` y el comando imprimía «El\n * revisor no ha encontrado nada en este diff» con código 0 — la misma frase, el\n * mismo código de salida y los mismos bytes que un diff genuinamente limpio.\n * Medido ejecutando el comando: con el modelo contestando «No puedo ayudarte con\n * eso.» y con el modelo contestando `[]`, la salida era IDÉNTICA.\n *\n * Es el defecto que este repositorio persigue —un fallo que se lee como éxito—\n * y aquí era el peor de los casos: un certificado de limpieza sobre un diff que\n * nadie revisó.\n */\nexport type Extraccion = { ok: true; candidatos: Array<Partial<Hallazgo>> } | { ok: false; motivo: string };\n\n/** Un trozo de la respuesta, para que el motivo diga QUÉ llegó y no solo que no valía. */\nfunction recorte(texto: string): string {\n\tconst limpio = normalizar(texto);\n\treturn limpio.length > 160 ? `${limpio.slice(0, 160)}…` : limpio;\n}\n\n/**\n * Saca el JSON de la respuesta del modelo.\n *\n * Tolera que venga envuelto en un bloque de código o con texto alrededor,\n * porque eso pasa a menudo y fallar por ello convertiría una revisión buena en\n * un error. Lo que NO hace es inventarse la estructura: si no hay un array, eso\n * es un fallo de contrato y sale como fallo, no como «cero hallazgos».\n *\n * `[]` sigue siendo una respuesta válida y frecuente: es `ok: true` con la lista\n * vacía. La diferencia entre esa y la de abajo es justo lo que hay que conservar.\n */\nexport function extraerCandidatos(salida: string): Extraccion {\n\tconst cercado = salida.match(/```(?:json)?\\s*([\\s\\S]*?)```/);\n\tconst bruto = cercado ? cercado[1] : salida;\n\tconst inicio = bruto.indexOf(\"[\");\n\tconst fin = bruto.lastIndexOf(\"]\");\n\tif (inicio === -1 || fin <= inicio) {\n\t\treturn { ok: false, motivo: `la respuesta no traía ningún array JSON. Llegó esto: ${recorte(salida)}` };\n\t}\n\ttry {\n\t\t// El trozo empieza en `[` y acaba en `]`, así que si analiza es un array:\n\t\t// no hace falta una rama para «analizó pero no es array», que nunca se\n\t\t// dispararía.\n\t\treturn { ok: true, candidatos: JSON.parse(bruto.slice(inicio, fin + 1)) as Array<Partial<Hallazgo>> };\n\t} catch (error) {\n\t\tconst detalle = error instanceof Error ? error.message : String(error);\n\t\treturn { ok: false, motivo: `el array JSON venía roto (${detalle}). Llegó esto: ${recorte(salida)}` };\n\t}\n}\n\n/** Lo que se le pide al modelo. */\nexport const PROMPT_REVISION = [\n\t\"Eres un revisor de código. Revisas SOLO el diff que se te da.\",\n\t\"\",\n\t\"Devuelve un array JSON de hallazgos, y NADA más. Cada hallazgo:\",\n\t'  { \"reglaId\": \"ada/<categoria>\", \"titulo\": \"...\", \"resumen\": \"...\",',\n\t'    \"severidad\": \"critica|alta|media|baja|informativa\",',\n\t'    \"ruta\": \"<ruta del fichero>\", \"lineaInicio\": <n>, \"lineaFin\": <n>,',\n\t'    \"evidencia\": \"<el fragmento EXACTO del diff, copiado literalmente>\",',\n\t'    \"remedio\": \"<qué hacer>\" }',\n\t\"\",\n\t\"Reglas que no se negocian:\",\n\t\"- `evidencia` tiene que estar COPIADA LITERALMENTE de una línea añadida del\",\n\t\"  diff. Si no puedes copiarla, no tienes hallazgo: no lo inventes.\",\n\t\"- Revisa solo lo AÑADIDO. Señalar algo que el diff borra es ruido.\",\n\t\"- Si el diff está limpio, devuelve `[]`. Un array vacío es una respuesta\",\n\t\"  correcta y frecuente; rellenar con hallazgos menores para parecer útil es\",\n\t\"  la forma más rápida de que dejen de leer las revisiones.\",\n\t\"\",\n\t\"Qué buscar, por orden: fallos de corrección · fugas de seguridad o de\",\n\t\"secretos · errores que se tragan en silencio · cruces de frontera sin\",\n\t\"validar (dato externo que llega a una ruta de fichero, una consulta o un\",\n\t\"comando) · condiciones de carrera · recursos que no se cierran.\",\n].join(\"\\n\");\n"]}

package/dist/core/revision/sarif.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Exportación a SARIF 2.1.0.
+ *
+ * SARIF es el formato que ingieren GitHub Code Scanning y Azure DevOps. Sin él,
+ * los hallazgos de una revisión se quedan en la terminal de quien la lanzó: no
+ * entran en el proceso de seguridad de la empresa, no aparecen en la pestaña de
+ * la pull request y no cuentan para una homologación. Es un requisito de
+ * compra, no una mejora.
+ *
+ * oh-my-pi lo tiene solo para su escáner de seguridad. Aquí vale para CUALQUIER
+ * revisión, que es la diferencia entre «tenemos un escáner que exporta» y
+ * «nuestro agente habla el idioma de tu proceso».
+ *
+ * Dos cosas que hacen que GitHub lo acepte y que se pierden fácil:
+ *
+ * - **Toda regla citada en `results` tiene que estar en `driver.rules`.** Si
+ *   falta, el resultado se ingiere sin descripción ni severidad, o se rechaza.
+ * - **`originalUriBaseIds` con la raíz del repositorio**, para que las rutas
+ *   relativas se resuelvan contra el árbol y no contra la máquina que lo generó.
+ */
+import { type Hallazgo } from "./hallazgo.ts";
+export interface OpcionesSarif {
+    /** Raíz del repositorio, para `originalUriBaseIds`. */
+    raizRepo: string;
+    herramienta?: string;
+    version?: string;
+    uriInformacion?: string;
+}
+export declare function aSarif(hallazgos: Hallazgo[], opciones: OpcionesSarif): Record<string, unknown>;
+//# sourceMappingURL=sarif.d.ts.map

package/dist/core/revision/sarif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/core/revision/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,KAAK,QAAQ,EAAsC,MAAM,eAAe,CAAC;AAElF,MAAM,WAAW,aAAa;IAC7B,wDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0D9F","sourcesContent":["/**\n * Exportación a SARIF 2.1.0.\n *\n * SARIF es el formato que ingieren GitHub Code Scanning y Azure DevOps. Sin él,\n * los hallazgos de una revisión se quedan en la terminal de quien la lanzó: no\n * entran en el proceso de seguridad de la empresa, no aparecen en la pestaña de\n * la pull request y no cuentan para una homologación. Es un requisito de\n * compra, no una mejora.\n *\n * oh-my-pi lo tiene solo para su escáner de seguridad. Aquí vale para CUALQUIER\n * revisión, que es la diferencia entre «tenemos un escáner que exporta» y\n * «nuestro agente habla el idioma de tu proceso».\n *\n * Dos cosas que hacen que GitHub lo acepte y que se pierden fácil:\n *\n * - **Toda regla citada en `results` tiene que estar en `driver.rules`.** Si\n *   falta, el resultado se ingiere sin descripción ni severidad, o se rechaza.\n * - **`originalUriBaseIds` con la raíz del repositorio**, para que las rutas\n *   relativas se resuelvan contra el árbol y no contra la máquina que lo generó.\n */\n\nimport { pathToFileURL } from \"node:url\";\nimport { type Hallazgo, huellaDe, nivelSarif, puntuacionDe } from \"./hallazgo.ts\";\n\nexport interface OpcionesSarif {\n\t/** Raíz del repositorio, para `originalUriBaseIds`. */\n\traizRepo: string;\n\therramienta?: string;\n\tversion?: string;\n\turiInformacion?: string;\n}\n\nexport function aSarif(hallazgos: Hallazgo[], opciones: OpcionesSarif): Record<string, unknown> {\n\t// Una regla por `reglaId`, con la descripción del primer hallazgo que la usa.\n\tconst reglas = new Map<string, Hallazgo>();\n\tfor (const h of hallazgos) if (!reglas.has(h.reglaId)) reglas.set(h.reglaId, h);\n\n\treturn {\n\t\t$schema: \"https://json.schemastore.org/sarif-2.1.0.json\",\n\t\tversion: \"2.1.0\",\n\t\truns: [\n\t\t\t{\n\t\t\t\ttool: {\n\t\t\t\t\tdriver: {\n\t\t\t\t\t\tname: opciones.herramienta ?? \"Ada\",\n\t\t\t\t\t\tversion: opciones.version ?? \"0.0.0\",\n\t\t\t\t\t\tinformationUri: opciones.uriInformacion ?? \"https://hoilab.com/ada\",\n\t\t\t\t\t\trules: [...reglas.values()].map((h) => ({\n\t\t\t\t\t\t\tid: h.reglaId,\n\t\t\t\t\t\t\tname: h.reglaId,\n\t\t\t\t\t\t\tshortDescription: { text: h.titulo },\n\t\t\t\t\t\t\tfullDescription: { text: h.resumen },\n\t\t\t\t\t\t\t...(h.remedio ? { help: { text: h.remedio } } : {}),\n\t\t\t\t\t\t\tproperties: {\n\t\t\t\t\t\t\t\ttags: h.etiquetas ?? [],\n\t\t\t\t\t\t\t\t\"security-severity\": String(puntuacionDe(h.severidad)),\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t})),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\tresults: hallazgos.map((h) => ({\n\t\t\t\t\truleId: h.reglaId,\n\t\t\t\t\tlevel: nivelSarif(h.severidad),\n\t\t\t\t\tmessage: { text: h.resumen },\n\t\t\t\t\tlocations: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tphysicalLocation: {\n\t\t\t\t\t\t\t\tartifactLocation: { uri: h.ruta, uriBaseId: \"%SRCROOT%\" },\n\t\t\t\t\t\t\t\tregion: {\n\t\t\t\t\t\t\t\t\tstartLine: h.lineaInicio,\n\t\t\t\t\t\t\t\t\tendLine: h.lineaFin ?? h.lineaInicio,\n\t\t\t\t\t\t\t\t\t// La evidencia viaja como fragmento de la región: es lo\n\t\t\t\t\t\t\t\t\t// que hace que el hallazgo sea comprobable desde el panel\n\t\t\t\t\t\t\t\t\t// sin abrir el repositorio.\n\t\t\t\t\t\t\t\t\tsnippet: { text: h.evidencia },\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\t// Lo que permite a GitHub reconocer el mismo hallazgo entre\n\t\t\t\t\t// ejecuciones aunque el fichero se haya movido.\n\t\t\t\t\tpartialFingerprints: { \"ada/v1\": huellaDe(h) },\n\t\t\t\t\tproperties: { severidad: h.severidad, \"security-severity\": String(puntuacionDe(h.severidad)) },\n\t\t\t\t})),\n\t\t\t\toriginalUriBaseIds: {\n\t\t\t\t\t\"%SRCROOT%\": { uri: pathToFileURL(opciones.raizRepo).href.replace(/\\/?$/, \"/\") },\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t};\n}\n"]}

package/dist/core/revision/sarif.js

@@ -0,0 +1,83 @@
+/**
+ * Exportación a SARIF 2.1.0.
+ *
+ * SARIF es el formato que ingieren GitHub Code Scanning y Azure DevOps. Sin él,
+ * los hallazgos de una revisión se quedan en la terminal de quien la lanzó: no
+ * entran en el proceso de seguridad de la empresa, no aparecen en la pestaña de
+ * la pull request y no cuentan para una homologación. Es un requisito de
+ * compra, no una mejora.
+ *
+ * oh-my-pi lo tiene solo para su escáner de seguridad. Aquí vale para CUALQUIER
+ * revisión, que es la diferencia entre «tenemos un escáner que exporta» y
+ * «nuestro agente habla el idioma de tu proceso».
+ *
+ * Dos cosas que hacen que GitHub lo acepte y que se pierden fácil:
+ *
+ * - **Toda regla citada en `results` tiene que estar en `driver.rules`.** Si
+ *   falta, el resultado se ingiere sin descripción ni severidad, o se rechaza.
+ * - **`originalUriBaseIds` con la raíz del repositorio**, para que las rutas
+ *   relativas se resuelvan contra el árbol y no contra la máquina que lo generó.
+ */
+import { pathToFileURL } from "node:url";
+import { huellaDe, nivelSarif, puntuacionDe } from "./hallazgo.js";
+export function aSarif(hallazgos, opciones) {
+    // Una regla por `reglaId`, con la descripción del primer hallazgo que la usa.
+    const reglas = new Map();
+    for (const h of hallazgos)
+        if (!reglas.has(h.reglaId))
+            reglas.set(h.reglaId, h);
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: opciones.herramienta ?? "Ada",
+                        version: opciones.version ?? "0.0.0",
+                        informationUri: opciones.uriInformacion ?? "https://hoilab.com/ada",
+                        rules: [...reglas.values()].map((h) => ({
+                            id: h.reglaId,
+                            name: h.reglaId,
+                            shortDescription: { text: h.titulo },
+                            fullDescription: { text: h.resumen },
+                            ...(h.remedio ? { help: { text: h.remedio } } : {}),
+                            properties: {
+                                tags: h.etiquetas ?? [],
+                                "security-severity": String(puntuacionDe(h.severidad)),
+                            },
+                        })),
+                    },
+                },
+                results: hallazgos.map((h) => ({
+                    ruleId: h.reglaId,
+                    level: nivelSarif(h.severidad),
+                    message: { text: h.resumen },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: h.ruta, uriBaseId: "%SRCROOT%" },
+                                region: {
+                                    startLine: h.lineaInicio,
+                                    endLine: h.lineaFin ?? h.lineaInicio,
+                                    // La evidencia viaja como fragmento de la región: es lo
+                                    // que hace que el hallazgo sea comprobable desde el panel
+                                    // sin abrir el repositorio.
+                                    snippet: { text: h.evidencia },
+                                },
+                            },
+                        },
+                    ],
+                    // Lo que permite a GitHub reconocer el mismo hallazgo entre
+                    // ejecuciones aunque el fichero se haya movido.
+                    partialFingerprints: { "ada/v1": huellaDe(h) },
+                    properties: { severidad: h.severidad, "security-severity": String(puntuacionDe(h.severidad)) },
+                })),
+                originalUriBaseIds: {
+                    "%SRCROOT%": { uri: pathToFileURL(opciones.raizRepo).href.replace(/\/?$/, "/") },
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=sarif.js.map

package/dist/core/revision/sarif.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sarif.js","sourceRoot":"","sources":["../../../src/core/revision/sarif.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exportación a SARIF 2.1.0.\n *\n * SARIF es el formato que ingieren GitHub Code Scanning y Azure DevOps. Sin él,\n * los hallazgos de una revisión se quedan en la terminal de quien la lanzó: no\n * entran en el proceso de seguridad de la empresa, no aparecen en la pestaña de\n * la pull request y no cuentan para una homologación. Es un requisito de\n * compra, no una mejora.\n *\n * oh-my-pi lo tiene solo para su escáner de seguridad. Aquí vale para CUALQUIER\n * revisión, que es la diferencia entre «tenemos un escáner que exporta» y\n * «nuestro agente habla el idioma de tu proceso».\n *\n * Dos cosas que hacen que GitHub lo acepte y que se pierden fácil:\n *\n * - **Toda regla citada en `results` tiene que estar en `driver.rules`.** Si\n *   falta, el resultado se ingiere sin descripción ni severidad, o se rechaza.\n * - **`originalUriBaseIds` con la raíz del repositorio**, para que las rutas\n *   relativas se resuelvan contra el árbol y no contra la máquina que lo generó.\n */\n\nimport { pathToFileURL } from \"node:url\";\nimport { type Hallazgo, huellaDe, nivelSarif, puntuacionDe } from \"./hallazgo.ts\";\n\nexport interface OpcionesSarif {\n\t/** Raíz del repositorio, para `originalUriBaseIds`. */\n\traizRepo: string;\n\therramienta?: string;\n\tversion?: string;\n\turiInformacion?: string;\n}\n\nexport function aSarif(hallazgos: Hallazgo[], opciones: OpcionesSarif): Record<string, unknown> {\n\t// Una regla por `reglaId`, con la descripción del primer hallazgo que la usa.\n\tconst reglas = new Map<string, Hallazgo>();\n\tfor (const h of hallazgos) if (!reglas.has(h.reglaId)) reglas.set(h.reglaId, h);\n\n\treturn {\n\t\t$schema: \"https://json.schemastore.org/sarif-2.1.0.json\",\n\t\tversion: \"2.1.0\",\n\t\truns: [\n\t\t\t{\n\t\t\t\ttool: {\n\t\t\t\t\tdriver: {\n\t\t\t\t\t\tname: opciones.herramienta ?? \"Ada\",\n\t\t\t\t\t\tversion: opciones.version ?? \"0.0.0\",\n\t\t\t\t\t\tinformationUri: opciones.uriInformacion ?? \"https://hoilab.com/ada\",\n\t\t\t\t\t\trules: [...reglas.values()].map((h) => ({\n\t\t\t\t\t\t\tid: h.reglaId,\n\t\t\t\t\t\t\tname: h.reglaId,\n\t\t\t\t\t\t\tshortDescription: { text: h.titulo },\n\t\t\t\t\t\t\tfullDescription: { text: h.resumen },\n\t\t\t\t\t\t\t...(h.remedio ? { help: { text: h.remedio } } : {}),\n\t\t\t\t\t\t\tproperties: {\n\t\t\t\t\t\t\t\ttags: h.etiquetas ?? [],\n\t\t\t\t\t\t\t\t\"security-severity\": String(puntuacionDe(h.severidad)),\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t})),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\tresults: hallazgos.map((h) => ({\n\t\t\t\t\truleId: h.reglaId,\n\t\t\t\t\tlevel: nivelSarif(h.severidad),\n\t\t\t\t\tmessage: { text: h.resumen },\n\t\t\t\t\tlocations: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tphysicalLocation: {\n\t\t\t\t\t\t\t\tartifactLocation: { uri: h.ruta, uriBaseId: \"%SRCROOT%\" },\n\t\t\t\t\t\t\t\tregion: {\n\t\t\t\t\t\t\t\t\tstartLine: h.lineaInicio,\n\t\t\t\t\t\t\t\t\tendLine: h.lineaFin ?? h.lineaInicio,\n\t\t\t\t\t\t\t\t\t// La evidencia viaja como fragmento de la región: es lo\n\t\t\t\t\t\t\t\t\t// que hace que el hallazgo sea comprobable desde el panel\n\t\t\t\t\t\t\t\t\t// sin abrir el repositorio.\n\t\t\t\t\t\t\t\t\tsnippet: { text: h.evidencia },\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\t// Lo que permite a GitHub reconocer el mismo hallazgo entre\n\t\t\t\t\t// ejecuciones aunque el fichero se haya movido.\n\t\t\t\t\tpartialFingerprints: { \"ada/v1\": huellaDe(h) },\n\t\t\t\t\tproperties: { severidad: h.severidad, \"security-severity\": String(puntuacionDe(h.severidad)) },\n\t\t\t\t})),\n\t\t\t\toriginalUriBaseIds: {\n\t\t\t\t\t\"%SRCROOT%\": { uri: pathToFileURL(opciones.raizRepo).href.replace(/\\/?$/, \"/\") },\n\t\t\t\t},\n\t\t\t},\n\t\t],\n\t};\n}\n"]}

package/dist/core/scheduler/scheduler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Scheduler: trabajo recurrente o diferido.
+ *
+ * Copiado del competidor SOLO en los dos detalles que separan un scheduler de
+ * un pie de plomo:
+ *
+ * 1. **Reclamar antes de entregar.** Un job cuya ejecución anterior sigue en
+ *    vuelo se SALTA, no se encola. Sin esto, un job más lento que su intervalo
+ *    acumula ejecuciones hasta ahogar la sesión.
+ * 2. **`nextRunAt` avanza al reclamar**, no al terminar. Así una ejecución lenta
+ *    no arrastra el horario.
+ *
+ * Y tres frenos que a ellos les faltan, cada uno por un riesgo real:
+ *
+ * - **Nunca hace steer.** Su modo por defecto inyecta el prompt recurrente
+ *   DENTRO de un turno activo, que es un vector de inyección: lo que diga el
+ *   texto programado entra a mitad de un razonamiento. Aquí siempre se entrega
+ *   como turno nuevo, y no es configurable.
+ * - **Techo de ejecuciones y caducidad obligatorios.** Un heartbeat desatendido
+ *   gasta tokens para siempre; ellos no tienen tope alguno.
+ * - **Se desactiva solo tras fallos seguidos**, para que un job roto no siga
+ *   quemando presupuesto indefinidamente.
+ */
+export interface ScheduledJob {
+    id: string;
+    /** Texto que se entrega como turno nuevo. */
+    prompt: string;
+    /** Repetición en ms. Ausente = ejecución única. */
+    intervalMs?: number;
+    nextRunAt: string;
+    runsUsed: number;
+    /** Obligatorio: sin techo no se crea el job. */
+    maxRuns: number;
+    /** ISO. Pasada esta fecha el job no vuelve a correr. */
+    expiresAt: string;
+    enabled: boolean;
+    consecutiveFailures: number;
+    createdAt: string;
+}
+export interface Dispatch {
+    dispatchId: string;
+    job: ScheduledJob;
+}
+export declare class Scheduler {
+    private path;
+    private data;
+    private loaded;
+    private counter;
+    constructor(agentDir: string);
+    private load;
+    private save;
+    list(): ScheduledJob[];
+    /**
+     * Programa un job. `maxRuns` y `expiresAt` son obligatorios a propósito: un
+     * scheduler sin techo es una fuga de presupuesto con sintaxis bonita.
+     */
+    add(input: {
+        id: string;
+        prompt: string;
+        firstRunAt: string;
+        intervalMs?: number;
+        maxRuns: number;
+        expiresAt: string;
+        now?: string;
+    }): {
+        ok: boolean;
+        error?: string;
+    };
+    remove(id: string): boolean;
+    /**
+     * Reclama los jobs vencidos.
+     *
+     * Un job con una ejecución en vuelo se salta: avanza su horario pero no se
+     * entrega. Es lo que impide que un job lento se acumule sobre sí mismo.
+     */
+    claimDue(nowIso: string): Dispatch[];
+    /** Cierra una ejecución. Tras varios fallos seguidos el job se desactiva. */
+    complete(dispatchId: string, ok: boolean): void;
+    /**
+     * Libera ejecuciones que murieron con el proceso.
+     *
+     * Sin esto un crash deja el job marcado como "en vuelo" para siempre y no
+     * vuelve a entregarse nunca — el mismo fallo que teníamos en los workflows.
+     */
+    reconcile(nowIso: string, staleAfterMs?: number): number;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/core/scheduler/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,sDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,YAAY,CAAC;CAClB;AASD,qBAAa,SAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAyD;IACrE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAK;IAEpB,YAAY,QAAQ,EAAE,MAAM,EAE3B;IAED,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,IAAI;IAOZ,IAAI,IAAI,YAAY,EAAE,CAGrB;IAED;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;KACb,GAAG;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CA6BlC;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAO1B;IAED;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAkCnC;IAED,8EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAW9C;IAED;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,SAAiB,GAAG,MAAM,CAQ/D;CACD","sourcesContent":["/**\n * Scheduler: trabajo recurrente o diferido.\n *\n * Copiado del competidor SOLO en los dos detalles que separan un scheduler de\n * un pie de plomo:\n *\n * 1. **Reclamar antes de entregar.** Un job cuya ejecución anterior sigue en\n *    vuelo se SALTA, no se encola. Sin esto, un job más lento que su intervalo\n *    acumula ejecuciones hasta ahogar la sesión.\n * 2. **`nextRunAt` avanza al reclamar**, no al terminar. Así una ejecución lenta\n *    no arrastra el horario.\n *\n * Y tres frenos que a ellos les faltan, cada uno por un riesgo real:\n *\n * - **Nunca hace steer.** Su modo por defecto inyecta el prompt recurrente\n *   DENTRO de un turno activo, que es un vector de inyección: lo que diga el\n *   texto programado entra a mitad de un razonamiento. Aquí siempre se entrega\n *   como turno nuevo, y no es configurable.\n * - **Techo de ejecuciones y caducidad obligatorios.** Un heartbeat desatendido\n *   gasta tokens para siempre; ellos no tienen tope alguno.\n * - **Se desactiva solo tras fallos seguidos**, para que un job roto no siga\n *   quemando presupuesto indefinidamente.\n */\n\nimport { mkdirSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/** Tope duro: ningún job puede programarse sin límite de ejecuciones. */\nconst MAX_RUNS_CEILING = 1000;\nconst FAILURES_BEFORE_DISABLE = 3;\n\nexport interface ScheduledJob {\n\tid: string;\n\t/** Texto que se entrega como turno nuevo. */\n\tprompt: string;\n\t/** Repetición en ms. Ausente = ejecución única. */\n\tintervalMs?: number;\n\tnextRunAt: string;\n\trunsUsed: number;\n\t/** Obligatorio: sin techo no se crea el job. */\n\tmaxRuns: number;\n\t/** ISO. Pasada esta fecha el job no vuelve a correr. */\n\texpiresAt: string;\n\tenabled: boolean;\n\tconsecutiveFailures: number;\n\tcreatedAt: string;\n}\n\nexport interface Dispatch {\n\tdispatchId: string;\n\tjob: ScheduledJob;\n}\n\ninterface SchedulerFile {\n\tversion: 1;\n\tjobs: ScheduledJob[];\n\t/** Ejecuciones reclamadas y aún sin cerrar. */\n\tinFlight: Array<{ dispatchId: string; jobId: string; claimedAt: string }>;\n}\n\nexport class Scheduler {\n\tprivate path: string;\n\tprivate data: SchedulerFile = { version: 1, jobs: [], inFlight: [] };\n\tprivate loaded = false;\n\tprivate counter = 0;\n\n\tconstructor(agentDir: string) {\n\t\tthis.path = join(agentDir, \"scheduler.json\");\n\t}\n\n\tprivate load(): void {\n\t\tif (this.loaded) return;\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(readFileSync(this.path, \"utf-8\")) as SchedulerFile;\n\t\t\tif (parsed.version === 1 && Array.isArray(parsed.jobs)) {\n\t\t\t\tthis.data = { version: 1, jobs: parsed.jobs, inFlight: parsed.inFlight ?? [] };\n\t\t\t}\n\t\t} catch {\n\t\t\t// primer arranque o fichero corrupto\n\t\t}\n\t\tthis.loaded = true;\n\t}\n\n\tprivate save(): void {\n\t\tmkdirSync(dirname(this.path), { recursive: true });\n\t\tconst tmp = `${this.path}.tmp`;\n\t\twriteFileSync(tmp, JSON.stringify(this.data, null, 1), \"utf-8\");\n\t\trenameSync(tmp, this.path);\n\t}\n\n\tlist(): ScheduledJob[] {\n\t\tthis.load();\n\t\treturn this.data.jobs;\n\t}\n\n\t/**\n\t * Programa un job. `maxRuns` y `expiresAt` son obligatorios a propósito: un\n\t * scheduler sin techo es una fuga de presupuesto con sintaxis bonita.\n\t */\n\tadd(input: {\n\t\tid: string;\n\t\tprompt: string;\n\t\tfirstRunAt: string;\n\t\tintervalMs?: number;\n\t\tmaxRuns: number;\n\t\texpiresAt: string;\n\t\tnow?: string;\n\t}): { ok: boolean; error?: string } {\n\t\tthis.load();\n\t\tif (!input.prompt.trim()) return { ok: false, error: \"El prompt no puede estar vacío.\" };\n\t\tif (!Number.isFinite(input.maxRuns) || input.maxRuns < 1) {\n\t\t\treturn { ok: false, error: \"maxRuns es obligatorio y debe ser >= 1.\" };\n\t\t}\n\t\tif (input.maxRuns > MAX_RUNS_CEILING) {\n\t\t\treturn { ok: false, error: `maxRuns no puede superar ${MAX_RUNS_CEILING}.` };\n\t\t}\n\t\tif (Number.isNaN(Date.parse(input.expiresAt))) {\n\t\t\treturn { ok: false, error: \"expiresAt es obligatorio y debe ser una fecha ISO.\" };\n\t\t}\n\t\tif (this.data.jobs.some((job) => job.id === input.id)) {\n\t\t\treturn { ok: false, error: `Ya existe un job con id '${input.id}'.` };\n\t\t}\n\t\tthis.data.jobs.push({\n\t\t\tid: input.id,\n\t\t\tprompt: input.prompt,\n\t\t\tintervalMs: input.intervalMs,\n\t\t\tnextRunAt: input.firstRunAt,\n\t\t\trunsUsed: 0,\n\t\t\tmaxRuns: input.maxRuns,\n\t\t\texpiresAt: input.expiresAt,\n\t\t\tenabled: true,\n\t\t\tconsecutiveFailures: 0,\n\t\t\tcreatedAt: input.now ?? new Date().toISOString(),\n\t\t});\n\t\tthis.save();\n\t\treturn { ok: true };\n\t}\n\n\tremove(id: string): boolean {\n\t\tthis.load();\n\t\tconst before = this.data.jobs.length;\n\t\tthis.data.jobs = this.data.jobs.filter((job) => job.id !== id);\n\t\tif (this.data.jobs.length === before) return false;\n\t\tthis.save();\n\t\treturn true;\n\t}\n\n\t/**\n\t * Reclama los jobs vencidos.\n\t *\n\t * Un job con una ejecución en vuelo se salta: avanza su horario pero no se\n\t * entrega. Es lo que impide que un job lento se acumule sobre sí mismo.\n\t */\n\tclaimDue(nowIso: string): Dispatch[] {\n\t\tthis.load();\n\t\tconst now = Date.parse(nowIso);\n\t\tconst inFlightJobs = new Set(this.data.inFlight.map((entry) => entry.jobId));\n\t\tconst dispatches: Dispatch[] = [];\n\n\t\tfor (const job of this.data.jobs) {\n\t\t\tif (!job.enabled) continue;\n\t\t\tif (Date.parse(job.expiresAt) <= now) {\n\t\t\t\tjob.enabled = false;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (job.runsUsed >= job.maxRuns) {\n\t\t\t\tjob.enabled = false;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (Date.parse(job.nextRunAt) > now) continue;\n\n\t\t\t// El horario avanza SIEMPRE al reclamar, incluso si se salta: una\n\t\t\t// ejecución lenta no debe arrastrar el calendario.\n\t\t\tjob.nextRunAt = job.intervalMs\n\t\t\t\t? new Date(now + job.intervalMs).toISOString()\n\t\t\t\t: new Date(now + 1).toISOString();\n\t\t\tif (!job.intervalMs) job.enabled = false; // ejecución única\n\n\t\t\tif (inFlightJobs.has(job.id)) continue; // ya hay una en vuelo: se salta\n\n\t\t\tconst dispatchId = `d-${job.id}-${++this.counter}`;\n\t\t\tthis.data.inFlight.push({ dispatchId, jobId: job.id, claimedAt: nowIso });\n\t\t\tjob.runsUsed += 1;\n\t\t\tdispatches.push({ dispatchId, job: { ...job } });\n\t\t}\n\t\tthis.save();\n\t\treturn dispatches;\n\t}\n\n\t/** Cierra una ejecución. Tras varios fallos seguidos el job se desactiva. */\n\tcomplete(dispatchId: string, ok: boolean): void {\n\t\tthis.load();\n\t\tconst index = this.data.inFlight.findIndex((entry) => entry.dispatchId === dispatchId);\n\t\tif (index === -1) return;\n\t\tconst [entry] = this.data.inFlight.splice(index, 1);\n\t\tconst job = this.data.jobs.find((candidate) => candidate.id === entry.jobId);\n\t\tif (job) {\n\t\t\tjob.consecutiveFailures = ok ? 0 : job.consecutiveFailures + 1;\n\t\t\tif (job.consecutiveFailures >= FAILURES_BEFORE_DISABLE) job.enabled = false;\n\t\t}\n\t\tthis.save();\n\t}\n\n\t/**\n\t * Libera ejecuciones que murieron con el proceso.\n\t *\n\t * Sin esto un crash deja el job marcado como \"en vuelo\" para siempre y no\n\t * vuelve a entregarse nunca — el mismo fallo que teníamos en los workflows.\n\t */\n\treconcile(nowIso: string, staleAfterMs = 30 * 60 * 1000): number {\n\t\tthis.load();\n\t\tconst now = Date.parse(nowIso);\n\t\tconst before = this.data.inFlight.length;\n\t\tthis.data.inFlight = this.data.inFlight.filter((entry) => now - Date.parse(entry.claimedAt) < staleAfterMs);\n\t\tconst reclaimed = before - this.data.inFlight.length;\n\t\tif (reclaimed > 0) this.save();\n\t\treturn reclaimed;\n\t}\n}\n"]}