docviz-builder 0.1.0

package/scripts/generate-catalog-doc.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Genera `examples/catalogo.md` a partir del catalogo de tipos.
+ *
+ * El documento sirve para dos cosas a la vez: es la referencia visual de todo
+ * lo que DocViz sabe dibujar, y es la prueba manual mas completa que existe,
+ * porque compilarlo obliga a que cada tipo del catalogo se renderice de verdad.
+ *
+ * Se genera en lugar de escribirse a mano para que no pueda quedar desfasado:
+ * anadir un tipo al catalogo lo anade aqui.
+ */
+
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { TYPE_CATALOG } from '../dist/dsl/catalog.js';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const target = path.join(root, 'examples', 'catalogo.md');
+
+const TITULOS = {
+  diagram: 'Diagramas',
+  chart: 'Graficos',
+  architecture: 'Arquitectura',
+};
+
+const INTROS = {
+  diagram:
+    'Se declaran en un bloque `diagram`. El campo `type` expresa la intencion; ' +
+    'el motor lo elige DocViz.',
+  chart:
+    'Se declaran en un bloque `chart`. Todos se dibujan con Vega-Lite y el ' +
+    'resultado es un SVG estatico, sin JavaScript.',
+  architecture:
+    'Se declaran en un bloque `architecture`. Se dibujan con LikeC4, y si no ' +
+    'estuviera disponible, con C4-PlantUML.',
+};
+
+const lines = [
+  '---',
+  'title: Catalogo de visualizaciones',
+  '---',
+  '',
+  '# Catalogo de visualizaciones',
+  '',
+  'Todos los tipos que DocViz sabe dibujar, cada uno con el bloque que lo',
+  'produce y el resultado ya compilado.',
+  '',
+  'Este documento **no se escribe a mano**: lo genera `npm run catalog` a partir',
+  'del catalogo de tipos, de modo que no puede quedar desfasado respecto a lo que',
+  'el compilador admite de verdad.',
+  '',
+];
+
+const resumen = ['| Tipo | Para que sirve | Motor |', '|---|---|---|'];
+for (const spec of TYPE_CATALOG) {
+  resumen.push(`| \`${spec.type}\` | ${spec.purpose} | ${spec.engine} |`);
+}
+lines.push(...resumen, '');
+
+for (const lang of ['diagram', 'chart', 'architecture']) {
+  const specs = TYPE_CATALOG.filter((s) => s.lang === lang);
+  if (specs.length === 0) continue;
+
+  lines.push('---', '', `## ${TITULOS[lang]}`, '', INTROS[lang], '');
+
+  for (const spec of specs) {
+    lines.push(`### \`${spec.type}\``, '');
+    lines.push(spec.purpose, '');
+    lines.push(`**Cuando usarlo.** ${spec.whenToUse}`, '');
+    lines.push(`**Cuando no.** ${spec.whenNotToUse}`, '');
+
+    const detalles = [];
+    if (spec.aliases !== undefined && spec.aliases.length > 0) {
+      detalles.push(`Alias: ${spec.aliases.map((a) => `\`${a}\``).join(', ')}.`);
+    }
+    if (spec.fallbacks !== undefined && spec.fallbacks.length > 0) {
+      detalles.push(`Si falta ${spec.engine}, se dibuja con ${spec.fallbacks.join(' o ')}.`);
+    }
+    if (detalles.length > 0) lines.push(detalles.join(' '), '');
+
+    // El bloque fuente se muestra dentro de una valla de cuatro tildes para que
+    // el propio compilador no lo tome por una visualizacion que debe dibujar.
+    lines.push('````md', `\`\`\`${spec.lang}`, spec.example, '```', '````', '');
+
+    // Y este es el bloque real, el que si se compila.
+    lines.push(`\`\`\`${spec.lang} title="${spec.type}"`, spec.example, '```', '');
+  }
+}
+
+lines.push(
+  '---',
+  '',
+  '## Como se elige',
+  '',
+  'Si dudas entre varios tipos, describe en una frase que quieres explicar y',
+  'consulta la herramienta MCP `docviz_suggest`, o ejecuta `docviz types` para',
+  'ver el catalogo con su proposito y su ejemplo.',
+  '',
+  'Y antes de dibujar, comprueba que el diagrama aporta algo: para informacion',
+  'sencilla, una tabla o un parrafo comunican mejor.',
+  '',
+);
+
+await writeFile(target, lines.join('\n'), 'utf8');
+process.stdout.write(`escrito ${path.relative(root, target)} con ${TYPE_CATALOG.length} tipos\n`);

