brahman/docs/changelog/charka.md

Changelog — charka

Transpilador COBOL → Rust. El módulo más grande del ecosistema (Fase D del plan macro) — el parser COBOL completo es un esfuerzo multi-mes.

feat(charka): EVALUATE — el case de COBOL

EVALUATE atraviesa el pipeline entero — antes el parser lo guardaba crudo como Stmt::Unknown.

• IR: Stmt::Evaluate { subject, whens, other } con WhenBranch { values, body }. Varios WHEN apilados comparten cuerpo; WHEN OTHER es el caso por defecto.
• Parser: EVALUATE subject WHEN v1 WHEN v2 ... [WHEN OTHER ...] END-EVALUATE.
• Codegen: lo baja a una cadena if / else if / else — una rama se elige si el sujeto es igual a alguno de sus valores; sin caída.
• Shadow: el intérprete evalúa el sujeto y ejecuta la primera rama cuyos valores casen, o el WHEN OTHER.
• Corpus: programa nuevo 09-evaluar (un EVALUATE por valor anidado en un PERFORM VARYING, con WHEN apilados y WHEN OTHER). Verificado: intérprete sombra y crate compilado dan la misma salida.
• Alcance v1: EVALUATE por igualdad de valor; no la forma EVALUATE TRUE con condiciones ni los rangos THRU.

feat(charka): PERFORM VARYING — el bucle con variable de control

El bucle más usado de COBOL, que antes el parser degradaba a un PERFORM vacío. Ahora atraviesa el pipeline entero.

• IR: PerformControl::Varying { var, from, by, until }.
• Parser: reconoce PERFORM VARYING var FROM x BY y UNTIL cond en línea (END-PERFORM) y fuera de línea (PERFORM párrafo VARYING …).
• Codegen: emite var = from; while !(until) { cuerpo; var += by; }.
• Shadow: el intérprete inicializa la variable, evalúa la condición antes de cada vuelta e incrementa al final.
• Corpus: programa nuevo 08-varying (suma 1..10 con PERFORM VARYING). Verificado: el intérprete sombra y el crate compilado por scaffold dan ambos SUMA 1 A 10 = 00055.

feat(charka): CLI del transpilador — transpile / scaffold / run / check

App nueva crates/apps/charka — el binario charka, que vuelve usable el pipeline desde la terminal. Cuatro comandos:

• transpile <in.cob> [-o out.rs] — emite el código Rust (a un archivo o a la salida estándar).
• scaffold <in.cob> -o <dir> — genera un crate Rust completo (Cargo.toml + src/main.rs) que depende de charka-runtime y compila tal cual.
• run <in.cob> — ejecuta el programa con el intérprete sombra y muestra su salida, sin compilar nada.
• check <in.cob> -e <esperado> — ejecuta y diferencia la salida contra un archivo esperado; reporta las líneas que difieren.

Avisa de los verbos COBOL que aún no se transpilan. Verificado de punta a punta contra el corpus: scaffold de 06-nomina genera un crate que compila y produce la misma salida que el intérprete sombra — las dos rutas de ejecución concuerdan. 4 tests; fmt + clippy limpios.

feat(charka-shadow): validador en sombra + corpus COBOL

Crate nuevo crates/modules/charka/charka-shadow y un corpus de prueba crates/modules/charka/corpus/ — el pipeline COBOL→Rust queda completo y validado de punta a punta.

• charka-shadow certifica que el transpilador preserva la semántica del COBOL original con una ejecución sombra: un intérprete que corre el Ir directamente sobre charka-runtime, sin compilar nada. Es una segunda ruta de ejecución, independiente del código que emite charka-codegen.
• interpret(&Ir) -> Outcome ejecuta el IR y captura las líneas de DISPLAY; run_source(&str) corre el pipeline completo (lexer → parser → IR → intérprete).
• Tope de pasos (Halt::StepLimit): un bucle que no termina se corta en vez de colgar la ejecución.
• Corpus: 7 programas COBOL de complejidad graduada — 01-hola (un DISPLAY), 02-aritmetica (ADD/SUBTRACT/MULTIPLY), 03-condicional (IF/ELSE), 04-bucle (PERFORM TIMES), 05-factorial (PERFORM UNTIL), 06-nomina (grupos, COMPUTE con paréntesis, ROUNDED, V99), 07-clasificar (IF anidado, AND). Cada uno con su .expected verificada a mano.
• 11 tests: los 7 programas del corpus + fuente vacío, STOP RUN, corte por tope de pasos y propagación de error de léxico.

