Entendiendo la estructura y los datos de tu proyecto con Xray Audit

 Luz en el camino

El principal escollo  de los proyectos complejos es calibrar su grado de complejidad. No disponer de los recursos para realizar una auditoría previa, puede llevar a la toma de decisiones a ciegas. De hecho, disponer de información exacta y actualizada incrementa la eficiencia tanto en la gestión como en el desarrollo. Así, esto permite:

• Cuantificar objetivamente la complejidad del proyecto y planificar adecuadamente su ejecución, estableciendo los recursos necesarios y la estrategia más adecuada. 
• Tomar decisiones informadas durante el desarrollo. Por ejemplo, en una migración en la que se han identificado 20 paragraphs distintos, podemos saber si algunos de ellos apenas se están utilizando y son susceptibles de excluirse de la migración.
• Evaluar el avance de un proyecto y detectar a tiempo si está adquiriendo una complejidad excesiva. 
• Detectar posibles mejoras.
• Además, facilita el onboarding a nuevos desarrolladores.

Hasta ahora están claras las ventajas de las auditorías, pero en Metadrop nos encontramos con algunas dificultades para su ejecución:

• La necesidad de perfiles técnicos para realizar la auditoría.
• La inversión de tiempo que estos perfiles necesitan. 
• La poca mantenibilidad y crecimiento del proceso. Resulta complicado incorporar nuevos informes a las auditorías semimanuales.
• En resumen, la imposibilidad de auditar de un modo ágil.
  
   

El módulo Xray Audit nace con la finalidad de superar estas limitaciones.

Auditar al alcance de unos clicks

El módulo Xray Audit supera los inconvenientes de las auditorías semimanuales: permite generar informes de forma instantánea y por cualquier perfil, ya sean desarrolladores, gestores de proyectos o administradores.

Con el fin de facilitar la evolución del módulo y simplificar el proceso de implementación de nuevos informes, hemos desarrollado el módulo sobre el sistema de plugins de Drupal. De este modo, el desarrollador o desarrolladora puede centrarse en el código que genera el informe y no en su integración con el módulo.

Por el momento, mientras ampliamos el módulo, veamos cuales son los diferentes tipos de informes que ofrece Xray Audit actualmente.

Informes sobre entidades de contenido

Desde Drupal 8, el sistema de Entidades es central. De hecho, la comunidad a menudo compara la construcción de sitios a través de configuración como jugar con un LEGO, en el que construimos un tipo de entidad (nodo), que puede tener diferentes bundles (página, artículo), a los que podemos agregar campos y configurar diferentes formas en las que mostrar la entidad (displays).

Para qué pueden ser útiles:

• Calibrar la complejidad del proyecto e identificar los riesgos.
• Conocer el número de componentes que se han de refactorizar.
• Identificar tipos de contenido infrautilizados o duplicados, susceptibles de eliminarse.
• Detectar entidades custom que pueden no ser evidentes a primera vista.

Tipos de entidades de contenido

Este informe muestra un listado de todas las entidades de contenido existentes, incluyendo las que pertenecen a módulos contrib y módulos custom.

Entidades de contenidos: tipos y número 

Dan información sobre el número de entidades existentes en la base de datos agrupadas por idioma. Por ejemplo, el número de nodos tipo artículo que se han creado hasta ahora.

Informes disponibles

• Número de elementos agrupados por tipo y por tipo e idioma:
  • Nodos
  • Paragraphs
  • Taxonomías
• Número de medias agrupados por tipo
• Usuarios y roles:
  • Número de usuarios
  • Roles
  • Permisos adjudicados a cada rol
  • Actividad de los usuarios: número de usuarios que han accedido en los últimos 3 meses, de los 3 a 6 meses y de más allá de los 6 meses.

Informes sobre Displays 

Para qué pueden ser útiles:

• Establecer estrategias para incrementar el rendimiento.
• Identificación y categorización de componentes en trabajos de refactorización.
• Conocer relaciones entre entidades de contenido.
• Determinar el uso de los formateadores de campos y los estilos de imagen.

Displays

Estos tipos de informe generan información sobre la configuración de los displays de las entidades de contenido: los campos que se muestran y el formateador que se aplica a cada campo.

En esta imagen vemos los distintos displays configurados para un tipo de nodo denominado recipe (hemos generado estos informes en un Drupal con el perfil Umami instalado).

• En la primera columna (fields), se enumeran todos los campos de recipe que existen a nivel de base datos, y en las columnas siguientes, los campos configurados para cada display, así como los campos computados. Estos últimos son campos que no existen como tal en la base de datos, sino que se calculan al vuelo, por ejemplo, el campo links.
• Media image es un campo de tipo referencia de entidad, asociado a entidades media de tipo image. En el display card podemos ver que está configurado para que se muestre aplicándose el display responsive_3x2.
• Podemos consultar en el informe de las entidades media para saber cómo se muestra la entidad. Por otro lado, en el display teaser, que suele mostrar los datos básicos de un contenido, no se muestra este campo.

