# RuleWalk — Status do Projeto > Estado atual e próximos passos. Atualizado em 2026-08-03. --- ## O que é RuleWalk é uma ferramenta de comunicação e auditoria de regras de negócio. Dado uma regra (de um documento, e-mail, ou função JS) e um conjunto de dados (real ou sintético), ela produz um único arquivo HTML auto-contido que mostra o que acontece com cada registro em cada etapa da regra. O resultado é um walkthrough navegável — cards expansíveis com contagem de registros, amostras antes/depois, e explicações em linguagem natural. Funciona 100% offline, sem servidor, sem dependências externas. **Proposta de valor em uma linha:** prove o comportamento de uma regra com dados antes de confiar nela. --- ## Como funciona hoje ### Arquitetura geral ``` Regra (doc ou código) │ ▼ [Claude / usuário] monta o Pipeline IR │ ▼ pipeline.json ──► rulewalk validate ──► OK / erros │ ▼ rulewalk deliver ──► rendered.html ``` Não há execução de código em nenhum ponto. Tudo é análise estática + dados pré-montados no IR. --- ### Componentes #### 1. Pipeline IR (`pipeline.json`) O coração do sistema. Um JSON tipado (schema v2) que registra: - **`meta`** — título, tipo de fonte (`doc` ou `code`), origem dos dados (`provided` ou `synthetic`), esquema da entidade inicial - **`initial_dataset`** — contagem e amostra dos registros de entrada - **`steps[]`** — cadeia de transformações, cada uma com tipo, contagens, amostras e condição - **`final_result`** — contagem e amostra do resultado final #### 2. Tipos de step | Tipo | O que faz | Invariante de contagem | |------|-----------|----------------------| | `filter` | Mantém ou descarta registros por condição | `output_count ≤ input_count` | | `transform` | Adiciona/modifica campos em todos os registros | `output_count == input_count` | | `group` | Agrega registros em grupos (muda a unidade de contagem) | N registros → M grupos | | `lookup` | Enriquece registros com dados de tabela externa | `output_count == input_count` | | `action` | Dispara efeito colateral (email, webhook, escrita) | sem `input/output_count`; usa `trigger_count` | #### 3. Campo `confidence` Sinaliza o grau de certeza sobre a regra extraída: | Valor | Significado visual | Quando usar | |-------|--------------------|-------------| | `confirmed` (default) | sem badge | Regra inequívoca e rastreável à fonte | | `assumed` | badge âmbar + borda esquerda | Fonte implica a regra mas com incerteza (magic numbers, thresholds sem comentário) | | `approximated` | badge laranja | Regra não estava na fonte — RuleWalk a inferiu ou inventou | #### 4. CLI (`rulewalk/bin/rulewalk.mjs`) Cinco comandos, zero dependências externas (Node.js puro, ≥18): | Comando | Descrição | |---------|-----------| | `doctor` | Verifica Node ≥18, presença do schema e do template | | `demo [dir]` | Gera o exemplo `pedidos-pendentes` em `examples/` | | `validate ` | Valida estrutura + cadeia de contagens; sai com código 1 se inválido | | `preview ` | Renderiza o HTML mesmo com erros (avisa, não aborta) | | `deliver ` | Valida e só renderiza se limpo (caminho de produção) | #### 5. Validador (`structuralValidate`) Implementado diretamente em JS no CLI. Verifica: - Campos obrigatórios por tipo de step - Campos proibidos por tipo (ex: `output_sample` em `filter`, `passed_sample` em `transform`) - **Cadeia de contagens**: `steps[0].input_count == initial_dataset.count`, cada `steps[i].input_count == steps[i-1].output_count`, `final_result.count == último step de dados` - Regras especiais para `action` (sem `input/output_count`) e `group` (requer `group_by` + `output_unit`) #### 6. Renderer Lê `viewer.html.template` e substitui o marcador `// DATA_PLACEHOLDER` pelo JSON serializado do pipeline. O HTML resultante é completamente auto-contido — CSS e JS inline, sem CDN, sem fontes externas, sem requisições de rede. #### 7. Skill do Claude Code (`rulewalk/SKILL.md`) Instrui o Claude a: 1. Entender a regra e identificar a entidade/steps 2. Gerar dados sintéticos cobrindo todos os ramos (12–20 registros) 3. Montar o `pipeline.json` com contagens corretas na primeira tentativa 4. Rodar `validate` e depois `deliver` 5. Reportar apenas o resumo compacto: `✓ caminho/rendered.html · N→M registros · K steps` Convenção de saída fixa: `./rulewalk-out//pipeline.json` e `./rulewalk-out//rendered.html`. --- ### Fluxo completo (via Claude Code) ``` Usuário descreve a regra │ ▼ Claude ativa a skill rulewalk │ ├─► Identifica entidade + steps + dados necessários ├─► Gera registros sintéticos (ou usa amostra fornecida) ├─► Escreve rulewalk-out//pipeline.json ├─► Roda: node /bin/rulewalk.mjs validate ./rulewalk-out//pipeline.json │ └─ Se inválido: corrige o JSON, revalida ├─► Roda: node /bin/rulewalk.mjs deliver ./rulewalk-out//pipeline.json ./rulewalk-out//rendered.html └─► Reporta: ✓ rulewalk-out//rendered.html · 20→9 registros · 2 steps ``` --- ### Exemplos existentes | Exemplo | Tipos de step | `source_type` | `confidence` | O que prova | |---------|--------------|---------------|--------------|-------------| | `pedidos-pendentes` | filter → filter | `doc` | confirmed | Pipeline mínimo válido; baseline do validador e viewer | | `triagem-leads` | filter → transform → group → lookup → action | `doc` | confirmed | Todos os 5 tipos de step; `result_from` no `final_result` | | `collection-queue` | filter → transform → filter | `code` | assumed (todos) | Caminho `source_type: "code"`; badge âmbar; `confidence_note` | --- ## O que precisa ### Lacunas técnicas #### 1. Validador não usa o JSON Schema real O arquivo `pipeline.schema.json` existe e é formalmente correto (draft 2020-12), mas o CLI não o usa para validar — reimplementa as regras manualmente em JS. Isso cria dois problemas: - As duas fontes de verdade podem divergir silenciosamente - O campo `sample_validation` definido no schema nunca é verificado **Precisa:** integrar um validador JSON Schema (ex: `ajv`) ou eliminar o schema externo e documentar que a validação é somente programática. #### 2. Sem testes automatizados Não há pasta `tests/`, nenhum script de teste no `package.json`. Os três exemplos em `examples/` funcionam como fixtures manuais, mas não rodam automaticamente. **Precisa:** suite de testes mínima — pelo menos um teste por tipo de step + casos de erro conhecidos na cadeia de contagens. #### 3. Não está publicado no npm O README instrui `npx rulewalk doctor` mas o pacote não está no registry. Quem clona o repositório precisa usar `node rulewalk/bin/rulewalk.mjs` — o README cobre isso, mas a inconsistência confunde. **Precisa:** publicar no npm, ou remover os exemplos com `npx` do README até a publicação. #### 4. `preview` não está documentado na skill O SKILL.md menciona apenas `validate` e `deliver`. O comando `preview` (renderiza mesmo com erros) é útil durante desenvolvimento mas está invisível para o Claude. **Precisa:** documentar `preview` na skill com orientação de quando usá-lo (iteração rápida antes de `deliver`). #### 5. Sem abertura automática do resultado Após o `deliver`, o HTML existe em disco mas o usuário precisa abrí-lo manualmente no browser. **Precisa:** flag `--open` no `deliver` que execute `start` (Windows) / `open` (macOS) / `xdg-open` (Linux) após renderizar com sucesso. --- ### Lacunas de design #### 6. Viewer HTML não tem URL para inspecionar Não li o template `viewer.html.template`, mas o viewer provavelmente não exibe o caminho do `pipeline.json` de origem. Se o HTML for compartilhado sem o JSON, não há como saber qual arquivo o gerou. **Precisa:** exibir `meta.title`, `meta.generated_at`, e o nome do arquivo JSON no rodapé ou cabeçalho do viewer. #### 7. `data_origin` por pipeline, não por step O campo `meta.data_origin` é único para todo o pipeline. Um pipeline pode misturar steps com dados reais e steps com dados sintéticos (ex: os registros iniciais são reais, mas o `lookup` usa tabela inventada). **Precisa:** avaliar se `data_origin` por step seria útil, ou documentar explicitamente que a granularidade é intencional. #### 8. Não há suporte a múltiplas entidades O `entity_schema` descreve apenas a entidade inicial. Após um `group`, a unidade muda (ex: de pedidos para grupos por região), mas não há como descrever o schema da entidade agrupada. **Precisa:** ou aceitar como limitação documentada, ou adicionar `output_entity_schema` opcional nos steps `group` e `transform`. --- ### Próximos passos sugeridos (por prioridade) | # | Item | Esforço | Impacto | |---|------|---------|---------| | 1 | Testes automatizados (jest/vitest ou script Node puro) | médio | alto — confiança para evoluir | | 2 | Publicar no npm (ou remover `npx` do README) | baixo | alto — reduz confusão | | 3 | Flag `--open` no `deliver` | baixo | médio — QoL imediato | | 4 | Documentar `preview` na skill | baixo | médio — melhora iteração | | 5 | Integrar validador JSON Schema real (ajv) | médio | médio — elimina duplicação | | 6 | Exibir metadados no viewer (título, data, arquivo de origem) | médio | médio — rastreabilidade | | 7 | Avaliar `data_origin` por step | baixo | baixo — design debt | | 8 | `output_entity_schema` em `group`/`transform` | alto | baixo — cobre caso raro |