el-filtro 0.2.0

package/dist/audit/pip.js

@@ -0,0 +1,211 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { classifySeverity, classifyUnknownSeverity, unknownSeverityExplanation, vulnerabilityExplanation, } from '../classify.js';
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : null;
+}
+function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+}
+/**
+ * Convierte el JSON ya parseado de `pip-audit --format json` en una vulnerabilidad por
+ * (paquete, id). Deduplica: pip-audit emite entradas repetidas de verdad (lo vi con
+ * PYSEC-2021-142 y PYSEC-2020-96 en pyyaml). Lanza si el payload no es un reporte válido
+ * para que el orquestador lo marque "no se pudo auditar" en vez de reportar 0 falsamente.
+ */
+export function parsePipAudit(auditJson) {
+    const root = asRecord(auditJson);
+    if (!root || !Array.isArray(root.dependencies)) {
+        throw new Error('pip-audit no devolvió un reporte válido.');
+    }
+    const seen = new Set();
+    const vulns = [];
+    for (const entry of root.dependencies) {
+        const dep = asRecord(entry);
+        if (!dep || typeof dep.name !== 'string')
+            continue;
+        const version = typeof dep.version === 'string' ? dep.version : '';
+        if (!Array.isArray(dep.vulns))
+            continue; // dependencia sin vulnerabilidades: se ignora
+        for (const rawVuln of dep.vulns) {
+            const v = asRecord(rawVuln);
+            if (!v || typeof v.id !== 'string')
+                continue;
+            const key = `${dep.name}::${v.id}`;
+            if (seen.has(key))
+                continue; // dedup
+            seen.add(key);
+            vulns.push({
+                package: dep.name,
+                version,
+                id: v.id,
+                fixVersions: asStringArray(v.fix_versions),
+                aliases: asStringArray(v.aliases),
+                description: typeof v.description === 'string' ? v.description : '',
+            });
+        }
+    }
+    return vulns;
+}
+/** Busca la severidad por el id propio o por cualquiera de sus alias (PYSEC → GHSA). */
+function severityFor(vuln, index) {
+    const direct = index[vuln.id];
+    if (direct)
+        return direct;
+    for (const alias of vuln.aliases) {
+        if (index[alias])
+            return index[alias];
+    }
+    return null;
+}
+// Orden de gravedad para quedarse con la peor de un paquete.
+const SEVERITY_RANK = {
+    critical: 5,
+    high: 4,
+    moderate: 3,
+    low: 2,
+    info: 1,
+};
+function worstSeverity(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+/**
+ * Combina las vulnerabilidades de pip-audit con el índice de severidades de OSV para
+ * producir los Findings del contrato.
+ *
+ * AGREGA POR PAQUETE, igual que `npm audit` (que devuelve una entrada por paquete, no por
+ * advisory). pip-audit sí emite una entrada por advisory, así que sin agregar saldría el
+ * mismo paquete repetido N veces con el mismo texto: ruido en consola, conteos no
+ * comparables entre ecosistemas, y El Repuesto proponiendo el mismo reemplazo N veces.
+ * Se conserva la severidad más alta y se reúnen todos los ids de advisory.
+ *
+ * Reutiliza `classifySeverity` sin cambios, así que 🔴/🟡 significan exactamente lo mismo
+ * que en npm. Sin severidad conocida: `severity: null` y 🟡 con explicación honesta.
+ */
+export function enrichPipFindings(vulns, index) {
+    const porPaquete = new Map();
+    for (const v of vulns) {
+        const severity = severityFor(v, index);
+        const prev = porPaquete.get(v.package);
+        const ghsaUrls = v.aliases
+            .filter((a) => a.startsWith('GHSA-'))
+            .map((a) => `https://github.com/advisories/${a}`);
+        if (!prev) {
+            porPaquete.set(v.package, {
+                version: v.version,
+                severity,
+                fixAvailable: v.fixVersions.length > 0,
+                titles: [v.id],
+                urls: [...new Set(ghsaUrls)],
+                fixVersions: [...v.fixVersions],
+                unresolved: severity ? 0 : 1,
+            });
+            continue;
+        }
+        prev.severity = worstSeverity(prev.severity, severity);
+        prev.fixAvailable = prev.fixAvailable || v.fixVersions.length > 0;
+        if (!severity)
+            prev.unresolved += 1;
+        if (!prev.titles.includes(v.id))
+            prev.titles.push(v.id);
+        for (const u of ghsaUrls)
+            if (!prev.urls.includes(u))
+                prev.urls.push(u);
+        for (const f of v.fixVersions)
+            if (!prev.fixVersions.includes(f))
+                prev.fixVersions.push(f);
+    }
+    return [...porPaquete].map(([pkg, agg]) => {
+        const bucket = agg.severity ? classifySeverity(agg.severity) : classifyUnknownSeverity();
+        return {
+            type: 'vulnerability',
+            package: pkg,
+            installedVersions: agg.version ? [agg.version] : [],
+            severity: agg.severity,
+            bucket,
+            // pip-audit no distingue directa/transitiva; se audita el requirements.txt declarado.
+            direct: true,
+            fixAvailable: agg.fixAvailable,
+            explanation: agg.severity ? vulnerabilityExplanation(bucket) : unknownSeverityExplanation(),
+            advisory: {
+                titles: agg.titles,
+                urls: agg.urls,
+                range: agg.fixVersions.length > 0 ? `< ${agg.fixVersions.join(' / ')}` : '',
+            },
+            unresolvedAdvisories: agg.unresolved,
+        };
+    });
+}
+const REQUIREMENTS = 'requirements.txt';
+const MISSING_PIP_AUDIT = 'falta pip-audit. Corre: pip install pip-audit';
+/**
+ * En Windows corremos con `shell: true` (para resolver .cmd/.exe), y ahí un binario
+ * ausente NO produce ENOENT: el shell devuelve exit code con un mensaje **localizado**
+ * ("no se reconoce como un comando…" en español). Sin esto, la persona vería un error
+ * críptico en vez del comando exacto para instalarlo — justo lo que el brief §6.3 pide evitar.
+ */
+export function looksLikeMissingPipAudit(stderr) {
+    return /no se reconoce como un comando|is not recognized as an internal or external command|command not found/i.test(stderr);
+}
+function pipErrorReason(err) {
+    const e = err;
+    if (e?.code === 'ENOENT')
+        return MISSING_PIP_AUDIT;
+    return e instanceof Error ? e.message : String(err);
+}
+/** Recorta la salida de error de pip para un statusReason legible. */
+function firstErrorLine(stderr) {
+    const line = stderr
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => /^ERROR/i.test(l));
+    return line ? line.replace(/^ERROR:\s*/i, '').slice(0, 160) : 'pip-audit falló';
+}
+/**
+ * Motor pip real para UN repo (BORDE). Corre `pip-audit -r requirements.txt --format json
+ * --no-deps` y enriquece la severidad contra OSV (1 llamada por paquete vulnerable).
+ * Nunca lanza: todo fallo se traduce a ok:false para no tumbar el escaneo. Si OSV falla,
+ * el repo SÍ queda auditado — solo pierde la severidad (🟡 + explicación).
+ */
+export async function auditPipRepo(repoPath, run, resolveSeverities) {
+    if (!existsSync(join(repoPath, REQUIREMENTS))) {
+        return {
+            ok: false,
+            reason: 'sin requirements.txt (soporte de pyproject/Poetry: no en esta versión)',
+        };
+    }
+    let result;
+    try {
+        result = await run('pip-audit', ['-r', REQUIREMENTS, '--format', 'json', '--no-deps'], {
+            cwd: repoPath,
+        });
+    }
+    catch (err) {
+        return { ok: false, reason: pipErrorReason(err) };
+    }
+    // Binario ausente vía shell (Windows): mensaje claro con el comando exacto.
+    if (looksLikeMissingPipAudit(result.stderr))
+        return { ok: false, reason: MISSING_PIP_AUDIT };
+    // pip-audit sale con code 1 cuando HAY vulnerabilidades: eso es normal, se parsea igual.
+    // Un fallo real (ResolutionImpossible, etc.) deja stdout vacío/no-JSON.
+    let vulns;
+    try {
+        vulns = parsePipAudit(JSON.parse(result.stdout));
+    }
+    catch {
+        return { ok: false, reason: firstErrorLine(result.stderr) };
+    }
+    // Severidad: 1 llamada a OSV por paquete vulnerable (no por advisory).
+    const index = {};
+    const porPaquete = new Map();
+    for (const v of vulns)
+        porPaquete.set(v.package, v.version);
+    for (const [name, version] of porPaquete) {
+        Object.assign(index, await resolveSeverities(name, version));
+    }
+    return { ok: true, findings: enrichPipFindings(vulns, index) };
+}

