Plugin PSA para IntelliJ: autocompletado personalizado

PSA: Autocompletado y navegación personalizados en IntelliJ con contexto PSI

El plugin PSA permite a los desarrolladores implementar autocompletado, navegación y plantillas de código específicas del proyecto directamente dentro de IntelliJ IDEA. Un script escrito en cualquier lenguaje analiza el árbol PSI actual y devuelve sugerencias. Esto resuelve el desafío de soportar marcos personalizados sin necesidad de instalar plugins separados.

Cómo funciona el contexto PSI

El plugin se activa cuando especificas la ruta a un script ejecutable en la configuración. Cuando se dispara el autocompletado (Ctrl+Space) o la navegación (GoTo), se genera un contexto PSA —un árbol PSI simplificado del elemento enfocado. Este se codifica en JSON y se guarda en un archivo temporal (debido a los límites de argumentos por línea de comandos) y se pasa al script mediante la variable de entorno PSA_CONTEXT.

Ejemplo para PHP:

<?php

function myFunc() {
    $l = '';
//        ^   cursor aquí
}

El JSON generado incluye una estructura jerárquica de elementos:

{
  "elementType": "comilla simple derecha",
  "elementName": null,
  "elementFqn": null,
  "text": "'",
  "parent": {
    "elementType": "String",
    "text": "''",
    // ... estructura anidada hasta el nivel de archivo
  }
}

Cada nodo PSI incluye elementType, elementName, elementFqn, text, textRange (startOffset/endOffset), parent/prev/next, y opciones.

Variables de entorno para el script

El script recibe:

• PSA_CONTEXT: Ruta al archivo JSON que contiene el árbol PSI.
• PSA_TYPE: Puede ser Completion o GoTo.
• PSA_LANGUAGE: El lenguaje de programación (PHP, JS, etc.).
• PSA_DEBUG: Establecido en 1 cuando el modo depuración está activo.
• PSA_OFFSET: Posición del cursor dentro del elemento.

El script analiza el árbol, evalúa el contexto (elemento + padres) y determina las sugerencias. Para Completion, devuelve un array de opciones; para GoTo, uno con un campo link.

Formato de respuesta del script

Respuesta JSON:

{
  "completions": [
    {
      "text": "texto de inserción",
      "link": "FileName.php:42:5", // solo para GoTo
      "bold": true,
      "priority": 10
    }
  ],
  "notifications": ["mensaje de depuración"],
  "gotoElementTypes": ["FUNCTION", "CLASS"] // filtro de rendimiento
}

priority ordena los resultados; bold destaca entradas. gotoElementTypes limita el alcance de GoTo para mejorar el rendimiento.

Documentación y Swagger

El plugin genera una interfaz Swagger UI a partir de sus modelos API para mayor claridad. Los métodos son 'falsos' pero describen la estructura de llamadas. Usa OpenAPI Generator para crear clases DTO para tu script.

Estructura de elementos PSI:

• elementType: Tipo (STRING, FUNCTION).
• elementName/Fqn: Nombre o FQCN.
• options: Diccionario de parámetros.
• text: Texto fuente original.
• textRange: Desplazamientos.
• Relaciones: parent/prev/next.

Configuración y rendimiento

Habilita el plugin y apúntalo a tu script. Activa PSA_DEBUG para solucionar errores. Usa filtros gotoElementTypes para reducir la sobrecarga de GoTo.

Ventajas frente a plugins específicos de framework:

• Dependencia a nivel de proyecto, no global.
• Soporta APIs y plantillas personalizadas.
• Soporte para scripts independientes del lenguaje.

Ejemplo de script (pseudocódigo):

#!/bin/bash
context=$(cat $PSA_CONTEXT | jq .)
if [[ $PSA_TYPE == "Completion" ]]; then
  # lógica de análisis
  echo '{"completions": [{"text": "customFunc()"}]}'
fi

Puntos clave

• PSA pasa todo el árbol PSI para un análisis contextual preciso.
• Los scripts devuelven completados con priority y bold para priorización personalizada.
• GoTo soporta enlaces file:line:pos y filtrado por elementType.
• La documentación Swagger acelera el desarrollo de DTOs.
• Funciona con cualquier lenguaje de proyecto (PHP, JS/TS, etc.).

— Editorial Team