@jamx-framework/compiler

Descripción

Compilador de JAMXScript para JAMX Framework. Transforma archivos .jamx y .ts en aplicaciones tipadas y optimizadas, proporcionando un sistema de plugins extensible que maneja desde la recolección de archivos hasta la generación de tipos para entornos, rutas y guardias de plataforma. El compilador está diseñado para ser usado tanto en modo desarrollo como en pipelines de CI/CD, ofreciendo diagnósticos claros y una arquitectura modular basada en plugins.

Cómo funciona

El compilador opera en una serie de pasos (pipeline) que procesan un proyecto JAMX de forma secuencial:

1. Verificación de estructura: Comprueba que el proyecto tiene la configuración mínima requerida (jamx.config.ts).
2. ENV Types: Analiza jamx.env.ts y genera un archivo TypeScript con tipos seguros para las variables de entorno.
3. Platform Guard: Detecta imports no permitidos que violarían la arquitectura de plataforma (por ejemplo, importar APIs específicas de plataforma desde código universal).
4. Route Types: Genera tipos para las rutas definidas en el proyecto, incluyendo inferencia de parámetros de ruta.
5. Compilación: (Opcional) Transforma el código según la configuración del proyecto.

El pipeline es extensible: los desarrolladores pueden crear plugins personalizados que se ejecuten en etapas específicas, como la generación de documentación o la minificación de assets.

Componentes principales

• src/core/pipeline.ts: Orquestador central que ejecuta los plugins en orden y acumula diagnósticos.
• src/core/file-collector.ts: Recolecta todos los archivos TypeScript del proyecto que deben ser analizados, excluyendo directorios como node_modules y dist.
• src/plugins/env-types/generator.ts: Genera tipos TypeScript para variables de entorno a partir de jamx.env.ts.
• src/plugins/platform-guard/detector.ts: Detecta imports que violan las reglas de plataforma usando el parser de SWC.
• src/plugins/route-types/generator.ts: Genera tipos para rutas definidas en el proyecto, incluyendo inferencia de parámetros.
• src/errors/JamxError.ts y src/errors/messages.ts: Definen la jerarquía de errores del compilador y fábricas de mensajes de error con códigos únicos y sugerencias.
• src/types/common.ts: (Nota: este archivo fue renombrado a types.ts en versiones recientes; contiene definiciones compartidas como SourceLocation y DiagnosticBag).

Uso básico

# Compilar un proyecto JAMX
jamx build

# Compilar en modo incremental (solo analiza archivos cambiados)
jamx build --mode incremental --changed-files src/modules/users/users.service.ts

# Ejecutar solo la generación de tipos de entorno sin compilar
jamx compile:env-types --dry-run

# Verificar que el proyecto tiene la estructura mínima
jamx check

Ejemplo de jamx.config.ts

import { defineConfig } from '@jamx-framework/core';

export default defineConfig({
  // Configuración básica del proyecto
  name: 'MiAplicacion',
  version: '1.0.0',
  // Otros ajustes opcionales...
});

Ejemplo de jamx.env.ts

import { defineEnv } from '@jamx-framework/env';

export const Env = defineEnv({
  PORT: { type: 'number', default: 3000 },
  DATABASE_URL: { 
    type: 'string', 
    required: true, 
    format: 'url' 
  },
  NODE_ENV: { 
    type: 'enum', 
    values: ['development', 'production', 'test'], 
    default: 'development' 
  }
});

Ejemplos

Generación de tipos de entorno

jamx compile:env-types --projectRoot ./src

Detectar violaciones de Platform Guard

jamx detect:platform-guard --projectRoot ./src

Generar tipos de rutas

jamx compile:route-types --projectRoot ./src --dry-run

Ejemplo de salida de diagnóstico

