@vibe2founder/tests2dialects 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Release] v0.4.1
+
+### What's Changed
+
+- :memo: **docs**: Added explicit "Running API Tests" section to README for clarity on execution steps.
+- :sparkles: **feat**: Created `examples/showcase-api.spec.ts` demonstrating all API dialect features (GET, POST, PUT, DELETE, Headers, Schema).
+
+## [0.4.0]
+
+### What's Changed
+
+- :recycle: **refactor**: Renomeado projeto para `@vibe2founder/tests2dialects`.
+- :bug: **fix**: Corrigidas extensões de importação ESM para `.js` em todo o projeto.
+- :bug: **fix**: Implementado isolamento de estado no CLI entre arquivos de teste via `resetAtomicCore()`.
+- :zap: **perf**: Melhorada a precisão do report do CLI com logs de caminho completo de suites.
+- :label: **types**: Adicionada interface `AtomicMock` para resolver lints de Proxy dinâmico.
+
+## [0.3.0]
+
+### What's Changed
+
+- :sparkles: **feat**: Criado o novo Dialeto de Testes de API (`@vibe2founder/api-test-dialect`).
+- :sparkles: **feat**: Implementado `@vibe2founder/request2http` nativo/local utilizando Fetch API.
+- :label: **types**: Adicionada tipagem semântica nominal para todos os parâmetros de rede em `types/api-types.ts`.
+- :memo: **docs**: Adicionados READMEs detalhados para os novos pacotes e relatório técnico em `reports/`.
+- :white_check_mark: **test**: Criado exemplo operacional em `examples/test-api.ts`.
+
+## [0.2.0]
+
+### What's Changed
+
+- :rocket: **release**: Version bump to 0.2.0.
+- :wrench: **chore**: Added `testall` as a CLI binary alias in `package.json`.
+- :art: **style**: Standardized `readme.md` headings to sentence case (only first word capitalized).
+- :sparkles: **feat**: Implemented `critica2.md` suggestions with visual proofs of coexistence and strategic sections for leadership.
+- :zap: **perf**: Enhanced core engine with Deep Proxies for mocks, supporting automatic method mocking.
+- :recycle: **refactor**: Implemented "Call Bubbling" in mocks to allow verifying object interactions via parent mocks.
+- :bug: **fix**: Fixed `beforeAll` and `afterAll` hook execution in the test runner.
+- :white_check_mark: **test**: Verified and fixed all examples, achieving 100% pass rate on the polyglot test suite.
+
+## [0.1.0]
+
+### What's Changed
+
+- :memo: **docs**: Expanded README with detailed philosophies for each test dialect.
+- :memo: **docs**: Added complete, realistic code examples for Math, Narrative, and Imperative dialects.
+- :recycle: **refactor**: Updated `src/index.ts` to export dialect functions as top-level exports, simplifying imports.
+- :wrench: **chore**: Standardized package naming in documentation to `@vibe2founder/tests2dialects`.
+- :art: **style**: Converted comparison table in README from HTML to Markdown for better portability.
+- :sparkles: **feat**: Complete README restructure following podcast feedback:
+  - Added "Cansado de Descrever?" hook connecting philosophy to practice
+  - Added "Quick Start" section for 5-minute first test victory
+  - Added visual dialect chooser flowchart
+  - Added "A Dor Que Resolvemos" pain-point sections before each dialect
+  - Moved advanced topics (Rosetta Table, Polyglot Mode) to the end
+  - Added gradual adoption/migration guide
+- :sparkles: **feat**: Complete CLI rewrite with Vitest-style output:
+  - ANSI color palette (green/red/yellow/cyan)
+  - Spinner animation during test execution
+  - Per-file timer showing elapsed time
+  - Grouped test results with indentation
+  - Summary statistics (files, tests, duration)
+  - Exit codes based on test results
+- :sparkles: **feat**: README restructure following critica2.md podcast:
+  - Visual proof of legacy coexistence (Jest + dialeto) at the very top
+  - New "Por Que Adotar no Seu Time?" section for tech leads/managers
+  - Progressive disclosure: API summaries in README, full docs linked separately
+  - Created `/docs/api-imperativo.md`, `/docs/api-matematico.md`, `/docs/api-narrativo.md`
+  - Reordered sections: Trust → Strategy → Quick Start → Choose Dialect

package/bun.lock

