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- Fuera de alcance v1: E/S de ficheros, CICS, SQL embebido.
115
116## charka-runtime
117
118El soporte de ejecución: lo que `charka-codegen` emite es Rust que
119enlaza contra este crate. Da a un programa transpilado la semántica de
120COBOL en tiempo de ejecución.
121
122- `Num` — campo numérico (`PIC 9(5)V99`): un `Decimal` conformado a su
123  `Picture`. `store`/`store_rounded` truncan o redondean a la escala
124  declarada; al desbordar conservan los dígitos de bajo orden (el
125  `ON SIZE ERROR` sin cláusula). `display` da los dígitos con relleno
126  de ceros.
127- `Text` — campo alfanumérico (`PIC X(20)`) de longitud fija: `store`
128  justifica a la izquierda y rellena/trunca; `fill` mueve figurativas
129  (`SPACES`, `ZEROS`).
130- `cobol_text_cmp` — comparación alfanumérica con relleno de espacios.
131- Reexporta `Decimal`/`Picture`/`Rounding` de `charka-bcd` para que el
132  código generado sólo necesite `use charka_runtime::*;`.
133
134Construido **antes** que `charka-codegen` (la nota de orden del plan
135los listaba al revés): el codegen emite llamadas contra esta API, así
136que el runtime debe existir primero — y es un crate autocontenido,
137verificable sin depender del código emitido.
138
139## charka-codegen
140
141La etapa final: `generate(&Ir) -> String` produce un fuente Rust (un
142`main.rs`) que, compilado contra `charka-runtime`, ejecuta la lógica
143del programa COBOL.
144
145- Un `struct Program` con un campo por cada dato elemental (`Num` /
146  `Text`); `Program::new()` lo inicializa desde las cláusulas `VALUE`.
147- Un método `p_<párrafo>(&mut self)` por párrafo; `run()` los encadena
148  en orden (el «caer» de COBOL); `main()` construye y corre.
149- Cada `Stmt` → líneas Rust: `MOVE`→`.store`, `DISPLAY`→`println!`,
150  `COMPUTE`/aritmética → expresiones `Decimal`, `IF`→`if`, `PERFORM`→
151  llamada / `for` / `while`, `STOP RUN`→`process::exit`.
152- **Tolerante**: lo no transpilable (`Stmt::Unknown`, dato sin
153  resolver, `**`) se emite como comentario `// charka:` — el código
154  generado siempre compila.
155- **Tablas** (`OCCURS n`): un campo `OCCURS` se emite como `Vec<Num>`
156  / `Vec<Text>`; una referencia con subíndice `ELEM(I)` indexa el
157  vector (subíndice 1-based de COBOL → 0-based de Rust).
158- Verificado de punta a punta: un programa COBOL de demostración
159  transpila a Rust que compila contra `charka-runtime` y produce la
160  salida correcta.
161- Fuera de alcance v1: grupos como campo propio, `REDEFINES`,
162  `OCCURS` de grupo, E/S de ficheros.
163
164## charka-shadow
165
166El validador: certifica que el pipeline preserva la semántica del
167COBOL original. Lo hace con una **ejecución sombra** — un intérprete
168que corre el `Ir` directamente sobre `charka-runtime`, sin compilar.
169
170- `interpret(&Ir) -> Outcome` — ejecuta el IR y captura las líneas de
171  `DISPLAY`. `run_source(&str)` corre el pipeline completo.
172- El intérprete es una segunda ruta de ejecución, independiente del
173  código que emite `charka-codegen`: si la sombra y el transpilado
174  divergieran, eso delataría un bug.
175- Tope de pasos: un bucle que no termina se corta con
176  `Halt::StepLimit` en vez de colgarse.
177- La referencia v1 es el **corpus** (`corpus/`): programas COBOL de
178  complejidad graduada con sus salidas esperadas verificadas a mano.
179  Un modo futuro, con GnuCOBOL, diferenciará contra el compilador real.
180- En el intérprete todo campo es un vector — un escalar es de longitud
181  1, una tabla `OCCURS n` de longitud `n`.
182
183## El corpus
184
185`crates/modules/charka/corpus/` — 17 programas COBOL graduados
186(`01-hola` … `17-rangopar`), cada uno con su `.expected`. Ejercita el
187pipeline completo de punta a punta. Ver su `README.md`.
188
189## La CLI
190
191`crates/apps/charka/` — el binario `charka`, que envuelve el pipeline
192en cuatro comandos: `transpile` (emite Rust), `scaffold` (genera un
193crate compilable), `run` (ejecuta vía el intérprete sombra) y `check`
194(ejecuta y diferencia contra una salida esperada). Avisa de los verbos
195no transpilados.
196
197## Estado
198
199Pipeline **completo** — `charka-bcd` (22 tests), `charka-lexer` (17),
200`charka-parser` (15), `charka-ir` (17), `charka-runtime` (17),
201`charka-codegen` (14), `charka-shadow` (11) y la CLI `charka` (4)
202implementados y verdes. COBOL → Rust corre de punta a punta, validado
203contra el corpus. El crate que genera `scaffold` compila y su salida
204coincide con la del intérprete sombra — las dos rutas de ejecución
205concuerdan.
206
207Próximo hito mayor: salir del subconjunto COBOL'85 puro hacia CICS,
208SQL embebido y los dialectos IBM Enterprise; ampliar el codegen
209(grupos como campo, `REDEFINES`, `OCCURS` de grupo, E/S de ficheros).