{
  "success": false,
  "errors": [
    {
      "code": "PG_UNIVERSAL_IMPORTS_PLATFORM",
      "message": "Universal module cannot import from platform-specific scope.\n  '@jamx-framework/web' is only available in Platform Shell modules.",
      "location": { "file": "src/modules/users/users.service.ts", "line": 5, "column": 1 },
      "suggestion": "Only import platform APIs through '@jamx-framework/platform', which is resolved at compile time for each target.",
      "docs": "https://jamx.dev/docs/architecture/platform-guards"
    }
  ],
  "warnings": [],
  "plugins": {
    "envTypes": { "ran": false, "durationMs": 0, "errorCount": 0, "warningCount": 0 },
    "platformGuard": { "ran": false, "durationMs": 0, "errorCount": 0, "warningCount": 0 },
    "routeTypes": { "ran": false, "durationMs": 0, "errorCount": 0, "warningCount": 0 }
  },
  "generatedFiles": [],
  "durationMs": 124,
  "plugins": { ... }
}

Flujo interno

1. Inicialización: El pipeline crea una instancia de CompilerPipeline que configura los plugins.
2. Verificación de estructura: Se comprueba la existencia de jamx.config.ts; si falta, se lanza CFG_MISSING_CONFIG.
3. ENV Types: El plugin EnvTypesPlugin lee jamx.env.ts, valida el esquema y genera src/.jamx/generated/env.d.ts.
4. Platform Guard: El plugin PlatformGuardPlugin analiza todos los archivos TypeScript para detectar imports prohibidos usando SWC.
5. Route Types: El plugin RouteTypesGenerator recopila rutas desde el router de JAMX y genera src/.jamx/generated/routes.d.ts.
6. Diagnóstico: Todos los diagnósticos se acumulan en un DiagnosticBag. Si hay errores críticos, se lanza CompilationFailedError.
7. Resultado: Se devuelve un CompileResult con información sobre éxito, duración, errores, warnings y archivos generados.

Este diseño modular permite a los desarrolladores extender el compilador con plugins personalizados sin modificar el núcleo, facilitando integraciones con herramientas de CI/CD, generación de documentación y otros procesos de build.

Plugin Development

Para crear un plugin personalizado:

1. Implementa una clase con los métodos run() y opcionalmente generate() según la etapa deseada.
2. Registra el plugin en el CompilerPipeline mediante pipeline.registerPlugin('my-plugin', myPlugin).
3. Asegúrate de que el plugin devuelva un objeto con al menos { diagnostics: DiagnosticBag }.
4. (Opcional) Genera archivos de salida usando fs.writeFile en el directorio de salida especificado.

Ejemplo de plugin mínimo:

import type { Plugin } from '@jamx-framework/compiler';

export class MyCustomPlugin implements Plugin {
  async run(options: any) {
    // Lógica personalizada...
    return { 
      generatedFile: '/ruta/generada.js',
      diagnostics: new DiagnosticBag() 
    };
  }
}

Testing

El proyecto incluye tests unitarios en packages/compiler/tests/unit/. Para ejecutarlos:

pnpm test
# o
npm run test

Los tests cubren:

• Verificación de estructura del proyecto
• Manejo de variables de entorno requeridas
• Detección de violaciones de Platform Guard
• Compilación exitosa de proyectos válidos
• Modo incremental y filtrado de archivos
• Duración de plugins en el resumen

Performance Considerations

• El compilador usa swc para parsing en lugar de TypeScript completo, lo que mejora significativamente la velocidad de análisis.
• Las operaciones de I/O están optimizadas con fs.promises y path para evitar cuellos de botella.
• En modo incremental, solo se analizan los archivos modificados, reduciendo el tiempo de build en proyectos grandes.

Compatibility

• Compatible con Node.js 18+ y TypeScript 5.x.
• Funciona en sistemas operativos Windows, macOS y Linux.
• No requiere dependencias globales; todas las herramientas se instalan como devDependencies del proyecto.

This compiler is the backbone of the JAMX Framework, enabling developers to build type-safe, modular applications with a single command while maintaining a clear separation of concerns through its plugin architecture.