@purecore/one-spec-4-all 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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 `@purecore/one-spec-4-all`.
+- :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/critica.md

@@ -0,0 +1,77 @@
+# Crítica e Esclarecimento: A Filosofia Aditiva do one-spec-4-all 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 **one-spec-4-all 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 one-spec-4-all 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 "one-spec-4-all", **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 one-spec-4-all 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 one-spec-4-all 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 "@purecore/one-spec-4-all";
+
+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 **one-spec-4-all 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/dist/index.d.ts

@@ -110,4 +110,8 @@ export declare const ClassicDialect: {
     beforeEach: (f: VoidFn) => void;
     afterEach: (f: VoidFn) => void;
 };
+export declare const axiom: (n: string, f: VoidFn) => void, proof: (n: string, f: VoidFn) => void, implies: <T>(val: T) => UniversalAssertion<T>, arbitrary: typeof createAtomicMock, lambda: typeof createAtomicMock, monitor: typeof createAtomicSpy, postulate: (f: VoidFn) => void, conclude: (f: VoidFn) => void, given: (f: VoidFn) => void;
+export declare const intend: (n: string, f: VoidFn) => void, story: (n: string, f: VoidFn) => void, detail: (n: string, f: VoidFn) => void, scenario: (n: string, f: VoidFn) => void, to: <T>(val: T) => UniversalAssertion<T>, dummy: typeof createAtomicMock, standIn: typeof createAtomicMock, watch: typeof createAtomicSpy, shadow: typeof createAtomicSpy, background: (f: VoidFn) => void, cleanup: (f: VoidFn) => void, before: (f: VoidFn) => void;
+export declare const ensure: (n: string, f: VoidFn) => void, suite: (n: string, f: VoidFn) => void, check: (n: string, f: VoidFn) => void, verify: (n: string, f: VoidFn) => void, that: <T>(val: T) => UniversalAssertion<T>, stub: typeof createAtomicMock, mock: typeof createAtomicMock, inspect: typeof createAtomicSpy, spy: typeof createAtomicSpy, initAll: (f: VoidFn) => void, disposeAll: (f: VoidFn) => void, reset: (f: VoidFn) => void;
+export declare const describe: (n: string, f: VoidFn) => void, it: (n: string, f: VoidFn) => void, test: (n: string, f: VoidFn) => void, expect: <T>(val: T) => UniversalAssertion<T>, beforeAll: (f: VoidFn) => void, afterAll: (f: VoidFn) => void, beforeEach: (f: VoidFn) => void, afterEach: (f: VoidFn) => void;
 export {};

package/dist/index.js

@@ -3,7 +3,7 @@
 // 1. ATOMIC CORE ENGINE (O Motor)
 // ============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClassicDialect = exports.ImperativeDialect = exports.NarrativeDialect = exports.MathDialect = void 0;
