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