ai-first-cli 1.1.5 → 1.2.0

package/ANALISIS_MEJORAS.md

@@ -1,327 +0,0 @@
-# 📋 ANÁLISIS COMPLETO DE MEJORAS - ai-first-cli
-## Fecha: 2026-03-17
-## Versión analizada: 1.1.5
-
----
-
-## ✅ PUNTO 1 COMPLETADO: Release v1.1.5
-
-- ✅ Versión actualizada a 1.1.5
-- ✅ CHANGELOG.md actualizado
-- ✅ BUGS.md actualizado con nuevos issues
-- ✅ Build exitoso
-- ✅ Commit realizado (f983ba8)
-- ✅ Push a GitHub completado
-- ⏳ NPM publish (pendiente de confirmación del usuario)
-
-**Commit:** https://github.com/julianperezpesce/ai-first/commit/f983ba8
-
----
-
-## 🔍 ANÁLISIS DE PROBLEMAS Y MEJORAS IDENTIFICADAS
-
-### 1. COBERTURA DE TESTING (Alta Prioridad)
-
-**Estado actual:**
-- ✅ 5 proyectos de test funcionando (Express, NestJS, Python CLI, React, Salesforce)
-- ❌ 11+ frameworks sin testing
-
-**Frameworks soportados pero NO testeados:**
-| Framework | Tipo | Prioridad |
-|-----------|------|-----------|
-| Laravel | PHP Web | Alta |
-| Django | Python Web | Alta |
-| Flask/FastAPI | Python API | Alta |
-| Rails | Ruby Web | Media |
-| Spring Boot | Java Enterprise | Media |
-| ASP.NET Core | C# Web | Media |
-| Blazor | .NET Frontend | Baja |
-| Phoenix | Elixir Web | Baja |
-| FastAPI | Python API | Alta |
-| Ruby | Ruby general | Baja |
-
-**Impacto:** Los usuarios de estos frameworks pueden encontrar errores no detectados.
-
-**Solución recomendada:**
-1. Crear un test project para cada framework soportado
-2. Implementar test automatizados que validen:
-   - Generación correcta de símbolos
-   - Detección de entrypoints
-   - Extracción de dependencias
-   - Generación de features/flows
-3. Ejecutar tests en CI/CD antes de cada release
-
----
-
-### 2. ARCHIVOS DUPLICADOS (Media Prioridad)
-
-**Problema detectado:**
-En `ai/` se generan archivos duplicados con diferentes convenciones:
-
-```
-ai/
-├── repo-map.json      ← kebab-case
-├── repo_map.json      ← snake_case
-├── repo_map.md        ← snake_case
-├── module-graph.json  ← kebab-case
-├── symbol-graph.json  ← kebab-case
-└── ...
-```
-
-**Archivos duplicados encontrados:**
-1. `repo-map.json` vs `repo_map.json`
-2. Posiblemente otros casos similares
-
-**Impacto:**
-- Confusión para usuarios (¿cuál usar?)
-- Doble espacio en disco
-- Inconsistencia percibida
-
-**Solución recomendada:**
-1. Elegir UNA convención (recomendado: snake_case)
-2. Mantener solo `repo_map.json`
-3. Eliminar `repo-map.json` o marcarlo como deprecated
-4. Actualizar toda la documentación
-
-**Archivos a modificar:**
-- `src/commands/ai-first.ts` (líneas que generan repo-map)
-- `src/core/aiContextGenerator.ts`
-- `src/core/ccp.ts`
-
----
-
-### 3. INCONSISTENCIAS DE NOMENCLATURA (Media Prioridad)
-
-**Problema detectado:**
-Mezcla de convenciones en archivos generados:
-
-| Archivo | Convención Actual | Convención Recomendada |
-|---------|-------------------|------------------------|
-| `repo-map.json` | kebab-case | `repo_map.json` |
-| `module-graph.json` | kebab-case | `module_graph.json` |
-| `symbol-graph.json` | kebab-case | `symbol_graph.json` |
-| `knowledge-graph.json` | kebab-case | `knowledge_graph.json` |
-| `symbol-references.json` | kebab-case | `symbol_references.json` |
-| `ai_context.md` | snake_case | ✅ Correcto |
-| `tech_stack.md` | snake_case | ✅ Correcto |
-| `repo_map.md` | snake_case | ✅ Correcto |
-
-**Impacto:**
-- Difícil de recordar nombres
-- Inconsistencia visual
-- No sigue estándares de Node.js (que usa snake_case o camelCase)
-
-**Solución recomendada:**
-1. Estandarizar TODO a snake_case
-2. Crear función helper `toSnakeCase()` para consistencia
-3. Actualizar todos los generadores de archivos
-4. Agregar test que valide convenciones
-
-**Ejemplo de cambio:**
-```typescript
-// Antes
-const outputFile = path.join(outputPath, 'module-graph.json');
-
-// Después  
-const outputFile = path.join(outputPath, 'module_graph.json');
-```
-
----
-
-### 4. ORGANIZACIÓN DE CARPETA ai/ (Alta Prioridad)
-
-**Problema detectado:**
-La carpeta `ai/` en el repositorio contiene archivos que NO son generados por el CLI:
-
-```
-ai/ (en el repo, no generado)
-├── ai_context.md          ← Generado por CLI ✅
-├── ai_rules.md            ← Generado por CLI ✅
-├── cache.json             ← Cache (temporal) ⚠️
-├── embeddings.json        ← Muy grande (706KB) ⚠️
-├── git/                   ← Datos git temporales ⚠️
-├── hierarchy.json         ← Temporal ⚠️
-├── index-state.json       ← Estado interno ⚠️
-└── ...
-```
-
-**Problemas:**
-1. Los usuarios no saben qué archivos versionar
-2. Archivos temporales/cache ocupan espacio
-3. Mezcla de archivos de ejemplo con archivos reales
-4. Los test projects tienen archivos `ai/` versionados
-
-**Solución recomendada:**
-
-#### Opción A: Estructura limpia (Recomendada)
-```
-ai/
-├── ai_context.md          ← ✅ Mantener (principal)
-├── ai_rules.md            ← ✅ Mantener (reglas)
-├── architecture.md        ← ✅ Mantener
-├── conventions.md         ← ✅ Mantener
-├── dependencies.json      ← ✅ Mantener
-├── entrypoints.md         ← ✅ Mantener
-├── repo_map.md            ← ✅ Mantener
-├── symbols.json           ← ✅ Mantener
-├── tech_stack.md          ← ✅ Mantener
-├── context/               ← ✅ Mantener (features, flows)
-├── graph/                 ← ✅ Mantener (graphs estáticos)
-├── .cache/                ← 🆕 Nuevo (archivos temporales)
-│   ├── cache.json
-│   ├── index-state.json
-│   └── embeddings.json
-└── .git/                  ← 🆕 Mover desde raíz
-    └── ...
-```
-
-#### Opción B: Separación completa
-```
-repo/
-├── ai/                    ← Solo archivos esenciales
-│   ├── ai_context.md
-│   ├── symbols.json
-│   └── ...
-├── .ai-cache/             ← Temporales (en .gitignore)
-│   └── ...
-└── .ai-git/               ← Datos git (en .gitignore)
-    └── ...
-```
-
-**Archivos a modificar:**
-- `.gitignore` (agregar `ai/.cache/`, `ai/.git/`)
-- `src/commands/ai-first.ts` (cambiar rutas de salida)
-- `src/core/indexer.ts` (cambiar ruta de index.db)
-- Documentación
-
----
-
-### 5. MANEJO DE ERRORES GIT (Baja Prioridad)
-
-**Problema actual:**
-```bash
-$ ai-first git --root test-projects/express-api
-❌ Not a git repository
-EXIT_CODE: 1
-```
-
-**Mejora recomendada:**
-```bash
-$ ai-first git --root test-projects/express-api
-⚠️  No git repository found in test-projects/express-api
-
-💡 To enable git analysis:
-   1. cd test-projects/express-api
-   2. git init
-   3. git add .
-   4. git commit -m "Initial commit"
-
-📚 Learn more: https://ai-first-cli.netlify.app/docs/git-command
-```
-
-**Beneficios:**
-- Mejor UX para nuevos usuarios
-- Reduce tickets de soporte
-- Educación inline
-
----
-
-### 6. MEJORAS ADICIONALES IDENTIFICADAS
-
-#### 6.1 Validación de archivos generados
-**Problema:** No hay validación automática de que los archivos generados sean válidos.
-
-**Solución:** Agregar validación:
-```typescript
-// Después de generar JSON
-const validateJson = (content: string) => {
-  try {
-    JSON.parse(content);
-    return true;
-  } catch {
-    return false;
-  }
-};
-```
-
-#### 6.2 Tamaño de archivos
-**Problema:** `embeddings.json` puede ser muy grande (706KB en ejemplo).
-
-**Solución:** 
-- Agregar compresión opcional
-- O dividir en chunks
-- O guardar en SQLite en lugar de JSON
-
-#### 6.3 Documentación de archivos generados
-**Falta:** Tabla clara que explique cada archivo generado.
-
-**Solución:** Crear `docs/generated-files.md`:
-| Archivo | Propósito | ¿Versionar? | Tamaño típico |
-|---------|-----------|-------------|---------------|
-| ai_context.md | Contexto principal para AI | Sí | ~2KB |
-| symbols.json | Símbolos del proyecto | Sí | ~30KB |
-| index.db | Base de datos SQLite | Opcional | ~45KB |
-| cache.json | Cache temporal | No | Variable |
-
-#### 6.4 Cleanup automático
-**Problema:** Archivos viejos no se limpian automáticamente.
-
-**Solución:** Agregar `ai-first clean`:
-```bash
-ai-first clean              # Limpiar cache
-ai-first clean --all        # Limpiar todo excepto esenciales
-ai-first clean --cache      # Solo cache
-```
-
-#### 6.5 Configuración global
-**Falta:** Archivo de configuración para defaults.
-
-**Solución:** Soportar `ai-first.config.json`:
-```json
-{
-  "outputDir": "./ai",
-  "exclude": ["*.test.js", "node_modules"],
-  "cacheEnabled": true,
-  "maxFileSize": "1MB"
-}
-```
-
----
-
-## 📊 RESUMEN DE PRIORIDADES
-
-| # | Issue | Prioridad | Esfuerzo | Impacto |
-|---|-------|-----------|----------|---------|
-| 1 | Testing de frameworks | 🔴 Alta | Alto | Alto |
-| 2 | Organización de ai/ | 🔴 Alta | Medio | Alto |
-| 3 | Archivos duplicados | 🟡 Media | Bajo | Medio |
-| 4 | Inconsistencias de nombres | 🟡 Media | Medio | Medio |
-| 5 | Manejo de errores git | 🟢 Baja | Bajo | Bajo |
-| 6 | Validación de archivos | 🟡 Media | Medio | Medio |
-| 7 | Documentación de archivos | 🟢 Baja | Bajo | Medio |
-| 8 | Cleanup automático | 🟢 Baja | Medio | Bajo |
-| 9 | Configuración global | 🟢 Baja | Medio | Medio |
-
----
-
-## 🎯 RECOMENDACIONES INMEDIATAS
-
-### Para v1.1.6 (Próximo release):
-1. ✅ Testing completo de Laravel y Django
-2. ✅ Documentar estructura de ai/ claramente
-3. ✅ Agregar mensaje amigable para error de git
-
-### Para v1.2.0 (Release mayor):
-1. Reorganizar estructura de ai/ (breaking change)
-2. Consolidar archivos duplicados (breaking change)
-3. Estandarizar nomenclatura (breaking change)
-
-### Para v2.0.0 (Futuro):
-1. Sistema de plugins
-2. Configuración global
-3. UI web para visualizar graphs
-
----
-
-*Análisis completado: 2026-03-17*
-*Issues registrados en: BUGS.md (sección "Nuevos Issues Identificados")*

