codenexusdocs

v2.0.0

Published

2 days ago

Analizador universal de repositorios y herramienta de documentación técnica para proyectos de software.

0High
0Medium
0Low

valosdev

Code Nexus Docs

🇪🇸 Español / 🇬🇧 English

🇪🇸 Español · 🇬🇧 English

La documentación principal está en español.

CodeNexusDocs admite salida en:

es
en

Configura el idioma global:

codenexusdocs config set language es

codenexusdocs config set language en

También puedes sobrescribir el idioma para un único comando:

codenexusdocs analyze . --lang es
codenexusdocs analyze . --lang en

Los nombres de los comandos permanecen estables para todos los idiomas:

analyze
api
database
architecture
installation
deployment
config

📚 Índice del documento

🇪🇸 Español · 🇬🇧 English

GitHub y npm utilizan anclas estándar; Bitbucket Cloud utiliza el prefijo markdown-header-.

GitHub / npm

Bitbucket Cloud

📦 Índice de versiones

Cada enlace lleva directamente al bloque correspondiente del historial de versiones.

GitHub / npm

Bitbucket Cloud

📦 ¿Qué es CodeNexusDocs?

CodeNexusDocs es una herramienta CLI desarrollada con TypeScript y Node.js para analizar automáticamente repositorios de software y construir una representación técnica estructurada del proyecto.

La finalidad del proyecto es pasar de:

Repositorio
    ↓
Análisis estático
    ↓
Modelo estructurado
    ↓
Documentación

a una herramienta capaz de mantener documentación técnica alineada con el código.

La filosofía principal es:

El análisis estático es la fuente de verdad. La IA futura debe interpretar y redactar a partir de ese modelo, no inventar información.

⚡ Instalación para usuarios finales

Requisitos

Necesitas:

Node.js 22+
npm

Comprueba:

node --version
npm --version

Instalación global

Una vez publicado el paquete:

npm install -g codenexusdocs

npm instalará el paquete y sus dependencias y expondrá el ejecutable definido en el campo bin del paquete.

Comprueba:

codenexusdocs --version

codenexusdocs --help

Después podrás utilizar CodeNexusDocs desde cualquier carpeta, sin clonar el repositorio fuente de CodeNexusDocs.

Usar sin instalación global

También puedes ejecutarlo con:

npx codenexusdocs analyze .

🚀 Primer uso

Entra en el proyecto que quieres analizar:

cd C:\ruta\del\proyecto

Ejecuta:

codenexusdocs analyze .

Después puedes profundizar en áreas concretas:

codenexusdocs api .

codenexusdocs database .

codenexusdocs architecture .

No es necesario copiar CodeNexusDocs dentro del proyecto analizado.

🧭 Referencia completa de comandos

CodeNexusDocs separa tres tipos de trabajo:

Análisis estático
      ↓
Modelos estructurados
      ↓
Documentación determinista
      ↓
IA opcional para interpretar y enriquecer

La IA nunca reemplaza el análisis estático. Cuando se utiliza --ai, la IA recibe contexto estructurado y evidencia seleccionada por CodeNexusDocs.

Resumen rápido

| Comando | Qué devuelve / genera | Uso principal | |---|---|---| | analyze | Resumen general del repositorio | Entender rápidamente un proyecto | | api | Endpoints y señales OpenAPI/Swagger; opcionalmente OpenAPI | Documentar o revisar una API | | database | Tablas, columnas, relaciones, índices y metadatos | Comprender el esquema | | dependencies | Dependencias, versiones, lockfiles y conflictos | Inventario y revisión de dependencias | | environment | Archivos, variables, usos y servicios sin exponer valores | Revisar configuración | | testing | Frameworks, tests, suites, herramientas y cobertura configurada | Auditar testing | | architecture | Capas, módulos, componentes, dependencias, patrones y diagramas | Comprender arquitectura | | evidence | Registro de evidencias y trazabilidad | Revisar por qué se produjo una detección | | installation / install | Requisitos, pasos y comandos detectados | Preparar instalación | | deployment | Plataformas, procesos, Docker, workers, queues, cron, etc. | Analizar despliegue | | profile | Perfil técnico dominante, evidencia, prioridades y documentos recomendados | Clasificar el enfoque del proyecto | | generate | Documentación Markdown determinista | Crear documentación base | | generate --ai | Documentación enriquecida por IA + telemetría | Explicar y ampliar la documentación | | ai-review | Claims, insights, advertencias y evidencia | Revisar calidad documental | | frameworks | Frameworks detectados, soporte, capacidades y evidencia | Inventariar ecosistema | | check | Estado de sincronización documental | CI / detectar drift | | diff | Diff unificado de documentación | Ver exactamente qué cambió | | config | Configuración de idioma, proveedor y credenciales | Administrar preferencias |

Los comandos aceptan una ruta opcional; . representa el repositorio actual.

`analyze`

Realiza el análisis general del repositorio y devuelve el modelo base que alimenta los analizadores especializados.

codenexusdocs analyze .

Útil para saber rápidamente:

proyecto y ruta
lenguajes
frameworks
runtimes
package managers
versiones
documentación detectada
estadísticas del repositorio

JSON completo:

codenexusdocs analyze . --json
codenexusdocs analyze . --json --output docs/analysis.json

Más detalle:

codenexusdocs analyze . --details
codenexusdocs analyze . --verbose

`index`

Construye un inventario determinista del repositorio para reutilizarlo en las siguientes etapas de comprensión del proyecto. El índice contiene metadatos de archivos y directorios, clasificación básica, fechas de modificación y hashes SHA-256 para archivos dentro del límite configurado. No contiene contenido fuente ni valores de secretos.

codenexusdocs index .

Opciones:

codenexusdocs index . --details
codenexusdocs index . --output docs/repository-index.json
codenexusdocs index . --force

El archivo predeterminado es:

docs/repository-index.json

El comando index no realiza llamadas a proveedores de IA.

`evidence`

