docviz-builder 0.1.0

package/dist/dsl/fields.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Deteccion de campos que el tipo no usa.
+ *
+ * Un bloque puede compilar y aun asi no decir lo que el autor queria: escribir
+ * `steps:` donde el tipo espera `flow:` no rompe nada, simplemente ignora el
+ * contenido. El silencio es peor que el error, porque el agente da por buena una
+ * documentacion incompleta.
+ *
+ * La lista de campos validos no se mantiene a mano —serian 57 listas que se
+ * desincronizarian— sino que se deduce de dos fuentes que ya existen y ya estan
+ * probadas:
+ *
+ *   1. las claves del ejemplo canonico del catalogo, que compila tal cual;
+ *   2. las claves que el compilador realmente leyo, observadas con un Proxy.
+ *
+ * Un campo que no esta en ninguna de las dos no hizo nada. Eso es un hecho, no
+ * una heuristica, y por eso se puede reportar sin miedo a falsos positivos.
+ */
+import { type ErrorCode } from '../core/errors.js';
+import type { TypeSpec } from './catalog.js';
+export interface FieldWarning {
+    readonly code: ErrorCode;
+    readonly field: string;
+    readonly message: string;
+    /** Campo valido mas parecido, si la distancia sugiere una errata. */
+    readonly suggestion?: string;
+}
+/** Un mapa observado: el original, lo que se leyo de el y de donde viene. */
+interface RegistroObservado {
+    ruta: string;
+    objetivo: Record<string, unknown>;
+    accessed: Set<string>;
+    enumerated: boolean;
+}
+export interface FieldAccessTracker<T extends object> {
+    /** El documento envuelto: pasalo al compilador en lugar del original. */
+    readonly doc: T;
+    /** Claves leidas hasta ahora. */
+    readonly accessed: ReadonlySet<string>;
+    /**
+     * `true` si alguien enumero el mapa completo (`Object.keys`, `for...in`,
+     * desestructuracion con resto). En ese caso no se puede saber que claves se
+     * usaron de verdad y el analisis se abstiene.
+     */
+    enumerated(): boolean;
+    /** Mapas anidados observados durante la compilacion. */
+    readonly anidados: readonly RegistroObservado[];
+}
+/** Envuelve un mapa anidado si hay una compilacion observada en curso. */
+export declare function observarAnidado(valor: Record<string, unknown>, ruta: string): Record<string, unknown>;
+/**
+ * Envuelve el documento para observar que claves lee el compilador.
+ *
+ * No altera el valor devuelto por ninguna clave: el compilador se comporta
+ * exactamente igual con el Proxy que sin el.
+ */
+export declare function trackFieldAccess<T extends object>(doc: T): FieldAccessTracker<T>;
+/** Cierra la observacion. Siempre en un `finally`: si no, se filtra a la siguiente. */
+export declare function stopTracking(): void;
+/**
+ * Campos que el tipo declara en su ejemplo canonico, mas los universales.
+ *
+ * El ejemplo es la fuente correcta porque una prueba de integracion lo dibuja
+ * de verdad con su motor: si dejara de ser valido, el catalogo fallaria antes
+ * que esta funcion.
+ */
+export declare function knownFields(spec: TypeSpec): ReadonlySet<string>;
+/**
+ * Campos presentes en el bloque que ni el ejemplo declara ni el compilador leyo.
+ *
+ * Devuelve avisos, nunca errores: el bloque compila, solo que una parte de lo
+ * que escribio el autor no llego al dibujo.
+ */
+export declare function unknownFields(doc: Record<string, unknown>, spec: TypeSpec | undefined, tracker?: FieldAccessTracker<object>): FieldWarning[];
+/**
+ * Campos sin usar en los mapas anidados del documento.
+ *
+ * Aqui no hay ejemplo canonico contra el que comparar —no se sabe que posicion
+ * del ejemplo corresponde a cada mapa—, asi que el criterio es solo uno: si el
+ * compilador no leyo la clave, esa clave no hizo nada. Sigue siendo un hecho.
+ */
+export declare function unknownNestedFields(tracker: FieldAccessTracker<object>): FieldWarning[];
+/**
+ * Convierte los avisos en el detalle que acompana a un error ya producido.
+ *
+ * Cuando el bloque falla, la causa suele ser justo la errata: reportar solo
+ * "falta participants" obliga al agente a adivinar que `particpants` sobraba.
+ */
+export declare function describeFieldWarnings(warnings: readonly FieldWarning[], spec: TypeSpec | undefined): string;
+/** Distancia de Levenshtein con una sola fila de trabajo. */
+export declare function editDistance(a: string, b: string): number;
+export {};
+//# sourceMappingURL=fields.d.ts.map

