1# Changelog — charka
2
3Transpilador COBOL → Rust. El módulo más grande del ecosistema (Fase D
4del plan macro) — el parser COBOL completo es un esfuerzo multi-mes.
5
6### feat(charka): EVALUATE TRUE y rangos WHEN ... THRU
7
8Completa el `EVALUATE` con sus dos formas que faltaban.
9
10- IR: la rama `WhenBranch` pasa de `values: Vec<Operand>` a
11  `tests: Vec<WhenTest>`, donde `WhenTest` es `Value` (igualdad),
12  `Range` (`WHEN lo THRU hi`) o `Cond` (`EVALUATE TRUE WHEN cond`).
13- Parser: detecta `EVALUATE TRUE` y entonces cada `WHEN` parsea una
14  condición; en modo valor reconoce `WHEN lo THRU hi`.
15- Codegen y shadow: una prueba `Range` se traduce a `lo <= s <= hi`;
16  una `Cond`, a la condición directa.
17- Corpus: programa nuevo `14-clasifica` (clasifica notas con rangos
18  `THRU` y un `EVALUATE TRUE`). Verificado en ambas rutas.
19
20### feat(charka): INSPECT — contar y reemplazar caracteres
21
22El verbo de COBOL para analizar y limpiar campos de texto.
23
24- IR: `Stmt::Inspect { target, op }` con `InspectOp::TallyingForAll`
25  (cuenta apariciones y las suma a un contador) y
26  `InspectOp::ReplacingAll` (reemplaza apariciones).
27- Parser: `INSPECT t TALLYING n FOR ALL lit` y
28  `INSPECT t REPLACING ALL a BY b`. Una forma no soportada cae a
29  `Stmt::Unknown`.
30- Codegen: `TALLYING` → `str::matches(..).count()`; `REPLACING` →
31  `str::replace`.
32- Shadow: el intérprete cuenta / reemplaza el texto.
33- Corpus: programa nuevo `13-inspeccion`. Verificado: el intérprete
34  sombra y el crate compilado dan la misma salida.
35- Alcance v1: `TALLYING FOR ALL` y `REPLACING ALL`; sin `LEADING`,
36  `FIRST`, `CHARACTERS`, `BEFORE`/`AFTER`.
37
38### feat(charka): STRING y UNSTRING — manejo de cadenas
39
40Dos verbos comunes de COBOL para construir y partir cadenas.
41
42- IR: `Stmt::StringConcat { sources, into }` y
43  `Stmt::Unstring { source, delimiter, into }`.
44- Parser: `STRING a b DELIMITED BY SIZE INTO t END-STRING` y
45  `UNSTRING s DELIMITED BY d INTO a b c END-UNSTRING`.
46- Codegen: `STRING` → `format!` concatenado; `UNSTRING` → un bloque
47  que parte con `str::split` y reparte los trozos.
48- Shadow: el intérprete concatena / parte el texto y lo reparte.
49- Corpus: programa nuevo `12-cadenas`. Verificado: el intérprete
50  sombra y el crate compilado dan la misma salida.
51- Alcance v1: `STRING` con `DELIMITED BY SIZE` (los demás
52  delimitadores se ignoran); sin `WITH POINTER` ni `ON OVERFLOW`.
53
54### feat(charka): OCCURS — tablas y referencias con subíndice
55
56Los arrays de COBOL, que antes el transpilador descartaba en silencio.
57Atraviesa el pipeline entero.
58
59- Parser: la cláusula `OCCURS n [TIMES]` se captura en `DataItem`.
60- IR: `Operand::Indexed { name, index }` — una referencia `ELEM(I)`.
61  El subíndice es 1-based, como COBOL. Los destinos de los statements
62  pasan de `Vec<String>` a `Vec<Operand>`, así que se puede escribir a
63  un elemento de tabla (`MOVE x TO ELEM(I)`, `COMPUTE ELEM(I) = ...`).
64  `Field` del modelo gana `occurs: Option<u32>`.
65- Codegen: un campo `OCCURS` se emite como `Vec<Num>`/`Vec<Text>`,
66  inicializado con `vec![..; n]`; una referencia con subíndice indexa
67  el vector (1-based → 0-based).
68- Shadow: en el intérprete todo campo es un vector — un escalar es de
69  longitud 1, una tabla de `n`; las referencias se resuelven a
70  `(nombre, índice)`.
71- Corpus: programa nuevo `11-tabla` (llena una tabla con cuadrados y
72  los suma). Verificado: el intérprete sombra y el crate compilado por
73  `scaffold` dan ambos `SUMA DE CUADRADOS = 000055`.
74- Alcance v1: `OCCURS` en datos elementales, una dimensión, subíndice
75  de un solo operando. Fuera: `OCCURS` de grupo, multidimensional,
76  `OCCURS DEPENDING ON`.
77
78### feat(charka): nombres de condición (nivel 88) + modelo de datos compartido
79
80`IF ES-VALIDO` — los nombres de condición de COBOL, que antes el
81transpilador evaluaba siempre como `false`. Y, de paso, se elimina una
82duplicación: la resolución del modelo de datos.
83
84- `charka-ir` gana un módulo `model`: `resolve_data(&[DataItem]) ->
85  DataModel` aplana el árbol de datos a campos elementales (`Field` con
86  `FieldKind`) y a nombres de condición (`ConditionName`). El `Ir`
87  ahora lleva un campo `model`. Es la fuente única de verdad sobre la
88  clasificación de PICTURE.
89- `charka-codegen` y `charka-shadow` consumen `ir.model` en vez de
90  reimplementar cada uno la clasificación numérico/alfanumérico, el
91  ancho de PICTURE y la normalización de `VALUE`. `charka-codegen` ya
92  no depende de `charka-bcd`.
93- `Cond::Named` (un nivel 88) se resuelve a `padre = valor`: el codegen
94  emite la comparación, el intérprete sombra la evalúa.
95- Corregido de paso: un dato con hijos de nivel 88 (p. ej.
96  `01 WS-FLAG PIC X. 88 ES-SI VALUE 'Y'.`) antes se perdía como si
97  fuera un grupo; ahora se reconoce como campo elemental.
98- Corpus: programa nuevo `10-condicion` (un semáforo con 88 de texto y
99  de número, en `IF` e `IF/ELSE`). Verificado: intérprete y crate
100  compilado dan la misma salida.
101
102### feat(charka): EVALUATE — el case de COBOL
103
104`EVALUATE` atraviesa el pipeline entero — antes el parser lo guardaba
105crudo como `Stmt::Unknown`.
106
107- IR: `Stmt::Evaluate { subject, whens, other }` con
108  `WhenBranch { values, body }`. Varios `WHEN` apilados comparten
109  cuerpo; `WHEN OTHER` es el caso por defecto.
110- Parser: `EVALUATE subject WHEN v1 WHEN v2 ... [WHEN OTHER ...]
111  END-EVALUATE`.
112- Codegen: lo baja a una cadena `if / else if / else` — una rama se
113  elige si el sujeto es igual a alguno de sus valores; sin caída.
114- Shadow: el intérprete evalúa el sujeto y ejecuta la primera rama
115  cuyos valores casen, o el `WHEN OTHER`.
116- Corpus: programa nuevo `09-evaluar` (un `EVALUATE` por valor anidado
117  en un `PERFORM VARYING`, con `WHEN` apilados y `WHEN OTHER`).
118  Verificado: intérprete sombra y crate compilado dan la misma salida.
119- Alcance v1: `EVALUATE` por igualdad de valor; no la forma
120  `EVALUATE TRUE` con condiciones ni los rangos `THRU`.
121
122### feat(charka): PERFORM VARYING — el bucle con variable de control
123
124El bucle más usado de COBOL, que antes el parser degradaba a un
125`PERFORM` vacío. Ahora atraviesa el pipeline entero.
126
127- IR: `PerformControl::Varying { var, from, by, until }`.
128- Parser: reconoce `PERFORM VARYING var FROM x BY y UNTIL cond` en
129  línea (`END-PERFORM`) y fuera de línea (`PERFORM párrafo VARYING …`).
130- Codegen: emite `var = from; while !(until) { cuerpo; var += by; }`.
131- Shadow: el intérprete inicializa la variable, evalúa la condición
132  antes de cada vuelta e incrementa al final.
133- Corpus: programa nuevo `08-varying` (suma 1..10 con `PERFORM
134  VARYING`). Verificado: el intérprete sombra y el crate compilado por
135  `scaffold` dan ambos `SUMA 1 A 10 = 00055`.
136
137### feat(charka): CLI del transpilador — transpile / scaffold / run / check
138
139App nueva `crates/apps/charka` — el binario `charka`, que vuelve usable
140el pipeline desde la terminal. Cuatro comandos:
141
142- `transpile <in.cob> [-o out.rs]` — emite el código Rust (a un archivo
143  o a la salida estándar).
144- `scaffold <in.cob> -o <dir>` — genera un crate Rust completo
145  (`Cargo.toml` + `src/main.rs`) que depende de `charka-runtime` y
146  compila tal cual.
147- `run <in.cob>` — ejecuta el programa con el intérprete sombra y
148  muestra su salida, sin compilar nada.
149- `check <in.cob> -e <esperado>` — ejecuta y diferencia la salida
150  contra un archivo esperado; reporta las líneas que difieren.
151
152Avisa de los verbos COBOL que aún no se transpilan. Verificado de
153punta a punta contra el corpus: `scaffold` de `06-nomina` genera un
154crate que compila y produce la misma salida que el intérprete sombra —
155las dos rutas de ejecución concuerdan. 4 tests; fmt + clippy limpios.
156
157### feat(charka-shadow): validador en sombra + corpus COBOL
158
159Crate nuevo `crates/modules/charka/charka-shadow` y un corpus de prueba
160`crates/modules/charka/corpus/` — el pipeline COBOL→Rust queda
161completo y validado de punta a punta.
162
163- `charka-shadow` certifica que el transpilador preserva la semántica
164  del COBOL original con una **ejecución sombra**: un intérprete que
165  corre el `Ir` directamente sobre `charka-runtime`, sin compilar nada.
166  Es una segunda ruta de ejecución, independiente del código que emite
167  `charka-codegen`.
168- `interpret(&Ir) -> Outcome` ejecuta el IR y captura las líneas de
169  `DISPLAY`; `run_source(&str)` corre el pipeline completo (lexer →
170  parser → IR → intérprete).
171- Tope de pasos (`Halt::StepLimit`): un bucle que no termina se corta
172  en vez de colgar la ejecución.
173- **Corpus**: 7 programas COBOL de complejidad graduada — `01-hola`
174  (un `DISPLAY`), `02-aritmetica` (`ADD`/`SUBTRACT`/`MULTIPLY`),
175  `03-condicional` (`IF`/`ELSE`), `04-bucle` (`PERFORM TIMES`),
176  `05-factorial` (`PERFORM UNTIL`), `06-nomina` (grupos, `COMPUTE` con
177  paréntesis, `ROUNDED`, `V99`), `07-clasificar` (`IF` anidado, `AND`).
178  Cada uno con su `.expected` verificada a mano.
179- 11 tests: los 7 programas del corpus + fuente vacío, `STOP RUN`,
180  corte por tope de pasos y propagación de error de léxico.
181
182### feat(charka-codegen): emisión de Rust desde el IR
183
184Crate nuevo `crates/modules/charka/charka-codegen` — la etapa final del
185pipeline. `generate(&Ir) -> String` produce un fuente Rust (un
186`main.rs`) que, compilado contra `charka-runtime`, ejecuta la lógica
187del programa COBOL.
188
189- Un `struct Program` con un campo por cada dato elemental — `Num`
190  para los numéricos, `Text` para los alfanuméricos; `Program::new()`
191  los inicializa desde sus cláusulas `VALUE`.
192- Un método `p_<párrafo>(&mut self)` por cada párrafo del PROCEDURE;
193  `run()` los encadena en orden (el «caer» de COBOL); `main()`
194  construye el `Program` y lo corre.
195- Cada `Stmt` → código Rust: `MOVE`→`.store`/`.fill`,
196  `DISPLAY`→`println!`, `COMPUTE` y la aritmética → expresiones
197  `Decimal`, `IF`→`if`/`else`, `PERFORM`→ llamada de método / `for` /
198  `while`, `GO TO`→ llamada + `return`, `STOP RUN`→`process::exit`.
199- Tolerante: lo no transpilable (`Stmt::Unknown`, un dato sin resolver,
200  el operador `**`) se emite como comentario `// charka:`; el código
201  generado siempre compila.
202- Saneado de identificadores COBOL→Rust (incl. choques con keywords).
203- Verificado de punta a punta: un programa COBOL de demostración
204  transpila a Rust que compila contra `charka-runtime` y produce la
205  salida esperada (`COMPUTE`, `IF`, `PERFORM`, `DISPLAY`).
206- 14 tests del fuente emitido; fuera de alcance v1: grupos como campo,
207  `REDEFINES`, `OCCURS`, `PERFORM ... THRU` como rango, E/S.
208
209### feat(charka-runtime): soporte de ejecución — campos Num y Text
210
211Crate nuevo `crates/modules/charka/charka-runtime` — el soporte que los
212programas COBOL transpilados enlazan. `charka-codegen` no emitirá Rust
213autónomo: emitirá Rust que llama a esta biblioteca.
214
215- `Num` — campo numérico (`PIC 9(5)V99`): un `Decimal` conformado a su
216  `Picture`. `store` trunca a la escala declarada; `store_rounded`
217  redondea; al desbordar la parte entera conserva los dígitos de bajo
218  orden (el `ON SIZE ERROR` de COBOL sin cláusula). `display` da los
219  dígitos con relleno de ceros y signo si corresponde.
220- `Text` — campo alfanumérico (`PIC X(n)`) de longitud fija: `store`
221  justifica a la izquierda y rellena con espacios o trunca; `fill`
222  mueve las constantes figurativas (`SPACES`, `ZEROS`).
223- `cobol_text_cmp` — comparación alfanumérica que rellena el más corto
224  con espacios.
225- Reexporta `Decimal`/`Picture`/`Rounding` de `charka-bcd`.
226- Construido antes que `charka-codegen` (la nota de orden del plan los
227  listaba al revés): el codegen emite contra esta API, así que el
228  runtime debe existir primero — y se verifica solo, sin el codegen.
229- 17 tests: campo en cero, `VALUE` inicial, truncado y redondeo,
230  desbordamiento que conserva bajo orden, magnitud sin signo y signo
231  con signo, justificación y relleno de texto, `fill`, comparación.
232
233### feat(charka-ir): representación intermedia — statements tipados
234
235Crate nuevo `crates/modules/charka/charka-ir` — la tercera etapa del
236pipeline: `Program` → `Ir`. El PROCEDURE division pasa de sentencias
237con tokens crudos a un árbol de instrucciones tipadas.
238
239- `lower(&Program) -> Ir` — total y tolerante: nunca falla.
240- `Ir { program_id, data, procedures }`. El modelo de datos (la DATA
241  division) pasa tal cual — sirve de tabla de símbolos.
242- `Stmt` cubre `MOVE`, `DISPLAY`, `ACCEPT`, `COMPUTE`, `ADD`,
243  `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `IF`/`ELSE`/`END-IF`, `PERFORM`
244  (fuera de línea, en línea, `TIMES`, `UNTIL`), `GO TO`, `STOP RUN`,
245  `GOBACK`, `EXIT`, `CONTINUE`.
246- Expresiones de `COMPUTE` con precedencia y paréntesis (`+ -` <
247  `* /` < `**` asociativo a derecha). Condiciones de `IF`/`UNTIL` con
248  comparadores en forma símbolo (`= < > <= >= <>`) o palabra
249  (`EQUAL TO`, `GREATER THAN`...), `AND`/`OR`/`NOT` y nombres de
250  condición (datos de nivel 88).
251- COBOL no termina los statements con un símbolo: el parser delimita
252  las listas de operandos con palabras "frontera" (verbos,
253  terminadores `END-*`/`ELSE`, conectores `TO`/`GIVING`/`BY`...).
254- Un verbo no soportado se conserva como `Stmt::Unknown { verb,
255  tokens }` — el lowering nunca aborta.
256- Fuera de alcance v1: `EVALUATE`, `STRING`/`UNSTRING`, E/S de
257  ficheros, `PERFORM VARYING`, CICS, SQL embebido.
258- 17 tests: MOVE simple y multi-destino, DISPLAY con figurativas,
259  precedencia de COMPUTE, flag ROUNDED, ADD in-place vs GIVING,
260  SUBTRACT, DIVIDE BY/INTO, IF/ELSE, condiciones con AND, nombre de
261  condición, PERFORM párrafo/TIMES/UNTIL en línea, varios statements
262  en una sentencia, verbo desconocido, programa completo.
263
264### feat(charka-parser): parser COBOL'85 → AST
265
266Crate nuevo `crates/modules/charka/charka-parser` — la segunda etapa del
267pipeline: `Vec<Token>` → `Program` (AST). Alcance v1: el esqueleto del
268programa.
269
270- `parse(&[Token]) -> Result<Program, ParseError>`. El AST: `Program`
271  (`program_id`, `data`, `paragraphs`), `DataItem`, `Paragraph`,
272  `Sentence`.
273- Particiona el flujo de tokens en las cuatro divisiones por sus
274  encabezados (`X DIVISION`); de la IDENTIFICATION extrae el
275  `PROGRAM-ID`.
276- **DATA division** → árbol de `DataItem`: número de nivel, nombre,
277  cláusula `PICTURE` reensamblada (`S9` `(` `5` `)` `V99` →
278  `S9(5)V99`) y `VALUE`. Anida por número de nivel — 01 y 77 son
279  raíces, 88 cuelga del ítem precedente.
280- **PROCEDURE division** → `Vec<Paragraph>`, cada párrafo con sus
281  `Sentence` (tokens crudos; sin parseo a nivel de statement, eso es
282  `charka-ir`). Las sentencias previas al primer encabezado van a un
283  párrafo implícito de nombre "".
284- Parser tolerante: salta encabezados de `SECTION`, entradas `FD`/`SD`
285  y cláusulas de datos que no sean `PICTURE`/`VALUE`. `ParseError` sólo
286  ante un número de nivel inválido o un dato sin nombre.
287- 15 tests: PROGRAM-ID (forma larga y `ID` corta), ítems planos y
288  anidados, reensamblado de PICTURE, variantes de VALUE, niveles 88,
289  `FILLER`, párrafos y párrafo implícito, encabezado de sección,
290  programa completo de punta a punta, nivel inválido.
291
292### feat(charka-lexer): tokenizador de COBOL
293
294Crate nuevo `crates/modules/charka/charka-lexer` — la primera etapa del
295pipeline del transpilador: texto COBOL → secuencia de `Token`.
296
297- **Lexer deliberadamente tonto**: no conoce keywords ni la cláusula
298  `PICTURE`; emite `Word` para todo identificador y deja la
299  clasificación al parser.
300- Tokens: `Word` (palabras COBOL con guiones internos), `Number`
301  (literal sin signo), `String` (comillas dobladas colapsadas),
302  `Period` (el `.` terminador), `Symbol` (paréntesis, separadores y
303  operadores `+ - * / ** = < > <= >= <>`).
304- Dos formatos de fuente: **fijo** (la tarjeta de 80 columnas — cols
305  1-6 secuencia, 7 indicadora, 8-72 código, 73-80 identificación) y
306  **libre**. Comentarios por la columna indicadora (`*`/`/`) o por `*`
307  inicial en formato libre.
308- Cada `Token` lleva línea y columna 1-based; `LexError` tipado
309  (literal sin cerrar, carácter inesperado).
310- Limitación v1 documentada: no soporta continuación de literales entre
311  líneas (indicador `-`). Subconjunto COBOL'85, el hito intermedio.
312- 17 tests: sentencias, palabras con guiones, literales y comillas
313  dobladas, números vs terminador, operadores, ambos formatos,
314  tracking de posición, errores.
315
316### feat(charka-bcd): aritmética decimal con semántica COBOL
317
318(Pre-existente.) `Picture` + `Decimal` de punto fijo exacto — ver el
319SDD del módulo. 22 tests.