parche-cli 0.0.0-stage → 0.5.1

package/src/packs.js

@@ -0,0 +1,55 @@
+// Carga de packs (la base de cambios) y el registro de transformaciones.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import arca from './codemods/arca-wsfe-condicion-iva.js';
+import arcaPhp from './codemods/arca-wsfe-condicion-iva-php.js';
+import mercadopago from './codemods/mercadopago-payments-to-orders.js';
+import aiModels from './detectors/ai-model-retirements.js';
+import { wsdlDetection, soapOnly } from './codemods/arca-rules.js';
+import { isPhp } from './php.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const PACKS_DIR = path.join(HERE, '..', 'packs');
+
+// Una transformación por pack y por lenguaje. Si un pack no tiene versión para un lenguaje,
+// ese pack no corre sobre esos archivos.
+const TRANSFORMS = {
+  // js y php: codemod; wsdl: WSDL de WSFEv1 sin el campo; text (Python, C#, Java, Go, VB.NET): solo SOAP propio.
+  'arca.wsfe.condicion-iva-receptor': { js: arca, php: arcaPhp, wsdl: wsdlDetection, text: soapOnly },
+  'mercadopago.payments-to-orders': { js: mercadopago },
+  'ai.model-retirements': { js: aiModels, php: aiModels, text: aiModels }, // detector de texto: sirve para cualquier lenguaje
+};
+
+const TEXT_ONLY = /\.(py|cs|java|go|vb)$/i;
+
+export function languageOf(file) {
+  if (isPhp(file)) return 'php';
+  if (/\.wsdl$/i.test(file)) return 'wsdl';
+  if (TEXT_ONLY.test(file)) return 'text';
+  return 'js';
+}
+
+export const REQUIRED_FIELDS = ['id', 'version', 'provider', 'title', 'kind', 'severity', 'deadline', 'last_verified',
+  'summary_es', 'why_es', 'sources', 'detect', 'codemod', 'review_checklist_es'];
+
+export function validatePack(pack) {
+  const missing = REQUIRED_FIELDS.filter((f) => !(f in pack));
+  if (missing.length) throw new Error(`Pack ${pack.id || '?'}: faltan campos ${missing.join(', ')}`);
+  if (!Array.isArray(pack.sources) || pack.sources.some((s) => !s.url)) throw new Error(`Pack ${pack.id}: sources inválidas`);
+  if (!['critical', 'high', 'medium', 'low'].includes(pack.severity)) throw new Error(`Pack ${pack.id}: severity inválida`);
+  return true;
+}
+
+export function loadPacks(dir = PACKS_DIR) {
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')))
+    .map((p) => (validatePack(p), p))
+    .sort((a, b) => (a.deadline || '9999').localeCompare(b.deadline || '9999'));
+}
+
+export function transformFor(packId, file = 'x.js') {
+  const byLang = TRANSFORMS[packId];
+  return (byLang && byLang[languageOf(file)]) || null;
+}

package/src/paths.js

@@ -0,0 +1,37 @@
+// Rutas y carpetas compartidas por el motor y el inventario.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Carpetas que no son código del cliente: dependencias instaladas (vendor/ es donde composer instala
+// las de PHP, incluida la propia librería de ARCA), builds y lo que escribe Parche.
+export const SKIP_DIRS = new Set(['node_modules', 'vendor', '.git', 'dist', 'build', 'coverage', '.next', '.parche']);
+
+// Rutas siempre con "/": van al reporte, al cuerpo del PR y al inventario.
+export const toPosix = (p) => p.split(path.sep).join('/');
+
+// Tests, mocks, fixtures y ejemplos: un PR que solo toca eso no le sirve al mantenedor, y la detección
+// por texto en esos archivos es ruido (frente B, 16/10).
+export function isTestFile(file) {
+  return /(^|\/)(__tests__|__mocks__|tests?|specs?|mocks?|fixtures?|examples?)\//i.test(file)
+    || /\.(test|spec|mock)\.[cm]?[jt]sx?$/i.test(file) || /Test\.php$/.test(file);
+}
+
+// Recorre el repo (salteando SKIP_DIRS) y devuelve las rutas relativas, con "/", de los archivos que
+// cumplen `match(nombre)`.
+export function findFiles(root, match) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name)); }
+      else if (match(e.name)) out.push(toPosix(path.relative(root, path.join(dir, e.name))));
+    }
+  };
+  walk(root);
+  return out.sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+}

