parche-cli 0.1.1 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Cambios
+
+Todas las versiones de `parche-cli` (npm) y de la Action `Pepo08/parche@v0`.
+
+## 0.5.1 — 2026-10-17
+
+Lo que apareció en el primer PR real (lunamarie11/obraya#1).
+
+### Arreglado
+- **Los commits ya no se firman con `bot@parche.dev`**, un dominio que no es nuestro. Ahora firma `PARCHE_GIT_NAME`/`PARCHE_GIT_EMAIL` si están; si no, la identidad de git de quien lo corre; y en GitHub Actions sin identidad, `github-actions[bot]`. Sin ninguna, `parche pr` frena antes de tocar el repo.
+- **`parche pr` chequea la sintaxis siempre**, también sin `--verify` (no ejecuta nada del repo). El PR ya no dice "Sin verificar": dice que Parche no corrió los tests y nombra los workflows del repo que los corren en cada pull request (`pull_request`; `pull_request_target` no cuenta).
+- El texto para un issue (sin cambios de código) ya no lleva la sección de verificación.
+
+## 0.5.0 — 2026-10-16
+
+Lo que encontró el frente de tracción al correr Parche sobre 175 repos públicos reales.
+
+### Nuevo
+- **La versión de la librería de ARCA importa:** con `afip.js`/`afip.php` 0.x (o `eesnaola/afip.php`) el campo no llega a ARCA (WSDL de 2021). Parche lee la versión instalada y el arreglo pasa a "revisar" con el aviso de actualizar a 1.x.
+- Detección de **`.wsdl` de WSFEv1 sin el campo** en el repo.
+- **Python, C#, Java, Go y VB.NET:** detección de integraciones SOAP propias y de clientes SOAP generados sin el campo.
+- `parche pr --push-remote <remote>`: abre PRs **desde un fork**.
+- **Pack de IA al día con las páginas oficiales:** `claude-sonnet-4-5-20250929` se retira el 30/11/2026; OpenAI retira `gpt-3.5-turbo`, `gpt-4`, `gpt-4-turbo`, `o1`, `o3-mini`, `o4-mini`, `gpt-4.1-nano`, `gpt-image-1` y otros el **23/10/2026**, y los snapshots de `gpt-5-*-2025-08-07` y `o3` el 11/12/2026; suma los ya retirados (DALL·E, `gpt-3.5-turbo-instruct`, `chatgpt-4o-latest`, Claude 2/3.5…). Cada aviso trae el reemplazo recomendado.
+
+### Arreglado
+- `parche pr` dejaba el archivo modificado en la rama base cuando fallaba la verificación; ahora el repo queda como estaba y la rama se borra. Tampoco quedan ramas vacías.
+- No se abre un PR cuyo único cambio sea un test o un mock.
+- ARCA en JS: se reconocen `(afip.ElectronicBilling as any).createVoucher(...)`, `afip.ElectronicBilling!` y alias (`const eb = afip.ElectronicBilling`). Si un archivo de ARCA no parsea, se avisa (antes se descartaba en silencio).
+- Menos ruido: la detección de SOAP propio ya no marca tests, mocks, tipos, constantes ni copias de la librería; si el repo ya usa el campo en otro archivo, lo que no se pudo leer pasa a "revisar".
+- Pack de IA: un modelo en una lista o catálogo se avisa como mención, no como uso; en Azure OpenAI no se da por cerrada la Assistants API.
+- Mucho más rápido en repos grandes: los codemods de ARCA no parsean archivos que no mencionan ARCA.
+- El texto para un issue (sin cambios de código) ya no habla de "este PR".
+- `detect.packages` de ARCA: fuera `afip.js` (no existe en npm); suma `@arcasdk/core`, `afip.ts`, `ts-afip-ws` y `facturajs`.
+
+### Cambiado
+- `docs/arquitectura.md` sale del repo: era documentación interna del equipo. El formato del inventario sigue en `docs/inventario.md`.
+
+## 0.4.1 — 2026-10-16
+
+Arreglos encontrados al correr Parche sobre los primeros repos públicos reales con ARCA y Mercado Pago.
+
+### Arreglado
+- **ARCA:** si el mismo objeto de comprobante se pasaba a dos llamadas, el campo se insertaba dos veces (clave duplicada: TypeScript no compila). Ahora se inserta una sola vez, en JS y en PHP.
+- **Decoradores** (NestJS, Angular, TypeORM): el chequeo de sintaxis fallaba y `--verify`/`--dry-run` frenaban el PR; el inventario no veía nada en esos archivos.
+- **Inventario en monorepos:** se leen todos los `package.json`, `composer.json` y `requirements.txt` del repo, no solo los de la raíz (`manifestFiles` dice cuáles).
+- **Inventario:** se siguen los clientes guardados en clases (`private x = new X()`, `this.x = new X()`).
+- `http://localhost:${PORT}` ya no aparece como un host externo.
+- `socket.io-client`, `@prisma/client`, `@trpc/client`, `pg`, `ws`, `@aws-sdk/types` y similares ya no se listan como APIs; toda la familia `@aws-sdk/` cuenta como AWS.
+
+### Mejorado
+- **ARCA:** cuando el comprobante lo arma otra función o llega como parámetro, el hallazgo dice dónde agregar el dato (por ejemplo: "lo arma `buildVoucherPayload()` (de `@/lib/afip/voucher-builder`)").
+
+## 0.4.0 — 2026-10-16
+
+### Nuevo
+- **Qué cambia en las versiones nuevas de tus SDKs** (`parche scan --upgrades`): para cada SDK de npm que el repo usa, compara la versión instalada con la última publicada leyendo sus tipos (`.d.ts`) y dice qué operaciones **del repo** desaparecen, piden parámetros obligatorios nuevos, pierden parámetros, cambian de tipo o pasan a deprecadas, con archivo y línea. Solo avisa (detect-only).
+- **`parche diff <paquete> --from <v> --to <v>`**: el mismo análisis para cualquier paquete, sin repo (acepta `latest` y versiones parciales; `--all`, `--json`).
+- Tarballs bajados del registry con verificación de integridad y cacheados en `~/.parche/cache` (`PARCHE_CACHE`, `PARCHE_OFFLINE=1`). Si el paquete no trae tipos, usa `@types/<paquete>`.
+- Ejemplo nuevo: `examples/legacy-ia` (SDK de OpenAI v3: `OpenAIApi` desaparece en las versiones nuevas, como dice la guía oficial de migración).
+- Dependencia nueva: `typescript ~6.0.3` (la última con el compiler API de JavaScript), cargada solo para el diff.
+
+## 0.3.0 — 2026-10-16
+
+### Nuevo
+- **Inventario de cualquier API** (nivel 1): `parche scan` lista todas las APIs de terceros del repo, tengan pack o no.
+  - **SDKs** de `package.json`, `composer.json` y `requirements.txt`, clasificados con una lista curada (`data/known-sdks.json`: pagos, facturación, IA, mensajería, email, nube, datos y más) y una heurística por nombre, con nivel de confianza.
+  - En JS/TS, **qué operaciones** se usan de cada SDK (`stripe.paymentIntents.create`, `client.messages.create`…), siguiendo imports, `require` e instancias.
+  - **Llamadas HTTP directas** con `fetch`, `axios` (incluido `axios.create({ baseURL })`), `got`, `undici` y `node-fetch`: método, host y ruta. Las URLs dinámicas se reportan aparte; lo local y lo relativo se descarta.
+  - **Modelos de IA** nombrados en el código (OpenAI, Anthropic, Gemini, Mistral, Cohere).
+- `.parche/inventory.json` con `schemaVersion: 1`, documentado en `docs/inventario.md` (los campos anteriores se mantienen).
+- La salida de `scan` y `.parche/report.md` muestran el inventario completo.
+- Ejemplo nuevo: `examples/saas-demo` (Stripe, Twilio, OpenAI, GitHub, Mercado Libre y HTTP directo).
+- `docs/arquitectura.md`: qué hace cada parte del código y por qué.
+
+## 0.2.0 — 2026-10-16
+
+### Nuevo
+- **Pack ARCA para PHP**: `afipsdk/afip.php` y sus forks (`fertandil87/afip.php`, `ivanalemunioz/afip.php`, `eesnaola/afip.php`). Agrega `CondicionIVAReceptorId` a `$afip->ElectronicBilling->CreateVoucher($data)` y `CreateNextVoucher($data)` con las mismas reglas que en JS: DocTipo 99 → automático; DNI con comprobante B o C → para revisar; factura A o CUIT → pide el dato y muestra los códigos válidos.
+  - Lee el array en la llamada (`array()` o `[]`) o en una variable definida una vez en la misma función; si no puede leerlo con certeza, lo reporta y no toca nada.
+  - Copia el estilo del cliente: comillas, indentación (espacios o tabs), `=>` alineados, coma final y fin de línea.
+- El motor escanea archivos `.php`, lee `composer.json` y saltea `vendor/`.
+- `--verify` corre `composer test` o `vendor/bin/phpunit` cuando cambian archivos PHP (y `npm test` cuando cambian archivos JS/TS).
+- Ejemplo nuevo: `examples/tienda-php`.
+
+### Arreglado
+- El cuerpo del PR decía "✅ pasan" cuando el repo no tenía tests; ahora dice que no hubo tests y que se validó la sintaxis.
+- Mercado Pago: el `import { randomUUID }` nuevo queda junto a los otros imports.
+- ARCA (JS): si la última propiedad no tenía coma final, la propiedad nueva tampoco la lleva.
+
+## 0.1.1 — 2026-10-15
+
+- Publicado en npm como `parche-cli` (npm no acepta `parche`). El comando instalado sigue siendo `parche`.
+
+## 0.1.0 — 2026-10-15
+
+- Primera versión: CLI (`packs`, `scan`, `fix`, `pr`, `feedback`), GitHub Action y packs de ARCA (afip.js), Mercado Pago Payments → Orders y retiros de modelos de IA.
+- CI en Linux y Windows. Arreglados 4 bugs que solo aparecían en Windows (offsets de recast, CRLF, rutas con `\`, `npm test` sin shell).

package/README.md

@@ -2,24 +2,31 @@
 
 [![CI](https://github.com/Pepo08/parche/actions/workflows/ci.yml/badge.svg)](https://github.com/Pepo08/parche/actions/workflows/ci.yml)
 
-Parche lee tu código, arma un inventario de qué APIs de terceros usás (Mercado Pago, ARCA, modelos de IA…) y lo cruza contra una base de **cambios de API verificados**. Cuando un proveedor cambia algo que te afecta, Parche abre un PR con el arreglo, explica qué cambió y por qué, y marca lo que necesita una persona. Ningún PR sale sin pasar la verificación.
+Parche lee tu código y arma el inventario de **todas** las APIs de terceros que usás: SDKs (Stripe, Twilio, OpenAI, AWS, Mercado Pago, ARCA…), llamadas HTTP directas y modelos de IA. Lo cruza contra una base de **cambios de API verificados** y, cuando un proveedor cambia algo que te afecta, te avisa o abre un PR con el arreglo, explica qué cambió y por qué, y marca lo que necesita una persona. Ningún PR sale sin pasar la verificación. Las APIs de pagos y facturación de Latinoamérica son el fuerte, pero el inventario cubre cualquier API.
 
 ```
 $ parche scan .
-APIs encontradas:
-  mercadopago   4 usos en 4 archivo(s)  [Payment.create, Payment.get]
-  arca          3 usos en 1 archivo(s)  [ElectronicBilling.createNextVoucher]
-  ia            2 usos en 1 archivo(s)  [modelo claude-3-5-haiku-20241022, OpenAI Assistants API]
+APIs del repo (6):
+  SDK   Anthropic · @anthropic-ai/sdk          alta   messages.create  · con pack
+  SDK   ARCA (ex AFIP) · @afipsdk/afip.js      alta   ElectronicBilling.createNextVoucher ×3  · con pack
+  SDK   Mercado Pago · mercadopago             alta   Payment.create ×3, Payment.get  · con pack
+  SDK   OpenAI · openai                        alta   beta.assistants.create  · con pack
+  IA    Anthropic · modelos                    alta   claude-3-5-haiku-20241022  · con pack
+  IA    OpenAI · modelos                       alta   gpt-4o  · con pack
 
 ■ Condición frente al IVA del receptor obligatoria en WSFEv1
-  ARCA (ex AFIP) · severidad critical · vence 2026-12-01 (47 días)
+  ARCA (ex AFIP) · severidad critical · vence 2026-12-01 (46 días)
   ✅ automático     src/facturacion.js:14  Agregado CondicionIVAReceptorId: 5 (Consumidor Final)…
   👀 revisar       src/facturacion.js:56  Agregado CondicionIVAReceptorId: 5 por inferencia (DNI + comprobante B/C)…
   ✋ falta un dato  src/facturacion.js:62  Falta CondicionIVAReceptorId y no se puede inferir… (comprobante clase A).
+
+■ Modelos y endpoints de IA retirados o por retirarse
+  🔎 detectado     src/ia.js:9  El modelo `claude-3-5-haiku-20241022` fue retirado el 2026-02-19: las llamadas ya fallan…
 …
-✅ automático: 5   👀 revisar: 8   ✋ falta un dato: 1   ⛔ bloqueado: 1   🔎 detectado: 2
 ```
 
+El inventario completo (con operaciones, ubicaciones y nivel de confianza) queda en `.parche/inventory.json`; el formato está en [`docs/inventario.md`](docs/inventario.md). Para ver un repo con APIs de todo tipo, desde este repo: `node bin/parche.js scan examples/saas-demo`.
+
 ## Por qué packs y no "un LLM que arregla todo"
 
 Ya hay varios prototipos que le piden a un modelo que lea un changelog y escriba el fix. El problema es que el modelo solo sabe lo que aprendió en su entrenamiento, y una migración de pagos o de facturación no admite "casi bien". Parche separa las dos cosas:
@@ -36,6 +43,8 @@ Requiere Node 22 o más nuevo. El paquete de npm se llama `parche-cli`; si lo in
 ```bash
 npx parche-cli packs                 # cambios que Parche conoce
 npx parche-cli scan .                # inventario + qué te afecta (.parche/report.md)
+npx parche-cli scan . --upgrades     # + qué cambia en las versiones nuevas de tus SDKs
+npx parche-cli diff <paquete> --from <v> --to <v>   # qué cambia en la API de un paquete
 npx parche-cli fix .                 # aplica los arreglos en tu working copy
 npx parche-cli pr . --verify         # una rama + commit + PR por cambio
 npx parche-cli feedback . --pack <id> --outcome merged|edited|rejected
@@ -43,6 +52,27 @@ npx parche-cli feedback . --pack <id> --outcome merged|edited|rejected
 
 `parche pr` abre el PR por la API de GitHub si hay `GITHUB_TOKEN` y un remote `origin` en github.com; si no (o con `--dry-run`), deja la rama, el commit y el cuerpo del PR en `.parche/pr-<pack>.md`. Si hay ítems para revisar, el PR se abre como borrador.
 
+- **Desde un fork:** `parche pr . --push-remote fork` pushea la rama al remote `fork` (tu fork, con tus credenciales de git) y abre el PR contra `origin`.
+- **Nunca deja el repo sucio:** si la verificación falla, descarta lo que escribió y borra su rama. Si no hay cambios de código, o solo cambiarían tests o mocks, no abre PR: deja el texto como issue en `.parche/`.
+
+### Qué cambia en las versiones nuevas de tus SDKs
+
+`--upgrades` compara, para cada SDK de npm que usás, la versión instalada con la última publicada. Lee los tipos (`.d.ts`) de las dos versiones y te dice qué operaciones **de tu código** desaparecen, piden parámetros nuevos, cambian de tipo o pasan a deprecadas. Solo avisa: no toca código.
+
+```
+$ npx parche-cli scan . --upgrades
+…
+Versiones nuevas de tus SDKs de npm:
+  openai                 3.3.0 → 7.34.0       ⚠ 2 de tus operaciones cambian o desaparecen
+      OpenAIApi.createChatCompletion  (src/asistente.js:8)
+        `OpenAIApi` ya no existe.
+      OpenAIApi.createEmbedding  (src/asistente.js:16)
+        `OpenAIApi` ya no existe.
+  stripe                 17.0.0 → 23.0.0      ✓ lo que usás no cambia (22 cambios en el SDK)
+```
+
+Y para un paquete cualquiera, sin repo: `npx parche-cli diff stripe --from 17 --to latest` (acepta versiones parciales y `latest`; `--all` para ver todo, `--json` para procesarlo). Los tarballs quedan en `~/.parche/cache` (cambiable con `PARCHE_CACHE`); con `PARCHE_OFFLINE=1` usa solo el caché.
+
 ### En GitHub Actions
 
 Para que corra todas las semanas, copiá [`templates/github-workflow.yml`](templates/github-workflow.yml) a `.github/workflows/parche.yml`. El paso clave es:
@@ -61,10 +91,30 @@ El workflow necesita `permissions: contents: write` y `pull-requests: write`.
 
 ```bash
 npm install
-npm test                         # 13 tests; el CI los corre en Linux y Windows
-bash demo.sh                     # demo completa sobre examples/tienda-demo
+npm test                         # el CI los corre en Linux y Windows
+bash demo.sh                     # demo completa sobre examples/tienda-demo (JS)
+node bin/parche.js scan examples/tienda-php   # ejemplo PHP con afip.php
+node bin/parche.js scan examples/saas-demo    # SaaS con Stripe, Twilio, OpenAI y HTTP directo
+node bin/parche.js scan examples/legacy-ia --upgrades   # OpenAI v3: qué se rompe al actualizar (usa la red)
 ```
 
+#### Sacar una versión
+
+Las versiones se publican solas desde GitHub Actions ([`release.yml`](.github/workflows/release.yml)) con [trusted publishing](https://docs.npmjs.com/trusted-publishers): npm confía en este repo y en ese workflow, sin tokens ni 2FA a mano. Desde `main` actualizado:
+
+```bash
+npm version 0.1.2 --no-git-tag-version            # cambia package.json y package-lock.json
+git commit -am "Parche 0.1.2"
+git tag -a v0.1.2 -m "Parche 0.1.2: qué cambió"   # el mensaje del tag es el texto del GitHub Release
+git push origin main v0.1.2
+```
+
+Con el tag, el workflow corre los tests, controla que la versión de `package.json` coincida con el tag y que el commit esté en `main`, publica `parche-cli` en npm (con provenance), mueve `v0` a esta versión (es la que usan los workflows con `Pepo08/parche@v0`) y crea el GitHub Release. Para notas largas, `git tag -a v0.1.2 -F notas.md`.
+
+- Solo dispara con versiones estables (`vX.Y.Z`); un tag como `v0.2.0-beta.1` no hace nada.
+- Si falla un paso después de publicar, "Re-run failed jobs" retoma: lo que ya está hecho se saltea.
+- Requiere, una sola vez, el Trusted Publisher en npmjs.com: `parche-cli` → Settings → Trusted publishing → GitHub Actions, con `Pepo08` / `parche` / `release.yml` y permiso para `npm publish`.
+
 ## Estados de cada hallazgo
 
 | Estado | Qué significa |
@@ -79,18 +129,38 @@ bash demo.sh                     # demo completa sobre examples/tienda-demo
 
 | Pack | Proveedor | Tipo | Fecha límite | Arreglo |
 |---|---|---|---|---|
-| `arca.wsfe.condicion-iva-receptor` | ARCA | rompe | 2026-12-01 | sí (consumidor final y DNI B/C) |
+| `arca.wsfe.condicion-iva-receptor` | ARCA | rompe | 2026-12-01 | sí, en JS (`afip.js`) y PHP (`afipsdk/afip.php` y forks): consumidor final y DNI B/C |
 | `mercadopago.payments-to-orders` | Mercado Pago | migración | — | sí (creación de pagos en SDK Node v2) |
 | `ai.model-retirements` | Anthropic, OpenAI | retiro | varias | solo detección |
 
 ## Verificación
 
-Antes de commitear, `--verify` parsea cada archivo modificado (JS/TS) y corre el `npm test` del repo. Si algo falla, no hay PR. El commit lleva la versión del pack que lo generó, para poder rastrear qué regla produjo cada cambio.
+Antes de commitear, Parche parsea **siempre** cada archivo modificado (JS/TS o PHP): eso no ejecuta nada del repo. Con `--verify`, además corre los tests del repo que correspondan a lo que cambió: `npm test` para JS/TS; para PHP, `composer test` o `vendor/bin/phpunit`. Si no hay tests, queda el chequeo de sintaxis y el PR lo dice. Sin `--verify` (por ejemplo, en un PR a un repo de terceros, donde no se ejecuta su código), el PR dice que Parche no corrió los tests y nombra los workflows del repo que los corren en cada pull request. Si algo falla, no hay PR. El commit lleva la versión del pack que lo generó, para poder rastrear qué regla produjo cada cambio.
+
+**Quién firma el commit:** `PARCHE_GIT_NAME` y `PARCHE_GIT_EMAIL` si están; si no, tu identidad de git (`user.name` y `user.email`, también la que configure tu workflow); en GitHub Actions sin identidad, `github-actions[bot]`, el mismo que abre el PR. Si no hay ninguna, `parche pr` frena antes de tocar el repo.
+
+## ARCA en PHP
+
+Para `afipsdk/afip.php` y sus forks (`fertandil87/afip.php`, `ivanalemunioz/afip.php`, `eesnaola/afip.php`), Parche busca `$afip->ElectronicBilling->CreateVoucher($data)` y `CreateNextVoucher($data)` (también en minúsculas: PHP no distingue) y agrega una línea por factura:
+
+```php
+            'DocNro'     => 0,
+            // parche: 5 = Consumidor Final (DocTipo 99, sin identificar)
+            'CondicionIVAReceptorId' => 5,
+```
+
+- Lee el array cuando está en la llamada (`array(...)` o `[...]`) o en una variable definida una sola vez, antes de la llamada y en la misma función. Si los datos llegan de otro lado, se reasignan o se completan en varios pasos (`$data['DocTipo'] = ...`), lo reporta como "falta un dato" y no toca nada.
+- Copia el estilo del array: comillas de las claves, indentación (espacios o tabs), alineación de los `=>`, coma final y fin de línea (LF o CRLF).
+- Saltea `vendor/`.
+
+**La versión de la librería importa.** Con `afip.js`/`afip.php` 0.x (y `eesnaola/afip.php`) el pedido se arma con un WSDL de 2021 que no tiene `CondicionIVAReceptorId`: aunque el campo esté en el código, no llega a ARCA. Parche lee la versión instalada (`composer.lock`, `package-lock.json`, `node_modules`) y, en esos casos, el arreglo sale como **"revisar"** con el aviso de actualizar a 1.x. También avisa si el repo tiene un `.wsdl` de WSFEv1 sin el campo.
+
+**Otros lenguajes:** en Python, C#, Java, Go y VB.NET, Parche detecta integraciones SOAP propias y clientes SOAP generados sin el campo (no los reescribe).
 
 ## Límites del MVP
 
-- Solo Node.js (JS/TS, ESM y CommonJS). Siguen PHP (la mayoría de los sistemas de facturación locales), Python y Java.
-- ARCA: cubre `@afipsdk/afip.js`. Las integraciones SOAP propias se detectan pero no se reescriben.
+- JS/TS (ESM y CommonJS) y, para ARCA, PHP. Siguen Python y Java.
+- ARCA: cubre `@afipsdk/afip.js` y `afipsdk/afip.php` (con sus forks). Las integraciones SOAP propias (en cualquier lenguaje) se detectan pero no se reescriben.
 - Mercado Pago: migra la creación de pagos con el SDK v2. Las consultas, capturas y reembolsos de pagos existentes se dejan a propósito en Payments API, como indica la guía oficial.
 - Se distribuye como CLI (`npx parche-cli`) + GitHub Action (`Pepo08/parche@v0`). La GitHub App (instalación en un click, PRs automáticos al publicarse un pack nuevo) es el próximo paso.
 - La capa de LLM (redactar packs desde changelogs y resolver casos "falta un dato" leyendo el modelo de datos del cliente) todavía no está incluida; cuando entre, va a pasar por la misma verificación.

package/bin/parche.js

@@ -9,15 +9,22 @@ import { verify } from '../src/verify.js';
 import * as git from '../src/git.js';
 import { parseGithubRemote, openPullRequest } from '../src/github.js';
 import { record } from '../src/ledger.js';
+import { apiLabel } from '../src/inventory/index.js';
+import { isTestFile } from '../src/paths.js';
 
 const HELP = `parche — Dependabot para APIs
 
 Uso:
   parche packs                         Lista los cambios de API que Parche conoce
-  parche scan <dir> [--json]           Inventario de APIs + qué te afecta
+  parche scan <dir> [--json] [--upgrades]
+                                       Inventario de APIs + qué te afecta; con --upgrades,
+                                       qué cambia en las versiones nuevas de tus SDKs de npm
+  parche diff <paquete> --from <v> --to <v> [--json] [--all]
+                                       Qué cambia en la API de un paquete de npm entre dos versiones
   parche fix <dir> [--pack <id>]       Aplica los arreglos en el código
-  parche pr <dir> [--pack <id>] [--dry-run] [--verify]
-                                       Rama + commit + PR por cada cambio
+  parche pr <dir> [--pack <id>] [--dry-run] [--verify] [--push-remote <remote>]
+                                       Rama + commit + PR por cada cambio. Con --push-remote,
+                                       pushea a ese remote (tu fork) y abre el PR contra origin
   parche feedback <dir> --pack <id> --outcome merged|edited|rejected [--note "..."]
 `;
 
@@ -49,6 +56,65 @@ function ensureLocalDir(root) {
   }
 }
 
+// Inventario de cualquier API (nivel 1): todo lo que el repo usa, tenga pack o no.
+function printInventory(inventory) {
+  const KIND = { sdk: 'SDK ', http: 'HTTP', 'ai-model': 'IA  ' };
+  console.log(`APIs del repo (${inventory.apis.length}):`);
+  if (!inventory.apis.length) console.log('  (no se encontraron APIs de terceros)');
+  for (const api of inventory.apis) {
+    const ops = api.operations.map((o) => (o.count > 1 ? `${o.op} ×${o.count}` : o.op));
+    const shown = ops.length > 4 ? [...ops.slice(0, 4), `+${ops.length - 4} más`] : ops;
+    const packs = api.packs.length ? '  · con pack' : '';
+    console.log(`  ${KIND[api.kind]}  ${apiLabel(api).padEnd(38)} ${api.confidence.padEnd(5)}  ${shown.join(', ') || '(declarada, sin usos encontrados)'}${packs}`);
+  }
+  if (inventory.unresolved.length) {
+    console.log(`  + ${inventory.unresolved.length} llamada(s) HTTP con URL dinámica (no se sabe a qué host van; detalle en el reporte)`);
+  }
+}
+
+// Versiones nuevas de los SDKs de npm (scan --upgrades): qué operaciones del repo cambian o desaparecen.
+function printUpgrades(results) {
+  console.log('\nVersiones nuevas de tus SDKs de npm:');
+  if (!results.length) console.log('  (no hay SDKs de npm con operaciones para comparar)');
+  for (const r of results) {
+    const head = `  ${r.package.padEnd(22)} ${r.installed ? `${r.installed} → ${r.latest}`.padEnd(20) : ''.padEnd(20)}`;
+    if (r.status === 'afectado') {
+      console.log(`${head} ⚠ ${r.affected.length} de tus operaciones cambian o desaparecen`);
+      for (const a of r.affected) {
+        const where = a.locations.map((l) => `${l.file}:${l.line}`).join(', ');
+        console.log(`      ${a.op}  (${where})`);
+        for (const c of a.changes) console.log(`        ${c.message}`);
+      }
+    } else if (r.status === 'sin-impacto') {
+      console.log(`${head} ✓ lo que usás no cambia (${r.totalChanges} cambios en el SDK)${r.unverified.length ? ` · ${r.unverified.length} operación(es) sin verificar` : ''}`);
+    } else if (r.status === 'al-dia') {
+      console.log(`${head} ✓ al día`);
+    } else if (r.status === 'sin-verificar') {
+      console.log(`${head} ? tus operaciones no aparecen en los tipos de la versión instalada: no se puede verificar`);
+    } else {
+      console.log(`${head} — ${r.error || 'no se pudo determinar la versión instalada'}`);
+    }
+  }
+}
+
+// Salida de `parche diff`.
+function printDiff(d, { all = false } = {}) {
+  const groups = [
+    ['Desaparecen', d.changes.filter((c) => c.type === 'removed')],
+    ['Cambian los parámetros', d.changes.filter((c) => ['new-required', 'param-removed', 'type-changed'].includes(c.type))],
+    ['Pasan a deprecados', d.changes.filter((c) => c.type === 'deprecated')],
+  ];
+  console.log(`${d.pkg} ${d.from} → ${d.to}  (tipos: ${d.typesFrom} → ${d.typesTo})`);
+  if (!d.changes.length) console.log('  No hay cambios incompatibles en la superficie pública.');
+  for (const [title, list] of groups) {
+    if (!list.length) continue;
+    console.log(`\n${title} (${list.length}):`);
+    const shown = all ? list : list.slice(0, 25);
+    for (const c of shown) console.log(`  - ${c.message}`);
+    if (shown.length < list.length) console.log(`  … y ${list.length - shown.length} más (--all para verlos todos)`);
+  }
+}
+
 function printFindings(result) {
   for (const pack of result.packs) {
     const fs2 = result.findings.filter((f) => f.pack === pack.id);
@@ -71,24 +137,44 @@ async function main() {
     return 0;
   }
 
+  if (cmd === 'diff') {
+    const pkg = dirArg;
+    if (!pkg || !args.from || !args.to) throw new Error('Uso: parche diff <paquete> --from <versión> --to <versión>');
+    // TypeScript se carga recién acá: el scan común no lo necesita.
+    const { createRegistry } = await import('../src/sdk-diff/registry.js');
+    const { diffVersions } = await import('../src/sdk-diff/upgrades.js');
+    const d = await diffVersions(createRegistry(), pkg, String(args.from), String(args.to));
+    if (d.error) throw new Error(d.error);
+    if (args.json) { console.log(JSON.stringify({ pkg, from: d.from, to: d.to, changes: d.changes }, null, 2)); return 0; }
+    printDiff(d, { all: !!args.all });
+    return 0;
+  }
+
   const root = path.resolve(dirArg || '.');
   if (!fs.existsSync(root)) throw new Error(`No existe ${root}`);
   const packIds = args.pack ? [args.pack] : null;
 
   if (cmd === 'scan') {
     const result = run(root, { write: false, packIds });
+    let upgrades = null;
+    if (args.upgrades) {
+      if (!args.json) console.error('Buscando versiones nuevas de tus SDKs en npm...');
+      const { createRegistry } = await import('../src/sdk-diff/registry.js');
+      const { checkUpgrades } = await import('../src/sdk-diff/upgrades.js');
+      upgrades = await checkUpgrades(result.inventory, root, createRegistry());
+      result.inventory.upgrades = upgrades;
+    }
     ensureLocalDir(root);
     fs.writeFileSync(path.join(root, '.parche', 'inventory.json'), JSON.stringify(result.inventory, null, 2));
-    fs.writeFileSync(path.join(root, '.parche', 'report.md'), scanReport({ ...result, changed: [] }));
+    fs.writeFileSync(path.join(root, '.parche', 'report.md'), scanReport({ ...result, changed: [], upgrades }));
     record(root, { type: 'scan', findings: counts(result.findings) });
     if (args.json) { console.log(JSON.stringify({ inventory: result.inventory, findings: result.findings }, null, 2)); return 0; }
     console.log(`Parche · scan de ${path.basename(root)}\n`);
-    console.log('APIs encontradas:');
-    for (const [prov, p] of Object.entries(result.inventory.providers)) {
-      console.log(`  ${prov.padEnd(12)} ${String(p.callSites).padStart(2)} usos en ${p.files.length} archivo(s)  [${Object.keys(p.ops).join(', ')}]`);
-    }
+    printInventory(result.inventory);
+    if (upgrades) printUpgrades(upgrades);
     printFindings(result);
-    console.log(`\n${summary(result.findings)}`);
+    const s = summary(result.findings);
+    console.log(s ? `\n${s}` : '\nNinguno de los packs verificados tiene cambios que te afecten hoy.');
     console.log(`Reporte: ${path.join(root, '.parche', 'report.md')}`);
     return 0;
   }
@@ -107,49 +193,65 @@ async function main() {
   if (cmd === 'pr') {
     if (!git.isRepo(root)) throw new Error('`parche pr` necesita un repositorio git.');
     if (!git.isClean(root)) throw new Error('Hay cambios sin commitear. Commiteá o guardá (stash) antes de correr `parche pr`.');
+    // Quién firma el commit se resuelve antes de escribir nada: si falla al commitear, el repo quedaría sucio.
+    git.commitIdentity(root);
     ensureLocalDir(root);
     const base = git.currentBranch(root);
     const packs = loadPacks().filter((p) => p.codemod && (!packIds || packIds.includes(p.id)));
+    // A dónde se pushea: origin, o el fork de quien abre el PR (--push-remote fork). El PR se abre contra origin.
+    const pushRemote = typeof args['push-remote'] === 'string' ? args['push-remote'] : 'origin';
     for (const pack of packs) {
       const preview = run(root, { write: false, packIds: [pack.id] });
       if (!preview.findings.length) continue;
       const branch = `parche/${pack.id}`;
-      git.checkoutNewBranch(root, branch, base);
-      const result = run(root, { write: true, packIds: [pack.id] });
-      const changedFiles = result.changed.map((c) => c.file);
-      const verification = args.verify || args['dry-run'] ? verify(root, changedFiles, { runTests: !!args.verify }) : null;
-      if (verification && !verification.ok) {
-        git.checkout(root, base);
-        throw new Error(`La verificación falló para ${pack.id}; no se abre el PR.\n${JSON.stringify(verification, null, 2)}`);
-      }
-      const body = prBody({ pack, findings: result.findings, changed: result.changed, verification });
-      const bodyPath = path.join(root, '.parche', `pr-${pack.id}.md`);
-      fs.writeFileSync(bodyPath, body);
-      const c = counts(result.findings);
-      const draft = !!(c['needs-review'] || c['needs-input'] || c.blocked);
       const title = `Parche: ${pack.title}`;
-      console.log(`\n■ ${title}`);
-      if (!changedFiles.length) {
-        console.log('  Sin cambios de código: queda como issue/reporte (ver cuerpo del PR).');
+      git.checkoutNewBranch(root, branch, base);
+      let keepBranch = false;
+      try {
+        const result = run(root, { write: true, packIds: [pack.id] });
+        const changedFiles = result.changed.map((c) => c.file);
+        const c = counts(result.findings);
+        const bodyPath = path.join(root, '.parche', `pr-${pack.id}.md`);
+        console.log(`\n■ ${title}`);
+        // La sintaxis se chequea siempre (no ejecuta nada del repo); los tests, solo con --verify.
+        const verification = changedFiles.length ? verify(root, changedFiles, { runTests: !!args.verify }) : null;
+        if (verification && !verification.ok) {
+          // Nada de lo que escribió Parche queda en el repo: se descarta y se borra la rama.
+          git.discardChanges(root);
+          throw new Error(`La verificación falló para ${pack.id}; no se abre el PR y el repo queda como estaba.\n${JSON.stringify(verification, null, 2)}`);
+        }
+        fs.writeFileSync(bodyPath, prBody({ pack, findings: result.findings, changed: result.changed, verification }));
+        if (!changedFiles.length || changedFiles.every(isTestFile)) {
+          const why = changedFiles.length ? 'solo cambiaría tests o mocks: no se abre un PR' : 'sin cambios de código';
+          git.discardChanges(root);
+          console.log(`  ${summary(result.findings)}`);
+          console.log(`  ${why[0].toUpperCase()}${why.slice(1)}; queda como issue o reporte: ${bodyPath}`);
+          record(root, { type: 'report-only', pack: pack.id, findings: c, reason: why });
+          continue;
+        }
+        const draft = !!(c['needs-review'] || c['needs-input'] || c.blocked);
+        const sha = git.commitAll(root, `${title}\n\n${pack.summary_es}\nPack ${pack.id} v${pack.version}.`);
+        keepBranch = true;
+        console.log(`  Rama ${branch} · commit ${sha} · ${changedFiles.length} archivo(s)${verification ? ` · verificación ${verification.ok ? 'OK' : 'FALLÓ'}` : ''}`);
+        console.log(`  ${summary(result.findings)}`);
+        console.log(`  Cuerpo del PR: ${bodyPath}`);
+        const target = parseGithubRemote(git.originUrl(root));
+        const pushTo = parseGithubRemote(git.remoteUrl(root, pushRemote));
+        let url = null;
+        if (!args['dry-run'] && process.env.GITHUB_TOKEN && target && pushTo) {
+          git.push(root, branch, pushRemote);
+          const head = pushTo.owner !== target.owner ? `${pushTo.owner}:${branch}` : branch;
+          url = await openPullRequest({ token: process.env.GITHUB_TOKEN, ...target, head, base, title, body: fs.readFileSync(bodyPath, 'utf8'), draft });
+          console.log(`  PR abierto${draft ? ' (borrador)' : ''}: ${url}`);
+        } else {
+          console.log(`  Modo prueba: no se abrió el PR${draft ? ' (iría como borrador por tener ítems para revisar)' : ''}.`);
+        }
+        record(root, { type: 'pr', pack: pack.id, packVersion: pack.version, branch, sha, url, draft, files: changedFiles, findings: c });
+      } finally {
+        // Pase lo que pase, se vuelve a la rama base; la rama de Parche solo queda si tiene un commit.
         git.checkout(root, base);
-        record(root, { type: 'report-only', pack: pack.id, findings: c });
-        continue;
-      }
-      const sha = git.commitAll(root, `${title}\n\n${pack.summary_es}\nPack ${pack.id} v${pack.version}.`);
-      console.log(`  Rama ${branch} · commit ${sha} · ${changedFiles.length} archivo(s)${verification ? ` · verificación ${verification.ok ? 'OK' : 'FALLÓ'}` : ''}`);
-      console.log(`  ${summary(result.findings)}`);
-      console.log(`  Cuerpo del PR: ${bodyPath}`);
-      const remote = parseGithubRemote(git.originUrl(root));
-      let url = null;
-      if (!args['dry-run'] && process.env.GITHUB_TOKEN && remote) {
-        git.push(root, branch);
-        url = await openPullRequest({ token: process.env.GITHUB_TOKEN, ...remote, head: branch, base, title, body, draft });
-        console.log(`  PR abierto${draft ? ' (borrador)' : ''}: ${url}`);
-      } else {
-        console.log(`  Modo prueba: no se abrió el PR${draft ? ' (iría como borrador por tener ítems para revisar)' : ''}.`);
+        if (!keepBranch) git.deleteBranch(root, branch);
       }
-      record(root, { type: 'pr', pack: pack.id, packVersion: pack.version, branch, sha, url, draft, files: changedFiles, findings: c });
-      git.checkout(root, base);
     }
     return 0;
   }

package/data/known-sdks.json

@@ -0,0 +1,125 @@
+{
+  "schemaVersion": 1,
+  "about": "Lista curada de SDKs de APIs de terceros (paquete → proveedor y rubro), de clientes HTTP y de hosts de APIs conocidas. La usa el inventario de `parche scan`. Agregar entradas es la forma de subir la confianza de una detección de 'baja' a 'alta'.",
+  "npm": {
+    "stripe": { "provider": "Stripe", "category": "pagos" },
+    "@stripe/stripe-js": { "provider": "Stripe", "category": "pagos" },
+    "mercadopago": { "provider": "Mercado Pago", "category": "pagos" },
+    "@paypal/checkout-server-sdk": { "provider": "PayPal", "category": "pagos" },
+    "@paypal/paypal-server-sdk": { "provider": "PayPal", "category": "pagos" },
+    "braintree": { "provider": "Braintree", "category": "pagos" },
+    "plaid": { "provider": "Plaid", "category": "pagos" },
+    "@adyen/api-library": { "provider": "Adyen", "category": "pagos" },
+    "@afipsdk/afip.js": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "@arcasdk/core": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "afip.ts": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "ts-afip-ws": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "facturajs": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "openai": { "provider": "OpenAI", "category": "ia" },
+    "@anthropic-ai/sdk": { "provider": "Anthropic", "category": "ia" },
+    "@google/generative-ai": { "provider": "Google (Gemini)", "category": "ia" },
+    "@google/genai": { "provider": "Google (Gemini)", "category": "ia" },
+    "@mistralai/mistralai": { "provider": "Mistral", "category": "ia" },
+    "cohere-ai": { "provider": "Cohere", "category": "ia" },
+    "groq-sdk": { "provider": "Groq", "category": "ia" },
+    "replicate": { "provider": "Replicate", "category": "ia" },
+    "@huggingface/inference": { "provider": "Hugging Face", "category": "ia" },
+    "twilio": { "provider": "Twilio", "category": "mensajería" },
+    "@slack/web-api": { "provider": "Slack", "category": "mensajería" },
+    "@slack/bolt": { "provider": "Slack", "category": "mensajería" },
+    "discord.js": { "provider": "Discord", "category": "mensajería" },
+    "telegraf": { "provider": "Telegram", "category": "mensajería" },
+    "node-telegram-bot-api": { "provider": "Telegram", "category": "mensajería" },
+    "@sendgrid/mail": { "provider": "SendGrid", "category": "email" },
+    "resend": { "provider": "Resend", "category": "email" },
+    "postmark": { "provider": "Postmark", "category": "email" },
+    "mailgun.js": { "provider": "Mailgun", "category": "email" },
+    "@mailchimp/mailchimp_marketing": { "provider": "Mailchimp", "category": "email" },
+    "aws-sdk": { "provider": "AWS", "category": "nube" },
+    "firebase-admin": { "provider": "Firebase (Google)", "category": "nube" },
+    "firebase": { "provider": "Firebase (Google)", "category": "nube" },
+    "googleapis": { "provider": "Google APIs", "category": "nube" },
+    "@supabase/supabase-js": { "provider": "Supabase", "category": "datos" },
+    "algoliasearch": { "provider": "Algolia", "category": "datos" },
+    "@notionhq/client": { "provider": "Notion", "category": "productividad" },
+    "airtable": { "provider": "Airtable", "category": "productividad" },
+    "@octokit/rest": { "provider": "GitHub", "category": "devtools" },
+    "@octokit/core": { "provider": "GitHub", "category": "devtools" },
+    "@sentry/node": { "provider": "Sentry", "category": "observabilidad" },
+    "@shopify/shopify-api": { "provider": "Shopify", "category": "ecommerce" },
+    "@woocommerce/woocommerce-rest-api": { "provider": "WooCommerce", "category": "ecommerce" },
+    "@hubspot/api-client": { "provider": "HubSpot", "category": "crm" },
+    "contentful": { "provider": "Contentful", "category": "contenido" },
+    "@googlemaps/google-maps-services-js": { "provider": "Google Maps", "category": "mapas" },
+    "auth0": { "provider": "Auth0", "category": "auth" },
+    "@clerk/clerk-sdk-node": { "provider": "Clerk", "category": "auth" }
+  },
+  "npmPrefixes": {
+    "@aws-sdk/": { "provider": "AWS", "category": "nube" },
+    "@google-cloud/": { "provider": "Google Cloud", "category": "nube" },
+    "@azure/": { "provider": "Azure", "category": "nube" }
+  },
+  "composer": {
+    "afipsdk/afip.php": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "fertandil87/afip.php": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "ivanalemunioz/afip.php": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "eesnaola/afip.php": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "multinexo/php-afip-ws": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "mercadopago/dx-php": { "provider": "Mercado Pago", "category": "pagos" },
+    "stripe/stripe-php": { "provider": "Stripe", "category": "pagos" },
+    "twilio/sdk": { "provider": "Twilio", "category": "mensajería" },
+    "aws/aws-sdk-php": { "provider": "AWS", "category": "nube" },
+    "openai-php/client": { "provider": "OpenAI", "category": "ia" },
+    "sendgrid/sendgrid": { "provider": "SendGrid", "category": "email" },
+    "google/apiclient": { "provider": "Google APIs", "category": "nube" }
+  },
+  "pypi": {
+    "stripe": { "provider": "Stripe", "category": "pagos" },
+    "mercadopago": { "provider": "Mercado Pago", "category": "pagos" },
+    "openai": { "provider": "OpenAI", "category": "ia" },
+    "anthropic": { "provider": "Anthropic", "category": "ia" },
+    "google-generativeai": { "provider": "Google (Gemini)", "category": "ia" },
+    "twilio": { "provider": "Twilio", "category": "mensajería" },
+    "boto3": { "provider": "AWS", "category": "nube" },
+    "sendgrid": { "provider": "SendGrid", "category": "email" },
+    "slack-sdk": { "provider": "Slack", "category": "mensajería" },
+    "pyafipws": { "provider": "ARCA (ex AFIP)", "category": "facturación" }
+  },
+  "httpClients": {
+    "npm": ["axios", "got", "undici", "node-fetch", "ky", "superagent", "cross-fetch", "isomorphic-fetch"],
+    "composer": ["guzzlehttp/guzzle", "symfony/http-client"],
+    "pypi": ["requests", "httpx", "aiohttp", "urllib3"]
+  },
+  "notApis": {
+    "prefixes": ["@types/", "eslint", "@eslint/", "prettier", "jest", "@jest/", "vitest", "mocha", "typescript", "ts-node", "@babel/", "babel-", "webpack", "vite", "rollup", "esbuild", "@vitejs/", "nodemon", "husky", "lint-staged", "@testing-library/", "@apollo/", "graphql", "react", "vue", "svelte", "next", "nuxt", "express", "fastify", "koa", "@nestjs/", "@angular/", "socket.io", "@prisma/", "prisma", "@trpc/", "@tanstack/", "@redis/", "redis", "ioredis", "ws", "pg", "mysql", "mongodb", "mongoose", "sequelize", "typeorm", "knex", "drizzle-orm", "@aws-sdk/types", "@smithy/"],
+    "why": "Librerías de desarrollo, frameworks, bases de datos y transporte (socket.io, ws): no son la API de un tercero aunque el nombre diga 'client'."
+  },
+  "hosts": {
+    "api.stripe.com": { "provider": "Stripe", "category": "pagos" },
+    "api.mercadopago.com": { "provider": "Mercado Pago", "category": "pagos" },
+    "api.mercadolibre.com": { "provider": "Mercado Libre", "category": "ecommerce" },
+    "api.paypal.com": { "provider": "PayPal", "category": "pagos" },
+    "api-m.paypal.com": { "provider": "PayPal", "category": "pagos" },
+    "afip.gov.ar": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "arca.gob.ar": { "provider": "ARCA (ex AFIP)", "category": "facturación" },
+    "api.openai.com": { "provider": "OpenAI", "category": "ia" },
+    "api.anthropic.com": { "provider": "Anthropic", "category": "ia" },
+    "generativelanguage.googleapis.com": { "provider": "Google (Gemini)", "category": "ia" },
+    "api.mistral.ai": { "provider": "Mistral", "category": "ia" },
+    "api.twilio.com": { "provider": "Twilio", "category": "mensajería" },
+    "api.telegram.org": { "provider": "Telegram", "category": "mensajería" },
+    "graph.facebook.com": { "provider": "Meta (WhatsApp/Facebook)", "category": "mensajería" },
+    "slack.com": { "provider": "Slack", "category": "mensajería" },
+    "hooks.slack.com": { "provider": "Slack", "category": "mensajería" },
+    "discord.com": { "provider": "Discord", "category": "mensajería" },
+    "api.sendgrid.com": { "provider": "SendGrid", "category": "email" },
+    "api.resend.com": { "provider": "Resend", "category": "email" },
+    "api.github.com": { "provider": "GitHub", "category": "devtools" },
+    "googleapis.com": { "provider": "Google APIs", "category": "nube" },
+    "amazonaws.com": { "provider": "AWS", "category": "nube" },
+    "api.notion.com": { "provider": "Notion", "category": "productividad" },
+    "api.airtable.com": { "provider": "Airtable", "category": "productividad" },
+    "myshopify.com": { "provider": "Shopify", "category": "ecommerce" },
+    "api.hubapi.com": { "provider": "HubSpot", "category": "crm" }
+  }
+}