Introducción a Glastor ReadmeGen

Glastor ReadmeGen (@glastor-dev/readmegen) es una herramienta de ingeniería de software desarrollada en Deno y TypeScript diseñada para automatizar el análisis estático de repositorios y la generación de archivos README.md profesionales y listos para producción.

🎯 El Problema

Mantener la documentación y los archivos README.md actualizados en proyectos de código abierto o comerciales suele ser una tarea manual propensa a errores y desactualizaciones:

• Badges de CI/CD rotos o apuntando a ramas erróneas.
• Dependencias obsoletas que no coinciden con deno.json o import_map.json.
• Ejemplos de código desfasados respecto a la API real.
• Tablas de contenido (TOC) desincronizadas con los encabezados.

💡 La Solución: Glastor ReadmeGen

ReadmeGen resuelve este problema mediante introspección estática automatizada:

1. Inspección de configuración: Analiza deno.json, deno.lock e import_map.json para extraer versiones, scripts y dependencias.
2. Análisis de código fuente (AST): Utiliza parsers de TypeScript para extraer interfaces, funciones públicas, tipos y documentación JSDoc.
3. Detección de CI/CD y Calidad: Examina workflows de GitHub Actions (.github/workflows/), linters y tests configurados.
4. Motor de renderizado flexible: Inyecta la información en plantillas modulares (minimal, modern, detailed) o preserva plantillas de perfil personalizadas (README.profile.md).

🚀 Principales Características

📚 Estructura de esta Documentación

En las siguientes secciones encontrarás el detalle completo de cómo se construyó la herramienta y cómo utilizarla:

• Cómo se realizó: Visión general del proceso de desarrollo y diseño.
• Arquitectura del Sistema: Diagramas y desglose de capas y módulos.
• Análisis de Proyectos y AST: Cómo funciona la extracción de datos y el parseo de código.
• Motor de Plantillas: El sistema de inyección y limpieza de Markdown.
• Guía de Instalación: Requisitos y pasos para instalar el CLI.
• Uso del CLI: Comandos, argumentos y modos de uso.
• Configuración: Opciones avanzadas de .readmegen.json.
• Referencia de la API: Uso programático mediante generateReadme y analyzeProject.

Cómo se Realizó Glastor ReadmeGen

Esta sección documenta el proceso de ingeniería, decisiones técnicas y evolución detrás del desarrollo de Glastor ReadmeGen.

🏛️ Evolución del Proyecto

1. Fase Inicial (Rust):

   • El proyecto comenzó originalmente como una herramienta CLI compilada en Rust (crate glastor_dev) con utilidades de generación y análisis de estadísticas en GitHub.
   • Aunque Rust ofrecía un rendimiento extremo y binarios independientes, la integración directa con proyectos del ecosistema Deno requería soporte nativo para TypeScript sin pasos de compilación intermedios.

2. Migración a Deno & TypeScript (v2.0+):

   • Para alinearse con las mejores prácticas modernas de JavaScript/TypeScript, el proyecto fue rediseñado desde cero sobre el Runtime de Deno.
   • Beneficios obtenidos:
     • Ejecución nativa de TypeScript sin tooling complejo (Babel, Webpack).
     • Permisos granulares de seguridad (--allow-read, --allow-write).
     • Ecosistema estándar de pruebas (deno test), linters (deno lint) y formateo (deno fmt).
     • Facilidad para ejecutarse directamente en pipelines de GitHub Actions mediante deno run.

🛠️ Tecnologías y Librerías Utilizadas

El desarrollo de la herramienta se apoya en tecnologías seleccionadas por su robustez y rendimiento:

• Runtime: Deno (versión 1.40.0 o superior).
• CLI Framework: @cliffy/command para la construcción de una interfaz de línea de comandos tipada, con validación de opciones y subcomandos.
• Prompts Interactivos: @cliffy/prompt para el asistente interactivo readmegen init.
• Manipulación de Rutas y Archivos: Módulos oficiales de Deno Standard Library (@std/path, @std/fs).
• Análisis de Código (AST): Parsers integrados con expresiones regulares y análisis de tokens para extraer firmas JSDoc, funciones exportadas e interfaces sin requerir compiladores externos pesados.
• Documentación Estática: mdBook desplegado automáticamente mediante GitHub Actions en GitHub Pages.

