amirtaherkhani/diago

Archify

Crie um diagrama HTML interativo e autocontido a partir de uma especificação JSON tipada e pequena. A saída estática é o padrão; habilite movimento apenas quando o usuário solicitar uma demonstração ou apresentação.

Caminho de autoria rápido

Use este caminho limitado para geração comum. Não leia a referência opcional do Visualizador em Tempo de Execução, a menos que o usuário pergunte sobre esses recursos.

1. Escolha architecture, workflow, sequence, dataflow ou lifecycle a partir da pergunta.

2. Leia um esquema correspondente em schemas/, schemas/common.schema.json e um exemplo JSON correspondente em examples/. Leia apenas esses arquivos. Autoria nova significa novos IDs estáveis, terminologia de domínio e layout; use o exemplo para a forma dos campos, não para fatos.

3. Artefato primeiro: a próxima ação da ferramenta deve escrever o candidato. Escreva o candidato antes de inspecionar os mecanismos internos do renderizador. Não planeje coordenadas exatas em prosa. Comece com um caminho principal claro, ramificações laterais curtas, rótulos esparsos e no máximo 12 nós primários. Defina meta.quality_profile como "showcase", a menos que o usuário solicite explicitamente um mapa denso standard. Comece com roteamento e rótulos automáticos. Não adicione via, channelX, channelY ou labelAt antes que um diagnóstico exija um; aplique no máximo um controle de geometria diagnosticado por reparo.

4. Valide após cada edição do candidato e imediatamente antes da transferência:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   Um recibo com apenas 4 verificações de artefato é validação básica, nunca aceitação de showcase. Uma aprovação showcase deve relatar todas as 9 verificações de artefato com 0 erros de composição e 0 avisos. Se o candidato omitir ou escrever incorretamente o campo exato meta.quality_profile, corrija-o antes da geometria. Uma validação final aprovada congela o candidato: nunca o edite depois disso.

5. Para um HTML entregue, deliver é o comando de aceitação final:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   Uma saída diferente de zero nunca pode ser descrita como sucesso. Se a validação falhar, altere apenas o subject diagnosticado, verifique evidence, escolha entre supportedFixes e execute novamente. Continue a correção focada enquanto a contagem de erros objetivo atingir um novo mínimo. Se duas rodadas consecutivas não melhorarem essa melhor contagem, pare e relate os diagnósticos não resolvidos com veracidade.

Não leia renderers/shared/geometry.mjs, código-fonte do renderizador, código-fonte do validador, testes ou benchmarks antes do primeiro candidato. Inspecione a implementação apenas para um diagnóstico interno não suportado ou após dois reparos focados falharem.

Nota sobre ciclo de vida: as colunas de fase 0..4 ocupam a trilha principal; as colunas de evento/resultado 0..2 alinham-se abaixo das fases posteriores. Um estado recuperável usa type: "failure" mais uma transição real de volta ao estado ativo.

Roteador de tipos

Tipo	Uso para
architecture	Componentes, serviços, limites de nuvem/segurança, infraestrutura
workflow	Processos, portas de aprovação, chamadas de ferramenta, runbooks, CI/CD
sequence	Cadeias de chamadas de API, ciclos de vida de requisição, rastreamentos assíncronos, retornos
dataflow	Pipelines, ETL/ELT, linhagem, governança, consumidores
lifecycle	Transições de estado/status, novas tentativas, estados de espera e terminais

Quando ambíguo, execute node bin/archify.mjs guide "<scenario>" --json. Exemplos de prova de cenário são referências estruturais, não fatos a copiar.

Entrada Mermaid

Leia Mermaid para topologia e significado, depois crie um novo JSON Archify; não renderize mecanicamente o estilo Mermaid.

• flowchart / graph → workflow, ou architecture para um mapa de componentes.
• sequenceDiagram → sequence; os participantes tornam-se participantes semânticos e as setas tornam-se mensagens.
• stateDiagram → lifecycle; estados e transições retêm o significado, não o estilo Mermaid.

Invariantes de autoria

• Um caminho principal óbvio; ramificações laterais saem do nó do caminho principal mais próximo. Remova arestas de baixo valor antes de adicionar controles de roteamento.
• Omita meta.legend para o padrão verdadeiro auto. Quando necessário, use apenas mode: auto|all|hidden e entries.<kind>.label|visible suportados pelo renderizador; rótulos nunca alteram a semântica.
• Os tipos de componente são frontend, backend, database, cloud, security, messagebus e external; as variantes são default, emphasis, security e dashed.
• Espaçamento significa lacuna clara, não distância do centro. Para um rótulo de relacionamento, a lacuna clara deve exceder sua largura de máscara medida; caso contrário, omita o rótulo ou mova-o deliberadamente.
• Rotas automáticas possuem seus próprios lados de ponto final. Um lado é um contrato de direção: o primeiro e o último segmento devem sair/entrar perpendicularmente a esse lado.
• O Espalhamento de Portas Automático é um comportamento padrão do renderizador para arquitetura, workflow, data-flow e ciclo de vida. Ele ignora relacionamentos únicos e via, channelX, channelY, labelAt ou rotas não auto explícitas. Portas quase paralelas usam uma ponte externa para que o roteamento automático não possa criar um segmento menor que 8px ou uma curva interna menor que 16px.
• Nunca aceite uma aresta cruzando um nó opaco não relacionado, um corredor compartilhado ambíguo ou um rótulo de relacionamento mascarando outra rota.

Leia references/authoring-contract.md apenas quando você precisar de enums de campo, matemática de espaçamento, regras de reparo de geometria, evidências de repositório ou posicionamento específico de modo.

Entrega

Use validate durante o reparo e deliver uma vez para aceitação final. A entrega congela os bytes exatos da especificação em um instantâneo privado no mesmo diretório, renderiza e verifica esse instantâneo, confirma o HTML atomicamente e relata SHA-256 mais contagens de bytes para especificação e artefato.

Adicione --open apenas quando o usuário quiser uma prévia local imediata. Para um ciclo de autoria ativo na área de trabalho, o comando opcional é:

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

Nunca inicie a prévia por padrão. Leia references/delivery-contract.md ao usar prévia, evidências de repositório, recibos de exportação, revisão visual ou abertura pós-confirmação.

Recursos opcionais do visualizador

O HTML gerado já contém troca de temas, pan/zoom, busca, foco, rastreamento de relacionamentos, visualizações semânticas, apresentação e exportações verdadeiras. Estes são recursos do leitor, não trabalho extra de autoria. meta.animation: "trace" é opcional; meta.views é opcional e deve conter no máximo cinco capítulos selecionados.

Leia references/viewer-runtime.md apenas quando o usuário solicitar explicitamente Cartões de Compartilhamento, Cartões de Rota/Alcance, movimento, histórias guiadas, links profundos, apresentação, busca/foco ou outro recurso do Visualizador em Tempo de Execução.

Configuração e fallback

Nenhuma instalação é necessária dentro do pacote da skill. Verifique com:

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

Quando o acesso ao shell não estiver disponível, coloque manualmente o SVG de arquitetura em assets/template.html, use classes CSS semânticas em vez de cores inline e siga o contrato de revisão visual em references/delivery-contract.md.

Saída

Retorne o caminho HTML verificado, o tipo de diagrama, o resumo da validação, o recibo de especificação/artefato e o status verdadeiro da revisão visual. Não reivindique sucesso para um comando com saída diferente de zero nem reivindique inspeção visual que você não realizou.