ArchitectOS

---

Mandato Estricto del Producto: ArchitectOS nunca modifica el código del usuario directamente; exclusivamente analiza, explica, calcula el impacto y genera planes de refactorización accionables. Las modificaciones de código son ejecutadas por Agentes de IA o desarrolladores humanos.

---

⚡ Inicio Rápido y Comandos Básicos

# 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

---

🏛️ El Pipeline de 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

---

🎯 Características de Precisión y Exactitud del Motor

• Motor SAST con 25 mapeos CWE: Reglas de alta precisión que cubren SQLi, XSS, RCE, ReDoS, Prototype Pollution, NoSQLi, Open Redirect, Unsafe Deserialization y Weak Cryptography.
• Filtro de Ruido Contextual: Suprime automáticamente falsos positivos dentro de bloques de prueba (describe/it), comentarios JSDoc, ramas condicionales muertas y cuando se detectan sanitizadores conocidos (DOMPurify, escapeHtml).
• Motor de Rastreo de Flujo de Datos Multi-Archivo: Rastrea entradas de usuario no confiables (HTTP req.body/searchParams) hasta los sinks de ejecución peligrosos a través de grafos de importación multi-archivo.
• Escáner de Duplicación de Código: Motor de similitud Jaccard con huellas de tokens que detecta bloques de código copiados y pegados entre paquetes de monorepos.
• Lista Blanca de Puntos de Entrada de Frameworks: Elimina falsos positivos para Next.js (GET, POST, generateMetadata, middleware), Remix, Vitest y puntos de entrada CLI.
• Detección de Ciclos SCC de Tarjan: Detección de ciclos de dependencia circular matemáticamente sólida para monorepos complejos.
• Transparencia Pública de Puntuación: Fórmulas y reglas de deducción completamente documentadas en SCORING.md.

---

🧪 Verificación de Benchmarks del Mundo Real (Desglose del Motor v1.2.1)

ArchitectOS está probado en combate y se usa en su propio desarrollo en bases de código de código abierto importantes con puntuación transparente de submétricas:

Repositorio	Archivos	General	Arq	Seg	Cal	IA	UI	Velocidad de Escaneo	Área de Enfoque Principal
excalidraw/excalidraw	520+	88/100	92	84	90	94	80	<18ms	Descomposición de Componentes Canvas
calcom/cal.com	1,400+	84/100	80	88	82	90	80	<45ms	Aislamiento de la Capa de Servicio de Reservas
shadcn/ui	120+	96/100	98	95	96	95	96	<8ms	Límites de Primitivas de Componentes de UI
cgseyhan/architectos	51	100/100	100	100	100	100	N/A	<19ms	Gobernanza AST Autoalojada Nativa

Nota: Los repositorios puramente CLI / backend (por ejemplo, architectos) omiten la puntuación de Arquitectura de UI.

---

🤖 Integración Nativa del Servidor MCP

Añade ArchitectOS a tu configuración MCP de Claude Code, Cursor o Codex:

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

Herramientas MCP Registradas

• architectos_review: Desglose de salud y problemas del repositorio.
• architectos_why: Análisis de acoplamiento de causa raíz.
• architectos_impact: Calculadora de impacto de cambios políglota.
• architectos_plan: Plan de refactorización y migración paso a paso.
• architectos_resolve: Resolvedor de símbolos y escudo contra alucinaciones.
• architectos_dead: Detector de exportaciones no utilizadas y código zombi.
• architectos_ui: Auditoría de composición y límites de componentes de UI independiente del framework.
• architectos_remember: Almacenar reglas de protección arquitectónicas persistentes.

---

📄 Licencia

Licencia MIT © 2026 Autores de ArchitectOS