SECCIÓN 08

Project Intelligence Layer (PIL)

El PIL es un índice local del proyecto que ixtli construye y mantiene en .ixtli/. Analiza el código fuente, extrae símbolos, resuelve imports y construye un grafo de dependencias entre archivos. Esto permite al backend entender el contexto de un cambio: qué funciones llaman al código modificado, qué endpoints se verían afectados, cuál es el radio de impacto.

Todo el PIL corre 100% local — sin red, sin API key, sin login. ixtli index init/update y los comandos de consulta de esta sección (endpoints, models, impact, callers, show) nunca llaman al backend. Es la misma inteligencia de código que enriquece ixtli review, pero disponible como utilidad independiente y gratuita, tanto para ti como para cualquier agente de coding que la use vía CLI o MCP — incluso sin cuenta de ixtli.

Lenguajes soportados: Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift, y más (16 extensiones en total).

Archivos del índice (en .ixtli/):

Archivo	Contenido
`index.json`	Mapa de archivos → {lenguaje, cantidad de símbolos}
`graph.json`	Grafo: archivo → {símbolos, imports resueltos}
`reverse.json`	Grafo inverso: archivo → [quién lo importa]
`confidence.json`	Puntuación de confianza por archivo (0.0–1.0)
`metadata.json`	Estadísticas globales, framework detectado, timestamp
`hashes.json`	Hashes SHA-256 de cada archivo (para actualizaciones incrementales)
`last_session.json`	Última sesión de review (para `ixtli re-review`)

El directorio .ixtli/ se agrega automáticamente al .gitignore del proyecto.

Inicializar el índice

ixtli index init

Escanea todo el proyecto, parsea los archivos fuente con tree-sitter (Python, TypeScript/JS) o con parsers regex (Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift) y construye el grafo de dependencias.

La primera vez puede tardar 10–60 segundos dependiendo del tamaño del proyecto.

Actualizar el índice

ixtli index update

Actualización incremental: solo re-indexa los archivos que cambiaron desde el último init o update (detectado por hash SHA-256). Mucho más rápido que init.

ixtli corre index update automáticamente al inicio de cada ixtli review.

Ver el estado del índice

ixtli index status

  PIL Index Status

  Root:          /home/user/projects/myapp
  Framework:     fastapi
  ORM:           sqlalchemy
  Files indexed: 142
  Symbols:       891
  Avg confidence: 0.91
  Last updated:  2026-04-18T10:30:00Z
  LSP server:    pyright

Confianza del índice:

Factor	Peso	Descripción
tree-sitter disponible	+0.40	Parser CST vs regex
Imports resueltos	+0.30×ratio	Fracción de imports que se resolvieron a archivos reales
Símbolos encontrados	+0.20	Más símbolos = mejor entendimiento
Framework detectado	+0.10	El extractor de framework encontró patrones
LSP bonus	+0.08	LSP verificó o mejoró el análisis

Un proyecto Python con pyright activo típicamente alcanza 0.93–0.97.

Explorar el índice

# Ver todos los símbolos de un archivo
ixtli index show --file src/auth.py

# Buscar un símbolo específico
ixtli index show UserService

# Buscar símbolos que contengan una cadena
ixtli index show create_user

Estos comandos leen directamente .ixtli/ y nunca tocan el backend. No requieren API key.

# Endpoints HTTP detectados (FastAPI, Flask, Django, Express, NestJS, etc.)
ixtli index endpoints
ixtli index endpoints --method POST
ixtli index endpoints --contains "/users"

# Modelos ORM detectados (SQLAlchemy, Django ORM, Prisma, TypeORM, etc.)
ixtli index models
ixtli index models --contains User

# Radio de impacto: qué archivos se rompen si modificas este
ixtli index impact src/models/user.py
ixtli index impact src/models/user.py --depth 3

# Quién usa un símbolo. Con LSP habilitado (ixtli lsp enable) da usos reales
# línea por línea (textDocument/references); sin LSP, cae a nivel archivo
# (grafo de imports).
ixtli index callers UserService

Todos aceptan --json para integrarlos en scripts o en el flujo de un agente de coding:

ixtli index endpoints --json | jq '.endpoints[] | select(.method == "POST")'

Las mismas consultas están disponibles sin CLI vía el servidor MCP (get_endpoints, get_models, get_impacted_files, get_symbol_info, search_symbols — ver sección 12), también sin requerir autenticación.

Limpiar el índice

ixtli index clear

Elimina el directorio .ixtli/. El próximo review o index update creará el índice desde cero.

Detección de framework

El PIL detecta automáticamente el framework y ORM del proyecto:

Frameworks web: FastAPI, Flask, Django, Express, NestJS, Next.js, Gin, Echo, Fiber, Axum, Actix, Rails, Sinatra, Spring, Ktor, Laravel, ASP.NET, Vapor

ORMs: SQLAlchemy, Django ORM, Prisma, TypeORM, GORM, ActiveRecord, Eloquent, Entity Framework

Una vez detectado el framework, extractores específicos marcan símbolos como kind="endpoint" o kind="model", lo que permite reportar los endpoints HTTP afectados por un cambio.

Historial de reviews e issues Git Hooks