ArchitectOS

---

Mandato Estrito do Produto: O ArchitectOS nunca modifica o código do usuário diretamente; ele exclusivamente analisa, explica, calcula impacto e gera planos de refatoração acionáveis. Modificações de código são executadas por Agentes de IA ou desenvolvedores humanos.

---

⚡ Início Rápido e Comandos Principais

# 1. Initialize and review repository
npx architectos

# 2. High-level repository health, security & UI review (with optional CI threshold)
architectos review
architectos review --threshold 80

# 3. Component deep-dive (supports --why, --ui, --dead, --duplication, --taint)
architectos analyze toolbar.tsx
architectos analyze toolbar.tsx --why
architectos analyze --ui
architectos analyze --dead
architectos analyze --duplication
architectos analyze --taint auth.controller.ts

# 4. View historical score timeline and trend
architectos history

# 5. Cross-graph downstream change impact & risk rating
architectos impact auth.ts

# 6. Structured refactoring migration plan
architectos plan toolbar.tsx

# 7. Symbol resolver & natural language architecture query
architectos resolve WorkspaceRepository
architectos resolve "Where is tenant isolation enforced?"

# 8. Native MCP server gateway & live watcher
architectos watch
architectos mcp

---

🏛️ O Pipeline do ArchitectOS

architectos review               # High-level health & problem breakdown (--threshold 80)
      ↓
architectos analyze <target>     # Deep-dive (--why, --ui, --dead, --duplication, --taint)
      ↓
architectos impact <target>      # Cross-graph downstream change risk
      ↓
architectos plan <target>        # Step-by-step refactoring migration plan
      ↓
architectos resolve <symbol>     # Hallucination shield & symbol resolver
      ↓
architectos history              # Historical score timeline & trend tracking
      ↓
AI Agent / Developer executes refactor

---

🎯 Recursos de Precisão e Exatidão do Mecanismo

• Mecanismo SAST com 25 mapeamentos CWE: Regras de alta precisão cobrindo SQLi, XSS, RCE, ReDoS, Prototype Pollution, NoSQLi, Open Redirect, Desserialização Insegura e Criptografia Fraca.
• Filtro de Ruído Sensível ao Contexto: Suprime automaticamente falsos positivos dentro de blocos de teste (describe/it), comentários JSDoc, ramos condicionais mortos e quando sanitizadores conhecidos (DOMPurify, escapeHtml) são detectados.
• Mecanismo de Rastreamento de Taint Multi-Arquivo: Rastreia entradas de usuário não confiáveis (HTTP req.body/searchParams) até sinks de execução perigosos em grafos de importação multi-arquivo.
• Scanner de Duplicação de Código: Mecanismo de similaridade Jaccard com impressão digital de tokens que detecta blocos de código copiados e colados em pacotes de monorepo.
• Lista de Permissões de Entrypoints de Frameworks: Elimina falsos positivos para Next.js (GET, POST, generateMetadata, middleware), Remix, Vitest e entrypoints de CLI.
• Detecção de Ciclos SCC de Tarjan: Detecção de ciclos de dependência circular matematicamente sólida para monorepos complexos.
• Transparência Pública de Pontuação: Fórmulas e regras de dedução totalmente documentadas em SCORING.md.

---

🧪 Verificação de Benchmark no Mundo Real (Detalhamento do Mecanismo v1.2.1)

O ArchitectOS é testado em batalha e usado internamente em grandes codebases de código aberto com pontuação transparente por sub-métrica:

Repositório	Arquivos	Geral	Arq	Seg	Qual	IA	UI	Velocidade de Varredura	Principal Área de Foco
excalidraw/excalidraw	520+	88/100	92	84	90	94	80	<18ms	Decomposição de Componentes Canvas
calcom/cal.com	1.400+	84/100	80	88	82	90	80	<45ms	Isolamento da Camada de Serviço de Reservas
shadcn/ui	120+	96/100	98	95	96	95	96	<8ms	Limites de Primitivas de Componentes de UI
cgseyhan/architectos	51	100/100	100	100	100	100	N/A	<19ms	Governança de AST Auto-hospedada Nativa

Nota: Repositórios puramente CLI / backend (ex.: architectos) omitem a pontuação de Arquitetura de UI.

---

🤖 Integração Nativa com Servidor MCP

Adicione o ArchitectOS à sua configuração MCP do Claude Code, Cursor ou Codex:

{
  "mcpServers": {
    "architectos": {
      "command": "npx",
      "args": ["-y", "architectos", "mcp"]
    }
  }
}

Ferramentas MCP Registradas

• architectos_review: Saúde do repositório e detalhamento de problemas.
• architectos_why: Análise de acoplamento de causa raiz.
• architectos_impact: Calculadora de impacto de mudanças poliglota.
• architectos_plan: Plano de refatoração de migração passo a passo.
• architectos_resolve: Resolvedor de símbolos e escudo contra alucinações.
• architectos_dead: Detector de exports não utilizados e código zumbi.
• architectos_ui: Auditoria de composição e limites de componentes de UI agnóstica de framework.
• architectos_remember: Armazena regras persistentes de salvaguarda arquitetural.

---

📄 Licença

Licença MIT © 2026 Autores do ArchitectOS