Merge pretty print refactor (squash): engine, helpers, instrumentation, prelude

Author: RafaelLopes23

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

Cargo.toml

@@ -8,3 +8,11 @@ nom = "7.0"
 approx = "0.5.1"
 once_cell = "1.10"
 indexmap = "2.2"
+
+[features]
+# Ativar contadores de instrumentação do pretty printer
+pp-profile = []
+# Habilita cache experimental para resultados de flatten (memoization estrutural)
+pp-flatten-cache = []
+# Mede duração do render do pretty printer e expõe função com métricas
+pp-timing = []

README.md

@@ -24,6 +24,7 @@ Para uma compreensão mais profunda dos componentes do projeto, consulte nossa d
 
 - **[Type Checker Module](docs/type_checker.md)** - Sistema de verificação de tipos estática que analisa expressões e declarações para garantir segurança de tipos em tempo de compilação. Implementa regras de tipagem bem definidas para todos os construtos da linguagem. *(Em desenvolvimento)*
 
+
 ## 🤝 Contribuindo
 
 Adoraríamos contar com sua contribuição! Por favor, leia nossos guias de contribuição:

docs/PRELUDE.md

@@ -0,0 +1,86 @@
+# PRELUDE
+
+> Superfície pública curada da crate. Hoje concentra utilidades do pretty printer, mas destina-se a agregar também itens estáveis de outros subsistemas (ex.: helpers de diagnóstico, construção de erros, futuras abstrações de ambiente) conforme amadureçam.
+
+## Objetivo
+Fornecer um ponto único e estável para importar construções de alto nível da linguagem/engine sem expor internals voláteis. Atualmente o foco é o pretty printer; novos módulos só ingressam quando houver estabilidade mínima e testes claros.
+
+## Escopo Incluído (Estado Atual)
+- Pretty printing:
+   - Tipos centrais: `Doc`, `ToDoc`.
+   - Construtores: `nil`, `text`, `line`, `softline`, `hardline`, `space`, `nest`, `group`, `concat`, `pretty`.
+   - Helpers: `punctuate`, `join_balanced`, `hardline_if_nonempty`, `fill`.
+   - Comentários: `line_comment`, `line_comment_ln`, `block_comment`.
+   - Instrumentação opcional (sob feature): `PrettyMetrics`, `pretty_with_metrics`.
+
+No futuro poderá incluir utilidades estáveis de:
+- Diagnostics (formatação padronizada de mensagens de erro).
+- Ambiente / runtime (builders de contexto estáveis, não mutáveis).
+- Parser simplifications (funções auxiliares neutras em relação a internals).
+
+## Explicitamente Fora do Prelude
+| Item | Motivo |
+|------|--------|
+| `flatten`, `best`, `fits` | Detalhes de implementação sujeitos a refactor. |
+| Cache (`pp-flatten-cache`) | Otimização interna; não faz parte da modelagem semântica. |
+| Contadores diretos (`pp-profile`) | Acesso indireto via `pretty_with_metrics` pode ser expandido no futuro. |
+
+## Política de Estabilidade
+1. Símbolos no prelude não serão removidos sem:
+   - Registro prévio no `REFACTORING_LOG.md` indicando deprecação.
+2. Mudanças de comportamento serão acompanhadas de testes atualizados e nota de racional.
+3. Novos símbolos entram somente após:
+   - Terem ao menos 1–2 testes cobrindo caso simples e limite.
+   - Não serem marcados como experimentais.
+
+## Quando Usar
+- Em testes ou exemplos que apenas constroem Docs ou mensagens.
+- Em código de geração de relatórios/diagnósticos (quando forem adicionados).
+- Em futuras camadas de codegen.
+
+## Quando Evitar
+- Ao modificar o próprio engine (`pretty_print.rs`) ou internals de futuros módulos.
+- Ao experimentar combinadores / APIs ainda instáveis (importar direto facilita evolução).
+- Se precisar de acesso deliberado a detalhes internos para refactor.
+
+## Processo para Adicionar Algo
+1. Implementar função/estrutura em módulo interno.
+2. Adicionar testes (happy path + edge mínimo).
+3. Registrar racional / estabilidade em `REFACTORING_LOG.md` ou CHANGELOG futuro.
+4. Após *cooldown* curto (ou consenso de revisão), reexportar em commit dedicado.
+
+## Exemplos
+```rust
+use r_python::prelude::*;
+
+let doc = group(concat(text("foo"), concat(line(), text("bar"))));
+assert_eq!(pretty(80, &doc), "foo bar");
+assert_eq!(pretty(3, &doc), "foo\nbar");
+```
+
+Comentários:
+```rust
+use r_python::prelude::*;
+let c = block_comment("/*\n multi\n line \n*/");
+let rendered = pretty(40, &c);
+assert!(rendered.starts_with("/*"));
+```
+
+## Futuras Extensões Planejáveis
+- `diagnostic(doc_like)` – construção declarativa de mensagens de erro.
+- `env_prelude` (sub-módulo) – acesso somente leitura a abstrações estáveis do ambiente.
+- `parser_atoms` – tokens/atoms reutilizáveis para geração de erros ou tooling.
+
+Inclusão condicionada a: baixa chance de refactor imediato + necessidade recorrente externa.
+
+## Dúvidas:
+**Posso ignorar o prelude?** Sim, importe de `pretty_print::pretty_print` se preferir granularidade.
+
+**Isso afeta performance?** Não – é só reexport; zero custo de runtime.
+
+**Por que `flatten` não está aqui?** Evita dependência em detalhes que podem ganhar caching/pipeline diferente.
+
+**E se eu quiser algo que não está no prelude?** Importe diretamente; se virar uso recorrente e estável, vamos propor inclusão.
+
+---
+Este arquivo deve permanecer curto; detalhes históricos continuam no `REFACTORING_LOG.md`.

