parche-cli 0.1.1 → 0.5.1

package/src/report.js

@@ -1,5 +1,7 @@
 // Reporte del scan y cuerpo del PR, en castellano.
-const LABEL = {
+import { apiLabel } from './inventory/index.js';
+
+const LABEL ={
   auto: '✅ automático',
   'needs-review': '👀 revisar',
   'needs-input': '✋ falta un dato',
@@ -26,16 +28,52 @@ export function counts(findings) {
   return c;
 }
 
-export function scanReport({ inventory, findings, packs, changed }, today = new Date()) {
+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', '');
-  const pk = Object.entries(inventory.packages);
-  if (pk.length) out.push(...pk.map(([n, v]) => `- \`${n}\` ${v}`), '');
-  for (const [prov, p] of Object.entries(inventory.providers)) {
-    out.push(`- **${prov}**: ${p.callSites} usos en ${p.files.length} archivo(s) — ${Object.entries(p.ops).map(([o, n]) => `${o} ×${n}`).join(', ')}`);
+  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.', '');
   }
-  out.push('');
+  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;
@@ -61,28 +99,43 @@ export function prBody({ pack, findings, changed, verification }, today = new Da
   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, '');
-  out.push('### Qué hace este PR', '');
+  // 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 modifica archivos: solo reporta lo que hay que resolver a mano.', '');
+    : '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('', '### Lo que este PR NO resuelve (necesita una persona)', '');
+    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}\``);
     }
   }
-  out.push('', '### Verificación', '');
-  if (verification) {
-    out.push(`- Sintaxis de los archivos modificados: ${verification.parse.ok ? '✅ OK' : '❌ ' + verification.parse.errors.join('; ')}`);
-    if (verification.tests) out.push(`- Tests del repo (\`npm test\`): ${verification.tests.ok ? '✅ pasan' : verification.tests.skipped ? '— no hay script de test' : '❌ fallan'}`);
-  } else {
-    out.push('- Sin verificar (corré `parche pr --verify`).');
+  // 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('', '### Checklist antes de mergear', '', ...pack.review_checklist_es.map((x) => `- [ ] ${x}`), '');
+  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');

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;
+}

package/src/sdk-diff/surface.js