package/src/php.js

@@ -0,0 +1,52 @@
+// Lectura de PHP con php-parser (glayzzle).
+// A diferencia de recast, php-parser lee el texto original: loc.start.offset y loc.end.offset son
+// posiciones exactas en el archivo del cliente, también con CRLF, tabs y acentos (lo cubren los tests).
+// Por eso acá se edita con esos offsets y no con offsetAt(), que corrige las particularidades de recast.
+import PhpParser from 'php-parser';
+
+const engine = new PhpParser.Engine({
+  parser: { php8: true, suppressErrors: false, extractDoc: false },
+  ast: { withPositions: true, withSource: false },
+});
+
+export function parsePhp(source, file = 'archivo.php') {
+  return engine.parseCode(source, file);
+}
+
+const SCOPE_KINDS = new Set(['function', 'method', 'closure', 'arrowfunc']);
+
+// Recorre el AST y llama visit(node, scope), donde scope es la función, el método, la closure
+// o el programa que contiene al nodo (en PHP las variables no cruzan esos límites).
+export function walkPhp(node, visit, scope = node) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const n of node) walkPhp(n, visit, scope);
+    return;
+  }
+  if (!node.kind) return;
+  visit(node, scope);
+  const inner = SCOPE_KINDS.has(node.kind) ? node : scope;
+  for (const [k, v] of Object.entries(node)) {
+    if (k === 'loc' || k === 'leadingComments' || k === 'trailingComments') continue;
+    walkPhp(v, visit, inner);
+  }
+}
+
+// Valor de un literal: número (también '99' entre comillas, que PHP convierte), string o booleano.
+// undefined si no es un literal (constante, variable, llamada...).
+export function phpLiteral(node) {
+  if (!node) return undefined;
+  if (node.kind === 'number') return Number(node.value);
+  if (node.kind === 'string') return /^-?\d+$/.test(node.value) ? Number(node.value) : node.value;
+  if (node.kind === 'boolean') return node.value;
+  return undefined;
+}
+
+// Clave de un elemento de array si es un string literal ('DocTipo' => ...); null si no.
+export function phpKey(entry) {
+  return entry && entry.key && entry.key.kind === 'string' ? entry.key.value : null;
+}
+
+export function isPhp(file) {
+  return /\.php$/i.test(file);
+}

package/src/report.js