docs/ROBUSTEZ_PRETTY_PRINT.md

@@ -0,0 +1,132 @@
+# Robustez do Pretty Printer
+
+> Objetivo: garantir que o pretty printer seja previsível, observável e extensível antes de ampliarmos o front-end e a geração de código.
+
+Este documento complementa o `REFACTORING_LOG.md` descrevendo como e quando usar os recursos opcionais e novos combinadores do sistema de pretty printing.
+
+## Visão Geral
+O pretty printer segue abordagem algébrica (Wadler) com variantes: `Nil, Text, Line, HardLine, Nest, Concat, Group`. Otimizações e extensões introduzidas na Fase 6 visam:
+- Observabilidade (tempo, contadores)
+- Robustez estrutural (balanceamento, cache opcional)
+- Ergonomia (fill, comentários, prelude)
+
+## Combinadores Principais
+- `group(doc)`: tenta layout em uma linha; se não couber, quebra nos `Line`.
+- `nest(indent, doc)`: aplica indentação às quebras internas.
+- `line() / hardline()`: quebra suave vs obrigatória.
+- `space()`: atalho `" "`.
+- `concat(a, b)`: concatenação direta.
+- `punctuate(sep, docs)`: intercala `sep` entre elementos; adaptativo (balanceado) para listas > 8.
+- `fill(docs)`: tenta manter itens sucessivos na mesma linha antes de quebrar.
+- `hardline_if_nonempty(docs)`: adiciona `hardline` após cada doc quando há pelo menos um.
+- Comentários: `line_comment`, `line_comment_ln`, `block_comment`.
+
+## Comentários
+- `line_comment("foo")` produz `// foo` (prefixo `//` opcional na entrada é normalizado).
+- `line_comment_ln` adiciona quebra obrigatória após o comentário.
+- `block_comment`:
+  - Entrada single-line => `/* body */`.
+  - Multi-linha => formato padronizado com prefixo ` * ` e fechamento em linha separada.
+  - Linhas externas vazias são removidas; espaços à esquerda por linha normalizados.
+
+## Prelude
+Uso opcional de ergonomia. Para a lista curada de símbolos e política de estabilidade consulte `docs/PRELUDE.md`.
+Exemplo rápido:
+```
+use r_python::prelude::*;
+let doc = group(concat(text("a"), concat(line(), text("b"))));
+assert_eq!(pretty(4, &doc), "a b");
+```
+
+## Features de Instrumentação
+| Feature | Propósito | Overhead | Quando usar |
+|---------|-----------|----------|-------------|
+| `pp-profile` | Contadores (`flatten`, `fits`, grupos) | Muito baixo | Diagnóstico de regressões / tuning rápido |
+| `pp-timing` | Tempo total + métricas (struct `PrettyMetrics`) | Baixo (chamada a `Instant`) | Medir impacto de novos combinadores |
+| `pp-flatten-cache` | Memoização de `flatten(doc)` por identidade | Médio (HashMap) | Árvores grandes reutilizando subdocs |
+
+Ative combinando:
+```
+cargo test --features "pp-profile pp-timing"
+```
+
+## Estratégias Recomendadas
+1. Investigação de desempenho: ligue `pp-profile` para contagem de chamadas.
+2. Medição comparativa: adicione `pp-timing` e compare `duration_ns` antes/depois.
+3. Casos sintéticos repetitivos: experimente `pp-flatten-cache` e verifique se `flatten_calls` cai proporcionalmente.
+4. Uso cotidiano / produção: nenhuma feature para via mais enxuta.
+
+## Padrões de Uso
+- Listas grandes: use `punctuate` diretamente; o balanceamento interno evita profundidade excessiva.
+- Sequências densas heterogêneas (ex.: parâmetros de função com tamanhos variáveis): considere `fill` para melhor compactação horizontal.
+- Comentários antes de blocos: `line_comment_ln` seguido de `group(...)` do bloco garante isolamento visual.
+- Documentar módulo público: `block_comment` multi-linha antes de declarações top-level.
+
+## Limitações Atuais
+- `fill` ainda não implementa heurística de redistribuição após primeira quebra (versão incremental).
+- `block_comment` normaliza indentação em vez de preservar formato ASCII-art.
+- Sem suporte a comentários de documentação diferenciados (planejável via futura função `doc_comment`).
+
+## Possíveis Evoluções Futuras
+- Interning lazy da forma flatten dentro de `Group` (elimina HashMap externo).
+- `fill` avançado (variante com alternância espaço/quebra minimizando altura total).
+- Comentários doc vs regulares com marcação distinta.
+- Ferramenta de benchmark sintético automatizado (collect + relatório diff).
+
+## Exemplo End-to-End
+```
+use r_python::prelude::*;
+
+let params: Vec<_> = [
+    text("user_id"),
+    text("very_long_parameter_name"),
+    text("flag"),
+].into_iter().collect();
+
+let signature = group(concat(text("fn foo("), concat(fill(&params), text(")"))));
+let commented = concat(line_comment_ln("Função de exemplo"), signature);
+let out = pretty(40, &commented);
+println!("{out}");
+```
+
+## Checklist Rápido
+- Resultado inesperado flatten? Ative `pp-profile` e observe contadores.
+- Layout muito vertical? Tente `fill` em vez de `punctuate` simples.
+- Performance degradou? Compare `duration_ns` com e sem alteração.
+
+## Exemplos Práticos
+
+### 1. Instrumentação (tempo + contadores)
+Arquivo: `examples/pp_timing.rs`
+
+Somente tempo:
+```
+cargo run --release --features pp-timing --example pp_timing
+```
+Tempo + contadores:
+```
+cargo run --release --features "pp-timing pp-profile" --example pp_timing
+```
+Mostra variação de layout (larguras 120 / 40 / 15) e, quando `pp-profile` ativado, imprime `flatten=`, `fits=`, `groups=`.
+
+### 2. Comentário seguido de bloco
+```
+let seq = concat(line_comment_ln("comentário"), group(concat(text("x = 1"), concat(line(), text("y = 2")))));
+```
+
+### 3. Lista grande balanceada (> 8 elementos)
+```
+let xs: Vec<_> = (0..15).map(|i| text(format!("x{i}"))).collect();
+let doc = group(punctuate(concat(text(","), line()), &xs));
+```
+
+### 4. Fill com itens heterogêneos
+```
+let docs = vec![text("a"), text("bbbbbbbbbbbb"), text("c"), text("dd")];
+let laid = fill(&docs);
+```
+Mantém densidade à esquerda até a quebra forçada pelo item longo.
+
+
+---
+Manter este arquivo conciso e focado em operação; detalhes cronológicos continuam em `REFACTORING_LOG.md`.

