TS status

monorepo-ts.md

Informe Técnico – Estado del Monorepo

1. Resumen Ejecutivo

El monorepo cuenta con 67 paquetes, de los cuales 25 ya están parcialmente migrados a TypeScript. La calidad del código es moderada en términos generales, aunque se detectaron inconsistencias significativas en tipado, configuración duplicada de tsconfig y falta de estandarización en dependencias. Se identificaron riesgos de deuda técnica que deben atenderse en el corto plazo, especialmente el uso excesivo de any y la presencia de console.log en código de producción.

2. Estructura del Monorepo

Número de paquetes: 67 paquetes organizados en packages/*

Gestor de monorepo: Lerna + Yarn Workspaces

• Lerna para gestión de versionado independiente
• Yarn Workspaces para gestión de dependencias
• Configuración de nohoist para paquetes específicos

Dependencias compartidas identificadas:

• @navent-re/global-styles (usado en 32 paquetes)
• @navent-re/utilities (usado en 8 paquetes)
• @navent-re/button (usado en 6 paquetes)
• @navent-re/input (usado en 5 paquetes)
• @navent-re/modal (usado en 4 paquetes)

Organización de carpetas: Estructura estándar con src/, lib/, types/ y archivos de configuración por paquete.

✅ Checklist:

• ✅ Configuración centralizada de scripts (package.json raíz)
• ✅ Configuración consistente de linters (ESLint + Prettier centralizados)
• ✅ Paquetes bien aislados sin dependencias cíclicas detectadas
• ⚠️ Dependencias compartidas bien identificadas pero con versiones inconsistentes

3. Estado de la Migración a TypeScript

Archivos totales JS/TS:

• JavaScript: ~512 archivos (.js/.jsx)
• TypeScript: ~236 archivos (.ts/.tsx)

Porcentaje migrado: 31.6% (236/748 archivos)

Paquetes con TS habilitado: 25 paquetes con tsconfig.pkg.json

Configuraciones de tsconfig: Unificadas desde la raíz, extendidas por paquete

Problemas detectados:

• Uso excesivo de any en 15+ archivos TypeScript
• Falta de tipado en librerías internas
• Mezcla de PropTypes y TypeScript en el mismo proyecto
• Tipos inconsistentes entre paquetes

✅ Checklist:

• ✅ Tipos estrictos (strict: true en tsconfig raíz)
• ❌ Eliminación progresiva de any (requiere atención inmediata)
• ✅ Configuración clara de paths/aliases (@navent-re/*)
• ⚠️ Configuración por paquete implementada pero inconsistente

4. Calidad del Código

ESLint: Configuración centralizada con reglas estrictas

• ✅ Reglas de indentación (tabs), linebreak (unix), quotes (single)
• ❌ Regla no-console: error pero se encontraron 50+ console.log en código
• ⚠️ Reglas de camelcase y no-duplicate-imports en modo warning

Prettier: Configuración centralizada con .prettierignore y .prettierrc

Testing:

• Framework: Jest + React Testing Library
• Cobertura: Configurada al 100% pero solo 5 paquetes tienen tests
• Estructura: __test__/ folders con archivos .test.js/.tsx

Deuda técnica identificada:

• Código duplicado en filtros (filters vs newFilters)
• Estilos de imports inconsistentes (mezcla de ES6 y CommonJS)
• Dependencias obsoletas (styled-components: "latest")
• Uso de PropTypes en lugar de TypeScript

⚠️ Riesgos frecuentes:

• Código duplicado entre paquetes de filtros
• Estilos de imports inconsistentes
• Dependencias obsoletas (especialmente styled-components)
• Console.log en producción (viola reglas de ESLint)

5. Diagnóstico de Riesgos y Problemas

Riesgo	Impacto	Severidad	Sugerencia
Uso excesivo de any	Bugs en runtime, pérdida de beneficios TS	Alta	Migrar a tipos explícitos
Dependencias desactualizadas	Fallos de seguridad, incompatibilidades	Media	Actualizar con npm-check-updates
Falta de tipado en librerías internas	Dificulta integración, debugging	Alta	Definir tipos compartidos
Console.log en producción	Logs innecesarios, posibles filtraciones	Media	Implementar logger estructurado
Mezcla PropTypes/TypeScript	Inconsistencia, mantenimiento	Media	Migrar completamente a TS
Versiones inconsistentes de dependencias	Conflictos, builds fallidas	Media	Unificar versiones

Dependencias duplicadas: Sí detectadas (especialmente global-styles con versiones 0.11.x y 0.12.x)

Problemas de build o CI/CD: No detectados críticos, pero configuración de Jest requiere atención

Compatibilidad JS/TS: Funcional pero con inconsistencias en tipado

Mantenibilidad a largo plazo: Moderada - requiere refactorización para mejorar

6. Recomendaciones y Plan de Acción

Corto plazo (1-2 sprints):

1. Centralizar tsconfig en la raíz:

   • Unificar configuraciones de TypeScript
   • Implementar reglas estrictas consistentes
   • Eliminar configuraciones duplicadas

2. Definir reglas estrictas de ESLint + TypeScript:

   • Activar @typescript-eslint/no-explicit-any
   • Implementar @typescript-eslint/strict
   • Configurar @typescript-eslint/prefer-ts-expect-error

3. Identificar y eliminar dependencias duplicadas:

   • Unificar versiones de @navent-re/global-styles
   • Implementar yarn dedupe
   • Revisar nohoist configuration

4. Eliminar console.log de producción:

   • Implementar logger estructurado
   • Configurar ESLint para bloquear commits con console.log
   • Revisar archivos de stories y componentes

Mediano plazo (2-3 meses):

1. Migrar los paquetes core a TS al 100%:

   • Priorizar paquetes más utilizados (global-styles, utilities, button)
   • Implementar tipos compartidos en @types package
   • Eliminar PropTypes progresivamente

2. Incorporar changesets para versionado:

   • Reemplazar Lerna por Changesets
   • Implementar versionado semántico automático
   • Mejorar changelog y release notes

3. Mejorar cobertura de tests:

   • Implementar tests en paquetes críticos
   • Configurar coverage thresholds por paquete
   • Implementar tests de integración entre paquetes

4. Refactorizar paquetes duplicados:

   • Consolidar filters y newFilters
   • Crear abstracciones compartidas
   • Eliminar código duplicado

Largo plazo (6-12 meses):

1. Completar migración a TS:

   • 100% de archivos en TypeScript
   • Eliminación completa de PropTypes
   • Tipos estrictos en todos los paquetes

2. Documentar arquitectura del monorepo:

   • Diagramas de dependencias
   • Guías de contribución
   • Decisiones de arquitectura (ADRs)

3. Automatizar validaciones en CI/CD:

   • Type checking automático
   • Linting y formatting automático
   • Tests automáticos en PRs

4. Implementar herramientas avanzadas:

   • ts-prune para detectar tipos no utilizados
   • depcheck para dependencias no utilizadas
   • nx o turborepo para builds más eficientes
   • storybook-addon-a11y para accesibilidad

7. Conclusión

El proyecto está en una etapa intermedia de migración a TypeScript, con avances visibles pero también desafíos importantes que requieren atención inmediata. La infraestructura del monorepo es sólida con Lerna y Yarn Workspaces, pero la calidad del código y consistencia necesitan mejora.

Principales fortalezas:

• Arquitectura de monorepo bien estructurada
• Configuración centralizada de herramientas
• Migración a TypeScript en progreso
• Sistema de testing configurado

Principales desafíos:

• Uso excesivo de any en TypeScript
• Inconsistencias en versiones de dependencias
• Mezcla de PropTypes y TypeScript
• Código duplicado entre paquetes

Si se sigue el plan propuesto, en un horizonte de 6 a 12 meses el monorepo podrá consolidarse como una base tecnológica más robusta, mantenible y escalable, con TypeScript completamente implementado, mejor cobertura de tests y procesos de CI/CD automatizados.

Recomendación prioritaria: Comenzar inmediatamente con la eliminación de any y la unificación de dependencias, ya que estos cambios tendrán el mayor impacto en la calidad y mantenibilidad del código.