@@ -0,0 +1,144 @@
+// Reporte del scan y cuerpo del PR, en castellano.
+import { apiLabel } from './inventory/index.js';
+
+const LABEL ={
+  auto: '✅ automático',
+  'needs-review': '👀 revisar',
+  'needs-input': '✋ falta un dato',
+  blocked: '⛔ bloqueado',
+  'detect-only': '🔎 detectado',
+};
+const SEVERITY = { critical: 'crítica', high: 'alta', medium: 'media', low: 'baja' };
+
+export function daysUntil(date, today = new Date()) {
+  if (!date) return null;
+  const ms = new Date(date + 'T00:00:00-03:00') - today;
+  return Math.ceil(ms / 86400000);
+}
+
+function deadlineText(pack, today) {
+  if (!pack.deadline) return 'sin fecha límite';
+  const d = daysUntil(pack.deadline, today);
+  return d >= 0 ? `${pack.deadline} (faltan ${d} días)` : `${pack.deadline} (vencida hace ${-d} días)`;
+}
+
+export function counts(findings) {
+  const c = {};
+  for (const f of findings) c[f.status] = (c[f.status] || 0) + 1;
+  return c;
+}
+
+function upgradesSection(upgrades) {
+  const out = ['## Versiones nuevas de tus SDKs de npm', '',
+    'Comparación de la API pública (tipos `.d.ts`) entre la versión instalada y la última publicada, cruzada con lo que usa este repo. Solo avisa: no cambia código.', '',
+    '| SDK | Instalada → última | Resultado |', '|---|---|---|'];
+  const STATUS = {
+    afectado: (r) => `⚠ ${r.affected.length} operación(es) del repo cambian o desaparecen`,
+    'sin-impacto': (r) => `✓ lo que usás no cambia (${r.totalChanges} cambios en el SDK)`,
+    'al-dia': () => '✓ al día',
+    'sin-verificar': () => '? tus operaciones no aparecen en los tipos instalados',
+  };
+  for (const r of upgrades) {
+    const res = STATUS[r.status] ? STATUS[r.status](r) : `— ${r.error || 'sin versión instalada'}`;
+    out.push(`| \`${r.package}\` | ${r.installed ? `${r.installed} → ${r.latest}` : '—'} | ${res} |`);
+  }
+  out.push('');
+  for (const r of upgrades.filter((x) => x.status === 'afectado')) {
+    out.push(`### \`${r.package}\` ${r.installed} → ${r.latest}`, '');
+    for (const a of r.affected) {
+      out.push(`- \`${a.op}\` (${a.locations.map((l) => `\`${l.file}:${l.line}\``).join(', ')}): ${a.changes.map((c) => c.message).join(' ')}`);
+    }
+    out.push('');
+  }
+  return out;
+}
+
+export function scanReport({ inventory, findings, packs, changed, upgrades = null }, today = new Date()) {
+  const out = [];
+  out.push(`# Parche — reporte de \`${inventory.repo}\``, '');
+  out.push('## APIs que usa este repo', '');
+  out.push('Todas las APIs de terceros que se encontraron en el código, tengan pack de Parche o no.', '');
+  if (inventory.apis.length) {
+    const KIND = { sdk: 'SDK', http: 'HTTP directo', 'ai-model': 'Modelos de IA' };
+    out.push('| Tipo | API | Rubro | Confianza | Operaciones (usos) | Pack |', '|---|---|---|---|---|---|');
+    for (const api of inventory.apis) {
+      const ops = api.operations.map((o) => `\`${o.op}\` ×${o.count}`).join(', ') || 'declarada, sin usos encontrados';
+      out.push(`| ${KIND[api.kind]} | ${apiLabel(api)} | ${api.category || '—'} | ${api.confidence} | ${ops} | ${api.packs.length ? 'sí' : '—'} |`);
+    }
+    out.push('');
+  } else {
+    out.push('No se encontraron APIs de terceros.', '');
+  }
+  if (inventory.unresolved.length) {
+    out.push('**Llamadas HTTP con URL dinámica** (no se puede saber a qué host van):', '',
+      ...inventory.unresolved.map((u) => `- \`${u.file}:${u.line}\` (${u.client})`), '');
+  }
+  if (upgrades) out.push(...upgradesSection(upgrades));
+  for (const pack of packs) {
+    const fs = findings.filter((f) => f.pack === pack.id);
+    if (!fs.length) continue;
+    out.push(`## ${pack.title}`, '');
+    out.push(`**Proveedor:** ${pack.provider} · **Severidad:** ${SEVERITY[pack.severity]} · **Fecha límite:** ${deadlineText(pack, today)}`, '');
+    out.push(pack.summary_es, '');
+    for (const f of fs) {
+      out.push(`- ${LABEL[f.status]} \`${f.file}${f.line ? `:${f.line}` : ''}\` — ${f.message}`);
+      if (f.suggestion) out.push(`  - Sugerido: \`${f.suggestion}\``);
+    }
+    out.push('');
+  }
+  if (changed && changed.length) {
+    out.push('## Archivos modificados', '', ...changed.map((c) => `- \`${c.file}\` (${c.packs.join(', ')})`), '');
+  }
+  return out.join('\n');
+}
+
+export function prBody({ pack, findings, changed, verification }, today = new Date()) {
+  const fs = findings.filter((f) => f.pack === pack.id);
+  const c = counts(fs);
+  const out = [];
+  out.push(`## ${pack.title}`, '');
+  out.push(`> **${pack.provider}** · severidad ${SEVERITY[pack.severity]} · fecha límite: ${deadlineText(pack, today)}`, '');
+  out.push('### Qué cambió', '', pack.why_es, '');
+  // Sin cambios de código el texto se usa como issue: los títulos no pueden hablar de "este PR".
+  const asIssue = !changed.length;
+  out.push(asIssue ? '### Qué encontró Parche' : '### Qué hace este PR', '');
+  const applied = fs.filter((f) => f.status === 'auto' || f.status === 'needs-review');
+  out.push(changed.length
+    ? `Modifica ${changed.length} archivo(s): ${changed.map((x) => `\`${x.file}\``).join(', ')}.`
+    : 'No hay un arreglo automático seguro: esto es lo que hay que resolver a mano.', '');
+  for (const f of applied) out.push(`- ${LABEL[f.status]} \`${f.file}:${f.line}\` — ${f.message}`);
+  const pending = fs.filter((f) => f.status === 'needs-input' || f.status === 'blocked');
+  if (pending.length) {
+    out.push('', asIssue ? '### Lo que hay que resolver (necesita una persona)' : '### Lo que este PR NO resuelve (necesita una persona)', '');
+    for (const f of pending) {
+      out.push(`- ${LABEL[f.status]} \`${f.file}:${f.line}\` — ${f.message}`);
+      if (f.suggestion) out.push(`  - Agregá: \`${f.suggestion}\``);
+    }
+  }
+  // Un issue no cambia código: no hay verificación que mostrar (antes decía "Sin verificar").
+  if (!asIssue) {
+    out.push('', '### Verificación', '');
+    if (verification) {
+      out.push(`- Sintaxis de los archivos modificados: ${verification.parse.ok ? '✅ OK' : '❌ ' + verification.parse.errors.join('; ')}`);
+      const t = verification.tests;
+      if (t?.notRun) {
+        // Lo que escribió a mano el frente B en el primer PR real (obraya), ahora lo dice Parche.
+        out.push(t.ci.length
+          ? `- Tests del repo: Parche no los corrió; los corre el CI de este repo (${t.ci.map((w) => `\`${w}\``).join(', ')}) en este PR.`
+          : '- Tests del repo: Parche no los corrió (sin `--verify` no ejecuta código del repo). Corrélos antes de mergear.');
+      } else if (t) {
+        out.push(t.skipped
+          ? '- Tests del repo: — no hay tests para correr; se validó la sintaxis de los archivos modificados.'
+          : `- Tests del repo (${t.commands.map((c) => `\`${c}\``).join(' y ')}): ${t.ok ? '✅ pasan' : '❌ fallan'}`);
+      }
+    } else {
+      out.push('- Sin verificar (corré `parche pr --verify`).');
+    }
+  }
+  out.push('', asIssue ? '### Checklist' : '### Checklist antes de mergear', '', ...pack.review_checklist_es.map((x) => `- [ ] ${x}`), '');
+  out.push('### Fuentes', '', ...pack.sources.map((s) => `- [${s.title}](${s.url})`), '');
+  out.push(`<sub>Pack \`${pack.id}\` v${pack.version}, verificado el ${pack.last_verified}. Resumen: ${Object.entries(c).map(([k, v]) => `${LABEL[k]} ${v}`).join(' · ')}. ¿Este PR te sirvió? Mergealo, editalo o cerralo: Parche aprende de cada resultado.</sub>`, '');
+  return out.join('\n');
+}
+
+export { LABEL };

