@hoilab/ada-cli 0.84.22 → 0.85.0

package/dist/core/edicion/tipos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../../src/core/edicion/tipos.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ¿La edición ha introducido un error de TIPOS?\n *\n * `parseo.ts` responde si el fichero sigue siendo sintácticamente válido, que\n * es el fallo más burdo. Este responde el siguiente: el fichero parsea, pero\n * llamas a la función con un argumento de más, o le pasas una cadena donde\n * esperaba un número. Hasta ahora eso solo salía al ejecutar `npm run check`,\n * que el modelo no lanza solo.\n *\n * oh-my-pi lo resuelve con un cliente LSP (9.920 líneas) que necesita un\n * servidor de lenguaje instalado. Aquí sale del compilador de TypeScript que ya\n * está en el proyecto, con un `LanguageService` que mantiene el programa vivo\n * entre ediciones. Medido sobre este repositorio (343 ficheros):\n *\n *     primera comprobación   2.500 ms   (una vez por proyecto, perezosa)\n *     otro fichero              14 ms\n *     tras cambiar el fichero  124-220 ms\n *\n * LA PRECONDICIÓN QUE LO HACE USABLE\n *\n * Solo se informa de lo que la edición ha INTRODUCIDO. Un repositorio a medio\n * refactorizar tiene cientos de errores de tipos, y volcárselos al modelo en\n * cada edición sería ruido puro: dejaría de leerlos el primer día y con ellos\n * el que sí importaba. Se comparan los diagnósticos de antes y los de después,\n * y solo viajan los nuevos.\n *\n * Y solo se paga cuando hace falta: si después de la edición no hay ningún\n * diagnóstico, no se calcula el \"antes\". La mayoría de ediciones son correctas,\n * así que el caso normal es una comprobación, no dos.\n */\n\nimport { dirname } from \"node:path\";\nimport ts from \"typescript\";\n\nexport interface ErrorDeTipos {\n\tlinea: number;\n\tmensaje: string;\n}\n\n/** Extensiones que tiene sentido comprobar. */\nconst COMPROBABLES = new Set([\".ts\", \".tsx\", \".mts\", \".cts\"]);\n\n/**\n * Tope de ficheros por proyecto.\n *\n * En un monorepo gigante la primera comprobación se va de las manos y el\n * usuario nota un parón que no ha pedido. Por encima del tope se calla y lo\n * dice — que es distinto de decir que está todo bien.\n */\nconst TOPE_FICHEROS = 5000;\n\ninterface Proyecto {\n\tservicio: ts.LanguageService;\n\t/** Contenido sobreescrito en memoria, por fichero. */\n\toverlay: Map<string, string>;\n\tversiones: Map<string, number>;\n\traiz: string;\n}\n\nexport type MotivoSinComprobar = \"extension-no-comprobable\" | \"sin-tsconfig\" | \"proyecto-demasiado-grande\";\n\nexport class ComprobadorDeTipos {\n\t/** Un servicio por `tsconfig`. Se reutiliza entre ediciones: es lo que hace que la segunda cueste 124 ms. */\n\tprivate readonly proyectos = new Map<string, Proyecto>();\n\tprivate readonly descartados = new Map<string, MotivoSinComprobar>();\n\n\t/** Por qué no se puede comprobar este fichero, o `null` si sí se puede. */\n\tporQueNo(ruta: string): MotivoSinComprobar | null {\n\t\tconst punto = ruta.lastIndexOf(\".\");\n\t\tif (punto === -1 || !COMPROBABLES.has(ruta.slice(punto).toLowerCase())) return \"extension-no-comprobable\";\n\t\tconst cfg = this.buscarConfig(ruta);\n\t\tif (!cfg) return \"sin-tsconfig\";\n\t\treturn this.descartados.get(cfg) ?? null;\n\t}\n\n\tprivate buscarConfig(ruta: string): string | undefined {\n\t\treturn ts.findConfigFile(dirname(ruta), ts.sys.fileExists, \"tsconfig.json\");\n\t}\n\n\tprivate proyectoDe(rutaConfig: string): Proyecto | null {\n\t\tconst existente = this.proyectos.get(rutaConfig);\n\t\tif (existente) return existente;\n\t\tif (this.descartados.has(rutaConfig)) return null;\n\n\t\tconst raiz = dirname(rutaConfig);\n\t\tconst cfg = ts.readConfigFile(rutaConfig, ts.sys.readFile);\n\t\tif (cfg.error) {\n\t\t\tthis.descartados.set(rutaConfig, \"sin-tsconfig\");\n\t\t\treturn null;\n\t\t}\n\t\tconst parsed = ts.parseJsonConfigFileContent(cfg.config, ts.sys, raiz);\n\t\tif (parsed.fileNames.length > TOPE_FICHEROS) {\n\t\t\tthis.descartados.set(rutaConfig, \"proyecto-demasiado-grande\");\n\t\t\treturn null;\n\t\t}\n\n\t\tconst overlay = new Map<string, string>();\n\t\tconst versiones = new Map<string, number>();\n\t\tconst host: ts.LanguageServiceHost = {\n\t\t\tgetScriptFileNames: () => parsed.fileNames,\n\t\t\tgetScriptVersion: (f) => String(versiones.get(f) ?? 0),\n\t\t\tgetScriptSnapshot: (f) => {\n\t\t\t\tconst texto = overlay.get(f) ?? ts.sys.readFile(f);\n\t\t\t\treturn texto === undefined ? undefined : ts.ScriptSnapshot.fromString(texto);\n\t\t\t},\n\t\t\tgetCurrentDirectory: () => raiz,\n\t\t\tgetCompilationSettings: () => parsed.options,\n\t\t\tgetDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),\n\t\t\tfileExists: (f) => overlay.has(f) || ts.sys.fileExists(f),\n\t\t\treadFile: (f) => overlay.get(f) ?? ts.sys.readFile(f),\n\t\t\treadDirectory: ts.sys.readDirectory,\n\t\t\tdirectoryExists: ts.sys.directoryExists,\n\t\t\tgetDirectories: ts.sys.getDirectories,\n\t\t};\n\t\tconst proyecto: Proyecto = {\n\t\t\tservicio: ts.createLanguageService(host, ts.createDocumentRegistry()),\n\t\t\toverlay,\n\t\t\tversiones,\n\t\t\traiz,\n\t\t};\n\t\tthis.proyectos.set(rutaConfig, proyecto);\n\t\treturn proyecto;\n\t}\n\n\t/** Diagnósticos de un contenido concreto, sin tocar el disco. */\n\tprivate diagnosticar(proyecto: Proyecto, ruta: string, contenido: string): ErrorDeTipos[] {\n\t\tproyecto.overlay.set(ruta, contenido);\n\t\tproyecto.versiones.set(ruta, (proyecto.versiones.get(ruta) ?? 0) + 1);\n\t\tlet brutos: readonly ts.Diagnostic[];\n\t\ttry {\n\t\t\tbrutos = proyecto.servicio.getSemanticDiagnostics(ruta);\n\t\t} catch {\n\t\t\t// Un fallo del servicio degrada la señal, no la sesión.\n\t\t\treturn [];\n\t\t}\n\t\tconst fuente = proyecto.servicio.getProgram()?.getSourceFile(ruta);\n\t\treturn brutos.map((d) => {\n\t\t\tconst pos = fuente && d.start !== undefined ? fuente.getLineAndCharacterOfPosition(d.start) : null;\n\t\t\treturn { linea: pos ? pos.line + 1 : 0, mensaje: ts.flattenDiagnosticMessageText(d.messageText, \" \") };\n\t\t});\n\t}\n\n\t/**\n\t * Los errores de tipos que esta edición ha INTRODUCIDO.\n\t *\n\t * Devuelve lista vacía cuando no hay ninguno nuevo, y también cuando no se\n\t * puede comprobar — para eso está `porQueNo()`, que quien llama debe mirar si\n\t * quiere distinguir «no hay errores» de «no lo he mirado». Son cosas muy\n\t * distintas y confundirlas es lo que convierte un aviso en una mentira.\n\t */\n\tintroducidos(ruta: string, antes: string | null, despues: string): ErrorDeTipos[] {\n\t\tif (this.porQueNo(ruta)) return [];\n\t\tconst cfg = this.buscarConfig(ruta);\n\t\tif (!cfg) return [];\n\t\tconst proyecto = this.proyectoDe(cfg);\n\t\tif (!proyecto) return [];\n\n\t\tconst despuesDiag = this.diagnosticar(proyecto, ruta, despues);\n\t\tif (despuesDiag.length === 0) {\n\t\t\tproyecto.overlay.delete(ruta);\n\t\t\treturn [];\n\t\t}\n\t\t// Solo aquí se paga la segunda comprobación: la mayoría de ediciones son\n\t\t// correctas y salen por el `return` de arriba con una sola.\n\t\tconst antesDiag = antes === null ? [] : this.diagnosticar(proyecto, ruta, antes);\n\t\tproyecto.overlay.delete(ruta);\n\n\t\tconst yaEstaban = new Set(antesDiag.map((d) => d.mensaje));\n\t\treturn despuesDiag.filter((d) => !yaEstaban.has(d.mensaje));\n\t}\n}\n\n/** El aviso para el modelo, o `null` si no hay nada que decir. */\nexport function avisoDeTipos(ruta: string, errores: ErrorDeTipos[]): string | null {\n\tif (errores.length === 0) return null;\n\tconst lineas = errores.slice(0, 3).map((e) => `  línea ${e.linea}: ${e.mensaje}`);\n\tconst resto = errores.length > 3 ? `\\n  …y ${errores.length - 3} más` : \"\";\n\treturn `⚠ Esta edición introduce ${errores.length === 1 ? \"un error\" : `${errores.length} errores`} de tipos en \\`${ruta}\\`:\\n${lineas.join(\"\\n\")}${resto}`;\n}\n"]}