Consulta el registro consolidado de evidencias que sustenta las detecciones de CodeNexusDocs. Cada observación tiene un ID determinista, dominio, fuente, tipo y fuerza. Las evidencias derivadas se marcan explícitamente para diferenciar conclusiones estructuradas de observaciones directas.

codenexusdocs evidence .
codenexusdocs evidence . --details
codenexusdocs evidence . --json
codenexusdocs evidence . --json --output docs/evidence.json

El comando no ejecuta el proyecto ni realiza llamadas de IA. El JSON completo también está disponible como ProjectInfo.evidence durante analyze --json y los mismos IDs pueden reutilizarse en el contexto de IA.

Tipo de proyecto

analyze muestra el tipo principal inferido y su nivel de confianza. Con --details también muestra la evidencia y las clasificaciones alternativas.

codenexusdocs analyze .
codenexusdocs analyze . --details

El dato queda disponible dentro del modelo JSON como projectType.

`api`

Analiza la API detectada y sus endpoints. Cuando el proyecto lo permite también identifica la integración OpenAPI/Swagger.

codenexusdocs api .

Generar OpenAPI YAML:

codenexusdocs api . --openapi

Generar OpenAPI JSON:

codenexusdocs api . --openapi --format json

Archivo personalizado:

codenexusdocs api . --openapi --output docs/openapi.yaml

Puede generar también una UI compatible con L5-Swagger cuando esa integración ya está presente en el proyecto.

Inteligencia de una ruta con IA

Stage 22 añade una segunda capa al comando api: después de detectar los endpoints, puedes seleccionar una ruta y pedir una explicación del flujo de código relacionado.

codenexusdocs api . --explain

También puedes seleccionar directamente una ruta:

codenexusdocs api . --route "GET /api/users/{id}"

El flujo es:

Endpoint
  ↓
Punto de entrada resoluble
  ↓
Funciones y llamadas internas
  ↓
Dependencias relevantes
  ↓
Modelos / entidades / validaciones / respuestas
  ↓
Selección de proveedor + modelo + nivel
  ↓
Preflight y costo
  ↓
Explicación estructurada

El trazado es determinista y limitado para evitar enviar el repositorio completo a la IA. Cuando una dependencia no puede resolverse estáticamente, CodeNexusDocs la marca como no resuelta en lugar de inventarla.

Opciones adicionales:

codenexusdocs api . --explain
codenexusdocs api . --route "GET /api/users/{id}"
codenexusdocs api . --route "GET /api/users/{id}" --refresh-ai

Úsalo para:

inventario de endpoints
revisión de API
generación OpenAPI
integración Swagger
documentación de API
explicación de una ruta con IA

`database`

Analiza la estructura de base de datos de forma estática.

codenexusdocs database .

Puede devolver información como:

migrations
Tables
Columns
Relations
Indexes

JSON:

codenexusdocs database . --json
codenexusdocs database . --json --output docs/database.json

Actualmente incluye análisis profundo específico para Laravel y Prisma.

`dependencies`

Construye un inventario de dependencias y lockfiles.

codenexusdocs dependencies .

Incluye cuando la fuente lo permite:

production/development
Direct/transitive
Declared/installed
Lockfiles
Versiones
Conflicts

JSON:

codenexusdocs dependencies . --json --output docs/dependencies.json

`environment`

Analiza la configuración del entorno sin imprimir valores secretos.

codenexusdocs environment .

Detecta señales de:

.env / .env.example
Configuration files
Environment variables
Docker / Compose
Required services
Variable usage

Los valores de variables no forman parte del reporte.

JSON:

codenexusdocs environment . --json --output docs/environment.json

`testing`

Detecta frameworks y estructuras de testing sin ejecutar los tests.

codenexusdocs testing .

Puede identificar, entre otros:

Jest / Vitest / Mocha / AVA / Jasmine
Playwright / Cypress
pytest / unittest
PHPUnit / Infection
JUnit / TestNG / Cucumber / Mockito
Dart test / flutter_test / integration_test
RSpec / Minitest
Go testing
xUnit / NUnit / MSTest

JSON:

codenexusdocs testing . --json --output docs/testing.json

`architecture`

Realiza el análisis arquitectónico profundo.

codenexusdocs architecture .

JSON:

codenexusdocs architecture . --json

Markdown:

codenexusdocs architecture . --markdown

Mermaid + HTML:

codenexusdocs architecture . --mermaid
codenexusdocs architecture . --mermaid --detailed

Puede modelar:

Architecture style
Layers
Modules
Components
Dependencies
Boundaries
Entry points
Services
Providers
Patterns
Metrics
Sources / evidence

Salidas típicas:

docs/architecture.json
docs/ARCHITECTURE.md
docs/architecture.mmd
docs/architecture.html

`installation` / `install`

Analiza cómo se instala y prepara el proyecto a partir de señales estáticas.

codenexusdocs installation .

Alias:

codenexusdocs install .

Detecta cuando están presentes:

Runtime
Package manager
Install commands
Build commands
Migration commands
Asset commands
Required tools

Los comandos encontrados no se ejecutan.

JSON:

codenexusdocs installation . --json --output docs/installation.json

`deployment`

Analiza cómo podría ejecutarse o desplegarse el proyecto según sus archivos y configuración.

codenexusdocs deployment .
codenexusdocs profile .

Puede detectar:

Docker / Compose
Procfile
Platforms
Start/build/migration processes
Workers
Queues
Cron
Database
Cache
Proxy

No realiza ningún despliegue.

JSON:

codenexusdocs deployment . --json --output docs/deployment.json

`generate`

Genera la documentación técnica base usando el modelo estático.

codenexusdocs generate .

Documentos disponibles:

README.md
INSTALLATION.md
ARCHITECTURE.md
API.md
DATABASE.md
ENVIRONMENT.md
TESTING.md
DEPLOYMENT.md
CONTRIBUTING.md
CHANGELOG.md

Seleccionar documentos:

codenexusdocs generate . --only readme,architecture,api

Elegir carpeta de salida:

codenexusdocs generate . --output docs/generated

Sobrescribir archivos existentes:

codenexusdocs generate . --force

