SECCIÓN 05

Review de código

El comando principal. Analiza archivos en busca de bugs, vulnerabilidades de seguridad y problemas de calidad.

Uso básico — archivos staged

git add src/auth.py
ixtli review

Por defecto, ixtli revisa los archivos en el staging area de git.

Archivos específicos

ixtli review src/auth.py src/models/user.py

Puedes especificar cualquier archivo, esté staged o no.

Incluir archivos no staged

ixtli review --unstaged      # archivos modificados sin stagear
ixtli review --all           # staged + unstaged

Todas las opciones

Flag	Descripción	Default
`--unstaged`	Incluir archivos modificados no staged	`false`
`--all`	Staged + unstaged	`false`
`--json`	Output en JSON (para scripts o CI)	`false`
`--quiet`	Silencioso a menos que haya issues. Sale con código 1 si hay issues high/critical	`false`
`--min-severity`	Severidad mínima a mostrar: `critical`, `high`, `medium`, `low`	`low`
`--include-fix`	Incluir código corregido en cada issue	`false`
`--ticket <ref>`	Vincular manualmente un ticket de issue tracker	—
`--no-ticket`	Deshabilitar contexto de ticket para este review	`false`

Severidades

Nivel	Descripción
`critical`	Vulnerabilidades de seguridad, data loss, crashes. Bloquea CI.
`high`	Bugs importantes, race conditions, memory leaks
`medium`	Code smells, malas prácticas que pueden causar problemas
`low`	Sugerencias de estilo, optimizaciones menores

Output de ejemplo

  Submitting 2 file(s) for review...
  ✓ Ticket context: jira PROJ-42 — Refactor authentication layer

  ╭────────────┬─────────────┬────────┬──────────────────┬───────────────────────╮
  │ Severity   │ File        │   Line │ Issue            │ Suggestion            │
  ├────────────┼─────────────┼────────┼──────────────────┼───────────────────────┤
  │ CRITICAL   │ src/auth.py │     42 │ SQL Injection    │ Usar queries          │
  │            │             │        │                  │ parametrizadas:       │
  │            │             │        │                  │ cursor.execute('...', │
  │            │             │        │                  │ (user_id,))           │
  ├────────────┼─────────────┼────────┼──────────────────┼───────────────────────┤
  │ HIGH       │ src/auth.py │     87 │ Hardcoded secret │ Mover a variable de   │
  │            │             │        │                  │ entorno:              │
  │            │             │        │                  │ os.environ['SECRET_K… │
  ╰────────────┴─────────────┴────────┴──────────────────┴───────────────────────╯

  Mode: Agent IA  |  Critical: 1  High: 1  Medium: 0  Low: 0

Mode: Agent IA indica que el análisis pasó por el motor LLM completo; Mode: Static indica que corrió solo el pre-análisis basado en AST (por ejemplo, si se agotó la cuota — ver "Quota exhausted").

Si filtras con --min-severity y hay issues por debajo del umbral, la tabla lo indica en vez de dejarlo en silencio:

  3 more issue(s) below 'high' severity not shown — run with --min-severity low to see all.

Output JSON

ixtli review --json

{
  "status": "completed",
  "analysis_mode": "llm",
  "review_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "files_analyzed": 2,
  "issues": [
    {
      "id": "abc123",
      "severity": "critical",
      "filename": "src/auth.py",
      "line": 42,
      "issue": "SQL Injection via unsanitized user_id",
      "suggestion": "Use parameterized queries: cursor.execute('...', (user_id,))"
    }
  ],
  "summary": { "critical": 1, "high": 1, "medium": 0, "low": 0 },
  "block_commit": false,
  "blocking_reason": null
}

Uso en CI/CD

# Falla si hay issues high o critical, silencioso si todo está bien
ixtli review --quiet

# Output JSON para procesar programáticamente
ixtli review --json | jq '.summary'

# Solo reportar critical y high
ixtli review --min-severity high

Exit codes:

Código	Significado
`0`	Sin issues blocking
`1`	Hay issues que bloquean
`2`	Error de ejecución (sin conexión, sin API key)
`3`	Nada que revisar (no hay archivos staged)

Contexto de tickets

Si tienes un tracker configurado, ixtli detecta automáticamente el ticket relacionado a partir del nombre del branch activo:

feat/PROJ-123-auth-refactor → detecta PROJ-123 (Jira/Linear)
fix/42-login-bug → detecta #42 (GitHub/GitLab)
feature/GH-789 → detecta GH-789 (GitHub)

El título y descripción del ticket se envían al backend para que el análisis sea más relevante al contexto del cambio.

# Ticket manual
ixtli review --ticket PROJ-123
ixtli review --ticket https://github.com/owner/repo/issues/456

# Deshabilitar detección automática
ixtli review --no-ticket

Review de commits

ixtli commit-review

Sin --range, analiza el staging area actual y sugiere un mensaje en formato Conventional Commits. Con --range, analiza ese rango de commits en su lugar (el staging area se ignora).

ixtli commit-review --range HEAD~3..HEAD   # últimos 3 commits
ixtli commit-review --range main..HEAD     # todo lo que la rama tiene de más contra main
ixtli commit-review --style simple          # mensaje sin prefijo de tipo
ixtli commit-review --json                  # output estructurado

Flag	Descripción	Default
`--range <rango>`	Rango de git a revisar en vez del staging area, ej. `HEAD~3..HEAD`, `main..HEAD`, o un sha/ref único	— (staging area)
`--style`	Estilo del mensaje de commit: `conventional`, `simple`	`conventional`
`--min-severity`	Severidad mínima a mostrar: `critical`, `high`, `medium`, `low`	`critical`
`--json`	Output en JSON (sin filtrar por severidad)	`false`
`--quiet`	Silencioso a menos que haya issues	`false`

Nota: a diferencia de ixtli review (default low, muestra todo), commit-review por default solo muestra critical — pensado como gate rápido antes de un push. Si la tabla parece vacía o incompleta pero el resumen (Mode: ... | Critical: N High: N ...) muestra más issues de los que ves, es porque hay issues de menor severidad ocultos; usa --min-severity low para verlos todos, o --json para la respuesta completa sin filtrar.

Autenticación Re-review — verificar fixes