package/dist/classify.js

@@ -0,0 +1,27 @@
+// Mapeo 100% determinístico severidad → urgencia (§6.5). Sin IA, sin API key.
+const FIX_NOW = new Set(['critical', 'high']);
+/** 🔴 fix-now ← critical/high · 🟡 can-wait ← moderate/low/info. */
+export function classifySeverity(severity) {
+    return FIX_NOW.has(severity) ? 'fix-now' : 'can-wait';
+}
+// Plantillas fijas: explican el hallazgo en lenguaje simple, no en jerga de CVE.
+const VULN_EXPLANATION = {
+    'fix-now': 'Esta librería tiene una vulnerabilidad conocida que se puede explotar directamente — actualízala antes de publicar algo que dependa de ella.',
+    'can-wait': 'Esta librería tiene una vulnerabilidad menor o difícil de explotar — conviene actualizarla, pero no es urgente.',
+};
+/** Explicación en lenguaje simple para un hallazgo de vulnerabilidad, según su bucket. */
+export function vulnerabilityExplanation(bucket) {
+    return VULN_EXPLANATION[bucket];
+}
+/**
+ * Bucket cuando no se pudo determinar la gravedad (hallazgo pip cuyo advisory no tiene
+ * etiqueta de severidad, o escaneo sin red). Cae en 🟡 a propósito: sin evidencia no se
+ * infla la urgencia — el brief advierte que un falso positivo el día 1 rompe la confianza.
+ */
+export function classifyUnknownSeverity() {
+    return 'can-wait';
+}
+/** Explicación honesta para severidad desconocida: dice que hay que mirarlo a mano. */
+export function unknownSeverityExplanation() {
+    return 'Esta librería tiene una vulnerabilidad conocida, pero no se pudo determinar qué tan grave es — revísala a mano para decidir si corre prisa.';
+}

