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