⚙️ Flujo de Ejecución del Generador

El proceso de generación sigue una tubería (pipeline) lineal y determinista:

[Proyecto Deno]
       │
       ▼
 1. Carga de Configuración (.readmegen.json / CLI flags)
       │
       ▼
 2. Inspección Estática (Parsers)
    ├── deno.json (versión, scripts, metadatos)
    ├── import_map.json (mapeo de dependencias)
    ├── .github/workflows/ (workflows de CI/CD activos)
    └── src/ (análisis AST de símbolos y exportaciones)
       │
       ▼
 3. Enriquecimiento de Datos (Generators)
    ├── Generación de Badges (licencia, versión, build status)
    ├── Generación de Tabla de Contenidos (TOC)
    └── Generación de Documentación de API
       │
       ▼
 4. Renderizado de Plantilla (Template Engine)
    ├── Sustitución de variables {{key}}
    └── Inyección inteligente para evitar duplicaciones
       │
       ▼
 5. Sanitización y Normalización
    ├── Eliminación de líneas residuales
    └── Limpieza de BOM y caracteres invisibles
       │
       ▼
[README.md Generado]

Arquitectura del Sistema

La base de código de Glastor ReadmeGen está organizada modularmente bajo el directorio src/, separando claramente la capa de interfaz (CLI), análisis de proyecto, generadores de contenido y utilidades de bajo nivel.

📂 Organización del Proyecto

src/
├── main.ts               # Punto de entrada de la CLI (Cliffy)
├── mod.ts                # API programática principal (generateReadme)
│
├── project/              # Orquestador del análisis de proyecto
│   └── analyze.ts        # Recopila y coordina todos los parsers y generadores
│
├── parsers/              # Módulos de introspección estática
│   ├── deno_json.ts      # Lee y valida deno.json / deno.jsonc
│   ├── import_map.ts     # Lee import_map.json
│   ├── imports.ts        # Analiza importaciones externas y locales
│   ├── project_files.ts  # Detecta archivos clave (LICENSE, Dockerfile, etc.)
│   ├── source_code.ts    # Extractor de exportaciones y símbolos
│   ├── source_code_ast.ts# Analizador léxico y AST de TypeScript
│   ├── tests.ts          # Detecta frameworks y archivos de test
│   └── workflows.ts      # Lee y parsea GitHub Actions en .github/workflows/
│
├── generators/           # Generadores de secciones en Markdown
│   ├── api.ts            # Formatea la documentación de funciones y tipos
│   ├── badges.ts         # Construye URLs de badges (shields.io)
│   ├── examples.ts       # Genera snippets de código de ejemplo
│   └── toc.ts            # Construye la tabla de contenidos interactiva
│
├── templates/            # Motor y archivos de plantillas
│   ├── minimal.md        # Plantilla compacta
│   ├── modern.md         # Plantilla estándar moderna
│   ├── detailed.md       # Plantilla exhaustiva con todas las secciones
│   ├── load.ts           # Cargador de plantillas locales
│   └── render.ts         # Motor de renderizado y reemplazo {{placeholders}}
│
└── utils/                # Utilidades auxiliares
    ├── file_system.ts    # Verificaciones de escritura y permisos
    ├── init_wizard.ts    # Asistente interactivo por consola
    ├── logger.ts         # Mensajes con formato, colores y estados
    ├── readme_infer.ts   # Inferencia de descripciones desde READMEs existentes
    └── user_config.ts    # Carga y validación de .readmegen.json

🧩 Responsabilidad de los Componentes

1. Interfaz de Línea de Comandos (src/main.ts)

Construida con @cliffy/command, gestiona los parámetros del usuario:

• --template: Selecciona el estilo de plantilla a aplicar.
• --output: Define la ruta del archivo de destino.
• --force: Permite sobrescribir archivos protegidos.
• Subcomando init: Lanza el asistente guiado para crear .readmegen.json.

2. Coordinador de Análisis (src/project/analyze.ts)

Es el cerebro del análisis. Ejecuta en paralelo (Promise.all) la lectura de todos los aspectos del repositorio:

• Extrae la versión de Deno y scripts de tareas de deno.json.
• Detecta si existen suites de pruebas automáticas.
• Analiza los workflows de GitHub Actions para asociar las insignias de build correspondientes.
• Consolida todos los datos en una estructura unificada TemplateData.