package/dist/cli.js

@@ -0,0 +1,53 @@
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { scan } from './scan.js';
+import { auditNpmRepo } from './audit/npm.js';
+import { auditPipRepo } from './audit/pip.js';
+import { createDeprecationResolver } from './audit/deprecated.js';
+import { fetchOsvSeverities } from './osv.js';
+import { runCommand } from './runners/exec.js';
+import { renderConsole, renderJson, writeReport } from './report.js';
+// \r vuelve al inicio de la línea; ESC[K borra hasta el final. fromCharCode(27) es
+// el byte ESC, escrito así para evitar ambigüedad de escape en el fuente.
+const CLEAR_LINE = '\r' + String.fromCharCode(27) + '[K';
+const program = new Command();
+program
+    .name('el-filtro')
+    .description('🔎 Escanea tus repos npm/pip y te dice, en lenguaje simple, qué dependencias arreglar ya')
+    .version('0.2.0')
+    .option('--path <ruta>', 'carpeta raíz a escanear', '.')
+    .option('--json', 'salida JSON máquina-legible, sin colores ni progreso')
+    .option('--no-write', 'no escribir el reporte a disco')
+    .action(async (opts) => {
+    const root = resolve(opts.path);
+    // Un solo resolvedor para todo el escaneo: cachea packuments entre repos (la familia
+    // comparte muchas dependencias).
+    const resolveDeprecation = createDeprecationResolver();
+    const report = await scan(root, {
+        auditNpm: (repoPath) => auditNpmRepo(repoPath, runCommand, resolveDeprecation),
+        auditPip: (repoPath) => auditPipRepo(repoPath, runCommand, fetchOsvSeverities),
+        onProgress: opts.json
+            ? undefined
+            : (current, total, name) => {
+                // Progreso en stderr para no ensuciar stdout (§11).
+                process.stderr.write(`${CLEAR_LINE}  Escaneando repo ${current}/${total}: ${name}...`);
+            },
+    });
+    if (!opts.json)
+        process.stderr.write(CLEAR_LINE); // limpia la línea de progreso
+    if (opts.json) {
+        console.log(renderJson(report));
+    }
+    else {
+        console.log(renderConsole(report, { colors: process.stdout.isTTY === true }));
+    }
+    if (opts.write !== false) {
+        const written = writeReport(report, root);
+        if (!opts.json)
+            console.log(`\nReporte guardado en: ${written}`);
+    }
+});
+program.parseAsync().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/discovery.js

