O que truepath faz?
Um spec.json descreve o processo (nós, arestas), os cenários (caminho,
mensagens, legendas, entradas) e de onde vêm os vereditos. build.py
calcula os vereditos, organiza o grafo, executa as verificações e gera um
.html offline — ou nada.
spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html (ou nada)
layout.py ──┘ └► fixture.json (--export)
Fluxo de trabalho
-
Copie o exemplo mais próximo junto às anotações do assunto (veja Arquivos), renomeie
spec.jsonpara<assunto>.spec.json. -
Descreva nós e arestas. Cada nó sumidouro (um resultado) recebe um
kind; kinds são as únicas cores, cada um com um rótulo na legenda. -
Escolha de onde vêm os vereditos (veja abaixo): um
oraclequando a regra existe no código, umportJS caso contrário. -
Escreva os cenários. Cada um declara sua
origin, seusinputs, os camposexpectados, e seusstepsao longo de arestas reais. -
Construa, depois abra o arquivo:
python3 <dir-da-skill>/scripts/build.py <assunto>.spec.json -
Leia as violações, corrija o spec — nunca a verificação.
spec.json constrói sim.html, <assunto>.spec.json constrói
<assunto>.sim.html; -o nomeia outro arquivo.
A página abre na primeira aba com o painel de detalhes aberto. Recolher o painel muda para a visão geral: todo o caminho desenhado, um ponto percorrendo-o em loop.
De onde vêm os vereditos
| Fonte | Chave do spec | Use quando | Marcado no painel |
|---|---|---|---|
| Oracle | oracle | a regra existe em um repositório | ✓ código |
| Port | port: "decide.js" | ainda sem código, regra em discussão, processo sem código | ⚠ portado |
Protocolo do Oracle. build.py obtém git archive de oracle.ref (nunca
o checkout ativo: um branch em desenvolvimento pode mudar durante a construção),
extrai oracle.paths, vincula oracle.link (tipicamente node_modules) e copia
oracle.files para dentro dele, depois executa oracle.cmd em oracle.cwd com:
TRUEPATH_ORACLE_IN: um array JSON de todos osinputsde cada cenário;TRUEPATH_ORACLE_OUT: onde escrever um array JSON de vereditos, mesma ordem.
oracle.repo é lido a partir da pasta do spec quando é relativo. link e
files são escritos como {caminho no snapshot: de onde vem}: um
caminho no repositório para link, um arquivo ao lado do spec para files.
Um veredito é um objeto de campos. outcome é obrigatório: nomeia o nó onde o
caminho deve terminar, e é o que vincula um cenário à lógica. basis opcionalmente
diz, por campo, se o código real o computou ("código: …"), a cola copiou
um comportamento ("port: …"), ou a simulação o define (qualquer outro texto,
mostrado ◇ definição). A página mostra essa marca ao lado de cada valor do painel
cujo campo tem uma base, seu texto completo ao passar o mouse, e --export afirma apenas
campos cuja base é código: um campo sem base conta como código sob um oracle,
como portado sob um port. Um oracle pode misturá-los: uma regra ainda em
discussão é portada ao lado das regras que o código já executa. Qualquer
runner funciona: um arquivo de teste do próprio framework do projeto, um script, um
teste JUnit para Java. O rodapé nomeia a ref e o sha curto que produziram os vereditos.
Um oracle que é um arquivo de teste pode funcionar como suíte de regressão:
quando TRUEPATH_ORACLE_IN está definido, ele escreve os vereditos; caso contrário, lê
o fixture exportado e o afirma. Os cenários então vivem uma vez, no spec,
e rodam em CI. examples/loyalty-tier/src/oracle.js faz ambos.
Referência do spec
| Chave | Forma | Notas |
|---|---|---|
title, subtitle, source | strings | source vai para o rodapé; como todo texto do spec, são exibidos como texto, nunca lidos como HTML |
lang | en (padrão) ou fr | idioma das palavras da própria página; o texto do spec é escrito nesse idioma |
kinds | {id: {label, color}} | no máximo 4 |
nodes | [{id, label, role?, kind?}] | role: "decision" marca um ponto de ramificação; onde um caminho começa é encontrado e desenhado redondo; sumidouros precisam de kind |
edges | [[from, to, label]] | label "" para nenhuma |
panel | [{label, value, at, labels?, digits?, compared?}] | value lê inputs.x ou verdict.y; mostrado a partir do passo at (0 é o primeiro); labels mapeia um valor para o que a página mostra ("true", "false", "null", "[]" para esses valores); digits preenche com zeros um código numérico até esse comprimento; compared: true para a linha que nomeia o que um par compara (a correção, a regra), deixado de fora da busca pela primeira divergência |
scenarios | [{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}] | origin: {kind: real|illustrative, text}; steps: [{hop: [from, to], message, caption}]; undecided: true marca uma regra ainda não decidida; caseName nomeia o caso em um fixture exportado |
pairs | [{before, after, tab, summary}] | dois ids de cenários, reproduzidos lado a lado como − e +; mesmo número de passos |
grid | {baseline, questions | variants, cases, steps, expect?, show?, hover, summary?} | casos × respostas (ou regras, correções), em vez de scenarios e pairs: veja abaixo |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | veja acima |
port | caminho para um arquivo CommonJS exportando decide(inputs) | usado quando não há oracle |
export | {dir, fixture, assert} | --export <worktree> escreve o fixture lá |
Comparando várias regras: a grid
Quando a pergunta é "o que cada resposta possível faz para cada caso", declare
uma grid. Prefira questions a uma lista plana de regras: o leitor decide
pergunta por pergunta, então a página deve ser organizada assim.
baseline:{id, label, short?, inputs}, o que acontece hoje;questions:[{id, text, options: [{id, label, inputs}], cases, if?}].caseslista os casos nos quais essa pergunta é decidida;if: {"Q1": "1A"}pede apenas após essa resposta.build.pyderiva uma variante por conjunto coerente de respostas (1A+2A,1A+2B,1B), mesclando osinputsdas opções;cases:[{id, label, summary, origin, inputs, steps?}];labelnomeia a linha em palavras que o leitor conhece, não um código de caso;steps: compartilhados por todas as células, a menos que um caso traga os seus próprios;expect:{case: {variant: {field: value}}}, verificado por C3;show: a única linha do painel que uma célula da matriz mostra (por padrão, a primeira dehover);hover: as linhas que uma célula mostra ao passar o mouse;summary: uma linha acima da matriz.
Uma variants: [{id, label, short?, note?, inputs}] plana com baseline como
um id ainda funciona: a matriz então tem uma seção, cada caso contra cada variante.
A página abre na matriz: uma tabela por pergunta, seus casos contra o hoje
e cada resposta, a linha da célula marcada ≠ onde difere do hoje. Não há
aba por caso: um clique em uma célula a abre, o hoje ao lado dessa resposta,
com a primeira divergência marcada. Dois botões, − e +, escolhem um
lado entre as respostas da seção (1A ao lado de 1B, não apenas ao lado do hoje), cada
um nomeado como sua pergunta o nomeia; ← matriz volta. No painel, uma linha
com "value": "answer" e "compared": true nomeia a resposta reproduzida.
Modelos de passos. message, caption e hop podem citar {inputs.x} ou
{verdict.y}: são preenchidos após a lógica ser executada, formatados como a linha do
painel que lê o mesmo caminho. Um hop para {verdict.outcome} permite que uma única
lista de passos sirva para todas as regras.
Verificações
| Id | Recusa |
|---|---|
| C1 | um passo cujo hop não é uma aresta |
| C2 | um caminho que quebra, não começa em um nó fonte, ou não tem passo |
| C3 | um campo expect que a lógica contradiz |
| C4 | um caminho que termina em outro lugar que não o outcome da lógica, ou uma lógica que não dá nenhum |
| C5 | um resultado sem um kind, um kind sem legenda, mais de 4 kinds |
| C6 | um rótulo mais largo que sua caixa (13px monoespaçada) |
| C7 | um cenário sem uma origin dizendo real ou ilustrativo, e de onde |
| C8 | um par cujos cenários não podem avançar juntos, ou são desconhecidos |
| C9 | uma linha do painel que lê um campo que falta em um cenário |
| C10 | uma célula da matriz nomeando uma linha do painel que não existe |
| C11 | um caso mostrado sob uma pergunta cuja célula ainda depende de outra pergunta |
| C12 | um caso em nenhuma seção da matriz, ou uma seção nomeando um caso desconhecido |
| C13 | uma linha do painel configurada para aparecer em um passo que o cenário não tem |
C3 e C4 são o ponto: um cenário que diz algo que o código não faz não pode
ser publicado. C6 protege o layout em vez do spec: as caixas são dimensionadas
para seus rótulos, então ele dispara apenas se layout.py parar de fazer isso. Prove
que uma nova verificação morde quebrando sua entrada uma vez, em tests/. Cada verificação é uma
função em build.py, listada em CHECKS sob o id desta tabela.
Um spec que a construção não consegue ler (uma chave faltando, uma aresta para um nó desconhecido, um port que lança exceção) é recusado da mesma forma, em palavras claras, antes que as verificações sejam executadas.
Regras de design
- Um elemento móvel por diagrama: um único ponto, velocidade constante, um hop de cada vez. Dois diagramas lado a lado se movem em sincronia.
- Arestas percorridas são sólidas, não percorridas são tracejadas e cinzas; nós fora do caminho desaparecem.
- A cor codifica apenas o tipo do resultado. Em um par, a primeira divergência (o
primeiro passo onde um valor do painel difere) é contornada em âmbar e marcada
≠em ambos os lados, e o painel mostra colunas−/+. - Cenários ilustrativos apenas onde nenhum caso real atinge aquele resultado; diga de onde vem o caso real (ticket, registro, medida, data).
- Uma grid mostra um campo por célula; três campos por célula tornaram a matriz ilegível.
- Tema claro por padrão, escuro sob
prefers-color-scheme; sem fonte web, para que o arquivo funcione offline.
Arquivos
| Caminho | Função |
|---|---|
scripts/build.py | lê o spec, obtém os vereditos, executa as verificações, escreve a página e o export |
scripts/runtime.html | a página; build.py lhe dá o que ela mostra, já formatado, e nada mais do spec |
scripts/layout.py | layout em camadas: caixas dimensionadas para seus rótulos, arestas ortogonais |
examples/refund-window/ | um port JS e um par antes/depois |
examples/free-shipping/ | uma grid: duas perguntas abertas, cada uma decidida nos casos que muda |
examples/loyalty-tier/ | um oracle no próprio src/ da pasta, sua cola e o fixture que --export escreve |
Arquivos gerados (.truepath/, onde vivem os snapshots de um oracle, e *.html
ao lado de um spec) são saída da construção. Os exemplos de port mantêm seus
sim.html para que a skill possa ser vista sem executá-la. loyalty-tier não mantém nenhum: seu
rodapé nomeia o commit que produziu os vereditos, então a página muda a cada
commit, e ela é construída apenas dentro de um repositório git que a contém.
Limites
- Um tipo de diagrama: o fluxo do processo. Visualizações de sequência e arquitetura não são construídas.
C6é medida no macOS (ui-monospace); uma fonte Windows mais estreita apenas adiciona espaço.- Os passos são declarados, não derivados da lógica: C3 e C4 pegam um resultado errado, não uma mensagem intermediária errada.