Por defecto, los archivos existentes se conservan. Cuando la generación forzada incluye README.md, CodeNexusDocs crea o actualiza README_BAK.md con el contenido que existía inmediatamente antes de la generación.

Generación con IA

codenexusdocs generate . --ai

La generación con IA:

1. Analiza estáticamente el repositorio
2. Construye contexto enfocado
3. Selecciona evidencia relevante
4. Hace una petición estructurada al proveedor elegido
5. Valida la respuesta
6. Genera los documentos solicitados

En una ejecución sin caché se intenta utilizar una única petición de generación aunque se produzcan varios documentos.

Forzar una nueva petición:

codenexusdocs generate . --ai --refresh-ai

`ai-review`

Realiza una revisión documental con IA sin modificar la documentación existente.

codenexusdocs ai-review .

Devuelve una estructura con:

Summary
Claims
Insights
Warnings
Evidence references
Confidence
Usage / cost telemetry

JSON:

codenexusdocs ai-review . --json
codenexusdocs ai-review . --json --output docs/ai-review.json

Detalle:

codenexusdocs ai-review . --details

Forzar una nueva petición:

codenexusdocs ai-review . --refresh-ai

`ai-validate`

Valida una conexión real con el proveedor de IA seleccionado mediante una petición estructurada mínima. No inspecciona el repositorio, no utiliza la caché de resultados de IA y no aplica reintentos automáticos.

codenexusdocs ai-validate --provider gemini
codenexusdocs ai-validate --provider openai
codenexusdocs ai-validate --provider cerebras

Para ejecutar únicamente el preflight:

codenexusdocs ai-validate --provider gemini --preflight-only

Salida JSON:

codenexusdocs ai-validate --provider gemini --json

La validación en vivo realiza como máximo una petición de preflight y una de generación. Si el preflight determina que el proveedor no está disponible, la generación no se ejecuta.

🤖 Configuración de IA

Stage 21 admite tres proveedores y permite seleccionar el modelo compatible dentro de cada proveedor:

Google Gemini → 6 modelos disponibles
OpenAI        → 6 modelos disponibles
Cerebras      → 1 modelo disponible

El usuario selecciona proveedor → modelo → nivel de procesamiento. El catálogo del modelo también contiene su recomendación de uso, ventana de contexto, salida máxima y tarifas de referencia.

Selección del proveedor

Cuando ejecutas una función de IA, CodeNexusDocs siempre muestra el menú del proveedor, incluso cuando ya existe un proveedor configurado.

codenexusdocs generate . --ai
codenexusdocs ai-review .

La configuración guardada solo sirve como referencia para config get; no se utiliza para saltarse el menú.

Ejemplo de menú:

── PROVEEDOR DE IA ──
  Elige el proveedor para esta ejecución...

? Selecciona el proveedor de IA:
❯ Google Gemini
  OpenAI
  Cerebras

? Selecciona el modelo de IA:
❯ GPT-6 Sol · gpt-6-sol · $2/$10 per 1M
  GPT-6 Luna · gpt-6-luna · $0.1/$0.5 per 1M
  ...

El menú también indica si ya existe una API key para cada proveedor.

API key existente

Después de seleccionar el proveedor:

¿Hay una key almacenada?
        ↓
       Sí
        ↓
  se reutiliza

No se vuelve a pedir la clave por cada ejecución.

API key faltante

Si no existe una credencial:

No hay API key
      ↓
Se solicita de forma oculta
      ↓
Se almacena en el almacén seguro del sistema

También puedes configurarla manualmente:

codenexusdocs config set ai-key

OpenAI: saldo de créditos vs límites de API

Para OpenAI, CodeNexusDocs separa explícitamente el saldo de créditos de los límites de solicitudes/tokens. Un saldo positivo no implica que todos los límites de la organización o del proyecto estén disponibles. El saldo actual de créditos no se obtiene mediante el endpoint de preflight de modelos utilizado por CodeNexusDocs, por lo que el CLI no mostrará un valor inventado: indicará que debe verificarse en Billing. OpenAI documenta que el saldo prepagado y los límites de uso/gasto son controles independientes.

Durante el preflight de OpenAI se mostrará: proveedor, modelo, costo máximo estimado, estado del saldo (si no está expuesto se marca como no consultable), límites de rate limit realmente recibidos y la capacidad de la generación. Si un header no existe, CodeNexusDocs lo trata como desconocido, nunca como 0.

Cuando OpenAI rechaza una solicitud, el diagnóstico distingue entre credit_balance_exhausted, insufficient_quota, límites de organización/proyecto y rate limit. La salida siempre incluye la causa específica disponible y una acción recomendada.

API key inválida

Si la credencial configurada es rechazada con un error de autenticación real:

Key existente
      ↓
Preflight / petición
      ↓
401 / error explícito de autenticación
      ↓
Se solicita una nueva key una sola vez

Una respuesta 429 por cuota o límite no provoca que CodeNexusDocs solicite otra API key. Tampoco existe fallback automático a otro proveedor.

Crear una API key

Cada usuario debe utilizar sus propias credenciales. CodeNexusDocs nunca utiliza una API key del desarrollador ni incluye claves dentro del paquete npm.

Google Gemini

Entra en Google AI Studio.
Abre la sección de API Keys o utiliza Get API key.
Crea o selecciona el proyecto que utilizarás con Gemini API.
Crea la key y cópiala de forma segura.
No la publiques ni la añadas al repositorio.

Google documenta que el acceso al Free Tier y sus límites dependen del proyecto y del modelo. Los límites activos deben comprobarse en AI Studio.

Referencia: Gemini API keys.

OpenAI

Entra en OpenAI Platform.
Abre API Keys.
Selecciona o crea el proyecto que utilizarás.
Crea una nueva secret key.
Copia la clave y mantenla privada.
Controla el gasto desde los límites y configuración de tu proyecto.

La facturación de OpenAI corresponde a la cuenta/proyecto del usuario.

Referencia: OpenAI API projects.

Cerebras

