@hoilab/ada-cli 0.84.21 → 0.85.0

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"]}

package/dist/core/estructural/buscar.js

@@ -0,0 +1,261 @@
+/**
+ * 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 { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+/** Alias en español e inglés para el mismo tipo de patrón. */
+const ALIAS_TIPO = {
+    funcion: "funcion",
+    function: "funcion",
+    func: "funcion",
+    clase: "clase",
+    class: "clase",
+    tipo: "tipo",
+    type: "tipo",
+    interfaz: "tipo",
+    interface: "tipo",
+    llamada: "llamada",
+    call: "llamada",
+    import: "import",
+    importacion: "import",
+    propiedad: "propiedad",
+    property: "propiedad",
+    prop: "propiedad",
+};
+/**
+ * `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 function parsearPatron(cadena) {
+    const separador = cadena.indexOf(":");
+    if (separador === -1)
+        return null;
+    const tipo = ALIAS_TIPO[cadena.slice(0, separador).trim().toLowerCase()];
+    const nombre = cadena.slice(separador + 1).trim();
+    if (!tipo || nombre === "")
+        return null;
+    return { tipo, nombre };
+}
+/** Lo que este buscador sabe LEER de verdad (parsea con el compilador de TS). */
+const EXTENSIONES_CUBIERTAS = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"]);
+/**
+ * Lenguajes de programación que reconocemos pero que este buscador NO sabe
+ * leer. Un `.py`, un `.go`, un componente `.vue`... tienen que salir como "sin
+ * cobertura", no como "cero coincidencias": lo segundo es indistinguible de
+ * haber buscado de verdad y no encontrar nada.
+ *
+ * Los ficheros que no son código en absoluto (`.json`, `.md`, imágenes...) no
+ * entran aquí: nunca pretendimos cubrirlos, así que no hay nada que avisar.
+ */
+const EXTENSIONES_OTRO_LENGUAJE = new Set([
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".rb",
+    ".php",
+    ".c",
+    ".h",
+    ".cpp",
+    ".hpp",
+    ".cc",
+    ".cs",
+    ".swift",
+    ".kt",
+    ".kts",
+    ".scala",
+    ".sh",
+    ".bash",
+    ".zsh",
+    ".lua",
+    ".pl",
+    ".ex",
+    ".exs",
+    ".erl",
+    ".hs",
+    ".clj",
+    ".dart",
+    ".m",
+    ".mm",
+    ".vue",
+    ".svelte",
+]);
+function extensionDe(ruta) {
+    const punto = ruta.lastIndexOf(".");
+    return punto === -1 ? "" : ruta.slice(punto).toLowerCase();
+}
+export function extensionCubierta(ruta) {
+    return EXTENSIONES_CUBIERTAS.has(extensionDe(ruta));
+}
+export function esOtroLenguajeConocido(ruta) {
+    return EXTENSIONES_OTRO_LENGUAJE.has(extensionDe(ruta));
+}
+const DIRS_IGNORADOS = new Set(["node_modules", "dist", "build", "out", "coverage", ".next", ".turbo", ".cache"]);
+/**
+ * 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 function listarFicheros(raiz) {
+    let info;
+    try {
+        info = statSync(raiz);
+    }
+    catch {
+        return [];
+    }
+    if (info.isFile())
+        return [raiz];
+    if (!info.isDirectory())
+        return [];
+    const resultado = [];
+    const pila = [raiz];
+    while (pila.length > 0) {
+        const dir = pila.pop();
+        let entradas;
+        try {
+            entradas = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entrada of entradas) {
+            if (entrada.name.startsWith("."))
+                continue; // .git, .cache, etc.
+            const ruta = join(dir, entrada.name);
+            if (entrada.isSymbolicLink())
+                continue; // evita ciclos por symlink
+            if (entrada.isDirectory()) {
+                if (!DIRS_IGNORADOS.has(entrada.name))
+                    pila.push(ruta);
+                continue;
+            }
+            if (entrada.isFile())
+                resultado.push(ruta);
+        }
+    }
+    return resultado;
+}
+function nombreDeCallee(expr) {
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name))
+        return expr.name.text;
+    return null;
+}
+function nombreDePropiedad(nombre) {
+    if (ts.isIdentifier(nombre) || ts.isPrivateIdentifier(nombre))
+        return nombre.text;
+    if (ts.isStringLiteral(nombre))
+        return nombre.text;
+    return null;
+}
+/** ¿Este nodo del AST es la declaración/uso que pide el patrón? */
+function coincideNodo(nodo, patron) {
+    switch (patron.tipo) {
+        case "funcion":
+            if (ts.isFunctionDeclaration(nodo))
+                return nodo.name?.text === patron.nombre;
+            if (ts.isVariableDeclaration(nodo) && ts.isIdentifier(nodo.name) && nodo.initializer) {
+                return (nodo.name.text === patron.nombre &&
+                    (ts.isArrowFunction(nodo.initializer) || ts.isFunctionExpression(nodo.initializer)));
+            }
+            if (ts.isMethodDeclaration(nodo))
+                return nombreDePropiedad(nodo.name) === patron.nombre;
+            return false;
+        case "clase":
+            return ts.isClassDeclaration(nodo) && nodo.name?.text === patron.nombre;
+        case "tipo":
+            if (ts.isTypeAliasDeclaration(nodo))
+                return nodo.name.text === patron.nombre;
+            if (ts.isInterfaceDeclaration(nodo))
+                return nodo.name.text === patron.nombre;
+            return false;
+        case "llamada":
+            return ts.isCallExpression(nodo) && nombreDeCallee(nodo.expression) === patron.nombre;
+        case "import":
+            return (ts.isImportDeclaration(nodo) &&
+                ts.isStringLiteral(nodo.moduleSpecifier) &&
+                nodo.moduleSpecifier.text === patron.nombre);
+        case "propiedad":
+            if (ts.isPropertyAssignment(nodo) || ts.isPropertySignature(nodo) || ts.isPropertyDeclaration(nodo)) {
+                return nombreDePropiedad(nodo.name) === patron.nombre;
+            }
+            if (ts.isShorthandPropertyAssignment(nodo))
+                return nodo.name.text === patron.nombre;
+            return false;
+    }
+}
+/** Todos los nodos de `fuente` que coinciden con `patron`, en orden de aparición. */
+export function nodosCoincidentes(fuente, patron) {
+    const resultado = [];
+    const visitar = (nodo) => {
+        if (coincideNodo(nodo, patron))
+            resultado.push(nodo);
+        ts.forEachChild(nodo, visitar);
+    };
+    visitar(fuente);
+    return resultado;
+}
+function lineaYFragmento(fuente, posicion) {
+    const { line } = fuente.getLineAndCharacterOfPosition(posicion);
+    const texto = fuente.text.split("\n")[line] ?? "";
+    return { linea: line + 1, fragmento: texto.trim().slice(0, 200) };
+}
+/**
+ * `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 function buscarEstructural(patronCadena, raices, cwd) {
+    const patron = parsearPatron(patronCadena);
+    if (!patron)
+        return null;
+    const coincidencias = [];
+    const noCubiertos = new Set();
+    for (const raiz of raices) {
+        for (const ruta of listarFicheros(raiz)) {
+            const relativa = relative(cwd, ruta) || ruta;
+            if (esOtroLenguajeConocido(ruta)) {
+                noCubiertos.add(relativa);
+                continue;
+            }
+            if (!extensionCubierta(ruta))
+                continue; // no es código: ni cobertura ni aviso
+            let codigo;
+            try {
+                codigo = readFileSync(ruta, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const fuente = ts.createSourceFile(ruta, codigo, ts.ScriptTarget.Latest, false);
+            for (const nodo of nodosCoincidentes(fuente, patron)) {
+                coincidencias.push({ ruta: relativa, ...lineaYFragmento(fuente, nodo.getStart(fuente)) });
+            }
+        }
+    }
+    return { coincidencias, noCubiertos: [...noCubiertos].sort() };
+}
+//# sourceMappingURL=buscar.js.map

package/dist/core/estructural/buscar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buscar.js","sourceRoot":"","sources":["../../../src/core/estructural/buscar.ts"],"names":[],"mappings":"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","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"]}

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

@@ -0,0 +1,36 @@
+/**
+ * Edición por FORMA sintáctica: sustituye el nodo que coincide, no el texto
+ * que se le parece.
+ *
+ * La otra cara del mismo problema que `buscar.ts`: un `sed`/reemplazo de
+ * cadenas que renombra `foo` también renombra la cadena `"llama a foo()"` y el
+ * comentario `// foo hace el cálculo`, porque para texto plano las tres cosas
+ * son la misma palabra. Aquí se sustituye el NODO — el rango exacto que ocupa
+ * la declaración, la llamada o el import en el AST — así que lo que no es ese
+ * nodo no se toca, sea lo que sea que diga.
+ *
+ * Reindenta las líneas del reemplazo que no sean la primera con la
+ * indentación de la línea del sitio: sin esto, sustituir una declaración
+ * multilínea deja el cuerpo pegado al margen izquierdo.
+ */
+export interface CambioEstructural {
+    ruta: string;
+    linea: number;
+    antes: string;
+    despues: string;
+}
+export interface ResultadoEdicionEstructural {
+    cambios: CambioEstructural[];
+    /** Ficheros de código en un lenguaje que no sabemos editar. Igual que en la búsqueda: nunca se disfraza de "nada que cambiar". */
+    noCubiertos: string[];
+    /** Rutas cuya edición dejó de parsear (antes sí, después no). Se aplica igual, como `edit`/`write`: se avisa, no se bloquea en silencio. */
+    rompieronParseo: string[];
+}
+/**
+ * `null` = el patrón no se entendió. `aplicar: false` calcula los cambios sin
+ * tocar disco; `aplicar: true` escribe cada fichero que cambió.
+ */
+export declare function editarEstructural(patronCadena: string, out: string, raices: string[], cwd: string, opciones: {
+    aplicar: boolean;
+}): ResultadoEdicionEstructural | null;
+//# sourceMappingURL=editar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"editar.d.ts","sourceRoot":"","sources":["../../../src/core/estructural/editar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC3C,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,oIAAkI;IAClI,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gJAA4I;IAC5I,eAAe,EAAE,MAAM,EAAE,CAAC;CAC1B;AAmED;;;GAGG;AACH,wBAAgB,iBAAiB,CAChC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAC5B,2BAA2B,GAAG,IAAI,CAoCpC","sourcesContent":["/**\n * Edición por FORMA sintáctica: sustituye el nodo que coincide, no el texto\n * que se le parece.\n *\n * La otra cara del mismo problema que `buscar.ts`: un `sed`/reemplazo de\n * cadenas que renombra `foo` también renombra la cadena `\"llama a foo()\"` y el\n * comentario `// foo hace el cálculo`, porque para texto plano las tres cosas\n * son la misma palabra. Aquí se sustituye el NODO — el rango exacto que ocupa\n * la declaración, la llamada o el import en el AST — así que lo que no es ese\n * nodo no se toca, sea lo que sea que diga.\n *\n * Reindenta las líneas del reemplazo que no sean la primera con la\n * indentación de la línea del sitio: sin esto, sustituir una declaración\n * multilínea deja el cuerpo pegado al margen izquierdo.\n */\n\nimport { readFileSync, writeFileSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport ts from \"typescript\";\nimport { parsea } from \"../edicion/parseo.ts\";\nimport {\n\tesOtroLenguajeConocido,\n\textensionCubierta,\n\tlistarFicheros,\n\tnodosCoincidentes,\n\ttype Patron,\n\tparsearPatron,\n} from \"./buscar.ts\";\n\nexport interface CambioEstructural {\n\truta: string;\n\tlinea: number;\n\tantes: string;\n\tdespues: string;\n}\n\nexport interface ResultadoEdicionEstructural {\n\tcambios: CambioEstructural[];\n\t/** Ficheros de código en un lenguaje que no sabemos editar. Igual que en la búsqueda: nunca se disfraza de \"nada que cambiar\". */\n\tnoCubiertos: string[];\n\t/** Rutas cuya edición dejó de parsear (antes sí, después no). Se aplica igual, como `edit`/`write`: se avisa, no se bloquea en silencio. */\n\trompieronParseo: string[];\n}\n\n/** La indentación (espacios/tabs) con la que empieza la línea que contiene `posicion`. */\nfunction indentacionDeLinea(fuente: ts.SourceFile, posicion: number): string {\n\tconst { line } = fuente.getLineAndCharacterOfPosition(posicion);\n\tconst texto = fuente.text.split(\"\\n\")[line] ?? \"\";\n\treturn texto.match(/^[ \\t]*/)?.[0] ?? \"\";\n}\n\n/** Las líneas 2+ del reemplazo, alineadas con la indentación del sitio donde entra. */\nfunction reindentar(texto: string, indentacion: string): string {\n\treturn texto\n\t\t.split(\"\\n\")\n\t\t.map((l, i) => (i === 0 ? l : indentacion + l))\n\t\t.join(\"\\n\");\n}\n\n/**\n * Descarta los nodos coincidentes que caen DENTRO del rango de otro nodo\n * coincidente (mismo patrón anidado en sí mismo: `{ id: { id: 1 } }` para\n * `propiedad:id`, `foo(foo(1))` para `llamada:foo`, una función sombreada\n * dentro de otra con el mismo nombre para `funcion:foo`...).\n *\n * Sin esto, sustituir el de fuera desplaza el texto y dos rangos que se\n * solapan se aplican con offsets que ya no encajan: cortan por mitad de un\n * literal y dejan basura sintáctica — a veces detectada por `parsea()`\n * después del hecho, a veces no (si por casualidad el resultado seguía\n * siendo JS válido, aunque mutilado). El nodo de dentro de todos modos\n * desaparece cuando se sustituye el de fuera, así que editarlo aparte no\n * tiene sentido: solo sobreviven los nodos que no están contenidos en\n * ningún otro nodo coincidente.\n */\nfunction sinAnidados(nodos: ts.Node[], fuente: ts.SourceFile): ts.Node[] {\n\treturn nodos.filter((nodo) => {\n\t\tconst inicio = nodo.getStart(fuente);\n\t\tconst fin = nodo.getEnd();\n\t\treturn !nodos.some((otro) => otro !== nodo && otro.getStart(fuente) <= inicio && otro.getEnd() >= fin);\n\t});\n}\n\n/** Sustituye en un fichero ya parseado todos los nodos que coinciden. `null` si ninguno coincidió. */\nfunction reescribirFuente(\n\tfuente: ts.SourceFile,\n\tpatron: Patron,\n\tout: string,\n): { contenido: string; cambios: Array<{ linea: number; antes: string; despues: string }> } | null {\n\tconst nodos = sinAnidados(nodosCoincidentes(fuente, patron), fuente);\n\tif (nodos.length === 0) return null;\n\n\t// De atrás hacia adelante: sustituir un nodo de más adelante en el fichero no\n\t// desplaza la posición de los que quedan por delante en el texto.\n\tconst ordenados = [...nodos].sort((a, b) => b.getStart(fuente) - a.getStart(fuente));\n\tlet contenido = fuente.text;\n\tconst cambios: Array<{ linea: number; antes: string; despues: string }> = [];\n\tfor (const nodo of ordenados) {\n\t\tconst inicio = nodo.getStart(fuente);\n\t\tconst fin = nodo.getEnd();\n\t\tconst antes = contenido.slice(inicio, fin);\n\t\tconst despues = reindentar(out, indentacionDeLinea(fuente, inicio));\n\t\tcontenido = contenido.slice(0, inicio) + despues + contenido.slice(fin);\n\t\tconst { line } = fuente.getLineAndCharacterOfPosition(inicio);\n\t\tcambios.push({ linea: line + 1, antes, despues });\n\t}\n\tcambios.reverse(); // en orden de aparición en el fichero, no en orden de sustitución\n\treturn { contenido, cambios };\n}\n\n/**\n * `null` = el patrón no se entendió. `aplicar: false` calcula los cambios sin\n * tocar disco; `aplicar: true` escribe cada fichero que cambió.\n */\nexport function editarEstructural(\n\tpatronCadena: string,\n\tout: string,\n\traices: string[],\n\tcwd: string,\n\topciones: { aplicar: boolean },\n): ResultadoEdicionEstructural | null {\n\tconst patron = parsearPatron(patronCadena);\n\tif (!patron) return null;\n\n\tconst cambios: CambioEstructural[] = [];\n\tconst noCubiertos = new Set<string>();\n\tconst rompieronParseo: 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;\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\tconst resultado = reescribirFuente(fuente, patron, out);\n\t\t\tif (!resultado) continue;\n\t\t\tfor (const c of resultado.cambios) cambios.push({ ruta: relativa, ...c });\n\n\t\t\t// Avisar, no bloquear: es la misma regla que ya sigue `edit`/`write` vía\n\t\t\t// `ObservadorDeEdiciones`, y esta tool no pasa por ahí porque toca varios\n\t\t\t// ficheros con un `path` que es un ámbito, no la ruta de un solo fichero.\n\t\t\tif (parsea(codigo, ruta) === true && parsea(resultado.contenido, ruta) === false) {\n\t\t\t\trompieronParseo.push(relativa);\n\t\t\t}\n\t\t\tif (opciones.aplicar) writeFileSync(ruta, resultado.contenido, \"utf-8\");\n\t\t}\n\t}\n\treturn { cambios, noCubiertos: [...noCubiertos].sort(), rompieronParseo };\n}\n"]}