package/scripts/rasterize.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Rasteriza los SVG generados a PNG para revisarlos visualmente.
+ *
+ * Se usa en la validacion manual y para producir las evidencias de
+ * `artifacts/test-results/screenshots/`. No forma parte del pipeline de build.
+ *
+ *   node scripts/rasterize.mjs <dirConSvg> <dirDestino> [--scale 2]
+ */
+
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import puppeteer from 'puppeteer-core';
+import { findBrowser, browserNotFoundHelp } from '../dist/renderers/browser.js';
+
+const [, , sourceDir, targetDir, ...rest] = process.argv;
+if (sourceDir === undefined || targetDir === undefined) {
+  process.stderr.write('uso: node scripts/rasterize.mjs <dirConSvg> <dirDestino> [--scale N]\n');
+  process.exit(2);
+}
+const scaleIndex = rest.indexOf('--scale');
+const scale = scaleIndex >= 0 ? Number(rest[scaleIndex + 1]) : 2;
+// `--scheme dark` emula un visor en modo oscuro para comprobar la variante dual.
+const schemeIndex = rest.indexOf('--scheme');
+const scheme = schemeIndex >= 0 ? rest[schemeIndex + 1] : 'light';
+
+const executablePath = findBrowser();
+if (executablePath === undefined) {
+  process.stderr.write(`${browserNotFoundHelp()}\n`);
+  process.exit(1);
+}
+
+const files = (await readdir(sourceDir)).filter((f) => f.endsWith('.svg')).sort();
+if (files.length === 0) {
+  process.stderr.write(`no hay SVG en ${sourceDir}\n`);
+  process.exit(1);
+}
+
+await mkdir(targetDir, { recursive: true });
+const browser = await puppeteer.launch({ executablePath, headless: true, args: ['--no-sandbox'] });
+
+for (const file of files) {
+  const svg = await readFile(path.join(sourceDir, file), 'utf8');
+  const page = await browser.newPage();
+  // El orden de los atributos varia entre motores: se leen por nombre.
+  const openTag = /<svg\b[^>]*>/.exec(svg)?.[0] ?? '';
+  const width = Number(/\bwidth="(\d+(?:\.\d+)?)"/.exec(openTag)?.[1] ?? 900);
+  const height = Number(/\bheight="(\d+(?:\.\d+)?)"/.exec(openTag)?.[1] ?? 700);
+
+  await page.emulateMediaFeatures([{ name: 'prefers-color-scheme', value: scheme }]);
+  await page.setViewport({ width: Math.min(width, 2400), height: Math.min(height, 2400), deviceScaleFactor: scale });
+  // El SVG se carga como imagen, igual que en un visor Markdown: es la unica
+  // forma de comprobar que su variante oscura se activa de verdad.
+  const dataUri = `data:image/svg+xml;base64,${Buffer.from(svg, 'utf8').toString('base64')}`;
+  await page.setContent(
+    `<!doctype html><html><body style="margin:0;background:${scheme === 'dark' ? '#0b0d10' : '#ffffff'}">` +
+      `<img src="${dataUri}" width="${width}" height="${height}"></body></html>`,
+    { waitUntil: 'load' },
+  );
+  const png = await page.screenshot({ type: 'png', fullPage: true });
+  const target = path.join(targetDir, file.replace(/\.svg$/, '.png'));
+  await writeFile(target, png);
+  await page.close();
+  process.stdout.write(`${file} -> ${path.relative(process.cwd(), target)} (${width}x${height})\n`);
+}
+
+await browser.close();