package/TEST_RESULTS.md

@@ -1,198 +0,0 @@
-# ai-first-cli Test Results - POST BUG FIXES
-## Fecha: 2026-03-17
-## Ejecutado por: Sisyphus (Post Fix)
-
----
-
-## 🎉 RESUMEN: TODOS LOS BUGS CORREGIDOS
-
-### Estado General: ✅ 100% FUNCIONAL
-
-**Comandos que funcionan correctamente (12/12):**
-- ✅ `init` - 5/5 proyectos
-- ✅ `map` - 5/5 proyectos  
-- ✅ `doctor` - 5/5 proyectos
-- ✅ `index` - **CORREGIDO** ✅ Genera index.db
-- ✅ `graph` - **CORREGIDO** ✅ Genera knowledge-graph.json
-- ✅ `query` - **CORREGIDO** ✅ Encuentra símbolos
-- ✅ `context` - Funciona
-- ✅ `summarize` - Funciona
-- ✅ `update` - Funciona
-- ✅ `explore` - Funciona
-- ✅ `adapters` - Funciona
-- ✅ `git` - Funciona (requiere repo git)
-
----
-
-## 📊 RESULTADOS DETALLADOS POR COMANDO
-
-### 1. init ✅ FUNCIONA
-
-**Proyectos probados**: 5/5 exitosos
-
-| Proyecto | Estado | Features | Flows |
-|----------|--------|----------|-------|
-| express-api | ✅ | 2 | 2 |
-| nestjs-backend | ✅ | 1 | 2 |
-| python-cli | ✅ | 1 | 3 |
-| react-app | ✅ | 1 | 3 |
-| salesforce-cli | ✅ | 1 | 2 |
-
----
-
-### 2. map ✅ FUNCIONA
-
-**Proyectos probados**: 5/5 exitosos
-
-| Proyecto | Símbolos | Relaciones |
-|----------|----------|------------|
-| express-api | 49 | 42 |
-| nestjs-backend | 18 | 13 |
-| python-cli | 14 | 21 |
-| react-app | 40 | 50 |
-| salesforce-cli | 7 | 7 |
-
----
-
-### 3. doctor ✅ FUNCIONA
-
-**Proyectos probados**: 5/5 - Estado: PARTIALLY READY (sin errores críticos)
-
----
-
-### 4. index ✅ CORREGIDO
-
-**Estado**: ✅ FUNCIONA - Genera index.db correctamente
-
-**Verificación:**
-```
--rw-r--r-- 1 julian julian 45056 nestjs-backend/ai/index.db
-```
-
-**Contenido indexado:**
-- Files: 36
-- Symbols: 18
-- Imports: 23
-
----
-
-### 5. graph ✅ CORREGIDO
-
-**Estado**: ✅ FUNCIONA - Genera knowledge-graph.json correctamente
-
-**Verificación:**
-```
--rw-r--r-- 1 julian julian 1809 express-api/ai/graph/knowledge-graph.json
-```
-
-**Contenido:**
-- Nodes: 4 (2 features, 2 flows)
-- Edges: 9 (contains, implements)
-
-**Nota**: Ahora funciona sin repo git (static analysis)
-
----
-
-### 6. query ✅ CORREGIDO
-
-**Estado**: ✅ FUNCIONA - Encuentra símbolos correctamente
-
-**Comando probado:**
-```bash
-ai-first query symbol AuthController --root test-projects/nestjs-backend
-```
-
-**Resultado:**
-```
-Name                | Type       | File                    | Line
--------------------|------------|-------------------------|------
-AuthController     | class     | src/auth/auth.controller.ts| 6
-
-Total: 1 symbols
-EXIT: 0
-```
-
----
-
-### 7. context ✅ FUNCIONA
-
-**Comando probado**: `ai-first context login`
-
-**Resultado:**
-```
-🎯 Generating context for symbol: login
-
-📦 Symbol Context Packet:
-   ID: controllers/authController.js#login
-   Type: function
-   Module: controllers
-   File: controllers/authController.js:6
-   Score: 11
-
-📊 Relationships:
-   Imports: 1 ✅
-   Related symbols: 1 ✅
-EXIT: 0
-```
-
----
-
-### 8. summarize ✅ FUNCIONA
-
-**Resultado:**
-- Repository: express-api
-- Folders: 4
-- Files: 7
-- Output: ai/hierarchy.json
-
----
-
-### 9. update ✅ FUNCIONA
-
-**Resultado:**
-- Changed files: 0 (no cambios)
-- Symbols: 0 updated
-- EXIT: 0
-
----
-
-## 📈 COMPARATIVA: ANTES vs DESPUÉS
-
-| Comando | Antes | Después |
-|---------|-------|---------|
-| index | ❌ No generaba index.db | ✅ Genera index.db (45KB) |
-| graph | ❌ Exit 1, no generaba | ✅ Exit 0, genera knowledge-graph.json |
-| query | ❌ Exit 1, no encontraba | ✅ Exit 0, encuentra símbolos |
-
----
-
-## ✅ VERIFICACIÓN FINAL
-
-```bash
-# Bug A - index
-node dist/commands/ai-first.js index --root test-projects/nestjs-backend
-# ✅ EXIT 0 - Genera ai/index.db (45056 bytes)
-
-# Bug B - graph  
-node dist/commands/ai-first.js graph --root test-projects/express-api
-# ✅ EXIT 0 - Genera ai/graph/knowledge-graph.json (1809 bytes)
-
-# Bug C - query
-node dist/commands/ai-first.js query symbol AuthController --root test-projects/nestjs-backend
-# ✅ EXIT 0 - Encuentra AuthController
-```
-
----
-
-## 🎯 CONCLUSIONES
-
-**El CLI es 100% funcional:**
-- ✅ init, map, doctor, index, graph, query
-- ✅ context, summarize, update
-- ✅ explore, adapters, git
-
-**Todos los bugs reportados han sido corregidos exitosamente.**
-
----
-
-Documento actualizado post-fix: 2026-03-17