@@ -0,0 +1,61 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectEcosystem } from './ecosystem.js';
+// Nunca se barren ni se tratan como repos candidatos.
+const ALWAYS_IGNORE = new Set(['node_modules', '.git']);
+function isRepo(dir) {
+    return existsSync(join(dir, '.git'));
+}
+/** Lee `exclude` de un `.el-filtro.json` en la raíz (config opcional, §6.1). */
+function readConfigExcludes(root) {
+    const p = join(root, '.el-filtro.json');
+    if (!existsSync(p))
+        return [];
+    try {
+        const cfg = JSON.parse(readFileSync(p, 'utf8'));
+        return Array.isArray(cfg.exclude)
+            ? cfg.exclude.filter((x) => typeof x === 'string')
+            : [];
+    }
+    catch {
+        return []; // config rota no debe tumbar el barrido
+    }
+}
+/**
+ * Barre `root` buscando repos (carpetas con `.git`). No desciende una vez hallado
+ * un repo (evita repos anidados y su node_modules) ni entra a node_modules (§6.1).
+ * Si el root mismo es un repo, lo devuelve a él. Orden determinístico.
+ */
+export function discoverRepos(root, opts = {}) {
+    const exclude = new Set([...(opts.exclude ?? []), ...readConfigExcludes(root)]);
+    const found = [];
+    function walk(dir) {
+        if (isRepo(dir)) {
+            found.push(dir);
+            return; // no descender dentro de un repo
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // carpeta ilegible: se ignora, el resto sigue
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (ALWAYS_IGNORE.has(entry.name) || exclude.has(entry.name))
+                continue;
+            walk(join(dir, entry.name));
+        }
+    }
+    walk(root);
+    // Fallback: no todo proyecto auditable es un repo git propio. Caso real: proyectos pip
+    // con requirements.txt anidados dentro del repo de otra cosa. Si el barrido no encontró
+    // NINGÚN repo, y la carpeta apuntada es en sí un proyecto, se audita esa carpeta. Así
+    // funciona "párate en tu proyecto y corre el comando". Los subproyectos anidados dentro
+    // de un repo siguen fuera de alcance (limitación conocida).
+    if (found.length === 0 && detectEcosystem(root) !== 'none')
+        return [root];
+    return found.sort();
+}

package/dist/ecosystem.js

@@ -0,0 +1,38 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+// Marcadores de un repo Python (§6.2). npm se detecta aparte con package.json.
+const PIP_MARKERS = ['requirements.txt', 'pyproject.toml', 'Pipfile'];
+/**
+ * Detecta el ecosistema de un repo por sus archivos marcadores (§6.2). npm tiene
+ * precedencia: si hay package.json, es el motor de la Etapa 1. Un repo sin ninguno
+ * devuelve 'none' — se lista como "no aplica", nunca como error.
+ */
+export function detectEcosystem(repoPath) {
+    if (existsSync(join(repoPath, 'package.json')))
+        return 'npm';
+    if (PIP_MARKERS.some((marker) => existsSync(join(repoPath, marker))))
+        return 'pip';
+    return 'none';
+}
+function hasNpm(repoPath) {
+    return existsSync(join(repoPath, 'package.json'));
+}
+function hasPip(repoPath) {
+    return PIP_MARKERS.some((marker) => existsSync(join(repoPath, marker)));
+}
+/**
+ * Ecosistemas presentes que NO ganaron la precedencia de `detectEcosystem`.
+ *
+ * La regla es explícita: npm gana cuando conviven (mismo early return de arriba, fijado por
+ * test). Pero no debe ser silenciosa — una carpeta políglota tiene dependencias del otro
+ * ecosistema sin auditar, y El Filtro las reporta en vez de esconderlas. Auditar ambos
+ * queda fuera de esta versión: `ecosystem` es un valor único del contrato que lee El Repuesto.
+ */
+export function detectSecondaryEcosystems(repoPath) {
+    const primary = detectEcosystem(repoPath);
+    if (primary === 'npm' && hasPip(repoPath))
+        return ['pip'];
+    if (primary === 'pip' && hasNpm(repoPath))
+        return ['npm']; // inalcanzable hoy; explícito por si cambia la precedencia
+    return [];
+}

package/dist/osv.js