feat(charka-codegen): emisión de Rust desde el IR

Crate nuevo crates/modules/charka/charka-codegen — la etapa final del pipeline. generate(&Ir) -> String produce un fuente Rust (un main.rs) que, compilado contra charka-runtime, ejecuta la lógica del programa COBOL.

• Un struct Program con un campo por cada dato elemental — Num para los numéricos, Text para los alfanuméricos; Program::new() los inicializa desde sus cláusulas VALUE.
• Un método p_<párrafo>(&mut self) por cada párrafo del PROCEDURE; run() los encadena en orden (el «caer» de COBOL); main() construye el Program y lo corre.
• Cada Stmt → código Rust: MOVE→.store/.fill, DISPLAY→println!, COMPUTE y la aritmética → expresiones Decimal, IF→if/else, PERFORM→ llamada de método / for / while, GO TO→ llamada + return, STOP RUN→process::exit.
• Tolerante: lo no transpilable (Stmt::Unknown, un dato sin resolver, el operador **) se emite como comentario // charka:; el código generado siempre compila.
• Saneado de identificadores COBOL→Rust (incl. choques con keywords).
• Verificado de punta a punta: un programa COBOL de demostración transpila a Rust que compila contra charka-runtime y produce la salida esperada (COMPUTE, IF, PERFORM, DISPLAY).
• 14 tests del fuente emitido; fuera de alcance v1: grupos como campo, REDEFINES, OCCURS, PERFORM ... THRU como rango, E/S.

feat(charka-runtime): soporte de ejecución — campos Num y Text

Crate nuevo crates/modules/charka/charka-runtime — el soporte que los programas COBOL transpilados enlazan. charka-codegen no emitirá Rust autónomo: emitirá Rust que llama a esta biblioteca.

• Num — campo numérico (PIC 9(5)V99): un Decimal conformado a su Picture. store trunca a la escala declarada; store_rounded redondea; al desbordar la parte entera conserva los dígitos de bajo orden (el ON SIZE ERROR de COBOL sin cláusula). display da los dígitos con relleno de ceros y signo si corresponde.
• Text — campo alfanumérico (PIC X(n)) de longitud fija: store justifica a la izquierda y rellena con espacios o trunca; fill mueve las constantes figurativas (SPACES, ZEROS).
• cobol_text_cmp — comparación alfanumérica que rellena el más corto con espacios.
• Reexporta Decimal/Picture/Rounding de charka-bcd.
• Construido antes que charka-codegen (la nota de orden del plan los listaba al revés): el codegen emite contra esta API, así que el runtime debe existir primero — y se verifica solo, sin el codegen.
• 17 tests: campo en cero, VALUE inicial, truncado y redondeo, desbordamiento que conserva bajo orden, magnitud sin signo y signo con signo, justificación y relleno de texto, fill, comparación.

feat(charka-ir): representación intermedia — statements tipados

Crate nuevo crates/modules/charka/charka-ir — la tercera etapa del pipeline: Program → Ir. El PROCEDURE division pasa de sentencias con tokens crudos a un árbol de instrucciones tipadas.

