chocolatito-code 1.0.0 → 1.1.0

package/dist/tools/findFiles.js

@@ -1,6 +1,52 @@
 import fs from "node:fs";
 import path from "node:path";
 import fg from "fast-glob";
+/**
+ * Tope de coincidencias que se recogen del disco. Antes el freno era
+ * `deep: 6`, que recortaba por profundidad y en silencio. Ahora no hay limite
+ * de profundidad, asi que hace falta un tope de resultados para que una
+ * busqueda desde la raiz de un disco no se quede recorriendo millones de
+ * entradas. Este si se avisa en la respuesta.
+ */
+const MAX_COINCIDENCIAS = 1000;
+/** Cuantas se le enseñan al modelo. El resto solo se cuentan. */
+const MAX_MOSTRADAS = 40;
+/** Caracteres que convierten un texto en glob. Si no hay ninguno, es un nombre. */
+const META_GLOB = /[*?[\]{}]/;
+/**
+ * Traduce lo que escribe el modelo al glob que fast-glob necesita.
+ *
+ * Dos trampas, y las dos daban cero resultados sin decir nada:
+ *
+ *  1. En glob, `*.ts` significa ".ts en el nivel raiz", no "en todo el arbol".
+ *     La descripcion de la herramienta pone `'*.tsx'` como ejemplo, asi que el
+ *     modelo lo escribe tal cual, recibe cero y concluye que el proyecto no
+ *     tiene TypeScript. El codigo viejo hacia justo lo contrario de lo que hace
+ *     falta: solo volvia recursivos los patrones SIN comodin.
+ *
+ *  2. fast-glob trata `\` como caracter de escape, no como separador. Un
+ *     patron con rutas de Windows (`src\**\*.ts`) se convertia en `src**.ts` y
+ *     no casaba con nada.
+ *
+ * Devuelve una lista porque para un patron con ruta se prueban dos: la ruta tal
+ * cual (relativa a la carpeta de busqueda) y la misma anclada a cualquier nivel,
+ * que es lo que suele querer decir quien escribe `src/*.ts` sin saber desde
+ * donde se esta buscando. fast-glob deduplica.
+ */
+export function normalizarPatron(pattern) {
+    const limpio = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+    if (limpio === "")
+        return ["**/*"];
+    // Nombre suelto ("package.json", "claude"): subcadena, en cualquier nivel.
+    if (!META_GLOB.test(limpio))
+        return [`**/*${limpio}*`];
+    // Glob sin ruta ("*.ts", "test-*"): lo que el modelo quiere decir es
+    // "en todo el arbol", no "solo en la raiz".
+    if (!limpio.includes("/"))
+        return [`**/${limpio}`];
+    // Glob con ruta: se respeta, y ademas se busca en cualquier nivel.
+    return limpio.startsWith("**/") ? [limpio] : [limpio, `**/${limpio}`];
+}
 export async function findFiles(pattern, searchDirectory = process.cwd(), cwd = process.cwd()) {
     const resolvedDir = path.isAbsolute(searchDirectory)
         ? searchDirectory
@@ -8,17 +54,36 @@ export async function findFiles(pattern, searchDirectory = process.cwd(), cwd =
     if (!fs.existsSync(resolvedDir)) {
         return `Error: La carpeta "${searchDirectory}" no existe.`;
     }
-    const matches = await fg([pattern.includes("*") ? pattern : `**/*${pattern}*`], {
+    const patrones = normalizarPatron(pattern);
+    const flujo = fg.stream(patrones, {
         cwd: resolvedDir,
         dot: true,
         onlyFiles: false,
-        deep: 6,
+        // Sin `deep`: la profundidad la limitaba a 6 niveles y perdia ficheros sin
+        // avisar. El freno ahora es MAX_COINCIDENCIAS.
+        followSymbolicLinks: false, // sin tope de profundidad, un symlink circular no termina
+        suppressErrors: true, // una carpeta sin permisos no debe tumbar la busqueda entera
         ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/AppData/**", "**/__pycache__/**"],
     });
+    const matches = [];
+    let truncado = false;
+    // `break` en un for-await destruye el stream, asi que el recorrido del disco
+    // se para aqui de verdad.
+    for await (const entrada of flujo) {
+        matches.push(String(entrada));
+        if (matches.length >= MAX_COINCIDENCIAS) {
+            truncado = true;
+            break;
+        }
+    }
+    matches.sort();
     if (matches.length === 0) {
-        return `No se encontraron archivos ni carpetas con el patrón "${pattern}" en "${resolvedDir}".`;
+        // Se dice con que patron se busco de verdad: un vacio legitimo y un patron
+        // mal escrito daban antes el mismo mensaje.
+        const usados = patrones.map((p) => `"${p}"`).join(" y ");
+        return `No se encontraron archivos ni carpetas con el patrón "${pattern}" (buscado como ${usados}) en "${resolvedDir}".`;
     }
-    const formatted = matches.slice(0, 40).map((relPath) => {
+    const formatted = matches.slice(0, MAX_MOSTRADAS).map((relPath) => {
         const full = path.join(resolvedDir, relPath);
         try {
             const isDir = fs.statSync(full).isDirectory();
@@ -28,6 +93,10 @@ export async function findFiles(pattern, searchDirectory = process.cwd(), cwd =
             return `[ITEM] ${relPath}`;
         }
     });
-    const totalStr = matches.length > 40 ? ` (mostrando primeros 40 de ${matches.length})` : "";
-    return `Resultados encontrados para "${pattern}" en "${resolvedDir}"${totalStr}:\n${formatted.join("\n")}`;
+    const total = truncado ? `${MAX_COINCIDENCIAS}+` : `${matches.length}`;
+    const totalStr = matches.length > MAX_MOSTRADAS ? ` (mostrando primeros ${MAX_MOSTRADAS} de ${total})` : "";
+    const aviso = truncado
+        ? `\n(Búsqueda cortada en ${MAX_COINCIDENCIAS} coincidencias: afina el patrón o la carpeta.)`
+        : "";
+    return `Resultados encontrados para "${pattern}" en "${resolvedDir}"${totalStr}:\n${formatted.join("\n")}${aviso}`;
 }

package/dist/tools/getSystemInfo.js

@@ -1,17 +1,25 @@
 import os from "node:os";
-import { execa } from "execa";
+import { ejecutarGit } from "./gitTools.js";
 export async function getSystemInfo(cwd = process.cwd()) {
     const nodeVersion = process.version;
     const platform = `${os.type()} ${os.release()} (${os.arch()})`;
     const memoryFree = `${(os.freemem() / (1024 * 1024 * 1024)).toFixed(1)} GB`;
     const memoryTotal = `${(os.totalmem() / (1024 * 1024 * 1024)).toFixed(1)} GB`;
-    let gitInfo = "Git no disponible o fuera de repositorio.";
-    try {
-        const { stdout: status } = await execa("git", ["status", "--short"], { cwd, reject: false });
-        const { stdout: branch } = await execa("git", ["branch", "--show-current"], { cwd, reject: false });
-        gitInfo = `Rama: ${branch.trim() || "HEAD"}\nCambios:\n${status.trim() || "Directorio limpio (sin cambios pendientes)."}`;
+    // Antes esto era `let gitInfo = "Git no disponible..."` dentro de un try/catch
+    // con `reject: false`: el catch no podia saltar nunca, el fallback era codigo
+    // muerto y la linea de asignacion se ejecutaba SIEMPRE, incluso con git
+    // saliendo por 128. Resultado: "Rama: HEAD / Directorio limpio" fuera de
+    // cualquier repositorio. Ahora el fallo se ve porque ejecutarGit lo devuelve.
+    const estado = await ejecutarGit(["status", "--short"], cwd);
+    let gitInfo;
+    if (!estado.ok) {
+        gitInfo = `No disponible: ${estado.error}.`;
+    }
+    else {
+        const rama = await ejecutarGit(["branch", "--show-current"], cwd);
+        const nombreRama = rama.ok ? rama.stdout.trim() || "HEAD (sin rama)" : `desconocida (${rama.error})`;
+        gitInfo = `Rama: ${nombreRama}\nCambios:\n${estado.stdout.trim() || "Directorio limpio (sin cambios pendientes)."}`;
     }
-    catch { }
     return [
         `--- INFORMACIÓN DEL SISTEMA ---`,
         `Plataforma: ${platform}`,

package/dist/tools/gitTools.d.ts

@@ -1,3 +1,27 @@
+/** O la salida de git, o el motivo por el que no hay salida. Nunca las dos cosas. */
+export type SalidaGit = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Ejecuta git distinguiendo "no hay nada que contar" de "git ha fallado".
+ *
+ * Por que existe: las llamadas de este archivo (y las de getSystemInfo) usaban
+ * `{ reject: false }` y despues miraban SOLO `stdout`. Con reject:false execa no
+ * lanza nada: devuelve un resultado con `exitCode: 128` y `stdout: ""`. Asi que
+ * fuera de un repositorio -o con dubious ownership, o con el index.lock ocupado,
+ * o sin git en el PATH- el `|| "Repositorio limpio"` se disparaba y la
+ * herramienta afirmaba que el arbol estaba limpio y sin commits. El try/catch
+ * que parecia cubrir eso era codigo muerto por el mismo motivo: reject:false
+ * significa que no hay excepcion que atrapar.
+ *
+ * Mentir "limpio" es peor que no contestar: el agente decide sobre esa frase si
+ * puede seguir escribiendo sin miedo.
+ */
+export declare function ejecutarGit(args: string[], cwd: string): Promise<SalidaGit>;
 export declare function gitStatus(cwd?: string): Promise<string>;
 export declare function gitDiff(staged?: boolean, cwd?: string): Promise<string>;
 export declare function gitCommit(message: string, addAll?: boolean, cwd?: string): Promise<string>;

package/dist/tools/gitTools.js

@@ -1,43 +1,104 @@
 import { execa } from "execa";
-export async function gitStatus(cwd = process.cwd()) {
-    try {
-        const { stdout: status } = await execa("git", ["status", "--short"], { cwd, reject: false });
-        const { stdout: branch } = await execa("git", ["branch", "--show-current"], { cwd, reject: false });
-        const { stdout: lastLog } = await execa("git", ["log", "-n", "3", "--oneline"], { cwd, reject: false });
-        return [
-            `--- ESTADO DE GIT ---`,
-            `Rama actual: ${branch.trim() || "HEAD (sin rama)"}`,
-            `Archivos modificados/nuevos:\n${status.trim() || "Repositorio limpio (sin cambios pendientes)."}\n`,
-            `Últimos commits:\n${lastLog.trim() || "Sin historial de commits."}`,
-        ].join("\n");
+/**
+ * Traduce un fallo de git a una frase que el agente pueda creerse.
+ *
+ * No intenta clasificarlo todo: los tres casos con nombre son los que el
+ * usuario se encuentra de verdad (fuera de repo, repo ajeno, git ausente) y el
+ * resto cae al primer renglon de stderr, que ya es informacion util.
+ */
+function explicarFalloGit(stderrCrudo, respaldo) {
+    const stderr = typeof stderrCrudo === "string" ? stderrCrudo.trim() : "";
+    const texto = stderr || (typeof respaldo === "string" ? respaldo : "");
+    if (/not a git repository|no es un repositorio/i.test(texto)) {
+        return "este directorio no es un repositorio git";
     }
-    catch (err) {
-        return `Error consultando estado de Git: ${err?.message || String(err)}`;
+    if (/dubious ownership/i.test(texto)) {
+        return "git se niega a leer el repositorio por 'dubious ownership' (pertenece a otro usuario)";
     }
+    if (/ENOENT|not recognized|no se reconoce|command not found/i.test(texto)) {
+        return "git no esta instalado o no esta en el PATH";
+    }
+    const primeraLinea = texto.split("\n").find((l) => l.trim())?.trim();
+    return primeraLinea || "git fallo sin dar ningun mensaje";
 }
-export async function gitDiff(staged = false, cwd = process.cwd()) {
+/**
+ * Ejecuta git distinguiendo "no hay nada que contar" de "git ha fallado".
+ *
+ * Por que existe: las llamadas de este archivo (y las de getSystemInfo) usaban
+ * `{ reject: false }` y despues miraban SOLO `stdout`. Con reject:false execa no
+ * lanza nada: devuelve un resultado con `exitCode: 128` y `stdout: ""`. Asi que
+ * fuera de un repositorio -o con dubious ownership, o con el index.lock ocupado,
+ * o sin git en el PATH- el `|| "Repositorio limpio"` se disparaba y la
+ * herramienta afirmaba que el arbol estaba limpio y sin commits. El try/catch
+ * que parecia cubrir eso era codigo muerto por el mismo motivo: reject:false
+ * significa que no hay excepcion que atrapar.
+ *
+ * Mentir "limpio" es peor que no contestar: el agente decide sobre esa frase si
+ * puede seguir escribiendo sin miedo.
+ */
+export async function ejecutarGit(args, cwd) {
     try {
-        const args = ["diff"];
-        if (staged)
-            args.push("--staged");
-        const { stdout } = await execa("git", args, { cwd, reject: false });
-        if (!stdout.trim()) {
-            return staged ? "No hay cambios preparados (staged)." : "No hay cambios sin preparar (unstaged).";
+        const res = await execa("git", args, { cwd, reject: false });
+        // `failed` cubre tambien el caso en que el binario ni siquiera arranca, donde
+        // exitCode puede llegar como undefined.
+        if (res.failed || res.exitCode !== 0) {
+            return { ok: false, error: explicarFalloGit(res.stderr, res?.shortMessage) };
         }
-        return stdout.slice(0, 12_000);
+        return { ok: true, stdout: typeof res.stdout === "string" ? res.stdout : "" };
     }
     catch (err) {
-        return `Error obteniendo git diff: ${err?.message || String(err)}`;
+        // Solo alcanzable si execa revienta antes de lanzar el proceso (opciones
+        // invalidas, cwd inexistente). Raro, pero no puede acabar en "limpio".
+        return { ok: false, error: explicarFalloGit(err?.stderr, err?.shortMessage || err?.message || String(err)) };
+    }
+}
+export async function gitStatus(cwd = process.cwd()) {
+    const status = await ejecutarGit(["status", "--short"], cwd);
+    if (!status.ok) {
+        return `--- ESTADO DE GIT ---\nNo se pudo leer el estado: ${status.error}.`;
+    }
+    const branch = await ejecutarGit(["branch", "--show-current"], cwd);
+    const log = await ejecutarGit(["log", "-n", "3", "--oneline"], cwd);
+    // `git log` sale con 128 en un repo recien creado: ahi "sin historial" si es
+    // la verdad, no un fallo que ocultar.
+    const historial = log.ok
+        ? log.stdout.trim() || "Sin historial de commits."
+        : /does not have any commits|bad default revision|unknown revision/i.test(log.error)
+            ? "Sin historial de commits."
+            : `No se pudo leer el historial: ${log.error}.`;
+    return [
+        `--- ESTADO DE GIT ---`,
+        `Rama actual: ${branch.ok ? branch.stdout.trim() || "HEAD (sin rama)" : `desconocida (${branch.error})`}`,
+        `Archivos modificados/nuevos:\n${status.stdout.trim() || "Repositorio limpio (sin cambios pendientes)."}\n`,
+        `Últimos commits:\n${historial}`,
+    ].join("\n");
+}
+export async function gitDiff(staged = false, cwd = process.cwd()) {
+    const args = ["diff"];
+    if (staged)
+        args.push("--staged");
+    const res = await ejecutarGit(args, cwd);
+    if (!res.ok) {
+        return `No se pudo obtener el diff: ${res.error}.`;
+    }
+    if (!res.stdout.trim()) {
+        return staged ? "No hay cambios preparados (staged)." : "No hay cambios sin preparar (unstaged).";
     }
+    return res.stdout.slice(0, 12_000);
 }
 export async function gitCommit(message, addAll = true, cwd = process.cwd()) {
     try {
         if (addAll) {
-            await execa("git", ["add", "-A"], { cwd, reject: false });
+            // Si el `add` falla (index.lock, permisos) y aun asi hubiera algo ya
+            // preparado, el commit saldria bien y el usuario creeria que se ha
+            // guardado todo. Se corta aqui.
+            const add = await ejecutarGit(["add", "-A"], cwd);
+            if (!add.ok)
+                return `Fallo al preparar los cambios (git add -A): ${add.error}.`;
         }
-        const { stdout, stderr, exitCode } = await execa("git", ["commit", "-m", message], { cwd, reject: false });
-        if (exitCode !== 0) {
-            return `Fallo al hacer commit:\n${stderr || stdout}`;
+        const { stdout, stderr, exitCode, failed } = await execa("git", ["commit", "-m", message], { cwd, reject: false });
+        if (failed || exitCode !== 0) {
+            return `Fallo al hacer commit:\n${stderr || stdout || `git salio con codigo ${exitCode}`}`;
         }
         return `✔ Commit creado exitosamente: "${message}"\n${stdout}`;
     }

package/dist/tools/moveCopyFile.d.ts

@@ -1 +1,18 @@
-export declare function moveCopyFile(sourcePath: string, destinationPath: string, operation?: "move" | "copy", cwd?: string): Promise<string>;
+/**
+ * Mover o copiar sobre una ruta que ya existe borra lo que hubiera alli, y esto
+ * lo hacia en silencio: renameSync reemplaza el destino tanto en Windows como en
+ * POSIX, y cpSync trae force:true de serie. "Mueve nuevo.txt a importante.txt"
+ * contestaba el mismo "✔ Movido/Renombrado ... exitosamente" tanto si el destino
+ * estaba vacio como si acababa de tragarse tres dias de trabajo. Y move_copy_file
+ * no abria dialogo en modo default, cuando delete_file si lo abre y el efecto
+ * sobre ese archivo es identico: desaparece.
+ *
+ * Por eso pisar el destino pasa a ser explicito. Sin `overwrite` la llamada se
+ * corta antes de tocar el disco y el modelo recibe por que; con `overwrite` la
+ * tabla de permisos lo trata como un borrado y pregunta (permissions.ts), y el
+ * mensaje de vuelta ya no se confunde con el de un destino vacio.
+ *
+ * El guardia vive aqui, en la herramienta, y no solo en la tabla de permisos:
+ * asi tambien lo tienen los ejecutores que no pasan por el bucle principal.
+ */
+export declare function moveCopyFile(sourcePath: string, destinationPath: string, operation?: "move" | "copy", cwd?: string, overwrite?: boolean): Promise<string>;

package/dist/tools/moveCopyFile.js

@@ -1,21 +1,91 @@
 import fs from "node:fs";
 import path from "node:path";
-export async function moveCopyFile(sourcePath, destinationPath, operation = "move", cwd = process.cwd()) {
+/**
+ * Mover o copiar sobre una ruta que ya existe borra lo que hubiera alli, y esto
+ * lo hacia en silencio: renameSync reemplaza el destino tanto en Windows como en
+ * POSIX, y cpSync trae force:true de serie. "Mueve nuevo.txt a importante.txt"
+ * contestaba el mismo "✔ Movido/Renombrado ... exitosamente" tanto si el destino
+ * estaba vacio como si acababa de tragarse tres dias de trabajo. Y move_copy_file
+ * no abria dialogo en modo default, cuando delete_file si lo abre y el efecto
+ * sobre ese archivo es identico: desaparece.
+ *
+ * Por eso pisar el destino pasa a ser explicito. Sin `overwrite` la llamada se
+ * corta antes de tocar el disco y el modelo recibe por que; con `overwrite` la
+ * tabla de permisos lo trata como un borrado y pregunta (permissions.ts), y el
+ * mensaje de vuelta ya no se confunde con el de un destino vacio.
+ *
+ * El guardia vive aqui, en la herramienta, y no solo en la tabla de permisos:
+ * asi tambien lo tienen los ejecutores que no pasan por el bucle principal.
+ */
+export async function moveCopyFile(sourcePath, destinationPath, operation = "move", cwd = process.cwd(), overwrite = false) {
     const resolvedSource = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(cwd, sourcePath);
     const resolvedDest = path.isAbsolute(destinationPath) ? destinationPath : path.resolve(cwd, destinationPath);
     if (!fs.existsSync(resolvedSource)) {
         return `Error: El origen "${sourcePath}" no existe.`;
     }
+    // Un destino que es el propio origen no es nada que pisar: renombrar
+    // "notas.txt" a "Notas.txt" es legitimo y existsSync dice que si en cualquier
+    // disco que no distinga mayusculas.
+    const esElMismo = mismaEntradaEnDisco(resolvedSource, resolvedDest);
+    const destinoExiste = !esElMismo && fs.existsSync(resolvedDest);
+    const destinoEsDirectorio = destinoExiste && esDirectorio(resolvedDest);
+    if (destinoExiste && !overwrite) {
+        const que = destinoEsDirectorio ? "un directorio" : "un archivo";
+        const verbo = operation === "copy" ? "Copiar" : "Mover";
+        return (`Error: El destino "${destinationPath}" ya existe (${que}). ` +
+            `${verbo} el origen encima reemplazaria su contenido y no se hace sin permiso. ` +
+            `Elige otra ruta, o repite la llamada con overwrite=true si de verdad quieres ` +
+            `reemplazarlo (el usuario tendra que confirmarlo).`);
+    }
     const destDir = path.dirname(resolvedDest);
     if (!fs.existsSync(destDir)) {
         fs.mkdirSync(destDir, { recursive: true });
     }
     if (operation === "copy") {
         fs.cpSync(resolvedSource, resolvedDest, { recursive: true });
-        return `✔ Copiado "${sourcePath}" -> "${destinationPath}" exitosamente.`;
+        if (!destinoExiste) {
+            return `✔ Copiado "${sourcePath}" -> "${destinationPath}" exitosamente.`;
+        }
+        // Directorio contra directorio, cpSync fusiona en vez de sustituir, y el
+        // snapshot de /undo de una carpeta vale null (readFileSync de un directorio
+        // da EISDIR), asi que esa perdida no se recupera. Decirlo, que el usuario
+        // acaba de aprobar el dialogo contando con la red.
+        if (destinoEsDirectorio) {
+            return (`⚠ Copiado "${sourcePath}" -> "${destinationPath}": el destino ya existia y los archivos ` +
+                `que coincidian se han reemplazado. /undo no restaura directorios.`);
+        }
+        return `⚠ Copiado "${sourcePath}" -> "${destinationPath}": el destino ya existia y su contenido anterior se ha reemplazado (/undo lo recupera).`;
     }
-    else {
-        fs.renameSync(resolvedSource, resolvedDest);
+    fs.renameSync(resolvedSource, resolvedDest);
+    if (!destinoExiste) {
         return `✔ Movido/Renombrado "${sourcePath}" -> "${destinationPath}" exitosamente.`;
     }
+    return `⚠ Movido/Renombrado "${sourcePath}" -> "${destinationPath}": el destino ya existia y su contenido anterior se ha reemplazado (/undo lo recupera).`;
+}
+/**
+ * Si las dos rutas son la misma entrada del disco. Se le pregunta al sistema de
+ * ficheros en vez de deducirlo de la plataforma: hay volumenes de macOS que si
+ * distinguen mayusculas, y ahi "Notas.txt" seria otro archivo al que si hay que
+ * proteger.
+ */
+function mismaEntradaEnDisco(a, b) {
+    if (a === b)
+        return true;
+    try {
+        // .native pregunta al sistema operativo, que devuelve la caja real con la
+        // que esta escrita la entrada; realpathSync a secas respeta la que le pasen.
+        return fs.realpathSync.native(a) === fs.realpathSync.native(b);
+    }
+    catch {
+        // Si el destino no existe, realpathSync lanza: no son la misma entrada.
+        return false;
+    }
+}
+function esDirectorio(ruta) {
+    try {
+        return fs.statSync(ruta).isDirectory();
+    }
+    catch {
+        return false;
+    }
 }

package/dist/tools/patchCascade.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cascada de estrategias para localizar el fragmento que el modelo quiere
+ * reemplazar.
+ *
+ * El problema real no es que el modelo invente el codigo: es que copia bien las
+ * lineas y se come la sangria, o se deja una linea en blanco delante, o resume
+ * el interior de un bloque largo. Con una unica busqueda exacta, todos esos
+ * casos son un fallo y una iteracion perdida; Aider y opencode los resuelven
+ * probando estrategias cada vez mas flexibles y parando en la primera que casa.
+ *
+ * Reglas que se mantienen en TODAS las estrategias, porque son lo que separa
+ * "tolerante" de "escribe donde le parece":
+ *
+ *  - Si una estrategia encuentra mas de un sitio posible, no elige: falla. La
+ *    ambiguedad se resuelve pidiendo mas contexto, no adivinando.
+ *  - Una coincidencia desproporcionada (mucho mas grande que lo buscado) se
+ *    rechaza aunque sea unica. Es el fallo mas caro: un anclaje laxo que se
+ *    come medio archivo y responde "editado exitosamente".
+ */
+export interface Coincidencia {
+    /** Indice de caracter donde empieza el tramo, en el texto normalizado a LF. */
+    inicio: number;
+    /** Indice de caracter donde acaba (exclusivo). */
+    fin: number;
+    /** Texto de reemplazo ya adaptado (p. ej. re-sangrado) al sitio encontrado. */
+    textoNuevo: string;
+    /** Nombre de la estrategia que acerto. Se informa para poder medirlo. */
+    estrategia: string;
+}
+/** Hay candidatos, pero mas de uno: no se puede elegir sin adivinar. */
+export interface Rechazo {
+    ambiguo: true;
+    estrategia: string;
+    ocurrencias: number;
+}
+export type ResultadoCascada = Coincidencia | Rechazo | null;
+export declare function esRechazo(r: ResultadoCascada): r is Rechazo;
+export declare function normalizarPuntuacion(texto: string): string;
+/** true si el texto tiene algo que normalizar; evita recorrer el archivo en balde. */
+export declare function tienePuntuacionRara(texto: string): boolean;
+/**
+ * Rechaza un tramo que abarque mucho mas de lo buscado.
+ *
+ * Los umbrales son los de opencode: mas del doble de lineas (o tres de mas), o
+ * cuatro veces los caracteres (o 500 de mas).
+ */
+export declare function esDesproporcionada(buscado: string, encontrado: string): boolean;
+/**
+ * Orden de la cascada, de mas estricta a mas flexible. Se para en la primera
+ * que devuelve algo: una estrategia mas laxa no puede mejorar lo que ya acerto
+ * una mas estricta.
+ *
+ * Un rechazo por ambiguedad NO deja pasar a la siguiente estrategia. Si el
+ * fragmento aparece dos veces exactas, encontrar un tercer sitio "parecido" no
+ * arregla nada: lo que hay que hacer es pedir mas contexto.
+ */
+export declare function localizarFragmento(contenidoNormalizado: string, viejoNormalizado: string, nuevoNormalizado: string): ResultadoCascada;