En esta entrada del blog, lo haremos:

• Demostrar la búsqueda y el cotejo de anotaciones
• Anotaciones de amén mediante plantillas de bigote

Sensei ofrece la posibilidad de comparar patrones de código problemáticos y luego modificarlos según las implementaciones acordadas. En este ejemplo, estoy utilizando @Disabled sin parámetro como patrón de código problemático.

Anotación de prueba desactivada

Desactivar las pruebas sin una razón específica puede resultar problemático a largo plazo porque olvidamos por qué las desactivamos.

@Disabled
   void thisTestMethodHasNoDisabledReason(){
    Assertions.fail("This test is disabled and should not run");
    }

El riesgo es que, con el tiempo, la base de código avanza, la prueba deshabilitada no se actualiza al ritmo del propósito del código y eventualmente se vuelve redundante e irrelevante, y potencialmente nunca se vuelve a habilitar.

Durante las revisiones de código, a menudo señalamos que es una buena idea añadir una descripción explicativa como parámetro de anotación.

@Disabled ("Disabled to demonstrate adding a reason")
    void thisTestMethodHasDisabledReason(){
   Assertions.fail("This test is disabled and should not run");
   }

Una receta de Sensei

Podemos escribir una receta para detectar cuando se añade @Disabled sin explicación y un Quick Fix que nos recuerde que debemos añadir la razón real que explique por qué lo hemos desactivado.

Cuando pienso en lo que voy a hacer, tengo que hacerlo:

• coinciden con la anotación Disabled sin ningún parámetro
• cambiar la anotación Disabled para tener un parámetro con el texto del marcador "TODO: añadir una descripción aquí"

Crear una receta de advertencia

Uso Alt+Enter para crear una nueva receta.

A continuación, añada el texto descriptivo básico en la información general.

Al convertir la regla en una advertencia, cualquier código que coincida se resalta pero no se muestra como un error flagrante.

Encontrar la anotación

En el editor de recetas, cambio la Búsqueda para que coincida con una anotación.

Esto resaltará todas las anotaciones en la vista previa.

Una vez hecho esto, quiero filtrar por el tipo de anotación.

Podría usar simplemente Disabled pero califico completamente la clase con el paquete para que sólo coincida con la anotación de JUnit 5. Como el código fuente se muestra en la vista previa, puedo copiar y pegar esto fácilmente desde el código real para evitar cualquier error tipográfico.

A continuación, quiero hacer coincidir sólo las anotaciones sin Parámetros, y puedo utilizar la GUI para hacerlo.

es decir, la búsqueda:

search:
  annotation:
    type: "org.junit.jupiter.api.Disabled"
    without:
       parameters:
          - {}

Crear una acción de reescritura rápida

Para mi QuickFix utilizaré una acción de reescritura.

Utilizo la funcionalidad de Mostrar Variables para mostrarme las variables de Mustache y previsualizar el contenido.

Y luego añado el código extra necesario para crear el comentario del marcador de posición.

es decir, QuickFix:

availableFixes:
 - name: "Add a todo comment parameter"
   actions:
   - rewrite:
      to: "{{{ . }}}(\"TODO: add a description here\")"
      target: "self"

Sensei en acción

Hemos creado un breve vídeo que muestra el proceso de creación de recetas en acción.

Resumen

Cuando se construye un Quick Fix de reescritura, es más fácil cuando podemos buscar el elemento de código que queremos reescribir, porque entonces es la entidad propia sobre la que podemos actuar.

En este ejemplo, he utilizado una acción de reescritura para modificar la anotación. La reescritura es una acción de propósito general que puede aplicarse a cualquier elemento de código y es una buena opción por defecto para explorar.

El plugin Sensei proporciona una manera fácil de encontrar patrones de código específicos en su código fuente, y luego aplicar reglas de reescritura para modificar el código coincidente. Todo dentro del IDE de Intellij, y en tiempo real.

‍

‍

Por ejemplo, puede crear una regla que coincida con las anotaciones de JUnit `@Disabled` que no tengan una razón, Sensei le informará del problema resaltando el código en el IDE.

Además, cuando usted `alt+enter`, puede tener la opción de `Añadir un parámetro de comentario de todo`.

Cuando se selecciona, esto modificaría el código para añadir una razón de tipo boilerplate, que luego puedes modificar, y si no lo haces, aparecerá en tu panel de tareas pendientes.

Por ejemplo, `@Disabled` se convertiría en ` @Disabled("TODO: añadir una descripción aquí")`.

