el-filtro 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charly.marketing
+
+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.

package/README.md

@@ -0,0 +1,214 @@
+# 🔎 El Filtro
+
+**Escanea todos tus repos de una pasada y te dice, en lenguaje simple, qué dependencias hay que arreglar ya y cuáles pueden esperar.**
+
+Reemplaza el ritual de entrar repo por repo, correr `npm audit`, y descifrar qué tan grave es cada hallazgo. El Filtro descubre tus proyectos, corre la auditoría que toque (npm o pip), detecta paquetes abandonados, y traduce todo a **dos niveles de urgencia** — sin jerga de CVE.
+
+Es 100% determinístico: **sin LLM, sin API key, sin registro**.
+
+Forma parte del kit de **Charly.marketing**:
+
+| Herramienta | Qué hace |
+|---|---|
+| El Freno de Mano | Previene |
+| El Doctor | Diagnostica la salud del proyecto |
+| La Alarma | Busca secretos expuestos |
+| **El Filtro** | **Audita las dependencias** |
+| El Repuesto | Propone los reemplazos |
+
+## Instalación y uso
+
+```bash
+npx el-filtro                          # escanea desde la carpeta actual
+npx el-filtro --path ./mis-proyectos   # escanea otra ruta
+npx el-filtro --json                   # salida JSON máquina-legible
+npx el-filtro --no-write               # no escribe el reporte a disco
+```
+
+**Cero configuración.** Te paras en tu carpeta de proyectos, corres el comando, y ya.
+
+Para auditar repos Python necesitas `pip-audit` (no viene con pip):
+
+```bash
+pip install pip-audit
+```
+
+Si falta, El Filtro te lo dice con el comando exacto y **salta solo ese repo** — el resto del escaneo sigue.
+
+## Qué hace
+
+1. **Descubre** todos los repos con `.git` bajo la carpeta que le indiques, sin bajar a `node_modules` ni a repos anidados.
+2. **Detecta el ecosistema** de cada uno (npm, pip, o ninguno).
+3. **Audita**: `npm audit` o `pip-audit`, según toque.
+4. **Detecta paquetes abandonados** (flag `deprecated` del registro de npm).
+5. **Clasifica** cada hallazgo en 🔴 o 🟡 con una explicación de una línea.
+6. **Reporta** en consola y en `.el-filtro/report-<timestamp>.json`.
+
+### Los dos niveles
+
+| | Cuándo |
+|---|---|
+| 🔴 **Arréglalo ya** | Vulnerabilidad `critical` o `high` · paquete abandonado sin reemplazo conocido |
+| 🟡 **Puede esperar** | Vulnerabilidad `moderate` o `low` · paquete abandonado que sí señala reemplazo · gravedad que no se pudo determinar |
+
+## Configuración opcional
+
+Un `.el-filtro.json` en la raíz escaneada permite excluir carpetas:
+
+```json
+{ "exclude": ["archivado", "experimentos"] }
+```
+
+## El reporte JSON
+
+Es el contrato estable que consume **El Repuesto**. `schemaVersion: 1`.
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "tool": "el-filtro",
+  "generatedAt": "2026-07-24T19:30:14.735Z",
+  "root": "C:\\...\\proyectos",
+  "summary": {
+    "reposScanned": 22, "reposAudited": 22, "reposSkipped": 0,
+    "findings": { "total": 53, "fixNow": 28, "canWait": 25 },
+    "bySeverity": { "critical": 8, "high": 19, "moderate": 25, "low": 0, "info": 0 },
+    "unknownSeverity": 0,        // vulnerabilidades sin gravedad determinada
+    "abandonedPackages": 1
+  },
+  "repos": [{
+    "name": "mi-repo",
+    "path": "C:\\...\\mi-repo",
+    "ecosystem": "npm",              // npm | pip | none
+    "secondaryEcosystems": [],       // otros ecosistemas presentes, NO auditados
+    "status": "audited",             // audited | no-audit | not-applicable
+    "statusReason": null,
+    "findings": [{
+      "type": "vulnerability",       // vulnerability | deprecated
+      "package": "lodash",
+      "installedVersions": ["4.17.11"],
+      "severity": "critical",        // null si no se pudo determinar, o si es deprecated
+      "bucket": "fix-now",           // fix-now | can-wait — SIEMPRE presente
+      "direct": true,
+      "fixAvailable": true,
+      "fix": {                       // QUÉ instalar; null si npm no nombró versión
+        "package": "lodash",         // ojo: puede ser OTRO paquete (ver abajo)
+        "version": "4.18.1",
+        "isSemVerMajor": false       // true = el salto puede romper
+      },
+      "explanation": "Esta librería tiene una vulnerabilidad conocida...",
+      "advisory": { "titles": [...], "urls": [...], "range": "<4.17.21" },
+      "unresolvedAdvisories": 0      // advisories sin gravedad resuelta dentro de este hallazgo
+    }]
+  }]
+}
+```
+
+**Para quien consuma este JSON:** `severity` puede venir en `null` aunque el hallazgo sea una vulnerabilidad (ver limitaciones). `bucket` siempre viene poblado — úsalo como señal principal.
+
+### `fixAvailable` + `fix`: tres estados, no dos
+
+Los dos campos se leen juntos. Colapsarlos pierde información en dos direcciones distintas:
+
+| `fixAvailable` | `fix` | Qué significa |
+|---|---|---|
+| `true` | objeto | Hay que instalar **algo distinto de lo declarado**: npm nombra qué y qué versión. |
+| `true` | `null` | Se arregla **dentro del rango que ya declaras** (`npm update <paquete>`). npm no nombra versión porque no hace falta. Es el arreglo **más barato**, no uno dudoso. |
+| `false` | `null` | No hay versión segura publicada. |
+
+**`fix.package` puede no ser el paquete vulnerable.** En un fallo transitivo npm apunta al padre que hay que subir: `esbuild` vulnerable → `fix.package: "vitest"`. Recomendar el paquete vulnerable ahí mandaría a tocar algo que ni está en el `package.json`.
+
+El campo `fix` es **aditivo** al `schemaVersion: 1` y siempre viene presente (en `null` si no aplica). Su ausencia significa que el reporte lo generó una versión anterior de El Filtro.
+
+📄 **Ejemplo completo:** [`examples/report-ejemplo.json`](examples/report-ejemplo.json) — generado de corridas reales (rutas saneadas). Cubre los tres estados de repo, los dos tipos de hallazgo, un caso de gravedad sin resolver y un repo políglota.
+
+### Invariantes garantizados
+
+- `findings.total === findings.fixNow + findings.canWait`
+- `suma(bySeverity) + unknownSeverity === número de hallazgos type:"vulnerability"`
+- `reposAudited + reposSkipped === reposScanned`
+
+## ⚠️ Limitaciones conocidas
+
+### La detección de "¿hay reemplazo?" es imperfecta — y falla a propósito hacia 🔴
+
+Cuando un paquete está marcado como `deprecated`, El Filtro decide entre 🔴 y 🟡 según si el mensaje **nombra un reemplazo**. Ese mensaje es **texto libre** que cada quien escribe distinto (`"Use uuid module instead"`, `"we recommend using babel-preset-env now"`, `"replaced by X"`…), así que la detección es por patrones y **no puede ser perfecta**.
+
+**El sesgo es deliberado: ante la duda, 🔴.** Si El Filtro no reconoce la frase, asume que **no hay salida conocida** y marca el hallazgo como urgente. Preferimos molestarte de más a hacerte creer que hay una alternativa cuando no la hay.
+
+En concreto:
+- Se descartan primero los contextos negativos (`"do not use"`, `"use at your own risk"`, `"no longer in use"`) — ahí no hay reemplazo, hay advertencia.
+- Solo cuentan marcadores explícitos: `use X instead`, `recommend using X`, `replaced by X`, `superseded by X`, `in favor of X`, `migrate to X`, `switch to X`.
+- Cualquier otra redacción → 🔴.
+
+Si ves un 🔴 por abandono, **lee el mensaje original** en `advisory.titles[0]`: puede que sí haya reemplazo escrito de una forma que no reconocimos.
+
+### La gravedad en pip no viene de pip-audit
+
+`pip-audit` **no expone severidad** en su JSON (ni con el servicio `pypi` ni con `osv`): solo devuelve `id`, `fix_versions`, `aliases` y `description`. El Filtro la resuelve consultando la **API pública de OSV** (sin API key), cruzando por el alias `GHSA` de cada advisory.
+
+Consecuencias:
+- **Sin conexión**, o si un advisory no tiene etiqueta de gravedad, el hallazgo queda con `severity: null` → 🟡 y lo dice explícitamente.
+- Si un paquete tiene varios advisories y solo algunos resuelven, se usa **la gravedad más alta conocida** y se reporta cuántos quedaron sin evaluar (`unresolvedAdvisories`), porque la gravedad real podría ser mayor.
+
+### Otras
+
+- **Paquetes abandonados: solo npm.** PyPI no tiene un flag `deprecated` estándar equivalente.
+- **Solo dependencias directas** se revisan por abandono (las de `package.json`) — son las que puedes reemplazar de verdad.
+- **Solo la señal `deprecated` explícita.** No usamos "meses sin publicar" como señal: marcaría como muerto algo que solo está maduro y estable.
+- **Monorepos / workspaces**: los subproyectos anidados *dentro* de un repo git no se auditan por separado.
+- **Una carpeta con `package.json` y `requirements.txt` a la vez** se audita como npm; el otro ecosistema se reporta en `secondaryEcosystems` pero **no se audita**.
+- **`pyproject.toml` / Poetry sin `requirements.txt`**: no soportado todavía; el repo se marca como no auditado con la razón.
+
+## Cómo se comporta cuando algo falla
+
+Un repo que no se puede auditar **nunca tumba el escaneo**: se marca `no-audit` con la razón en lenguaje simple y el resto continúa. Vale para: falta `pip-audit`, no hay lockfile y no hay red, `requirements.txt` con versiones en conflicto, o registro caído.
+
+Si un repo npm **no tiene lockfile**, El Filtro genera uno en una **carpeta temporal** para poder auditar — **nunca modifica tu repo**.
+
+## Desarrollo
+
+```bash
+npm install
+npm test          # build + suite completa (TDD, fixtures reales como oráculo)
+npm run test:watch
+```
+
+### Nota de verificación del campo `fix` (2026-07-26)
+
+El end-to-end que valida los tres estados de `fixAvailable`/`fix` se corrió con la variable
+de entorno `npm_config_registry` apuntando a un proxy local de tránsito, en vez de ir directo
+al registro. Queda escrito para que no haya duda de qué se probó y en qué condiciones.
+
+**Por qué:** en esa fecha, `npm audit` fallaba desde este entorno contra
+`registry.npmjs.org/-/npm/v1/security/advisories/bulk`:
+
+| Cliente | Resultado |
+|---|---|
+| npm 11.8.0 · Node v24.13.1 (Windows 11) | `invalid json response body` — respuesta gzip que el cliente no decodifica |
+| npm 11.4.2 (vía `npx`) | idéntico |
+| npm 9 y npm 10 (vía `npx`) | `400 Bad Request` contra el endpoint legado `/-/npm/v1/security/audits/quick` |
+| npm 10.8.2 · Node v20.20.2 (VPS Ubuntu, **otra red**) | mismo 400; y npm 11 en esa máquina, mismo error de gzip |
+| `curl` con las mismas cabeceras, en ambas redes | **HTTP 200 con JSON correcto en texto plano** |
+
+Descartado que fuera la red (falla igual en dos redes y dos versiones de Node) y que fuera el
+registro (el status oficial reportaba Security Audit operativo, y `curl` obtenía la respuesta
+correcta). El fallo está en la capa HTTP del cliente npm.
+
+**Qué hacía el proxy:** reenviar cada petición a `registry.npmjs.org` pidiendo
+`Accept-Encoding: identity` y devolver la respuesta sin tocarla. No cachea, no altera ni
+sustituye datos — **los advisories siguen viniendo del registro real**. Solo cambia la
+compresión de un salto de transporte.
+
+**Qué NO se tocó:** la variable se exportó únicamente para los procesos de esa corrida.
+No se modificó `.npmrc` ni ninguna configuración de la máquina (`npm config get registry`
+siguió devolviendo `https://registry.npmjs.org/` durante y después).
+
+**Qué se verificó así:** los 24 repos del corpus se auditaron (0 sin auditar) y los tres
+estados aparecieron en datos frescos — 46 hallazgos con `fix` poblado, 11 con `fixAvailable:
+true` y `fix: null` (caso `postcss`), y el resto sin arreglo. Los tests unitarios usan
+fixtures capturados de corridas reales y no dependen del proxy.
+
+## Licencia
+
+MIT © [Charly.marketing](https://charly.marketing)

package/bin/el-filtro.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/audit/deprecated.js

@@ -0,0 +1,121 @@
+/**
+ * Detección de paquetes abandonados (§6.4 del brief).
+ *
+ * Solo la **Señal 1**: el flag `deprecated` explícito del registro de npm — 100% confiable,
+ * lo pone quien mantiene el paquete. La Señal 2 (umbral de meses sin publicar) queda fuera
+ * a propósito: marcaría como muerto algo que solo está maduro y estable, y un falso positivo
+ * el día 1 rompe la confianza más rápido de lo que la construye un acierto.
+ */
+const REGISTRY = 'https://registry.npmjs.org';
+// Packument abreviado: mucho más liviano que el completo y trae `deprecated` por versión.
+const ABBREVIATED = 'application/vnd.npm.install-v1+json';
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : null;
+}
+// Contextos NEGATIVOS: el mensaje usa "use/using" para advertir, no para ofrecer salida
+// ("Do not use this package", "use at your own risk"). Si aparece uno, no hay alternativa.
+const NEGATIVE_CONTEXT = /\b(?:do\s+not|don'?t|never|avoid|no\s+longer|not)\s+(?:use|using)\b|\bat\s+your\s+own\s+risk\b|\bin\s+use\b/i;
+// Un token de paquete: nombre npm (admite @scope/nombre, guiones, puntos).
+const PKG = String.raw `[\w@][\w@/.-]*`;
+/**
+ * Formas EXPLÍCITAS de nombrar un reemplazo. Deliberadamente estrictas: cada patrón exige
+ * un marcador inequívoco ("instead", "replaced by", "in favor of"…) además del nombre del
+ * paquete. No basta con que aparezca el verbo "use" suelto.
+ */
+const REPLACEMENT_PATTERNS = [
+    new RegExp(String.raw `\buse\s+${PKG}(?:\s+\w+){0,3}\s+instead\b`, 'i'), // "Use uuid module instead"
+    new RegExp(String.raw `\brecommend(?:s|ed)?\s+using\s+${PKG}`, 'i'), // "we recommend using babel-preset-env"
+    new RegExp(String.raw `\breplaced\s+by\s+${PKG}`, 'i'),
+    new RegExp(String.raw `\bsuperseded\s+by\s+${PKG}`, 'i'),
+    new RegExp(String.raw `\bin\s+favou?r\s+of\s+${PKG}`, 'i'),
+    new RegExp(String.raw `\bmigrate\s+to\s+${PKG}`, 'i'),
+    new RegExp(String.raw `\bswitch\s+to\s+${PKG}`, 'i'),
+];
+/**
+ * ¿El mensaje de deprecación nombra un reemplazo? Determinístico, sin IA.
+ *
+ * SESGO DELIBERADO: el mensaje es texto libre que cada quien escribe distinto, así que esta
+ * detección es imposible de hacer perfecta. Ante la duda se responde `false` → el hallazgo
+ * cae en 🔴 (más urgente de lo necesario). El error inaceptable es el contrario: dar 🟡 y
+ * hacer creer que hay salida cuando no la hay. Por eso primero se descartan los contextos
+ * negativos y luego se exige un marcador explícito de reemplazo.
+ */
+export function hasKnownAlternative(message) {
+    if (typeof message !== 'string' || message.trim() === '')
+        return false;
+    if (NEGATIVE_CONTEXT.test(message))
+        return false;
+    return REPLACEMENT_PATTERNS.some((re) => re.test(message));
+}
+/** Mensaje de deprecación de una versión concreta, o null si esa versión no está marcada. */
+export function deprecatedFromPackument(packument, version) {
+    const versions = asRecord(asRecord(packument)?.versions);
+    const entry = asRecord(versions?.[version]);
+    const deprecated = entry?.deprecated;
+    return typeof deprecated === 'string' && deprecated.trim() !== '' ? deprecated : null;
+}
+/**
+ * Dependencias DIRECTAS declaradas en package.json (prod + dev).
+ *
+ * Solo las directas: son las que de verdad puedes cambiar, y son las que El Repuesto podrá
+ * proponer reemplazar. Revisar el árbol completo dispararía cientos de consultas al registro
+ * por repo para hallazgos sobre los que no puedes actuar directamente.
+ */
+export function directDependencies(packageJson) {
+    const pkg = asRecord(packageJson);
+    const names = new Set();
+    for (const field of ['dependencies', 'devDependencies']) {
+        const deps = asRecord(pkg?.[field]);
+        if (!deps)
+            continue;
+        for (const name of Object.keys(deps))
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * Construye el hallazgo de paquete abandonado. Regla de bucket del brief §6.5:
+ * 🔴 deprecated SIN alternativa conocida (estás varado) · 🟡 CON alternativa (hay a dónde ir).
+ * `severity` es null a propósito: estar abandonado no es una vulnerabilidad con gravedad.
+ */
+export function buildDeprecatedFinding(packageName, version, message) {
+    const conAlternativa = hasKnownAlternative(message);
+    return {
+        type: 'deprecated',
+        package: packageName,
+        installedVersions: version ? [version] : [],
+        severity: null,
+        bucket: conAlternativa ? 'can-wait' : 'fix-now',
+        direct: true,
+        fixAvailable: conAlternativa,
+        explanation: conAlternativa
+            ? 'Quien mantiene esta librería la dio por abandonada y señala con qué reemplazarla — cambia cuando puedas, no corre prisa hoy.'
+            : 'Quien mantiene esta librería la dio por abandonada y no señala reemplazo: ya no recibirá parches de seguridad, así que conviene salir de ella.',
+        advisory: { titles: [message], urls: [], range: '' },
+        unresolvedAdvisories: 0,
+    };
+}
+/**
+ * BORDE de red: consulta el registro de npm (sin credenciales) y cachea el packument en
+ * memoria durante el escaneo — la familia de repos comparte muchas dependencias, así que
+ * la caché evita repetir la misma consulta repo tras repo. Nunca lanza: sin red devuelve
+ * null y simplemente no se reportan abandonados.
+ */
+export function createDeprecationResolver() {
+    const cache = new Map();
+    return async (packageName, version) => {
+        try {
+            if (!cache.has(packageName)) {
+                const res = await fetch(`${REGISTRY}/${encodeURIComponent(packageName)}`, {
+                    headers: { Accept: ABBREVIATED },
+                    signal: AbortSignal.timeout(15_000),
+                });
+                cache.set(packageName, res.ok ? await res.json() : null);
+            }
+            return deprecatedFromPackument(cache.get(packageName), version);
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/audit/npm.js

@@ -0,0 +1,231 @@
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { classifySeverity, vulnerabilityExplanation } from '../classify.js';
+import { buildDeprecatedFinding, directDependencies, } from './deprecated.js';
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : null;
+}
+const SEVERITIES = new Set(['critical', 'high', 'moderate', 'low', 'info']);
+function asSeverity(v) {
+    return SEVERITIES.has(v) ? v : 'info';
+}
+function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+}
+/**
+ * `fixAvailable` de npm audit tiene tres formas: objeto (hay que instalar algo distinto),
+ * `true` pelado (basta actualizar dentro del rango declarado) y `false` (no hay arreglo).
+ * Solo la primera trae versión objetivo; las otras dos devuelven null y se distinguen
+ * entre sí por el booleano `fixAvailable`.
+ */
+function asFixTarget(v) {
+    const fix = asRecord(v);
+    if (!fix || typeof fix.name !== 'string' || typeof fix.version !== 'string')
+        return null;
+    return {
+        package: fix.name,
+        version: fix.version,
+        isSemVerMajor: fix.isSemVerMajor === true,
+    };
+}
+/**
+ * Convierte el JSON ya parseado de `npm audit --json` (auditReportVersion 2, npm v7+)
+ * en un hallazgo por paquete vulnerable. Lanza si el input no es un reporte válido
+ * (p.ej. `{error:...}` cuando falta el lockfile) para que el orquestador lo marque
+ * como "no se pudo auditar" en vez de reportar 0 vulnerabilidades falsamente.
+ */
+export function parseNpmAudit(auditJson) {
+    const root = asRecord(auditJson);
+    if (!root || 'error' in root || !asRecord(root.vulnerabilities)) {
+        throw new Error('npm audit no devolvió un reporte válido (¿falta el lockfile o hubo un error?).');
+    }
+    const vulnerabilities = root.vulnerabilities;
+    const findings = [];
+    for (const [name, raw] of Object.entries(vulnerabilities)) {
+        const v = asRecord(raw);
+        if (!v)
+            continue;
+        // `via` mezcla strings (paquetes transitivos que introducen el fallo) y objetos
+        // advisory {title,url,severity,range}. Solo los objetos traen título/url.
+        const titles = [];
+        const urls = [];
+        if (Array.isArray(v.via)) {
+            for (const entry of v.via) {
+                const adv = asRecord(entry);
+                if (!adv)
+                    continue; // entrada string → se ignora aquí
+                if (typeof adv.title === 'string' && !titles.includes(adv.title))
+                    titles.push(adv.title);
+                if (typeof adv.url === 'string' && !urls.includes(adv.url))
+                    urls.push(adv.url);
+            }
+        }
+        findings.push({
+            package: name,
+            severity: asSeverity(v.severity),
+            direct: v.isDirect === true,
+            fixAvailable: Boolean(v.fixAvailable),
+            fix: asFixTarget(v.fixAvailable),
+            range: typeof v.range === 'string' ? v.range : '',
+            nodes: asStringArray(v.nodes),
+            titles,
+            urls,
+        });
+    }
+    return findings;
+}
+/**
+ * Resuelve la(s) versión(es) instalada(s) hoy leyendo el `package-lock.json`
+ * (lockfileVersion 2/3), donde `packages` está indexado por el path exacto que
+ * `npm audit` reporta en `nodes` (p.ej. "node_modules/axios"). Devuelve versiones
+ * únicas; ignora paths ausentes. Es el dato puntual que consume El Repuesto.
+ */
+export function installedVersionsFromLockfile(lockJson, nodes) {
+    const lock = asRecord(lockJson);
+    const packages = asRecord(lock?.packages);
+    if (!packages)
+        return [];
+    const versions = [];
+    for (const node of nodes) {
+        const entry = asRecord(packages[node]);
+        const version = entry?.version;
+        if (typeof version === 'string' && !versions.includes(version))
+            versions.push(version);
+    }
+    return versions;
+}
+/**
+ * Combina el parseo del audit con las versiones del lockfile y la clasificación
+ * determinística para producir los Findings finales del contrato (§6.5, §6.6).
+ * Pura: recibe ambos JSON ya parseados; la orquestación de I/O vive en auditNpmRepo.
+ */
+export function enrichFindings(auditJson, lockJson) {
+    return parseNpmAudit(auditJson).map((v) => {
+        const bucket = classifySeverity(v.severity);
+        return {
+            type: 'vulnerability',
+            package: v.package,
+            installedVersions: installedVersionsFromLockfile(lockJson, v.nodes),
+            severity: v.severity,
+            bucket,
+            direct: v.direct,
+            fixAvailable: v.fixAvailable,
+            fix: v.fix,
+            explanation: vulnerabilityExplanation(bucket),
+            advisory: { titles: v.titles, urls: v.urls, range: v.range },
+        };
+    });
+}
+/**
+ * Hallazgos de paquetes abandonados de un repo npm (§6.4): recorre las dependencias
+ * DIRECTAS del package.json, resuelve la versión instalada en el lockfile y pregunta al
+ * registro si esa versión está marcada como deprecated. Un paquete sin versión en el
+ * lockfile se omite (no se puede afirmar qué versión tienes). Nunca lanza: si el
+ * resolvedor falla (sin red), simplemente no se reportan abandonados.
+ */
+export async function deprecatedFindingsFor(packageJson, lockJson, resolve) {
+    const findings = [];
+    for (const name of directDependencies(packageJson)) {
+        const [version] = installedVersionsFromLockfile(lockJson, [`node_modules/${name}`]);
+        if (!version)
+            continue;
+        try {
+            const message = await resolve(name, version);
+            if (message)
+                findings.push(buildDeprecatedFinding(name, version, message));
+        }
+        catch {
+            // Sin red o registro caído: se omite este paquete, el resto del escaneo sigue.
+        }
+    }
+    return findings;
+}
+const LOCKFILES = ['package-lock.json', 'npm-shrinkwrap.json'];
+function findLockfile(dir) {
+    for (const name of LOCKFILES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function npmErrorReason(err) {
+    const e = err;
+    if (e?.code === 'ENOENT')
+        return 'npm no está disponible en el PATH';
+    return e instanceof Error ? e.message : String(err);
+}
+/**
+ * Corre `npm audit --json` en `dir` y arma los Findings usando el lockfile dado.
+ * `packageJsonPath` es siempre el del repo REAL (no la copia temporal), y si se pasa un
+ * resolvedor se suman los hallazgos de paquetes abandonados (§6.4).
+ */
+async function runAuditIn(dir, lockPath, run, packageJsonPath, resolveDeprecation) {
+    let result;
+    try {
+        result = await run('npm', ['audit', '--json'], { cwd: dir });
+    }
+    catch (err) {
+        return { ok: false, reason: npmErrorReason(err) };
+    }
+    // npm audit sale con code 1 cuando HAY vulnerabilidades: se parsea el stdout igual.
+    let findings;
+    let lockJson;
+    try {
+        const auditJson = JSON.parse(result.stdout);
+        lockJson = JSON.parse(readFileSync(lockPath, 'utf8'));
+        findings = enrichFindings(auditJson, lockJson);
+    }
+    catch {
+        return { ok: false, reason: 'npm audit no devolvió un reporte válido' };
+    }
+    // Paquetes abandonados: se suman a los hallazgos de vulnerabilidad. Que falle esta parte
+    // (sin red) no invalida la auditoría de vulnerabilidades que ya salió bien.
+    if (resolveDeprecation) {
+        try {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+            findings = [...findings, ...(await deprecatedFindingsFor(packageJson, lockJson, resolveDeprecation))];
+        }
+        catch {
+            // package.json ilegible o registro caído: se reporta lo que sí se pudo.
+        }
+    }
+    return { ok: true, findings };
+}
+/**
+ * Motor npm real para UN repo (BORDE). Si hay lockfile, audita in-place (audit es
+ * solo lectura). Si falta, usa una COPIA TEMPORAL: copia package.json a un dir temp,
+ * genera ahí el lockfile con `npm install --package-lock-only --ignore-scripts`,
+ * audita y borra — sin tocar el repo del usuario (decisión confirmada del brief).
+ * Nunca lanza: todo fallo se traduce a ok:false para no tumbar el escaneo (§7).
+ */
+export async function auditNpmRepo(repoPath, run, resolveDeprecation) {
+    const packageJsonPath = join(repoPath, 'package.json');
+    const existingLock = findLockfile(repoPath);
+    if (existingLock) {
+        return runAuditIn(repoPath, existingLock, run, packageJsonPath, resolveDeprecation);
+    }
+    if (!existsSync(packageJsonPath)) {
+        return { ok: false, reason: 'no hay package.json para auditar' };
+    }
+    let tmp = null;
+    try {
+        tmp = mkdtempSync(join(tmpdir(), 'el-filtro-audit-'));
+        copyFileSync(join(repoPath, 'package.json'), join(tmp, 'package.json'));
+        await run('npm', ['install', '--package-lock-only', '--ignore-scripts'], { cwd: tmp });
+        const tmpLock = findLockfile(tmp);
+        if (!tmpLock) {
+            return { ok: false, reason: 'no se pudo generar el lockfile (¿sin conexión?). Corre: npm install' };
+        }
+        // El package.json que se lee para deprecated es el del repo real, no la copia temporal.
+        return await runAuditIn(tmp, tmpLock, run, packageJsonPath, resolveDeprecation);
+    }
+    catch (err) {
+        return { ok: false, reason: npmErrorReason(err) };
+    }
+    finally {
+        if (tmp)
+            rmSync(tmp, { recursive: true, force: true });
+    }
+}