@@ -0,0 +1,80 @@
+/**
+ * Resolución de severidad para el motor pip.
+ *
+ * `pip-audit` NO expone severidad en su JSON (verificado con pip-audit 2.10.1: las únicas
+ * claves por vulnerabilidad son id/fix_versions/aliases/description, tanto con el servicio
+ * `pypi` como con `osv`). La API pública de OSV sí la trae, sin API key ni registro, y con
+ * el MISMO vocabulario que npm audit (CRITICAL/HIGH/MODERATE/LOW) — por eso `classify.ts`
+ * se reutiliza tal cual y 🔴/🟡 significan lo mismo en ambos ecosistemas.
+ */
+const OSV_QUERY_URL = 'https://api.osv.dev/v1/query';
+const LABELS = {
+    critical: 'critical',
+    high: 'high',
+    moderate: 'moderate',
+    low: 'low',
+};
+/** Etiqueta de OSV → severidad interna. Desconocida/ausente → null (nunca inventar). */
+export function normalizeOsvSeverity(label) {
+    if (typeof label !== 'string')
+        return null;
+    return LABELS[label.trim().toLowerCase()] ?? null;
+}
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : null;
+}
+/**
+ * Construye el índice id → severidad desde un `POST /v1/query` de OSV.
+ *
+ * Clave del diseño: solo las entradas GHSA traen `database_specific.severity`; las PYSEC
+ * (que son las que devuelve pip-audit) NO. Pero ambas se referencian mutuamente vía
+ * `aliases`, así que cada severidad se indexa bajo el id propio Y bajo todos sus alias —
+ * de ahí que un id PYSEC herede la severidad de su gemelo GHSA.
+ */
+export function severityIndexFromOsv(osvJson) {
+    const root = asRecord(osvJson);
+    const vulns = root?.vulns;
+    if (!Array.isArray(vulns))
+        return {};
+    const index = {};
+    for (const entry of vulns) {
+        const v = asRecord(entry);
+        if (!v)
+            continue;
+        const dbSpecific = asRecord(v.database_specific);
+        const severity = normalizeOsvSeverity(dbSpecific?.severity);
+        if (!severity)
+            continue;
+        if (typeof v.id === 'string')
+            index[v.id] = severity;
+        if (Array.isArray(v.aliases)) {
+            for (const alias of v.aliases) {
+                if (typeof alias === 'string' && !index[alias])
+                    index[alias] = severity;
+            }
+        }
+    }
+    return index;
+}
+/**
+ * BORDE de red: consulta OSV por paquete+versión (1 llamada por paquete vulnerable) y
+ * devuelve el índice de severidades. Nunca lanza: si no hay red o la respuesta es rara,
+ * devuelve {} y los hallazgos quedan con severidad desconocida (🟡 + explicación), sin
+ * tumbar la auditoría del repo.
+ */
+export const fetchOsvSeverities = async (packageName, version) => {
+    try {
+        const res = await fetch(OSV_QUERY_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ package: { name: packageName, ecosystem: 'PyPI' }, version }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok)
+            return {};
+        return severityIndexFromOsv(await res.json());
+    }
+    catch {
+        return {};
+    }
+};

package/dist/report.js