package/dist/core/estructural/editar.js

@@ -0,0 +1,123 @@
+/**
+ * Edición por FORMA sintáctica: sustituye el nodo que coincide, no el texto
+ * que se le parece.
+ *
+ * La otra cara del mismo problema que `buscar.ts`: un `sed`/reemplazo de
+ * cadenas que renombra `foo` también renombra la cadena `"llama a foo()"` y el
+ * comentario `// foo hace el cálculo`, porque para texto plano las tres cosas
+ * son la misma palabra. Aquí se sustituye el NODO — el rango exacto que ocupa
+ * la declaración, la llamada o el import en el AST — así que lo que no es ese
+ * nodo no se toca, sea lo que sea que diga.
+ *
+ * Reindenta las líneas del reemplazo que no sean la primera con la
+ * indentación de la línea del sitio: sin esto, sustituir una declaración
+ * multilínea deja el cuerpo pegado al margen izquierdo.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+import ts from "typescript";
+import { parsea } from "../edicion/parseo.js";
+import { esOtroLenguajeConocido, extensionCubierta, listarFicheros, nodosCoincidentes, parsearPatron, } from "./buscar.js";
+/** La indentación (espacios/tabs) con la que empieza la línea que contiene `posicion`. */
+function indentacionDeLinea(fuente, posicion) {
+    const { line } = fuente.getLineAndCharacterOfPosition(posicion);
+    const texto = fuente.text.split("\n")[line] ?? "";
+    return texto.match(/^[ \t]*/)?.[0] ?? "";
+}
+/** Las líneas 2+ del reemplazo, alineadas con la indentación del sitio donde entra. */
+function reindentar(texto, indentacion) {
+    return texto
+        .split("\n")
+        .map((l, i) => (i === 0 ? l : indentacion + l))
+        .join("\n");
+}
+/**
+ * Descarta los nodos coincidentes que caen DENTRO del rango de otro nodo
+ * coincidente (mismo patrón anidado en sí mismo: `{ id: { id: 1 } }` para
+ * `propiedad:id`, `foo(foo(1))` para `llamada:foo`, una función sombreada
+ * dentro de otra con el mismo nombre para `funcion:foo`...).
+ *
+ * Sin esto, sustituir el de fuera desplaza el texto y dos rangos que se
+ * solapan se aplican con offsets que ya no encajan: cortan por mitad de un
+ * literal y dejan basura sintáctica — a veces detectada por `parsea()`
+ * después del hecho, a veces no (si por casualidad el resultado seguía
+ * siendo JS válido, aunque mutilado). El nodo de dentro de todos modos
+ * desaparece cuando se sustituye el de fuera, así que editarlo aparte no
+ * tiene sentido: solo sobreviven los nodos que no están contenidos en
+ * ningún otro nodo coincidente.
+ */
+function sinAnidados(nodos, fuente) {
+    return nodos.filter((nodo) => {
+        const inicio = nodo.getStart(fuente);
+        const fin = nodo.getEnd();
+        return !nodos.some((otro) => otro !== nodo && otro.getStart(fuente) <= inicio && otro.getEnd() >= fin);
+    });
+}
+/** Sustituye en un fichero ya parseado todos los nodos que coinciden. `null` si ninguno coincidió. */
+function reescribirFuente(fuente, patron, out) {
+    const nodos = sinAnidados(nodosCoincidentes(fuente, patron), fuente);
+    if (nodos.length === 0)
+        return null;
+    // De atrás hacia adelante: sustituir un nodo de más adelante en el fichero no
+    // desplaza la posición de los que quedan por delante en el texto.
+    const ordenados = [...nodos].sort((a, b) => b.getStart(fuente) - a.getStart(fuente));
+    let contenido = fuente.text;
+    const cambios = [];
+    for (const nodo of ordenados) {
+        const inicio = nodo.getStart(fuente);
+        const fin = nodo.getEnd();
+        const antes = contenido.slice(inicio, fin);
+        const despues = reindentar(out, indentacionDeLinea(fuente, inicio));
+        contenido = contenido.slice(0, inicio) + despues + contenido.slice(fin);
+        const { line } = fuente.getLineAndCharacterOfPosition(inicio);
+        cambios.push({ linea: line + 1, antes, despues });
+    }
+    cambios.reverse(); // en orden de aparición en el fichero, no en orden de sustitución
+    return { contenido, cambios };
+}
+/**
+ * `null` = el patrón no se entendió. `aplicar: false` calcula los cambios sin
+ * tocar disco; `aplicar: true` escribe cada fichero que cambió.
+ */
+export function editarEstructural(patronCadena, out, raices, cwd, opciones) {
+    const patron = parsearPatron(patronCadena);
+    if (!patron)
+        return null;
+    const cambios = [];
+    const noCubiertos = new Set();
+    const rompieronParseo = [];
+    for (const raiz of raices) {
+        for (const ruta of listarFicheros(raiz)) {
+            const relativa = relative(cwd, ruta) || ruta;
+            if (esOtroLenguajeConocido(ruta)) {
+                noCubiertos.add(relativa);
+                continue;
+            }
+            if (!extensionCubierta(ruta))
+                continue;
+            let codigo;
+            try {
+                codigo = readFileSync(ruta, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const fuente = ts.createSourceFile(ruta, codigo, ts.ScriptTarget.Latest, false);
+            const resultado = reescribirFuente(fuente, patron, out);
+            if (!resultado)
+                continue;
+            for (const c of resultado.cambios)
+                cambios.push({ ruta: relativa, ...c });
+            // Avisar, no bloquear: es la misma regla que ya sigue `edit`/`write` vía
+            // `ObservadorDeEdiciones`, y esta tool no pasa por ahí porque toca varios
+            // ficheros con un `path` que es un ámbito, no la ruta de un solo fichero.
+            if (parsea(codigo, ruta) === true && parsea(resultado.contenido, ruta) === false) {
+                rompieronParseo.push(relativa);
+            }
+            if (opciones.aplicar)
+                writeFileSync(ruta, resultado.contenido, "utf-8");
+        }
+    }
+    return { cambios, noCubiertos: [...noCubiertos].sort(), rompieronParseo };
+}
+//# sourceMappingURL=editar.js.map

package/dist/core/estructural/editar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editar.js","sourceRoot":"","sources":["../../../src/core/estructural/editar.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Edición por FORMA sintáctica: sustituye el nodo que coincide, no el texto\n * que se le parece.\n *\n * La otra cara del mismo problema que `buscar.ts`: un `sed`/reemplazo de\n * cadenas que renombra `foo` también renombra la cadena `\"llama a foo()\"` y el\n * comentario `// foo hace el cálculo`, porque para texto plano las tres cosas\n * son la misma palabra. Aquí se sustituye el NODO — el rango exacto que ocupa\n * la declaración, la llamada o el import en el AST — así que lo que no es ese\n * nodo no se toca, sea lo que sea que diga.\n *\n * Reindenta las líneas del reemplazo que no sean la primera con la\n * indentación de la línea del sitio: sin esto, sustituir una declaración\n * multilínea deja el cuerpo pegado al margen izquierdo.\n */\n\nimport { readFileSync, writeFileSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport ts from \"typescript\";\nimport { parsea } from \"../edicion/parseo.ts\";\nimport {\n\tesOtroLenguajeConocido,\n\textensionCubierta,\n\tlistarFicheros,\n\tnodosCoincidentes,\n\ttype Patron,\n\tparsearPatron,\n} from \"./buscar.ts\";\n\nexport interface CambioEstructural {\n\truta: string;\n\tlinea: number;\n\tantes: string;\n\tdespues: string;\n}\n\nexport interface ResultadoEdicionEstructural {\n\tcambios: CambioEstructural[];\n\t/** Ficheros de código en un lenguaje que no sabemos editar. Igual que en la búsqueda: nunca se disfraza de \"nada que cambiar\". */\n\tnoCubiertos: string[];\n\t/** Rutas cuya edición dejó de parsear (antes sí, después no). Se aplica igual, como `edit`/`write`: se avisa, no se bloquea en silencio. */\n\trompieronParseo: string[];\n}\n\n/** La indentación (espacios/tabs) con la que empieza la línea que contiene `posicion`. */\nfunction indentacionDeLinea(fuente: ts.SourceFile, posicion: number): string {\n\tconst { line } = fuente.getLineAndCharacterOfPosition(posicion);\n\tconst texto = fuente.text.split(\"\\n\")[line] ?? \"\";\n\treturn texto.match(/^[ \\t]*/)?.[0] ?? \"\";\n}\n\n/** Las líneas 2+ del reemplazo, alineadas con la indentación del sitio donde entra. */\nfunction reindentar(texto: string, indentacion: string): string {\n\treturn texto\n\t\t.split(\"\\n\")\n\t\t.map((l, i) => (i === 0 ? l : indentacion + l))\n\t\t.join(\"\\n\");\n}\n\n/**\n * Descarta los nodos coincidentes que caen DENTRO del rango de otro nodo\n * coincidente (mismo patrón anidado en sí mismo: `{ id: { id: 1 } }` para\n * `propiedad:id`, `foo(foo(1))` para `llamada:foo`, una función sombreada\n * dentro de otra con el mismo nombre para `funcion:foo`...).\n *\n * Sin esto, sustituir el de fuera desplaza el texto y dos rangos que se\n * solapan se aplican con offsets que ya no encajan: cortan por mitad de un\n * literal y dejan basura sintáctica — a veces detectada por `parsea()`\n * después del hecho, a veces no (si por casualidad el resultado seguía\n * siendo JS válido, aunque mutilado). El nodo de dentro de todos modos\n * desaparece cuando se sustituye el de fuera, así que editarlo aparte no\n * tiene sentido: solo sobreviven los nodos que no están contenidos en\n * ningún otro nodo coincidente.\n */\nfunction sinAnidados(nodos: ts.Node[], fuente: ts.SourceFile): ts.Node[] {\n\treturn nodos.filter((nodo) => {\n\t\tconst inicio = nodo.getStart(fuente);\n\t\tconst fin = nodo.getEnd();\n\t\treturn !nodos.some((otro) => otro !== nodo && otro.getStart(fuente) <= inicio && otro.getEnd() >= fin);\n\t});\n}\n\n/** Sustituye en un fichero ya parseado todos los nodos que coinciden. `null` si ninguno coincidió. */\nfunction reescribirFuente(\n\tfuente: ts.SourceFile,\n\tpatron: Patron,\n\tout: string,\n): { contenido: string; cambios: Array<{ linea: number; antes: string; despues: string }> } | null {\n\tconst nodos = sinAnidados(nodosCoincidentes(fuente, patron), fuente);\n\tif (nodos.length === 0) return null;\n\n\t// De atrás hacia adelante: sustituir un nodo de más adelante en el fichero no\n\t// desplaza la posición de los que quedan por delante en el texto.\n\tconst ordenados = [...nodos].sort((a, b) => b.getStart(fuente) - a.getStart(fuente));\n\tlet contenido = fuente.text;\n\tconst cambios: Array<{ linea: number; antes: string; despues: string }> = [];\n\tfor (const nodo of ordenados) {\n\t\tconst inicio = nodo.getStart(fuente);\n\t\tconst fin = nodo.getEnd();\n\t\tconst antes = contenido.slice(inicio, fin);\n\t\tconst despues = reindentar(out, indentacionDeLinea(fuente, inicio));\n\t\tcontenido = contenido.slice(0, inicio) + despues + contenido.slice(fin);\n\t\tconst { line } = fuente.getLineAndCharacterOfPosition(inicio);\n\t\tcambios.push({ linea: line + 1, antes, despues });\n\t}\n\tcambios.reverse(); // en orden de aparición en el fichero, no en orden de sustitución\n\treturn { contenido, cambios };\n}\n\n/**\n * `null` = el patrón no se entendió. `aplicar: false` calcula los cambios sin\n * tocar disco; `aplicar: true` escribe cada fichero que cambió.\n */\nexport function editarEstructural(\n\tpatronCadena: string,\n\tout: string,\n\traices: string[],\n\tcwd: string,\n\topciones: { aplicar: boolean },\n): ResultadoEdicionEstructural | null {\n\tconst patron = parsearPatron(patronCadena);\n\tif (!patron) return null;\n\n\tconst cambios: CambioEstructural[] = [];\n\tconst noCubiertos = new Set<string>();\n\tconst rompieronParseo: 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;\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\tconst resultado = reescribirFuente(fuente, patron, out);\n\t\t\tif (!resultado) continue;\n\t\t\tfor (const c of resultado.cambios) cambios.push({ ruta: relativa, ...c });\n\n\t\t\t// Avisar, no bloquear: es la misma regla que ya sigue `edit`/`write` vía\n\t\t\t// `ObservadorDeEdiciones`, y esta tool no pasa por ahí porque toca varios\n\t\t\t// ficheros con un `path` que es un ámbito, no la ruta de un solo fichero.\n\t\t\tif (parsea(codigo, ruta) === true && parsea(resultado.contenido, ruta) === false) {\n\t\t\t\trompieronParseo.push(relativa);\n\t\t\t}\n\t\t\tif (opciones.aplicar) writeFileSync(ruta, resultado.contenido, \"utf-8\");\n\t\t}\n\t}\n\treturn { cambios, noCubiertos: [...noCubiertos].sort(), rompieronParseo };\n}\n"]}

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

@@ -0,0 +1,11 @@
+/**
+ * `ast_search` y `ast_edit`: la búsqueda y la edición estructural, como tools
+ * del agente.
+ *
+ * El renderizado se deja al genérico (`ToolDefinition.renderCall/renderResult`
+ * son opcionales): igual que `crearBrowserTools`, la caja de texto por
+ * defecto ya vale para lo que devuelven estas dos.
+ */
+import type { ToolDefinition } from "../extensions/types.ts";
+export declare function crearEstructuralTools(cwd: string): Record<string, ToolDefinition>;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/core/estructural/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA6G9E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAKjF","sourcesContent":["/**\n * `ast_search` y `ast_edit`: la búsqueda y la edición estructural, como tools\n * del agente.\n *\n * El renderizado se deja al genérico (`ToolDefinition.renderCall/renderResult`\n * son opcionales): igual que `crearBrowserTools`, la caja de texto por\n * defecto ya vale para lo que devuelven estas dos.\n */\n\nimport { Type } from \"typebox\";\nimport type { AgentToolResult, ToolDefinition } from \"../extensions/types.ts\";\nimport { resolveToCwd } from \"../tools/path-utils.ts\";\nimport { buscarEstructural } from \"./buscar.ts\";\nimport { editarEstructural } from \"./editar.ts\";\n\nconst AYUDA_PATRON =\n\t'Patrón estructural \"tipo:nombre\". tipo es uno de: funcion, clase, tipo, llamada, import, propiedad. ' +\n\t'Ejemplos: \"funcion:procesarPedido\", \"clase:Cliente\", \"llamada:fetch\", \"import:react\", \"propiedad:id\".';\n\nfunction rutasDe(pathParam: string | undefined, cwd: string): string[] {\n\tconst crudas = (pathParam ?? \".\")\n\t\t.split(\";\")\n\t\t.map((p) => p.trim())\n\t\t.filter((p) => p.length > 0);\n\treturn (crudas.length > 0 ? crudas : [\".\"]).map((p) => resolveToCwd(p, cwd));\n}\n\nfunction texto(t: string): AgentToolResult<unknown> {\n\treturn { content: [{ type: \"text\" as const, text: t }], details: undefined };\n}\n\nfunction avisoNoCubiertos(noCubiertos: string[]): string {\n\tif (noCubiertos.length === 0) return \"\";\n\treturn `\\n\\nSin cobertura estructural (no es .ts/.tsx/.js/.jsx), no se han mirado: ${noCubiertos.join(\", \")}`;\n}\n\nconst astSearchSchema = Type.Object({\n\tpat: Type.String({ description: AYUDA_PATRON }),\n\tpath: Type.Optional(\n\t\tType.String({ description: 'Fichero o directorio a buscar; varios separados por \";\" (default: \".\")' }),\n\t),\n});\n\nfunction crearAstSearchTool(cwd: string): ToolDefinition<typeof astSearchSchema> {\n\treturn {\n\t\tname: \"ast_search\",\n\t\tlabel: \"Búsqueda estructural\",\n\t\tpromptSnippet:\n\t\t\t\"buscar una declaración/llamada/import por su FORMA en el AST, no por texto (evita comentarios y cadenas)\",\n\t\tdescription:\n\t\t\t\"Busca en código TypeScript/JavaScript por estructura sintáctica, no por texto: encuentra la declaración de una \" +\n\t\t\t\"función/clase/tipo, una llamada, un import o una propiedad SIN que un comentario o una cadena que mencionen el \" +\n\t\t\t`mismo nombre cuenten como coincidencia. ${AYUDA_PATRON} Solo cubre .ts/.tsx/.js/.jsx (y variantes de módulo); ` +\n\t\t\t\"para otros lenguajes de programación lo dice explícitamente en vez de devolver cero resultados.\",\n\t\tparameters: astSearchSchema,\n\t\tasync execute(_toolCallId, { pat, path }): Promise<AgentToolResult<unknown>> {\n\t\t\tconst raices = rutasDe(path, cwd);\n\t\t\tconst resultado = buscarEstructural(pat, raices, cwd);\n\t\t\tif (resultado === null) {\n\t\t\t\tthrow new Error(`No se entiende el patrón \"${pat}\". ${AYUDA_PATRON}`);\n\t\t\t}\n\t\t\tconst { coincidencias, noCubiertos } = resultado;\n\t\t\tconst cuerpo =\n\t\t\t\tcoincidencias.length === 0\n\t\t\t\t\t? \"No hay coincidencias estructurales.\"\n\t\t\t\t\t: coincidencias.map((c) => `${c.ruta}:${c.linea}: ${c.fragmento}`).join(\"\\n\");\n\t\t\treturn texto(cuerpo + avisoNoCubiertos(noCubiertos));\n\t\t},\n\t};\n}\n\nconst astEditSchema = Type.Object({\n\tpat: Type.String({ description: AYUDA_PATRON }),\n\tout: Type.String({\n\t\tdescription:\n\t\t\t\"Texto que sustituye a CADA nodo que coincida, completo (por ejemplo la declaración entera con el nuevo \" +\n\t\t\t\"nombre). Las líneas 2+ se reindentan a la indentación del sitio.\",\n\t}),\n\tpath: Type.Optional(\n\t\tType.String({ description: 'Fichero o directorio a editar; varios separados por \";\" (default: \".\")' }),\n\t),\n});\n\nfunction crearAstEditTool(cwd: string): ToolDefinition<typeof astEditSchema> {\n\treturn {\n\t\tname: \"ast_edit\",\n\t\tlabel: \"Edición estructural\",\n\t\tpromptSnippet:\n\t\t\t\"sustituir una declaración/llamada por su FORMA en el AST, sin tocar cadenas/comentarios que compartan el mismo texto\",\n\t\tdescription:\n\t\t\t\"Reemplaza en código TypeScript/JavaScript el nodo que coincide con un patrón estructural (ver ast_search) \" +\n\t\t\t\"por el texto de `out`, sin tocar cadenas ni comentarios que mencionen el mismo nombre porque no son ese nodo. \" +\n\t\t\t\"Útil para renombrar una declaración con precisión donde un buscar-y-reemplazar de texto rompería otras cosas. \" +\n\t\t\t\"Escribe los ficheros que cambian. Solo cubre .ts/.tsx/.js/.jsx; para otros lenguajes lo dice en vez de fingir que no había nada que cambiar.\",\n\t\tparameters: astEditSchema,\n\t\tasync execute(_toolCallId, { pat, out, path }): Promise<AgentToolResult<unknown>> {\n\t\t\tconst raices = rutasDe(path, cwd);\n\t\t\tconst resultado = editarEstructural(pat, out, raices, cwd, { aplicar: true });\n\t\t\tif (resultado === null) {\n\t\t\t\tthrow new Error(`No se entiende el patrón \"${pat}\". ${AYUDA_PATRON}`);\n\t\t\t}\n\t\t\tconst { cambios, noCubiertos, rompieronParseo } = resultado;\n\t\t\tif (cambios.length === 0) {\n\t\t\t\treturn texto(\n\t\t\t\t\t`No hay coincidencias estructurales; ningún fichero se ha tocado.${avisoNoCubiertos(noCubiertos)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst cuerpo = cambios.map((c) => `${c.ruta}:${c.linea}:\\n- ${c.antes}\\n+ ${c.despues}`).join(\"\\n\\n\");\n\t\t\tconst avisoRoto =\n\t\t\t\trompieronParseo.length > 0\n\t\t\t\t\t? `\\n\\n⚠ Estos ficheros han quedado sintácticamente rotos tras la edición: ${rompieronParseo.join(\", \")}. Arréglalos antes de seguir.`\n\t\t\t\t\t: \"\";\n\t\t\treturn texto(\n\t\t\t\t`${cambios.length} cambio(s) aplicados.\\n\\n${cuerpo}${avisoRoto}${avisoNoCubiertos(noCubiertos)}`,\n\t\t\t);\n\t\t},\n\t};\n}\n\nexport function crearEstructuralTools(cwd: string): Record<string, ToolDefinition> {\n\treturn {\n\t\tast_search: crearAstSearchTool(cwd) as ToolDefinition,\n\t\tast_edit: crearAstEditTool(cwd) as ToolDefinition,\n\t};\n}\n"]}