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
18## charka-bcd
19
20COBOL no calcula en binario flotante: opera sobre campos decimales de
21precisión fija (`PIC S9(5)V99`). Reproducir un programa COBOL exige
22reproducir esa aritmética dígito a dígito.
23
24- `Picture` — parsea la cláusula PICTURE numérica (`9`, `V`, `S`, `9(n)`).
25- `Decimal` — punto fijo exacto (`mantissa: i128` + `scale`); suma, resta
26  y producto exactos; división con escala de resultado fija; redondeo
27  `Truncate`/`HalfUp`; `coerce` a un `Picture` con detección de
28  desbordamiento.
29- Determinista, sin dependencias de plataforma — mismo programa, mismos
30  dígitos, en cualquier máquina.
31
32## charka-lexer
33
34Primera etapa del pipeline: texto COBOL → secuencia de `Token`.
35
36- **Lexer tonto**: no conoce keywords ni la cláusula `PICTURE` — emite
37  `Word` para todo identificador; la clasificación es del parser.
38- Tokens: `Word` (con guiones internos, `WORKING-STORAGE`), `Number`
39  (sin signo), `String` (comillas dobladas colapsadas), `Period`,
40  `Symbol` (`( ) , ; :` y operadores `+ - * / ** = < > <= >= <>`).
41- Dos formatos: **fijo** (cols 1-6 secuencia, 7 indicadora, 8-72
42  código, 73-80 id) y **libre**. Comentarios por col 7 (`*`/`/`) o `*`
43  inicial en formato libre.
44- Cada token lleva línea/columna 1-based. `LexError` tipado.
45- Limitación v1: sin continuación de literales entre líneas
46  (indicador `-`).
47
48## charka-parser
49
50Segunda etapa: tokens → AST. Alcance v1 — el **esqueleto del programa**.
51
52- `parse(&[Token]) -> Result<Program, ParseError>`.
53- `Program { program_id, data: Vec<DataItem>, paragraphs: Vec<Paragraph> }`.
54- **DATA division** → árbol de `DataItem` (`level`, `name`, `picture`,
55  `value`, `children`). Reensambla la cláusula `PICTURE` desde sus
56  tokens (`S9` `(` `5` `)` `V99` → `S9(5)V99`); anida por número de
57  nivel (01 y 77 son raíces; 88 cuelga del ítem precedente).
58- **PROCEDURE division** → `Vec<Paragraph>`, cada `Paragraph` con sus
59  `Sentence` (tokens crudos — sin parseo a nivel de statement). Las
60  sentencias previas al primer encabezado van a un párrafo implícito
61  de nombre "".
62- Tolerante: salta encabezados de `SECTION`, entradas `FD`/`SD` y
63  cláusulas de datos que no sean `PICTURE`/`VALUE`. `ParseError` sólo
64  ante nivel inválido o dato sin nombre.
65- Limitación v1: no parsea statements, ni la ENVIRONMENT division, ni
66  CICS / SQL embebido / dialectos IBM.
67
68## charka-ir
69
70Tercera etapa: `Program` → `Ir`. Aquí se parsea cada `Sentence` cruda
71(tokens) a statements tipados — el PROCEDURE division pasa de tokens a
72árbol de instrucciones.
73
74- `lower(&Program) -> Ir` — **total y tolerante**, nunca falla.
75- `Ir { program_id, data: Vec<DataItem>, procedures: Vec<Procedure> }`.
76  El modelo de datos pasa tal cual (sirve de tabla de símbolos).
77- `Procedure { name, body: Vec<Stmt> }`. `Stmt` cubre `Move`,
78  `Display`, `Accept`, `Compute`, `Add`/`Subtract`/`Multiply`/`Divide`,
79  `If`, `Perform`, `GoTo`, `StopRun`, `Goback`, `Exit`, `Continue`.
80- `Expr` — expresiones aritméticas con precedencia y paréntesis (Pratt:
81  `+ -` < `* /` < `**` der.). `Cond` — comparaciones (símbolo o forma
82  palabra) unidas por `AND`/`OR`/`NOT`, más nombres de condición (88).
83- Un verbo no soportado se conserva como `Stmt::Unknown { verb,
84  tokens }` — el lowering jamás aborta.
85- COBOL no separa statements con un símbolo: cada uno corta donde
86  empieza el verbo del siguiente. El parser usa palabras "frontera"
87  (verbos + terminadores `END-*`/`ELSE` + conectores `TO`/`GIVING`...)
88  para delimitar listas de operandos.
89- Fuera de alcance v1: `EVALUATE`, `STRING`/`UNSTRING`, E/S de
90  ficheros, `PERFORM VARYING`, CICS, SQL embebido.
91
92## Estado
93
94`charka-bcd` (22 tests), `charka-lexer` (17 tests), `charka-parser`
95(15 tests) y `charka-ir` (17 tests) implementados y verdes.
96**Pendiente** — el resto del transpilador (Fase D del plan macro):
97
98| crate pendiente   | rol                                                  |
99| ----------------- | ---------------------------------------------------- |
100| `charka-codegen`  | emisión de Rust                                      |
101| `charka-shadow`   | validador en sombra (original vs transpilado)        |
102| `charka-runtime`  | runtime determinista (sobre `charka-bcd`)            |
103
104Hito intermedio sugerido: subconjunto COBOL'85 puro antes de CICS/SQL.