@@ -0,0 +1,149 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import picocolors from 'picocolors';
+const SCHEMA_VERSION = 1;
+const SEVERITY_ORDER = ['critical', 'high', 'moderate', 'low', 'info'];
+/**
+ * Envuelve los resultados por repo en el contrato JSON estable (§6.6) y calcula el
+ * resumen. Función pura: recibe `now` para ser determinística en tests. Invariantes:
+ * total === fixNow + canWait, y sum(bySeverity) === # hallazgos vulnerability.
+ */
+export function buildReport(root, repos, now = new Date()) {
+    const allFindings = repos.flatMap((r) => r.findings);
+    const reposAudited = repos.filter((r) => r.status === 'audited').length;
+    const bySeverity = { critical: 0, high: 0, moderate: 0, low: 0, info: 0 };
+    for (const f of allFindings) {
+        if (f.type === 'vulnerability' && f.severity)
+            bySeverity[f.severity] += 1;
+    }
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        tool: 'el-filtro',
+        generatedAt: now.toISOString(),
+        root,
+        summary: {
+            reposScanned: repos.length,
+            reposAudited,
+            reposSkipped: repos.length - reposAudited,
+            findings: {
+                total: allFindings.length,
+                fixNow: allFindings.filter((f) => f.bucket === 'fix-now').length,
+                canWait: allFindings.filter((f) => f.bucket === 'can-wait').length,
+            },
+            bySeverity,
+            unknownSeverity: allFindings.filter((f) => f.type === 'vulnerability' && !f.severity).length,
+            abandonedPackages: allFindings.filter((f) => f.type === 'deprecated').length,
+        },
+        // Normalizado: el JSON siempre trae secondaryEcosystems, unresolvedAdvisories y fix,
+        // aunque vengan vacíos/en cero/null — contrato estable para El Repuesto. Que `fix`
+        // esté SIEMPRE presente es lo que le permite distinguir "reporte viejo sin el campo"
+        // de "hallazgo sin versión objetivo".
+        repos: repos.map((r) => ({
+            ...r,
+            secondaryEcosystems: r.secondaryEcosystems ?? [],
+            findings: r.findings.map((f) => ({
+                ...f,
+                unresolvedAdvisories: f.unresolvedAdvisories ?? 0,
+                fix: f.fix ?? null,
+            })),
+        })),
+    };
+}
+/** Salida JSON máquina-legible (el contrato que consume El Repuesto). */
+export function renderJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+const HEADER_BOX = [
+    '╔════════════════════════════════════════╗',
+    '║   🔎  EL FILTRO — Dependencias          ║',
+    '╚════════════════════════════════════════╝',
+].join('\n');
+function findingLine(repo, f) {
+    const version = f.installedVersions[0] ? ` ${f.installedVersions[0]}` : '';
+    // Una vulnerabilidad sin severidad resuelta (pip sin dato en OSV) se nombra en palabras,
+    // no con un paréntesis vacío.
+    const tag = f.type === 'deprecated' ? 'abandonado' : (f.severity ?? 'gravedad desconocida');
+    return `  • ${repo.name} › ${f.package}${version}  (${tag})`;
+}
+/**
+ * Aviso cuando la gravedad de un paquete quedó resuelta a medias: la severidad mostrada es
+ * la más alta de las que SÍ se resolvieron, así que la real podría ser mayor. Solo se dice
+ * si además hay una severidad mostrada — si no hay ninguna, la explicación ya lo cubre.
+ */
+function unresolvedNote(f) {
+    const n = f.unresolvedAdvisories ?? 0;
+    if (n === 0 || !f.severity)
+        return null;
+    return `(${n} advisor${n === 1 ? 'y' : 'ies'} sin evaluar: la gravedad real podría ser mayor)`;
+}
+/** Resumen humano agrupado por los 2 buckets, con desglose por repo (§6.6). */
+export function renderConsole(report, opts = {}) {
+    const pc = picocolors.createColors(opts.colors ?? false);
+    const s = report.summary;
+    const lines = [HEADER_BOX, ''];
+    lines.push(`Carpeta: ${report.root}`);
+    lines.push(`Repos escaneados: ${s.reposScanned}  ·  auditados: ${s.reposAudited}  ·  sin auditar: ${s.reposSkipped}`);
+    lines.push(`Hallazgos: ${s.findings.total}   ${pc.red(`🔴 ${s.findings.fixNow} arréglalo ya`)}   ${pc.yellow(`🟡 ${s.findings.canWait} pueden esperar`)}`);
+    const withFindings = report.repos.filter((r) => r.findings.length > 0);
+    const collect = (bucket) => withFindings.flatMap((r) => r.findings.filter((f) => f.bucket === bucket).map((f) => ({ r, f })));
+    const fixNow = collect('fix-now');
+    const canWait = collect('can-wait');
+    lines.push('', pc.red(`🔴 ARRÉGLALO YA (${fixNow.length})`));
+    if (fixNow.length === 0)
+        lines.push(pc.dim('  (nada urgente)'));
+    for (const { r, f } of fixNow) {
+        lines.push(findingLine(r, f));
+        lines.push(pc.dim(`      ${f.explanation}`));
+        const nota = unresolvedNote(f);
+        if (nota)
+            lines.push(pc.dim(`      ${nota}`));
+    }
+    lines.push('', pc.yellow(`🟡 PUEDEN ESPERAR (${canWait.length})`));
+    if (canWait.length === 0)
+        lines.push(pc.dim('  (nada por aquí)'));
+    for (const { r, f } of canWait) {
+        lines.push(findingLine(r, f));
+        const nota = unresolvedNote(f);
+        if (nota)
+            lines.push(pc.dim(`      ${nota}`));
+    }
+    const notAudited = report.repos.filter((r) => r.status === 'no-audit');
+    if (notAudited.length > 0) {
+        lines.push('', 'Repos sin auditar:');
+        for (const r of notAudited) {
+            lines.push(`  • ${r.name} — ${r.statusReason ?? 'razón desconocida'}`);
+        }
+    }
+    const pending = report.repos.filter((r) => r.status === 'pending');
+    if (pending.length > 0) {
+        lines.push('', 'Repos pendientes:');
+        for (const r of pending) {
+            lines.push(`  • ${r.name} — ${r.statusReason ?? 'pendiente'}`);
+        }
+    }
+    // La precedencia de ecosistema no es silenciosa: si el repo también tiene dependencias
+    // del otro ecosistema, se dice. Esconderlas sería ocultar deuda sin auditar.
+    const poliglotas = report.repos.filter((r) => (r.secondaryEcosystems ?? []).length > 0);
+    if (poliglotas.length > 0) {
+        lines.push('', 'Con dependencias de otro ecosistema (no auditadas en esta versión):');
+        for (const r of poliglotas) {
+            lines.push(`  • ${r.name} — también tiene dependencias ${r.secondaryEcosystems.join(', ')}`);
+        }
+    }
+    return lines.join('\n');
+}
+function safeTimestamp(iso) {
+    return iso.replace(/[:.]/g, '-'); // Windows no permite ':' en nombres de archivo
+}
+/**
+ * Escribe el reporte JSON en `<baseDir>/.el-filtro/report-<ts>.json` y devuelve la
+ * ruta escrita. Borde de I/O — cubierto por su test de temp dir y por e2e.
+ */
+export function writeReport(report, baseDir) {
+    const dir = join(baseDir, '.el-filtro');
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `report-${safeTimestamp(report.generatedAt)}.json`);
+    writeFileSync(file, renderJson(report));
+    return file;
+}
+export { SEVERITY_ORDER };