package/src/sdk-diff/compare.js

@@ -0,0 +1,121 @@
+// Comparación de dos superficies de un SDK (surface.js) y cruce con las operaciones que usa el repo.
+// Todo lo que sale de acá es detect-only: avisa qué cambia, no reescribe código (nivel 1).
+
+const NS = ['default', 'exports'];
+
+const required = (sig) => sig.params.filter((p) => !p.optional).length;
+const minRequired = (sigs) => Math.min(...sigs.map(required));
+const maxParams = (sigs) => Math.max(...sigs.map((s) => s.params.length));
+const hasRest = (sigs) => sigs.some((s) => s.params.some((p) => p.rest));
+const short = (t) => (t.length > 80 ? `${t.slice(0, 77)}...` : t);
+
+// Cambios entre la superficie vieja (a) y la nueva (b).
+// → [{ ns, path, type: 'removed' | 'new-required' | 'param-removed' | 'type-changed' | 'deprecated', message }]
+export function diffSurfaces(a, b) {
+  const changes = [];
+  for (const ns of NS) {
+    // Si la versión nueva no expone nada en este lado (pasa cuando cambia la forma del módulo, por ejemplo de
+    // exports con nombre a `export =`), no se puede distinguir "se borró" de "no se pudo leer": no se compara.
+    if (b[ns].size === 0 && a[ns].size > 0) continue;
+    const removedRoots = [];
+    for (const [p, ea] of a[ns]) {
+      if (removedRoots.some((r) => p.startsWith(`${r}.`))) continue; // ya se reportó el padre
+      const eb = b[ns].get(p);
+      if (!eb) {
+        removedRoots.push(p);
+        changes.push({ ns, path: p, type: 'removed', message: `\`${p}\` ya no existe.` });
+        continue;
+      }
+      if (ea.signatures && eb.signatures) changes.push(...compareSignatures(ns, p, ea.signatures, eb.signatures));
+      if (eb.deprecated && !ea.deprecated) {
+        changes.push({ ns, path: p, type: 'deprecated', message: `\`${p}\` pasó a estar deprecado${eb.deprecated !== 'deprecado' ? `: ${short(eb.deprecated)}` : '.'}` });
+      }
+    }
+  }
+  return changes;
+}
+
+function compareSignatures(ns, p, sa, sb) {
+  const out = [];
+  const reqA = minRequired(sa);
+  const reqB = minRequired(sb);
+  if (reqB > reqA) {
+    const best = sb.find((s) => required(s) === reqB);
+    const oldNames = new Set(sa.flatMap((s) => s.params.filter((x) => !x.optional).map((x) => x.name)));
+    const nuevos = best.params.filter((x) => !x.optional && !oldNames.has(x.name)).map((x) => x.name);
+    out.push({ ns, path: p, type: 'new-required',
+      message: `\`${p}\` pide más parámetros obligatorios (${reqA} → ${reqB}${nuevos.length ? `: ${nuevos.join(', ')}` : ''}).` });
+  }
+  if (!hasRest(sb) && maxParams(sb) < maxParams(sa)) {
+    const newNames = new Set(sb.flatMap((s) => s.params.map((x) => x.name)));
+    const quitados = sa.flatMap((s) => s.params.map((x) => x.name)).filter((n, i, all) => !newNames.has(n) && all.indexOf(n) === i);
+    out.push({ ns, path: p, type: 'param-removed',
+      message: `\`${p}\` acepta menos parámetros (${maxParams(sa)} → ${maxParams(sb)}${quitados.length ? `: se quitó ${quitados.join(', ')}` : ''}).` });
+  }
+  // Tipos: solo con una firma de cada lado (con sobrecargas, comparar por posición confunde más de lo que ayuda).
+  if (sa.length === 1 && sb.length === 1) {
+    const n = Math.min(sa[0].params.length, sb[0].params.length);
+    for (let i = 0; i < n; i++) {
+      const pa = sa[0].params[i];
+      const pb = sb[0].params[i];
+      if (pa.type !== pb.type) {
+        out.push({ ns, path: p, type: 'type-changed',
+          message: `En \`${p}\`, el parámetro \`${pb.name}\` cambió de tipo: \`${short(pa.type)}\` → \`${short(pb.type)}\`.` });
+      }
+    }
+  }
+  return out;
+}
+
+// ¿En qué parte de la superficie vieja vive esta operación? La ruta exacta o, si no, su prefijo más largo.
+function namespaceOf(op, surface) {
+  let best = null;
+  for (const ns of NS) {
+    const parts = op.split('.');
+    for (let i = parts.length; i > 0; i--) {
+      const pre = parts.slice(0, i).join('.');
+      if (surface[ns].has(pre)) {
+        if (!best || i > best.depth) best = { ns, depth: i };
+        break;
+      }
+    }
+  }
+  return best && best.ns;
+}
+
+// Para mostrar y contar: el mismo cambio suele verse por varios caminos (la instancia del export por defecto,
+// la clase exportada y la fábrica: clientes.borrar, Cliente.clientes.borrar, crearCliente.clientes.borrar).
+// Se queda con el más corto. El cruce con el repo usa la lista completa, porque el repo puede usar cualquiera.
+export function dedupeChanges(changes) {
+  const seen = new Set(changes.filter((c) => c.ns === 'default').map((c) => `${c.type}|${c.path}`));
+  const out = [];
+  for (const c of changes) {
+    if (c.ns === 'exports') {
+      const rest = c.path.split('.').slice(1).join('.');
+      if (rest && seen.has(`${c.type}|${rest}`)) continue;
+      const key = `${c.type}|${rest || c.path}`;
+      if (rest && seen.has(`x|${key}`)) continue;
+      if (rest) seen.add(`x|${key}`);
+    }
+    out.push(c);
+  }
+  return out;
+}
+
+// Operaciones del repo que no aparecen en los tipos de la versión instalada: sobre esas no se puede afirmar nada.
+export function unverifiedOperations(operations, oldSurface) {
+  return operations.filter((op) => !namespaceOf(op, oldSurface));
+}
+
+// Operaciones del repo (del inventario) que tocan un cambio: la misma ruta, o una ruta padre que desapareció.
+// → [{ op, changes: [...] }]  (solo las operaciones afectadas)
+export function affectedOperations(changes, operations, oldSurface) {
+  const out = [];
+  for (const op of operations) {
+    const ns = namespaceOf(op, oldSurface);
+    if (!ns) continue; // la operación no está en los tipos de la versión instalada: no se puede afirmar nada
+    const hits = changes.filter((c) => c.ns === ns && (c.path === op || (c.type === 'removed' && op.startsWith(`${c.path}.`))));
+    if (hits.length) out.push({ op, changes: hits });
+  }
+  return out;
+}

