21 El Libro de Ridgun

La lib `diff` — Algoritmo LCS, Distancia de Edición, Unified Diff y Parches

21.1. ¿Por qué existe la lib `diff`? (El problema real y la filosofía Ridgun)

«¿Por qué necesito una lib diff escrita desde cero en Ridgun puro en lugar de enlazar una librería de C de toda la vida?»

Esa es la primera pregunta que se hace cualquier ingeniero de sistemas al llegar a diff. Y la respuesta resume toda la filosofía de ridgun-libs:

Seamos sinceros: cuando un test falla o un archivo de configuración cambia, un seco "expected A, got B" de 200 líneas te obliga a dejarte las pestañas buscando qué línea exacta ha cambiado.

La lib diff calcula la Subsecuencia Común Más Larga (LCS) sobre Tensor[Int] 2D para producir ediciones mínimas (DiffKeep, DiffAdd, DiffDel), distancia de edición, estadísticas, formato Unified Diff (---/+++/@@) y reconstrucción exacta con diff apply.

En un ecosistema tradicional, resolver las tareas del dominio DIFF implica arrastrar dependencias externas en C, lidiar con punteros crudos, conversiones opacas de tipos, excepciones no verificadas o pausas impredecibles del recolector de basura. En Ridgun, la lib diff (src/main/ridgun/lib/diff.rg) aborda el problema con cuatro principios innegociables:

Declara import diff (o import diff as alias) al inicio del archivo: cada lib define su espacio de nombres module :: diff y en modo --strict las funciones multi-palabra se invocan siempre con espacios naturales.
Encadena tus tuberías de izquierda a derecha con ->: escribe entrada paso uno -> paso dos -> resultado, usa máscaras (+ _ _ +) para desestructurar secuencias y omite _ = en sentencias secuenciales (o descarta con -> ()).
Recursión de cola con TCO (Tail-Call Optimization): todos los recorridos internos de diff se compilan a bucles nativos en $O(1)$ espacio de pila.
Memoria determinista (RMM1 / RMM2): cada estructura intermedia se libera en el instante exacto en que termina su última lectura, sin Garbage Collector.

21.2. Artefactos nativos, importación y catálogo completo de la API de `diff`

En ridgun-libs, diff es una lib de primera clase ubicada en src/main/ridgun/lib/diff.rg (dominio DIFF). Al compilar con stable bundle, se empaqueta en tres artefactos nativos:

Artefacto	Ruta	Propósito
Bundle Ridgun	`target/bundles/diff.rglib`	Distribución e importación directa con `import diff`
Archivo compilado	`target/diff.rgc`	Artefacto intermedio verificado por `ridgunc`
Objeto compartido ELF64	`target/libdiff.so`	Biblioteca dinámica nativa sin dependencias de C ni `libc`

Cada lib declara su propio espacio de nombres con module :: diff: basta con escribir import diff (o import diff as alias) en el encabezado y llamar a sus funciones con espacios naturales (mi funcion x) y tuberías -> (x mi funcion -> resultado).

21.2.1. Resumen de familias funcionales de `diff`