package/dist/runners/exec.js

@@ -0,0 +1,47 @@
+/**
+ * Adaptador de I/O para correr procesos reales (npm). Es el BORDE: no se testea por
+ * unidad; la lógica que lo usa se prueba con fakes de esta misma firma, y este
+ * adaptador queda cubierto por el e2e y la demo real.
+ *
+ * Nunca rechaza por exit code ≠ 0 (npm audit sale con 1 cuando HAY vulnerabilidades,
+ * lo cual es normal): devuelve el `code` para que la capa de arriba decida. Solo
+ * rechaza si el binario no se pudo lanzar (ENOENT). Mismo patrón que Las Llantas.
+ */
+import { execFile } from 'node:child_process';
+/** true si el error es "no se pudo lanzar el binario" (binario ausente). */
+function isSpawnFailure(err) {
+    const e = err;
+    return typeof e?.code === 'string' && typeof e.syscall === 'string' && e.syscall.startsWith('spawn');
+}
+// Solo tokens simples: letras, dígitos y `-_@:./\+=~,`. Sin espacios ni metacaracteres.
+const SAFE_ARG = /^[\w@:./\\+=~,-]*$/;
+export function isShellSafeArg(arg) {
+    return SAFE_ARG.test(arg);
+}
+/**
+ * Con shell:true (necesario en Windows para resolver npm.cmd) Node NO escapa los
+ * argumentos. Esta barrera impide que un valor externo se vuelva un comando aparte
+ * vía `&`, `;`, `|`… El cwd (que sí puede tener espacios) va como opción, no como arg.
+ */
+function assertShellSafe(command, args) {
+    for (const value of [command, ...args]) {
+        if (!isShellSafeArg(value)) {
+            throw new Error(`Argumento no seguro para exec (posible inyección de comandos): ${JSON.stringify(value)}.`);
+        }
+    }
+}
+export const runCommand = (command, args, options = {}) => {
+    assertShellSafe(command, args);
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { cwd: options.cwd, shell: process.platform === 'win32', maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error && isSpawnFailure(error)) {
+                reject(error);
+                return;
+            }
+            const code = error && typeof error.code === 'number'
+                ? error.code
+                : 0;
+            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+};