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: Vec<DataItem>, procedures: Vec<Procedure> }`.
79  El modelo de datos pasa tal cual (sirve de tabla de símbolos).
80- `Procedure { name, body: Vec<Stmt> }`. `Stmt` cubre `Move`,
81  `Display`, `Accept`, `Compute`, `Add`/`Subtract`/`Multiply`/`Divide`,
82  `If`, `Perform`, `GoTo`, `StopRun`, `Goback`, `Exit`, `Continue`.
83- `Expr` — expresiones aritméticas con precedencia y paréntesis (Pratt:
84  `+ -` < `* /` < `**` der.). `Cond` — comparaciones (símbolo o forma
85  palabra) unidas por `AND`/`OR`/`NOT`, más nombres de condición (88).
86- Un verbo no soportado se conserva como `Stmt::Unknown { verb,
87  tokens }` — el lowering jamás aborta.
88- COBOL no separa statements con un símbolo: cada uno corta donde
89  empieza el verbo del siguiente. El parser usa palabras "frontera"
90  (verbos + terminadores `END-*`/`ELSE` + conectores `TO`/`GIVING`...)
91  para delimitar listas de operandos.
92- `PERFORM` cubre las cuatro formas: párrafo / en línea, `n TIMES`,
93  `UNTIL cond` y `VARYING var FROM x BY y UNTIL cond`.
94- Fuera de alcance v1: `EVALUATE`, `STRING`/`UNSTRING`, E/S de
95  ficheros, CICS, SQL embebido.
96
97## charka-runtime
98
99El soporte de ejecución: lo que `charka-codegen` emite es Rust que
100enlaza contra este crate. Da a un programa transpilado la semántica de
101COBOL en tiempo de ejecución.
102
103- `Num` — campo numérico (`PIC 9(5)V99`): un `Decimal` conformado a su
104  `Picture`. `store`/`store_rounded` truncan o redondean a la escala
105  declarada; al desbordar conservan los dígitos de bajo orden (el
106  `ON SIZE ERROR` sin cláusula). `display` da los dígitos con relleno
107  de ceros.
108- `Text` — campo alfanumérico (`PIC X(20)`) de longitud fija: `store`
109  justifica a la izquierda y rellena/trunca; `fill` mueve figurativas
110  (`SPACES`, `ZEROS`).
111- `cobol_text_cmp` — comparación alfanumérica con relleno de espacios.
112- Reexporta `Decimal`/`Picture`/`Rounding` de `charka-bcd` para que el
113  código generado sólo necesite `use charka_runtime::*;`.
114
115Construido **antes** que `charka-codegen` (la nota de orden del plan
116los listaba al revés): el codegen emite llamadas contra esta API, así
117que el runtime debe existir primero — y es un crate autocontenido,
118verificable sin depender del código emitido.
119
120## charka-codegen
121
122La etapa final: `generate(&Ir) -> String` produce un fuente Rust (un
123`main.rs`) que, compilado contra `charka-runtime`, ejecuta la lógica
124del programa COBOL.
125
126- Un `struct Program` con un campo por cada dato elemental (`Num` /
127  `Text`); `Program::new()` lo inicializa desde las cláusulas `VALUE`.
128- Un método `p_<párrafo>(&mut self)` por párrafo; `run()` los encadena
129  en orden (el «caer» de COBOL); `main()` construye y corre.
130- Cada `Stmt` → líneas Rust: `MOVE`→`.store`, `DISPLAY`→`println!`,
131  `COMPUTE`/aritmética → expresiones `Decimal`, `IF`→`if`, `PERFORM`→
132  llamada / `for` / `while`, `STOP RUN`→`process::exit`.
133- **Tolerante**: lo no transpilable (`Stmt::Unknown`, dato sin
134  resolver, `**`) se emite como comentario `// charka:` — el código
135  generado siempre compila.
136- Verificado de punta a punta: un programa COBOL de demostración
137  transpila a Rust que compila contra `charka-runtime` y produce la
138  salida correcta.
139- Fuera de alcance v1: grupos como campo propio, `REDEFINES`,
140  `OCCURS`/tablas, `PERFORM ... THRU` como rango, E/S de ficheros.
141
142## charka-shadow
143
144El validador: certifica que el pipeline preserva la semántica del
145COBOL original. Lo hace con una **ejecución sombra** — un intérprete
146que corre el `Ir` directamente sobre `charka-runtime`, sin compilar.
147
148- `interpret(&Ir) -> Outcome` — ejecuta el IR y captura las líneas de
149  `DISPLAY`. `run_source(&str)` corre el pipeline completo.
150- El intérprete es una segunda ruta de ejecución, independiente del
151  código que emite `charka-codegen`: si la sombra y el transpilado
152  divergieran, eso delataría un bug.
153- Tope de pasos: un bucle que no termina se corta con
154  `Halt::StepLimit` en vez de colgarse.
155- La referencia v1 es el **corpus** (`corpus/`): 7 programas COBOL de
156  complejidad graduada con sus salidas esperadas verificadas a mano.
157  Un modo futuro, con GnuCOBOL, diferenciará contra el compilador real.
158
159## El corpus
160
161`crates/modules/charka/corpus/` — 7 programas COBOL graduados
162(`01-hola` … `07-clasificar`), cada uno con su `.expected`. Ejercita
163el pipeline completo de punta a punta. Ver su `README.md`.
164
165## La CLI
166
167`crates/apps/charka/` — el binario `charka`, que envuelve el pipeline
168en cuatro comandos: `transpile` (emite Rust), `scaffold` (genera un
169crate compilable), `run` (ejecuta vía el intérprete sombra) y `check`
170(ejecuta y diferencia contra una salida esperada). Avisa de los verbos
171no transpilados.
172
173## Estado
174
175Pipeline **completo** — `charka-bcd` (22 tests), `charka-lexer` (17),
176`charka-parser` (15), `charka-ir` (17), `charka-runtime` (17),
177`charka-codegen` (14), `charka-shadow` (11) y la CLI `charka` (4)
178implementados y verdes. COBOL → Rust corre de punta a punta, validado
179contra el corpus. El crate que genera `scaffold` compila y su salida
180coincide con la del intérprete sombra — las dos rutas de ejecución
181concuerdan.
182
183Próximo hito mayor: salir del subconjunto COBOL'85 puro hacia CICS,
184SQL embebido y los dialectos IBM Enterprise; ampliar el codegen
185(grupos, `REDEFINES`, `OCCURS`/tablas, E/S de ficheros).