Entra en Cerebras.
Inicia sesión o crea tu cuenta.
Abre la administración de API keys.
Crea una key para tu proyecto/cuenta.
Cópiala y mantenla privada.

Cerebras documenta límites Free Tier para modelos compatibles; los límites efectivos dependen de la cuenta y pueden cambiar.

Referencia: Cerebras Rate Limits.

Variables de entorno

Para uso manual o CI/CD también se admiten:

Gemini:
  CODENEXUSDOCS_GEMINI_API_KEY
  GEMINI_API_KEY

OpenAI:
  CODENEXUSDOCS_OPENAI_API_KEY
  OPENAI_API_KEY

Cerebras:
  CODENEXUSDOCS_CEREBRAS_API_KEY
  CEREBRAS_API_KEY

Las variables de entorno tienen prioridad sobre el almacén seguro.

`config`

Seleccionar idioma:

codenexusdocs config set language es
codenexusdocs config set language en

Seleccionar proveedor guardado como referencia:

codenexusdocs config set ai-provider gemini
codenexusdocs config set ai-provider openai
codenexusdocs config set ai-provider cerebras

Configurar key de forma interactiva:

codenexusdocs config set ai-key

Eliminar la key del proveedor seleccionado en el menú:

codenexusdocs config remove ai-key

Consultar estado sin mostrar secretos:

codenexusdocs config get

El archivo de configuración solo guarda preferencias como el proveedor seleccionado. Las API keys se almacenan en el almacén de credenciales del sistema operativo.

📊 Preflight, tokens y costos

Antes de una petición nueva, CodeNexusDocs muestra un AI Preflight. Esta sección no ejecuta la generación todavía; presenta la estimación y, cuando el proveedor lo permite, consulta metadatos reales del modelo y límites reportados por la API.

La información incluye:

Proveedor
Modelo
Credencial y origen
Tokens de entrada estimados
Máximo de tokens de salida
Tokens estimados de la petición
Ventana de contexto
Presupuesto de contexto
Margen de contexto
Límite real de entrada del proveedor
Límite real de salida del proveedor
Tarifa de entrada / salida
Costo máximo estimado
Free Tier de referencia
Disponibilidad del modelo
Método de comprobación
Límites/cuota en vivo cuando el proveedor los expone

La salida utiliza columnas separadas para evitar que títulos y valores se junten.

Después de la petición, el bloque de AI USAGE prioriza los datos reales devueltos por la API del proveedor. CodeNexusDocs normaliza las diferencias entre proveedores y además calcula el costo equivalente usando esos tokens reales y el snapshot de precios configurado.

Input tokens reales
Output tokens reales
Total tokens
Cached input tokens
Reasoning tokens
Tool-use prompt tokens cuando existe
Request ID
Nivel de servicio cuando existe
Estado / motivo de finalización cuando existe
Costo reportado por el proveedor cuando existe
Costo de entrada calculado
Costo de entrada en caché calculado
Costo de salida calculado
Costo total calculado
Costo equivalente a tarifa pública
Costo máximo estimado
Duración
Tokens por segundo
Límites en vivo / tokens restantes
Fuente del uso
Base del cálculo

Tokens y costos reales

Los proveedores sí devuelven información de uso de tokens en la respuesta de generación. Gemini expone usageMetadata con tokens de entrada, salida, caché, razonamiento y total; OpenAI expone response.usage con entrada, salida, caché, razonamiento y total; Cerebras expone usage con entrada, salida, total y detalles de caché/razonamiento. CodeNexusDocs guarda esos valores como uso reportado por el proveedor, en lugar de sustituirlos por estimaciones locales. Gemini usage metadata y OpenAI response usage

En OpenAI, además de entrada, entrada en caché y salida, los modelos con escritura en caché tienen una tarifa separada. CodeNexusDocs conserva esa tarifa y la utiliza para reconciliar el costo de entrada no previamente almacenada en caché.

Las APIs de generación no entregan de forma general el importe monetario final facturado a la cuenta. Por eso CodeNexusDocs calcula un costo equivalente a partir de los tokens reales y la tarifa pública registrada para el proveedor/modelo; cuando una API futura exponga un importe de billing, el modelo de datos ya admite conservarlo por separado. Esta diferencia se muestra explícitamente en el CLI para no confundir un cálculo de tarifa pública con el cargo real de la cuenta.

El catálogo de modelos registra la tarifa base de cada modelo y calcula el costo estimado con esa configuración. Para los modelos de OpenAI que tienen precio de contexto largo, cuando la petición supera el umbral configurado se aplican automáticamente los multiplicadores publicados por el proveedor; por ejemplo, en GPT-6 y GPT-5.6 el contexto largo usa x2 en entrada/caché y x1.5 en salida. Gemini 3.1 Pro aplica su tramo de precio para prompts de más de 200K tokens.

El selector muestra para cada modelo para qué escenario está recomendado y las tarifas base, y el preflight muestra la tarifa efectiva usada en el cálculo.

Comprobación en vivo de límites

No todos los proveedores exponen la misma información.

Gemini: models.get permite comprobar que el modelo existe para la API key y obtener sus límites de tokens. La API estándar no expone de forma general la cuota restante del Free Tier; los límites activos se consultan en AI Studio.
OpenAI: la API puede devolver headers x-ratelimit-* con límites, tokens/solicitudes restantes y ventanas de reset. CodeNexusDocs los aprovecha cuando están presentes.
Cerebras: la API devuelve headers de rate limit con solicitudes y tokens restantes y sus tiempos de reset. CodeNexusDocs los aprovecha tanto en el preflight como después de la generación.

El Free Tier de Gemini no se presenta como una cifra fija garantizada porque Google especifica que los límites dependen del modelo/proyecto y pueden cambiar. La autoridad es el límite activo mostrado por Google AI Studio.

Capacidad restante y preflight de IA

El preflight de CodeNexusDocs distingue entre existencia del modelo, credencial válida y capacidad disponible para la generación. Cuando el proveedor expone límites en la respuesta HTTP, CodeNexusDocs registra los límites, lo que queda disponible y la ventana de reinicio, y compara esa capacidad con los tokens estimados que requiere la documentación.