Sensei combina la funcionalidad de un escáner de código de análisis estático con un motor de reescritura de código.

Acciones de IntelliJ Intention

Basado en la descripción anterior, la alternativa obvia (si no estaba usando Sensei) es usar la funcionalidad de IntelliJ Intention Actions.

Sensei se diferencia de IntelliJ Intention Actions porque el objetivo de Sensei es proporcionar una forma de crear matchers y rewriters que sean específicos para el proyecto, o incluso locales para un desarrollador individual.

Hemos intentado crear una interfaz gráfica de usuario que facilite la escritura y la experimentación de las reglas de concordancia y de reescritura.

¿Cómo puede ayudarme a mejorar personalmente?

Cuando aprendo una nueva biblioteca, me lleva tiempo crear una memoria muscular en torno a los métodos y el formato. Así que puedo optar por crear recetas personales que

• enlazar con la documentación oficial o las páginas de tutoriales
• tienen plantillas de caldera que son más eficaces
• corregir las malas prácticas de codificación
• añadir código de caldera para ayudar a utilizar una biblioteca

Puedo utilizar Sensei para construir recetas temporales que me impulsen a las prácticas actuales que he elegido utilizar y me ayuden a crear hábitos eficaces. Y las recetas son temporales porque puedo eliminarlas cuando las supere.

¿Cómo puede ayudar a mi equipo a mejorar?

Del mismo modo, podemos ayudar a los equipos a crear memoria muscular en torno a las normas de codificación acordadas.

Crear libros de recetas que aplicamos cuando encontramos los mismos comentarios en las revisiones de pull requests. Como los libros de recetas se almacenan en el control de versiones con el proyecto, están disponibles para todos en el proyecto. Y podemos desactivarlos cuando ya no necesitemos las indicaciones.

Sensei ayuda a dar una respuesta temprana

Lo que hemos intentado construir con Sensei es una forma de obtener la información que nos ayuda a mejorar, y recordatorios de acciones correctivas, tan pronto como podamos en el proceso de codificación.

En lugar de esperar a que

• los resultados de un analizador estático
• los comentarios de una revisión del código

En cambio, podemos ver la retroalimentación, para las normas personalizadas que queremos hacer cumplir, mientras codificamos.

Y tenemos recordatorios, o reglas de reescritura reales, para ayudarnos a escribir código que cumpla con las normas.

Sensei es flexible

En ese sentido, Sensei es un poco una mezcla, ya que es:

• parte Analizador estático
• tutor de codificación
• motor de reescritura

Sensei es lo suficientemente flexible como para que el trabajo de decir "¿Qué es Sensei?" sea un poco más difícil.

Sensei llena un vacío en el flujo de trabajo de programación

Hemos intentado que Sensei sea la pieza que faltaba en el flujo de trabajo del programador y que le ayude a mejorar elementos específicos de su estilo de codificación, o del uso de bibliotecas, con las que usted y su equipo están trabajando actualmente.

Esta flexibilidad significa que se necesita un poco más de tiempo para familiarizarse con Sensei que con una herramienta de análisis estático o con el IntelliJ Intentions incorporado. Aun así, dedicando el tiempo a experimentar, obtendrás una nueva forma de acelerar tu aprendizaje en tu proceso de desarrollo personal.

¿Cómo experimentar?

Una vez que haya descargado e instalado Sensei desde el[Intellij Marketplace]

La forma más fácil de hacer que Sensei trabaje para usted es observar su proceso de codificación y considerar:

• ¿Qué documentación sigues buscando?
  -- Podrías añadir algunas recetas de Sensei que enlacen a esa documentación.
• ¿Qué errores simples sigues cometiendo?
  -- Podrías codificar temporalmente ese mal patrón de codificación como un emparejador, y escribir una reescritura Quick Fix que modifique el código para que sea lo que realmente quieres escribir.
• ¿Qué código boilerplate escribes para utilizar una biblioteca?
  -- Podrías crear una regla Quick Fix para escribir el código por ti.

Dado que Sensei está diseñado para trabajar junto a cualquier herramienta de análisis estático que estés usando, si encuentras que las mismas violaciones están siendo reportadas desde el análisis estático, entonces podrías replicar la condición en una receta de Sensei . A continuación, puede añadir una solución rápida para ayudar a entrenar, no sólo para identificar el error, sino también para pasar rápidamente a escribir el código correcto

Ejecución de inspecciones de IntelliJ desde la integración continua