package/scripts/sync-docs.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Sincroniza con el catalogo todo lo que la documentacion afirma sobre los
+ * tipos disponibles.
+ *
+ * El catalogo es la fuente de verdad, pero README, AGENTS y la documentacion
+ * del proyecto repiten sus tablas para que se puedan leer sin ejecutar nada.
+ * Copiar a mano garantiza que un dia diverjan, asi que las regiones marcadas se
+ * generan desde el codigo.
+ *
+ *   node scripts/sync-docs.mjs           regenera
+ *   node scripts/sync-docs.mjs --check   falla si algo quedo desfasado
+ *
+ * El modo `--check` es lo que convierte la promesa en garantia: forma parte de
+ * `docs:check` y de las pruebas, asi que un tipo nuevo no puede publicarse con
+ * la documentacion vieja.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { TYPE_CATALOG } from '../dist/dsl/catalog.js';
+import { themeNames } from '../dist/themes/index.js';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const check = process.argv.includes('--check');
+
+// --------------------------------------------------------------------------
+// Fragmentos generados
+// --------------------------------------------------------------------------
+
+const LANGS = [
+  ['diagram', 'Diagramas — bloque `diagram`'],
+  ['chart', 'Gráficos — bloque `chart`'],
+  ['architecture', 'Arquitectura — bloque `architecture`'],
+];
+
+/** Tabla "necesidad -> tipo -> motor" de una valla. */
+function tablaPorValla(lang) {
+  const filas = TYPE_CATALOG.filter((s) => s.lang === lang).map((s) => {
+    const respaldo = s.fallbacks !== undefined && s.fallbacks.length > 0 ? ` (o ${s.fallbacks.join(' / ')})` : '';
+    return `| ${s.purpose.replace(/\.$/, '')} | \`${s.type}\` | ${s.engine}${respaldo} |`;
+  });
+  return ['| Necesidad | `type` | Motor |', '|---|---|---|', ...filas].join('\n');
+}
+
+/** Las tres tablas, con su encabezado. */
+function tablasCompletas(nivel) {
+  const h = '#'.repeat(nivel);
+  return LANGS.map(([lang, titulo]) => `${h} ${titulo}\n\n${tablaPorValla(lang)}`).join('\n\n');
+}
+
+/** Recuento por motor, para el resumen del README. */
+function resumenPorMotor() {
+  const porMotor = new Map();
+  for (const spec of TYPE_CATALOG) {
+    porMotor.set(spec.engine, (porMotor.get(spec.engine) ?? 0) + 1);
+  }
+  const filas = [...porMotor.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([motor, n]) => `| ${motor} | ${n} |`);
+  return ['| Motor | Tipos |', '|---|---|', ...filas].join('\n');
+}
+
+/** Diagrama que explica el reparto de intenciones entre motores. */
+function diagramaDeReparto() {
+  const porMotor = new Map();
+  for (const spec of TYPE_CATALOG) {
+    const lista = porMotor.get(spec.engine) ?? [];
+    lista.push(spec.type);
+    porMotor.set(spec.engine, lista);
+  }
+  const lineas = ['type: flow', 'title: Del tipo declarado al motor', 'direction: lr', '', 'flow:'];
+  for (const [motor, tipos] of [...porMotor.entries()].sort((a, b) => b[1].length - a[1].length)) {
+    // Tres ejemplos bastan para que se entienda el reparto; la lista completa
+    // esta en la tabla, y un diagrama con 57 nodos no explicaria nada.
+    const muestra = tipos.slice(0, 3).join(', ');
+    const resto = tipos.length > 3 ? ` y ${tipos.length - 3} mas` : '';
+    lineas.push(`  - DSL -> ${motor}: ${muestra}${resto}`);
+  }
+  return ['```diagram', ...lineas, '```'].join('\n');
+}
+
+const FRAGMENTOS = {
+  'tipos-tablas-3': () => tablasCompletas(3),
+  'tipos-tablas-4': () => tablasCompletas(4),
+  'tipos-resumen': () => resumenPorMotor(),
+  'tipos-reparto': () => diagramaDeReparto(),
+  'tipos-total': () => String(TYPE_CATALOG.length),
+  'temas': () => themeNames().map((t) => `\`${t}\``).join(', '),
+};
+
+// --------------------------------------------------------------------------
+// Sustitucion entre marcas
+// --------------------------------------------------------------------------
+
+/**
+ * Reemplaza el contenido entre `<!-- docviz:<nombre> -->` y
+ * `<!-- /docviz:<nombre> -->`.
+ *
+ * Se usan comentarios HTML porque son invisibles al leer el Markdown y
+ * sobreviven a la compilacion, de modo que la region se puede regenerar tantas
+ * veces como haga falta sin tocar la prosa que la rodea.
+ */
+function aplicar(texto, archivo) {
+  let salida = texto;
+  const marcas = [...texto.matchAll(/<!--\s*docviz:([\w-]+)\s*-->/g)].map((m) => m[1]);
+
+  for (const nombre of marcas) {
+    const generar = FRAGMENTOS[nombre];
+    if (generar === undefined) {
+      throw new Error(`${archivo}: la marca "docviz:${nombre}" no corresponde a ningun fragmento conocido`);
+    }
+    const patron = new RegExp(
+      `(<!--\\s*docviz:${nombre}\\s*-->)[\\s\\S]*?(<!--\\s*/docviz:${nombre}\\s*-->)`,
+      'g',
+    );
+    if (!patron.test(salida)) {
+      throw new Error(`${archivo}: falta la marca de cierre <!-- /docviz:${nombre} -->`);
+    }
+    patron.lastIndex = 0;
+    const contenido = generar();
+    // Un fragmento de una sola linea se queda en linea: si no, partiria la
+    // frase que lo rodea y el Markdown fuente quedaria ilegible.
+    const cuerpo = contenido.includes('\n') ? `\n${contenido}\n` : contenido;
+    salida = salida.replace(patron, `$1${cuerpo}$2`);
+  }
+  return salida;
+}
+
+const ARCHIVOS = ['README.md', 'AGENTS.md', 'docs-src/dsl.md'];
+
+let desfasados = [];
+for (const relativo of ARCHIVOS) {
+  const archivo = path.join(root, relativo);
+  const original = await readFile(archivo, 'utf8');
+  const actualizado = aplicar(original, relativo);
+  if (original === actualizado) continue;
+  if (check) desfasados.push(relativo);
+  else await writeFile(archivo, actualizado, 'utf8');
+}
+
+if (check) {
+  if (desfasados.length > 0) {
+    process.stderr.write(
+      `Documentacion desfasada respecto al catalogo:\n` +
+        desfasados.map((f) => `  - ${f}`).join('\n') +
+        `\n\nEjecuta \`npm run docs:sync\` y vuelve a confirmar.\n`,
+    );
+    process.exit(1);
+  }
+  process.stdout.write(`documentacion al dia con el catalogo (${TYPE_CATALOG.length} tipos)\n`);
+} else {
+  process.stdout.write(
+    `sincronizados ${ARCHIVOS.length} documentos con el catalogo (${TYPE_CATALOG.length} tipos)\n`,
+  );
+}