OpenAI: aprovecha los headers x-ratelimit-*, incluyendo límites y valores restantes de solicitudes/tokens y, cuando están presentes, los límites de tokens a nivel de proyecto.
Cerebras: aprovecha los headers x-ratelimit-* de la API para mostrar solicitudes restantes del día y tokens restantes de la ventana por minuto; las ventanas se conservan por separado porque corresponden a métricas distintas.
Google Gemini: la API estándar no expone de forma general la cuota restante del proyecto en la respuesta de metadatos del modelo. CodeNexusDocs muestra esa limitación de forma explícita y no inventa una cuota restante; los límites activos se consultan en Google AI Studio. Si el proveedor responde 429 con un tiempo de reintento, ese tiempo se conserva para el diagnóstico; no se convierte artificialmente en una cuota restante.

La métrica Capacidad para esta generación indica si, con la capacidad conocida en ese momento, la solicitud estimada cabe en la ventana disponible. No constituye una garantía de disponibilidad futura porque los límites pueden cambiar entre el preflight y la generación.

Cambio interactivo de API key

Cuando se selecciona un proveedor que ya tiene una API key configurada, el CLI pregunta si se desea cambiarla para esa ejecución. Si se reemplaza una clave almacenada en el almacén seguro del sistema, la nueva clave se guarda de forma segura. Si la clave original proviene de una variable de entorno, CodeNexusDocs no modifica la variable y la nueva clave se utiliza únicamente durante la ejecución actual.

Diagnóstico técnico de errores de proveedores

Cuando una operación de IA falla en cualquiera de los proveedores soportados (Google Gemini, OpenAI o Cerebras), CodeNexusDocs muestra siempre la causa específica detectada y una acción recomendada. El diagnóstico técnico es seguro: no imprime la API key ni el contenido completo del prompt.

El diagnóstico puede incluir, según lo que exponga el SDK/API:

HTTP status
Provider code / status / type
Provider reason / domain
Provider message
Request ID / Response ID cuando exista
Retry-After
Finish reason / Block reason
Número de candidatos/opciones
Tokens reportados
Longitud de la respuesta
Motivo y fase del fallo
Causa específica detectada por CodeNexusDocs
Acción recomendada según código, estado, fase y motivo
Headers de rate limit disponibles

La información se limita a metadatos seguros; CodeNexusDocs no imprime cuerpos completos de error ni solicitudes completas para evitar exponer información sensible. Incluso cuando un SDK no proporciona metadatos detallados, el CLI conserva la fase, código y mensaje de la excepción para no mostrar únicamente un error genérico.

Los errores 429 de Gemini representan límites de frecuencia/cuota y los 503 indican indisponibilidad temporal; Google documenta ambos estados y recomienda reintentos controlados. Cerebras expone headers x-ratelimit-* con capacidad restante y ventanas de reinicio, y puede rechazar una solicitud antes de procesarla cuando la suma estimada de entrada y max_completion_tokens supera la capacidad disponible. Gemini API errors y Cerebras Rate Limits

Optimización

La etapa utiliza varias medidas para reducir el consumo:

Una sola petición estructurada por ejecución
Contexto específico por documento
Selección priorizada de archivos
Compresión mediante JSON compacto
Eliminación de duplicación entre análisis/evidencia
Hard-fit determinista del contexto
Presupuestos distintos por proveedor
Caché local de resultados validados
No se ejecuta countTokens como petición adicional; los tokens reales se toman de la respuesta de generación cuando el proveedor los devuelve
Los errores transitorios (408/429/5xx) se reintentan automáticamente con exponential backoff y jitter; se respeta `Retry-After` cuando el proveedor lo proporciona.
No hay fallback automático entre proveedores

El caché local se encuentra en:

~/.codenexusdocs/ai-cache

Cuando hay un hit de caché, se evita la petición de IA y el uso de proveedor para esa generación.

`frameworks`

Analiza los frameworks que pueden inferirse estáticamente del repositorio mediante perfiles y evidencia.

codenexusdocs frameworks .

Opciones:

codenexusdocs frameworks . --details
codenexusdocs frameworks . --json
codenexusdocs frameworks . --json --output docs/frameworks.json
codenexusdocs frameworks . --limit 5

La evidencia puede proceder de:

manifest
dependency
file
(directory)

Los perfiles se clasifican como:

specialized
profiled

`check`

Verifica si la documentación existente coincide con la documentación esperada por los generadores deterministas.

codenexusdocs check .

Opciones comunes:

codenexusdocs check . --only readme,architecture,api
codenexusdocs check . --docs docs/generated
codenexusdocs check . --json
codenexusdocs check . --json --output docs/documentation-drift.json

Estados:

✓ Synchronized
~ Changed
✗ Missing

Código de salida:

0 → sin drift
1 → documentación modificada o faltante

Es especialmente útil en CI/CD.

`diff`

Muestra las diferencias entre la documentación actual y la esperada.

codenexusdocs diff .

Ejemplos:

codenexusdocs diff . --only readme,api
codenexusdocs diff . --details
codenexusdocs diff . --json

Produce un diff unificado y reutiliza los mismos generadores de generate.

Opciones globales de salida

Las opciones que aparecen en los comandos compatibles son:

--details
--verbose
--quiet
--json
--output <path>
--lang <es|en>

--details muestra más elementos detectados.

--verbose conserva el detalle y añade información útil para diagnóstico y tiempos.

--quiet reduce la salida humana al mínimo; en los comandos de IA el menú interactivo del proveedor y las solicitudes de credenciales siguen siendo necesarios.

--json conserva el modelo estructurado para automatizaciones y archivos de salida.

`--help` y `--version`

Consultar ayuda:

codenexusdocs --help
codenexusdocs generate --help
codenexusdocs ai-review --help

Consultar versión:

codenexusdocs --version

La versión procede de package.json.

🖥️ Salida de consola

