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
17## charka-bcd
18
19COBOL no calcula en binario flotante: opera sobre campos decimales de
20precisión fija (`PIC S9(5)V99`). Reproducir un programa COBOL exige
21reproducir esa aritmética dígito a dígito.
22
23- `Picture` — parsea la cláusula PICTURE numérica (`9`, `V`, `S`, `9(n)`).
24- `Decimal` — punto fijo exacto (`mantissa: i128` + `scale`); suma, resta
25  y producto exactos; división con escala de resultado fija; redondeo
26  `Truncate`/`HalfUp`; `coerce` a un `Picture` con detección de
27  desbordamiento.
28- Determinista, sin dependencias de plataforma — mismo programa, mismos
29  dígitos, en cualquier máquina.
30
31## charka-lexer
32
33Primera etapa del pipeline: texto COBOL → secuencia de `Token`.
34
35- **Lexer tonto**: no conoce keywords ni la cláusula `PICTURE` — emite
36  `Word` para todo identificador; la clasificación es del parser.
37- Tokens: `Word` (con guiones internos, `WORKING-STORAGE`), `Number`
38  (sin signo), `String` (comillas dobladas colapsadas), `Period`,
39  `Symbol` (`( ) , ; :` y operadores `+ - * / ** = < > <= >= <>`).
40- Dos formatos: **fijo** (cols 1-6 secuencia, 7 indicadora, 8-72
41  código, 73-80 id) y **libre**. Comentarios por col 7 (`*`/`/`) o `*`
42  inicial en formato libre.
43- Cada token lleva línea/columna 1-based. `LexError` tipado.
44- Limitación v1: sin continuación de literales entre líneas
45  (indicador `-`).
46
47## charka-parser
48
49Segunda etapa: tokens → AST. Alcance v1 — el **esqueleto del programa**.
50
51- `parse(&[Token]) -> Result<Program, ParseError>`.
52- `Program { program_id, data: Vec<DataItem>, paragraphs: Vec<Paragraph> }`.
53- **DATA division** → árbol de `DataItem` (`level`, `name`, `picture`,
54  `value`, `children`). Reensambla la cláusula `PICTURE` desde sus
55  tokens (`S9` `(` `5` `)` `V99` → `S9(5)V99`); anida por número de
56  nivel (01 y 77 son raíces; 88 cuelga del ítem precedente).
57- **PROCEDURE division** → `Vec<Paragraph>`, cada `Paragraph` con sus
58  `Sentence` (tokens crudos — sin parseo a nivel de statement). Las
59  sentencias previas al primer encabezado van a un párrafo implícito
60  de nombre "".
61- Tolerante: salta encabezados de `SECTION`, entradas `FD`/`SD` y
62  cláusulas de datos que no sean `PICTURE`/`VALUE`. `ParseError` sólo
63  ante nivel inválido o dato sin nombre.
64- Limitación v1: no parsea statements, ni la ENVIRONMENT division, ni
65  CICS / SQL embebido / dialectos IBM.
66
67## Estado
68
69`charka-bcd` (22 tests), `charka-lexer` (17 tests) y `charka-parser`
70(15 tests) implementados y verdes. **Pendiente** — el resto del
71transpilador (Fase D del plan macro):
72
73| crate pendiente   | rol                                                  |
74| ----------------- | ---------------------------------------------------- |
75| `charka-ir`       | representación intermedia (parseo de statements)     |
76| `charka-codegen`  | emisión de Rust                                      |
77| `charka-shadow`   | validador en sombra (original vs transpilado)        |
78| `charka-runtime`  | runtime determinista (sobre `charka-bcd`)            |
79
80Hito intermedio sugerido: subconjunto COBOL'85 puro antes de CICS/SQL.