package/dist/core/errores/proveedor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Qué ha pasado de verdad cuando el proveedor devuelve un error.
+ *
+ * Hoy se le enseña al usuario el error crudo. Esto es literal, capturado
+ * ejecutando `ada-cli review` durante el desarrollo:
+ *
+ *     El modelo no devolvió nada (error: 429: {"message":"Provider returned
+ *     error","code":429,"metadata":{"raw":"stealth/ox-alpha is temporarily
+ *     rate-limited upstream. Please retry shortly.","provider_name":"Stealth",
+ *     "is_byok":false,"limit_source":"upstream_provider_shared_pool",
+ *     "remedy_hint":"Retry shortly, add your own provider key (https://
+ *     openrouter.ai/settings/integrations), or route to another provider…"}}).
+ *
+ * Dentro de ese volcado hay tres cosas útiles —es un límite de tasa, es
+ * temporal, y hay tres salidas— y el usuario tiene que extraerlas a mano de un
+ * JSON de 400 caracteres. Peor: la mayoría no lo lee, y un error que no se lee
+ * es un error que se interpreta como «esto no funciona».
+ *
+ * Este módulo lo convierte en:
+ *
+ *     El proveedor está limitando la tasa (429). Es temporal.
+ *     Reintenta en unos segundos, cambia de modelo con /model, o configura tu
+ *     propia clave del proveedor.
+ *
+ * DOS DECISIONES QUE IMPORTAN
+ *
+ * - **`reintentable` es un dato, no una opinión.** Lo consume el código que
+ *   decide si volver a intentarlo; mezclarlo con el texto obligaría a leer
+ *   prosa para tomar una decisión de control.
+ * - **Lo desconocido se dice desconocido.** Una clasificación que inventa una
+ *   categoría plausible para todo es peor que ninguna: manda al usuario a
+ *   arreglar algo que no está roto. Cuando no se sabe, se devuelve el mensaje
+ *   original y se dice que no se ha podido clasificar.
+ */
+export type ClaseDeError = "limite-de-tasa" | "sin-credencial" | "credencial-invalida" | "cuota-agotada" | "modelo-no-disponible" | "contexto-excedido" | "contenido-rechazado" | "red" | "servidor" | "cancelado" | "desconocida";
+export interface ErrorClasificado {
+    clase: ClaseDeError;
+    /** ¿Tiene sentido volver a intentarlo tal cual? Dato de control, no prosa. */
+    reintentable: boolean;
+    /** Segundos que el proveedor pide esperar, cuando lo dice. */
+    esperarSegundos?: number;
+    /** Qué puede hacer el usuario, en una o dos líneas. */
+    queHacer: string;
+    /** El texto original, para quien necesite el detalle. */
+    original: string;
+}
+export declare function clasificarError(entrada: {
+    mensaje: string;
+    estado?: number;
+}): ErrorClasificado;
+/** El error, listo para enseñárselo a una persona. */
+export declare function explicarError(e: ErrorClasificado): string;
+//# sourceMappingURL=proveedor.d.ts.map

package/dist/core/errores/proveedor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proveedor.d.ts","sourceRoot":"","sources":["../../../src/core/errores/proveedor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,YAAY,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,qBAAqB,GACrB,eAAe,GACf,sBAAsB,GACtB,mBAAmB,GACnB,qBAAqB,GACrB,KAAK,GACL,UAAU,GACV,WAAW,GACX,aAAa,CAAC;AAEjB,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,YAAY,CAAC;IACpB,+EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CACjB;AAoJD,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CA2B/F;AAED,wDAAsD;AACtD,wBAAgB,aAAa,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAIzD","sourcesContent":["/**\n * Qué ha pasado de verdad cuando el proveedor devuelve un error.\n *\n * Hoy se le enseña al usuario el error crudo. Esto es literal, capturado\n * ejecutando `ada-cli review` durante el desarrollo:\n *\n *     El modelo no devolvió nada (error: 429: {\"message\":\"Provider returned\n *     error\",\"code\":429,\"metadata\":{\"raw\":\"stealth/ox-alpha is temporarily\n *     rate-limited upstream. Please retry shortly.\",\"provider_name\":\"Stealth\",\n *     \"is_byok\":false,\"limit_source\":\"upstream_provider_shared_pool\",\n *     \"remedy_hint\":\"Retry shortly, add your own provider key (https://\n *     openrouter.ai/settings/integrations), or route to another provider…\"}}).\n *\n * Dentro de ese volcado hay tres cosas útiles —es un límite de tasa, es\n * temporal, y hay tres salidas— y el usuario tiene que extraerlas a mano de un\n * JSON de 400 caracteres. Peor: la mayoría no lo lee, y un error que no se lee\n * es un error que se interpreta como «esto no funciona».\n *\n * Este módulo lo convierte en:\n *\n *     El proveedor está limitando la tasa (429). Es temporal.\n *     Reintenta en unos segundos, cambia de modelo con /model, o configura tu\n *     propia clave del proveedor.\n *\n * DOS DECISIONES QUE IMPORTAN\n *\n * - **`reintentable` es un dato, no una opinión.** Lo consume el código que\n *   decide si volver a intentarlo; mezclarlo con el texto obligaría a leer\n *   prosa para tomar una decisión de control.\n * - **Lo desconocido se dice desconocido.** Una clasificación que inventa una\n *   categoría plausible para todo es peor que ninguna: manda al usuario a\n *   arreglar algo que no está roto. Cuando no se sabe, se devuelve el mensaje\n *   original y se dice que no se ha podido clasificar.\n */\n\nexport type ClaseDeError =\n\t| \"limite-de-tasa\"\n\t| \"sin-credencial\"\n\t| \"credencial-invalida\"\n\t| \"cuota-agotada\"\n\t| \"modelo-no-disponible\"\n\t| \"contexto-excedido\"\n\t| \"contenido-rechazado\"\n\t| \"red\"\n\t| \"servidor\"\n\t| \"cancelado\"\n\t| \"desconocida\";\n\nexport interface ErrorClasificado {\n\tclase: ClaseDeError;\n\t/** ¿Tiene sentido volver a intentarlo tal cual? Dato de control, no prosa. */\n\treintentable: boolean;\n\t/** Segundos que el proveedor pide esperar, cuando lo dice. */\n\tesperarSegundos?: number;\n\t/** Qué puede hacer el usuario, en una o dos líneas. */\n\tqueHacer: string;\n\t/** El texto original, para quien necesite el detalle. */\n\toriginal: string;\n}\n\n/** Lo que el proveedor sugiere, cuando viene en el cuerpo. */\nfunction pistaDelProveedor(texto: string): string | null {\n\tconst m = texto.match(/\"remedy_hint\"\\s*:\\s*\"([^\"]{1,300})\"/);\n\treturn m ? m[1] : null;\n}\n\n/** `retry-after` en segundos, venga en cabecera o en el cuerpo. */\nfunction segundosDeEspera(texto: string): number | undefined {\n\tconst m = texto.match(/retry[-_\\s]?after[\"'\\s:]*(\\d{1,5})/i);\n\tif (m) return Number(m[1]);\n\tconst ms = texto.match(/\"retryAfterMs\"\\s*:\\s*(\\d{1,8})/);\n\treturn ms ? Math.ceil(Number(ms[1]) / 1000) : undefined;\n}\n\ninterface Regla {\n\tclase: ClaseDeError;\n\treintentable: boolean;\n\t/** Se prueba contra el texto completo (mensaje + cuerpo). */\n\tcoincide: (texto: string, estado?: number) => boolean;\n\tqueHacer: string;\n}\n\n/**\n * El orden importa: lo más específico primero.\n *\n * «Cuota agotada» y «límite de tasa» llegan los dos como 429 y se arreglan de\n * formas opuestas —uno esperando, el otro cambiando de plan o de cuenta—, así\n * que confundirlos manda al usuario a esperar indefinidamente algo que no va a\n * pasar.\n */\nconst REGLAS: Regla[] = [\n\t{\n\t\tclase: \"cancelado\",\n\t\treintentable: false,\n\t\tcoincide: (t) => /\\b(aborted|abortError|operation was aborted|cancell?ed)\\b/i.test(t),\n\t\tqueHacer: \"La operación se canceló. Si no fuiste tú, revisa si algo agotó el tiempo de espera.\",\n\t},\n\t{\n\t\tclase: \"cuota-agotada\",\n\t\treintentable: false,\n\t\tcoincide: (t) =>\n\t\t\t/\\b(usage limit|quota exceeded|credit balance|insufficient_quota|billing|out of credits|plan limit)\\b/i.test(\n\t\t\t\tt,\n\t\t\t),\n\t\tqueHacer:\n\t\t\t\"Se ha agotado la cuota o el saldo de esta cuenta. Esperar no lo arregla: cambia de modelo con /model, usa otra credencial o amplía el plan.\",\n\t},\n\t{\n\t\tclase: \"limite-de-tasa\",\n\t\treintentable: true,\n\t\tcoincide: (t, estado) => estado === 429 || /\\brate[- ]?limit(?:ed|ing|s)?\\b|\\btoo many requests\\b/i.test(t),\n\t\tqueHacer:\n\t\t\t\"El proveedor está limitando la tasa. Es temporal: reintenta en unos segundos, cambia de modelo con /model o configura tu propia clave del proveedor.\",\n\t},\n\t{\n\t\tclase: \"contexto-excedido\",\n\t\treintentable: false,\n\t\tcoincide: (t) =>\n\t\t\t/\\b(context[_\\s]length|maximum context|too many tokens|prompt is too long|context_length_exceeded)\\b/i.test(t),\n\t\tqueHacer:\n\t\t\t\"La conversación no cabe en la ventana del modelo. Compacta con /compact, empieza una sesión nueva o usa un modelo con más contexto.\",\n\t},\n\t{\n\t\tclase: \"credencial-invalida\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) =>\n\t\t\t(estado === 401 || estado === 403) &&\n\t\t\t/\\b(invalid|expired|revoked|invalidated|incorrect api key|unauthorized)\\b/i.test(t),\n\t\tqueHacer: \"La credencial no vale o ha caducado. Vuelve a autenticarte con /login.\",\n\t},\n\t{\n\t\tclase: \"sin-credencial\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) => estado === 401 || /\\b(no api key|missing api key|not authenticated)\\b/i.test(t),\n\t\tqueHacer: \"No hay credencial para este proveedor. Configúrala con /login.\",\n\t},\n\t{\n\t\tclase: \"modelo-no-disponible\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) =>\n\t\t\t(estado === 404 && /model/i.test(t)) ||\n\t\t\t/\\b(model_not_found|does not exist or you do not have access)\\b/i.test(t),\n\t\tqueHacer: \"Ese modelo no existe o tu cuenta no tiene acceso. Elige otro con /model.\",\n\t},\n\t{\n\t\tclase: \"contenido-rechazado\",\n\t\treintentable: false,\n\t\tcoincide: (t) => /\\b(content[_\\s]filter|safety|blocked by|refused to respond|policy violation)\\b/i.test(t),\n\t\tqueHacer: \"El proveedor ha rechazado el contenido por su política. Reformula la petición.\",\n\t},\n\t{\n\t\tclase: \"red\",\n\t\treintentable: true,\n\t\t// `connection error` lo añadió `ada-cli commit`: con el proveedor apagado,\n\t\t// el SDK de OpenAI devuelve literalmente «Connection error.» y ni una de\n\t\t// las palabras de arriba. Salía como \"no se ha podido clasificar\", que es\n\t\t// honesto pero deja al usuario sin saber que basta con mirar la red.\n\t\t//\n\t\t// `terminated` es el hermano del anterior y aparece cuando el proveedor NO\n\t\t// estaba apagado sino que se murió a media respuesta: undici corta el\n\t\t// socket y el SDK devuelve `{stopReason:\"error\", errorMessage:\"terminated\"}`.\n\t\t// Capturado ejecutando `commit` contra un servidor que emite un trozo y\n\t\t// destruye la conexión.\n\t\tcoincide: (t) =>\n\t\t\t/\\b(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|network error|connection error|fetch failed|terminated)\\b/i.test(\n\t\t\t\tt,\n\t\t\t),\n\t\tqueHacer: \"No se ha podido llegar al proveedor. Revisa la conexión o el proxy y reintenta.\",\n\t},\n\t{\n\t\tclase: \"servidor\",\n\t\treintentable: true,\n\t\tcoincide: (_t, estado) => estado !== undefined && estado >= 500 && estado < 600,\n\t\tqueHacer: \"El proveedor ha fallado por su lado. Suele arreglarse solo: reintenta en un momento.\",\n\t},\n];\n\n/** Saca el código HTTP del texto cuando no viene aparte. */\nfunction estadoDelTexto(texto: string): number | undefined {\n\t// También un código a pelo al principio (`429 Too Many Requests`), que es\n\t// como llega la mitad de los errores de proveedor. Exigir los dos puntos\n\t// dejaba sin clasificar justo el caso más común: lo cazó la prueba.\n\t//\n\t// Y el código ENTRE PARÉNTESIS, que es la otra mitad. `formatProviderError`\n\t// del SDK (packages/ai/src/utils/error-body.ts:128) arma el mensaje así:\n\t//\n\t//     `${prefix} (${status}): ${body}`     -> \"OpenAI API error (401): {…}\"\n\t//     `${status}: ${body}`                 -> \"429: {…}\"          (sin prefix)\n\t//\n\t// Solo la segunda forma casaba. La primera la usan `openai-responses` y\n\t// `azure-openai-responses`, o sea todo el que va por la Responses API de\n\t// OpenAI o por Azure. Medido ejecutando el clasificador sobre los formatos\n\t// reales del SDK: 4 de 6 salían \"desconocida\", entre ellos un 429 y un 401.\n\t// El 429 con el que se dio esto por bueno venía de openrouter, que va por\n\t// `openai-completions` y NO lleva prefijo — de ahí que pasara.\n\t//\n\t// Se exige el `):` pegado para no confundirlo con cualquier número de tres\n\t// cifras entre paréntesis que aparezca en el cuerpo del error.\n\tconst m =\n\t\ttexto.match(/\\b(?:status|code)[\"'\\s:]*(\\d{3})\\b/i) ??\n\t\ttexto.match(/\\((\\d{3})\\)\\s*:/) ??\n\t\ttexto.match(/^\\s*(\\d{3})\\b/);\n\tconst n = m ? Number(m[1]) : Number.NaN;\n\treturn n >= 100 && n < 600 ? n : undefined;\n}\n\nexport function clasificarError(entrada: { mensaje: string; estado?: number }): ErrorClasificado {\n\tconst texto = entrada.mensaje ?? \"\";\n\tconst estado = entrada.estado ?? estadoDelTexto(texto);\n\n\tfor (const regla of REGLAS) {\n\t\tif (!regla.coincide(texto, estado)) continue;\n\t\tconst pista = pistaDelProveedor(texto);\n\t\treturn {\n\t\t\tclase: regla.clase,\n\t\t\treintentable: regla.reintentable,\n\t\t\tesperarSegundos: segundosDeEspera(texto),\n\t\t\t// La pista del proveedor va DETRÁS de la nuestra, no en su lugar: la\n\t\t\t// nuestra está en el idioma del usuario y habla de nuestros comandos;\n\t\t\t// la suya conoce su infraestructura. Las dos suman.\n\t\t\tqueHacer: pista ? `${regla.queHacer}\\nEl proveedor añade: ${pista}` : regla.queHacer,\n\t\t\toriginal: texto,\n\t\t};\n\t}\n\n\t// Lo desconocido se dice desconocido. Inventar una categoría plausible manda\n\t// al usuario a arreglar algo que no está roto.\n\treturn {\n\t\tclase: \"desconocida\",\n\t\treintentable: false,\n\t\tqueHacer: \"No se ha podido clasificar este error. El mensaje original está debajo.\",\n\t\toriginal: texto,\n\t};\n}\n\n/** El error, listo para enseñárselo a una persona. */\nexport function explicarError(e: ErrorClasificado): string {\n\tconst espera = e.esperarSegundos ? ` Pide esperar ${e.esperarSegundos} s.` : \"\";\n\tif (e.clase === \"desconocida\") return `${e.queHacer}\\n${e.original}`;\n\treturn `${e.queHacer}${espera}`;\n}\n"]}

