parche-cli 0.0.0-stage → 0.5.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

@@ -0,0 +1,87 @@
+// Verificación: ningún PR sale sin que el código modificado parsee y, si se pide, sin que pasen los tests.
+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 = [];
+  for (const rel of changedFiles) {
+    try {
+      parseCheck(fs.readFileSync(path.join(root, rel), 'utf8'), rel);
+    } catch (e) {
+      errors.push(`${rel}: ${e.message}`);
+    }
+  }
+  const result = { parse: { ok: errors.length === 0, errors } };
+  if (runTests) {
+    const cmds = testCommands(root, changedFiles);
+    if (!cmds.length) {
+      result.tests = { ok: true, skipped: true, commands: [] };
+    } else {
+      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;
+}

package/templates/github-workflow.yml

@@ -0,0 +1,27 @@
+# Copiá este archivo a .github/workflows/parche.yml en tu repo.
+# Cada lunes Parche revisa tu código contra la base de cambios de APIs
+# y abre un PR por cada cambio que te afecta (en borrador si hay algo para revisar).
+name: Parche
+
+on:
+  schedule:
+    - cron: "17 11 * * 1" # lunes 8:17 (hora de Argentina)
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  parche:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - name: Instalar dependencias del proyecto (para correr sus tests antes de cada PR)
+        run: npm ci
+      - uses: Pepo08/parche@v0