nebula-ui-kitESTADO: Aprobado
FECHA: 2026-10-14
AUTOR: Carlos Alberto Torres Camargo (arquitecto)
ALCANCE: la librería de componentes nebula-ui-kit: su código, su pipeline de publicación, su Storybook y las solicitudes de cambio de los equipos que la consumen
RELACIONADOS: Publicación de Nebula UI Kit por Jenkins, Changelog de Nebula UI Kit, Librería Pipeline Compartida, Definition of Done, ADR-014 (pruebas E2E del frontend)
IMPLEMENTACIÓN DE REFERENCIA: nebula-ui-kit 2.17.0, publicada el 14-oct-2026 desde el build #38 de main (1.428 pruebas en verde, Quality Gate OK con bloqueo activo)
nebula-ui-kit es la librería sobre la que se construyen todas las pantallas del ERP: el motor de formularios, las tablas, los diálogos y el perfil visual 3.0. El ERP la declara con caret (^2.x), de modo que cada versión publicada llega a todas las pantallas en la siguiente instalación.
Una versión publicada en Nexus es inmutable: npm no deja repisarla, y retirarla rompe a quien ya la instaló. Un defecto que se publica solo se corrige con la versión siguiente.
Hasta la 2.16.0 el pipeline analizaba el kit con SonarQube, pero el resultado solo avisaba: la publicación seguía aunque el gate saliera en ERROR. Además, el análisis se registraba siempre con la versión de la raíz del workspace (0.9.9), que nunca cambia, así que el «código nuevo» del gate se acumulaba desde la primera versión y no se medía versión por versión. Estado medido sobre la 2.16.0 (14-oct-2026):
| Medida | Valor |
|---|---|
| Cobertura de líneas | 87,9 % |
| Cobertura de ramas | 81,3 % |
| Bugs | 9 (8 de accesibilidad) |
| Duplicación | 5,4 % |
| Componente con menor cobertura | lib-table-input: 66,4 % de líneas, con dos defectos sin detectar (initialSort y pageSize no se aplicaban; Escape revertía la fila equivocada con la tabla ordenada) |
Tampoco estaba escrito quién puede modificar la librería, quién aprueba un cambio, cómo pide un ajuste quien desarrolla pantallas, ni dónde se ve la evolución versión por versión.
El pipeline de la librería (npmLibraryPipeline de centrica-pipeline-shared) corre con sonarBlocking: true. Si el Quality Gate no pasa, el build falla y no se publica nada, ni la prerelease de develop ni la estable de main.
El gate es «Centrica» y se evalúa sobre el código nuevo de cada versión:
| Condición | Falla si |
|---|---|
| Cobertura del código nuevo | menor al 50 % |
| Líneas duplicadas en el código nuevo | mayor al 3 % |
| Hotspots de seguridad revisados | menor al 100 % |
| Violaciones nuevas | mayor a 0 |
El análisis se envía con -Dsonar.projectVersion igual a la versión del package.json de la librería (projects/nebula-ui-kit/package.json), no la de la raíz del workspace. El periodo de código nuevo es PREVIOUS_VERSION: cada versión se mide contra la anterior.
| Etapa | Si falla |
|---|---|
| Instalación | Detiene |
| Lint | Avisa y continúa |
| Pruebas unitarias (con cobertura) | Detiene |
| Compilación | Detiene |
| SonarQube (Quality Gate) | Detiene (desde la 2.17.0) |
| Publicación | Detiene |
Una regla de Sonar solo se excluye en sonar-project.properties del repositorio, por regla y por carpeta, con el motivo escrito. Nunca se excluye un archivo completo de todas las reglas, ni se relaja el gate desde la interfaz de Sonar.
Exclusión vigente:
| Regla | Carpeta | Motivo |
|---|---|---|
typescript:S1874 (uso de API deprecada) |
**/components/table-input/** |
El componente deprecado lib-table-input usa sus propios tipos, también deprecados. Fuera de esa carpeta la regla sigue activa: quien use lib-table-input desde otro sitio recibe el aviso. |
@deprecated sin forRemoval es un cambio menor (X.Y+1.0). El componente sigue funcionando igual y la nota indica con qué reemplazarlo.forRemoval, solo ocurre en una versión mayor (X+1.0.0).El preflight local no basta: el agente de Jenkins es más lento que una estación de trabajo. El 14-oct-2026 la 2.17.0 pasó todas las pruebas en local y el build #37 de main se cayó porque una prueba con 10.000 filas tardó 5,8 s contra el límite de 5 s. Una prueba de volumen declara su propio límite de tiempo en el describe que la contiene.
| Rol | Quién | Qué hace |
|---|---|---|
| Dueño y aprobador | Carlos Alberto Torres Camargo, arquitecto | Aprueba todo cambio antes de que entre a develop. Es el único que confirma la publicación de la versión estable en Jenkins (botón «Publicar»). Decide lo que el manual de diseño no resuelve. |
| Mantenedor del kit | Arquitectura de componentes, designada por el dueño | Revisa la solicitud, verifica que el cambio sea aditivo y que no rompa firmas, decide la versión, escribe o revisa el código y sus pruebas, corre el preflight de Sonar, integra a develop y a main y avisa a los consumidores. |
| Consumidores | Desarrolladores de pantallas del ERP | Usan la versión publicada. No modifican el código del kit. Piden ajustes por el canal de la sección 4.3. |
Ningún cambio entra al kit sin dos aprobaciones, en este orden:
La orden puede venir directamente del dueño; aun así, la propuesta pasa primero por el mantenedor y después se construye. Integrar a main y publicar requieren la orden expresa del dueño en cada publicación.
Quien desarrolla una pantalla y necesita algo del kit:
La solicitud dice:
| Dato | Ejemplo |
|---|---|
| Pantalla y HT | Elaboración Apropiación Inicial, HT_PRE_008 |
| Componente del kit | lib-table-compact |
| Qué hace hoy | Pinta las 8.594 filas sin paginar ni buscar |
| Qué se espera | Paginación y buscador sin cambiar la firma actual |
| Evidencia | Captura, ticket de Mantis o diseño aprobado |
Mientras el ajuste no esté publicado, la pantalla no copia ni parchea el componente: espera la versión o lo resuelve con lo que el kit ya ofrece.
html.ui-3-0; ningún perfil cambia a otro.| Qué | Dónde | Cómo se actualiza |
|---|---|---|
| Storybook del kit | http://10.120.0.2:8552/storybook/ | Solo. Un sincronizador en nodo-01 pregunta a Nexus cada 10 minutos cuál es la versión latest; si cambió, compila el Storybook del commit publicado y lo reemplaza. El 14-oct-2026 la 2.17.0 quedó en el Storybook unos 12 minutos después de publicarse. |
| Manual de Diseño 3.0 | http://10.120.0.2:8552/ | Se sincroniza con el repositorio del manual. |
| Lo deprecado | Deprecado: qué no usar | Se regenera al deprecar algo. |
| Calidad | SonarQube, proyecto nebula-ui-kit |
Cada build de develop y main. |
| Evolución versión por versión | Changelog de Nebula UI Kit | Se agrega una entrada con cada versión publicada. |
| Alternativa | Por qué no |
|---|---|
| Dejar Sonar como aviso | Es lo que había: la 2.16.0 se publicó con el gate en ERROR y nadie lo vio. Un aviso que no detiene nada no protege una versión inmutable. |
Excluir lib-table-input completo del análisis |
Dejaría de medir su cobertura y sus defectos justo cuando se le subió del 66 % al 98 %. Se excluyó solo la regla S1874 y solo en su carpeta. |
| Que cada equipo modifique el kit | Fue la causa de cambios que se revirtieron por no estar autorizados (5-oct-2026). Con una librería compartida, un cambio local rompe pantallas ajenas. |
| Changelog solo en los commits | Los commits existen, pero mezclan pruebas, ajustes de formato y cambios funcionales, y no dicen qué versión se publicó ni cuándo. |
Positivas
Costos
ERROR obliga a corregir antes de publicar.| Versión | Fecha | Autor | Descripción |
|---|---|---|---|
| 1.0.0 | 2026-10-14 | Carlos Torres | Versión inicial. Gate de Sonar bloqueante desde la 2.17.0, versión de la librería en cada análisis, exclusiones acotadas, regla de deprecación, roles y doble aprobación, canal de solicitudes, Storybook sincronizado con Nexus y changelog de versiones. |