@@ -0,0 +1,22 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vibe2founder/tests2dialects",
+      "dependencies": {
+        "@types/node": "latest",
+        "undici-types": "~7.16.0",
+      },
+      "devDependencies": {
+        "typescript": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@25.0.10", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-zWW5KPngR/yvakJgGOmZ5vTBemDoSqF3AcV/LrO5u5wTWyEAVVh+IT39G4gtyAkh3CtTZs8aX/yRM82OfzHJRg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/bunfig.toml

@@ -0,0 +1,2 @@
+[run]
+tsconfig = "./tsconfig.json"

package/critica.md

@@ -0,0 +1,77 @@
+# Crítica e Esclarecimento: A Filosofia Aditiva do tests2dialects Tester
+
+Uma crítica comum a novos frameworks é a sensação de que "precisamos jogar tudo fora e reaprender a programar". Este documento existe para esclarecer que o **tests2dialects Tester** foi desenhado com uma filosofia oposta: a **Filosofia Aditiva**.
+
+---
+
+## 1. Não é uma Negação do Passado
+
+A maior preocupação de qualquer equipe é o **código legado**. Se você tem 5.000 testes escritos em Jest padrão (`describe`, `it`, `expect`), o tests2dialects Tester **não exige que você reescreva uma linha sequer**.
+
+O framework funciona como um **superset** (superconjunto). Ele entende nativamente a sintaxe do Jest.
+
+> **Resumo:** Seus testes antigos continuam passando. Seu conhecimento de Jest continua válido.
+
+---
+
+## 2. O Mito da "Torre de Babel"
+
+Quando dizemos "tests2dialects", **não esperamos que cada desenvolvedor seja fluente em todos os dialetos**. Isso seria ineficiente e aumentaria a carga cognitiva.
+
+A proposta é a **Especialização por Contexto**:
+
+- O **Cientista de Dados** só precisa aprender o `MathDialect`. Ele não precisa saber o que é um `scenario` ou `looks`.
+- O **Designer/Frontend** foca no `VisualDialect`. Ele ignora completamente a existência dos axiomas matemáticos.
+- O **Engenheiro de Backend** usa o `ImperativeDialect`.
+
+> **Você não precisa aprender 4 idiomas.** Você escolhe um que se adapta ao seu projeto e ignora o resto. O framework é poliglota; você não precisa ser.
+
+---
+
+## 3. Um Executor para Todos (One Runner)
+
+Tecnicamente, não há "mágica" pesada rodando por trás. O tests2dialects Tester **unifica a execução**. Isso significa que você não precisa de pipelines de CI/CD separados para "Testes Jest Antigos" e "Testes Novos".
+
+Um único comando:
+
+```bash
+npm test
+```
+
+Executará:
+
+- ✅ Seus arquivos `.spec.ts` antigos (Jest Clássico).
+- ✅ Seus novos arquivos de regras de negócio (`MathDialect`).
+- ✅ Seus novos testes de componentes (`VisualDialect`).
+
+Todos aparecem no mesmo relatório, com a mesma cobertura de código, na mesma janela de terminal.
+
+---
+
+## 4. Exemplo Prático de Coexistência
+
+Imagine um arquivo de teste que está sendo migrado ou refatorado. O código abaixo é **100% válido** e executável pelo tests2dialects Tester:
+
+```javascript
+// Legado: Ninguém quer mexer nisso agora
+describe("Módulo de Login (Legacy)", () => {
+  it("deve validar senha", () => {
+    expect(validar("123")).toBe(true);
+  });
+});
+
+// Novo: Nova funcionalidade de criptografia adicionada hoje
+import { axiom, implies } from "@vibe2founder/tests2dialects";
+
+axiom("Nova Criptografia SHA-256", () => {
+  // Usamos o dialeto novo apenas para a feature nova
+  // Não quebramos nada do anterior
+  implies(hash("123")).matches(/^[a-f0-9]{64}$/);
+});
+```
+
+---
+
+## Conclusão
+
+O **tests2dialects Tester** não veio para destruir o Jest ou o Mocha. Ele veio para **dar vocabulário onde o vocabulário padrão falha em expressar a intenção**. É uma ferramenta de **adição**, não de substituição.

package/docs/4-ideias.md

@@ -0,0 +1,66 @@
+4 Ideias Contraintuitivas do tests2dialects que Vão Mudar a Forma Como Você Escreve Testes
+
+Adotar um novo framework de testes muitas vezes vem com um custo alto: a sensação de que precisamos "jogar tudo fora e reaprender a programar". É um processo que paralisa equipes e desvaloriza o código construído ao longo de anos. O framework tests2dialects chega com uma filosofia surpreendentemente diferente, a "Filosofia Aditiva" — uma abordagem que respeita seu tempo e seu código. Neste post, vamos explorar as quatro ideias mais impactantes e contraintuitivas por trás dessa nova forma de pensar que promete expandir, e não substituir, seu ecossistema de testes.
+
+1. Você não precisa reescrever uma linha de código legado
+
+A primeira e mais radical ideia do tests2dialects é o respeito absoluto pelo seu trabalho existente. A "Filosofia Aditiva" significa que o framework funciona como um superset (superconjunto) do Jest. Ele não exige a reescrita de testes antigos.
+
+Isso quer dizer que os milhares de testes describe/it/expect que sua equipe já possui continuarão funcionando perfeitamente, com um único comando de execução. Não há migração forçada, nem quebra de compatibilidade.
+
+O tests2dialects Tester não veio para destruir o Jest ou o Mocha. Ele veio para dar vocabulário onde o vocabulário padrão falha em expressar a intenção. É uma ferramenta de adição, não de substituição.
+
+Essa abordagem é crucial porque reduz drasticamente o risco de adoção. Ela respeita o trabalho já feito pela equipe e permite que novas funcionalidades e conceitos sejam introduzidos de forma gradual e segura, sem a necessidade de um "big bang" ou de uma refatoração massiva.
+
+2. A linguagem do seu teste deveria refletir a do seu problema
+
+A frustração central que o tests2dialects resolve é o desalinhamento semântico. A linguagem padrão de testes, com describe e it, foi projetada para descrever comportamentos de componentes, mas se torna inadequada em outros contextos, como provar a correção de um algoritmo ou verificar a conformidade de um contrato de API.
+
+Veja como a linguagem padrão soa "errada" e informal ao testar uma função de criptografia pura: describe("SHA-256", () => { it("should produce a valid hash"...) })
+
+Em contraste, o Dialeto Matemático do framework reflete o rigor necessário com uma sintaxe de prova axiomática, alinhada à natureza do problema:
+
+axiom("Teoria de Hash SHA-256", () => {
+proof("Hash de string vazia converge para constante conhecida", () => {
+implies(sha256("")).is("e3b0c44...");
+});
+});
+
+A linguagem importa. Ela molda o pensamento.
+
+Utilizar a semântica correta aumenta fundamentalmente a clareza, o rigor e, mais importante, a intenção do teste. A equipe não está mais descrevendo um comportamento; está, de fato, provando uma verdade universal, o que alinha a mentalidade do desenvolvedor com o rigor matemático do problema. O código passa a comunicar o que está fazendo de forma muito mais precisa.
+
+3. O framework é poliglota para que você não precise ser
+
+A ideia de múltiplos "dialetos" de teste pode soar como um convite ao caos, o chamado "Mito da Torre de Babel". No entanto, a proposta do tests2dialects é o oposto: a ideia não é que cada desenvolvedor aprenda todos os dialetos, mas que cada especialista use a ferramenta mais afiada para sua tarefa, adotando a mentalidade certa para o trabalho.
+
+O conceito é a Especialização por Contexto:
+
+- Cientista de Dados: Foca no MathDialect, adotando uma mentalidade científica e axiomática para provar a correção de algoritmos.
+- Product Manager e Designer: Utilizam o NarrativeDialect para descrever fluxos de usuário de forma legível, focando na experiência humana e no comportamento do sistema.
+- Engenheiro de Backend/Sistemas: Usa o ImperativeDialect para garantir a conformidade de APIs, adotando uma mentalidade rigorosa de engenharia de sistemas.
+
+A mensagem é clara: "Você não precisa aprender 4 idiomas. Você escolhe um que se adapta ao seu projeto e ignora o resto." Essa abordagem reduz a carga cognitiva, permitindo que as equipes trabalhem com ferramentas especializadas e de alta precisão sem nunca sair do mesmo ecossistema de testes.
+
+4. Seus testes podem virar a documentação que seu time de produto entende
+
+Uma das barreiras mais comuns no desenvolvimento de software é a comunicação entre a equipe de produto e a de engenharia. Os testes, que deveriam ser a fonte da verdade sobre o comportamento do sistema, são frequentemente ilegíveis para pessoas não-técnicas.
+
+O Dialeto Narrativo do tests2dialects foi criado para destruir essa barreira. Veja a diferença:
+
+// Antes (Ilegível para não-técnicos)
+it("should return 403", () => { /_ ... _/ });
+
+// Depois (Claro para todos)
+scenario("Usuário sem permissão tenta acessar o painel de Admin", () => {
+const response = attemptAccessAsUnauthorizedUser();
+to(response.status).be(403);
+});
+
+Essa mudança transforma os testes em um "contrato vivo" e uma "documentação viva". Product Managers e Designers podem agora ler os testes e validar se as regras de negócio foram implementadas conforme o esperado. Os testes se tornam a fonte única de verdade para as regras de negócio, quebrando a barreira clássica entre produto e engenharia e garantindo que o produto construído é, de fato, o produto desejado.
+
+Conclusão
+
+O tests2dialects não se apresenta como um substituto revolucionário, mas como uma evolução inteligente. Sua filosofia é adicionar poder de expressão ao ecossistema que já conhecemos, uma ferramenta que lhe devolve o poder de escolher a palavra certa para o problema certo. Ele nos dá o vocabulário para alinhar a linguagem do teste à natureza do problema.
+
+Depois de ver essa abordagem, a pergunta que fica é: será que a forma como sempre escrevemos testes tem limitado a forma como pensamos sobre nossos próprios sistemas?

package/docs/api-api.md

@@ -0,0 +1,93 @@
+# 🌐 Dialeto de API - API Completa
+
+> **Filosofia:** Design by Contract e Fluent Interface.
+>
+> **Vibe:** Declarativa, Precisa, Conectada.
+>
+> **Ideal para:** Backend Engineers, QA Automation, validação de contratos, testes de integração e microserviços.
+
+## Estrutura
+
+| Função                 | Descrição                                  | Equivalente Supertest/Axios         |
+| :----------------------- | :------------------------------------------- | :---------------------------------- |
+| `ApiSpec.define(name)` | Inicia a definição de um novo teste de API | `describe` / `it`               |
+| `.from(url)`           | Define a URL base para a requisição        | `request(app)` / `axios.create` |
+| `.get(path)`           | Configura uma requisição GET               | `.get(path)`                      |
+| `.post(path, body)`    | Configura uma requisição POST com corpo    | `.post(path).send(body)`          |
+| `.put(path, body)`     | Configura uma requisição PUT com corpo     | `.put(path).send(body)`           |
+| `.delete(path)`        | Configura uma requisição DELETE            | `.delete(path)`                   |
+| `.method(verb, path)`  | Define um método HTTP arbitrário           | `.request({method, url})`         |
+
+## Configuração da Requisição
+
+| Função              | Descrição                                   | Equivalente                             |
+| :-------------------- | :-------------------------------------------- | :-------------------------------------- |
+| `.header(key, val)` | Adiciona um cabeçalho à requisição        | `.set(key, val)`                      |
+| `.withBody(body)`   | Define ou sobrescreve o corpo da requisição | `.send(body)`                         |
+| `.withAuth(token)`  | Atalho para Header Authorization Bearer       | `.set('Authorization', 'Bearer ...')` |
+
+## Asserções
+
+| Função                           | Descrição                                                  | Equivalente Jest/Chai                      |
+| :----------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------- |
+| `.shouldReturn(status)`                        | Verifica o Status Code HTTP retornado                        | `expect(res.status).toBe(status)`        |
+| `.matchingSchema(schema)`                      | Valida se a resposta corresponde ao schema (tipagem nominal) | `expect(res.body).toMatchSchema(schema)` |
+
+## Execução
+
+| Função   | Descrição                              | O que faz                                                        |
+| :--------- | :--------------------------------------- | :--------------------------------------------------------------- |
+| `.run()` | Executa a requisição e as validações | Dispara o fetch, valida status, valida schema e loga o resultado |
+
+## Exemplo Completo
+
+```typescript
+import { ApiSpec } from "@vibe2founder/tests2dialects";
+
+// Definindo o teste de forma fluída e declarativa
+await ApiSpec.define("Ciclo de Vida do Usuário")
+  .from("https://api.empresa.com/v1")
+  
+  // Passo 1: Criar Usuário
+  .post("/users", {
+    name: "Antigravity",
+    email: "ag@vibe2founder.codes",
+    role: "admin"
+  })
+  .header("X-Project-ID", "one-spec-4-all")
+  .shouldReturn(201)
+  .matchingSchema({
+    id: "number",
+    name: "string",
+    createdAt: "string"
+  })
+  .run();
+
+// Passo 2: Validar se o usuário existe
+await ApiSpec.define("Buscar Usuário Criado")
+  .from("https://api.empresa.com/v1")
+  .get("/users/1")
+  .shouldReturn(200)
+  .run();
+
+// Passo 3: Remover Usuário
+await ApiSpec.define("Remover Usuário")
+  .from("https://api.empresa.com/v1")
+  .delete("/users/1")
+  .shouldReturn(204)
+  .run();
+```
+
+## Quando Usar
+
+- ✅ Testes de integração de APIs REST.
+- ✅ Verificação de contratos e schemas de resposta.
+- ✅ Validação de Status Codes HTTP.
+- ✅ Cenários que dependem de rede real ou mocks de rede.
+- ✅ Testes E2E de backend.
+
+## Quando NÃO Usar
+
+- ❌ Testes unitários de funções puras → Use o [Dialeto Matemático](./api-matematico.md)
+- ❌ Fluxos de UI complexas ou Narrativas de negócio → Use o [Dialeto Narrativo](./api-narrativo.md)
+- ❌ Lógica de negócios interna sem I/O direto → Use o [Dialeto Imperativo](./api-imperativo.md)

package/docs/api-imperativo.md

@@ -0,0 +1,125 @@
+# 🛡️ Dialeto Imperativo - API Completa
+
+> **Filosofia:** Design by Contract e Engenharia de Sistemas.
+>
+> **Vibe:** Técnica, Rigorosa, "Crachá de Engenheiro".
+>
+> **Ideal para:** Engenheiros de backend, DevOps, validação de APIs, conformidade (compliance).
+
+## Estrutura
+
+| Função             | Descrição                       | Equivalente Jest |
+| ------------------ | ------------------------------- | ---------------- |
+| `ensure(name, fn)` | Garante um requisito de sistema | `describe`       |
+| `suite(name, fn)`  | Uma suite de verificações       | `describe`       |
+| `check(name, fn)`  | Uma checagem pontual            | `test` / `it`    |
+| `verify(name, fn)` | Verificação de conformidade     | `test` / `it`    |
+
+## Asserções
+
+| Função                        | Descrição             | Equivalente Jest                         |
+| ----------------------------- | --------------------- | ---------------------------------------- |
+| `that(val).is(expected)`      | "Que o valor é..."    | `expect(val).toBe(expected)`             |
+| `that(val).isOk()`            | Verifica "truthiness" | `expect(val).toBeTruthy()`               |
+| `that(val).matches(regex)`    | Validação de padrão   | `expect(val).toMatch(regex)`             |
+| `that(val).triggered()`       | Verifica disparo      | `expect(val).toHaveBeenCalled()`         |
+| `that(val).calledWith(args)`  | Verifica payload      | `expect(val).toHaveBeenCalledWith(args)` |
+| `that(val).triggeredCount(n)` | Contagem exata        | `expect(val).toHaveBeenCalledTimes(n)`   |
+
+## Mocks
+
+| Função                 | Descrição                        | Equivalente Jest          |
+| ---------------------- | -------------------------------- | ------------------------- |
+| `stub()`               | Cria um stub de infraestrutura   | `jest.fn()`               |
+| `mock()`               | Alias para stub                  | `jest.fn()`               |
+| `inspect(obj, method)` | Inspeciona um método interno     | `jest.spyOn(obj, method)` |
+| `spy(obj, method)`     | Alias clássico                   | `jest.spyOn(obj, method)` |
+| `s.forceReturn(val)`   | Força um retorno imediato        | `mockReturnValue(val)`    |
+| `s.resolveWith(val)`   | Resolve promessa (network)       | `mockResolvedValue(val)`  |
+| `s.executes(fn)`       | Executa implementação substituta | `mockImplementation(fn)`  |
+
+## Lifecycle
+
+| Função           | Descrição                       | Equivalente Jest |
+| ---------------- | ------------------------------- | ---------------- |
+| `initAll(fn)`    | Inicialização de sistema        | `beforeAll(fn)`  |
+| `reset(fn)`      | Reset de estado (antes de cada) | `beforeEach(fn)` |
+| `disposeAll(fn)` | Descarte de recursos            | `afterAll(fn)`   |
+
+## Exemplo Completo
+
+```javascript
+import {
+  ensure,
+  check,
+  verify,
+  that,
+  stub,
+  initAll,
+  reset,
+} from "@vibe2founder/tests2dialects";
+
+ensure("Conformidade do Gateway de Pagamento", () => {
+  let apiGateway;
+  let transactionLogger;
+
+  initAll(() => {
+    apiGateway = stub();
+    transactionLogger = stub();
+
+    apiGateway.forceReturn({
+      status: 200,
+      transactionId: "tx_abc123",
+      timestamp: "2026-01-01T00:00:00Z",
+    });
+    transactionLogger.forceReturn(true);
+  });
+
+  reset(() => {
+    // Limpa estado entre testes se necessário
+  });
+
+  check("Transação bem-sucedida retorna status 200", () => {
+    const response = apiGateway.process({
+      amount: 99.9,
+      currency: "BRL",
+      cardToken: "tok_visa_xxxx",
+    });
+
+    that(response.status).is(200);
+    that(response.transactionId).matches(/^tx_[a-z0-9]+$/);
+  });
+
+  verify("TransactionId segue padrão RFC do contrato", () => {
+    const response = apiGateway.process({ amount: 50 });
+
+    that(response.transactionId).matches(/^tx_[a-z0-9]{6,}$/);
+    that(response.timestamp).matches(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  check("Toda transação deve ser logada para auditoria", () => {
+    apiGateway.process({ amount: 100 });
+    transactionLogger.log({ event: "PAYMENT_PROCESSED" });
+
+    that(transactionLogger).triggered();
+    that(transactionLogger).calledWith({ event: "PAYMENT_PROCESSED" });
+  });
+
+  verify("Gateway deve ser acionado exatamente uma vez por request", () => {
+    that(apiGateway).triggeredCount(1);
+  });
+});
+```
+
+## Quando Usar
+
+- ✅ Integrações de API
+- ✅ Drivers de banco de dados
+- ✅ Validação de contratos RFC
+- ✅ Conformidade com regulamentos (PCI-DSS, LGPD, etc.)
+- ✅ Testes de infraestrutura
+
+## Quando NÃO Usar
+
+- ❌ Algoritmos matemáticos puros → Use o [Dialeto Matemático](./api-matematico.md)
+- ❌ Fluxos de usuário legíveis por PMs → Use o [Dialeto Narrativo](./api-narrativo.md)

package/docs/api-matematico.md

@@ -0,0 +1,145 @@
+# 📐 Dialeto Matemático - API Completa
+
+> **Filosofia:** Lógica Formal e Programação Funcional.
+>
+> **Vibe:** Científica, Imutável, Axiomática.
+>
+> **Ideal para:** Cientistas de dados, engenheiros de algoritmos, bibliotecas de utilitários, cálculos financeiros.
+
+## Estrutura
+
+| Função            | Descrição                                | Equivalente Jest |
+| ----------------- | ---------------------------------------- | ---------------- |
+| `axiom(name, fn)` | Define um grupo de verdades fundamentais | `describe`       |
+| `proof(name, fn)` | Uma prova individual de um caso          | `test` / `it`    |
+| `lemma(name, fn)` | Uma prova auxiliar (menor)               | `test` / `it`    |
+
+## Asserções
+
+| Função                            | Descrição                           | Equivalente Jest                         |
+| --------------------------------- | ----------------------------------- | ---------------------------------------- |
+| `implies(val).is(expected)`       | "O valor implica ser..."            | `expect(val).toBe(expected)`             |
+| `implies(val).wasEvaluated()`     | Verifica se a função foi computada  | `expect(val).toHaveBeenCalled()`         |
+| `implies(val).appliedTo(args)`    | Verifica os argumentos da aplicação | `expect(val).toHaveBeenCalledWith(args)` |
+| `implies(val).evaluated(n).times` | Frequência de avaliação             | `expect(val).toHaveBeenCalledTimes(n)`   |
+| `implies(val).matches(regex)`     | Corresponde a um padrão             | `expect(val).toMatch(regex)`             |
+
+## Mocks
+
+| Função                 | Descrição                                | Equivalente Jest          |
+| ---------------------- | ---------------------------------------- | ------------------------- |
+| `arbitrary()`          | Cria uma função genérica para teste      | `jest.fn()`               |
+| `lambda()`             | Alias para arbitrary                     | `jest.fn()`               |
+| `monitor(obj, method)` | Monitora uma função existente            | `jest.spyOn(obj, method)` |
+| `f.yields(val)`        | Define o resultado produzido pela função | `mockReturnValue(val)`    |
+| `f.mapsTo(val)`        | Alias para yields                        | `mockReturnValue(val)`    |
+| `f.convergesTo(val)`   | Define o resultado assíncrono (limite)   | `mockResolvedValue(val)`  |
+| `f.derive(fn)`         | Define a implementação lógica            | `mockImplementation(fn)`  |
+
+## Lifecycle
+
+| Função          | Descrição                           | Equivalente Jest |
+| --------------- | ----------------------------------- | ---------------- |
+| `postulate(fn)` | Define premissas iniciais globais   | `beforeAll(fn)`  |
+| `setup(fn)`     | Alias para postulate                | `beforeAll(fn)`  |
+| `given(fn)`     | "Dado que..." (antes de cada prova) | `beforeEach(fn)` |
+| `conclude(fn)`  | Conclusões finais / limpeza         | `afterAll(fn)`   |
+
+## Exemplo Completo
+
+```javascript
+import {
+  axiom,
+  proof,
+  lemma,
+  implies,
+  arbitrary,
+  monitor,
+  postulate,
+  given,
+  conclude,
+} from "@vibe2founder/tests2dialects";
+
+axiom("Teoria de Juros Compostos", () => {
+  let calcInterest;
+  let applyTax;
+  const logger = arbitrary();
+
+  postulate(() => {
+    // Premissas globais para todos os teoremas deste axioma
+    console.log("Estabelecendo premissas...");
+  });
+
+  given(() => {
+    // Definimos as funções puras a serem testadas a cada ciclo
+    calcInterest = (p, r, t) => Math.floor(p * Math.pow(1 + r, t));
+    applyTax = (subtotal, rate) =>
+      Math.round(subtotal * (1 + rate) * 100) / 100;
+  });
+
+  proof("Capital de 1000 a 5% por 2 anos implica montante de 1102", () => {
+    const result = calcInterest(1000, 0.05, 2);
+    implies(result).is(1102);
+  });
+
+  proof("Taxa zero implica preservação do capital", () => {
+    const result = calcInterest(500, 0, 10);
+    implies(result).is(500);
+  });
+
+  proof("Desconto de 100% anula o preço", () => {
+    const calcDiscount = (price, percent) => price - price * (percent / 100);
+    implies(calcDiscount(500, 100)).is(0);
+  });
+
+  lemma("Imposto de 10% sobre R$100 resulta em R$110", () => {
+    implies(applyTax(100, 0.1)).is(110);
+  });
+
+  proof("Logger arbitrário registra cálculo", () => {
+    logger.yields(true);
+    logger("calc_start");
+
+    implies(logger).wasEvaluated();
+    implies(logger).appliedTo("calc_start");
+  });
+
+  conclude(() => {
+    console.log("Teoremas provados com sucesso.");
+  });
+});
+
+axiom("Teoria de Fibonacci", () => {
+  const fib = arbitrary();
+
+  given(() => {
+    // Definição recursiva de Fibonacci
+    fib.derive((n) => (n <= 1 ? n : fib(n - 1) + fib(n - 2)));
+  });
+
+  proof("Fibonacci(0) implica 0", () => {
+    implies(fib(0)).is(0);
+  });
+
+  proof("Fibonacci(1) implica 1", () => {
+    implies(fib(1)).is(1);
+  });
+
+  proof("Fibonacci(10) implica 55", () => {
+    implies(fib(10)).is(55);
+  });
+});
+```
+
+## Quando Usar
+
+- ✅ Algoritmos matemáticos puros
+- ✅ Funções de criptografia
+- ✅ Cálculos financeiros
+- ✅ Regras de negócio determinísticas
+- ✅ Bibliotecas de utilitários
+
+## Quando NÃO Usar
+
+- ❌ Integrações de API com contratos → Use o [Dialeto Imperativo](./api-imperativo.md)
+- ❌ Fluxos de usuário legíveis por PMs → Use o [Dialeto Narrativo](./api-narrativo.md)