🧠 codebase-synapse

Motor de indexación semántica, análisis de grafos de dependencias y servidor MCP (Model Context Protocol) de alto rendimiento, diseñado para transformar bases de código complejas en grafos de conocimiento estructurados y consultables por agentes de Inteligencia Artificial y desarrolladores.

codebase-synapse actúa como la "sinapsis" cognitiva del código fuente. Utilizando Rust como lenguaje base por su seguridad y velocidad extrema, el sistema genera embeddings semánticos locales, construye árboles de Merkle para el control de versiones del índice, procesa consultas complejas mediante un motor de tipo Cypher simplificado y proporciona análisis topológicos profundos sobre el acoplamiento y el riesgo del software.

---

🚀 Descripción General del Proyecto

En proyectos de gran envergadura, comprender las relaciones lógicas, el impacto de los cambios y la semántica detrás de las funciones es una tarea titánica para los seres humanos y las herramientas de análisis estático tradicionales. codebase-synapse resuelve esto mediante tres pilares fundamentales:

1. Indexación Inteligente de Código: Escanea de forma proactiva el sistema de archivos (src/indexer/), analiza sintácticamente el código de múltiples lenguajes (src/parser/) e implementa un sistema de control de cambios rápido basado en árboles de Merkle (merkle.rs) y observadores en tiempo real (watcher.rs).
2. Análisis de Grafos Avanzado: Mapea la base de código como un grafo multidimensional. Permite calcular el acoplamiento dinámico (change_coupling.rs), la criticidad con PageRank (pagerank.rs), la modularidad del código mediante el algoritmo de Leiden (leiden.rs) y realizar análisis predictivos de impacto y riesgo (impact.rs, risk.rs).
3. Búsqueda Híbrida y Semántica: Combina la precisión léxica de un motor BM25 con la potencia contextual de embeddings vectoriales generados localmente a través de la librería Candle de Hugging Face (candle.rs), permitiendo consultas semánticas y de similitud de grano fino.
4. Puente para Agentes de IA (MCP): Implementa de forma nativa el estándar Model Context Protocol (src/mcp/), permitiendo que LLMs y asistentes de IA interactúen directamente con las herramientas de análisis de grafos y búsqueda del repositorio de forma estandarizada.

---

🛠️ Tecnologías y Librerías Utilizadas

El núcleo del sistema está construido en Rust para garantizar la latencia ultra baja y la eficiencia en memoria necesarias para procesar repositorios de millones de líneas de código.

• Rust (Edición Reciente): Garantía de seguridad en memoria sin recolector de basura.
• Hugging Face Candle: Framework de Machine Learning minimalista en Rust para la ejecución local y ultrarrápida de modelos de embeddings.
• Model Context Protocol (MCP): Protocolo abierto para la integración segura de herramientas con LLMs (Claude, GPTs, etc.).
• Motor de Grafos a Medida: Algoritmos avanzados implementados directamente para análisis estructural de código (Leiden, PageRank, DFS/BFS traversals).
• Parser de Consultas Cypher: Un subset personalizado de analizador sintáctico y planificador de ejecución para buscar patrones en el grafo de código.
• Nginx / Alpine Docker (Opcional): Capa de proxy o servicio estático auxiliar provisto en la raíz.

---

📂 Estructura del Repositorio

A continuación se detalla la arquitectura de módulos en src/:

src/
├── main.rs                   # Punto de entrada principal de la aplicación CLI y servicios.
├── lib.rs                    # Exportación de la biblioteca y módulos principales.
├── config.rs                 # Gestión de configuración del sistema (.env, mem0.yaml).
├── access/                   # Control de acceso y seguridad de las consultas.
├── cli/                      # Interfaz de línea de comandos (gestión de artefactos).
│   └── artifact.rs
├── context/                  # Gestor del contexto de ejecución y estado global.
├── cypher/                   # Motor de base de datos de grafos integrado.
│   ├── parser.rs             # Parser léxico y sintáctico para subconjunto de Cypher.
│   └── planner.rs            # Planificador de ejecución de consultas de grafos.
├── db/                       # Interfaz de persistencia (esquemas y consultas).
│   ├── schema.rs
│   └── queries.rs
├── embedding/                # Generación de embeddings vectoriales.
│   └── candle.rs             # Integración nativa con modelos de Candle.
├── graph/                    # Algoritmos avanzados de grafos aplicados al código.
│   ├── builder.rs            # Generador del grafo de dependencias y llamadas.
│   ├── boundaries.rs         # Detección de fronteras de dominio arquitectónico.
│   ├── change_coupling.rs    # Detección de acoplamiento de cambios temporales.
│   ├── impact.rs             # Análisis de impacto (qué se rompe si modifico X).
│   ├── intent.rs             # Análisis de intención y semántica del flujo.
│   ├── leiden.rs             # Algoritmo de Leiden para clustering del código.
│   ├── pagerank.rs           # Cálculo de la relevancia e importancia de un archivo/función.
│   ├── risk.rs               # Estimación de riesgo basado en complejidad y cambios.
│   └── traversal.rs          # Algoritmos de recorrido (DFS, BFS, etc.).
├── indexer/                  # Motor de rastreo e indexación física del disco.
│   ├── calls.rs              # Extracción de llamadas a funciones/métodos.
│   ├── infra.rs              # Abstracción de infraestructura.
│   ├── manifests.rs          # Parsing de manifiestos (Cargo.toml, package.json, etc.).
│   ├── merkle.rs             # Árbol de Merkle para hashing rápido de cambios.
│   ├── routes.rs             # Enrutamiento de eventos del indexador.
│   ├── walker.rs             # Rastreador de archivos concurrentes.
│   └── watcher.rs            # Monitoreo de cambios en caliente.
├── mcp/                      # Implementación del Model Context Protocol.
│   ├── protocol.rs           # Manejo de mensajes del protocolo.
│   ├── transport.rs          # Transporte del protocolo (Stdio / SSE / WebSockets).
│   ├── tools.rs              # Herramientas expuestas para el LLM.
│   └── architecture.rs       # Estructura del servidor MCP.
├── parser/                   # Parser AST multilinguaje.
│   └── language.rs           # Identificación y parsing específico de sintaxis de programación.
├── search/                   # Capa de búsqueda.
│   ├── bm25.rs               # Búsqueda léxica clásica de texto completo.
│   ├── vector.rs             # Búsqueda espacial por proximidad de embeddings.
│   └── hybrid.rs             # Fusionador de resultados (RRF) para búsqueda híbrida.
└── similarity/               # Cálculo de distancias y métricas de similitud.

---

🛠️ Instalación y Configuración Local

Requisitos Previos

• Rust: Tener instalado el compilador rustc y el gestor de paquetes cargo (MSRV recomendado: 1.75+).
• Modelos de Embeddings: Asegúrate de contar con conexión a internet en la primera ejecución para descargar el modelo de embedding por defecto a través de Candle (ej. all-MiniLM-L6-v2 o similar según configuración).

Configuración del Entorno

Copia el archivo de variables de entorno de ejemplo y ajusta los parámetros necesarios:

cp .env.example .env  # Si existe, o crea uno con las claves necesarias

El archivo mem0.yaml puede usarse para configurar las opciones del almacén de memoria a largo plazo del indexador.

Compilación y Ejecución

Para compilar el proyecto en modo de desarrollo:

cargo build

Para arrancar el indexador y el servidor de comandos:

cargo run --bin codebase-synapse -- [opciones]

Para compilar una versión altamente optimizada para producción:

cargo build --release

Ejecutar las Pruebas Unitarias y de Integración

cargo test

---

🔌 Uso con el Model Context Protocol (MCP)

codebase-synapse expone un servidor de herramientas MCP que puede configurarse en clientes compatibles (como Claude Desktop, Cursor o VS Code). Esto permite a un agente inteligente solicitar la ejecución de PageRank sobre tus archivos, buscar semánticamente funciones o trazar el grafo de llamadas directamente desde el chat.

Para iniciarlo en modo transporte stdio (estándar para integraciones locales):

cargo run --release -- --mcp-stdio

---

⚙️ Gobernanza del Proyecto

Este repositorio sigue directrices estrictas de desarrollo y calidad automatizada:

• Formateado y Linting: Se utiliza Biome (biome.json) para mantener la coherencia en archivos JSON, Javascript/Typescript del ecosistema, y herramientas de soporte.
• Git Hooks: Se gestionan mediante Lefthook (lefthook.yml), el cual ejecuta validaciones previas a cada commit para garantizar que el código de Rust pase el compilador, las pruebas y los análisis de formato de manera automática.
• Auditorías de Seguridad: Se ejecutan localmente mediante el script security_audit.sh y la herramienta Bumblebee para detectar dependencias vulnerables y malas prácticas.
• Protección de Calidad: El archivo .no-mistakes.yaml actúa como proxy y guardián de calidad en los pipelines de despliegue continuo (CI/CD).

---

Megacore - Automatizando y estandarizando la calidad del software en Megasoft.