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