Relatório de auditoria abrangente e reconstrução documental de Joss Before: Contribua para Joss. Depois: Auditoria técnica 2026. Índice geral: Documentação Joss. — ## 1. Introdução e objetivo da auditoria Este relatório documenta a auditoria exaustiva e a reconstrução profunda da documentação da linguagem de programação Joss, realizada em 5 de setembro de 2026. O princípio orientador absoluto deste trabalho foi: > O código-fonte é a única fonte da verdade. Toda a documentação anterior foi contrastada com o comportamento real do analisador léxico (pkg/parser/lexer.go), o Pratt analisador (pkg/parser), a árvore de sintaxe abstrata AST (pkg/parser/ast*.go), o sistema de tipo e inferência (pkg/typesystem), o analisador semântico (pkg/analyzer), o avaliador Go e execução motor (pkg/core), as classes e funções nativas registradas e o conjunto de testes automatizados. — ## 2. Diagnóstico do estado inicial e dívida documental No início da auditoria, detectou-se que a documentação existente apresentava uma lacuna significativa em relação às reais capacidades do código: ### A. Lacuna pedagógica para iniciantes - A documentação foi escrita quase exclusivamente como uma referência técnica compacta para pessoas que já dominam outras linguagens ou conhecem o jargão do compilador. - Não houve explicações sobre conceitos fundamentais, como o que é uma variável, por que $ é usado, a diferença entre imprimir na tela (print) e retornar um valor (return) ou o que memória e escopo (scope) representam. - Conceitos avançados como async, await ou channel foram apresentados através de fragmentos de código sem explicar previamente a diferença entre sincronia, assincronia e simultaneidade. ### B. Recursos implementados no código que estavam não documentados ou subdocumentados Durante a inspeção linha por linha do código-fonte, foram descobertos comportamentos e sintaxe que foram implementados, mas ausentes nos guias: 1. O operador Pipeline (|>): - Implementado em pkg/parser/parser.go (precedência PIPE_OP), pkg/parser/parser_expressions.go e avaliado em pkg/core/evaluator_infix.go. - Permite compor funções da esquerda para a direita: " ada " |> trim |> strtoupper. Se a função exigir mais argumentos, o valor da esquerda será injetado como primeiro parâmetro. Estava ausente nos tutoriais. 2. O operador Elvis (?:): - Implementado no analisador ternário (parseTernaryExpression) e avaliado em evaluateTernary. Permite avaliar valores padrão quando a condição é verdadeira: $val = $input ?: "default". 3. O operador de coalescência nula (??): - Implementado com proteção contra erros nulos para substitutos limpos: $val = $input ?? "fallback". 4. O operador de navegação null-safe (?->): - Permite acesso a propriedades e métodos de instâncias potencialmente nulas ($user?->nombre) sem travar o programa.5. Anexar sintaxe automaticamente em arrays ($arr[] = $val): - Suportado no avaliador de atribuições (IndexExpression com índice nulo), permitindo que elementos sejam adicionados ao final naturalmente. 6. Consumo de canais simultâneos usando foreach: - executeForeach em pkg/core/executor.go verifica se o iterável é um *Channel (for item := range ch.Ch), permitindo criar padrões puros de produtor-consumidor sem chamadas manuais repetitivas para recv. 7. Estrutura do mapa de erros capturado em catch ($e): - Quando ocorre um JossError em tempo de execução, o bloco catch recebe um mapa associativo estruturado com as chaves "message", "type", "file", "line" e "error". 8. Invariância de referência bilateral (ref): - O código impõe que tanto a declaração da função quanto a chamada usem ref, requer tipos idênticos (sem estender int para float) e proíbe escapar da referência fora do quadro. ### C. Documentação desatualizada e informações incorretas removidas - Aliases removidos: Esclarecido categoricamente que integer, double, boolean, dynamic, any e list não são mais padronizados; usá-los aciona o erro JOSS-TYPE-009. - Sintaxe assíncrona obsoleta: Foi documentado que async(func() ...) foi removido e que a única sintaxe válida é o bloco async { ... }. - APIs fantasmas ou catalogadas incorretamente: Foram removidas menções a métodos não cadastrados no despachante como Http::query ou System::change_db. - Comportamento não mutante de array_pop e array_shift: Os desenvolvedores foram explicitamente alertados de que em Joss essas funções retornam o elemento sem reduzir o comprimento do array original. — ## 3. Nova arquitetura documental do projeto A documentação foi reestruturada em quatro níveis complementares para satisfazer todos os públicos sem degradar o rigor técnico:“`text
┌─────────────────────────────────────────────────────────────┐ │ 1. APRENDER JOSS (Niveles 0 al 10 - Progresivo y pedagógico) │ │ - PRIMEROS_PASOS: De cero a un programa ejecutable. │ │ - FUNDAMENTOS: Memoria, tipos primitivos y variables. │ │ - CONTROL_FLUJO: Ternarios con bloques, match y bucles. │ │ - FUNCIONES: Scope, closures, ref y pipelines. │ │ - COLECCIONES: Arrays, maps y texto Unicode. │ │ - SISTEMA_TIPOS: Inferencia, uniones y conversiones. │ │ - CLASES: POO, Init, encapsulación y herencia. │ │ - ERRORES: Fases, diagnósticos y try/catch. │ │ - CONCURRENCIA: Async, Future y canales. │ │ - PROYECTO_CONSOLA: Proyecto real con persistencia JSON. │ │ - PROYECTO_WEB: Aplicación MVC con el stack nativo. │ │ - GLOSARIO: Diccionario conceptual para principiantes. │ ├─────────────────────────────────────────────────────────────┤ │ 2. REFERENCIA TÉCNICA DEL LENGUAJE Y HERRAMIENTAS │ │ - SINTAXIS: Tokens, precedencias y operadores. │ │ - GRAMATICA: EBNF formal y correspondencia con el AST. │ │ - DIAGNOSTICOS: Catálogo completo de códigos JOSS-*. │ │ - FUNCIONES_GLOBALES: Las 121 funciones built-in. │ │ - MODULOS_NATIVOS: Clases integradas en Go. │ │ - CATALOGO_NATIVO: Catálogo sincronizado por docgen. │ │ - CLI: Referencia de comandos joss. │ │ - VSCODE_EXTENSION: LSP y tooling del editor. │ │ - ESTADO_IMPLEMENTACION: Estado real vs límites. │ ├─────────────────────────────────────────────────────────────┤ │ 3. DESARROLLO DE APLICACIONES │ │ - ESTRUCTURA_PROYECTO, CONFIGURACION, MODULOS_IMPORTS. │ │ - SERVIDOR, CONTROLADORES, MIDDLEWARE, VISTAS, ASSETS. │ │ - MODELOS, SCHEMA_BUILDER, MIGRACIONES, AUTENTICACION. │ │ - WEBSOCKETS, PLUGINS, SEO_SITEMAP. │ ├─────────────────────────────────────────────────────────────┤ │ 4. INTERNALS Y GUÍA PARA CONTRIBUIDORES │ │ - ARQUITECTURA: Pipeline del compilador y runtime Go. │ │ - CONTRIBUIR: Cómo extender sintaxis, tipos y built-ins. │ │ - AUDITORIAS Y NOVEDADES: Historial y optimizaciones. │ └─────────────────────────────────────────────────────────────┘
--- ## 4. Problemas de experiência do desenvolvedor (UX) detectados na linguagem Durante a auditoria do código-fonte e execução do teste, foram identificados os seguintes pontos onde o comportamento atual da linguagem pode ser confuso ou exigir atenção no futuro: 1. **Detecção de `break` / `continue` em ternários aninhados**: - O loop do otimizador de plano (`pkg/runtime/plan`) procura saltos diretos no AST. Se um `break` ou `continue` estiver dentro do bloco de um ternário no loop, em determinadas situações o plano não o detecta e escapa como um pânico interno ao invés de ser absorvido pelo loop. 2. **Arms de `match` que são blocos**: - Na implementação atual de `pkg/core`, um braço `match` cujo valor certo é um bloco `{ ... }` pode retornar o nó de sintaxe do bloco como um valor em vez de executar suas instruções internas, mesmo que o analisador semântico conte isso como um retorno válido. Recomenda-se usar expressões diretas nos braços de `match`. 3. **Comportamento não atômico de `GranDB::transaction`**: - `GranDB::transaction` abre uma transação SQL em Go (`tx, err := db.Begin()`), mas chamadas normais executadas dentro do fechamento do usuário usam a conexão de banco de dados padrão da instância e não o ponteiro `*sql.Tx`, portanto não garantem atomicidade completa em caso de erros no retorno de chamada. 4. **Discrepância em `array_pop` e `array_shift`**: - Desenvolvedores provenientes de PHP ou JavaScript esperam que `array_pop` remova o elemento do array original. Em Joss, ele retorna o valor, mas o array subjacente mantém seu tamanho. 5. **Assimetria de análise estática em projetos web**: - O comando `joss analyze main.joss` verifica `main.joss` e os arquivos dentro de `app/**/*.joss`. No entanto, `routes.joss` é processado somente quando você inicia o servidor HTTP usando seu próprio carregador, portanto, um erro de sintaxe em `routes.joss` só é descoberto ao executar `joss server start`. 6. **Segurança na geração de números pseudoaleatórios**: - Certas funções utilitárias nativas (como `Str::random` e o módulo TOTP) usam o pacote `math/rand` com sementes previsíveis em vez do gerador criptograficamente seguro `crypto/rand`. --- ## 5. Verificação formal e testes executados Para garantir que nenhum documento possua links quebrados, exemplos desatualizados ou inconsistências com o tempo de execução, foi executado o conjunto completo de validação: 1. **Verificação de catálogo e documentação nativa**: ```bash
go run ./tools/cataloggen --check
go run ./tools/docgen --check
- Conjunto de testes de unidade e integração:
go test ./pkg/parser ./pkg/typesystem ./pkg/analyzer ./pkg/core - Verificação e navegação de contrato (
TestDocumentationNavigationAndPublicMirroreTestDocumentationContracts): - Verificação de todos os links Markdown locais entre documentos. - Verificação de paridade byte a byte entredocs/*.mdeejemplos/Joss-Red-JosSecurity/assets/docs/*.md. - Ejecución y análisis de todos los bloques etiquetados con<!-- joss-run: ... -->,<!-- joss-check: ... -->y<!-- joss-error: ... -->. - Construção geral do repositório:
— ## 6. Conclusão Com esta reconstrução, a documentação do Joss deixa de ser um simples catálogo de sintaxe e se torna um sistema pedagógico e técnico abrangente. Ele permite que qualquer pessoa sem experiência anterior aprenda a programar do zero, passo a passo, ao mesmo tempo que fornece aos desenvolvedores experientes e colaboradores de compiladores uma referência abrangente, honesta e verificável, baseada 100% no código-fonte.go build ./...