CodeNexusDocs está diseñado para mantener la salida de la terminal compacta y útil. Los comandos muestran un resumen por defecto y permiten profundizar únicamente cuando sea necesario.

Vista resumida

codenexusdocs analyze .
codenexusdocs index .
codenexusdocs api .
codenexusdocs database .
codenexusdocs architecture .
codenexusdocs installation .
codenexusdocs deployment .

La salida por defecto prioriza:

información esencial del proyecto
conteos y métricas
estado del análisis
resultados relevantes
rutas de archivos generados

Las listas grandes de dependencias, tablas, endpoints, módulos u otros elementos no se imprimen completas por defecto.

Vista detallada

Usa --details cuando necesites inspeccionar los elementos detectados:

codenexusdocs analyze . --details
codenexusdocs api . --details
codenexusdocs database . --details
codenexusdocs architecture . --details

Modo verbose

--verbose conserva la vista detallada y añade información adicional útil para diagnóstico y medición:

codenexusdocs analyze . --verbose

Modo quiet

--quiet reduce la salida al mínimo y está pensado especialmente para scripts o automatizaciones:

codenexusdocs analyze . --quiet

Salida JSON

Para integraciones y procesamiento automático:

codenexusdocs analyze . --json

Cuando el comando admita un archivo de salida:

codenexusdocs analyze . --json --output docs/analysis.json

La salida humana y la salida JSON están separadas: el JSON mantiene la información estructurada completa sin obligar a la terminal a mostrar listas extensas.

🌍 Lenguajes y frameworks

CodeNexusDocs utiliza una estrategia de detección universal + analizadores especializados.

Hay que diferenciar entre:

Detección universal: reconoce tecnologías y estructuras sin depender de un framework concreto.
Análisis especializado: aplica reglas específicas de un framework.
Validación profunda: confirma que el análisis funciona de extremo a extremo sobre proyectos reales.

El catálogo del proyecto se amplía progresivamente; no todos los frameworks tienen todavía el mismo nivel de profundidad o validación.

Lenguajes contemplados

PHP
Python
Java
Kotlin
Groovy
TypeScript
JavaScript
Dart
C#
Ruby
Go
Rust
Elixir
Scala

Frameworks / ecosistemas contemplados por el proyecto

PHP

Laravel
Symfony
CodeIgniter
Laravel Livewire

Python

Django
Django REST Framework
Flask
FastAPI

Java

Spring Boot
Micronaut
Quarkus
Play Framework

Kotlin

Ktor

Groovy

Grails

TypeScript

NestJS
Fastify
Next.js
Nuxt
Vue
React
Angular
Svelte
AdonisJS
React Native
Ionic

JavaScript

Express
Koa
Hapi

Dart

Flutter

C#

ASP.NET Core
Blazor

Ruby

Ruby on Rails
Sinatra

Go

Gin
Fiber
Echo

Rust

Axum
Actix Web
Rocket

Elixir

Phoenix
Plug

Scala

Akka HTTP
Play Framework

🏗️ Arquitectura interna

La estructura conceptual es:

Repository
      ↓
Universal Detection Engine
      ↓
ProjectInfo
      ↓
Project Profile Engine
      ↓
Specialized Analyzer Engine
      ↓
Framework / Language Analyzer
      ↓
Structured Documents
      ↓
Generators
      ↓
Documentation

Los módulos internos se organizan aproximadamente como:

src/
├── cli/
├── config/
└── core/
    ├── analyzer/
    ├── analyzers/
    ├── api/
    ├── architecture/
    ├── database/
    ├── installation/
    ├── deployment/
    ├── evidence/
    ├── dependencies/
    ├── frameworks/
    ├── indexing/
    ├── profiles/
    ├── ai/
    │   └── context/
    ├── documentation/
    ├── environment/
    ├── testing/
    ├── detectors/
    ├── registries/
    └── models/

📦 Historial de versiones

`1.9.9` — npm Distribution Hardening

La versión 1.9.9 endurece el proceso de empaquetado y publicación de CodeNexusDocs para que el paquete npm tenga una superficie controlada, verificable y reproducible.

El flujo de distribución valida antes de publicar:

package.json / package-lock.json
        ↓
Build
        ↓
CLI bin + versión
        ↓
npm pack --dry-run
        ↓
Allow-list del paquete
        ↓
Secret / credential scan
        ↓
Release check
        ↓
Publish / publish --dry-run

Incluye:

✅ Verificación de coherencia de versión
✅ Verificación de `dist/cli/index.js`
✅ Verificación de shebang del CLI
✅ Verificación de `codenexusdocs --version`
✅ Allow-list del contenido publicado
✅ Detección de archivos de credenciales
✅ Detección de patrones de API keys
✅ Verificación de README, LICENSE y logo
✅ Empaquetado `versiones/` multiplataforma
✅ Release check reproducible

Nuevos scripts de desarrollo/distribución:

npm run release:check
npm run pack:verify
npm run pack:version
npm run publish:verify

release:check compila el proyecto, verifica la versión que reporta el ejecutable y comprueba la superficie real que npm pack --dry-run prepararía para publicar. No publica la versión ni crea una llamada al registry por sí mismo.

npm recomienda utilizar npm pack --dry-run y npm publish --dry-run para inspeccionar qué se enviaría al registry antes de publicar. El README de npm debe permanecer en la raíz del paquete, y el campo files permite mantener una superficie explícita de publicación.

`2.0.0` — Stage 22 Completion & Route Intelligence Cleanup

Cierra formalmente la Stage 22 — API Route Intelligence. La capa api --explain queda orientada a explicar el flujo real de una ruta sin exponer IDs técnicos de evidencia en la salida del usuario.

Incluye:

✅ Explicación estructurada de una ruta API
✅ Resolución estática de controller / handler / function
✅ Trazado acotado de llamadas internas y dependencias relacionadas
✅ Modelos / entidades / schemas / validaciones / middleware / respuestas
✅ Compatibilidad representativa con múltiples lenguajes y familias de frameworks
✅ Reutilización del sistema de proveedor, modelo, nivel, preflight, costo y caché de IA
✅ Sin etiquetas [ev] ni evidenceIds en la respuesta de Stage 22
✅ Filtrado de llamadas comunes de framework / ORM / query builder para reducir falsos unresolved
✅ Invalidación de explicaciones de caché anteriores mediante versión de caché `2`
✅ Pruebas deterministas de trazado y filtrado de unresolved

