Jira Support LLM

Jira Support LLM es una extensión de VS Code diseñada para automatizar y optimizar el primer análisis (triage) de tickets de soporte en Jira, aprovechando de manera nativa la Inteligencia Artificial integrada en el editor a través de GitHub Copilot (utilizando la API vscode.lm de VS Code).

La extensión consulta periódicamente los tickets de Jira mediante JQL, evalúa su relevancia frente a un catálogo local de diagnósticos técnicos escritos en Markdown, extrae información faltante, identifica incidentes y publica un comentario estructurado de diagnóstico en Jira de manera automática. Además, ofrece un potente panel interactivo dentro del editor para visualizar, buscar y avanzar el flujo de trabajo de los tickets sin salir de VS Code.

🚀 Capacidades clave

• Integración Nativa de IA en VS Code: Consume de forma directa los modelos de chat de GitHub Copilot (como copilot-gpt-4o, copilot-gpt-4 u otros disponibles) mediante la API oficial vscode.lm.selectChatModels.
• Clasificación por Scoring Paralelo: Evalúa cada ticket en paralelo contra un conjunto de guías de diagnóstico escritas en Markdown (.md). El modelo otorga un puntaje de relevancia (0 a 100). El diagnóstico con mayor puntaje que supere el umbral configurado (scoreThreshold) es seleccionado para realizar el análisis profundo.
• Contexto de Proyecto Adicional: Permite inyectar un archivo de documentación del proyecto (promptsDocumentation) al contexto del LLM. Esto le da visibilidad de la arquitectura, APIs o dependencias del proyecto al evaluar relevancia y redactar el diagnóstico.
• Análisis Genérico Inteligente: Si no se configuran prompts o si ninguno supera el umbral de coincidencia, se realiza un análisis de soporte general y se guarda el ticket en unclassified-tickets/ para futuras mejoras del catálogo.
• Panel Webview Interactivo:
  • Filtros avanzados: Búsqueda en tiempo real por texto (clave, resumen, reportante, clasificación) y filtrado por estado de conclusión de la IA.
  • Estadísticas de control: Métricas en vivo del estado de los tickets (requieren atención, completos, incidentes, cerrados).
  • Transiciones de Jira directas: Consulta dinámicamente los estados disponibles para un ticket en Jira y permite transicionar su estado (ej. de To Do a In Progress o Done) directamente desde el panel.
  • Indicador de urgencia por color: El borde izquierdo de cada tarjeta cambia visualmente (verde, amarillo, rojo y fondo de emergencia) según la antigüedad del ticket en relación al umbral configurado (elapsedTimeThresholdHours).
• Notificaciones de Escritorio en Tiempo Real: Envía alertas de VS Code al detectar nuevos tickets asignados entre ciclos de consulta, facilitando una respuesta rápida.
• Caché y Persistencia Local: Almacena el estado y los análisis en workspaceState para evitar duplicidad de comentarios en Jira.
• Seguridad Garantizada: El token de Jira se almacena cifrado localmente mediante el llavero del sistema de VS Code utilizando la API context.secrets.

🛠️ Requisitos

• Node.js 20 o superior.
• VS Code 1.90.0 o superior.
• Extensión GitHub Copilot instalada y activa en el cliente con acceso a modelos de chat.
• Cuenta de Jira con correo electrónico y un API Token activo.

⏱️ Inicio rápido

1. Instalar dependencias y compilar:

   npm install
   npm run compile
   

2. Iniciar sesión de depuración: Abre el repositorio en VS Code y presiona F5 para lanzar una instancia de desarrollo de VS Code con la extensión cargada (Extension Development Host).

3. Configurar ajustes iniciales: En la nueva ventana, abre la configuración de VS Code e ingresa los valores para jiraClassifier.*. Al activarse la extensión, se solicitará de forma segura tu Jira API Token.

4. Operar la extensión: Abre el panel Jira Support LLM desde la barra de actividades de VS Code o ejecuta Jira Support LLM: Iniciar Soporte desde la paleta de comandos (Cmd+Shift+P / Ctrl+Shift+P).

⚙️ Configuración

Todos los parámetros son configurables desde la interfaz de Configuración de VS Code buscando Jira Support LLM o directamente en tu archivo settings.json:

