1# modules/charka/ — Transpilador COBOL → Rust
2
3**Propósito.** Modernizar sistemas COBOL legados transpilándolos a Rust
4con un runtime determinista y un validador en sombra (shadow validator)
5que compara la salida del original y la del transpilado. Es el módulo
6más grande del ecosistema — el parser COBOL completo (CICS, SQL
7embebido, dialectos IBM Enterprise) es un esfuerzo multi-mes.
8
9## Crates
10
11| crate          | tipo | rol                                                          |
12| -------------- | ---- | ------------------------------------------------------------ |
13| `charka-bcd`    | lib  | Aritmética decimal de punto fijo con semántica COBOL: `Picture`, `Decimal`, redondeo, `ON SIZE ERROR` |
14| `charka-lexer`  | lib  | Tokenizador COBOL: formato fijo (tarjeta de 80 columnas) y libre |
15| `charka-parser`  | lib  | Parser COBOL'85 (subconjunto): tokens → AST (`Program`) |
16| `charka-ir`      | lib  | Representación intermedia: el AST con los statements del PROCEDURE ya tipados |
17| `charka-runtime` | lib  | Soporte de ejecución de los programas transpilados: campos `Num` y `Text` |
18| `charka-codegen` | lib  | Emisión de Rust: IR → fuente Rust sobre `charka-runtime` |
19| `charka-shadow`  | lib  | Validador en sombra: intérprete del IR + corpus de prueba |
20
21## charka-bcd
22
23COBOL no calcula en binario flotante: opera sobre campos decimales de
24precisión fija (`PIC S9(5)V99`). Reproducir un programa COBOL exige
25reproducir esa aritmética dígito a dígito.
26
27- `Picture` — parsea la cláusula PICTURE numérica (`9`, `V`, `S`, `9(n)`).
28- `Decimal` — punto fijo exacto (`mantissa: i128` + `scale`); suma, resta
29  y producto exactos; división con escala de resultado fija; redondeo
30  `Truncate`/`HalfUp`; `coerce` a un `Picture` con detección de
31  desbordamiento.
32- Determinista, sin dependencias de plataforma — mismo programa, mismos
33  dígitos, en cualquier máquina.
34
35## charka-lexer
36
37Primera etapa del pipeline: texto COBOL → secuencia de `Token`.
38
39- **Lexer tonto**: no conoce keywords ni la cláusula `PICTURE` — emite
40  `Word` para todo identificador; la clasificación es del parser.
41- Tokens: `Word` (con guiones internos, `WORKING-STORAGE`), `Number`
42  (sin signo), `String` (comillas dobladas colapsadas), `Period`,
43  `Symbol` (`( ) , ; :` y operadores `+ - * / ** = < > <= >= <>`).
44- Dos formatos: **fijo** (cols 1-6 secuencia, 7 indicadora, 8-72
45  código, 73-80 id) y **libre**. Comentarios por col 7 (`*`/`/`) o `*`
46  inicial en formato libre.
47- Cada token lleva línea/columna 1-based. `LexError` tipado.
48- Limitación v1: sin continuación de literales entre líneas
49  (indicador `-`).
50
51## charka-parser
52
53Segunda etapa: tokens → AST. Alcance v1 — el **esqueleto del programa**.
54
55- `parse(&[Token]) -> Result<Program, ParseError>`.
56- `Program { program_id, data: Vec<DataItem>, paragraphs: Vec<Paragraph> }`.
57- **DATA division** → árbol de `DataItem` (`level`, `name`, `picture`,
58  `value`, `children`). Reensambla la cláusula `PICTURE` desde sus
59  tokens (`S9` `(` `5` `)` `V99` → `S9(5)V99`); anida por número de
60  nivel (01 y 77 son raíces; 88 cuelga del ítem precedente).
61- **PROCEDURE division** → `Vec<Paragraph>`, cada `Paragraph` con sus
62  `Sentence` (tokens crudos — sin parseo a nivel de statement). Las
63  sentencias previas al primer encabezado van a un párrafo implícito
64  de nombre "".
65- Tolerante: salta encabezados de `SECTION`, entradas `FD`/`SD` y
66  cláusulas de datos que no sean `PICTURE`/`VALUE`. `ParseError` sólo
67  ante nivel inválido o dato sin nombre.
68- Limitación v1: no parsea statements, ni la ENVIRONMENT division, ni
69  CICS / SQL embebido / dialectos IBM.
70
71## charka-ir
72
73Tercera etapa: `Program` → `Ir`. Aquí se parsea cada `Sentence` cruda
74(tokens) a statements tipados — el PROCEDURE division pasa de tokens a
75árbol de instrucciones.
76
77- `lower(&Program) -> Ir` — **total y tolerante**, nunca falla.
78- `Ir { program_id, data, model, procedures }`. `data` es el árbol de
79  `DataItem` con su estructura de grupos; `model` es el **modelo de
80  datos resuelto** (módulo `model`): el árbol aplanado a campos
81  elementales (`Field` con `FieldKind` numérico/alfanumérico y el
82  `VALUE` normalizado) más los nombres de condición (nivel 88). Es la
83  fuente única de verdad sobre «qué tipo de campo describe una
84  PICTURE» — `charka-codegen` y `charka-shadow` lo consumen en vez de
85  reimplementar la clasificación.
86- `Procedure { name, body: Vec<Stmt> }`. `Stmt` cubre `Move`,
87  `Display`, `Accept`, `Compute`, `Add`/`Subtract`/`Multiply`/`Divide`,
88  `If`, `Evaluate`, `StringConcat`, `Unstring`, `Inspect`,
89  `Initialize`, `SetTrue`, `Perform`, `GoTo`, `StopRun`, `Goback`,
90  `Exit`, `Continue`.
91- `Expr` — expresiones aritméticas con precedencia y paréntesis (Pratt:
92  `+ -` < `* /` < `**` der.). `Cond` — comparaciones (símbolo o forma
93  palabra) unidas por `AND`/`OR`/`NOT`, más nombres de condición
94  (nivel 88), que se resuelven contra el `model` a `padre = valor`.
95- Un verbo no soportado se conserva como `Stmt::Unknown { verb,
96  tokens }` — el lowering jamás aborta.
97- COBOL no separa statements con un símbolo: cada uno corta donde
98  empieza el verbo del siguiente. El parser usa palabras "frontera"
99  (verbos + terminadores `END-*`/`ELSE` + conectores `TO`/`GIVING`...)
100  para delimitar listas de operandos.
101- `PERFORM` cubre las cuatro formas: párrafo (incluido el rango
102  `THRU`) / en línea, `n TIMES`, `UNTIL cond` y `VARYING var FROM x
103  BY y UNTIL cond`.
104- `EVALUATE` — el `case` de COBOL: `WHEN valor`, `WHEN lo THRU hi`
105  (rango), `WHEN OTHER`, y la forma `EVALUATE TRUE WHEN condición`.
106- `STRING` (concatenación) y `UNSTRING` (partición por delimitador) —
107  el manejo de cadenas. `INSPECT` — contar (`TALLYING FOR ALL`) y
108  reemplazar (`REPLACING ALL`).
109- `INITIALIZE` — resetea un dato (o todos los elementales de un grupo)
110  a su valor por defecto. El `model` registra los grupos y sus
111  miembros (`DataModel::groups`).
112- `SET cond... TO TRUE` — la cara de escritura de los nombres de
113  condición (nivel 88): asigna a su dato padre el valor del 88.
114- E/S de ficheros: `Stmt::Open`/`Close`/`Read`/`Write` y `Ir::files`
115  (de `SELECT` + `FD`). Sólo organización «line sequential».
116- Fuera de alcance v1: CICS, SQL embebido.
117
118## charka-runtime
119
120El soporte de ejecución: lo que `charka-codegen` emite es Rust que
121enlaza contra este crate. Da a un programa transpilado la semántica de
122COBOL en tiempo de ejecución.
123
124- `Num` — campo numérico (`PIC 9(5)V99`): un `Decimal` conformado a su
125  `Picture`. `store`/`store_rounded` truncan o redondean a la escala
126  declarada; al desbordar conservan los dígitos de bajo orden (el
127  `ON SIZE ERROR` sin cláusula). `display` da los dígitos con relleno
128  de ceros.
129- `Text` — campo alfanumérico (`PIC X(20)`) de longitud fija: `store`
130  justifica a la izquierda y rellena/trunca; `fill` mueve figurativas
131  (`SPACES`, `ZEROS`).
132- `cobol_text_cmp` — comparación alfanumérica con relleno de espacios.
133- `CobFile` — un fichero «line sequential»: `open_input` carga las
134  líneas a memoria, `open_output` acumula, `read`/`write` operan línea
135  a línea, `close` vuelca a disco lo escrito.
136- Reexporta `Decimal`/`Picture`/`Rounding` de `charka-bcd` para que el
137  código generado sólo necesite `use charka_runtime::*;`.
138
139Construido **antes** que `charka-codegen` (la nota de orden del plan
140los listaba al revés): el codegen emite llamadas contra esta API, así
141que el runtime debe existir primero — y es un crate autocontenido,
142verificable sin depender del código emitido.
143
144## charka-codegen
145
146La etapa final: `generate(&Ir) -> String` produce un fuente Rust (un
147`main.rs`) que, compilado contra `charka-runtime`, ejecuta la lógica
148del programa COBOL.
149
150- Un `struct Program` con un campo por cada dato elemental (`Num` /
151  `Text`); `Program::new()` lo inicializa desde las cláusulas `VALUE`.
152- Un método `p_<párrafo>(&mut self)` por párrafo; `run()` los encadena
153  en orden (el «caer» de COBOL); `main()` construye y corre.
154- Cada `Stmt` → líneas Rust: `MOVE`→`.store`, `DISPLAY`→`println!`,
155  `COMPUTE`/aritmética → expresiones `Decimal`, `IF`→`if`, `PERFORM`→
156  llamada / `for` / `while`, `STOP RUN`→`process::exit`.
157- **Tolerante**: lo no transpilable (`Stmt::Unknown`, dato sin
158  resolver, `**`) se emite como comentario `// charka:` — el código
159  generado siempre compila.
160- **Tablas** (`OCCURS n`): un campo `OCCURS` se emite como `Vec<Num>`
161  / `Vec<Text>`; una referencia con subíndice `ELEM(I)` indexa el
162  vector (subíndice 1-based de COBOL → 0-based de Rust).
163- Verificado de punta a punta: un programa COBOL de demostración
164  transpila a Rust que compila contra `charka-runtime` y produce la
165  salida correcta.
166- E/S de ficheros «line sequential»: un campo `CobFile` por fichero;
167  `OPEN`/`CLOSE`/`READ`/`WRITE` emiten llamadas a `charka-runtime`.
168- Fuera de alcance v1: grupos como campo propio, `REDEFINES`,
169  `OCCURS` de grupo.
170
171## charka-shadow
172
173El validador: certifica que el pipeline preserva la semántica del
174COBOL original. Lo hace con una **ejecución sombra** — un intérprete
175que corre el `Ir` directamente sobre `charka-runtime`, sin compilar.
176
177- `interpret(&Ir) -> Outcome` — ejecuta el IR y captura las líneas de
178  `DISPLAY`. `run_source(&str)` corre el pipeline completo.
179- El intérprete es una segunda ruta de ejecución, independiente del
180  código que emite `charka-codegen`: si la sombra y el transpilado
181  divergieran, eso delataría un bug.
182- Tope de pasos: un bucle que no termina se corta con
183  `Halt::StepLimit` en vez de colgarse.
184- La referencia v1 es el **corpus** (`corpus/`): programas COBOL de
185  complejidad graduada con sus salidas esperadas verificadas a mano.
186  Un modo futuro, con GnuCOBOL, diferenciará contra el compilador real.
187- En el intérprete todo campo es un vector — un escalar es de longitud
188  1, una tabla `OCCURS n` de longitud `n`.
189
190## El corpus
191
192`crates/modules/charka/corpus/` — 19 programas COBOL graduados
193(`01-hola` … `19-reporte`), cada uno con su `.expected`. Ejercita el
194pipeline completo de punta a punta. Ver su `README.md`.
195
196## La CLI
197
198`crates/apps/charka/` — el binario `charka`, que envuelve el pipeline
199en cuatro comandos: `transpile` (emite Rust), `scaffold` (genera un
200crate compilable), `run` (ejecuta vía el intérprete sombra) y `check`
201(ejecuta y diferencia contra una salida esperada). Avisa de los verbos
202no transpilados.
203
204## Estado
205
206Pipeline **completo** — `charka-bcd` (22 tests), `charka-lexer` (18),
207`charka-parser` (17), `charka-ir` (30), `charka-runtime` (22),
208`charka-codegen` (26), `charka-shadow` (24) y la CLI `charka` (4)
209implementados y verdes. COBOL → Rust corre de punta a punta, validado
210contra el corpus. El crate que genera `scaffold` compila y su salida
211coincide con la del intérprete sombra — las dos rutas de ejecución
212concuerdan.
213
214Próximo hito mayor: salir del subconjunto COBOL'85 puro hacia CICS,
215SQL embebido y los dialectos IBM Enterprise; ampliar el codegen
216(grupos como campo, `REDEFINES`, `OCCURS` de grupo, ficheros
217indexados, `CALL` a subprogramas).