Hub de Entendimento & Segurança — Ondas 0, 1, 2¶

O "espaço de inteligência" do copilot/. Esta página é o índice ("wiki dos wikis"): de um lugar só você chega em todos os mapas, e sabe como cada um se atualiza.

Regra mental do stack: verdade medida (roda e reflete a realidade, sem IA) → intenção autorada (você declara) → narrativa (IA/prompt explica). O que está aqui é majoritariamente a base: verdade medida.

TL;DR — comandos¶

Portal visual (MkDocs Material)¶

O hub, o catálogo, a arquitetura e os ADRs viram um site navegável (lê o analises/):

pnpm portal:dev     # serve o portal em http://127.0.0.1:8000
pnpm portal:build   # site estático -> portal-site/

Pré-requisito (uma vez): pip install --user mkdocs-material. Deploy sugerido: Cloudflare Pages.

# a partir de copilot/
pnpm docs:diagrams        # regenera TODOS os artefatos visuais de uma vez
pnpm depcruise:check      # valida as regras de arquitetura (lado TS)
pnpm depcruise:graph      # gera o grafo de deps em Mermaid
pnpm codecharta:generate  # gera a "cidade 3D" (cc.json)
pnpm likec4:dev           # arquitetura interativa (abre no navegador)
pnpm likec4:mermaid       # gera os diagramas C4 em Mermaid
pnpm --filter @copilot/database db:dbml   # gera o ERD do banco (DBML)

Quer responder…	Ferramenta	Artefato	Como atualiza
"O que depende do quê / o que quebra"	dependency-cruiser	`analises/diagramas/dep-graph.mmd`	`pnpm depcruise:graph`
"Como o banco se liga"	Drizzle→DBML + Azimutt	`packages/database/docs/schema.dbml`	`pnpm db:dbml`
"Onde está a complexidade"	CodeCharta	`analises/codecharta/copilot.cc.json`	`pnpm codecharta:generate`
"Tem segredo vazado?"	Gitleaks (CI)	check no PR	automático no CI
"Tem padrão inseguro?"	Semgrep (CI)	SARIF (artifact)	automático no CI
"Dependência vulnerável?"	Dependabot	PRs automáticos	automático (semanal)

Onda 0 — Segurança (CI)¶

Antes não havia nenhuma checagem de segurança no ci.yml. Agora há três.

1. Gitleaks — segredos vazados¶

Arquivo: job gitleaks em .github/workflows/ci.yml.
O que faz: varre todo o histórico do git procurando tokens/chaves/senhas.
Por que importa aqui: existem apps/worker/token.json e arquivos .env no repo — exatamente o tipo de coisa que o AGENTS.md manda manter fora do git. O Gitleaks avisa se algum cair no versionamento.
Bloqueante de propósito: segredo no repo é incidente, não aviso.
Nota: grátis para conta pessoal/repo. Em organização exige GITLEAKS_LICENSE (também gratuita).

2. Semgrep — SAST (padrões inseguros)¶

Arquivo: job semgrep em ci.yml. Cobre TS e Python (p/typescript, p/python, p/secrets, p/default).
Modo atual: informativo (não usa --error) — reporta sem travar o merge. O resultado vai como artifact semgrep-sarif.
Para deixar bloqueante depois: troque o comando por semgrep ci com --error, ou marque o job como required check nas settings do repo.

3. Dependabot — supply chain¶

Arquivo: .github/dependabot.yml.
Cobre os dois ecossistemas: npm (em /copilot) e pip (no worker Python em /copilot/apps/worker), mais as próprias GitHub Actions.
O que faz: abre PRs automáticos quando uma dependência tem vulnerabilidade/atualização. Updates de patch/minor vêm agrupados pra não te inundar.

Onda 1 — Arquitetura¶

4. dependency-cruiser¶