Ejemplo de settings.json para desarrollo:

{
  "jiraClassifier.jiraUrl": "https://myco.atlassian.net",
  "jiraClassifier.jiraEmail": "soporte@myco.com",
  "jiraClassifier.jiraProject": "BANK",
  "jiraClassifier.jiraJql": "project = BANK AND status != Closed ORDER BY updated DESC",
  "jiraClassifier.promptsDirectory": "/Users/usuario/Projects/jira-ticket-support-vscode/examples",
  "jiraClassifier.promptsDocumentation": "/Users/usuario/Projects/jira-ticket-support-vscode/doc/documentation/documentation.md",
  "jiraClassifier.scoreThreshold": 0.7,
  "jiraClassifier.elapsedTimeThresholdHours": 12
}

[!WARNING] Nunca guardes tu API Token de Jira en el archivo settings.json. La extensión utiliza context.secrets para guardarlo de manera encriptada a través del sistema operativo. Puedes cambiar el token en cualquier momento con el comando jiraClassifier.updateJiraToken.

🔄 Flujo de procesamiento (Ciclo de soporte)

Cuando se inicia el servicio o se refresca de forma manual, la extensión orquesta el siguiente flujo:

sequenceDiagram
    actor Usuario
    participant Extension as Extensión VS Code
    participant SupportController as Controlador de Soporte
    participant PromptLoader as Cargador de Prompts
    participant FileSystem as Sistema de Archivos
    participant Jira as API de Jira
    participant Copilot as GitHub Copilot (vscode.lm)
    participant WorkspaceState as Caché Local
    participant Panel as Panel de Control

    Usuario->>Extension: Inicia o refresca soporte
    Extension->>SupportController: runCycle()
    SupportController->>PromptLoader: Cargar prompts Markdown
    PromptLoader-->>SupportController: Diagnósticos disponibles (.md)
    SupportController->>FileSystem: Leer documentación opcional
    FileSystem-->>SupportController: Contexto técnico/negocio
    SupportController->>Jira: Buscar tickets activos con JQL
    Jira-->>SupportController: Listado de tickets

    loop Por cada ticket
        SupportController->>WorkspaceState: Consultar resultado previo
        alt Resultado en caché
            WorkspaceState-->>SupportController: Reutilizar TicketResult (Evita spam)
        else Ticket pendiente de procesar
            alt Ticket cerrado o resuelto
                SupportController->>SupportController: Marcar como CLOSED
            else Ticket sin título ni descripción
                SupportController->>FileSystem: Registrar ticket en unclassified-tickets/
                SupportController->>Jira: Publicar comentario de ticket vacío
            else Ticket analizable
                SupportController->>Copilot: Evaluar relevancia de cada prompt en paralelo
                Copilot-->>SupportController: Scores individuales (0-100)
                alt Mejor score >= scoreThreshold * 100
                    SupportController->>Copilot: Analizar ticket usando el prompt del diagnóstico
                    Copilot-->>SupportController: Clasificación y campos faltantes
                else Coincidencia por debajo del umbral
                    SupportController->>Copilot: Realizar análisis genérico (fallback)
                    Copilot-->>SupportController: Análisis general
                    SupportController->>FileSystem: Registrar ticket en unclassified-tickets/
                end
                SupportController->>Jira: Publicar comentario con el resultado
            </div>
            SupportController->>WorkspaceState: Guardar TicketResult y marca de comentario
        end
    end

    SupportController->>Panel: Actualizar resultados
    Panel-->>Usuario: Mostrar estado, análisis e interactividad de los tickets

Decisiones detalladas del ciclo