• lower(&Program) -> Ir — total y tolerante: nunca falla.
• Ir { program_id, data, procedures }. El modelo de datos (la DATA division) pasa tal cual — sirve de tabla de símbolos.
• Stmt cubre MOVE, DISPLAY, ACCEPT, COMPUTE, ADD, SUBTRACT, MULTIPLY, DIVIDE, IF/ELSE/END-IF, PERFORM (fuera de línea, en línea, TIMES, UNTIL), GO TO, STOP RUN, GOBACK, EXIT, CONTINUE.
• Expresiones de COMPUTE con precedencia y paréntesis (+ - < * / < ** asociativo a derecha). Condiciones de IF/UNTIL con comparadores en forma símbolo (= < > <= >= <>) o palabra (EQUAL TO, GREATER THAN...), AND/OR/NOT y nombres de condición (datos de nivel 88).
• COBOL no termina los statements con un símbolo: el parser delimita las listas de operandos con palabras "frontera" (verbos, terminadores END-*/ELSE, conectores TO/GIVING/BY...).
• Un verbo no soportado se conserva como Stmt::Unknown { verb, tokens } — el lowering nunca aborta.
• Fuera de alcance v1: EVALUATE, STRING/UNSTRING, E/S de ficheros, PERFORM VARYING, CICS, SQL embebido.
• 17 tests: MOVE simple y multi-destino, DISPLAY con figurativas, precedencia de COMPUTE, flag ROUNDED, ADD in-place vs GIVING, SUBTRACT, DIVIDE BY/INTO, IF/ELSE, condiciones con AND, nombre de condición, PERFORM párrafo/TIMES/UNTIL en línea, varios statements en una sentencia, verbo desconocido, programa completo.

feat(charka-parser): parser COBOL'85 → AST

Crate nuevo crates/modules/charka/charka-parser — la segunda etapa del pipeline: Vec<Token> → Program (AST). Alcance v1: el esqueleto del programa.

• parse(&[Token]) -> Result<Program, ParseError>. El AST: Program (program_id, data, paragraphs), DataItem, Paragraph, Sentence.
• Particiona el flujo de tokens en las cuatro divisiones por sus encabezados (X DIVISION); de la IDENTIFICATION extrae el PROGRAM-ID.
• DATA division → árbol de DataItem: número de nivel, nombre, cláusula PICTURE reensamblada (S9 ( 5 ) V99 → S9(5)V99) y VALUE. Anida por número de nivel — 01 y 77 son raíces, 88 cuelga del ítem precedente.
• PROCEDURE division → Vec<Paragraph>, cada párrafo con sus Sentence (tokens crudos; sin parseo a nivel de statement, eso es charka-ir). Las sentencias previas al primer encabezado van a un párrafo implícito de nombre "".
• Parser tolerante: salta encabezados de SECTION, entradas FD/SD y cláusulas de datos que no sean PICTURE/VALUE. ParseError sólo ante un número de nivel inválido o un dato sin nombre.
• 15 tests: PROGRAM-ID (forma larga y ID corta), ítems planos y anidados, reensamblado de PICTURE, variantes de VALUE, niveles 88, FILLER, párrafos y párrafo implícito, encabezado de sección, programa completo de punta a punta, nivel inválido.

feat(charka-lexer): tokenizador de COBOL

Crate nuevo crates/modules/charka/charka-lexer — la primera etapa del pipeline del transpilador: texto COBOL → secuencia de Token.

• Lexer deliberadamente tonto: no conoce keywords ni la cláusula PICTURE; emite Word para todo identificador y deja la clasificación al parser.
• Tokens: Word (palabras COBOL con guiones internos), Number (literal sin signo), String (comillas dobladas colapsadas), Period (el . terminador), Symbol (paréntesis, separadores y operadores + - * / ** = < > <= >= <>).
• Dos formatos de fuente: fijo (la tarjeta de 80 columnas — cols 1-6 secuencia, 7 indicadora, 8-72 código, 73-80 identificación) y libre. Comentarios por la columna indicadora (*//) o por * inicial en formato libre.
• Cada Token lleva línea y columna 1-based; LexError tipado (literal sin cerrar, carácter inesperado).
• Limitación v1 documentada: no soporta continuación de literales entre líneas (indicador -). Subconjunto COBOL'85, el hito intermedio.
• 17 tests: sentencias, palabras con guiones, literales y comillas dobladas, números vs terminador, operadores, ambos formatos, tracking de posición, errores.

feat(charka-bcd): aritmética decimal con semántica COBOL

(Pre-existente.) Picture + Decimal de punto fijo exacto — ver el SDD del módulo. 22 tests.