La trazabilidad de archivos continúa utilizándose internamente para fundamentar la explicación, pero no se presenta como una lista de IDs de evidencia al usuario.

Esta versión considera cerrada la etapa funcional. Mejoras futuras de reutilización documental, CI/CD, plugins, monorepos y cloud pertenecen al roadmap posterior.

`1.9.11` — Stage 21 Completion & Release Certification

Cierra formalmente la Stage 21 — AI Documentation Intelligence. Esta versión mantiene la generación preparada para proyectos grandes y añade progreso de ejecución visible durante la generación de IA. Los proveedores compatibles utilizan streaming cuando su API lo permite, mientras CodeNexusDocs mantiene un heartbeat para evitar que una generación prolongada parezca bloqueada. Esta versión sincroniza las versiones de motor que todavía estaban congeladas en releases anteriores, incorpora una prueba de cierre de etapa y endurece la comprobación de documentación, distribución y capacidades AI sin realizar llamadas reales a proveedores durante los tests.

El gate de cierre verifica: package.json, package-lock.json, README.md, README.en.md, la integración de los tres proveedores, contexto y optimización AI, caché, telemetría, validación en vivo, perfiles, evidencia, pruebas existentes y la superficie de distribución.

La certificación es determinista y local; npm run test:stage21 no requiere ni utiliza API keys.

Los ajustes posteriores mantienen la versión 1.9.11: la selección interactiva de proveedor/modelo/nivel conserva el modelo elegido durante preflight y generación; el cálculo de costos para OpenAI contempla las escrituras en caché y el multiplicador de contexto largo; y la portada del PDF utiliza el recurso de logo claro dedicado del template para evitar fondos blancos cuando se genera sobre la portada oscura.

`1.9.10` — Real AI Provider Validation

Añade una validación explícita en vivo para los proveedores Gemini, OpenAI y Cerebras. La validación utiliza una petición estructurada mínima, comprueba localmente el resultado, evita generar cuando el preflight declara el proveedor no disponible y desactiva los reintentos automáticos para mantener acotados el costo y el número de peticiones.

`1.9.9.1` — README Language Navigation

Esta revisión de mantenimiento añade un selector multiplataforma entre README.md y README.en.md y hace que la generación documental produzca ambas variantes del README.

La versión npm permanece en 1.9.9 para conservar una versión SemVer publicable; 1.9.9.1 identifica esta revisión interna del proyecto.

`1.9.8` — Confidence Explainability & UX

La versión 1.9.8 hace explicable la confianza dinámica que ya utiliza CodeNexusDocs. El porcentaje continúa siendo un resultado heurístico calculado a partir de la evidencia; esta versión añade el detalle que explica de dónde sale ese valor.

Las detecciones que ya utilizan el ConfidenceEngine pueden exponer, además de confidence, un bloque confidenceDetails con:

Support
Source breadth
Evidence diversity
Separation from alternatives
Evidence count
Unique sources
Unique evidence kinds

En modo --details, la CLI muestra los factores que favorecen la confianza y las limitaciones detectadas. Esto se aplica a tipo de proyecto, perfiles, frameworks, testing y arquitectura. El mismo bloque queda disponible en las salidas JSON para que integraciones externas puedan explicar el resultado sin volver a ejecutar el análisis.

Evidence
   ↓
ConfidenceEngine
   ↓
ConfidenceResult
   ↓
Explainability
   ├── Supporting factors
   └── Limitations

La generación de estas explicaciones es local y determinista; no realiza llamadas a IA.

`1.9.7` — Evidence & Context Optimization

La versión 1.9.7 añade una capa de optimización determinista sobre la evidencia que entra al contexto de IA. El objetivo es reducir duplicación y ruido sin alterar el análisis estático ni el Evidence Ledger.

Static Analysis
      ↓
Evidence Ledger
      ↓
Evidence Optimizer
      ↓
Focused AI Context
      ↓
LLM

EvidenceOptimizer combina:

relevancia respecto de los documentos solicitados;
fuerza y tipo de evidencia;
señales directas frente a derivadas;
independencia de las fuentes;
límites por dominio y por cantidad;
presupuesto de contexto disponible para la ejecución.

Las evidencias de archivos fuente seleccionadas por el snapshot se conservan. La optimización solo reduce metadatos redundantes de evidencia antes de construir la petición final.

El preflight muestra cuánta evidencia de análisis se recibió y cuánta se conservará después de la optimización. No se realizan llamadas adicionales al proveedor.

`1.9.6` — Evidence Ledger & Traceability

Incluye el campo opcional kind en ProjectTypeEvidence para mantener compatibilidad entre el detector de tipo, el motor de confianza dinámica y el ledger de evidencias.

Añade una capa determinista de evidencia consolidada sobre el modelo estructurado. Cada observación recibe un ID estable y se conserva su dominio, fuente, tipo, fuerza y si es directa o derivada. El registro puede consultarse desde analyze --json, desde el nuevo comando evidence o como docs/evidence.json.

codenexusdocs evidence .
codenexusdocs evidence . --details
codenexusdocs evidence . --json

La evidencia no almacena contenido fuente completo ni credenciales. Los IDs son deterministas para la misma combinación de dominio, señal, fuente y tipo, permitiendo reutilizar la misma referencia entre confianza, contexto de IA y documentación.

`1.9.4.1` — Dynamic Evidence Confidence

La versión 1.9.4.1 sustituye la conversión estática de scores a porcentajes por un cálculo dinámico de confianza basado en la evidencia observada en cada análisis.

Evidencia detectada
      ↓
Fuerza de señal
      ↓
Fiabilidad + especificidad
      ↓
Retornos decrecientes por repetición de la misma fuente
      ↓