IntelliJ IDEA ofrece funcionalidad para ayudar a mejorar nuestra codificación, dentro del IDE al escribir código como Intenciones. Las Intenciones pueden ser usadas en lote para inspeccionar el código en busca de patrones a lo largo de la fuente e incluso extenderse al análisis de la Línea de Comandos o añadirse a la Integración Continua. Este post cubre la funcionalidad fuera de la caja de IntelliJ y la expansión con Intenciones personalizadas creadas en Sensei.

‍

Inspecciones de IntelliJ

La función de Inspecciones de IntelliJ impulsa la visualización de muchos de los errores que se informan dinámicamente en el IDE cuando se codifica, por ejemplo

• detectar las clases abstractas que pueden convertirse en interfaces,
• identificar los campos de clase redundantes que pueden ser locales,
• advertencia sobre el uso de métodos obsoletos,
• etc.

Estas inspecciones resaltan el código que coincide en el IDE como Acciones de Intención que a menudo tienen un QuickFix asociado.

El resaltado del IDE en tiempo real cuando el código coincide con una Inspección puede ayudarnos a mejorar nuestra codificación de forma dinámica. Después de identificar el problema en el código, el uso de IntelliJ Intention Actions para QuickFix el código puede reforzar mejores patrones.

Perfil de las inspecciones

Las inspecciones pueden ejecutarse por lotes desde el IDE, y desde la línea de comandos o en un proceso de integración continua.

La clave para trabajar con las inspecciones de IntelliJ como un lote es mediante el uso de un Perfil de Inspección.

IntelliJ tiene dos perfiles de inspección por defecto: uno almacenado en el proyecto, y otro almacenado en el IDE.

Se pueden crear nuevos perfiles de inspección para configurar plugins o casos de uso específicos, por ejemplo

• Ejecutar sólo el escaneo en tiempo real de Checkstyle
• Ejecutar un conjunto específico de reglas de Sensei
• Ejecutar las comprobaciones de HTML
  

Las inspecciones de un perfil pueden activarse o desactivarse desde las Preferencias de IntelliJ. El cuadro de diálogo de Preferencias es también una forma sencilla de conocer la gama de Inspecciones disponibles.

El icono de la "herramienta" le permite duplicar un perfil y crear un nuevo perfil para recoger un conjunto específico de reglas.

Ejecución de un perfil de inspección en el IDE

Los Perfiles de Inspección pueden ser ejecutados desde el IDE usando el menú `Analizar | Inspeccionar Código...`.

La función de análisis le permite controlar el ámbito en el que se ejecutará la inspección, por ejemplo, todo el proyecto, incluyendo o excluyendo los orígenes de las pruebas, o un conjunto específico de archivos. 

También puede gestionar los perfiles de inspección desde aquí para crear o configurar un perfil concreto.

Al hacer clic en [Aceptar] en el cuadro de diálogo "Especificar ámbito de inspección", IntelliJ ejecutará todas las inspecciones seleccionadas en el perfil en el ámbito definido.

IntelliJ informará de los resultados de la ejecución de las inspecciones en la pestaña `Resultados de la inspección`.

El plugin Sensei de Secure Code Warrior le permite crear recetas personalizadas de coincidencia de código. Sensei se integra estrechamente con IntelliJ para hacer que estas recetas personalizadas sean tan naturales de usar como las Acciones de Intención de IntelliJ. Esto significa que se cargan en IntelliJ como inspecciones y pueden agruparse, activarse y desactivarse utilizando perfiles de inspección. La creación de un perfil de inspección personalizado y el uso de la función de análisis del código de inspección es la forma recomendada de ejecutar las recetas de Sensei de forma masiva en un proyecto.

Ejecución de un perfil de inspección desde la línea de comandos

IntelliJ tiene la capacidad de ejecutar inspecciones desde la línea de comandos, tal y como documenta JetBrains:

- https://www.jetbrains.com/help/idea/working-with-the-ide-features-from-command-line.html

Yo uso principalmente macOS, y puedo ejecutar una sola instancia de IntelliJ desde la línea de comandos con:

open -na "IntelliJ IDEA CE.app"

Para facilitar la ejecución, añado esto a un script de comandos del shell.

vi /usr/local/bin/idea

El contenido del script proviene de la documentación oficial proporcionada por IntelliJ.

#!/bin/sh
open -na "IntelliJ IDEA CE.app" --args "$@"

Luego hice este ejecutable para permitirme simplificar el proceso de inspección de la línea de comandos.