3. Sistema de Sanitización (src/mod.ts)

Para evitar que código TypeScript de depuración o comentarios de desarrollo terminen en el archivo Markdown final, sanitizeGeneratedMarkdown aplica filtros mediante expresiones regulares que eliminan:

• Caracteres invisibles y Byte Order Marks (BOM: \uFEFF, \u200B).
• Líneas residuales de código fuente (export type, import ...).
• Espaciado redundante y saltos de línea consecutivos.

Análisis de Proyectos y AST

Uno de los aspectos técnicos más avanzados de Glastor ReadmeGen es su capacidad para inspeccionar estáticamente el código TypeScript sin necesidad de ejecutarlo, extrayendo metadatos precisos mediante análisis sintáctico.

🔍 Análisis AST (source_code_ast.ts)

El archivo src/parsers/source_code_ast.ts implementa un analizador que recorre el código fuente de los archivos .ts para descubrir símbolos públicos:

1. Extracción de Funciones Exportadas

El analizador detecta declaraciones de funciones públicas:

export function generateReadme(args: GenerateReadmeArgs): Promise<void>;

Extrayendo:

• Nombre de la función (generateReadme).
• Lista de parámetros tipados (args: GenerateReadmeArgs).
• Tipo de retorno (Promise<void>).
• Bloques JSDoc asociados (/** ... */).

2. Extracción de Tipos e Interfaces

Identifica estructuras de datos clave:

export interface GenerateReadmeArgs {
  template: TemplateName | string;
  output: string;
  force: boolean;
}

Generando tablas que documentan cada propiedad, su tipo y si es obligatoria u opcional.

📦 Análisis de Dependencias (imports.ts)

El analizador de importaciones examina las declaraciones de dependencias en todo el proyecto:

• Dependencias JSR (jsr:@std/path, jsr:@cliffy/command).
• Dependencias Deno.land (https://deno.land/std/...).
• Dependencias NPM (npm:chalk, npm:fast-glob).
• Importaciones locales relativas (./utils/...).

Esto permite generar automáticamente la sección de Dependencies en el README sin requerir que el desarrollador las enumere a mano.

🤖 Detección de CI/CD y Workflows (workflows.ts)

El parser inspecciona la carpeta .github/workflows/ en busca de archivos .yml o .yaml:

• Detecta si existe un flujo de pruebas o integración continua (ci.yml, test.yml).
• Vincula automáticamente el badge de estado correspondiente:

  ![Build Status](https://github.com/usuario/repo/actions/workflows/ci.yml/badge.svg?branch=master)
  

• Si se configuran ramas personalizadas en .readmegen.json, el parser adapta los parámetros del badge para apuntar a la rama objetivo.

Motor de Plantillas y Generación

El subsistema de plantillas (src/templates/) es el encargado de transformar los datos recopilados durante el análisis en un documento Markdown estructurado y estéticamente cuidado.

📑 Plantillas Disponibles

ReadmeGen incluye tres estilos de plantilla preconfigurados:

🔄 Variables de Plantilla (Placeholders)

Las plantillas utilizan una sintaxis de doble llave {{variable}} que es reemplazada dinámicamente por el motor de renderizado (render.ts):

• {{projectName}}: Nombre inferido del proyecto o directorio.
• {{badges}}: Cadena con todas las insignias SVG formateadas.
• {{description}}: Descripción del proyecto extraída de deno.json o inferida del contexto.
• {{toc}}: Tabla de contenidos interactiva con enlaces ancla.
• {{installation}}: Comando recomendado de instalación (deno install ...).
• {{usage}}: Comando de ejecución principal (deno task readme).
• {{basicExample}}: Bloque de código con ejemplo de uso de la librería.
• {{apiDocs}}: Tablas con la documentación detallada de la API.
• {{dependencies}}: Listado de dependencias detectadas.
• {{testCommand}}: Comando para ejecutar pruebas unitarias.
• {{contributing}}: Sección de pautas para contribuyentes.
• {{license}}: Información de la licencia detectada.

🧠 Inyección Inteligente

En ocasiones, un usuario puede utilizar una plantilla personalizada (como README.profile.md) que no incluye explícitamente los placeholders estándar ({{badges}}, {{apiDocs}}).

Para resolver esto, src/mod.ts implementa Inyección Inteligente:

1. Evitar Duplicados: Si el documento ya tiene insignias manuales, el motor analiza las URLs de las imágenes y solo agrega aquellas insignias que no existan previamente.
2. Posicionamiento Automático: Si no hay {{badges}}, inyecta los badges automáticamente justo debajo del primer encabezado # Titulo.
3. Secciones Desplegables: Si existen datos de API o dependencias pero no hay placeholder, los adjunta al final del documento dentro de etiquetas <details> de HTML para no alterar la estructura visual original.

Guía de Instalación

Glastor ReadmeGen está diseñado para ejecutarse sobre el runtime de Deno. Requiere Deno versión 1.40.0 o superior.

1. Requisitos Previos

Si aún no tienes Deno instalado en tu sistema:

En Windows (PowerShell)

irm https://deno.land/install.ps1 | iex

En macOS / Linux (Terminal)

curl -fsSL https://deno.land/install.sh | sh

Verifica la instalación:

deno --version

2. Instalación de ReadmeGen como CLI Global

Puedes compilar e instalar el comando readmegen directamente en tu PATH del sistema:

Desde el repositorio local

Clona el repositorio y ejecuta:

deno install -A -n readmegen ./src/main.ts

Una vez instalado, el comando estará disponible en cualquier terminal:

readmegen --version

3. Uso mediante Tareas de Deno (deno task)

Si estás trabajando directamente en el repositorio de Glastor, no necesitas instalar el CLI de forma global. Puedes utilizar las tareas predefinidas en deno.json:

# Generar el README estándar
deno task readme

# Forzar la sobrescritura del README
deno task readme:force

# Generar un README de prueba sin alterar el principal
deno task readme:check

4. Ejecución en Contenedores Docker

El proyecto incluye un Dockerfile optimizado con Deno preinstalado:

# Construir la imagen
docker build -t glastor-readmegen .

# Ejecutar el generador montando el directorio actual
docker run --rm -v "$(pwd):/app" glastor-readmegen

Guía de Uso del CLI

El CLI de Glastor ReadmeGen ofrece comandos intuitivos tanto para generar documentación de forma automática como para inicializar proyectos desde cero.

🛠️ Comando Principal

readmegen [opciones]

Opciones Disponibles

📋 Ejemplos de Uso

1. Generación Básica

Genera el archivo README.md utilizando la plantilla moderna:

readmegen

2. Seleccionar Plantilla Específica

Genera un README exhaustivo con toda la información de API y dependencias:

readmegen --template detailed

Para utilidades pequeñas donde solo se necesita lo esencial:

readmegen --template minimal

3. Generar en un Archivo Diferente

Para generar un borrador o previsualización sin alterar el README principal:

readmegen --output PREVIEW.md --force

🧙 Asistente de Configuración (readmegen init)

Si deseas personalizar el comportamiento del generador en tu proyecto, ejecuta el asistente guiado:

readmegen init

Este comando inicia una sesión interactiva en la terminal que te solicitará:

1. Nombre del proyecto: Nombre visible en los títulos.
2. Descripción breve: Resumen de una línea para el encabezado.
3. Repositorio de GitHub: En formato usuario/repo para generar enlaces y badges.
4. Estilo de insignias: flat, flat-square, plastic, etc.
5. Secciones opcionales: Activar o desactivar tablas de API, tests o dependencias.

Al finalizar, el asistente creará automáticamente el archivo .readmegen.json en la raíz de tu proyecto.

Configuración (.readmegen.json)

Glastor ReadmeGen permite una personalización exhaustiva a través del archivo de configuración opcional .readmegen.json en la raíz del proyecto.

📄 Estructura del Archivo

A continuación se muestra un ejemplo con todas las opciones disponibles:

{
  "projectName": "Mi Proyecto",
  "description": "Librería de alto rendimiento para procesamiento de datos en Deno.",
  "repo": "glastor-dev/readmegen",
  "defaultBranch": "master",
  "ciWorkflow": "ci.yml",
  "badgeStyle": "for-the-badge",
  "license": "GPL-3.0-only",
  "includeExamples": true,
  "strict": false,
  "exclude": [
    ".git",
    "node_modules",
    "dist",
    "build",
    "test"
  ],
  "sections": {
    "installation": true,
    "api": true,
    "contributing": true,
    "license": true,
    "dependencies": true
  },
  "api": {
    "include": ["src/mod.ts"],
    "exclude": ["src/utils/internal.ts"],
    "hideInternal": true
  },
  "sanitize": {
    "forceBannerFirst": true,
    "bannerLine": "![Banner](images/banner.webp)"
  }
}

⚙️ Descripción de Campos

Opciones Generales

Control de Secciones (sections)

Permite habilitar o deshabilitar bloques enteros de contenido generado:

• installation: Bloque con instrucciones de instalación.
• api: Tabla de referencia con funciones y tipos exportados.
• contributing: Pautas de contribución y requisitos de Pull Request.
• license: Información de licencia.
• dependencies: Listado de paquetes JSR, Deno y NPM importados.

Filtros de API (api)

Permite afinar la extracción del parser AST:

• include: Lista de archivos específicos a analizar para extraer símbolos.
• exclude: Archivos de código a omitir.
• hideInternal: Si es true, oculta funciones o tipos marcados con la etiqueta @internal de JSDoc.

Referencia de la API

Además de utilizarse como herramienta CLI, Glastor ReadmeGen puede integrarse como biblioteca en cualquier aplicación o script de Deno a través de src/mod.ts.

🚀 Importación

import { generateReadme, sanitizeGeneratedMarkdown } from "./src/mod.ts";

📘 Funciones Principales

generateReadme(args: GenerateReadmeArgs): Promise<void>

Orquesta el análisis completo del repositorio y escribe el archivo de salida formateado.

Parámetros (GenerateReadmeArgs)

Ejemplo de Uso

import { generateReadme } from "./src/mod.ts";

await generateReadme({
  template: "modern",
  output: "README.md",
  force: true,
});

console.log("¡README generado con éxito!");

sanitizeGeneratedMarkdown(markdown: string): string

Limpia y normaliza el texto Markdown generado para garantizar su presentación óptima.

• Elimina caracteres especiales de inicio de archivo (BOM, zero-width spaces).
• Filtra líneas residuales de código fuente que hayan podido escapar al parser.
• Normaliza los saltos de línea a formato Unix (LF).

Parámetros

Retorno

Devuelve el string sanitizado y listo para ser persistido en disco.

🔬 Análisis de Proyecto (src/project/analyze.ts)

analyzeProject(options: AnalyzeProjectOptions): Promise<ProjectAnalysis>

Función de bajo nivel que ejecuta los parsers e inspectores estáticos sobre una carpeta de proyecto.

import { analyzeProject } from "./src/project/analyze.ts";

const analysis = await analyzeProject({
  projectRoot: Deno.cwd(),
  readmePath: "./README.md",
});

console.log("Metadatos extraídos:", analysis.templateData);

Contribución y Desarrollo

Esta guía detalla el entorno de desarrollo y los comandos necesarios para contribuir al proyecto Glastor ReadmeGen.

💻 Configuración Local

1. Clona el repositorio:

   git clone https://github.com/glastor-dev/glastor-dev.git
   cd glastor-dev
   

2. Verifica que tienes Deno instalado:

   deno --version
   

🧪 Pruebas Unitarias

El proyecto utiliza el test runner integrado de Deno (deno test). Las pruebas se encuentran ubicadas en el directorio test/:

# Ejecutar todas las pruebas
deno task test

# O directamente
deno test -A

🎨 Formateo y Linter

El repositorio cuenta con reglas estrictas de calidad de código configuradas en deno.json:

# Formatear el código automáticamente
deno task fmt

# Verificar formato sin modificar archivos (para CI)
deno task fmt:check

# Ejecutar el analizador estático de Deno
deno task lint

# Comprobación de tipos de TypeScript
deno task check

⚡ Benchmarks

Para medir el rendimiento del motor de plantillas y la sanitización de Markdown:

deno task bench

Los benchmarks garantizan que la generación de documentación se complete en milisegundos, incluso en repositorios con cientos de archivos fuente.

📖 Compilación de esta Documentación

La documentación está construida con mdBook. Para previsualizarla localmente:

cd book
mdbook serve --open

Cada cambio en la rama master desencadena automáticamente el flujo de GitHub Actions (.github/workflows/mdbook.yml), compilando y desplegando esta web en GitHub Pages.