parche-cli 0.1.1 → 0.6.0

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

package/src/sdk-diff/upgrades.js

@@ -0,0 +1,107 @@
+// `parche scan --upgrades` y `parche diff`: para cada SDK de npm que el repo usa, compara la versión
+// instalada con la última publicada y dice qué operaciones del repo cambian o desaparecen.
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractSurface } from './surface.js';
+import { diffSurfaces, affectedOperations, unverifiedOperations, dedupeChanges } from './compare.js';
+import { compareVersions } from './registry.js';
+
+const readJson = (p) => {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+// Versión instalada: node_modules → package-lock.json → la base del rango declarado ("^3.2.1" → 3.2.1).
+// Si la base no existe en el registry, la más alta de la misma versión mayor. → { version, from } | null
+export function installedVersion(root, pkg, declared, meta) {
+  const nm = readJson(path.join(root, 'node_modules', pkg, 'package.json'));
+  if (nm?.version) return { version: nm.version, from: 'node_modules' };
+  const lock = readJson(path.join(root, 'package-lock.json'));
+  const locked = lock?.packages?.[`node_modules/${pkg}`]?.version || lock?.dependencies?.[pkg]?.version;
+  if (locked) return { version: locked, from: 'package-lock.json' };
+  const m = String(declared || '').match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  const base = `${m[1]}.${m[2] || 0}.${m[3] || 0}`;
+  if (!meta || meta.versions[base]) return { version: base, from: 'package.json' };
+  const sameMajor = Object.keys(meta.versions).filter((v) => v.split('.')[0] === m[1] && !v.includes('-')).sort(compareVersions);
+  return sameMajor.length ? { version: sameMajor[sameMajor.length - 1], from: 'package.json' } : null;
+}
+
+// "latest", "4" o "4.1" → la versión exacta más alta que corresponde, según el registry.
+export function resolveSpec(meta, spec) {
+  if (spec === 'latest') return meta['dist-tags']?.latest || null;
+  if (meta.versions[spec]) return spec;
+  const matches = Object.keys(meta.versions).filter((v) => !v.includes('-') && v.startsWith(`${spec}.`)).sort(compareVersions);
+  return matches.length ? matches[matches.length - 1] : null;
+}
+
+// Diff completo entre dos versiones de un paquete (acepta "latest" y versiones parciales).
+export async function diffVersions(registry, pkg, fromSpec, toSpec) {
+  const meta = await registry.metadata(pkg);
+  const from = resolveSpec(meta, fromSpec);
+  const to = resolveSpec(meta, toSpec);
+  if (!from || !to) return { pkg, from: fromSpec, to: toSpec, error: `${pkg}: no existe la versión ${!from ? fromSpec : toSpec} en el registry.` };
+  const [ta, tb] = await Promise.all([registry.types(pkg, from), registry.types(pkg, to)]);
+  if (!ta || !tb) return { pkg, from, to, error: `No hay tipos (.d.ts) para ${!ta ? from : to}: no se puede comparar.` };
+  const sa = extractSurface({ files: ta.files, entry: ta.entry, pkgName: pkg });
+  const sb = extractSurface({ files: tb.files, entry: tb.entry, pkgName: pkg });
+  const all = diffSurfaces(sa, sb);
+  // changes: para mostrar (sin repetidos); allChanges: para cruzar con lo que usa el repo.
+  return { pkg, from, to, typesFrom: ta.source, typesTo: tb.source, before: sa, changes: dedupeChanges(all), allChanges: all };
+}
+
+// Para cada SDK de npm del inventario que tiene operaciones: versión instalada vs última.
+export async function checkUpgrades(inventory, root, registry) {
+  const results = [];
+  const sdks = inventory.apis.filter((a) => a.kind === 'sdk' && a.ecosystem === 'npm' && a.operations.length);
+  for (const api of sdks) {
+    const base = { package: api.package, provider: api.provider };
+    try {
+      const meta = await registry.metadata(api.package);
+      const latest = meta['dist-tags']?.latest;
+      const installed = installedVersion(root, api.package, api.version, meta);
+      if (!latest || !installed) {
+        results.push({ ...base, status: 'sin-version', installed: installed?.version || null, latest: latest || null });
+        continue;
+      }
+      if (compareVersions(installed.version, latest) >= 0) {
+        results.push({ ...base, status: 'al-dia', installed: installed.version, latest });
+        continue;
+      }
+      const d = await diffVersions(registry, api.package, installed.version, latest);
+      if (d.error) {
+        results.push({ ...base, status: 'sin-tipos', installed: installed.version, latest, error: d.error });
+        continue;
+      }
+      const ops = api.operations.map((o) => o.op);
+      const affected = affectedOperations(d.allChanges, ops, d.before).map((a) => ({
+        ...a, locations: api.operations.find((o) => o.op === a.op).locations,
+      }));
+      const unverified = unverifiedOperations(ops, d.before);
+      const status = affected.length ? 'afectado' : unverified.length === ops.length ? 'sin-verificar' : 'sin-impacto';
+      results.push({ ...base, status, installed: installed.version, installedFrom: installed.from, latest,
+        totalChanges: d.changes.length, affected, unverified });
+    } catch (err) {
+      const notPublished = /respondió 404/.test(err.message);
+      results.push({ ...base, status: notPublished ? 'no-publicado' : 'error',
+        error: notPublished ? `${api.package} no está publicado en el registry de npm (¿paquete privado o interno?).` : err.message });
+    }
+  }
+  return results;
+}
+
+// Hallazgos detect-only (en castellano) para el reporte.
+export function upgradeFindings(results) {
+  const findings = [];
+  for (const r of results.filter((x) => x.status === 'afectado')) {
+    for (const a of r.affected) {
+      const where = a.locations[0];
+      findings.push({ pack: 'sdk.upgrades', file: where.file, line: where.line, status: 'detect-only',
+        message: `${r.package} ${r.installed} → ${r.latest}: ${a.changes.map((c) => c.message).join(' ')}` });
+    }
+  }
+  return findings;
+}

package/src/verify.js

@@ -3,6 +3,55 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { parseCheck } from './ast.js';
+import { isPhp } from './php.js';
+
+const readJson = (root, name) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, name), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+// Tests que corresponden a los archivos modificados: `npm test` para JS/TS; para PHP,
+// `composer test` o, si no hay script, vendor/bin/phpunit. Si no hay ninguno, queda el chequeo de sintaxis.
+export function testCommands(root, changedFiles) {
+  const cmds = [];
+  const pkg = readJson(root, 'package.json');
+  if (changedFiles.some((f) => !isPhp(f)) && pkg?.scripts?.test) {
+    cmds.push({ label: 'npm test', cmd: 'npm', args: ['test', '--silent'] });
+  }
+  if (changedFiles.some(isPhp)) {
+    const composer = readJson(root, 'composer.json');
+    if (composer?.scripts?.test) cmds.push({ label: 'composer test', cmd: 'composer', args: ['test'] });
+    else if (fs.existsSync(path.join(root, 'vendor', 'bin', 'phpunit'))) {
+      cmds.push({ label: 'vendor/bin/phpunit', cmd: path.join('vendor', 'bin', 'phpunit'), args: [] });
+    }
+  }
+  return cmds;
+}
+
+// Workflows del repo que corren en cada pull request: si Parche no corrió los tests, el PR dice dónde se corren.
+// `on: [push, pull_request]`, `on:` + `pull_request:` o `- pull_request`. No cuenta pull_request_target:
+// corre el código de la rama base, no el del PR.
+const ON_PULL_REQUEST = /^\s*(['"]?on['"]?\s*:.*\bpull_request\b|-?\s*pull_request\b\s*(:|#|$))/m;
+
+export function prWorkflows(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((f) => /\.ya?ml$/i.test(f)).sort();
+  } catch {
+    return [];
+  }
+  return names.filter((f) => {
+    try {
+      return ON_PULL_REQUEST.test(fs.readFileSync(path.join(dir, f), 'utf8'));
+    } catch {
+      return false;
+    }
+  }).map((f) => `.github/workflows/${f}`);
+}
 
 export function verify(root, changedFiles, { runTests = false } = {}) {
   const errors = [];
@@ -15,16 +64,23 @@ export function verify(root, changedFiles, { runTests = false } = {}) {
   }
   const result = { parse: { ok: errors.length === 0, errors } };
   if (runTests) {
-    const pkgPath = path.join(root, 'package.json');
-    const pkg = fs.existsSync(pkgPath) ? JSON.parse(fs.readFileSync(pkgPath, 'utf8')) : {};
-    if (!pkg.scripts || !pkg.scripts.test) {
-      result.tests = { ok: true, skipped: true };
+    const cmds = testCommands(root, changedFiles);
+    if (!cmds.length) {
+      result.tests = { ok: true, skipped: true, commands: [] };
     } else {
-      // En Windows npm es npm.cmd y Node solo lo ejecuta a través de un shell.
-      const r = spawnSync('npm', ['test', '--silent'], { cwd: root, encoding: 'utf8', timeout: 300000, shell: process.platform === 'win32' });
-      const output = (r.stdout || '') + (r.stderr || '') + (r.error ? `\n${r.error.message}` : '');
-      result.tests = { ok: r.status === 0, output: output.slice(-2000) };
+      let ok = true;
+      let output = '';
+      for (const c of cmds) {
+        // En Windows npm, composer y phpunit son .cmd/.bat y Node solo los ejecuta a través de un shell.
+        const r = spawnSync(c.cmd, c.args, { cwd: root, encoding: 'utf8', timeout: 300000, shell: process.platform === 'win32' });
+        output += `$ ${c.label}\n${r.stdout || ''}${r.stderr || ''}${r.error ? `\n${r.error.message}` : ''}\n`;
+        if (r.status !== 0) { ok = false; break; }
+      }
+      result.tests = { ok, commands: cmds.map((c) => c.label), output: output.slice(-2000) };
     }
+  } else {
+    // Sin --verify, Parche no ejecuta código del repo (por ejemplo, en un repo de terceros): se dice, no se oculta.
+    result.tests = { ok: true, notRun: true, ci: prWorkflows(root) };
   }
   result.ok = result.parse.ok && (!result.tests || result.tests.ok);
   return result;