examples/pp_bench.rs

@@ -0,0 +1,45 @@
+//! Benchmark sintético simples para o pretty printer.
+//! Execute com: cargo run --release --features pp-profile --example pp_bench
+
+use r_python::pretty_print::*;
+use std::rc::Rc;
+
+fn linear_chain(n: usize) -> Rc<Doc> {
+    let mut parts = Vec::with_capacity(n);
+    for i in 0..n {
+        parts.push(text(format!("item{i}")));
+    }
+    // Implementação linear (left-deep) via fold
+    let sep = concat(text(","), line());
+    let doc = parts
+        .into_iter()
+        .reduce(|acc, d| concat(acc, concat(sep.clone(), d)))
+        .unwrap();
+    group(doc)
+}
+
+fn balanced_chain(n: usize) -> Rc<Doc> {
+    let mut parts = Vec::with_capacity(n);
+    for i in 0..n {
+        parts.push(text(format!("item{i}")));
+    }
+    let sep = concat(text(","), line());
+    group(join_balanced(sep, &parts))
+}
+
+fn main() {
+    let sizes = [50, 100, 200, 400, 800];
+    for &n in &sizes {
+        for variant in ["linear", "balanced"] {
+            let doc = match variant {
+                "linear" => linear_chain(n),
+                _ => balanced_chain(n),
+            };
+            let rendered = pretty(80, &doc);
+            // Consumir output para evitar otimização
+            assert!(rendered.len() > 0);
+            #[cfg(feature = "pp-profile")]
+            println!("n={n} variant={variant} {}", pp_profile_report());
+        }
+    }
+}

