pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/bin/update-session-context.sh

@@ -0,0 +1,261 @@
+#!/bin/bash
+# ===== SESSION CONTEXT UPDATER =====
+# Actualiza .AI_SESSION_START.md automáticamente después de cada commit
+# Se ejecuta como post-commit hook
+
+set -e
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT"
+
+# Colores
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Obtener información actual
+BRANCH=$(git branch --show-current)
+ISSUE=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+VIOLATIONS_HIGH=$(cat .audit_tmp/ast-summary.json 2>/dev/null | jq '.summary.high // 0' || echo "0")
+FILES_MODIFIED=$(git diff --name-only origin/develop...HEAD 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+COMMITS_TODAY=$(git log --since="today" --oneline 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+
+# Determinar fase actual
+PHASE="2.1"
+PHASE_NAME="Violations cleanup (Small files)"
+PROGRESS="15%"
+
+if [ -z "$ISSUE" ]; then
+    ISSUE="185"
+fi
+
+# Derivar etiqueta de sesión desde .AI_EVIDENCE.json si existe
+SESSION_LABEL=""
+EVIDENCE_FILE=".AI_EVIDENCE.json"
+if [ -f "$EVIDENCE_FILE" ]; then
+    SESSION_ID=$(jq -r '.session_id // empty' "$EVIDENCE_FILE" 2>/dev/null || echo "")
+    SESSION_ACTION=$(jq -r '.action // empty' "$EVIDENCE_FILE" 2>/dev/null || echo "")
+    if [ -n "$SESSION_ID" ]; then
+        if [ -n "$SESSION_ACTION" ] && [ "$SESSION_ACTION" != "null" ]; then
+            SESSION_LABEL="$SESSION_ID - $SESSION_ACTION"
+        else
+            SESSION_LABEL="$SESSION_ID"
+        fi
+    fi
+fi
+
+if [ -z "$SESSION_LABEL" ]; then
+    SESSION_LABEL="#$ISSUE - Fix any types (small files)"
+fi
+
+# Obtener archivos staged/modificados
+STAGED_FILES=$(git diff --name-only --cached 2>/dev/null || echo "")
+if [ -z "$STAGED_FILES" ]; then
+    STAGED_FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | head -10 || echo "Sin cambios")
+fi
+
+# Obtener últimos commits
+LAST_COMMITS=$(git log --oneline -3 2>/dev/null || echo "Sin commits recientes")
+
+# Generar archivo actualizado
+cat > .AI_SESSION_START.md <<EOF
+# 🚨 NUEVA SESIÓN - LEER PRIMERO 🚨
+
+## ⚠️ SI ESTÁS EN UNA NUEVA VENTANA DE CONTEXTO, EJECUTA ESTE PROTOCOLO:
+
+**Última actualización:** $TIMESTAMP
+**Sesión actual:** $SESSION_LABEL
+
+---
+
+## 📋 PASO 1: LEER REGLAS (OBLIGATORIO)
+
+**ANTES de modificar código, LEER:**
+- [ ] \`.cursor/rules/rulesfront.mdc\` (líneas 119-142 - Clean Architecture)
+- [ ] \`.cursor/rules/rulesbackend.mdc\` (Repository pattern, Use Cases)
+- [ ] \`.cursor/rules/rulesios.mdc\` (SwiftUI, MVVM, Protocol-Oriented)
+- [ ] \`.cursor/rules/rulesandroid.mdc\` (Jetpack Compose, MVVM, Hilt)
+
+**ACTUALIZAR:**
+- [ ] \`.AI_EVIDENCE.json\` con timestamp actual
+- [ ] Responder 3 preguntas del protocolo
+
+**Enforcement:**
+- ✅ \`pre-commit\` valida \`.AI_EVIDENCE.json\` (< 10 min antigüedad)
+- ✅ \`pre-commit\` valida Clean Architecture (forbidden dirs)
+- ✅ \`pre-commit\` valida Git Flow (16 steps)
+- ⛔ COMMIT BLOQUEADO si no cumples protocolo
+
+---
+
+## 🗺️ PASO 2: CONTEXTO GITHUB (Links rápidos)
+
+**Issues principales:**
+- 🔗 [Issue #1 - RULES](https://github.com/juancarlosmerlosalbarracin/RuralGO/issues/1) - Reglas y protocolo (Pinned)
+- 🔗 [Issue #2 - ROADMAP](https://github.com/juancarlosmerlosalbarracin/RuralGO/issues/2) - Plan completo v1.0.0 (Milestone)
+- 🔗 [Issue #$ISSUE - ACTUAL](https://github.com/juancarlosmerlosalbarracin/RuralGO/issues/$ISSUE) - Fix any types - Small files
+
+---
+
+## 📊 PASO 3: ESTADO ACTUAL DE LA SESIÓN
+
+### Branch activo:
+\`\`\`bash
+$BRANCH
+\`\`\`
+
+### Fase del plan:
+**Fase $PHASE** - $PHASE_NAME
+- **Progreso total:** $PROGRESS
+- **Commits hoy:** $COMMITS_TODAY
+- **Files modificados:** $FILES_MODIFIED
+- **Violations HIGH restantes:** $VIOLATIONS_HIGH
+
+### Archivos modificados recientemente:
+\`\`\`
+$STAGED_FILES
+\`\`\`
+
+### Últimos 3 commits:
+\`\`\`
+$LAST_COMMITS
+\`\`\`
+
+---
+
+## 🎯 PASO 4: PRÓXIMOS PASOS (Continuar desde aquí)
+
+### Inmediato (esta sesión):
+1. **Verificar estado:** \`git status\`
+2. **Continuar cleanup:** Próximos 10 archivos pequeños
+3. **Actualizar Issue #$ISSUE** con progreso
+
+### Próxima sesión (Issue #186):
+- Archivos medium (100-500 líneas)
+- Estimación: ~800K tokens
+- 30 files, ~100 any types
+
+### Bloqueadores:
+**Ninguno** - Path despejado para continuar
+
+---
+
+## 📈 MÉTRICAS GLOBALES
+
+**Violations restantes:**
+- 🔴 CRITICAL: 0
+- 🟠 HIGH: $VIOLATIONS_HIGH (objetivo: <100)
+- 🟡 MEDIUM: ~8,450
+- 🔵 LOW: ~12,300
+
+**Progreso fases:**
+- ✅ Fase 1: Git Flow + AI Protocol (100%)
+- 🔄 Fase 2: Violations cleanup ($PROGRESS)
+- 📋 Fase 3: iOS Setup (0%)
+- 📋 Fase 4: Android Setup (0%)
+- 📋 Fase 5: Testing & Docs (0%)
+
+**Target v1.0.0:** 2025-12-31
+
+---
+
+## 🔧 COMANDOS ÚTILES (Verificación rápida)
+
+\`\`\`bash
+# Ver estado
+git status
+git branch --show-current
+git log --oneline -5
+
+# Verificar protocolo
+cat .AI_EVIDENCE.json | jq '.timestamp'
+cat .AI_EVIDENCE.json | jq '.protocol_3_questions.answered'
+
+# Ver violations actuales
+bash scripts/hooks-system/presentation/cli/audit.sh
+
+# Actualizar este archivo manualmente
+bash scripts/update-session-context.sh
+\`\`\`
+
+---
+
+## ✅ CHECKLIST DE INICIO DE SESIÓN
+
+Marca cuando completes:
+- [ ] Leído \`.AI_SESSION_START.md\` (este archivo)
+- [ ] Leído reglas \`.mdc\` aplicables
+- [ ] Actualizado \`.AI_EVIDENCE.json\`
+- [ ] Verificado branch actual
+- [ ] Verificado archivos staged
+- [ ] Listo para continuar trabajo
+
+**Una vez completado, responde:**
+"✅ Contexto cargado, continuamos con [describe tarea actual]"
+
+---
+
+## 📚 ARQUITECTURA CLEAN (Recordatorio rápido)
+
+\`\`\`
+✅ CORRECTO:
+infrastructure/
+  ├── config/              ← Configuración (i18n, API, env)
+  ├── services/            ← Servicios externos (CSV, APIs)
+  └── repositories/        ← Implementaciones de datos
+
+application/
+  ├── use-cases/           ← Lógica de negocio
+  └── dtos/                ← Data Transfer Objects
+
+domain/
+  ├── entities/            ← Modelos de negocio
+  └── repositories/        ← Interfaces (NO implementaciones)
+
+presentation/
+  ├── hooks/               ← Custom React hooks
+  ├── stores/              ← Zustand/Redux
+  └── components/          ← UI components
+
+❌ PROHIBIDO:
+lib/          → usar infrastructure/ o domain/
+utils/        → usar application/ o infrastructure/
+helpers/      → usar application/use-cases/
+\`\`\`
+
+---
+
+## 🚨 PRINCIPIO FUNDAMENTAL
+
+**"Measure twice, cut once"**
+→ LEER reglas + VERIFICAR estructura + PREGUNTAR si duda
+→ SOLO ENTONCES crear/modificar archivos
+
+---
+
+**Archivo auto-actualizado por:** \`scripts/update-session-context.sh\`
+**Frecuencia:** Cada commit (post-commit hook)
+**Última ejecución:** $TIMESTAMP
+EOF
+
+echo -e "${GREEN}✅ .AI_SESSION_START.md actualizado${NC}"
+echo -e "${BLUE}📊 Estado: $FILES_MODIFIED files modificados, $VIOLATIONS_HIGH HIGH violations${NC}"
+
+# OPCIONAL: Si existe gh CLI, actualizar también GitHub issue
+if command -v gh &> /dev/null && [ -n "$ISSUE" ]; then
+    gh issue comment "$ISSUE" --body "🔄 **Progreso actualizado:** $TIMESTAMP
+
+📊 **Métricas:**
+- Files modificados: $FILES_MODIFIED
+- Commits hoy: $COMMITS_TODAY
+- Violations HIGH: $VIOLATIONS_HIGH
+
+🌿 **Branch:** \`$BRANCH\`
+
+_Auto-updated by update-session-context.sh_" 2>/dev/null && \
+    echo -e "${GREEN}✅ GitHub issue #$ISSUE actualizado${NC}" || \
+    echo -e "${BLUE}ℹ️  GitHub issue no actualizado (gh CLI no disponible o sin permisos)${NC}"
+fi
+
+exit 0

package/scripts/hooks-system/bin/verify-no-verify.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+
+# Script de verificación: Comprobar que NO se ha usado --no-verify sin autorización
+# Uso: ./scripts/verify-no-verify-policy.sh
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+COMMITS_TO_CHECK=10
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}🔍 VERIFICACIÓN: Política de --no-verify${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"
+echo ""
+echo -e "Branch actual: ${YELLOW}${BRANCH}${NC}"
+echo -e "Commits a revisar: ${COMMITS_TO_CHECK}"
+echo ""
+
+# Buscar en los últimos commits si hay mensajes que indiquen bypass del hook
+echo -e "${BLUE}📋 Analizando últimos commits...${NC}"
+echo ""
+
+VIOLATIONS_FOUND=0
+
+while read -r commit_hash; do
+  # Obtener mensaje completo (subject + body)
+  commit_full_message=$(git log -1 --pretty=format:"%B" "$commit_hash")
+  commit_subject=$(git log -1 --pretty=format:"%s" "$commit_hash")
+
+  # Buscar patrones sospechosos en el mensaje de commit
+  if echo "$commit_full_message" | grep -iE "(bypass.?hook|skip.?hook|--no-verify|no.?verify)" > /dev/null 2>&1; then
+    # Verificar si tiene autorización explícita en el mensaje completo
+    if echo "$commit_full_message" | grep -iE "(authorized|autorizado|approved)" > /dev/null 2>&1; then
+      echo -e "  ${GREEN}✅${NC} ${commit_hash:0:7}: Bypass AUTORIZADO"
+      echo -e "     ${YELLOW}→${NC} ${commit_subject:0:80}..."
+    else
+      echo -e "  ${RED}❌${NC} ${commit_hash:0:7}: Bypass SIN AUTORIZACIÓN EXPLÍCITA"
+      echo -e "     ${RED}→${NC} ${commit_subject:0:80}..."
+      VIOLATIONS_FOUND=$((VIOLATIONS_FOUND + 1))
+    fi
+  fi
+done < <(git log -${COMMITS_TO_CHECK} --pretty=format:"%H")
+
+echo ""
+echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"
+
+if [ $VIOLATIONS_FOUND -eq 0 ]; then
+  echo -e "${GREEN}✅ VERIFICACIÓN EXITOSA${NC}"
+  echo -e "${GREEN}   No se encontraron usos no autorizados de --no-verify${NC}"
+  echo ""
+  exit 0
+else
+  echo -e "${RED}❌ VERIFICACIÓN FALLIDA${NC}"
+  echo -e "${RED}   Se encontraron ${VIOLATIONS_FOUND} commits con bypass sin autorización explícita${NC}"
+  echo ""
+  echo -e "${YELLOW}⚠️  Acción requerida:${NC}"
+  echo -e "   1. Revisar los commits marcados"
+  echo -e "   2. Verificar si tienen autorización del usuario"
+  echo -e "   3. Si NO tienen autorización, revertir o documentar"
+  echo ""
+  exit 1
+fi

package/scripts/hooks-system/bin/violations

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Violations API - CLI Wrapper
+# =============================================================================
+# Usage: violations <command> [args]
+# Examples:
+#   violations list common.quality.comments
+#   violations show common.quality.todo_fixme
+#   violations summary
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+API="${SCRIPT_DIR}/violations-api.js"
+
+if [[ ! -f "$API" ]]; then
+  echo "❌ Error: violations-api.js not found"
+  exit 1
+fi
+
+node "$API" "$@"

package/scripts/hooks-system/bin/violations-api.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+class ViolationsAPI {
+  constructor(summaryPath = '.audit_tmp/ast-summary.json') {
+    this.summaryPath = summaryPath;
+    this.data = null;
+    this.indexes = null;
+  }
+
+  load() {
+    if (!fs.existsSync(this.summaryPath)) {
+      process.stderr.write(`\n❌ Summary file not found: ${this.summaryPath}\n\n`);
+      process.stderr.write(`💡 Solution: Run an audit first:\n`);
+      process.stderr.write(`   cd scripts/hooks-system\n`);
+      process.stderr.write(`   bash presentation/cli/audit.sh\n\n`);
+      process.exit(1);
+    }
+    this.data = JSON.parse(fs.readFileSync(this.summaryPath, 'utf8'));
+    this.buildIndexes();
+    return this;
+  }
+
+  buildIndexes() {
+    this.indexes = {
+      byFile: {},
+      bySeverity: {},
+      byRule: {},
+      byPlatform: {}
+    };
+
+    this.data.findings.forEach(finding => {
+      const file = finding.filePath;
+      const severity = finding.severity;
+      const rule = finding.ruleId;
+      const platform = this.detectPlatform(file);
+
+      if (!this.indexes.byFile[file]) this.indexes.byFile[file] = [];
+      this.indexes.byFile[file].push(finding);
+
+      if (!this.indexes.bySeverity[severity]) this.indexes.bySeverity[severity] = [];
+      this.indexes.bySeverity[severity].push(finding);
+
+      if (!this.indexes.byRule[rule]) this.indexes.byRule[rule] = [];
+      this.indexes.byRule[rule].push(finding);
+
+      if (!this.indexes.byPlatform[platform]) this.indexes.byPlatform[platform] = [];
+      this.indexes.byPlatform[platform].push(finding);
+    });
+  }
+
+  detectPlatform(filePath) {
+    if (/apps\/backend/i.test(filePath)) return 'backend';
+    if (/apps\/admin|apps\/web|src\//i.test(filePath)) return 'frontend';
+    if (/ios|swift/i.test(filePath)) return 'ios';
+    if (/android|kotlin/i.test(filePath)) return 'android';
+    return 'other';
+  }
+
+  getViolationsByFile(filePath) {
+    if (!this.indexes) this.load();
+
+    const absolutePath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(process.cwd(), filePath);
+
+    return this.indexes.byFile[absolutePath] || [];
+  }
+
+  getViolationsBySeverity(severity) {
+    if (!this.indexes) this.load();
+    return this.indexes.bySeverity[severity] || [];
+  }
+
+  getViolationsByRule(ruleId) {
+    if (!this.indexes) this.load();
+    return this.indexes.byRule[ruleId] || [];
+  }
+
+  getViolationsByPlatform(platform) {
+    if (!this.indexes) this.load();
+    return this.indexes.byPlatform[platform] || [];
+  }
+
+  getStagedViolations() {
+    if (!this.indexes) this.load();
+
+    const { execSync } = require('child_process');
+    const stagedFiles = execSync('git diff --cached --name-only --diff-filter=ACM', { encoding: 'utf8' })
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map(f => path.join(process.cwd(), f));
+
+    const stagedViolations = [];
+    stagedFiles.forEach(file => {
+      const violations = this.indexes.byFile[file] || [];
+      stagedViolations.push(...violations);
+    });
+
+    return stagedViolations;
+  }
+
+  getTopViolations(limit = 10) {
+    if (!this.data) this.load();
+
+    const ruleStats = {};
+    this.data.findings.forEach(f => {
+      if (!ruleStats[f.ruleId]) {
+        ruleStats[f.ruleId] = {
+          count: 0,
+          severity: f.severity,
+          files: new Set()
+        };
+      }
+      ruleStats[f.ruleId].count++;
+      ruleStats[f.ruleId].files.add(f.filePath);
+    });
+
+    return Object.entries(ruleStats)
+      .map(([ruleId, stats]) => ({
+        ruleId,
+        count: stats.count,
+        severity: stats.severity,
+        filesAffected: stats.files.size
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, limit);
+  }
+
+  getSummary() {
+    if (!this.data) this.load();
+
+    const summary = {
+      total: this.data.findings.length,
+      critical: this.data.findings.filter(f => f.severity === 'critical').length,
+      high: this.data.findings.filter(f => f.severity === 'high').length,
+      medium: this.data.findings.filter(f => f.severity === 'medium').length,
+      low: this.data.findings.filter(f => f.severity === 'low').length,
+      filesAffected: new Set(this.data.findings.map(f => f.filePath)).size
+    };
+
+    return summary;
+  }
+}
+
+function cli() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const api = new ViolationsAPI();
+
+  try {
+    api.load();
+
+    switch (command) {
+      case 'file': {
+        const filePath = args[1];
+        if (!filePath) {
+          process.stderr.write('Usage: violations-api.js file <path>\n');
+          process.exit(1);
+        }
+        const violations = api.getViolationsByFile(filePath);
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        break;
+      }
+
+      case 'severity': {
+        const severity = args[1];
+        if (!severity) {
+          process.stderr.write('Usage: violations-api.js severity <critical|high|medium|low>\n');
+          process.exit(1);
+        }
+        const violations = api.getViolationsBySeverity(severity);
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        break;
+      }
+
+      case 'rule': {
+        const ruleId = args[1];
+        if (!ruleId) {
+          process.stderr.write('Usage: violations-api.js rule <ruleId>\n');
+          process.exit(1);
+        }
+        const violations = api.getViolationsByRule(ruleId);
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        break;
+      }
+
+      case 'staged': {
+        const violations = api.getStagedViolations();
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        break;
+      }
+
+      case 'top': {
+        const limit = parseInt(args[1]) || 10;
+        const top = api.getTopViolations(limit);
+        process.stdout.write(JSON.stringify(top, null, 2) + '\n');
+        break;
+      }
+
+      case 'summary': {
+        const summary = api.getSummary();
+        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+        break;
+      }
+
+      case 'platform': {
+        const platform = args[1];
+        if (!platform) {
+          process.stderr.write('Usage: violations-api.js platform <backend|frontend|ios|android|other>\n');
+          process.exit(1);
+        }
+        const violations = api.getViolationsByPlatform(platform);
+        process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+        break;
+      }
+
+      case 'list': {
+        const ruleId = args[1];
+        if (!ruleId) {
+          process.stderr.write('Usage: violations-api.js list <ruleId>\n');
+          process.stderr.write('Example: violations-api.js list common.quality.todo_fixme\n');
+          process.exit(1);
+        }
+        const violations = api.getViolationsByRule(ruleId);
+
+        if (violations.length === 0) {
+          process.stdout.write(`✅ No violations found for rule: ${ruleId}\n`);
+          process.exit(0);
+        }
+
+        process.stdout.write(`📋 ${violations.length} violation(s) for ${ruleId}:\n\n`);
+        violations.forEach((v, i) => {
+          const loc = `${v.filePath}:${v.line}:${v.column || 1}`;
+          process.stdout.write(`${i + 1}. ${loc}\n`);
+        });
+        break;
+      }
+
+      case 'show': {
+        const ruleId = args[1];
+        const contextLines = parseInt(args[2]) || 3;
+
+        if (!ruleId) {
+          process.stderr.write('Usage: violations-api.js show <ruleId> [contextLines]\n');
+          process.stderr.write('Example: violations-api.js show common.quality.todo_fixme 3\n');
+          process.exit(1);
+        }
+
+        const violations = api.getViolationsByRule(ruleId);
+
+        if (violations.length === 0) {
+          process.stdout.write(`✅ No violations found for rule: ${ruleId}\n`);
+          process.exit(0);
+        }
+
+        process.stdout.write(`\n🔍 ${violations.length} violation(s) for ${ruleId}:\n`);
+
+        violations.forEach((v, i) => {
+          const loc = `${v.filePath}:${v.line}:${v.column || 1}`;
+          process.stdout.write(`\n${'─'.repeat(70)}\n`);
+          process.stdout.write(`📄 ${i + 1}. ${loc}\n`);
+          process.stdout.write(`   ${v.message}\n`);
+          process.stdout.write(`${'─'.repeat(70)}\n`);
+
+          try {
+            if (fs.existsSync(v.filePath)) {
+              const lines = fs.readFileSync(v.filePath, 'utf8').split('\n');
+              const targetLine = v.line - 1;
+              const start = Math.max(0, targetLine - contextLines);
+              const end = Math.min(lines.length, targetLine + contextLines + 1);
+
+              for (let j = start; j < end; j++) {
+                const lineNum = (j + 1).toString().padStart(4, ' ');
+                const marker = j === targetLine ? '→' : ' ';
+                const line = lines[j];
+                process.stdout.write(`${lineNum} ${marker} ${line}\n`);
+              }
+            } else {
+              process.stdout.write(`   ⚠️  File not accessible\n`);
+            }
+          } catch (err) {
+            process.stdout.write(`   ⚠️  Error reading file: ${err.message}\n`);
+          }
+        });
+
+        process.stdout.write(`\n${'═'.repeat(70)}\n`);
+        process.stdout.write(`✅ ${violations.length} violation(s) shown\n`);
+        process.stdout.write(`\n💡 Click on any path above to open in editor\n\n`);
+        break;
+      }
+
+      default:
+        process.stderr.write(`
+Violations API - Dynamic Query Interface
+
+Usage:
+  violations-api.js <command> [options]
+
+Commands:
+  file <path>          Get violations for specific file (indexed)
+  severity <level>     Get violations by severity (indexed)
+  rule <ruleId>        Get violations for specific rule (indexed)
+  platform <name>      Get violations by platform (indexed)
+  staged               Get violations in staged files only (git-aware)
+  top [limit]          Get top N violations (default: 10)
+  summary              Get violations summary (fast stats)
+  list <ruleId>        List clickable file paths for rule violations
+  show <ruleId> [ctx]  Show code context for violations (default: 3 lines)
+
+Platforms: backend, frontend, ios, android, other
+
+Examples:
+  violations-api.js file apps/backend/src/main.ts
+  violations-api.js severity high
+  violations-api.js rule common.types.any
+  violations-api.js platform backend
+  violations-api.js staged
+  violations-api.js top 5
+  violations-api.js summary
+  violations-api.js list common.quality.todo_fixme      # Clickable paths
+  violations-api.js show common.quality.todo_fixme 5    # Show with 5 lines context
+
+Performance:
+✅ Indexed queries (O(1) lookups)
+✅ No manual JSON parsing
+✅ Exact path matching
+✅ Pre-built on load
+`);
+        process.exit(1);
+    }
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  cli();
+}
+
+module.exports = { ViolationsAPI };