Informe sobre módulos Drupal

Esta sección contiene un informe sobre los módulos de Drupal instalados, proyectos  a los que pertenecen y si están siendo usados, es decir, habilitados.

Esto último se hace atendiendo a los archivos de configuración exportados, y no exclusivamente a si están habilitados en el entorno y el sitio en que estamos ejecutando el Xray Audit.

Esto es especialmente interesante en los proyectos complejos que utilicen Configuration Split como herramienta para gestión de los diferentes contextos de configuración. Por ejemplo, un multisite en la que hay un config split por tipo de sitio (profile), así como por entorno y por sitio.

El informe nos permite saber los módulos que se habilitan globalmente (por el archivo core.extension) o los que son habilitados por un config split determinado. Por ejemplo, en la imagen podemos ver como el módulo Xray Audit se habilita exclusivamente en el entorno local y no globalmente.

¿Para qué puede ser útil?

• Identificar los módulos instalados susceptibles de ser eliminados porque no se habiliten en ningún contexto. La columna “Project” nos pone sobre aviso de aquellos módulos que son submódulos de otros módulos.
• Detectar incongruencias en la configuración de los config splits.
• Por supuesto, saber qué módulos se están utilizando de un vistazo.

Cómo extenderlo  

El desarrollo del módulo se ha basado en el sistema de plugins de Drupal para facilitar la integración de nuevos informes. Los desarrolladores pueden encontrar en el README las instrucciones de cómo hacerlo.

XrayAuditTaskPlugin  es el plugin principal que va a integrar el código que genera el informe con el Xray Audit.

/** 
 * 
 * @XrayAuditTaskPlugin ( 
 *   id = "queries_data_media", 
 *   label = @Translation("Data about medias"), 
 *   description = @Translation("Queries execute on database to get reports about medias."), 
 *   group = "queries_data", 
 *   sort = 3, 
 *   operations = { 
 *  	"media_types" = { 
 *      	"label" = "Media types", 
 *      	"description" = "Media types.", 
 *      	"dependencies" = {"media"} 
 *   	}, 
 *	}, 
 *   dependencies = {"media"} 
 * ) 
 */ 

Parámetros: 

• id: identificador único.
• label: nombre.
• description: una pequeña descripción sobre los reportes generados por este plugin.
• group: el tipo de informe al que pertenece.
• sort: posición que ocupa en la página donde se muestra el listado de informes disponibles.
• operations: cada operación genera un informe determinado, por lo tanto, un mismo plugin puede generar uno o varios informes. Los parámetros son:
  • index: identificador único de la operación. Este elemento se utiliza para construir la URL del informe.
  • label: nombre de la operación.
  • description: breve descripción sobre el informe.
  • dependencies: una lista de módulos de los que depende el informe. Por ejemplo, si el informe va a extraer datos sobre la entidad paragraph, el módulo Paragraphs debe estar habilitado. Si la dependencia no se cumple, esta operación simplemente no se muestra al usuario.
• dependencies: también es posible definir dependencias a nivel del XrayAuditTaskPlugin y no solo de operaciones.

   

Por último, habrá que sobreescribir como mínimo estos dos métodos:

• getDataOperationResult: se encarga de ejecutar el código que devuelve los datos que servirán para generar el informe. Estos datos se deben devolver en un array.
• buildDataRenderArray: recibe los datos generados por el método anterior y devuelve un render array de Drupal. 

Conclusión

Disponer de una radiografía del proyecto en el que se está trabajando es fundamental durante la planificación y desarrollo del mismo. Pero para que sea realmente eficiente, es necesario que dicha radiografía se pueda realizar en cualquier punto del proyecto, por perfiles no técnicos, que no suponga una inversión de tiempo adicional y que dicha información se muestre de manera centralizada. Con el módulo Xray Audit, cubrimos estas necesidades. 

Por el momento, el módulo cuenta con los  informes de los que hemos hablado en este artículo. En un futuro no muy lejano, queremos implementar las siguientes funcionalidades: 

• Posibilidad de ver una vista previa de los displays de las distintas entidades.
• Listado de bloques (block_content)
• Listado y uso de Crops y estilos de imagen.
• Listado de vistas activas, displays y lugares en las que se utilizan.
• Listado de módulos activos empleados para la construcción de las páginas y navegabilidad del sitio, por ejemplo, Paragraphs, Layout Builder, Page Manager. El objetivo sería identificar de  manera rápida qué estrategia o estrategias de site building se está aplicando.
• Estatus del core.
• Listado de Webforms activos e inactivos y lugares en los que se muestran.
  
   

Son bienvenidas vuestras sugerencias, propuestas y contribuciones ;)