+exports.afterEach = exports.beforeEach = exports.afterAll = exports.beforeAll = exports.expect = exports.test = exports.it = exports.describe = exports.reset = exports.disposeAll = exports.initAll = exports.spy = exports.inspect = exports.mock = exports.stub = exports.that = exports.verify = exports.check = exports.suite = exports.ensure = exports.before = exports.cleanup = exports.background = exports.shadow = exports.watch = exports.standIn = exports.dummy = exports.to = exports.scenario = exports.detail = exports.story = exports.intend = exports.given = exports.conclude = exports.postulate = exports.monitor = exports.lambda = exports.arbitrary = exports.implies = exports.proof = exports.axiom = exports.ClassicDialect = exports.ImperativeDialect = exports.NarrativeDialect = exports.MathDialect = void 0;
 class AtomicCore {
     static instance;
     rootSuite = {
@@ -297,4 +297,8 @@ exports.ClassicDialect = {
     beforeEach: (f) => core.addHook("beforeEach", f),
     afterEach: (f) => core.addHook("afterEach", f),
 };
-// End of library exports
+// --- Top-Level Exports for Ease of Use ---
+exports.axiom = exports.MathDialect.axiom, exports.proof = exports.MathDialect.proof, exports.implies = exports.MathDialect.implies, exports.arbitrary = exports.MathDialect.arbitrary, exports.lambda = exports.MathDialect.lambda, exports.monitor = exports.MathDialect.monitor, exports.postulate = exports.MathDialect.postulate, exports.conclude = exports.MathDialect.conclude, exports.given = exports.MathDialect.given;
+exports.intend = exports.NarrativeDialect.intend, exports.story = exports.NarrativeDialect.story, exports.detail = exports.NarrativeDialect.detail, exports.scenario = exports.NarrativeDialect.scenario, exports.to = exports.NarrativeDialect.to, exports.dummy = exports.NarrativeDialect.dummy, exports.standIn = exports.NarrativeDialect.standIn, exports.watch = exports.NarrativeDialect.watch, exports.shadow = exports.NarrativeDialect.shadow, exports.background = exports.NarrativeDialect.background, exports.cleanup = exports.NarrativeDialect.cleanup, exports.before = exports.NarrativeDialect.before;
+exports.ensure = exports.ImperativeDialect.ensure, exports.suite = exports.ImperativeDialect.suite, exports.check = exports.ImperativeDialect.check, exports.verify = exports.ImperativeDialect.verify, exports.that = exports.ImperativeDialect.that, exports.stub = exports.ImperativeDialect.stub, exports.mock = exports.ImperativeDialect.mock, exports.inspect = exports.ImperativeDialect.inspect, exports.spy = exports.ImperativeDialect.spy, exports.initAll = exports.ImperativeDialect.initAll, exports.disposeAll = exports.ImperativeDialect.disposeAll, exports.reset = exports.ImperativeDialect.reset;
+exports.describe = exports.ClassicDialect.describe, exports.it = exports.ClassicDialect.it, exports.test = exports.ClassicDialect.test, exports.expect = exports.ClassicDialect.expect, exports.beforeAll = exports.ClassicDialect.beforeAll, exports.afterAll = exports.ClassicDialect.afterAll, exports.beforeEach = exports.ClassicDialect.beforeEach, exports.afterEach = exports.ClassicDialect.afterEach;

package/docs/4-ideias.md

@@ -0,0 +1,66 @@
+4 Ideias Contraintuitivas do one-spec-4-all 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 one-spec-4-all 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 one-spec-4-all é 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 one-spec-4-all 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 one-spec-4-all 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 one-spec-4-all é 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 one-spec-4-all 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 one-spec-4-all 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-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 "@purecore/one-spec-4-all";
+
+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 "@purecore/one-spec-4-all";
+
+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)

package/docs/api-narrativo.md

@@ -0,0 +1,181 @@
+# 📖 Dialeto Narrativo - API Completa
+
+> **Filosofia:** BDD (Behavior Driven Development) e Storytelling.
+>
+> **Vibe:** Fluida, Humana, Descritiva.
+>
+> **Ideal para:** Designers, Product Managers, times ágeis, testes de fluxos de usuário (User Journeys).
+
+## Estrutura
+
+| Função               | Descrição                           | Equivalente Jest |
+| -------------------- | ----------------------------------- | ---------------- |
+| `intend(name, fn)`   | Define a intenção do bloco          | `describe`       |
+| `story(name, fn)`    | Alias para agrupamento de histórias | `describe`       |
+| `detail(name, fn)`   | Detalha um comportamento específico | `test` / `it`    |
+| `scenario(name, fn)` | Um cenário de uso                   | `test` / `it`    |
+
+## Asserções
+
+| Função                    | Descrição                      | Equivalente Jest                         |
+| ------------------------- | ------------------------------ | ---------------------------------------- |
+| `to(val).be(expected)`    | "Para o valor ser..."          | `expect(val).toBe(expected)`             |
+| `to(val).have(prop)`      | Verifica posse de propriedade  | `expect(val).toHaveProperty(prop)`       |
+| `to(val).wasCalled()`     | Verifica se o ator foi chamado | `expect(val).toHaveBeenCalled()`         |
+| `to(val).received(args)`  | Verifica o que foi recebido    | `expect(val).toHaveBeenCalledWith(args)` |
+| `to(val).called(n).times` | Contagem de chamadas           | `expect(val).toHaveBeenCalledTimes(n)`   |
+
+## Mocks (Dublês/Atores)
+
+| Função                       | Descrição                        | Equivalente Jest          |
+| ---------------------------- | -------------------------------- | ------------------------- |
+| `dummy()`                    | Um dublê (ator) no lugar do real | `jest.fn()`               |
+| `standIn()`                  | Alias para dummy                 | `jest.fn()`               |
+| `watch(obj, method)`         | Observa um ator existente        | `jest.spyOn(obj, method)` |
+| `shadow(obj, method)`        | Segue (shadows) um método        | `jest.spyOn(obj, method)` |
+| `actor.respondsWith(val)`    | Define a resposta do ator        | `mockReturnValue(val)`    |
+| `actor.eventuallyGives(val)` | Resposta futura (promessa)       | `mockResolvedValue(val)`  |
+| `actor.actsLike(fn)`         | Define como o ator deve agir     | `mockImplementation(fn)`  |
+
+## Lifecycle
+
+| Função           | Descrição                     | Equivalente Jest |
+| ---------------- | ----------------------------- | ---------------- |
+| `background(fn)` | Contexto de fundo da história | `beforeAll(fn)`  |
+| `before(fn)`     | Antes de cada cena            | `beforeEach(fn)` |
+| `cleanup(fn)`    | Limpeza após a história       | `afterAll(fn)`   |
+
+## Exemplo Completo
+
+```javascript
+import {
+  intend,
+  story,
+  scenario,
+  detail,
+  to,
+  standIn,
+  dummy,
+  watch,
+  background,
+  before,
+  cleanup,
+} from "@purecore/one-spec-4-all";
+
+intend("Fluxo de Autenticação do Usuário", () => {
+  const authService = standIn();
+  const database = standIn();
+  const emailSender = dummy();
+
+  background(() => {
+    // Configura o cenário de fundo para toda a história
+    authService.respondsWith({ token: "abc-123", expiresIn: 3600 });
+    database.respondsWith(true);
+    emailSender.respondsWith({ sent: true });
+  });
+
+  before(() => {
+    // Reset de estado antes de cada cena
+  });
+
+  scenario("Login com credenciais válidas deve retornar token", () => {
+    const response = authService.login("usuario", "senha_secreta");
+
+    to(response).have("token");
+    to(response.token).be("abc-123");
+    to(response).have("expiresIn");
+  });
+
+  scenario("Login deve registrar tentativa no banco de dados", () => {
+    authService.login("usuario", "senha_secreta");
+    database.logAttempt("usuario", "success");
+
+    to(database).wasCalled();
+    to(database).received("logAttempt", "usuario", "success");
+  });
+
+  scenario("Login bem-sucedido envia email de boas-vindas", () => {
+    authService.login("novo_usuario", "senha123");
+    emailSender.send("novo_usuario@email.com", "Bem-vindo!");
+
+    to(emailSender).wasCalled();
+  });
+
+  cleanup(() => {
+    console.log("Histórias de autenticação concluídas.");
+  });
+});
+
+story("Jornada de Compra do Usuário", () => {
+  const cart = standIn();
+  const user = standIn();
+  const paymentGateway = standIn();
+
+  background(() => {
+    cart.respondsWith({ items: [], total: 0 });
+    user.respondsWith({ name: "João", loggedIn: true });
+    paymentGateway.respondsWith({ status: "approved" });
+  });
+
+  scenario("Usuário adiciona primeiro produto ao carrinho", () => {
+    cart.add({ name: "Camiseta", price: 49.9, quantity: 1 });
+    cart.respondsWith({
+      items: [{ name: "Camiseta", price: 49.9, quantity: 1 }],
+      total: 49.9,
+    });
+
+    to(cart).wasCalled();
+    to(cart.items).have("length");
+  });
+
+  scenario("Usuário aplica cupom de desconto", () => {
+    const coupon = standIn();
+    coupon.respondsWith({ valid: true, discount: 15 });
+
+    cart.applyCoupon("DESCONTO15");
+    cart.respondsWith({ total: 42.42 }); // 49.9 - 15%
+
+    to(coupon).wasCalled();
+    to(cart.total).be(42.42);
+  });
+
+  detail("Carrinho vazio mostra mensagem amigável", () => {
+    cart.respondsWith({
+      items: [],
+      total: 0,
+      message: "Seu carrinho está vazio",
+    });
+
+    to(cart.message).be("Seu carrinho está vazio");
+  });
+
+  scenario("Usuário não logado tenta finalizar compra", () => {
+    user.respondsWith({ loggedIn: false });
+    const checkout = standIn();
+    checkout.respondsWith({ error: "LOGIN_REQUIRED", status: 401 });
+
+    to(checkout.status).be(401);
+    to(checkout.error).be("LOGIN_REQUIRED");
+  });
+
+  scenario("Pagamento aprovado finaliza a compra", () => {
+    cart.checkout();
+
+    to(paymentGateway.status).be("approved");
+    to(cart).wasCalled();
+  });
+});
+```
+
+## Quando Usar
+
+- ✅ Fluxos de usuário (User Journeys)
+- ✅ Testes E2E legíveis
+- ✅ Documentação viva para PMs
+- ✅ Regras de negócio de alto nível
+- ✅ Testes de aceitação
+
+## Quando NÃO Usar
+
+- ❌ Algoritmos matemáticos puros → Use o [Dialeto Matemático](./api-matematico.md)
+- ❌ Integrações técnicas com contratos rígidos → Use o [Dialeto Imperativo](./api-imperativo.md)