Firma / Función / Tipo	Qué hace y cuándo usarla
`type DiffOp`	`DiffKeep String
`diff lines / diff text`	Calcula el guion mínimo de edición LCS entre listas `[String]` o textos multilínea
`diff edit distance / diff stats`	Distancia mínima de inserción+borrado y recuento `(kept, added, deleted)`
`diff format / diff unified`	Formatea líneas compactas `+ / - /` o Unified Diff estándar con cabeceras
`diff apply / diff apply text`	Reconstruye el documento destino sin pérdidas a partir del guion de edición

21.2.2. Catálogo exhaustivo de tipos y firmas en `src/main/ridgun/lib/diff.rg`

A continuación tienes el inventario completo de tipos algebraicos (type), operadores (op ::) y firmas de funciones (fn ::) definidos en src/main/ridgun/lib/diff.rg (2 tipos, 0 operadores y 33 funciones):

Tipos algebraicos y registros (type) de diff:

type DiffEdit = diff_op: String, line_text: String, old_line_no: Int, new_line_no: Int
type DiffStats = equal_count: Int, insert_count: Int, delete_count: Int

#	Función / Firma (`fn ::`)	Tipo de Retorno
`1`	`fn :: df max Int Int`	`Int`
`2`	`fn :: df int to str pos Int`	`String`
`3`	`fn :: df int to str Int`	`String`
`4`	`fn :: df rev [String] [String]`	`[String]`
`5`	`fn :: df rev ints [Int] [Int]`	`[Int]`
`6`	`fn :: df split lines loop String Int Int Int [String]`	`[String]`
`7`	`fn :: df split lines String`	`[String]`
`8`	`fn :: df zeros Int [Int]`	`[Int]`
`9`	`fn :: df nth int [Int] Int`	`Int`
`10`	`fn :: df head int [Int]`	`Int`
`11`	`fn :: df cell val String String Int Int Int`	`Int`
`12`	`fn :: df build row String [String] [Int] Int [Int]`	`[Int]`
`13`	`fn :: df build dp [String] [String] [[Int]]`	`[[Int]]`
`14`	`fn :: df tail rows [[Int]]`	`[[Int]]`
`15`	`fn :: df head row [[Int]]`	`[Int]`
`16`	`fn :: df rev edits [DiffEdit] [DiffEdit]`	`[DiffEdit]`
`17`	`fn :: df backtrack [String] [String] [[Int]] Int Int Int [DiffEdit]`	`[DiffEdit]`
`18`	`fn :: df backtrack step String [String] String [String] [[Int]] Int Int Int [DiffEdit]`	`[DiffEdit]`
`19`	`fn :: df backtrack branch String [String] String [String] [[Int]] [[Int]] Int Int Int Int Int [DiffEdit]`	`[DiffEdit]`
`20`	`fn :: df list length [String]`	`Int`
`21`	`fn :: diff lines [String] [String]`	`[DiffEdit]`
`22`	`fn :: diff text String String`	`[DiffEdit]`
`23`	`fn :: df stats loop [DiffEdit] Int Int Int`	`DiffStats`
`24`	`fn :: diff stats [DiffEdit]`	`DiffStats`
`25`	`fn :: diff edit distance String String`	`Int`
`26`	`fn :: diff has changes [DiffEdit]`	`Bool`
`27`	`fn :: df format unified lines [DiffEdit] String`	`String`
`28`	`fn :: df hunk start Int`	`Int`
`29`	`fn :: df unified header String String Int Int`	`String`
`30`	`fn :: diff unified String String String String`	`String`
`31`	`fn :: df apply collect [DiffEdit] [String]`	`[String]`
`32`	`fn :: df join lines [String]`	`String`
`33`	`fn :: diff apply [DiffEdit]`	`String`

21.3. Explorando `diff` a fondo: Ejemplos paso a paso de cada funcionalidad

No basta con ver la tabla de firmas: vamos a explorar cada una de las funcionalidades de la lib diff mediante ejemplos progresivos y ejecutables en Ridgun. Empezaremos por las dos recetas tabulares de uso cotidiano y después recorreremos en detalle todos los escenarios funcionales, transformaciones y casos límite verificados en src/test/ridgun/test diff.rg.

21.3.1. Ejemplo 1: Flujo principal en estilo tabular con `diff`

Observa cómo en Ridgun los signos = y los pasos de transformación con diff quedan alineados como una tabla limpia, sin variables mutables innecesarias ni efectos laterales ocultos:

import diff

fn :: auditar cambio String String => Int String
      auditar cambio antes despues =
        diff edit distance antes despues -> dist
        diff unified antes despues "config.old" "config.new" -> parche
        (dist, parche)

21.3.2. Ejemplo 2: Composición segura y manejo de casos de borde

Toda función de la lib diff está diseñada para componerse con guardas booleanas | y con el resto de las 32 libs de ridgun-libs:

import diff

fn :: verificar parche String [DiffEdit] => String
      verificar parche orig ops =
        diff apply orig ops