Config: .dependency-cruiser.js + tsconfig.depcruise.json (resolve o alias @/ da raiz).
Cobre o lado TS: apps/web, apps/extension, packages/*. O worker é Python e não entra.
Duas funções: entender (grafo) e proteger (regras de fronteira no CI).

Regras configuradas: | Regra | Severidade | Significado | |---|---|---| | no-circular | error | Dependência circular A→…→A | | packages-nao-importam-apps | error | packages/* não pode depender de apps/* | | apps-nao-se-importam | error | Um app não importa o interior de outro app | | sem-orfaos | warn | Arquivo que ninguém importa (código morto?) | | dev-dep-em-prod | warn | Código de prod importando devDependency | | import-nao-resolvido | warn | Import que não resolve |

Como ver o grafo: abra analises/diagramas/dep-graph.mmd (renderiza no GitHub, VS Code com extensão Mermaid, ou em https://mermaid.live).

⚠️ Primeira descoberta real (9 ciclos)¶

Na primeira rodada o depcruise:check achou 9 dependências circulares, todas no schema do banco. Causa exata:

// packages/database/src/schema/org-playbook.ts
import { organizations, playbookPresets } from "./index"   // ❌ via barrel

O arquivo importa os vizinhos pelo barrel ./index, e o index.ts re-exporta org-playbook de volta → ciclo. Fix (quebra o ciclo, é mecânico e seguro):

import { organizations } from "./organizations"     // ✅ import direto do vizinho
import { playbookPresets } from "./playbook-presets"

Não quebra nada hoje (o Drizzle tolera), mas é o motivo nº1 de build incremental lento e de "por que mexer aqui afeta lá". Posso aplicar esse fix em todos os arquivos afetados se você quiser — é só pedir.

Também houve 22 warnings de órfãos (ex.: components/ui/* não usados, _proxy-desativado.ts) — candidatos a limpeza, sem urgência.

CI: os jobs novos (gitleaks, semgrep, architecture) não são required checks ainda, então aparecem no PR mas não bloqueiam merge. Quando você confiar neles, marque como required em Settings → Branches.

5. Semgrep¶

Coberto na Onda 0 (é o SAST). Vale tanto como segurança quanto como qualidade.

Onda 2 — Entendimento visual¶

6. ERD do banco (Drizzle → DBML → Azimutt)¶

Script: packages/database/scripts/generate-dbml.ts · Saída: packages/database/docs/schema.dbml.
Resultado atual: 41 tabelas, 62 relacionamentos, derivados das FKs (.references()) do schema.
Substitui teu fluxo manual: nada de "pedir o comando pra IA e colar no editor". É gerado do schema, sempre verdadeiro.
Como visualizar:
Azimutt (https://azimutt.app) → New project → Import → DBML (melhor para schema grande: agrupa, esconde o que não importa).
dbdiagram.io → cola o conteúdo de schema.dbml.
Observação: o DBML lista user duas vezes — vale conferir se é export duplo no schema (better-auth) ou só quirk do gerador. Não é bloqueante.

7. CodeCharta — cidade 3D (versão sem Java)¶

Script: scripts/generate-codecharta.mjs · Saída: analises/codecharta/copilot.cc.json.
Resultado atual: 431 arquivos analisados (apps + packages).
Por que custom: o CodeCharta oficial (ccsh) é Java, e não há Java no ambiente. Este gerador calcula métricas reais e leves (linhas de código, comentários, proxy de complexidade e de nº de funções) e emite o .cc.json direto — valor imediato, zero setup.
Como visualizar: abra https://codecharta.com (ou a extensão CodeCharta do VS Code) e arraste o arquivo copilot.cc.json. Cada prédio = um arquivo; altura/área/cor = métrica.
Upgrade futuro (métricas mais ricas): instalar Java + ccsh e usar importers (Sonar, MetricGardener, git churn) — aí entram complexidade ciclomática real e hotspots por churn.

Onda 3 — Arquitetura curada & Catálogo¶

Arquitetura (LikeC4)¶

Modelo (você cura): o arquivo analises/likec4/model.likec4 — camada de intenção autorada (C4: contexto + containers). Não é gerado do código; você ajusta as relações conforme a realidade. O primeiro desenho é um rascunho.
Visual: veja a página Arquitetura (imagens nítidas via pnpm likec4:png). Auto-regenerável em Mermaid via pnpm likec4:mermaid.
Interativo: pnpm likec4:dev (abre no navegador, navegável/zoom). · Site estático: pnpm likec4:build.
Diferença pro resto: LikeC4 = "como eu decido que o sistema é"; dependency-cruiser/CodeCharta = "como o código está de fato".

Catálogo de serviços¶

STACK.md — todos os provedores/serviços nos 6 planos (infra, jobs, integrações, AI ops, observabilidade, qualidade/segurança). Forward-compatible para catalog-info.yaml (Port/Backstage).

Juntos, STACK.md (quais serviços existem) + LikeC4 (como se conectam) + os diagramas das Ondas 1-2 (deps, banco, cidade) formam o "espaço de inteligência": de um lugar você vê serviços, arquitetura e saúde do código.

Status¶

Onda	Item	Estado
0	Gitleaks	✅ configurado no CI
0	Semgrep	✅ configurado no CI (informativo)
0	Dependabot	✅ configurado (npm + pip + actions)
1	dependency-cruiser	✅ rodando — achou 9 ciclos + 22 órfãos
1	regras de arquitetura	✅ no CI (job `architecture`)
2	ERD / DBML / Azimutt	✅ 41 tabelas, 62 refs
2	CodeCharta	✅ 431 arquivos (versão sem Java)
3	LikeC4 (modelo + visual)	✅ modelo válido, 3 views em Mermaid (rascunho a curar)
3	STACK.md (catálogo)	✅ 6 planos pré-preenchidos (campos `TODO` a completar)

Próximos passos sugeridos (não feitos — dependem da tua decisão)¶

Aplicar o fix dos 9 ciclos (import direto em vez de barrel) no schema.
Marcar os jobs de CI como required checks quando confiar neles.
Deixar o Semgrep bloqueante (--error) após revisar os primeiros achados.
(Opcional) instalar Java para o CodeCharta "full" com churn/complexidade real.
Curar o modelo LikeC4 (likec4/model.likec4): corrigir as relações do rascunho conforme a realidade.
Completar os campos TODO do STACK.md (custos, env vars exatas).