sentry-test 1.0.0__py3-none-any.whl

sentry_test-1.0.0.dist-info/METADATA

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: sentry-test
+Version: 1.0.0
+Summary: Test quality intelligence for change-oriented reviews
+Author: Lucas Nicolau Ferreira
+License: MIT License
+        
+        Copyright (c) 2026 Lucas Nicolau Ferreira
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALING IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Sentry
+
+CLI de qualidade de teste orientada a mudança. O `sentry` cria a pasta da spec, valida a matriz de casos em markdown, roda a suíte, lê o diff e a cobertura, e emite um veredito auditável — e deixa o fluxo escrito para o agente de IA que for implementar a mudança.
+
+Markdown é a fonte da intenção: a CLI parseia e valida `CASES.md` e `PROMPT.md` — ela nunca os escreve. O agente de IA faz a redação; o Sentry garante estrutura, rastreabilidade e veredito.
+
+> Não confundir com o [Sentry da getsentry](https://sentry.io) (monitoramento de erros). Este projeto é distribuído como `sentry-test`.
+
+## A divisão de responsabilidade
+
+- **O agente de IA declara intenção** — escreve o `CASES.md`: requisito, camada, tipo, prioridade, entrada, resultado esperado.
+- **O Sentry mede a realidade** — decide status, teste associado, evidência e veredito.
+
+O agente nunca escreve status. O Sentry nunca chama um modelo. É isso que torna o veredito auditável e reproduzível.
+
+## Instalação
+
+```bash
+pip install sentry-test
+```
+
+Requer Python 3.11+. Confira com `sentry --version` (imprime a versão do pacote).
+
+Se faltar `pytest` ou `coverage`, o `init` avisa. Para instalar junto:
+
+```bash
+sentry init --install
+```
+
+## Setup
+
+```bash
+cd seu-projeto
+sentry init
+```
+
+Cria `.sentry/` (specs, execuções, relatórios e banco), o `sentry.toml`, as entradas do `.gitignore`, e escreve o fluxo em dois lugares:
+
+- **Skill `sentry-cases`** em `.claude/skills/sentry-cases/SKILL.md` — carregada automaticamente pelo Claude Code e por agentes que seguem essa convenção.
+- **`AGENT-SENTRY.md`** na raiz do projeto — o mesmo fluxo em markdown puro, sem depender de convenção de nenhuma ferramenta.
+
+Para outros agentes (Cursor, Windsurf, Codex, opencode), aponte-os para o `AGENT-SENTRY.md` no arquivo de regras que cada um já usa — por exemplo, uma linha em `.cursor/rules` ou `AGENTS.md`:
+
+```markdown
+Para escrever ou revisar casos de teste, siga AGENT-SENTRY.md.
+```
+
+`init` é idempotente: não apaga histórico, não sobrescreve configuração existente, não duplica estruturas.
+
+## O fluxo
+
+1. `sentry new "cadastro de cliente"` — cria `.sentry/specs/cadastro-de-cliente/` com `PROMPT.md` (pedido preservado) e `CASES.md` em branco
+2. **`sentry-cases`** — seu agente pergunta o que estiver ambíguo e preenche o `CASES.md` seguindo o template
+3. `sentry check cadastro-de-cliente` — estrutura válida? classes de equivalência do catálogo cobertas?
+4. seu agente liga cada caso ao teste real com o marcador `# cenario: <nome exato do caso>`
+5. `sentry run --spec cadastro-de-cliente --run-tests` — roda a suíte, lê diff e cobertura, aplica as regras, persiste
+6. `sentry report` / `sentry history` — releitura e comparação entre execuções
+
+Todo passo também funciona sem agente, pelos comandos abaixo.
+
+## Comandos
+
+Código de saída `0` em sucesso; veja a tabela de códigos adiante.
+
+| Comando | O que faz |
+| --- | --- |
+| `sentry init [--install]` | Prepara o repositório: `.sentry/`, `sentry.toml`, `.gitignore`, guia de agente e skills. Com `--install`, instala as dependências ausentes. |
+| `sentry new <nome> [--prompt "..."] [--json]` | Cria a pasta da spec com slug derivado do nome. `--json` emite template, vocabulário aceito e classes cobradas, para o agente consumir. |
+| `sentry check [<slug>\|all]` | Valida `CASES.md`: estrutura, vocabulário e cobrança de classes de equivalência. `all` valida todas as specs juntas. |
+| `sentry run [--spec <slug>\|all] [--run-tests]` | Executa a análise e persiste. Sem `--run-tests` não há cobertura, e o veredito tende a `inconclusivo`. |
+| `sentry report` | Exibe o último relatório (`.sentry/reports/latest.md`). |
+| `sentry history` | Lista execuções e compara as duas últimas: cobertura, testes, achados novos, resolvidos e persistentes. |
+| `sentry clear [--keep-last N] [--yes]` | Poda execuções e relatórios antigos. Sem `--yes` apenas mostra o que sairia — apagar histórico é irreversível. Nunca toca em `.sentry/specs/`. |
+
+## Códigos de saída
+
+Quatro estados distinguíveis, para separar "código mal testado" de "meu ambiente quebrou":
+
+| Código | Significado |
+| --- | --- |
+| `0` | aprovado |
+| `1` | aprovado com ressalvas |
+| `2` | reprovado |
+| `3` | inconclusivo ou erro de infraestrutura |
+
+Erro de infraestrutura nunca produz veredito aprovado: uma suíte que não conseguiu rodar é diferente de uma suíte que reprovou.
+
+`sentry check` mantém semântica própria: `0` estrutura válida, `1` erros estruturais, `2` não foi possível resolver a spec.
+
+## Skills
+
+Geradas para cada agente configurado; o `AGENT-SENTRY.md` cobre os demais.
+
+| Workflow | O que o agente faz |
+| --- | --- |
+| `sentry-cases` | Recebe o pedido em texto livre, cria a spec, **pergunta antes de escrever** toda ambiguidade que mude um caso, preenche o `CASES.md`, liga cada caso ao teste com `# cenario:` e roda `check` até fechar limpo. Nunca escreve status. |
+
+## Regras determinísticas
+
+Dez regras, com severidade configurável por projeto.
+
+| Regra | Severidade padrão | Dispara quando |
+| --- | --- | --- |
+| `test-failing` | crítica | a suíte tem teste falhando |
+| `case-spec-invalid` | crítica | o `CASES.md` tem erro estrutural |
+| `changed-code-uncovered` | alta | cobertura do código alterado é zero |
+| `scenario-without-test` | alta | caso declarado sem teste associado |
+| `error-path-without-test` | alta | `raise`/`throw` em linha alterada que nenhum teste executou |
+| `missing-equivalence-class` | alta | classe exigida pelo catálogo que nenhum caso cobre |
+| `coverage-below-threshold` | alta | cobertura do código alterado abaixo do limiar declarado |
+| `requirement-without-scenario` | média | requisito sem cenário correspondente |
+| `coverage-missing` | média | não foi possível calcular a cobertura do código alterado |
+| `global-coverage-below-threshold` | média | cobertura global abaixo do limiar declarado |
+
+Sem limiar declarado, o Sentry não inventa um mínimo. Quem define "quanto basta" é o projeto, e o relatório registra o número aplicado.
+
+## Catálogo de classes de equivalência
+
+Tabela fixa de situações que precisam de teste, **por tipo de campo**. Não gera casos: cobra os que o agente deixou de declarar.
+
+Tipos conhecidos: `cpf`, `cnpj`, `email`, `senha`, `data`, `telefone`, `cep`, `inteiro`, `decimal`, `texto`, `rota`.
+
+Uma classe que não faz sentido para o campo pode ser dispensada **com justificativa**, em vez de virar caso artificial ou cobrança eterna:
+
+```markdown
+## Classes não aplicáveis
+
+- **exclude/tamanho-maximo-excedido**: é parâmetro de configuração, não campo de formulário
+```
+
+A dispensa remove o achado, mas fica registrada no relatório — nada some em silêncio.
+
+## Dimensões de cobertura
+
+Cada uma reporta `coberta`, `parcial`, `não coberta` ou `não aplicável`, com evidência.
+
+| Dimensão | De onde tira a evidência |
+| --- | --- |
+| requisitos e regras de negócio | cenários da spec com teste associado |
+| APIs, persistência, transações e integrações | casos de tipo `contrato`/`integração` e camada `integração` |
+| exceções, resiliência e recuperação | caminhos de erro alterados executados por algum teste |
+| segurança e autorização | campos de tipo `rota` com todas as classes de acesso cobertas |
+
+`não aplicável` é distinto de `não coberta`: um projeto sem rotas não é punido na dimensão de segurança.
+
+## Configuração
+
+`sentry.toml` na raiz, versionável, sem segredos. Tudo é opcional além do que o `init` já escreve.
+
+```toml
+[project]
+name = "meu-projeto"
+
+[specs]
+path = ".sentry/specs"
+
+[test]                    # qualquer executor que exporte JUnit XML
+command = "npx jest"
+junit_xml = "reports/junit.xml"   # sem isto, o Sentry injeta --junitxml (pytest)
+
+[tests]                   # onde procurar testes
+paths = ["tests"]         # padrão: tests, test, spec, __tests__
+
+[coverage]                # relatório gerado pela suíte do próprio projeto
+path = "coverage/lcov.info"
+format = "lcov"           # opcional: detectado pelo conteúdo quando omitido
+
+[analysis]
+run_tests_by_default = false
+timeout_seconds = 300
+exclude = ["frontend/"]   # diretórios fora do escopo da análise
+
+[policy.thresholds]       # sem isto, nenhum mínimo é cobrado
+changed_coverage = 85
+global_coverage = 90
+
+[policy.severities]       # sobrescreve a severidade de qualquer regra
+coverage-missing = "alta"
+
+[catalog.fields]          # tipos de campo do seu domínio
+matricula = ["vazio", "formato-invalido", "valida"]
+
+[dimensions]              # eixos que não se aplicam ao projeto
+disabled = []
+```
+
+`.sentry/` guarda specs, execuções, relatórios e o banco. Fica fora do Git, com uma exceção deliberada: `.sentry/reports/latest.md` é versionado, para o veredito aparecer no diff da PR sem que o revisor precise rodar o Sentry.
+
+O histórico é mantido indefinidamente, e cresce a cada execução. Para podar:
+
+```bash
+sentry clear --keep-last 10        # mostra o que sairia
+sentry clear --keep-last 10 --yes  # remove
+```
+
+As specs nunca são removidas: são intenção declarada, não evidência gerada.
+
+## Stacks suportadas
+
+A **derivação** — do pedido à matriz de casos — é agnóstica de linguagem: o `CASES.md` é markdown e o catálogo raciocina sobre tipo de dado, não sobre código.
+
+A **verificação** depende do formato de intercâmbio que sua suíte exporta, não da ferramenta:
+
+| Capacidade | Suporte |
+| --- | --- |
+| Execução da suíte | qualquer comando que exporte **JUnit XML** — pytest, Jest, Vitest, `go test` (gotestsum), Surefire, `dotnet test`, RSpec, PHPUnit |
+| Cobertura | **lcov** (nyc, c8, Jest, simplecov), **Cobertura XML** (JaCoCo, coverlet), **coverage.py** (JSON) — detectados pelo conteúdo |
+| Rastreabilidade caso↔teste | `.py`, `.js`/`.jsx`/`.ts`/`.tsx`, `.go`, `.java`/`.kt`, `.cs`, `.rb`, `.php`, `.rs` — e o marcador `cenario:` funciona em qualquer comentário |
+| Caminhos de erro | por AST em Python; por padrão sintático (`throw`, `catch`, `panic`, `rescue`, `panic!`) nas demais |
+| Análise de impacto | 12 extensões de código-fonte |
+
+A detecção de caminho de erro fora de Python é menos precisa que AST, e o relatório registra essa diferença como limitação — nunca a esconde.
+
+Camada `frontend` é recusada de propósito: sem adaptador que a verifique, um caso declarado ficaria preso em `não coberto` para sempre.
+
+## Local-first
+
+Nenhuma telemetria, nenhuma chamada externa, nenhum envio de código ou diff. Todo o histórico permanece na máquina.
+
+## Desenvolvimento
+
+```bash
+python -m pip install -e .
+python -m pytest
+```
+
+O Sentry se analisa: `sentry run --spec all --run-tests` na raiz do repositório
+casa os casos declarados em `.sentry/specs/` com as funções de teste reais e
+reporta as quatro dimensões.
+
+## Licença
+
+MIT

sentry_test-1.0.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+sentry_test-1.0.0.dist-info/licenses/LICENSE,sha256=w2VXTcpLsShFLnGAOyIAXTJgzh1fE35Pc0tzeld0VDM,1078
+sentrytest/__init__.py,sha256=35jw87a9NAUeOFJnDPpzOjaRE4xAjG2Qrskk9ZJGNRA,63
+sentrytest/cli.py,sha256=J2_2QV8N00D-My9x8x-kelVUN5zwiotExBFTwMaldbE,11113
+sentrytest/init_project.py,sha256=ty-PO5FEW9UvfiC0KdcKVtgOOlUvIx5HRAHn4cEoitQ,4745
+sentrytest/skills.py,sha256=__0X6EGxuABByhULfRyhn37IRH2-LM1Vmib0cu6s0h4,8981
+sentrytest/adapters/__init__.py,sha256=sHs7IzwyJBkCa8MSKMO5_lbcmxZxgYbQt0DTRFoOjGU,45
+sentrytest/adapters/case_specs.py,sha256=RiO6Uqtbga09Liuxnwqu9SYEhjTM7TIC_cqC52GxP6k,8795
+sentrytest/adapters/local_tools.py,sha256=IAFIQaatl8Lt2GPJr8bx0NulFztuxOQdTOUdYAsTyBU,16006
+sentrytest/adapters/toml_config.py,sha256=hnvpaM_2ksNeckjbf_QyTYTvqrjvOi-B7dlCr6T7fbg,248
+sentrytest/application/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sentrytest/application/analyze.py,sha256=b0UhDuOI-1b85a8tIph9VjuKyMu9TpTqwJ8NszYO4w0,13931
+sentrytest/application/cases.py,sha256=t_gn5g4DXvE_vECwdJlK0El5tDsaYRa6ORlo3hZv-OQ,4780
+sentrytest/application/coverage_context.py,sha256=nnoANIM9Y1P1FVYXYh1_ZS2if5nyRavSu1ugravRBH8,931
+sentrytest/application/dimensions.py,sha256=QNtrklzlneKMcFcoCgiXvhK0qUr9TPDtHNY6thRbKJo,4272
+sentrytest/application/error_paths.py,sha256=HetpiqzTcoldOL0q9ezBJ1ZOpJFxu89KmreNSXhn4pI,5478
+sentrytest/application/impact.py,sha256=Hxdaw2Sjxdas-J5OaaTy6GghjrFkRhgeZbniRiy0l5Q,3487
+sentrytest/application/reporting.py,sha256=GKia_LmG62kUCxsPhRkq8049qRTlxAFTYYnD3BHHIWQ,11022
+sentrytest/application/traceability.py,sha256=ZjYbhQSQhYRwdDCEO7HCf122PEGVQGha0vGEwfrTerY,8070
+sentrytest/domain/__init__.py,sha256=SRfF7oDVlOOAi6nGKiJIUK6B_arqYLO9iSMp-2IZZps,21
+sentrytest/domain/catalog.py,sha256=v9XDZOHsTa7L2r_B1gI992FGoq_OAIvg3FJZV09DSlc,3949
+sentrytest/domain/models.py,sha256=BsEP65y8o-Maa1jhHhFaWVkLTzOxY4w_mVuyOCV1MXs,3831
+sentrytest/domain/rules.py,sha256=7t4I6CdbxUyjB_USDS4i8D1Ps7xlbiEK4iAgotBKe3w,5757
+sentrytest/ports/__init__.py,sha256=PN4XmYk6B1tg4awK-1AC-tKDBGwUtDPHH3XP1mYGzDA,21
+sentrytest/ports/inputs.py,sha256=fXJTV8RypTjTNmkZ27BcBLMwP7qKtxMg0tcGWYHxTD8,1850
+sentry_test-1.0.0.dist-info/METADATA,sha256=eyeX-ZIK44me6QKOn8dk1AhM13GNu6Zko1QKaRtJd4M,12686
+sentry_test-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sentry_test-1.0.0.dist-info/entry_points.txt,sha256=fgtkXdY-icVXreQV1exA2Qrqv5Qx5CBIdc0XHjAPCHY,47
+sentry_test-1.0.0.dist-info/top_level.txt,sha256=_tdeT-T3OV7Hfd-jq_AkbutODFLUJUfboZtCML-Qs9s,11
+sentry_test-1.0.0.dist-info/RECORD,,

sentry_test-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sentry_test-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sentry = sentrytest.cli:main

sentry_test-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Nicolau Ferreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALING IN THE
+SOFTWARE.

sentry_test-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sentrytest

sentrytest/__init__.py

@@ -0,0 +1,3 @@
+"""Núcleo público do pacote Sentry."""
+
+__version__ = "1.0.0"

sentrytest/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adaptadores das integrações externas."""

sentrytest/adapters/case_specs.py

@@ -0,0 +1,244 @@
+"""Leitura e validação da matriz de casos declarada em CASES.md.
+
+O agente de IA escreve o arquivo seguindo TEMPLATE; o Sentry apenas parseia e
+valida a estrutura. Nenhuma inferência é feita sobre o conteúdo em texto livre.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+TEMPLATE = """# <Título da funcionalidade>
+
+## Prompt
+
+<o pedido original em texto livre, preservado literalmente>
+
+## Campos
+
+- **<nome do campo>**: <tipo> — <regra declarada>
+
+## Caso: <nome curto e único>
+
+- **Requisito:** <o que do prompt este caso verifica>
+- **Camada:** backend | integração
+- **Tipo:** unitário | integração | contrato
+- **Prioridade:** crítica | alta | média | baixa
+- **Classe:** <campo>/<classe de equivalência>
+- **Dado:** <pré-condição>
+- **Quando:** <ação>
+- **Então:** <resultado esperado>
+- **Entrada:** `campo = valor`
+
+## Classes não aplicáveis
+
+- **<campo>/<classe>**: <motivo pelo qual esta classe do catálogo não se aplica aqui>
+"""
+
+LAYERS = ("backend", "integração")
+TEST_TYPES = ("unitário", "integração", "contrato")
+PRIORITIES = ("crítica", "alta", "média", "baixa")
+
+_TITLE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+_SECTION = re.compile(r"^##\s+(.+?)\s*\n([\s\S]*?)(?=\n##\s|\Z)", re.MULTILINE)
+_FIELD = re.compile(r"^-\s+\*\*(.+?)\*\*:\s*(\S+)\s*(?:[—-]\s*(.*))?$", re.MULTILINE)
+_NOT_APPLICABLE = re.compile(r"^-\s+\*\*(.+?)/(.+?)\*\*:\s*(.*?)\s*$", re.MULTILINE)
+_BULLET = re.compile(r"^-\s+\*\*(.+?):\*\*\s*(.*)$", re.MULTILINE)
+_INPUT_PAIR = re.compile(r"([A-Za-z_][\w.]*)\s*=\s*(\"[^\"]*\"|'[^']*'|[^,]+)")
+
+_REQUIRED_BULLETS = ("requisito", "camada", "tipo", "prioridade", "dado", "quando", "entao")
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    name: str
+    type: str
+    rule: str = ""
+
+
+@dataclass(frozen=True)
+class CaseSpec:
+    name: str
+    requirement: str
+    layer: str
+    test_type: str
+    priority: str
+    given: str
+    when: str
+    then: str
+    equivalence_class: str | None = None
+    input_data: dict[str, str] = None
+
+    def __post_init__(self):
+        if self.input_data is None:
+            object.__setattr__(self, "input_data", {})
+
+
+@dataclass(frozen=True)
+class NotApplicableClass:
+    field: str
+    class_name: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class CaseDocument:
+    title: str
+    prompt: str
+    fields: tuple[FieldSpec, ...] = ()
+    cases: tuple[CaseSpec, ...] = ()
+    not_applicable: tuple[NotApplicableClass, ...] = ()
+
+
+def _normalize(text: str) -> str:
+    stripped = unicodedata.normalize("NFKD", text.strip().casefold())
+    return "".join(char for char in stripped if not unicodedata.combining(char))
+
+
+def _match_enum(value: str, allowed: tuple[str, ...]) -> str | None:
+    normalized = _normalize(value)
+    for candidate in allowed:
+        if _normalize(candidate) == normalized:
+            return candidate
+    return None
+
+
+def _parse_input_data(raw: str) -> dict[str, str]:
+    content = raw.strip().strip("`").strip()
+    if not content:
+        return {}
+    result: dict[str, str] = {}
+    for name, value in _INPUT_PAIR.findall(content):
+        cleaned = value.strip()
+        if len(cleaned) >= 2 and cleaned[0] == cleaned[-1] and cleaned[0] in "\"'":
+            cleaned = cleaned[1:-1]
+        result[name] = cleaned
+    return result
+
+
+def _parse_fields(body: str) -> tuple[FieldSpec, ...]:
+    fields = []
+    for name, type_name, rule in _FIELD.findall(body):
+        name = name.strip()
+        if not name or name.startswith("<"):
+            continue
+        fields.append(FieldSpec(name, type_name.strip(), (rule or "").strip()))
+    return tuple(fields)
+
+
+def _parse_not_applicable(body: str) -> tuple[NotApplicableClass, ...]:
+    items = []
+    for field_name, class_name, reason in _NOT_APPLICABLE.findall(body):
+        field_name, class_name, reason = field_name.strip(), class_name.strip(), reason.strip()
+        if not field_name or field_name.startswith("<"):
+            continue
+        items.append(NotApplicableClass(field_name, class_name, reason))
+    return tuple(items)
+
+
+def _parse_case(name: str, body: str) -> CaseSpec:
+    bullets = {_normalize(key): value.strip() for key, value in _BULLET.findall(body)}
+    return CaseSpec(
+        name=name,
+        requirement=bullets.get("requisito", ""),
+        layer=bullets.get("camada", ""),
+        test_type=bullets.get("tipo", ""),
+        priority=bullets.get("prioridade", ""),
+        given=bullets.get("dado", ""),
+        when=bullets.get("quando", ""),
+        then=bullets.get("entao", ""),
+        equivalence_class=bullets.get("classe") or None,
+        input_data=_parse_input_data(bullets.get("entrada", "")),
+    )
+
+
+def parse_cases(text: str) -> CaseDocument:
+    title_match = _TITLE.search(text)
+    title = title_match.group(1).strip() if title_match else ""
+    prompt = ""
+    fields: tuple[FieldSpec, ...] = ()
+    not_applicable: tuple[NotApplicableClass, ...] = ()
+    cases = []
+    for heading, body in _SECTION.findall(text):
+        heading = heading.strip()
+        normalized = _normalize(heading)
+        if normalized == "prompt":
+            prompt = body.strip()
+        elif normalized == "campos":
+            fields = _parse_fields(body)
+        elif normalized == "classes nao aplicaveis":
+            not_applicable = _parse_not_applicable(body)
+        elif normalized.startswith("caso:"):
+            name = heading.split(":", 1)[1].strip()
+            if name and not name.startswith("<"):
+                cases.append(_parse_case(name, body))
+    return CaseDocument(title=title, prompt=prompt, fields=fields, cases=tuple(cases), not_applicable=not_applicable)
+
+
+def validate_document(document: CaseDocument) -> list[str]:
+    """Erros estruturais do CASES.md. Lista vazia significa documento válido."""
+    errors: list[str] = []
+    if not document.title or document.title.startswith("<"):
+        errors.append("título ausente: a primeira linha deve ser '# <Título da funcionalidade>'")
+    if not document.prompt or document.prompt.startswith("<"):
+        errors.append("seção '## Prompt' ausente ou não preenchida")
+    if not document.cases:
+        errors.append("nenhum caso declarado: use '## Caso: <nome>' para cada caso de teste")
+
+    seen: set[str] = set()
+    declared_fields = {field.name for field in document.fields}
+    for case in document.cases:
+        key = _normalize(case.name)
+        if key in seen:
+            errors.append(f"caso duplicado: '{case.name}'")
+        seen.add(key)
+
+        bullets = {
+            "requisito": case.requirement, "camada": case.layer, "tipo": case.test_type,
+            "prioridade": case.priority, "dado": case.given, "quando": case.when, "entao": case.then,
+        }
+        for bullet in _REQUIRED_BULLETS:
+            if not bullets[bullet]:
+                errors.append(f"caso '{case.name}': campo obrigatório ausente '{bullet}'")
+
+        if case.layer and not _match_enum(case.layer, LAYERS):
+            errors.append(f"caso '{case.name}': camada inválida '{case.layer}' (use: {', '.join(LAYERS)})")
+        if case.test_type and not _match_enum(case.test_type, TEST_TYPES):
+            errors.append(f"caso '{case.name}': tipo inválido '{case.test_type}' (use: {', '.join(TEST_TYPES)})")
+        if case.priority and not _match_enum(case.priority, PRIORITIES):
+            errors.append(f"caso '{case.name}': prioridade inválida '{case.priority}' (use: {', '.join(PRIORITIES)})")
+
+        if case.equivalence_class and "/" in case.equivalence_class:
+            field_name = case.equivalence_class.split("/", 1)[0].strip()
+            if declared_fields and field_name not in declared_fields:
+                errors.append(
+                    f"caso '{case.name}': classe referencia o campo '{field_name}', que não está declarado em '## Campos'"
+                )
+
+    for item in document.not_applicable:
+        if not item.reason:
+            errors.append(f"classe não aplicável '{item.field}/{item.class_name}': falta o motivo")
+        if declared_fields and item.field not in declared_fields:
+            errors.append(
+                f"classe não aplicável referencia o campo '{item.field}', que não está declarado em '## Campos'"
+            )
+    return errors
+
+
+class CaseSpecAdapter:
+    """Implementa a porta SpecReader lendo a matriz declarada em CASES.md."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+    def document(self) -> CaseDocument:
+        return parse_cases(self.path.read_text(encoding="utf-8"))
+
+    def scenarios(self):
+        from ..ports.inputs import SpecScenario
+        return tuple(
+            SpecScenario(case.name, case.given, case.when, case.then)
+            for case in self.document().cases
+        )