package/dist/dsl/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/dsl/fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAQ7C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,6EAA6E;AAC7E,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM;IAClD,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAWD,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CA4ChF;AAED,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAgB/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,OAAO,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,GACnC,YAAY,EAAE,CA4BhB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,YAAY,EAAE,CAqBvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAU3G;AAqBD,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAezD"}

package/dist/dsl/fields.js

@@ -0,0 +1,233 @@
+/**
+ * Deteccion de campos que el tipo no usa.
+ *
+ * Un bloque puede compilar y aun asi no decir lo que el autor queria: escribir
+ * `steps:` donde el tipo espera `flow:` no rompe nada, simplemente ignora el
+ * contenido. El silencio es peor que el error, porque el agente da por buena una
+ * documentacion incompleta.
+ *
+ * La lista de campos validos no se mantiene a mano —serian 57 listas que se
+ * desincronizarian— sino que se deduce de dos fuentes que ya existen y ya estan
+ * probadas:
+ *
+ *   1. las claves del ejemplo canonico del catalogo, que compila tal cual;
+ *   2. las claves que el compilador realmente leyo, observadas con un Proxy.
+ *
+ * Un campo que no esta en ninguna de las dos no hizo nada. Eso es un hecho, no
+ * una heuristica, y por eso se puede reportar sin miedo a falsos positivos.
+ */
+import { parse as parseYaml } from 'yaml';
+import { ERROR_CODES } from '../core/errors.js';
+/** Campos que admite cualquier bloque, sea cual sea su tipo. */
+const UNIVERSAL_FIELDS = ['type', 'title'];
+/** Distancia maxima para considerar que un campo es una errata de otro. */
+const MAX_TYPO_DISTANCE = 2;
+/**
+ * Observador activo durante una compilacion.
+ *
+ * Los mapas anidados no se pueden envolver desde fuera: aparecen a medida que
+ * el compilador desciende por el documento, y quien los desenvuelve es
+ * `asRecord`. Esta variable es como `asRecord` sabe que hay alguien mirando.
+ */
+let observadorActivo;
+/** Envuelve un mapa anidado si hay una compilacion observada en curso. */
+export function observarAnidado(valor, ruta) {
+    return observadorActivo === undefined ? valor : observadorActivo.registrar(valor, ruta);
+}
+/**
+ * Envuelve el documento para observar que claves lee el compilador.
+ *
+ * No altera el valor devuelto por ninguna clave: el compilador se comporta
+ * exactamente igual con el Proxy que sin el.
+ */
+export function trackFieldAccess(doc) {
+    const anidados = [];
+    const envolver = (objetivo, registro) => new Proxy(objetivo, {
+        get(t, prop, receiver) {
+            if (typeof prop === 'string' && registro !== undefined)
+                registro.accessed.add(prop);
+            return Reflect.get(t, prop, receiver);
+        },
+        has(t, prop) {
+            if (typeof prop === 'string' && registro !== undefined)
+                registro.accessed.add(prop);
+            return Reflect.has(t, prop);
+        },
+        ownKeys(t) {
+            if (registro !== undefined)
+                registro.enumerated = true;
+            return Reflect.ownKeys(t);
+        },
+    });
+    const raiz = {
+        ruta: '',
+        objetivo: doc,
+        accessed: new Set(),
+        enumerated: false,
+    };
+    const observador = {
+        registrar(valor, ruta) {
+            // El mismo objeto puede llegar dos veces: se observa una sola.
+            const previo = anidados.find((r) => r.objetivo === valor);
+            if (previo !== undefined)
+                return envolver(valor, previo);
+            const registro = { ruta, objetivo: valor, accessed: new Set(), enumerated: false };
+            anidados.push(registro);
+            return envolver(valor, registro);
+        },
+    };
+    observadorActivo = observador;
+    return {
+        doc: envolver(doc, raiz),
+        accessed: raiz.accessed,
+        enumerated: () => raiz.enumerated,
+        anidados,
+    };
+}
+/** Cierra la observacion. Siempre en un `finally`: si no, se filtra a la siguiente. */
+export function stopTracking() {
+    observadorActivo = undefined;
+}
+const knownCache = new Map();
+/**
+ * Campos que el tipo declara en su ejemplo canonico, mas los universales.
+ *
+ * El ejemplo es la fuente correcta porque una prueba de integracion lo dibuja
+ * de verdad con su motor: si dejara de ser valido, el catalogo fallaria antes
+ * que esta funcion.
+ */
+export function knownFields(spec) {
+    const cached = knownCache.get(spec.type);
+    if (cached !== undefined)
+        return cached;
+    const fields = new Set(UNIVERSAL_FIELDS);
+    try {
+        const parsed = parseYaml(spec.example);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            for (const key of Object.keys(parsed))
+                fields.add(key);
+        }
+    }
+    catch {
+        // Un ejemplo que no parsea es un fallo del catalogo, no de este analisis:
+        // se queda con los universales y las pruebas del catalogo lo denuncian.
+    }
+    knownCache.set(spec.type, fields);
+    return fields;
+}
+/**
+ * Campos presentes en el bloque que ni el ejemplo declara ni el compilador leyo.
+ *
+ * Devuelve avisos, nunca errores: el bloque compila, solo que una parte de lo
+ * que escribio el autor no llego al dibujo.
+ */
+export function unknownFields(doc, spec, tracker) {
+    if (spec === undefined)
+        return [];
+    if (tracker !== undefined && tracker.enumerated())
+        return [];
+    const known = knownFields(spec);
+    const accessed = tracker?.accessed;
+    const warnings = [];
+    for (const field of Object.keys(doc)) {
+        if (known.has(field))
+            continue;
+        if (accessed !== undefined && accessed.has(field))
+            continue;
+        const suggestion = nearestField(field, known);
+        const message = suggestion !== undefined
+            ? `el campo "${field}" no existe en el tipo ${spec.type}; quiza querias "${suggestion}"`
+            : `el campo "${field}" no existe en el tipo ${spec.type} y se ha ignorado`;
+        const warning = {
+            code: ERROR_CODES.DSL_FIELD_UNKNOWN,
+            field,
+            message,
+            ...(suggestion !== undefined ? { suggestion } : {}),
+        };
+        warnings.push(warning);
+    }
+    return warnings;
+}
+/**
+ * Campos sin usar en los mapas anidados del documento.
+ *
+ * Aqui no hay ejemplo canonico contra el que comparar —no se sabe que posicion
+ * del ejemplo corresponde a cada mapa—, asi que el criterio es solo uno: si el
+ * compilador no leyo la clave, esa clave no hizo nada. Sigue siendo un hecho.
+ */
+export function unknownNestedFields(tracker) {
+    const warnings = [];
+    for (const registro of tracker.anidados) {
+        if (registro.enumerated)
+            continue;
+        for (const field of Object.keys(registro.objetivo)) {
+            if (registro.accessed.has(field))
+                continue;
+            const hermanas = [...registro.accessed].filter((k) => k in registro.objetivo);
+            const suggestion = nearestField(field, new Set(hermanas));
+            const donde = registro.ruta === '' ? '' : ` en ${registro.ruta}`;
+            warnings.push({
+                code: ERROR_CODES.DSL_FIELD_UNKNOWN,
+                field,
+                message: suggestion !== undefined
+                    ? `el campo "${field}"${donde} no se usa; quiza querias "${suggestion}"`
+                    : `el campo "${field}"${donde} no se usa y se ha ignorado`,
+                ...(suggestion !== undefined ? { suggestion } : {}),
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Convierte los avisos en el detalle que acompana a un error ya producido.
+ *
+ * Cuando el bloque falla, la causa suele ser justo la errata: reportar solo
+ * "falta participants" obliga al agente a adivinar que `particpants` sobraba.
+ */
+export function describeFieldWarnings(warnings, spec) {
+    if (warnings.length === 0)
+        return '';
+    const lines = warnings.map((w) => `  - ${w.message}`);
+    // "del ejemplo" y no "de sequence": el ejemplo es el esqueleto minimo, y un
+    // tipo puede admitir campos opcionales que no aparecen en el. Prometer una
+    // lista cerrada seria mentir.
+    const campos = spec === undefined ? '' : `\ncampos del ejemplo de ${spec.type}: ${[...knownFields(spec)].sort().join(', ')}`;
+    const ficha = spec === undefined ? '' : `\nficha completa: docviz types ${spec.type}`;
+    return `campos no reconocidos:\n${lines.join('\n')}${campos}${ficha}`;
+}
+/** Campo valido mas parecido, si la diferencia es propia de una errata. */
+function nearestField(field, known) {
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of known) {
+        const distance = editDistance(field, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    // El umbral es relativo ademas de absoluto: en un campo de tres letras, dos
+    // ediciones ya son una palabra distinta.
+    const limit = Math.min(MAX_TYPO_DISTANCE, Math.floor(field.length / 2));
+    return best !== undefined && bestDistance <= limit && bestDistance > 0 ? best : undefined;
+}
+/** Distancia de Levenshtein con una sola fila de trabajo. */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+//# sourceMappingURL=fields.js.map

package/dist/dsl/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../src/dsl/fields.ts"],"names":[],"mappings":"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"}

package/dist/dsl/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Punto de entrada del DSL de alto nivel.
+ *
+ * El agente que escribe documentacion solo necesita aprender tres vallas:
+ *
+ *     ```diagram```      intencion visual (secuencia, flujo, arbol, ...)
+ *     ```chart```        comparacion o tendencia cuantitativa
+ *     ```architecture``` modelo C4
+ *
+ * DocViz decide el motor. Los lenguajes nativos (`plantuml`, `mermaid`, `d2`,
+ * `graphviz`, `vega-lite`, `likec4`) siguen disponibles como via de escape.
+ */
+import { type TypeSpec } from './catalog.js';
+import { type FieldWarning } from './fields.js';
+export declare const DSL_LANGUAGES: readonly ["diagram", "chart", "architecture"];
+export type DslLanguage = (typeof DSL_LANGUAGES)[number];
+export interface CompiledDsl {
+    /** Motor que finalmente dibuja el bloque. */
+    rendererType: string;
+    source: string;
+    title?: string;
+    /** Ficha del tipo resuelto, util para diagnosticos. */
+    spec?: TypeSpec;
+    /**
+     * Campos que el bloque declaraba y el dibujo ignoro.
+     *
+     * No impiden compilar: el documento sale, pero no dice lo que el autor creia.
+     */
+    warnings?: FieldWarning[];
+}
+/** Predicado que indica si un motor esta disponible en el registro actual. */
+export type EngineAvailability = (engine: string) => boolean;
+export declare function isDslLanguage(lang: string): lang is DslLanguage;
+/** Catalogo legible, usado por `docviz types` y por las herramientas MCP. */
+export declare function dslCatalog(): Record<DslLanguage, string[]>;
+/** Catalogo completo con los metadatos de cada tipo. */
+export declare function dslCatalogDetailed(): readonly TypeSpec[];
+export declare function compileDsl(lang: string, source: string, isAvailable?: EngineAvailability): CompiledDsl;
+export { compileType, compileChartType, typesForEngine, compiledTypeNames, compilerEngines } from './compile.js';
+export { TYPE_CATALOG, findType, typeNames, typesFor, allTypeNames } from './catalog.js';
+export type { TypeSpec, DslLang } from './catalog.js';
+export { compileChartOfType } from './chart.js';
+export { knownFields, unknownFields, describeFieldWarnings, editDistance } from './fields.js';
+export type { FieldWarning } from './fields.js';
+export { compileArchitecture, architectureLikeC4 } from './architecture.js';
+/** Nombres de tipo de `diagram`, en orden alfabetico. */
+export declare function diagramTypeNames(): string[];
+/** Nombres de tipo de `chart`, en orden alfabetico. */
+export declare function chartTypeNames(): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/dsl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dsl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAGrB,eAAO,MAAM,aAAa,+CAAgD,CAAC;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAI7D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,WAAW,CAE/D;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAM1D;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,SAAS,QAAQ,EAAE,CAExD;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,kBAAkC,GAC9C,WAAW,CA8Eb;AAOD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzF,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5E,yDAAyD;AACzD,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED,uDAAuD;AACvD,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC"}

package/dist/dsl/index.js

@@ -0,0 +1,114 @@
+/**
+ * Punto de entrada del DSL de alto nivel.
+ *
+ * El agente que escribe documentacion solo necesita aprender tres vallas:
+ *
+ *     ```diagram```      intencion visual (secuencia, flujo, arbol, ...)
+ *     ```chart```        comparacion o tendencia cuantitativa
+ *     ```architecture``` modelo C4
+ *
+ * DocViz decide el motor. Los lenguajes nativos (`plantuml`, `mermaid`, `d2`,
+ * `graphviz`, `vega-lite`, `likec4`) siguen disponibles como via de escape.
+ */
+import { parse as parseYaml } from 'yaml';
+import { DocVizError, DslValidationError, ERROR_CODES } from '../core/errors.js';
+import { compileChartType, compileType } from './compile.js';
+import { findType, TYPE_CATALOG, typeNames } from './catalog.js';
+import { describeFieldWarnings, stopTracking, trackFieldAccess, unknownFields, unknownNestedFields, } from './fields.js';
+import { asRecord, optionalString } from './util.js';
+export const DSL_LANGUAGES = ['diagram', 'chart', 'architecture'];
+const ALL_AVAILABLE = () => true;
+export function isDslLanguage(lang) {
+    return DSL_LANGUAGES.includes(lang);
+}
+/** Catalogo legible, usado por `docviz types` y por las herramientas MCP. */
+export function dslCatalog() {
+    return {
+        diagram: typeNames('diagram'),
+        chart: typeNames('chart'),
+        architecture: typeNames('architecture'),
+    };
+}
+/** Catalogo completo con los metadatos de cada tipo. */
+export function dslCatalogDetailed() {
+    return TYPE_CATALOG;
+}
+export function compileDsl(lang, source, isAvailable = ALL_AVAILABLE) {
+    if (!isDslLanguage(lang)) {
+        throw new DslValidationError(`"${lang}" no es un lenguaje de DSL de DocViz`, `lenguajes validos: ${DSL_LANGUAGES.join(', ')}`, ERROR_CODES.DSL_TYPE);
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(source);
+    }
+    catch (err) {
+        throw new DslValidationError(`el bloque ${lang} no es YAML valido`, err instanceof Error ? err.message : String(err), ERROR_CODES.DSL_YAML);
+    }
+    if (parsed === null || parsed === undefined) {
+        throw new DslValidationError(`el bloque ${lang} esta vacio`, exampleFor(lang), ERROR_CODES.DSL_FIELD_MISSING);
+    }
+    const doc = asRecord(parsed, lang);
+    const title = optionalString(doc, 'title');
+    const declared = optionalString(doc, 'type');
+    if (declared === undefined && lang !== 'architecture') {
+        throw new DslValidationError(`el bloque ${lang} necesita un campo "type"`, exampleFor(lang), ERROR_CODES.DSL_FIELD_MISSING);
+    }
+    const typeName = declared ?? 'c4-context';
+    // El tipo debe pertenecer a la valla en la que se declaro: escribir un
+    // `type: bar` dentro de un bloque `diagram` es un error del autor, no una
+    // conversion silenciosa.
+    const spec = findType(typeName);
+    if (spec !== undefined && spec.lang !== lang) {
+        throw new DslValidationError(`el tipo "${typeName}" pertenece a la valla \`${spec.lang}\`, no a \`${lang}\``, `escribe el bloque como \`\`\`${spec.lang} en lugar de \`\`\`${lang}`, ERROR_CODES.DSL_TYPE);
+    }
+    // El compilador recibe el documento observado, no el original: asi se sabe
+    // que campos leyo de verdad y cuales quedaron sin usar.
+    const tracker = trackFieldAccess(doc);
+    let compiled;
+    try {
+        compiled =
+            lang === 'chart'
+                ? compileChartType(tracker.doc, typeName)
+                : compileType(tracker.doc, typeName, isAvailable);
+    }
+    catch (err) {
+        // Una errata suele ser la causa real del fallo: "falta participants" no le
+        // dice a nadie que el problema era haber escrito "particpants".
+        if (err instanceof DocVizError) {
+            throw err.withExtraDetail(describeFieldWarnings(unknownFields(doc, spec, tracker), spec));
+        }
+        throw err;
+    }
+    finally {
+        stopTracking();
+    }
+    const result = {
+        rendererType: compiled.engine,
+        source: compiled.source,
+        spec: compiled.spec,
+    };
+    if (title !== undefined)
+        result.title = title;
+    const warnings = [...unknownFields(doc, compiled.spec, tracker), ...unknownNestedFields(tracker)];
+    if (warnings.length > 0)
+        result.warnings = warnings;
+    return result;
+}
+function exampleFor(lang) {
+    const spec = findType(lang === 'diagram' ? 'sequence' : lang === 'chart' ? 'bar' : 'c4-context');
+    return spec !== undefined ? `ejemplo:\n${spec.example}` : '';
+}
+export { compileType, compileChartType, typesForEngine, compiledTypeNames, compilerEngines } from './compile.js';
+export { TYPE_CATALOG, findType, typeNames, typesFor, allTypeNames } from './catalog.js';
+export { compileChartOfType } from './chart.js';
+export { knownFields, unknownFields, describeFieldWarnings, editDistance } from './fields.js';
+export { compileArchitecture, architectureLikeC4 } from './architecture.js';
+/** Nombres de tipo de `diagram`, en orden alfabetico. */
+export function diagramTypeNames() {
+    return typeNames('diagram');
+}
+/** Nombres de tipo de `chart`, en orden alfabetico. */
+export function chartTypeNames() {
+    return typeNames('chart');
+}
+//# sourceMappingURL=index.js.map

package/dist/dsl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dsl/index.ts"],"names":[],"mappings":"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"}

package/dist/dsl/util.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Utilidades de validacion del DSL declarativo.
+ *
+ * Los mensajes son la interfaz real del DSL para un agente: deben decir que
+ * campo falla, que se esperaba y como se escribe bien.
+ */
+import { type ErrorCode } from '../core/errors.js';
+/**
+ * Aborta la compilacion del bloque.
+ *
+ * El codigo es tan importante como el texto: un agente que reintenta necesita
+ * distinguir "falta un campo" de "el valor no vale" sin leer castellano.
+ */
+export declare function fail(message: string, detail?: string, code?: ErrorCode): never;
+export declare function asRecord(value: unknown, field: string): Record<string, unknown>;
+/**
+ * Texto obligatorio.
+ *
+ * Acepta numeros y booleanos porque YAML los convierte sin avisar: en
+ * `- name: 2025` el valor llega como numero, y rechazarlo obligaria al autor a
+ * entrecomillar cualquier etiqueta que parezca un dato.
+ */
+export declare function requireString(record: Record<string, unknown>, key: string, field: string): string;
+export declare function optionalString(record: Record<string, unknown>, key: string): string | undefined;
+export declare function optionalNumber(record: Record<string, unknown>, key: string, field: string): number | undefined;
+export declare function requireNumber(record: Record<string, unknown>, key: string, field: string): number;
+export declare function requireArray(value: unknown, field: string): unknown[];
+export declare function optionalArray(value: unknown, field: string): unknown[];
+/**
+ * Acepta `- Texto` o `- name: Texto` de forma indistinta.
+ *
+ * Los numeros se admiten porque YAML los convierte solo: en `quadrants: [1, 2]`
+ * el autor esta escribiendo etiquetas, no cantidades.
+ */
+export declare function nameOf(item: unknown, field: string, key?: string): string;
+/**
+ * Normaliza `- Texto` y `- {name: Texto, ...}` a un mapa.
+ *
+ * Es el patron mas repetido del DSL: casi todas las listas admiten la forma
+ * corta. Centralizarlo evita que cada compilador olvide que YAML convierte
+ * `- 2025` en numero y rompa con una etiqueta perfectamente valida.
+ */
+export declare function asNamedRecord(raw: unknown, field: string, key?: string): Record<string, unknown>;
+export declare function oneOf<T extends string>(value: string | undefined, allowed: readonly T[], field: string, fallback: T): T;
+/**
+ * Generador de ids estables y seguros.
+ *
+ * Los motores destino se alimentan siempre de ids sinteticos (`n1`, `n2`, ...)
+ * y del texto original solo como etiqueta entrecomillada. Asi ningun caracter
+ * del documento puede alterar la sintaxis generada.
+ */
+export declare class IdFactory {
+    private readonly prefix;
+    private readonly byKey;
+    private counter;
+    constructor(prefix?: string);
+    id(key: string): string;
+    has(key: string): boolean;
+    get(key: string): string | undefined;
+    keys(): string[];
+}
+/** Cadena entre comillas dobles para D2. */
+export declare function d2Label(text: string): string;
+/** Cadena entre comillas simples para LikeC4. */
+export declare function likec4Label(text: string): string;
+/** Etiqueta segura para Mermaid: entre comillas y sin comillas internas. */
+export declare function mermaidLabel(text: string): string;
+/** Texto seguro dentro de una etiqueta PlantUML de una sola linea. */
+export declare function plantUmlText(text: string): string;
+/** Cadena entrecomillada para Graphviz DOT. */
+export declare function dotLabel(text: string): string;
+/**
+ * Interpreta la forma `Origen -> Destino: etiqueta`, admitiendo `->`, `-->`,
+ * `..>` y `<-` para invertir el sentido.
+ */
+export interface ParsedEdge {
+    from: string;
+    to: string;
+    label?: string;
+    dashed: boolean;
+}
+/**
+ * Detecta el mapa de una sola entrada que YAML produce a partir de
+ * `- Origen -> Destino: etiqueta`.
+ */
+export declare function asArrowShorthand(item: unknown): {
+    expression: string;
+    label?: string;
+} | undefined;
+export declare function parseEdgeExpression(expression: string, field: string): ParsedEdge;
+/**
+ * Normaliza un item de relacion.
+ *
+ * Admite tres formas:
+ *
+ *     - Usuario -> API: Login      (YAML lo entrega como mapa de una entrada)
+ *     - "Usuario -> API"           (cadena)
+ *     - {from: Usuario, to: API}   (mapa explicito)
+ *
+ * La primera es la que escribe cualquiera de forma natural, pero YAML la
+ * interpreta como `{ "Usuario -> API": "Login" }` por culpa de los dos puntos.
+ * Se reconoce ese caso en lugar de exigir comillas.
+ */
+export declare function toEdge(item: unknown, field: string): ParsedEdge;
+//# sourceMappingURL=util.d.ts.map

package/dist/dsl/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/dsl/util.ts"],"names":[],"mappings":"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"}