package/dist/core/errores/proveedor.js

@@ -0,0 +1,191 @@
+/**
+ * Qué ha pasado de verdad cuando el proveedor devuelve un error.
+ *
+ * Hoy se le enseña al usuario el error crudo. Esto es literal, capturado
+ * ejecutando `ada-cli review` durante el desarrollo:
+ *
+ *     El modelo no devolvió nada (error: 429: {"message":"Provider returned
+ *     error","code":429,"metadata":{"raw":"stealth/ox-alpha is temporarily
+ *     rate-limited upstream. Please retry shortly.","provider_name":"Stealth",
+ *     "is_byok":false,"limit_source":"upstream_provider_shared_pool",
+ *     "remedy_hint":"Retry shortly, add your own provider key (https://
+ *     openrouter.ai/settings/integrations), or route to another provider…"}}).
+ *
+ * Dentro de ese volcado hay tres cosas útiles —es un límite de tasa, es
+ * temporal, y hay tres salidas— y el usuario tiene que extraerlas a mano de un
+ * JSON de 400 caracteres. Peor: la mayoría no lo lee, y un error que no se lee
+ * es un error que se interpreta como «esto no funciona».
+ *
+ * Este módulo lo convierte en:
+ *
+ *     El proveedor está limitando la tasa (429). Es temporal.
+ *     Reintenta en unos segundos, cambia de modelo con /model, o configura tu
+ *     propia clave del proveedor.
+ *
+ * DOS DECISIONES QUE IMPORTAN
+ *
+ * - **`reintentable` es un dato, no una opinión.** Lo consume el código que
+ *   decide si volver a intentarlo; mezclarlo con el texto obligaría a leer
+ *   prosa para tomar una decisión de control.
+ * - **Lo desconocido se dice desconocido.** Una clasificación que inventa una
+ *   categoría plausible para todo es peor que ninguna: manda al usuario a
+ *   arreglar algo que no está roto. Cuando no se sabe, se devuelve el mensaje
+ *   original y se dice que no se ha podido clasificar.
+ */
+/** Lo que el proveedor sugiere, cuando viene en el cuerpo. */
+function pistaDelProveedor(texto) {
+    const m = texto.match(/"remedy_hint"\s*:\s*"([^"]{1,300})"/);
+    return m ? m[1] : null;
+}
+/** `retry-after` en segundos, venga en cabecera o en el cuerpo. */
+function segundosDeEspera(texto) {
+    const m = texto.match(/retry[-_\s]?after["'\s:]*(\d{1,5})/i);
+    if (m)
+        return Number(m[1]);
+    const ms = texto.match(/"retryAfterMs"\s*:\s*(\d{1,8})/);
+    return ms ? Math.ceil(Number(ms[1]) / 1000) : undefined;
+}
+/**
+ * El orden importa: lo más específico primero.
+ *
+ * «Cuota agotada» y «límite de tasa» llegan los dos como 429 y se arreglan de
+ * formas opuestas —uno esperando, el otro cambiando de plan o de cuenta—, así
+ * que confundirlos manda al usuario a esperar indefinidamente algo que no va a
+ * pasar.
+ */
+const REGLAS = [
+    {
+        clase: "cancelado",
+        reintentable: false,
+        coincide: (t) => /\b(aborted|abortError|operation was aborted|cancell?ed)\b/i.test(t),
+        queHacer: "La operación se canceló. Si no fuiste tú, revisa si algo agotó el tiempo de espera.",
+    },
+    {
+        clase: "cuota-agotada",
+        reintentable: false,
+        coincide: (t) => /\b(usage limit|quota exceeded|credit balance|insufficient_quota|billing|out of credits|plan limit)\b/i.test(t),
+        queHacer: "Se ha agotado la cuota o el saldo de esta cuenta. Esperar no lo arregla: cambia de modelo con /model, usa otra credencial o amplía el plan.",
+    },
+    {
+        clase: "limite-de-tasa",
+        reintentable: true,
+        coincide: (t, estado) => estado === 429 || /\brate[- ]?limit(?:ed|ing|s)?\b|\btoo many requests\b/i.test(t),
+        queHacer: "El proveedor está limitando la tasa. Es temporal: reintenta en unos segundos, cambia de modelo con /model o configura tu propia clave del proveedor.",
+    },
+    {
+        clase: "contexto-excedido",
+        reintentable: false,
+        coincide: (t) => /\b(context[_\s]length|maximum context|too many tokens|prompt is too long|context_length_exceeded)\b/i.test(t),
+        queHacer: "La conversación no cabe en la ventana del modelo. Compacta con /compact, empieza una sesión nueva o usa un modelo con más contexto.",
+    },
+    {
+        clase: "credencial-invalida",
+        reintentable: false,
+        coincide: (t, estado) => (estado === 401 || estado === 403) &&
+            /\b(invalid|expired|revoked|invalidated|incorrect api key|unauthorized)\b/i.test(t),
+        queHacer: "La credencial no vale o ha caducado. Vuelve a autenticarte con /login.",
+    },
+    {
+        clase: "sin-credencial",
+        reintentable: false,
+        coincide: (t, estado) => estado === 401 || /\b(no api key|missing api key|not authenticated)\b/i.test(t),
+        queHacer: "No hay credencial para este proveedor. Configúrala con /login.",
+    },
+    {
+        clase: "modelo-no-disponible",
+        reintentable: false,
+        coincide: (t, estado) => (estado === 404 && /model/i.test(t)) ||
+            /\b(model_not_found|does not exist or you do not have access)\b/i.test(t),
+        queHacer: "Ese modelo no existe o tu cuenta no tiene acceso. Elige otro con /model.",
+    },
+    {
+        clase: "contenido-rechazado",
+        reintentable: false,
+        coincide: (t) => /\b(content[_\s]filter|safety|blocked by|refused to respond|policy violation)\b/i.test(t),
+        queHacer: "El proveedor ha rechazado el contenido por su política. Reformula la petición.",
+    },
+    {
+        clase: "red",
+        reintentable: true,
+        // `connection error` lo añadió `ada-cli commit`: con el proveedor apagado,
+        // el SDK de OpenAI devuelve literalmente «Connection error.» y ni una de
+        // las palabras de arriba. Salía como "no se ha podido clasificar", que es
+        // honesto pero deja al usuario sin saber que basta con mirar la red.
+        //
+        // `terminated` es el hermano del anterior y aparece cuando el proveedor NO
+        // estaba apagado sino que se murió a media respuesta: undici corta el
+        // socket y el SDK devuelve `{stopReason:"error", errorMessage:"terminated"}`.
+        // Capturado ejecutando `commit` contra un servidor que emite un trozo y
+        // destruye la conexión.
+        coincide: (t) => /\b(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|network error|connection error|fetch failed|terminated)\b/i.test(t),
+        queHacer: "No se ha podido llegar al proveedor. Revisa la conexión o el proxy y reintenta.",
+    },
+    {
+        clase: "servidor",
+        reintentable: true,
+        coincide: (_t, estado) => estado !== undefined && estado >= 500 && estado < 600,
+        queHacer: "El proveedor ha fallado por su lado. Suele arreglarse solo: reintenta en un momento.",
+    },
+];
+/** Saca el código HTTP del texto cuando no viene aparte. */
+function estadoDelTexto(texto) {
+    // También un código a pelo al principio (`429 Too Many Requests`), que es
+    // como llega la mitad de los errores de proveedor. Exigir los dos puntos
+    // dejaba sin clasificar justo el caso más común: lo cazó la prueba.
+    //
+    // Y el código ENTRE PARÉNTESIS, que es la otra mitad. `formatProviderError`
+    // del SDK (packages/ai/src/utils/error-body.ts:128) arma el mensaje así:
+    //
+    //     `${prefix} (${status}): ${body}`     -> "OpenAI API error (401): {…}"
+    //     `${status}: ${body}`                 -> "429: {…}"          (sin prefix)
+    //
+    // Solo la segunda forma casaba. La primera la usan `openai-responses` y
+    // `azure-openai-responses`, o sea todo el que va por la Responses API de
+    // OpenAI o por Azure. Medido ejecutando el clasificador sobre los formatos
+    // reales del SDK: 4 de 6 salían "desconocida", entre ellos un 429 y un 401.
+    // El 429 con el que se dio esto por bueno venía de openrouter, que va por
+    // `openai-completions` y NO lleva prefijo — de ahí que pasara.
+    //
+    // Se exige el `):` pegado para no confundirlo con cualquier número de tres
+    // cifras entre paréntesis que aparezca en el cuerpo del error.
+    const m = texto.match(/\b(?:status|code)["'\s:]*(\d{3})\b/i) ??
+        texto.match(/\((\d{3})\)\s*:/) ??
+        texto.match(/^\s*(\d{3})\b/);
+    const n = m ? Number(m[1]) : Number.NaN;
+    return n >= 100 && n < 600 ? n : undefined;
+}
+export function clasificarError(entrada) {
+    const texto = entrada.mensaje ?? "";
+    const estado = entrada.estado ?? estadoDelTexto(texto);
+    for (const regla of REGLAS) {
+        if (!regla.coincide(texto, estado))
+            continue;
+        const pista = pistaDelProveedor(texto);
+        return {
+            clase: regla.clase,
+            reintentable: regla.reintentable,
+            esperarSegundos: segundosDeEspera(texto),
+            // La pista del proveedor va DETRÁS de la nuestra, no en su lugar: la
+            // nuestra está en el idioma del usuario y habla de nuestros comandos;
+            // la suya conoce su infraestructura. Las dos suman.
+            queHacer: pista ? `${regla.queHacer}\nEl proveedor añade: ${pista}` : regla.queHacer,
+            original: texto,
+        };
+    }
+    // Lo desconocido se dice desconocido. Inventar una categoría plausible manda
+    // al usuario a arreglar algo que no está roto.
+    return {
+        clase: "desconocida",
+        reintentable: false,
+        queHacer: "No se ha podido clasificar este error. El mensaje original está debajo.",
+        original: texto,
+    };
+}
+/** El error, listo para enseñárselo a una persona. */
+export function explicarError(e) {
+    const espera = e.esperarSegundos ? ` Pide esperar ${e.esperarSegundos} s.` : "";
+    if (e.clase === "desconocida")
+        return `${e.queHacer}\n${e.original}`;
+    return `${e.queHacer}${espera}`;
+}
+//# sourceMappingURL=proveedor.js.map

package/dist/core/errores/proveedor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proveedor.js","sourceRoot":"","sources":["../../../src/core/errores/proveedor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA2BH,8DAA8D;AAC9D,SAAS,iBAAiB,CAAC,KAAa,EAAiB;IACxD,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAAA,CACvB;AAED,mEAAmE;AACnE,SAAS,gBAAgB,CAAC,KAAa,EAAsB;IAC5D,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC7D,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACzD,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACxD;AAUD;;;;;;;GAOG;AACH,MAAM,MAAM,GAAY;IACvB;QACC,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,4DAA4D,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,QAAQ,EAAE,yFAAqF;KAC/F;IACD;QACC,KAAK,EAAE,eAAe;QACtB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,uGAAuG,CAAC,IAAI,CAC3G,CAAC,CACD;QACF,QAAQ,EACP,8IAA6I;KAC9I;IACD;QACC,KAAK,EAAE,gBAAgB;QACvB,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,GAAG,IAAI,wDAAwD,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3G,QAAQ,EACP,uJAAsJ;KACvJ;IACD;QACC,KAAK,EAAE,mBAAmB;QAC1B,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,sGAAsG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/G,QAAQ,EACP,wIAAqI;KACtI;IACD;QACC,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CACvB,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;YAClC,2EAA2E,CAAC,IAAI,CAAC,CAAC,CAAC;QACpF,QAAQ,EAAE,wEAAwE;KAClF;IACD;QACC,KAAK,EAAE,gBAAgB;QACvB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,GAAG,IAAI,qDAAqD,CAAC,IAAI,CAAC,CAAC,CAAC;QACxG,QAAQ,EAAE,iEAAgE;KAC1E;IACD;QACC,KAAK,EAAE,sBAAsB;QAC7B,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CACvB,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpC,iEAAiE,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,QAAQ,EAAE,0EAA0E;KACpF;IACD;QACC,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,iFAAiF,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1G,QAAQ,EAAE,kFAAgF;KAC1F;IACD;QACC,KAAK,EAAE,KAAK;QACZ,YAAY,EAAE,IAAI;QAClB,6EAA2E;QAC3E,2EAAyE;QACzE,2EAA0E;QAC1E,qEAAqE;QACrE,EAAE;QACF,2EAA2E;QAC3E,uEAAsE;QACtE,8EAA8E;QAC9E,wEAAwE;QACxE,yBAAwB;QACxB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,oIAAoI,CAAC,IAAI,CACxI,CAAC,CACD;QACF,QAAQ,EAAE,kFAAiF;KAC3F;IACD;QACC,KAAK,EAAE,UAAU;QACjB,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAC/E,QAAQ,EAAE,sFAAsF;KAChG;CACD,CAAC;AAEF,6DAA4D;AAC5D,SAAS,cAAc,CAAC,KAAa,EAAsB;IAC1D,4EAA0E;IAC1E,yEAAyE;IACzE,uEAAoE;IACpE,EAAE;IACF,8EAA4E;IAC5E,0EAAyE;IACzE,EAAE;IACF,8EAA4E;IAC5E,iFAA+E;IAC/E,EAAE;IACF,wEAAwE;IACxE,yEAAyE;IACzE,2EAA2E;IAC3E,6EAA4E;IAC5E,2EAA0E;IAC1E,kEAA+D;IAC/D,EAAE;IACF,4EAA2E;IAC3E,gEAA+D;IAC/D,MAAM,CAAC,GACN,KAAK,CAAC,KAAK,CAAC,qCAAqC,CAAC;QAClD,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC;QAC9B,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACxC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CAC3C;AAED,MAAM,UAAU,eAAe,CAAC,OAA6C,EAAoB;IAChG,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC;IAEvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,SAAS;QAC7C,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO;YACN,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,eAAe,EAAE,gBAAgB,CAAC,KAAK,CAAC;YACxC,sEAAqE;YACrE,uEAAsE;YACtE,oDAAoD;YACpD,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,0BAAyB,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ;YACpF,QAAQ,EAAE,KAAK;SACf,CAAC;IACH,CAAC;IAED,8EAA6E;IAC7E,gDAA+C;IAC/C,OAAO;QACN,KAAK,EAAE,aAAa;QACpB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,0EAAyE;QACnF,QAAQ,EAAE,KAAK;KACf,CAAC;AAAA,CACF;AAED,wDAAsD;AACtD,MAAM,UAAU,aAAa,CAAC,CAAmB,EAAU;IAC1D,MAAM,MAAM,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,eAAe,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,IAAI,CAAC,CAAC,KAAK,KAAK,aAAa;QAAE,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;IACrE,OAAO,GAAG,CAAC,CAAC,QAAQ,GAAG,MAAM,EAAE,CAAC;AAAA,CAChC","sourcesContent":["/**\n * Qué ha pasado de verdad cuando el proveedor devuelve un error.\n *\n * Hoy se le enseña al usuario el error crudo. Esto es literal, capturado\n * ejecutando `ada-cli review` durante el desarrollo:\n *\n *     El modelo no devolvió nada (error: 429: {\"message\":\"Provider returned\n *     error\",\"code\":429,\"metadata\":{\"raw\":\"stealth/ox-alpha is temporarily\n *     rate-limited upstream. Please retry shortly.\",\"provider_name\":\"Stealth\",\n *     \"is_byok\":false,\"limit_source\":\"upstream_provider_shared_pool\",\n *     \"remedy_hint\":\"Retry shortly, add your own provider key (https://\n *     openrouter.ai/settings/integrations), or route to another provider…\"}}).\n *\n * Dentro de ese volcado hay tres cosas útiles —es un límite de tasa, es\n * temporal, y hay tres salidas— y el usuario tiene que extraerlas a mano de un\n * JSON de 400 caracteres. Peor: la mayoría no lo lee, y un error que no se lee\n * es un error que se interpreta como «esto no funciona».\n *\n * Este módulo lo convierte en:\n *\n *     El proveedor está limitando la tasa (429). Es temporal.\n *     Reintenta en unos segundos, cambia de modelo con /model, o configura tu\n *     propia clave del proveedor.\n *\n * DOS DECISIONES QUE IMPORTAN\n *\n * - **`reintentable` es un dato, no una opinión.** Lo consume el código que\n *   decide si volver a intentarlo; mezclarlo con el texto obligaría a leer\n *   prosa para tomar una decisión de control.\n * - **Lo desconocido se dice desconocido.** Una clasificación que inventa una\n *   categoría plausible para todo es peor que ninguna: manda al usuario a\n *   arreglar algo que no está roto. Cuando no se sabe, se devuelve el mensaje\n *   original y se dice que no se ha podido clasificar.\n */\n\nexport type ClaseDeError =\n\t| \"limite-de-tasa\"\n\t| \"sin-credencial\"\n\t| \"credencial-invalida\"\n\t| \"cuota-agotada\"\n\t| \"modelo-no-disponible\"\n\t| \"contexto-excedido\"\n\t| \"contenido-rechazado\"\n\t| \"red\"\n\t| \"servidor\"\n\t| \"cancelado\"\n\t| \"desconocida\";\n\nexport interface ErrorClasificado {\n\tclase: ClaseDeError;\n\t/** ¿Tiene sentido volver a intentarlo tal cual? Dato de control, no prosa. */\n\treintentable: boolean;\n\t/** Segundos que el proveedor pide esperar, cuando lo dice. */\n\tesperarSegundos?: number;\n\t/** Qué puede hacer el usuario, en una o dos líneas. */\n\tqueHacer: string;\n\t/** El texto original, para quien necesite el detalle. */\n\toriginal: string;\n}\n\n/** Lo que el proveedor sugiere, cuando viene en el cuerpo. */\nfunction pistaDelProveedor(texto: string): string | null {\n\tconst m = texto.match(/\"remedy_hint\"\\s*:\\s*\"([^\"]{1,300})\"/);\n\treturn m ? m[1] : null;\n}\n\n/** `retry-after` en segundos, venga en cabecera o en el cuerpo. */\nfunction segundosDeEspera(texto: string): number | undefined {\n\tconst m = texto.match(/retry[-_\\s]?after[\"'\\s:]*(\\d{1,5})/i);\n\tif (m) return Number(m[1]);\n\tconst ms = texto.match(/\"retryAfterMs\"\\s*:\\s*(\\d{1,8})/);\n\treturn ms ? Math.ceil(Number(ms[1]) / 1000) : undefined;\n}\n\ninterface Regla {\n\tclase: ClaseDeError;\n\treintentable: boolean;\n\t/** Se prueba contra el texto completo (mensaje + cuerpo). */\n\tcoincide: (texto: string, estado?: number) => boolean;\n\tqueHacer: string;\n}\n\n/**\n * El orden importa: lo más específico primero.\n *\n * «Cuota agotada» y «límite de tasa» llegan los dos como 429 y se arreglan de\n * formas opuestas —uno esperando, el otro cambiando de plan o de cuenta—, así\n * que confundirlos manda al usuario a esperar indefinidamente algo que no va a\n * pasar.\n */\nconst REGLAS: Regla[] = [\n\t{\n\t\tclase: \"cancelado\",\n\t\treintentable: false,\n\t\tcoincide: (t) => /\\b(aborted|abortError|operation was aborted|cancell?ed)\\b/i.test(t),\n\t\tqueHacer: \"La operación se canceló. Si no fuiste tú, revisa si algo agotó el tiempo de espera.\",\n\t},\n\t{\n\t\tclase: \"cuota-agotada\",\n\t\treintentable: false,\n\t\tcoincide: (t) =>\n\t\t\t/\\b(usage limit|quota exceeded|credit balance|insufficient_quota|billing|out of credits|plan limit)\\b/i.test(\n\t\t\t\tt,\n\t\t\t),\n\t\tqueHacer:\n\t\t\t\"Se ha agotado la cuota o el saldo de esta cuenta. Esperar no lo arregla: cambia de modelo con /model, usa otra credencial o amplía el plan.\",\n\t},\n\t{\n\t\tclase: \"limite-de-tasa\",\n\t\treintentable: true,\n\t\tcoincide: (t, estado) => estado === 429 || /\\brate[- ]?limit(?:ed|ing|s)?\\b|\\btoo many requests\\b/i.test(t),\n\t\tqueHacer:\n\t\t\t\"El proveedor está limitando la tasa. Es temporal: reintenta en unos segundos, cambia de modelo con /model o configura tu propia clave del proveedor.\",\n\t},\n\t{\n\t\tclase: \"contexto-excedido\",\n\t\treintentable: false,\n\t\tcoincide: (t) =>\n\t\t\t/\\b(context[_\\s]length|maximum context|too many tokens|prompt is too long|context_length_exceeded)\\b/i.test(t),\n\t\tqueHacer:\n\t\t\t\"La conversación no cabe en la ventana del modelo. Compacta con /compact, empieza una sesión nueva o usa un modelo con más contexto.\",\n\t},\n\t{\n\t\tclase: \"credencial-invalida\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) =>\n\t\t\t(estado === 401 || estado === 403) &&\n\t\t\t/\\b(invalid|expired|revoked|invalidated|incorrect api key|unauthorized)\\b/i.test(t),\n\t\tqueHacer: \"La credencial no vale o ha caducado. Vuelve a autenticarte con /login.\",\n\t},\n\t{\n\t\tclase: \"sin-credencial\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) => estado === 401 || /\\b(no api key|missing api key|not authenticated)\\b/i.test(t),\n\t\tqueHacer: \"No hay credencial para este proveedor. Configúrala con /login.\",\n\t},\n\t{\n\t\tclase: \"modelo-no-disponible\",\n\t\treintentable: false,\n\t\tcoincide: (t, estado) =>\n\t\t\t(estado === 404 && /model/i.test(t)) ||\n\t\t\t/\\b(model_not_found|does not exist or you do not have access)\\b/i.test(t),\n\t\tqueHacer: \"Ese modelo no existe o tu cuenta no tiene acceso. Elige otro con /model.\",\n\t},\n\t{\n\t\tclase: \"contenido-rechazado\",\n\t\treintentable: false,\n\t\tcoincide: (t) => /\\b(content[_\\s]filter|safety|blocked by|refused to respond|policy violation)\\b/i.test(t),\n\t\tqueHacer: \"El proveedor ha rechazado el contenido por su política. Reformula la petición.\",\n\t},\n\t{\n\t\tclase: \"red\",\n\t\treintentable: true,\n\t\t// `connection error` lo añadió `ada-cli commit`: con el proveedor apagado,\n\t\t// el SDK de OpenAI devuelve literalmente «Connection error.» y ni una de\n\t\t// las palabras de arriba. Salía como \"no se ha podido clasificar\", que es\n\t\t// honesto pero deja al usuario sin saber que basta con mirar la red.\n\t\t//\n\t\t// `terminated` es el hermano del anterior y aparece cuando el proveedor NO\n\t\t// estaba apagado sino que se murió a media respuesta: undici corta el\n\t\t// socket y el SDK devuelve `{stopReason:\"error\", errorMessage:\"terminated\"}`.\n\t\t// Capturado ejecutando `commit` contra un servidor que emite un trozo y\n\t\t// destruye la conexión.\n\t\tcoincide: (t) =>\n\t\t\t/\\b(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|socket hang up|network error|connection error|fetch failed|terminated)\\b/i.test(\n\t\t\t\tt,\n\t\t\t),\n\t\tqueHacer: \"No se ha podido llegar al proveedor. Revisa la conexión o el proxy y reintenta.\",\n\t},\n\t{\n\t\tclase: \"servidor\",\n\t\treintentable: true,\n\t\tcoincide: (_t, estado) => estado !== undefined && estado >= 500 && estado < 600,\n\t\tqueHacer: \"El proveedor ha fallado por su lado. Suele arreglarse solo: reintenta en un momento.\",\n\t},\n];\n\n/** Saca el código HTTP del texto cuando no viene aparte. */\nfunction estadoDelTexto(texto: string): number | undefined {\n\t// También un código a pelo al principio (`429 Too Many Requests`), que es\n\t// como llega la mitad de los errores de proveedor. Exigir los dos puntos\n\t// dejaba sin clasificar justo el caso más común: lo cazó la prueba.\n\t//\n\t// Y el código ENTRE PARÉNTESIS, que es la otra mitad. `formatProviderError`\n\t// del SDK (packages/ai/src/utils/error-body.ts:128) arma el mensaje así:\n\t//\n\t//     `${prefix} (${status}): ${body}`     -> \"OpenAI API error (401): {…}\"\n\t//     `${status}: ${body}`                 -> \"429: {…}\"          (sin prefix)\n\t//\n\t// Solo la segunda forma casaba. La primera la usan `openai-responses` y\n\t// `azure-openai-responses`, o sea todo el que va por la Responses API de\n\t// OpenAI o por Azure. Medido ejecutando el clasificador sobre los formatos\n\t// reales del SDK: 4 de 6 salían \"desconocida\", entre ellos un 429 y un 401.\n\t// El 429 con el que se dio esto por bueno venía de openrouter, que va por\n\t// `openai-completions` y NO lleva prefijo — de ahí que pasara.\n\t//\n\t// Se exige el `):` pegado para no confundirlo con cualquier número de tres\n\t// cifras entre paréntesis que aparezca en el cuerpo del error.\n\tconst m =\n\t\ttexto.match(/\\b(?:status|code)[\"'\\s:]*(\\d{3})\\b/i) ??\n\t\ttexto.match(/\\((\\d{3})\\)\\s*:/) ??\n\t\ttexto.match(/^\\s*(\\d{3})\\b/);\n\tconst n = m ? Number(m[1]) : Number.NaN;\n\treturn n >= 100 && n < 600 ? n : undefined;\n}\n\nexport function clasificarError(entrada: { mensaje: string; estado?: number }): ErrorClasificado {\n\tconst texto = entrada.mensaje ?? \"\";\n\tconst estado = entrada.estado ?? estadoDelTexto(texto);\n\n\tfor (const regla of REGLAS) {\n\t\tif (!regla.coincide(texto, estado)) continue;\n\t\tconst pista = pistaDelProveedor(texto);\n\t\treturn {\n\t\t\tclase: regla.clase,\n\t\t\treintentable: regla.reintentable,\n\t\t\tesperarSegundos: segundosDeEspera(texto),\n\t\t\t// La pista del proveedor va DETRÁS de la nuestra, no en su lugar: la\n\t\t\t// nuestra está en el idioma del usuario y habla de nuestros comandos;\n\t\t\t// la suya conoce su infraestructura. Las dos suman.\n\t\t\tqueHacer: pista ? `${regla.queHacer}\\nEl proveedor añade: ${pista}` : regla.queHacer,\n\t\t\toriginal: texto,\n\t\t};\n\t}\n\n\t// Lo desconocido se dice desconocido. Inventar una categoría plausible manda\n\t// al usuario a arreglar algo que no está roto.\n\treturn {\n\t\tclase: \"desconocida\",\n\t\treintentable: false,\n\t\tqueHacer: \"No se ha podido clasificar este error. El mensaje original está debajo.\",\n\t\toriginal: texto,\n\t};\n}\n\n/** El error, listo para enseñárselo a una persona. */\nexport function explicarError(e: ErrorClasificado): string {\n\tconst espera = e.esperarSegundos ? ` Pide esperar ${e.esperarSegundos} s.` : \"\";\n\tif (e.clase === \"desconocida\") return `${e.queHacer}\\n${e.original}`;\n\treturn `${e.queHacer}${espera}`;\n}\n"]}

package/dist/core/estructural/buscar.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Búsqueda por FORMA sintáctica, no por texto.
+ *
+ * `grep "function foo"` encuentra la declaración, el comentario que la
+ * menciona y la cadena que la nombra en un mensaje de error: para `grep`, las
+ * tres líneas son iguales, texto que casa con el patrón. Esto camina el AST
+ * real de TypeScript, así que un comentario (trivia, no nodo) o una cadena
+ * (`StringLiteral`, un tipo de nodo que ninguno de nuestros patrones pide)
+ * nunca pueden colar como si fueran la declaración.
+ *
+ * Mismo compilador que ya usa `edicion/parseo.ts`: sin dependencias nuevas, y
+ * ya sabemos que acierta en sintaxis (no en tipos, que es justo lo que no
+ * hace falta para esto). Cubre `.ts/.tsx/.js/.jsx` y sus variantes de módulo;
+ * el resto de lenguajes de programación conocidos se declaran SIN COBERTURA
+ * en vez de callarse y devolver cero resultados, que es indistinguible de "no
+ * hay nada que encontrar" y por eso miente.
+ */
+import ts from "typescript";
+export type TipoPatron = "funcion" | "clase" | "tipo" | "llamada" | "import" | "propiedad";
+export interface Patron {
+    tipo: TipoPatron;
+    nombre: string;
+}
+/**
+ * `null` = el patrón no tiene la forma `tipo:nombre` que entendemos.
+ *
+ * Se corta en el PRIMER `:` a propósito: `import:node:fs` tiene que dejar
+ * `nombre = "node:fs"` intacto, con su propio `:` de módulo interno de Node.
+ */
+export declare function parsearPatron(cadena: string): Patron | null;
+export declare function extensionCubierta(ruta: string): boolean;
+export declare function esOtroLenguajeConocido(ruta: string): boolean;
+/**
+ * Todos los ficheros bajo `raiz` (o `[raiz]` si ya es un fichero).
+ *
+ * Sin `fd` ni glob: un recorrido a mano basta para lo que pide esta tool, y
+ * evita depender de un binario externo para algo que `readdirSync` ya resuelve.
+ * Se saltan los directorios ocultos y los de artefactos de build, igual que
+ * haría cualquier búsqueda de código real.
+ */
+export declare function listarFicheros(raiz: string): string[];
+/** Todos los nodos de `fuente` que coinciden con `patron`, en orden de aparición. */
+export declare function nodosCoincidentes(fuente: ts.SourceFile, patron: Patron): ts.Node[];
+export interface Coincidencia {
+    ruta: string;
+    linea: number;
+    fragmento: string;
+}
+export interface ResultadoBusquedaEstructural {
+    coincidencias: Coincidencia[];
+    /** Ficheros de código en un lenguaje que este buscador no sabe leer. Nunca se disfraza de "sin resultados". */
+    noCubiertos: string[];
+}
+/**
+ * `null` = el patrón no se entendió (fallo de lectura, no "no hay nada").
+ *
+ * `raices` son rutas absolutas (ficheros o directorios); `cwd` solo se usa
+ * para dejar las rutas del resultado relativas y legibles.
+ */
+export declare function buscarEstructural(patronCadena: string, raices: string[], cwd: string): ResultadoBusquedaEstructural | null;
+//# sourceMappingURL=buscar.d.ts.map

package/dist/core/estructural/buscar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buscar.d.ts","sourceRoot":"","sources":["../../../src/core/estructural/buscar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAsB3F,MAAM,WAAW,MAAM;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO3D;AAqDD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgCrD;AAkDD,sFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,EAAE,CAAC,IAAI,EAAE,CAQlF;AAQD,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC5C,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,gHAA+G;IAC/G,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,EAAE,MAAM,GACT,4BAA4B,GAAG,IAAI,CA2BrC","sourcesContent":["/**\n * Búsqueda por FORMA sintáctica, no por texto.\n *\n * `grep \"function foo\"` encuentra la declaración, el comentario que la\n * menciona y la cadena que la nombra en un mensaje de error: para `grep`, las\n * tres líneas son iguales, texto que casa con el patrón. Esto camina el AST\n * real de TypeScript, así que un comentario (trivia, no nodo) o una cadena\n * (`StringLiteral`, un tipo de nodo que ninguno de nuestros patrones pide)\n * nunca pueden colar como si fueran la declaración.\n *\n * Mismo compilador que ya usa `edicion/parseo.ts`: sin dependencias nuevas, y\n * ya sabemos que acierta en sintaxis (no en tipos, que es justo lo que no\n * hace falta para esto). Cubre `.ts/.tsx/.js/.jsx` y sus variantes de módulo;\n * el resto de lenguajes de programación conocidos se declaran SIN COBERTURA\n * en vez de callarse y devolver cero resultados, que es indistinguible de \"no\n * hay nada que encontrar\" y por eso miente.\n */\n\nimport { readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { join, relative } from \"node:path\";\nimport ts from \"typescript\";\n\nexport type TipoPatron = \"funcion\" | \"clase\" | \"tipo\" | \"llamada\" | \"import\" | \"propiedad\";\n\n/** Alias en español e inglés para el mismo tipo de patrón. */\nconst ALIAS_TIPO: Record<string, TipoPatron> = {\n\tfuncion: \"funcion\",\n\tfunction: \"funcion\",\n\tfunc: \"funcion\",\n\tclase: \"clase\",\n\tclass: \"clase\",\n\ttipo: \"tipo\",\n\ttype: \"tipo\",\n\tinterfaz: \"tipo\",\n\tinterface: \"tipo\",\n\tllamada: \"llamada\",\n\tcall: \"llamada\",\n\timport: \"import\",\n\timportacion: \"import\",\n\tpropiedad: \"propiedad\",\n\tproperty: \"propiedad\",\n\tprop: \"propiedad\",\n};\n\nexport interface Patron {\n\ttipo: TipoPatron;\n\tnombre: string;\n}\n\n/**\n * `null` = el patrón no tiene la forma `tipo:nombre` que entendemos.\n *\n * Se corta en el PRIMER `:` a propósito: `import:node:fs` tiene que dejar\n * `nombre = \"node:fs\"` intacto, con su propio `:` de módulo interno de Node.\n */\nexport function parsearPatron(cadena: string): Patron | null {\n\tconst separador = cadena.indexOf(\":\");\n\tif (separador === -1) return null;\n\tconst tipo = ALIAS_TIPO[cadena.slice(0, separador).trim().toLowerCase()];\n\tconst nombre = cadena.slice(separador + 1).trim();\n\tif (!tipo || nombre === \"\") return null;\n\treturn { tipo, nombre };\n}\n\n/** Lo que este buscador sabe LEER de verdad (parsea con el compilador de TS). */\nconst EXTENSIONES_CUBIERTAS = new Set([\".ts\", \".tsx\", \".js\", \".jsx\", \".mts\", \".cts\", \".mjs\", \".cjs\"]);\n\n/**\n * Lenguajes de programación que reconocemos pero que este buscador NO sabe\n * leer. Un `.py`, un `.go`, un componente `.vue`... tienen que salir como \"sin\n * cobertura\", no como \"cero coincidencias\": lo segundo es indistinguible de\n * haber buscado de verdad y no encontrar nada.\n *\n * Los ficheros que no son código en absoluto (`.json`, `.md`, imágenes...) no\n * entran aquí: nunca pretendimos cubrirlos, así que no hay nada que avisar.\n */\nconst EXTENSIONES_OTRO_LENGUAJE = new Set([\n\t\".py\",\n\t\".go\",\n\t\".rs\",\n\t\".java\",\n\t\".rb\",\n\t\".php\",\n\t\".c\",\n\t\".h\",\n\t\".cpp\",\n\t\".hpp\",\n\t\".cc\",\n\t\".cs\",\n\t\".swift\",\n\t\".kt\",\n\t\".kts\",\n\t\".scala\",\n\t\".sh\",\n\t\".bash\",\n\t\".zsh\",\n\t\".lua\",\n\t\".pl\",\n\t\".ex\",\n\t\".exs\",\n\t\".erl\",\n\t\".hs\",\n\t\".clj\",\n\t\".dart\",\n\t\".m\",\n\t\".mm\",\n\t\".vue\",\n\t\".svelte\",\n]);\n\nfunction extensionDe(ruta: string): string {\n\tconst punto = ruta.lastIndexOf(\".\");\n\treturn punto === -1 ? \"\" : ruta.slice(punto).toLowerCase();\n}\n\nexport function extensionCubierta(ruta: string): boolean {\n\treturn EXTENSIONES_CUBIERTAS.has(extensionDe(ruta));\n}\n\nexport function esOtroLenguajeConocido(ruta: string): boolean {\n\treturn EXTENSIONES_OTRO_LENGUAJE.has(extensionDe(ruta));\n}\n\nconst DIRS_IGNORADOS = new Set([\"node_modules\", \"dist\", \"build\", \"out\", \"coverage\", \".next\", \".turbo\", \".cache\"]);\n\n/**\n * Todos los ficheros bajo `raiz` (o `[raiz]` si ya es un fichero).\n *\n * Sin `fd` ni glob: un recorrido a mano basta para lo que pide esta tool, y\n * evita depender de un binario externo para algo que `readdirSync` ya resuelve.\n * Se saltan los directorios ocultos y los de artefactos de build, igual que\n * haría cualquier búsqueda de código real.\n */\nexport function listarFicheros(raiz: string): string[] {\n\tlet info: ReturnType<typeof statSync>;\n\ttry {\n\t\tinfo = statSync(raiz);\n\t} catch {\n\t\treturn [];\n\t}\n\tif (info.isFile()) return [raiz];\n\tif (!info.isDirectory()) return [];\n\n\tconst resultado: string[] = [];\n\tconst pila = [raiz];\n\twhile (pila.length > 0) {\n\t\tconst dir = pila.pop() as string;\n\t\tlet entradas: import(\"node:fs\").Dirent[];\n\t\ttry {\n\t\t\tentradas = readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const entrada of entradas) {\n\t\t\tif (entrada.name.startsWith(\".\")) continue; // .git, .cache, etc.\n\t\t\tconst ruta = join(dir, entrada.name);\n\t\t\tif (entrada.isSymbolicLink()) continue; // evita ciclos por symlink\n\t\t\tif (entrada.isDirectory()) {\n\t\t\t\tif (!DIRS_IGNORADOS.has(entrada.name)) pila.push(ruta);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (entrada.isFile()) resultado.push(ruta);\n\t\t}\n\t}\n\treturn resultado;\n}\n\nfunction nombreDeCallee(expr: ts.Expression): string | null {\n\tif (ts.isIdentifier(expr)) return expr.text;\n\tif (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) return expr.name.text;\n\treturn null;\n}\n\nfunction nombreDePropiedad(nombre: ts.PropertyName): string | null {\n\tif (ts.isIdentifier(nombre) || ts.isPrivateIdentifier(nombre)) return nombre.text;\n\tif (ts.isStringLiteral(nombre)) return nombre.text;\n\treturn null;\n}\n\n/** ¿Este nodo del AST es la declaración/uso que pide el patrón? */\nfunction coincideNodo(nodo: ts.Node, patron: Patron): boolean {\n\tswitch (patron.tipo) {\n\t\tcase \"funcion\":\n\t\t\tif (ts.isFunctionDeclaration(nodo)) return nodo.name?.text === patron.nombre;\n\t\t\tif (ts.isVariableDeclaration(nodo) && ts.isIdentifier(nodo.name) && nodo.initializer) {\n\t\t\t\treturn (\n\t\t\t\t\tnodo.name.text === patron.nombre &&\n\t\t\t\t\t(ts.isArrowFunction(nodo.initializer) || ts.isFunctionExpression(nodo.initializer))\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (ts.isMethodDeclaration(nodo)) return nombreDePropiedad(nodo.name) === patron.nombre;\n\t\t\treturn false;\n\t\tcase \"clase\":\n\t\t\treturn ts.isClassDeclaration(nodo) && nodo.name?.text === patron.nombre;\n\t\tcase \"tipo\":\n\t\t\tif (ts.isTypeAliasDeclaration(nodo)) return nodo.name.text === patron.nombre;\n\t\t\tif (ts.isInterfaceDeclaration(nodo)) return nodo.name.text === patron.nombre;\n\t\t\treturn false;\n\t\tcase \"llamada\":\n\t\t\treturn ts.isCallExpression(nodo) && nombreDeCallee(nodo.expression) === patron.nombre;\n\t\tcase \"import\":\n\t\t\treturn (\n\t\t\t\tts.isImportDeclaration(nodo) &&\n\t\t\t\tts.isStringLiteral(nodo.moduleSpecifier) &&\n\t\t\t\tnodo.moduleSpecifier.text === patron.nombre\n\t\t\t);\n\t\tcase \"propiedad\":\n\t\t\tif (ts.isPropertyAssignment(nodo) || ts.isPropertySignature(nodo) || ts.isPropertyDeclaration(nodo)) {\n\t\t\t\treturn nombreDePropiedad(nodo.name) === patron.nombre;\n\t\t\t}\n\t\t\tif (ts.isShorthandPropertyAssignment(nodo)) return nodo.name.text === patron.nombre;\n\t\t\treturn false;\n\t}\n}\n\n/** Todos los nodos de `fuente` que coinciden con `patron`, en orden de aparición. */\nexport function nodosCoincidentes(fuente: ts.SourceFile, patron: Patron): ts.Node[] {\n\tconst resultado: ts.Node[] = [];\n\tconst visitar = (nodo: ts.Node): void => {\n\t\tif (coincideNodo(nodo, patron)) resultado.push(nodo);\n\t\tts.forEachChild(nodo, visitar);\n\t};\n\tvisitar(fuente);\n\treturn resultado;\n}\n\nfunction lineaYFragmento(fuente: ts.SourceFile, posicion: number): { linea: number; fragmento: string } {\n\tconst { line } = fuente.getLineAndCharacterOfPosition(posicion);\n\tconst texto = fuente.text.split(\"\\n\")[line] ?? \"\";\n\treturn { linea: line + 1, fragmento: texto.trim().slice(0, 200) };\n}\n\nexport interface Coincidencia {\n\truta: string;\n\tlinea: number;\n\tfragmento: string;\n}\n\nexport interface ResultadoBusquedaEstructural {\n\tcoincidencias: Coincidencia[];\n\t/** Ficheros de código en un lenguaje que este buscador no sabe leer. Nunca se disfraza de \"sin resultados\". */\n\tnoCubiertos: string[];\n}\n\n/**\n * `null` = el patrón no se entendió (fallo de lectura, no \"no hay nada\").\n *\n * `raices` son rutas absolutas (ficheros o directorios); `cwd` solo se usa\n * para dejar las rutas del resultado relativas y legibles.\n */\nexport function buscarEstructural(\n\tpatronCadena: string,\n\traices: string[],\n\tcwd: string,\n): ResultadoBusquedaEstructural | null {\n\tconst patron = parsearPatron(patronCadena);\n\tif (!patron) return null;\n\n\tconst coincidencias: Coincidencia[] = [];\n\tconst noCubiertos = new Set<string>();\n\tfor (const raiz of raices) {\n\t\tfor (const ruta of listarFicheros(raiz)) {\n\t\t\tconst relativa = relative(cwd, ruta) || ruta;\n\t\t\tif (esOtroLenguajeConocido(ruta)) {\n\t\t\t\tnoCubiertos.add(relativa);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!extensionCubierta(ruta)) continue; // no es código: ni cobertura ni aviso\n\t\t\tlet codigo: string;\n\t\t\ttry {\n\t\t\t\tcodigo = readFileSync(ruta, \"utf-8\");\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst fuente = ts.createSourceFile(ruta, codigo, ts.ScriptTarget.Latest, false);\n\t\t\tfor (const nodo of nodosCoincidentes(fuente, patron)) {\n\t\t\t\tcoincidencias.push({ ruta: relativa, ...lineaYFragmento(fuente, nodo.getStart(fuente)) });\n\t\t\t}\n\t\t}\n\t}\n\treturn { coincidencias, noCubiertos: [...noCubiertos].sort() };\n}\n"]}