package/skills/docviz/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: docviz
+description: Genera diagramas y gráficos dentro de documentación Markdown declarando la intención (secuencia, flujo, arquitectura C4, barras, tendencia…) en lugar de escribir PlantUML, Mermaid, D2 o Vega-Lite a mano. Úsalo siempre que vayas a dibujar algo en un documento, cuando dudes qué tipo de diagrama encaja, o cuando un bloque de diagrama no compile. Todo se renderiza en local y la salida es Markdown estándar con imágenes SVG, así que se ve igual en GitHub, en un wiki o en un PDF.
+---
+
+# DocViz — diagramas como código dentro de Markdown
+
+Escribes **qué quieres explicar**; DocViz elige el motor y devuelve Markdown
+portable con la imagen ya generada. No escribas PlantUML, Mermaid, D2, Graphviz,
+Vega-Lite ni LikeC4 a mano: cada visor soporta un subconjunto distinto y el
+resultado deja de verse según dónde se lea.
+
+## Las tres vallas
+
+| Valla | Cuándo |
+|---|---|
+| `diagram` | Interacción, flujo, estados, dependencias, análisis estratégico |
+| `chart` | Comparación cuantitativa, tendencia, distribución |
+| `architecture` | Modelo C4 |
+
+````md
+```diagram
+type: sequence
+title: Autenticación
+
+participants:
+  - Usuario
+  - API
+
+flow:
+  - Usuario -> API: Login
+  - API --> Usuario: Token
+```
+````
+
+`->` es un mensaje, `-->` una respuesta.
+
+## No adivines el tipo — pregunta
+
+Hay 57 tipos. Antes de escribir un bloque, si no estás seguro:
+
+```bash
+npx docviz suggest "el proceso de aprobación de una solicitud"   # recomienda el tipo
+npx docviz types                                                 # catálogo con su propósito
+npx docviz types sequence                                        # ficha y ejemplo que compila tal cual
+```
+
+`docviz types <tipo>` imprime el esqueleto mínimo del tipo. Cópialo y rellénalo:
+es la forma más rápida de no equivocarte de campo.
+
+## Flujo de trabajo
+
+```bash
+npx docviz check docs-src                     # valida sin dibujar (rápido)
+npx docviz build docs-src --output docs       # compila a Markdown + SVG
+npx docviz verify docs                        # comprueba que no haya imágenes rotas
+npx docviz diff <docs-src anterior> docs-src  # qué diagramas cambiaron
+```
+
+No des la tarea por terminada mientras `check` o `verify` fallen.
+
+## Cuando algo falla
+
+Cada error trae un **código** además de archivo y línea. Léelo, no adivines:
+
+| Código | Qué hacer |
+|---|---|
+| `DV101` | Falta un campo obligatorio; el detalle dice cuál |
+| `DV102` | El campo está con la forma equivocada (lista donde iba mapa, o al revés) |
+| `DV103` | El valor no es uno de los admitidos; el detalle los enumera |
+| `DV104` | Escribiste un campo que ese tipo no usa. Si te propone otro nombre, es una errata |
+| `DV105` | El bloque no es YAML válido; suele ser la indentación |
+| `DV106` | El `type` no existe o va en otra valla; usa `docviz suggest` |
+| `DV005` | Falta Java o Chromium en la máquina. No cambies el diagrama: dilo |
+
+Un documento con varios bloques rotos los reporta **todos a la vez**:
+arréglalos en una sola pasada.
+
+Y antes de reescribir un bloque a mano:
+
+```bash
+npx docviz fix bloque.yaml    # corrige las erratas y dice si con eso basta
+```
+
+Un `AVISO ... [DV104]` no rompe el build, pero significa que un campo que
+escribiste no llegó al dibujo. O sobra, o está mal escrito; en ningún caso se
+ignora.
+
+## Reglas
+
+- Modifica los documentos fuente; nunca el directorio de salida ni `assets/generated`.
+- No generes SVG o PNG a mano si DocViz puede generarlos.
+- No fijes colores: el tema trae su equivalente en modo oscuro y un color escrito
+  a mano pierde esa propiedad.
+- No sustituyas un diagrama declarativo por una captura de pantalla.
+- Antes de dibujar, comprueba que aporta algo: para información sencilla, una
+  tabla o un párrafo comunican mejor. Un diagrama de veinte cajas no explica
+  nada — divídelo.
+
+## Primera vez en un proyecto
+
+```bash
+npm install -D docviz-builder
+npx docviz setup    # descarga plantuml.jar (única operación de red)
+npx docviz init     # configuración, AGENTS.md y un documento de ejemplo
+npx docviz doctor   # qué motores puede usar esta máquina
+```
+
+`docviz init` deja un `AGENTS.md` con el catálogo completo de los 57 tipos y sus
+tablas de decisión. Consúltalo cuando necesites el detalle que este resumen no
+trae.