• Tickets en estado final: Los tickets cuyo estado en Jira es Closed o Resuelto se marcan automáticamente como CLOSED y se omiten del análisis profundo para no alterar flujos de tickets ya gestionados.
• Tickets vacíos: Si el resumen y la descripción están en blanco, se concluye con estado EMPTY, se genera un comentario genérico solicitando contexto mínimo y se almacena en el registro local.
• Diagnósticos Markdown y Scoring: Se realiza mediante Promise.all para evaluar todos los diagnósticos de forma simultánea. El de mayor puntuación es el seleccionado, siempre que supere el límite configurado (scoreThreshold * 100).
• Análisis Genérico (Fallback): Si no hay archivos diagnósticos cargados o si la puntuación máxima obtenida no alcanza el umbral de aceptación, se ejecuta un prompt genérico para clasificar e identificar campos incompletos. Este resultado concluye como UNCLASSIFIED y guarda el ticket en unclassified-tickets/ del workspace para que los administradores identifiquen qué diagnósticos técnicos hace falta diseñar e incorporar en el catálogo.

📝 Formato de los diagnósticos Markdown

El motor de clasificación de la extensión lee archivos Markdown (.md) desde el directorio configurado en promptsDirectory. Cada archivo representa una categoría de falla y debe contener un encabezado YAML frontmatter con los metadatos y un cuerpo con los criterios técnicos:

---
id: database-connection-error
label: Error de Conexión a Base de Datos
classification: DATABASE_ERROR
---

## Objetivo de clasificación
Identificar fallas donde el servicio no logra comunicarse con la base de datos (PostgreSQL, Oracle, Redis, etc.).

## Señales Fuertes (Relevancia alta)
- Mensajes como: "Connection refused", "FATAL: password authentication failed", "Connection timeout".
- Códigos HTTP: 500 o 503 provenientes de servicios de base de datos.

## No clasificar como este error cuando
- La base de datos responde pero hay una violación de integridad de datos (ej. duplicidad de registros).
- El error es una falla de red general externa a la base de datos.

## Datos mínimos requeridos
- Nombre del servicio o microservicio afectado.
- Nombre o URL del host de la base de datos.
- Timestamp exacto del error.

[!TIP] Consulta la carpeta de Ejemplos de Diagnósticos para ver guías preconfiguradas sobre fallas de login, timeout de APIs y caídas de base de datos.

También puedes leer las instrucciones detalladas en doc/documentation/README.md y utilizar la Plantilla de Contexto del Proyecto para inyectar información de tu arquitectura.

📂 Estructura del proyecto

jira-ticket-support-vscode/
├── doc/
│   └── documentation/
│       ├── README.md                  # Guía para la documentación de proyectos de soporte
│       └── project-support-template.md # Plantilla para inyectar contexto de negocio/API
├── examples/
│   ├── README.md                      # Guía detallada de prompts diagnósticos
│   ├── database-connection-error.md   # Ejemplo de diagnóstico de base de datos
│   └── login-authentication-failure.md # Ejemplo de diagnóstico de autenticación
├── src/
│   ├── config/                        # ConfigManager: Lectura y validación de settings.json
│   ├── core/                          # Lógica central (ClassifierEngine, CommentBuilder, PromptLoader)
│   ├── services/                      # Servicios externos (Jira, Copilot via vscode.lm, SecretManager)
│   ├── support/                       # SupportController: Orquestación del ciclo de polling
│   ├── ui/                            # TicketPanel: Webview interactivo de tickets
│   ├── extension.ts                   # Punto de activación de la extensión y comandos
│   └── types.ts                       # Interfaces y tipos compartidos de TypeScript
├── package.json                       # Configuración y menú de comandos de la extensión
└── tsconfig.json                      # Configuración de compilación de TypeScript

⌨️ Comandos disponibles

Accede a estos comandos desde la paleta de comandos de VS Code (Cmd+Shift+P / Ctrl+Shift+P):

🧪 Desarrollo y pruebas

Si deseas modificar o extender el comportamiento del bot, utiliza los siguientes comandos npm:

# Compilar el código TypeScript a JavaScript
npm run compile

# Compilar continuamente al detectar cambios en los archivos (modo desarrollo)
npm run watch

# Ejecutar el linter para verificar buenas prácticas en TypeScript
npm run lint

# Compilar y ejecutar las pruebas automatizadas de la extensión
npm test

Empaquetado de producción

Para generar un archivo .vsix instalable localmente en cualquier VS Code sin necesidad de compilar desde fuentes:

npx vsce package

Esto creará un archivo jira-support-llm-X.Y.Z.vsix que puedes instalar mediante Instalar desde VSIX... en la sección de extensiones de tu VS Code.