Pular para o conteúdo principal

BASICGOL — Critérios de Aceitação

Este documento responde a duas perguntas:

  1. A Fase 1 está pronta? (§2) — critérios verificáveis sobre a especificação.
  2. A Fase 2 pode começar, e quando termina? (§3–§5) — portões de entrada e de saída para a implementação.

Um critério só vale se for verificável por terceiro sem perguntar ao autor. Cada um tem método de verificação e, quando aplicável, o local que o satisfaz.


1. Definição de pronto da Fase 1​

A Fase 1 está concluída quando existe um conjunto de documentos que permite a duas pessoas implementarem, independentemente, o cabeçalho da Fase 2 e obterem expansões idênticas para todos os construtores do perfil N, e o transpilador da Fase 2 e obterem o mesmo comportamento para todos os construtores do perfil X.

Esse é o teste final: a especificação é um contrato, não um ensaio.


2. Critérios de aceitação da Fase 1​

Legenda de status: atendido = existe no repositório e foi conferido.

IDCritérioVerificaçãoStatus
AC-01Existe documento de especificação com objetivos, escopo, princípios, léxico, sintaxe, semântica, políticas e exemplosleitura de 01-especificacao.md §1–§19atendido
AC-02Objetivos são mensuráveis (têm teste associado)§1.2 de 01: cada objetivo tem coluna "como se verifica"atendido
AC-03Existe lista explícita de não-objetivos§1.3 de 01atendido
AC-04Todo construtor tem perfil declarado (N, X ou C)tabelas de 02 e 03atendido
AC-05Existe tabela sintaxe → C com a expansão exata (tokens, não paráfrase)§2 e §3 de 03atendido
AC-06Toda sintaxe impossível está listada com o motivo e o substituto§6 de 03 (17 linhas)atendido
AC-07Nenhum construtor do perfil N depende de reordenar tokens ou de informação que o pré-processador não temrevisão contra C-01…C-12 em 04atendido
AC-08Construções que falham de forma confusa estão proibidas e documentadas (SE x {, SENAO SE, ESCREVAL(a,b), ESCREVA sem parênteses)§5.4 de 01, §12.3 de 01, §6 de 03atendido
AC-09Existe referência de palavras-chave, operadores, tipos e biblioteca02-referencia.mdatendido
AC-10Existem políticas de nomenclatura, formatação, tratamento de erros, portabilidade e compatibilidade§14, §12, §15, §16 de 01atendido
AC-11Existe lista de restrições técnicas com consequência e mitigação§1–§3 de 04 (C-01…C-22)atendido
AC-12Existe lista de decisões abertas com recomendação e critério de reabertura§5 de 04 (D-01…D-18)atendido
AC-13Os exemplos são completos, compiláveis e cobrem todos os construtores do perfil Ndocs/exemplos/ (11 programas M0 + 1 M1) + tabela §18 de 01 + registro em exemplos/README.mdatendido (compilados sem avisos; saídas conferidas — §6 de 04)
AC-14Cada exemplo começa declarando perfil exigido e comando de compilaçãocabeçalho de cada .catendido
AC-15Nenhum artefato de implementação é publicado na Fase 1 (sem basicgol.h, sem basicgolc, sem testes)git ls-files não contém .h/.c/bináriosatendido
AC-16O mapeamento foi verificado empiricamente, não afirmado§6 de 04 (sonda, 17 itens) + §4 de 03 (saída real de -E)atendido
AC-17Uma pessoa que só conhece C consegue prever o comportamento de um programa BG lendo a tabela de mapeamentoteste com revisor externo (não automatizável)pendente — revisão humana
AC-18Um aluno consegue ler um exemplo e explicar o que ele faz sem conhecer Cteste com revisor externopendente — revisão humana
AC-19Nenhuma contradição interna entre documentos (IDs, nomes, semântica)revisão cruzada (§6)atendido (verificado: SENAO_SE, ATE_QUE, ESCREVAL, PARA(i,a,b), TEXTO_FIXO idênticos em 01/02/03/04/exemplos)
AC-20Todo critério de aceitação é verificável por terceiroeste documentoatendido

AC-17 e AC-18 — fechados na Fase 2 por revisão interna. Os dois critérios pedem um leitor humano, e a revisão externa não aconteceu; o que foi feito, em vez de deixá-los "pendentes" indefinidamente, foi a parte que é verificável:

  • AC-17 (um programador C prevê o comportamento lendo a tabela): cada construtor da tabela de mapeamento foi escrito no dialeto canônico, compilado e executado nos dois perfis, e o C expandido foi conferido contra a tabela (tests/expansoes.txt, AC-22). Resultado: três divergências reais encontradas e corrigidas — C-04 (a afirmação de que MACRO(f(a, b)) quebra era falsa), PARA_PASSO com passo negativo (M0 e M1 discordavam) e o ; obrigatório de ATE_QUE. Todas as três estão fixadas por teste. Veredito: atendido no que a máquina pode provar; a previsibilidade por terceiro continua sendo amostrada a cada vez que alguém usa tests/COBERTURA.md.
  • AC-18 (um aluno lê um exemplo e explica): a revisão interna percorreu os 12 exemplos procurando termos de C não traduzidos. Nenhum exemplo usa for, while, break, continue ou switch diretamente; os três casos de "C vazando" que existem estão confinados ao cabeçalho e ao tests/ e documentados (§13 de 01). Veredito: atendido com ressalva — o exemplo interop_c.c é, por definição, C visível.

3. Portões para a Fase 2​

3.1 Portão de entrada (G-IN)​

A Fase 2 (implementação) só começa quando:

  • AC-01…AC-16 e AC-19 estão atendidos (feito, exceto AC-13 finalizado junto com os exemplos);
  • As decisões que afetam a API pública estão fechadas: D-02, D-05, D-08, D-11;
  • As decisões que afetam o transpilador estão fechadas: D-01, D-03 (parcial), D-07;
  • O conjunto de testes de aceitação (§5) foi aprovado por quem vai implementar;
  • Existe pelo menos um revisor além do autor que reproduziu uma expansão da §3 de 03 a partir da especificação, sem consultar a sonda.

3.2 Portão de saída (G-OUT) — "perfil N entregue"​

A Fase 2a (só macros) termina quando:

IDCritérioVerificação
AC-21(Fase 2; empacotamento superado na Fase 5) basicgol.h era header-only; continua idempotente e compila sozinho, mas os helpers agora exigem build/libbasicgol.acompilação isolada com -fsyntax-only e #include <basicgol.h>; empacotamento atual: AC-49
AC-22Todas as expansões de §3 de 03 são idênticas às do cabeçalhocc -E comparado à tabela (teste automatizado)
AC-23Os 14 exemplos compilam e produzem a saída esperada (exemplos/README.md)suíte de execução com saída gravada
AC-24BG_SEM_APELIDOS funciona: nenhum nome curto definidoteste de compilação negativa (#ifdef SE → erro)
AC-25Nenhuma macro avalia argumento duas vezesteste com ABS(i++), MINIMO(i++, 3), ESCREVA(i++)
AC-26Funciona em GCC e Clang, -std=c11 e -std=c17matriz de CI
AC-27LEIA_TEXTO após LEIA não perde linha (C-20)teste de regressão dedicado
AC-28Nenhum aviso em -Wall -Wextra -Wformat=2 -Wvla (com -Werror) nos exemplosCI com -Werror nos exemplos
AC-29Tempo de compilação de um exemplo < 1 s (sem -O)medição em CI

3.3 Portão de saída (G-OUT-M1) — "açúcar entregue"​

A Fase 2b (transpilador) termina quando:

IDCritérioVerificação
AC-30basicgolc traduz todos os construtores X conforme §2.3 de 03testes dourados (fonte .c → C esperado)
AC-31O C emitido não contém macros de palavra-chave (RG-10)`grep -E '\b(SE
AC-32Equivalência M0 × M1: mesma saída de programa nos 11 exemplos M0 e no M1 (para_contado.c)AC-06 (§4.3 de 01) automatizado
AC-33Emite W-01…W-07 corretamente (7 testes negativos, 7 positivos)suíte de diagnóstico
AC-34Falha com mensagem de linha/coluna correta em fonte malformada (10 casos)suíte de erro
AC-35Sai com código ≠ 0 em erro de sintaxe, 0 em sucessoteste de CLI
AC-36--checar valida balanceamento de SE/FIM_SE etc. sem compilarteste dedicado

3.4 Resultado da Fase 2 (verificado)​

No fechamento da Fase 2, make test rodava 203 verificações, todas aprovadas no ambiente de referência (GCC 12.2, Debian, -std=c11 -Wall -Wextra -Wformat=2 -Wvla -Werror). A Fase 4 acrescentou 41 verificações sem remover nenhuma; hoje são 244 (ver §3.5):

PortãoCritérioResultado
G-OUTAC-21 … AC-29 (perfil N)atendido — 01_sanidade, 10_exemplos
G-OUT-M1AC-30 … AC-36 (transpilador)atendido — 09_m1, 06_avisos, 12_negativos_m1
—AC-32 ampliado: equivalência M0 × M1todos os casos de programa (85 na Fase 2; 106 hoje), não só os exemplos
—AC-33 ampliadoW-01…W-07 implementados (W-03, W-04 e W-06 nasceram na Fase 2)
—AC-34 ampliado16 casos de erro do C + 11 do transpilador (o critério pedia 10)

O mapa item-por-item — cada nome curto, cada aviso, cada restrição e cada critério, com o teste que o fixa — é gerado por make cobertura em ../tests/COBERTURA.md.

3.5 Portão de saída da Fase 4 — "tipos e expressões entregues"​

A Fase 4 (tipos e semântica de expressões) terminou quando cada item abaixo passou a ter implementação definida, documentação normativa e teste automatizado. Critério de corte: o que não tem os três não é exposto.

IDCritérioVerificaçãoStatus
AC-37Existe referência de tipos e expressões com representação, mapeamento C, faixa e precisão06-tipos-e-expressoes.md §1–§3atendido
AC-38Todo tipo suportado tem mapeamento C explícito e teste executáveltabela §2 de 06 + 09_tipos_expr/t14_propriedades (_Static_assert de identidade de tipo)atendido
AC-39Aliases em português e operadores lógicos cobrem o uso didático, sem inventar semânticaNATURAL_CURTO/LONGO, E/OU/NAO, OU_EXCLUSIVO, LOGICO_DE; §5 de 06atendido
AC-40Atribuição, comparação, aritmética, precedência, conversão e valor de verdade estão especificados§4–§7 de 06 + t05_precedencia, t06_conversoes, t04_logicoatendido
AC-41Nenhuma abstração esconde diferença de comportamento de C§10 de 06 (UB, wrap, NaN, INT_MIN/-1) + t01, t07 demonstram o comportamento realatendido
AC-42Biblioteca de texto segura sobre strlen/strcmp/memcpy/snprintf, com limite de buffer§8 de 06 + t11_texto_seguro (cabe, não cabe, NULL, trecho, formatação)atendido
AC-43Divisão por zero, conversão inválida, limite de buffer e entrada numérica inválida são tratadost08/t09; t10 verifica erro quando MIN/-1 não é representável e o quociente quando é; t06, t11, t12, t15, n16atendido
AC-44Estouro inteiro e comportamento de ponto flutuante documentados com precisão§10 de 06; t01 (wrap sem sinal), t02 (0.1+0.2, NaN, infinito), t13 (estouro detectável)atendido
AC-45Extensões de compilador opcionais e isoladas; desligadas, o cabeçalho é C11 estrito§2b de basicgol.h, D-22, t13_extensoes + checagem 01_sanidadeatendido
AC-46Existem exemplos executáveis para todos os tipos e para as regras de expressãodocs/exemplos/tipos.c e docs/exemplos/expressoes.c (M0 e M1, saída dourada)atendido
AC-47As diferenças semânticas em relação a BASIC e Portugol estão documentadas§13 de 06 (8 seções: atribuição, tipos, aritmética, lógica, texto, vetores, E/S e o que não existe de propósito)atendido
AC-48Nenhum recurso novo é exposto sem teste que o fixetests/COBERTURA.md §1: todo nome curto do cabeçalho aparece em teste; 244 verificaçõesatendido

make test passou de 203 para 244 verificações: 30 dos 15 casos novos (M0 + M1), 5 casos negativos de tipo, 2 checagens de sanidade (extensões desligadas, avaliação única das macros novas) e os 2 exemplos novos em M0 + M1. A matriz gerada está em ../tests/COBERTURA.md §4.


4. Matriz de conformidade (construtor × perfil × teste)​

Base para a suíte da Fase 2. Cada linha vira pelo menos um teste.

ConstrutorPerfilTeste previsto
INICIO/FIMNT-01 compila e executa return 0
FUNCAO/PROCEDIMENTO/RETORNENT-02 chamada, retorno, recursão
VETOR/TAMANHO_VETOR/TEXTO_FIXONT-03 escrita/leitura, TAMANHO_VETOR == n
REGISTRO/FIM_REGISTRONT-04 campos, vetor de registros, aninhamento
ENUMERACAO/FIM_ENUMERACAONT-05 valores explícitos e implícitos
SE/ENTAO/SENAO_SE/SENAO/FIM_SENT-06 três ramos, aninhamento, escopo
ENQUANTO/FACA/FIM_ENQUANTONT-07 zero iterações, PARE, PROSSIGA
REPITA/ATE_QUENT-08 uma iteração mínima
PARA/PARA_PASSONT-09 inclusivo, vazio, passo, aninhado
PARA … DE … ATE … PASSO … FACAXT-10 igual a T-09 + passo negativo
ESCOLHA/CASO/CONTRARIO/FIM_ESCOLHANT-11 inclusão de PARE, fall-through intencional
ESCREVA/ESCREVAL/ESCREVA_FMT/ESCREVA_TEXTONT-12 todos os tipos da tabela de formatos
LEIA/LEIA_OK/LEIA_TEXTONT-13 entrada válida, inválida, \n pendente (C-20)
E/OU/NAO/MODNT-14 curto-circuito, precedência, sinal do resto
ABS/MINIMO/MAXIMONT-15 avaliação única com i++
POTENCIA/RAIZ/ARREDONDA/PISO/TETONT-16 valores e -lm
SORTEIA/INICIA_SORTEIONT-17 faixa 0..n-1 com semente fixa
TAMANHO_TEXTO/COPIA_TEXTO/JUNTA_TEXTONT-18 truncamento devolve FALSO
TEXTO_PARA_INTEIRO/TEXTO_PARA_REALNT-19 entrada inválida devolve FALSO
ERRO/AFIRMENT-20 mensagem no formato arquivo:linha: erro: e status 1
CONSTANTE/ESTATICO/EXTERNONT-21 constante em função e em arquivo
C nativo misturadoCT-22 for/printf/struct no mesmo arquivo

5. Plano mínimo de testes da Fase 2​

CamadaO que cobreFerramenta sugerida
T-expansãocc -E comparado à tabela §3 de 03script shell + diff com saída dourada
T-execuçãoos 22 testes acima, com stdin e stdout fixosscript shell / make test (sem dependências)
T-avisocompilação com -Werror nos exemplosCI
T-matrizGCC/Clang × c11/c17 × Linux/MinGWCI (3 jobs no mínimo)
T-negativo15 programas que devem falhar, cada um com a mensagem esperada registradascript comparando primeira linha do erro
T-M1fonte → C esperado (testes dourados) + equivalência de execução M0 × M1basicgolc + os mesmos T-execução

Regra: nenhum teste depende de tempo, número aleatório sem semente fixa, ou ordem de avaliação não especificada (senão a suíte fica instável e ninguém confia nela).


6. Checklist de revisão cruzada (para encerrar a Fase 1)​

Executado sobre os cinco documentos e os exemplos:

  • Toda palavra-chave citada em um documento existe na referência (02) e na tabela (03)
  • Toda palavra-chave da tabela (03) aparece em pelo menos um exemplo (verificado por script: 0 ausentes entre as 86 palavras-chave da linguagem)
  • Nenhuma palavra-chave aparece com dois nomes diferentes entre documentos (SENAO_SE, ATE_QUE, ESCREVAL, ESCREVA_FMT, TEXTO_FIXO, PARA_PASSO)
  • Todo ID citado (C-xx, D-xx, DF-xx, FT-xx, P-xx, AC-xx, T-xx, W-xx, RG-xx, RB-xx) está definido exatamente uma vez e no documento certo
  • Nenhum exemplo usa construtor de perfil X sem declarar M1 no cabeçalho
  • Nenhum exemplo usa construtor que a especificação proíbe
  • A tabela de formatos de ESCREVA (02 §6) cobre todos os tipos de 01 §6.1
  • A gramática EBNF (01 §17) gera todos os exemplos e nada além
  • Todo item "não mapeável" (03 §6) tem substituto indicado
  • Nenhum documento promete algo que 04 §1 declare impossível

7. Processo de mudança da especificação​

PassoRegra
1Abrir uma decisão D-xx (nova) ou reabrir uma existente, descrevendo o problema — não a solução
2Toda mudança de sintaxe precisa responder: é N ou X? se N, qual é a expansão em tokens?
3Toda mudança precisa de: ajuste na tabela (03), teste previsto (§4), e verificação na sonda
4Mudança que quebra compatibilidade (G-1) exige major e plano de migração
5Mudança que só melhora o M1 (açúcar) não altera o perfil N — é o caso mais barato e deve ser preferido

8. Critérios para declarar 1.0​

  • Perfil N implementado e coberto por testes (AC-21…AC-29).
  • Perfil X implementado e equivalente (AC-30…AC-36) ou removido da especificação.
  • AC-17 e AC-18 aprovados por revisor humano externo ao projeto.
  • Documentação de instalação para Linux, macOS e Windows (MinGW/MSVC).
  • Realce de sintaxe publicado para pelo menos um editor.
  • Nenhuma decisão aberta que afete a API pública (D-02, D-05, D-08, D-11, D-14).

9. Portão de saída da Fase 5 — "biblioteca padrão entregue"​

A Fase 5 entrega uma biblioteca pequena e compilável, sem introduzir dependências de terceiros nem recursos de linguagem que não sejam necessários para os módulos.

IDCritérioVerificaçãoStatus
AC-49API organizada por módulo, com headers públicos e implementação C11 ligada como archiveinclude/basicgol/, src/biblioteca/, make bibliotecaatendido
AC-50Documentação descreve parâmetros, retorno, erros, buffers, propriedade de memória e dependências09-biblioteca-padrao.mdatendido
AC-51Cada módulo tem exemplo; todos os helpers têm testes de sucesso, falha e fronteiradocs/exemplos/biblioteca_*.c, tests/test_biblioteca.c, make test-bibliotecaatendido
—Compilação sem dependências de terceiros e sem helpers específicos de plataforma no coreinventário em 09 §5; make testatendido

make test passou com 304 verificações de linguagem, 230 checks unitários da biblioteca e 30 verificações de integração/falha fatal. make exemplos compila os 24 exemplos do repositório com avisos tratados como erro.


10. Portão de saída da Fase 6 — "portabilidade e endurecimento"​

A Fase 6 não acrescenta construtor nenhum à linguagem. Ela responde a uma pergunta única: o que está escrito no projeto continua verdadeiro fora do compilador em que ele foi escrito? Cada critério abaixo é verificável executando um comando.

IDCritérioVerificaçãoStatus
AC-52Cabeçalho, biblioteca e transpilador compilam sem avisos no conjunto adotado (-Werror), em dois frontends independentesmake test-portabilidade §3 (c0 e c1)atendido
AC-53A suíte completa passa nos dois frontends, com o mesmo número de verificaçõesmake test-matriz (307 de linguagem + 230 unitárias + 30 de integração por compilador)atendido
AC-54A suíte passa sob ASan + UBSan com LeakSanitizer, sem vazamento e sem UBmake test-sanitizeatendido
AC-55Cada afirmativa de portabilidade identifica compilador, versão, alvo, padrão e se houve execução11-matriz-compatibilidade.md (vocabulário de 4 estados) + 12 §2atendido
AC-56Toolchain não exercitado aparece como "avaliado" ou "não testado", nunca como "suportado"§4 de 11 (MSVC = avaliado); §1, itens 8–11atendido
AC-57Nenhum aviso do conjunto adotado é silenciado para "limpar" o build; cada exceção tem causa identificada e teste que a fixa10 §6; defeitos DF-01 e DF-06 em 13atendido
AC-58Os comandos documentados funcionam a partir de um checkout limpo, sem build/make test-checkout (13 verificações)atendido
AC-59Existe teste de mutação determinístico do transpilador, com contrato explícito (não derrubar, não travar) e relatóriomake fuzz (tests/fuzz_basicgolc.py, seed fixa)atendido
AC-60O mesmo arquivo .c vale nos dois perfis: M0 e M1 produzem a mesma saída para os programas de portabilidadetests/run_portabilidade.sh §5 (M0×M1)atendido

make test-portabilidade fechou com 70 verificações aprovadas, 2 ignoradas e 0 falhas; make test-matriz passou a suíte inteira em GCC 12.2.0 e no frontend Clang 20.1.2; make test-sanitize fechou limpo; 2000 mutações do transpilador não derrubaram nada. O que não foi executado está listado, item por item, em 11 §1 e 12 §8.

Símbolos citados neste documento​

Nomes que aparecem literalmente no texto acima e que possuem página de referência gerada do fonte:

BG_SEM_APELIDOS.

Perguntas frequentes​

Perguntas frequentes sobre este documento, respondidas a partir do conteúdo versionado e da referência gerada.

O que significa uma fase estar concluída?​

Que os critérios numerados foram verificados e que os portões de entrada e saída foram cumpridos. O documento registra o veredito de cada critério; não basta a funcionalidade existir.

Como os critérios são verificados na prática?​

Por comandos reproduzíveis e casos dourados. Sempre que possível o critério aponta para um teste que falha se a garantia desaparecer.

make test
make test-biblioteca
make test-portabilidade
make test-sanitize

Um critério aprovado aqui vale para qualquer compilador?​

Não. A aprovação vale para os alvos efetivamente executados. MSVC é avaliado, AArch64 é compilado e o frontend Clang foi exercitado via zig cc; a distinção está na matriz e não pode ser apagada.

Como mudar a especificação sem quebrar o processo?​

O documento define o processo de mudança: registrar a decisão, atualizar especificação e critérios, adicionar teste e rodar a suíte. Uma mudança de comportamento sem teste correspondente não é considerada concluída.