@@ -0,0 +1,159 @@
+// Superficie pública de una versión de un SDK, leída de sus .d.ts con el compiler API de TypeScript.
+//
+// Devuelve dos mapas de ruta → entrada, con la misma forma que las operaciones del inventario (hito B):
+//   default: miembros de la instancia del export por defecto  → "chat.completions.create"
+//   exports: exports con nombre y sus miembros                 → "OpenAIApi.createChatCompletion"
+// Cada entrada: { kind, deprecated (texto o null), signatures: [{ params: [{ name, optional, rest, type }] }] }.
+//
+// TypeScript (24 MB) se carga recién acá, para que `parche scan` común no lo pague.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let tsModule = null;
+const loadTs = () => (tsModule ||= require('typescript'));
+
+const MAX_PROPS = 400;
+const TYPE_MAX = 400;
+
+export function extractSurface({ files, entry, pkgName, maxDepth = 4 }) {
+  const ts = loadTs();
+  const options = {
+    noEmit: true, skipLibCheck: true, types: [], strict: false,
+    target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS, moduleResolution: ts.ModuleResolutionKind.Node10,
+  };
+  // Sistema de archivos virtual: el paquete vive en /node_modules/<pkg>/; las libs de TypeScript, en disco.
+  const base = `/node_modules/${pkgName}/`;
+  const virtual = new Map([...files].map(([p, c]) => [base + p, c]));
+  const norm = (f) => f.replace(/\\/g, '/');
+  const libDir = norm(path.dirname(ts.getDefaultLibFilePath(options)));
+  const isLib = (f) => norm(f).startsWith(libDir);
+  const dirs = new Set();
+  for (const p of virtual.keys()) for (let d = path.posix.dirname(p); d !== '/'; d = path.posix.dirname(d)) dirs.add(d);
+  const host = {
+    fileExists: (f) => virtual.has(norm(f)) || (isLib(f) && fs.existsSync(f)),
+    readFile: (f) => virtual.get(norm(f)) ?? (isLib(f) && fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : undefined),
+    getSourceFile: (f, lang) => {
+      const text = host.readFile(f);
+      return text === undefined ? undefined : ts.createSourceFile(f, text, lang, true);
+    },
+    directoryExists: (d) => dirs.has(norm(d).replace(/\/$/, '')) || isLib(d),
+    getDirectories: () => [],
+    getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+    getCurrentDirectory: () => '/',
+    getCanonicalFileName: (f) => f,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+    writeFile: () => {},
+  };
+  const entryPath = base + entry;
+  const program = ts.createProgram({ rootNames: [entryPath], options, host });
+  const checker = program.getTypeChecker();
+  const sf = program.getSourceFile(entryPath);
+  const surface = { default: new Map(), exports: new Map() };
+  if (!sf) return surface;
+
+  // El módulo: el archivo de entrada o, si declara `declare module 'pkg' { ... }`, ese módulo ambiental.
+  let mod = checker.getSymbolAtLocation(sf);
+  if (!mod) mod = checker.getAmbientModules().find((m) => m.name.replace(/^["']|["']$/g, '') === pkgName);
+  if (!mod) return surface;
+
+  const resolve = (sym) => (sym && sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym);
+  const declOf = (sym) => sym.valueDeclaration || (sym.declarations && sym.declarations[0]);
+  const typeStr = (type) => checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation).replace(/\s+/g, ' ').slice(0, TYPE_MAX);
+  const deprecatedOf = (sym) => {
+    const tag = sym.getJsDocTags(checker).find((t) => t.name === 'deprecated');
+    return tag ? (ts.displayPartsToString(tag.text) || 'deprecado').trim() : null;
+  };
+  const isHidden = (sym) => {
+    const name = sym.getName();
+    if (name.startsWith('#') || name.startsWith('_') || name.startsWith('__@')) return true;
+    const d = declOf(sym);
+    return !!(d && ts.getCombinedModifierFlags(d) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected));
+  };
+  const signaturesOf = (sigs) => sigs.map((sig) => ({
+    params: sig.getParameters().map((p) => {
+      const d = p.valueDeclaration;
+      const rest = !!(d && d.dotDotDotToken);
+      const optional = rest || !!(d && (d.questionToken || d.initializer)) || (d && ts.isParameter(d) && checker.isOptionalParameter(d));
+      return { name: p.getName(), optional: !!optional, rest, type: d ? typeStr(checker.getTypeOfSymbolAtLocation(p, d)) : 'any' };
+    }),
+  }));
+  // Tipos de la librería estándar (Promise, Array, Map...): no son parte del SDK, no se baja por ellos.
+  const isLibType = (type) => {
+    const s = type.aliasSymbol || type.getSymbol();
+    const decls = s && s.declarations;
+    return !!(decls && decls.length && decls.every((d) => isLib(d.getSourceFile().fileName)));
+  };
+  // ¿Es un "recurso"? Tiene métodos, o propiedades que a su vez tienen métodos (openai.chat → chat.completions.create).
+  const hasMethods = (type, depth = 2) => {
+    if (isLibType(type)) return false;
+    const props = checker.getPropertiesOfType(type);
+    if (props.length > MAX_PROPS) return false;
+    return props.some((p) => {
+      if (isHidden(p)) return false;
+      const d = declOf(p);
+      if (!d) return false;
+      const t = checker.getTypeOfSymbolAtLocation(p, d);
+      if (t.getCallSignatures().length > 0) return true;
+      return depth > 1 && !!(t.flags & ts.TypeFlags.Object) && hasMethods(t, depth - 1);
+    });
+  };
+
+  // Miembros de un tipo (recursivo en "recursos": objetos que a su vez tienen métodos).
+  function addMembers(map, prefix, type, depth, stack) {
+    if (depth > maxDepth || stack.has(type)) return;
+    const props = checker.getPropertiesOfType(type);
+    if (props.length > MAX_PROPS) return;
+    stack.add(type);
+    for (const p of props) {
+      if (isHidden(p)) continue;
+      const d = declOf(p);
+      if (!d) continue;
+      const pathName = prefix ? `${prefix}.${p.getName()}` : p.getName();
+      const pType = checker.getTypeOfSymbolAtLocation(p, d);
+      const sigs = pType.getCallSignatures();
+      if (sigs.length) map.set(pathName, { kind: 'method', deprecated: deprecatedOf(p), signatures: signaturesOf(sigs) });
+      else map.set(pathName, { kind: 'property', deprecated: deprecatedOf(p) });
+      // Recursos (también los invocables, como client.messages(sid) que además tiene messages.create).
+      if (pType.flags & ts.TypeFlags.Object && hasMethods(pType)) addMembers(map, pathName, pType, depth + 1, stack);
+    }
+    stack.delete(type);
+  }
+
+  // Un símbolo exportado: clase (sus miembros de instancia), función, u objeto/namespace con miembros.
+  function addSymbol(map, prefix, rawSym) {
+    const sym = resolve(rawSym);
+    if (!sym) return;
+    const d = declOf(sym);
+    if (sym.flags & ts.SymbolFlags.Class) {
+      if (prefix) map.set(prefix, { kind: 'class', deprecated: deprecatedOf(sym) });
+      addMembers(map, prefix, checker.getDeclaredTypeOfSymbol(sym), 1, new Set());
+      return;
+    }
+    if (!d || !(sym.flags & ts.SymbolFlags.Value)) return; // solo tipos: no se pueden llamar
+    const type = checker.getTypeOfSymbolAtLocation(sym, d);
+    const sigs = type.getCallSignatures();
+    if (sigs.length && prefix) map.set(prefix, { kind: 'function', deprecated: deprecatedOf(sym), signatures: signaturesOf(sigs) });
+    else if (prefix) map.set(prefix, { kind: 'property', deprecated: deprecatedOf(sym) });
+    if (type.flags & ts.TypeFlags.Object && hasMethods(type)) addMembers(map, prefix, type, 1, new Set());
+    // Fábricas: const client = twilio(sid, token) → los miembros del cliente que devuelve, en la misma ruta.
+    for (const sig of sigs.slice(0, 1)) {
+      const ret = checker.getReturnTypeOfSignature(sig);
+      if (ret.flags & ts.TypeFlags.Object && hasMethods(ret)) addMembers(map, prefix, ret, 1, new Set());
+    }
+  }
+
+  const exported = checker.getExportsOfModule(mod);
+  for (const sym of exported) {
+    const name = sym.getName();
+    if (name === 'default') continue;
+    addSymbol(surface.exports, name, sym);
+  }
+  // Export por defecto: `export default X` o `export = X` (CommonJS).
+  const defaultSym = exported.find((s) => s.getName() === 'default')
+    || (mod.exports && mod.exports.get('export=') ? checker.resolveExternalModuleSymbol(mod) : null);
+  if (defaultSym && defaultSym !== mod) addSymbol(surface.default, '', defaultSym);
+  return surface;
+}

package/src/sdk-diff/tar.js

@@ -0,0 +1,47 @@
+// Lector mínimo de tarballs de npm (.tgz), sin dependencias: gunzip + formato tar (ustar, pax y GNU).
+// Solo devuelve los archivos que sirven para comparar APIs: package.json y declaraciones de tipos.
+import zlib from 'node:zlib';
+
+const WANTED = /(^|\/)package\.json$|\.d\.(ts|mts|cts)$/;
+
+const str = (buf, start, len) => {
+  const s = buf.subarray(start, start + len);
+  const end = s.indexOf(0);
+  return s.subarray(0, end === -1 ? s.length : end).toString('utf8');
+};
+const octal = (buf, start, len) => parseInt(str(buf, start, len).trim() || '0', 8);
+
+// Registros pax: "<largo> clave=valor\n"
+function paxPath(data) {
+  for (const rec of data.toString('utf8').split('\n')) {
+    const m = rec.match(/^\d+ path=(.*)$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// tgz → Map(ruta sin el "package/" inicial → contenido). Ignora todo lo que no sea tipos o package.json.
+export function extractTypes(tgz) {
+  const tar = zlib.gunzipSync(tgz);
+  const files = new Map();
+  let offset = 0;
+  let nextName = null;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((b) => b === 0)) break; // fin del archivo
+    const size = octal(header, 124, 12);
+    const type = String.fromCharCode(header[156] || 48);
+    const prefix = str(header, 345, 155);
+    let name = nextName || (prefix ? `${prefix}/${str(header, 0, 100)}` : str(header, 0, 100));
+    nextName = null;
+    const dataStart = offset + 512;
+    const data = tar.subarray(dataStart, dataStart + size);
+    offset = dataStart + Math.ceil(size / 512) * 512;
+    if (type === 'x') { nextName = paxPath(data); continue; } // pax: el nombre largo es del próximo
+    if (type === 'L') { nextName = str(data, 0, data.length); continue; } // GNU: nombre largo
+    if (type !== '0' && type !== '\0') continue; // solo archivos comunes
+    name = name.replace(/^[^/]+\//, ''); // "package/index.d.ts" → "index.d.ts"
+    if (WANTED.test(name)) files.set(name, data.toString('utf8'));
+  }
+  return files;
+}