Diversidad de fuentes + tipos de evidencia
      ↓
Separación frente a candidatos competidores
      ↓
Confianza dinámica 0–100

La confianza es una métrica heurística, no una probabilidad estadística. Los pesos de las reglas representan la fuerza de una señal, mientras que el porcentaje final se recalcula según lo que realmente exista en el repositorio analizado.

Se aplica a las salidas de análisis de tipo de proyecto, frameworks, ecosistemas, arquitectura y testing. Esto evita que una única carpeta, archivo o manifest produzca automáticamente el mismo porcentaje que una clasificación respaldada por varias fuentes independientes.

La funcionalidad no añade llamadas a IA ni requiere ejecutar el proyecto.

`1.9.4` — Project Type Detection

La versión 1.9.4 añade una clasificación determinista del tipo principal de proyecto utilizando el índice del repositorio introducido en 1.9.3.

✅ Full-stack application
✅ Backend / API
✅ Frontend application
✅ Mobile application
✅ Desktop application
✅ CLI tool
✅ Library / package
✅ Monorepo
✅ Static site
✅ Infrastructure / DevOps
✅ Documentation project
✅ Unknown project type

La detección se integra en analyze, conserva nivel de confianza y evidencia de los archivos/directorios que originan la clasificación y aparece también en el README determinista generado. No ejecuta el proyecto ni realiza llamadas de IA.

El análisis normal reutiliza el inventario determinista sin calcular hashes de archivos, evitando introducir un coste innecesario en analyze. El comando explícito index mantiene el cálculo de SHA-256 para el inventario reutilizable.

`1.9.3.1` — Cross-platform README Navigation

Patch de navegación para que los índices internos del README puedan utilizarse desde los tres renderizadores objetivo: GitHub, npm y Bitbucket Cloud. npm renderiza el README como GitHub Flavored Markdown mediante la API de GitHub, mientras que Bitbucket Cloud genera anchors con el prefijo markdown-header-.

✅ Índice GitHub / npm
✅ Índice Bitbucket Cloud
✅ Índice de versiones en ambos formatos
✅ Slugs Unicode deterministas
✅ Manejo consistente de títulos duplicados

No se cambia el comando index introducido en 1.9.3; sigue disponible como capacidad futura.

`1.9.3` — README Navigation & Documentation Indexes

La versión 1.9.3 consolida la navegación documental de CodeNexusDocs y conserva el índice determinista del repositorio incorporado en esta versión.

✅ Índice navegable del README
✅ Índice de versiones dentro del README
✅ Enlaces directos a los títulos del README
✅ README generado con índice de los documentos Markdown generados
✅ Enlaces relativos entre documentos para uso local y en repositorios
✅ Navegación compatible con generación estática y generación con IA
✅ Índice determinista del repositorio como capacidad reutilizable para futuras versiones
✅ Comando `index` conservado para uso futuro

El README raíz mantiene una navegación separada para el contenido del documento y para el historial de versiones. Cuando generate crea documentación Markdown, el README.md generado añade automáticamente enlaces a los demás documentos seleccionados en la misma ejecución.

La navegación de 1.9.3 se amplía en 1.9.3.1 con dos variantes por plataforma: #<slug> para GitHub/npm y #markdown-header-<slug> para Bitbucket Cloud.

La indexación determinista del repositorio sigue disponible mediante:

codenexusdocs index .

Esta capacidad no realiza llamadas de IA y no almacena el contenido fuente dentro del índice.

`1.9.2` — Safe README Regeneration Backup

Añade un mecanismo determinista de

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Code Nexus Docs

🇪🇸 Español / 🇬🇧 English

📚 Índice del documento

GitHub / npm

Bitbucket Cloud

📦 Índice de versiones

GitHub / npm

Bitbucket Cloud

📦 ¿Qué es CodeNexusDocs?

⚡ Instalación para usuarios finales

Requisitos

Instalación global

Usar sin instalación global

🚀 Primer uso

🧭 Referencia completa de comandos

Resumen rápido

analyze

index

evidence

Tipo de proyecto

api

Inteligencia de una ruta con IA

database

dependencies

environment

testing

architecture

installation / install

deployment

generate

Generación con IA

ai-review

ai-validate

🤖 Configuración de IA

Selección del proveedor

API key existente

API key faltante

OpenAI: saldo de créditos vs límites de API

API key inválida

Crear una API key

Google Gemini

OpenAI

Cerebras

Variables de entorno

config

📊 Preflight, tokens y costos

Tokens y costos reales

Comprobación en vivo de límites

Capacidad restante y preflight de IA

Cambio interactivo de API key

Diagnóstico técnico de errores de proveedores

Optimización

frameworks

check

diff

Opciones globales de salida

--help y --version

🖥️ Salida de consola

Vista resumida

Vista detallada

Modo verbose

Modo quiet

Salida JSON

🌍 Lenguajes y frameworks

Lenguajes contemplados

Frameworks / ecosistemas contemplados por el proyecto

PHP

Python

Java

Kotlin

Groovy

TypeScript

JavaScript

Dart

`analyze`

`index`

`evidence`

`api`

`database`

`dependencies`

`environment`

`testing`

`architecture`

`installation` / `install`

`deployment`

`generate`

`ai-review`

`ai-validate`

`config`

`frameworks`

`check`

`diff`

`--help` y `--version`

`1.9.9` — npm Distribution Hardening

`2.0.0` — Stage 22 Completion & Route Intelligence Cleanup

`1.9.11` — Stage 21 Completion & Release Certification

`1.9.10` — Real AI Provider Validation

`1.9.9.1` — README Language Navigation

`1.9.8` — Confidence Explainability & UX

`1.9.7` — Evidence & Context Optimization

`1.9.6` — Evidence Ledger & Traceability

`1.9.4.1` — Dynamic Evidence Confidence

`1.9.4` — Project Type Detection

`1.9.3.1` — Cross-platform README Navigation

`1.9.3` — README Navigation & Documentation Indexes

`1.9.2` — Safe README Regeneration Backup