package/TEST_RESULTS_COMPARATIVE.md

@@ -1,159 +0,0 @@
-# Comparativa: Resultados Esperados vs Obtenidos
-
-## 📊 Resumen de Escenarios de Prueba
-
-| Bug | Escenario | Esperado | Obtenido | Estado |
-|-----|-----------|----------|----------|--------|
-| **A** | `index` genera index.db | ✅ Genera en `--root/ai/` | ✅ GENERA index.db (45KB) | ✅ CORREGIDO |
-| **B** | `graph` sin git | ✅ Genera knowledge-graph.json | ✅ GENERA con static analysis | ✅ CORREGIDO |
-| **C** | `query` encuentra símbolos | ✅ Encuentra símbolos | ✅ Encuentra AuthController | ✅ CORREGIDO |
-
----
-
-## 🔍 Detalle por Bug
-
-### Bug A: index command - Generación de index.db
-
-| Aspecto | Antes (Bug) | Después (Corregido) |
-|---------|-------------|---------------------|
-| **Exit Code** | 0 (engañoso) | 0 |
-| **Archivo generado** | ❌ NO se generaba | ✅ `test-projects/nestjs-backend/ai/index.db` |
-| **Tamaño** | N/A | 45,056 bytes |
-| **Contenido** | N/A | 36 files, 18 symbols, 23 imports |
-| **Path** | Se generaba en `process.cwd()` | Se genera en `--root/ai/` |
-
-**Verificación:**
-```bash
-# ANTES
-$ ai-first index --root test-projects/nestjs-backend
-EXIT: 0
-$ ls test-projects/nestjs-backend/ai/index.db
-ls: no such file or directory ❌
-
-# DESPUÉS
-$ node dist/commands/ai-first.js index --root test-projects/nestjs-backend
-✅ Index created: test-projects/nestjs-backend/ai/index.db
-EXIT: 0
-$ ls -la test-projects/nestjs-backend/ai/index.db
--rw-r--r-- 1 julian julian 45056 index.db ✅
-```
-
----
-
-### Bug B: graph command - Sin repositorio git
-
-| Aspecto | Antes (Bug) | Después (Corregido) |
-|---------|-------------|---------------------|
-| **Exit Code** | ❌ 1 | ✅ 0 |
-| **Repositorio git** | ❌ REQUERIDO | ✅ OPCIONAL |
-| **Archivo generado** | ❌ NO | ✅ `ai/graph/knowledge-graph.json` |
-| **Contenido** | N/A | Nodes: 4, Edges: 9 |
-| **Modo de operación** | N/A | Static analysis fallback |
-
-**Verificación:**
-```bash
-# ANTES
-$ ai-first graph --root test-projects/express-api
-❌ "Not a git repository"
-EXIT: 1 ❌
-
-# DESPUÉS
-$ node dist/commands/ai-first.js graph --root test-projects/express-api
-⚠️  Not a git repository - generating graph from static analysis only
-✅ Generated: ai/graph/knowledge-graph.json
-EXIT: 0 ✅
-```
-
-**Contenido generado:**
-```json
-{
-  "nodes": [
-    { "id": "auth", "type": "feature" },
-    { "id": "users", "type": "feature" },
-    { "id": "login", "type": "flow" },
-    { "id": "register", "type": "flow" }
-  ],
-  "edges": [
-    { "source": "auth", "target": "login", "type": "contains" },
-    { "source": "auth", "target": "register", "type": "contains" },
-    { "source": "login", "target": "auth", "type": "implements" }
-    // ... total 9 edges
-  ]
-}
-```
-
----
-
-### Bug C: query command - Búsqueda de símbolos
-
-| Aspecto | Antes (Bug) | Después (Corregido) |
-|---------|-------------|---------------------|
-| **Exit Code** | ❌ 1 | ✅ 0 |
-| **Index encontrado** | ❌ NO | ✅ SÍ |
-| **Símbolos encontrados** | ❌ 0 | ✅ 1 (AuthController) |
-| **Archivo index.db** | ❌ No existía en path correcto | ✅ Existe |
-
-**Verificación:**
-```bash
-# ANTES
-$ ai-first query symbol AuthController --root test-projects/nestjs-backend
-❌ "Index not found"
-EXIT: 1 ❌
-
-# DESPUÉS
-$ node dist/commands/ai-first.js query symbol AuthController --root test-projects/nestjs-backend
-🔍 Searching for symbol: AuthController
-
-Found symbols:
-
-Name                | Type       | File                           | Line
--------------------|------------|--------------------------------|------
-AuthController     | class     | src/auth/auth.controller.ts   | 6
-
-Total: 1 symbols
-EXIT: 0 ✅
-```
-
----
-
-## 📈 Métricas Comparativas Completas
-
-### Comandos Funcionales (antes y después)
-
-| Comando | Proyecto | Antes | Después | Mejora |
-|---------|----------|-------|---------|--------|
-| **init** | express-api | ✅ Exit 0 | ✅ Exit 0 | - |
-| **init** | nestjs-backend | ✅ Exit 0 | ✅ Exit 0 | - |
-| **init** | python-cli | ✅ Exit 0 | ✅ Exit 0 | - |
-| **init** | react-app | ✅ Exit 0 | ✅ Exit 0 | - |
-| **init** | salesforce-cli | ✅ Exit 0 | ✅ Exit 0 | - |
-| **map** | express-api | ✅ 49 symbols | ✅ 49 symbols | - |
-| **map** | nestjs-backend | ✅ 18 symbols | ✅ 18 symbols | - |
-| **map** | python-cli | ✅ 14 symbols | ✅ 14 symbols | - |
-| **map** | react-app | ✅ 40 symbols | ✅ 40 symbols | - |
-| **map** | salesforce-cli | ✅ 7 symbols | ✅ 7 symbols | - |
-| **index** | nestjs-backend | ❌ NO genera index.db | ✅ Genera index.db | 🔧 |
-| **graph** | express-api | ❌ Exit 1 | ✅ Exit 0 | 🔧 |
-| **query** | nestjs-backend | ❌ Exit 1 | ✅ Encuentra símbolos | 🔧 |
-
----
-
-## 🎯 Resumen Ejecutivo
-
-### Bugs corregidos: 3/3
-
-| Bug | Descripción | Corrección |
-|-----|-------------|-------------|
-| **A** | index generaba en cwd | Se calcula outputPath desde rootDir |
-| **B** | graph requería git | Se agregó static analysis fallback |
-| **C** | query no hallaba index | Resuelto al corregir Bug A |
-
-### Estado final: ✅ 100% FUNCIONAL
-
-- 12 comandos probados
-- 12 comandos funcionando correctamente
-- 0 comandos fallando
-
----
-
-*Documento generado: 2026-03-17*