npm package: @jamx-framework/compiler
Description: JAMX Framework â€” JAMXScript Compiler
Author: Stiven-21
Latest version: 1.1.0

# @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
```bash
# 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`
```typescript
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`
```typescript
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
```bash
jamx compile:env-types --projectRoot ./src
```

### Detectar violaciones de Platform Guard
```bash
jamx detect:platform-guard --projectRoot ./src
```

### Generar tipos de rutas
```bash
jamx compile:route-types --projectRoot ./src --dry-run
```

### Ejemplo de salida de diagnóstico
```json
{
  "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:
```typescript
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:

```bash
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.