chmod 755 /usr/local/bin/idea

La documentación oficial de intellij describe la forma general del comando de inspección como

idea inspect <project> <inspection-profile> <output></output></inspection-profile></project>
[<options>]</options>

En la práctica, califico completamente las rutas y no necesito ninguna opción:

idea inspect /Users/user/GitHub/sensei-blog-examples /Users/user/GitHub/sensei-blog-examples/.idea/inspectionProfiles/senseiprofile.xml /Users/user/GitHub/sensei-blog-examples/scan-results

Esto ejecuta todas las inspecciones que agregué al `senseiprofile` y reporta los resultados en la carpeta `scan-results`.

Visualización de los resultados de la inspección

Podemos informar de estos resultados desde la integración continua, como veremos más adelante.

También podemos verlos dentro del propio IntelliJ utilizando la función `Analyse \ View Offline Inspection Results...`.

Esto cargará los resultados en la pestaña "Resultados de la inspección".

Esto está oficialmente documentado en el sitio de JetBrains:

- https://www.jetbrains.com/help/idea/command-line-code-inspector.html#inspection-results

Esto podría utilizarse durante un proceso de revisión de código si la ejecución de la línea de comandos se incorporara a un proceso de Integración Continua y los revisores quisieran comprobar el contexto de origen completo de cualquiera de las entradas de resultados de la Inspección.

Perfiles de inspección en la integración continua

Al añadir la inspección de la línea de comandos en la integración continua, lo ideal es que queramos que se genere un informe de forma automática y hay varias opciones abiertas para nosotros.

TeamCity ofrece soporte inmediato para los perfiles de inspección en la integración continua.

- https://www.jetbrains.com/help/teamcity/inspections.html

El plugin Jenkins Warnings NG soporta la salida de línea de comandos de IntelliJ Inspections como uno de los formatos de informe.

- https://github.com/jenkinsci/warnings-ng-plugin

- https://github.com/jenkinsci/warnings-ng-plugin/blob/master/SUPPORTED-FORMATS.md

Existen proyectos comunitarios como `idea CLI Inspector` para apoyar el uso de los Perfiles de Inspección en otras herramientas de CI, por ejemplo

- https://github.com/bentolor/idea-cli-inspector

El futuro de los Perfiles de Inspección en un proceso de CI parece aún más brillante con la introducción del proyecto JetBrains Qodana. El proyecto Qodana es una versión sin cabeza de IntelliJ con acciones oficiales de Github e imágenes Docker.

- https://github.com/JetBrains/Qodana

Qodana se encuentra actualmente en fase beta, pero el equipo de Sensei lo está supervisando para que se convierta en una plataforma soportada oficialmente para ejecutar las reglas de Sensei como parte de la Integración Continua.

Resumen

Las Acciones de Intención nos permiten reforzar los patrones de codificación y corregirlos rápidamente en el IDE cuando cometemos errores durante la codificación.

Los Perfiles de Inspección nos permiten reunirlos en perfiles que pueden ejecutarse por lotes como una acción de Análisis e Inspección de Código. Esto puede ser útil si encontramos un patrón y queremos volver a comprobar si lo hemos pasado por alto en alguna otra parte de nuestro código.

Los Perfiles de Inspección pueden ejecutarse desde la línea de comandos e incluso incorporarse a los procesos de Integración Continua apoyando un modelo de "confiar, pero verificar" y detectar cualquier desviación accidental.

Todo lo anterior está incorporado en la funcionalidad de IntelliJ y JetBrains está mejorando su proceso de Integración Continua con la introducción de Qodana.

Sensei recetas se cargan en IntelliJ para actuar como Acciones de Intención nativas y ser recogidas en Perfiles de Inspección para soportar la comprobación por lotes a través de Inspect Code y el soporte de Integración Continua proporcionado por la funcionalidad oficial de ejecución de Línea de Comandos de JetBrains.

---

Puede instalar Sensei desde IntelliJ usando "Preferences \ Plugins" (Mac) o "Settings \ Plugins" (Windows) y luego sólo busque "sensei secure code".

Si quieres probar a ejecutar un proyecto en IntelliJ desde la línea de comandos, el proyecto utilizado en este post se puede encontrar en el repositorio `sensei-blog-examples` en la cuenta de GitHub de Secure Code Warrior . Un ejercicio para el lector es crear un perfil que ejecute sólo las reglas de Sensei . Pruébalo:

https://github.com/securecodewarrior/sensei-blog-examples

Más información sobre Sensei