package/src/sdk-diff/registry.js

@@ -0,0 +1,142 @@
+// Acceso al registry de npm para comparar versiones de un SDK: metadata, tarballs (con verificación
+// de integridad) y los archivos de tipos de cada versión. Todo queda cacheado en ~/.parche/cache:
+// los tarballs son inmutables, así que una versión se baja una sola vez.
+//
+// PARCHE_CACHE cambia la carpeta del caché; PARCHE_OFFLINE=1 usa solo el caché (lo usan los tests).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { extractTypes } from './tar.js';
+
+const REGISTRY = 'https://registry.npmjs.org';
+const METADATA_TTL_MS = 60 * 60 * 1000;
+
+export function defaultCacheDir() {
+  return process.env.PARCHE_CACHE || path.join(os.homedir(), '.parche', 'cache');
+}
+
+const safeName = (pkg) => pkg.replace('/', '__');
+
+export function createRegistry({ cacheDir = defaultCacheDir(), fetch = globalThis.fetch, offline = process.env.PARCHE_OFFLINE === '1' } = {}) {
+  const dirFor = (pkg) => path.join(cacheDir, safeName(pkg));
+
+  async function metadata(pkg) {
+    const file = path.join(dirFor(pkg), 'metadata.json');
+    if (fs.existsSync(file)) {
+      const fresh = Date.now() - fs.statSync(file).mtimeMs < METADATA_TTL_MS;
+      if (offline || fresh) return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    if (offline) throw new Error(`Sin conexión y sin metadata de ${pkg} en el caché (${file}).`);
+    const res = await fetch(`${REGISTRY}/${pkg.replace('/', '%2F')}`, { headers: { Accept: 'application/json' } });
+    if (!res.ok) throw new Error(`El registry respondió ${res.status} para ${pkg}.`);
+    const json = await res.json();
+    // Solo lo que hace falta: versiones con su tarball e integridad, y los dist-tags.
+    const slim = {
+      name: json.name,
+      'dist-tags': json['dist-tags'] || {},
+      versions: Object.fromEntries(Object.entries(json.versions || {}).map(([v, m]) => [v, { dist: { tarball: m.dist?.tarball, integrity: m.dist?.integrity } }])),
+    };
+    fs.mkdirSync(dirFor(pkg), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(slim));
+    return slim;
+  }
+
+  async function tarball(pkg, version) {
+    const file = path.join(dirFor(pkg), `${version}.tgz`);
+    if (fs.existsSync(file)) return fs.readFileSync(file);
+    if (offline) throw new Error(`Sin conexión y sin ${pkg}@${version} en el caché (${file}).`);
+    const meta = await metadata(pkg);
+    const dist = meta.versions[version]?.dist;
+    if (!dist?.tarball) throw new Error(`${pkg}@${version} no existe en el registry.`);
+    const res = await fetch(dist.tarball);
+    if (!res.ok) throw new Error(`No se pudo bajar ${pkg}@${version} (${res.status}).`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    // Integridad: el hash tiene que coincidir con el que publica el registry.
+    if (dist.integrity) {
+      const [algo, expected] = dist.integrity.split(/-(.*)/s);
+      const actual = crypto.createHash(algo).update(buf).digest('base64');
+      if (actual !== expected) throw new Error(`La integridad de ${pkg}@${version} no coincide: no se usa.`);
+    }
+    fs.mkdirSync(dirFor(pkg), { recursive: true });
+    fs.writeFileSync(file, buf);
+    return buf;
+  }
+
+  // Archivos de tipos de una versión: los propios del paquete o, si no tiene, los de @types/<paquete>
+  // de la misma versión mayor. → { files: Map, entry, source: 'paquete' | '@types/...' } | null
+  async function types(pkg, version) {
+    const own = extractTypes(await tarball(pkg, version));
+    const entry = typesEntry(own);
+    if (entry) return { files: own, entry, source: pkg };
+    const typesPkg = `@types/${pkg.startsWith('@') ? pkg.slice(1).replace('/', '__') : pkg}`;
+    let meta;
+    try {
+      meta = await metadata(typesPkg);
+    } catch {
+      return null;
+    }
+    const major = version.split('.')[0];
+    const candidates = Object.keys(meta.versions).filter((v) => v.split('.')[0] === major && !v.includes('-')).sort(compareVersions);
+    const pick = candidates[candidates.length - 1];
+    if (!pick) return null;
+    const files = extractTypes(await tarball(typesPkg, pick));
+    const typesEntryFile = typesEntry(files);
+    return typesEntryFile ? { files, entry: typesEntryFile, source: `${typesPkg}@${pick}` } : null;
+  }
+
+  return { metadata, tarball, types };
+}
+
+// Archivo de entrada de los tipos según el package.json (types, typings o exports) o index.d.ts.
+export function typesEntry(files) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(files.get('package.json') || '{}');
+  } catch { /* package.json roto: se busca index.d.ts */ }
+  const fromExports = typesInExports(pkg.exports);
+  const candidates = [pkg.types, pkg.typings, fromExports, 'index.d.ts'].filter((x) => typeof x === 'string');
+  for (const c of candidates) {
+    const norm = c.replace(/^\.\//, '');
+    const withExt = /\.d\.(ts|mts|cts)$/.test(norm) ? norm : `${norm.replace(/\.(js|mjs|cjs)$/, '')}.d.ts`;
+    if (files.has(withExt)) return withExt;
+  }
+  return null;
+}
+
+// `types` dentro de `exports`, que puede ser { ".": {...} } o directamente un objeto de condiciones
+// anidadas (stripe 23: exports.default.require.types). Se prefiere lo de Node/CommonJS.
+const CONDITION_ORDER = ['types', 'require', 'node', 'default', 'import'];
+export function typesInExports(exp, depth = 0) {
+  if (!exp || typeof exp !== 'object' || depth > 5) return null;
+  if (Array.isArray(exp)) {
+    for (const e of exp) { const t = typesInExports(e, depth + 1); if (t) return t; }
+    return null;
+  }
+  if ('.' in exp) return typeof exp['.'] === 'string' ? null : typesInExports(exp['.'], depth + 1);
+  if (Object.keys(exp).some((k) => k.startsWith('./'))) return null; // solo subrutas: no hay entrada principal
+  if (typeof exp.types === 'string') return exp.types;
+  const keys = Object.keys(exp).sort((a, b) => {
+    const ia = CONDITION_ORDER.indexOf(a);
+    const ib = CONDITION_ORDER.indexOf(b);
+    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+  });
+  for (const k of keys) {
+    const t = typesInExports(exp[k], depth + 1);
+    if (t) return t;
+  }
+  return null;
+}
+
+// Comparación de versiones semver simples (x.y.z); las prereleases van antes que la estable.
+export function compareVersions(a, b) {
+  const pa = a.split(/[.-]/);
+  const pb = b.split(/[.-]/);
+  for (let i = 0; i < 3; i++) {
+    const d = Number(pa[i] || 0) - Number(pb[i] || 0);
+    if (d) return d;
+  }
+  const preA = a.includes('-');
+  const preB = b.includes('-');
+  return preA === preB ? a.localeCompare(b) : preA ? -1 : 1;
+}