examples/pp_timing.rs

@@ -0,0 +1,48 @@
+//! Exemplo de instrumentação com `pp-timing` (+ opcional `pp-profile`).
+//! Execute com:
+//!   cargo run --release --features "pp-timing" --example pp_timing
+//! Ou com contadores:
+//!   cargo run --release --features "pp-timing pp-profile" --example pp_timing
+
+#[cfg(feature = "pp-timing")]
+fn main() {
+    use r_python::prelude::*;
+
+    // Construímos um Doc com mistura de grupos, nest e fill para gerar alguma atividade.
+    let items: Vec<_> = (0..20)
+        .map(|i| {
+            group(concat(
+                text(format!("item{i}")),
+                concat(line(), text("valor")),
+            ))
+        })
+        .collect();
+    let filled = fill(&items);
+    let doc = group(nest(2, concat(text("lista:"), concat(line(), filled))));
+
+    // Mede em diferentes larguras para comparar decisões de quebra.
+    for &w in &[120usize, 40, 15] {
+        let metrics = pretty_with_metrics(w, &doc);
+        println!("--- width={w} ---");
+        println!("{}", metrics.output);
+        println!(
+            "len={} duration_ns={}{}",
+            metrics.rendered_len,
+            metrics.duration_ns,
+            match (
+                metrics.flatten_calls,
+                metrics.fits_calls,
+                metrics.group_decisions
+            ) {
+                (Some(f), Some(ft), Some(g)) => format!(" flatten={f} fits={ft} groups={g}"),
+                _ => String::new(),
+            }
+        );
+        println!();
+    }
+}
+
+#[cfg(not(feature = "pp-timing"))]
+fn main() {
+    eprintln!("Este exemplo requer a feature 'pp-timing'. Use: \n  cargo run --features pp-timing --example pp_timing");
+}

src/lib.rs

@@ -1,2 +1,4 @@
 pub mod ir;
 pub mod parser;
+pub mod prelude;
+pub mod pretty_print;

src/main.rs

@@ -14,6 +14,7 @@ pub mod environment;
 pub mod interpreter;
 pub mod ir;
 pub mod parser;
+pub mod pretty_print;
 pub mod type_checker;
 
 fn main() {

src/prelude.rs

@@ -0,0 +1,13 @@
+//! Prelude estável de construção de documentos. Detalhes completos em `docs/PRELUDE.md`.
+//! Inclui apenas superfície considerada estável; internals ficam fora.
+
+pub use crate::pretty_print::pretty_print::{
+    block_comment, concat, fill, group, hardline, hardline_if_nonempty, join_balanced, line,
+    line as softline, line_comment, line_comment_ln, nest, nil, pretty, punctuate, space, text,
+    Doc, ToDoc,
+};
+
+#[cfg(feature = "pp-timing")]
+pub use crate::pretty_print::pretty_print::{pretty_with_metrics, PrettyMetrics};
+
+// Fora do prelude: flatten, best, fits, caches/profile diretos.