@tinya-code/gas-admin-ui 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/lib/core/registry/composition-validator.spec.ts

@@ -0,0 +1,358 @@
+import { setSchemaCatalog } from './schema-catalog';
+import { testCatalog } from '../testing/test-catalog';
+
+setSchemaCatalog(testCatalog);
+
+import { describe, expect, it } from 'vitest';
+
+import type {
+  DataSource,
+  NavigationTarget,
+  ResourceSchema,
+  SelectionBinding,
+  UiViewTabs,
+  ViewChildNode,
+} from '../models/schema.model';
+import {
+  MAX_DEPTH,
+  MAX_NODES,
+  SchemaCompositionError,
+  validateComposition,
+} from './composition-validator';
+
+/** Schema sintético mínimo para ejercitar el validador (D2 · R9.9.2). */
+function esquemaCon(uiViews: NonNullable<ResourceSchema['uiViews']>): ResourceSchema {
+  return {
+    id: 'orders',
+    label: 'Pedidos',
+    labelPlural: 'Pedidos',
+    kind: 'collection',
+    endpoint: {},
+    keyField: 'id',
+    titleField: 'title',
+    listColumns: [],
+    fields: [],
+    uiViews,
+  };
+}
+
+function tabs(children: ViewChildNode[]): UiViewTabs {
+  return { type: 'tabs', path: 'panel', config: { children } };
+}
+
+function hijo(id: string, type = 'list'): ViewChildNode {
+  return { id, label: `Hijo ${id}`, type };
+}
+
+/** Exige un `SchemaCompositionError` cuyo mensaje nombra todos los fragmentos. */
+function expectaError(fn: () => void, ...fragmentos: string[]): void {
+  let error: unknown;
+  try {
+    fn();
+  } catch (caught) {
+    error = caught;
+  }
+  expect(error, 'se esperaba un SchemaCompositionError').toBeInstanceOf(SchemaCompositionError);
+  for (const fragmento of fragmentos) {
+    expect((error as Error).message).toContain(fragmento);
+  }
+}
+
+describe('composition-validator', () => {
+  it('acepta una composición heterogénea válida', () => {
+    const schema = esquemaCon({
+      panel: tabs([
+        {
+          id: 'cal',
+          label: 'Calendario',
+          type: 'calendar',
+          config: { startField: 'pickup_date', titleField: 'customer_name' },
+        },
+        {
+          id: 'board',
+          label: 'Tablero',
+          type: 'kanban',
+          config: { groupField: 'status', columns: [] },
+        },
+        { id: 'rows', label: 'Filas', type: 'list' },
+      ]),
+      list: { type: 'list' },
+    });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+
+  it('deja pasar un schema sin composición (uiViews base)', () => {
+    const schema = esquemaCon({
+      list: { type: 'list' },
+      create: { type: 'form', path: 'new' },
+      detail: { type: 'detail', path: ':key' },
+    });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+
+  it('falla con id duplicado nombrando contenedor e id', () => {
+    const schema = esquemaCon({ panel: tabs([hijo('cal'), hijo('cal')]) });
+
+    expectaError(() => validateComposition(schema), 'orders.panel', 'cal', 'duplicado');
+  });
+
+  it('falla con un hijo sin id nombrando el contenedor', () => {
+    const sinId = { label: 'Sin id', type: 'list' } as ViewChildNode;
+    const schema = esquemaCon({ panel: tabs([sinId]) });
+
+    expectaError(() => validateComposition(schema), 'orders.panel', 'sin id');
+  });
+
+  it('falla con tipo de hijo sin descriptor nombrando recurso, contenedor e hijo (get, no resolve)', () => {
+    const schema = esquemaCon({ panel: tabs([hijo('cal', 'heatmap')]) });
+
+    expectaError(() => validateComposition(schema), 'orders', 'panel', 'cal', 'heatmap');
+  });
+
+  // ── Ciclos y refs (R9.9.2 · los `ref` hacen posible el ciclo) ──────────────
+
+  it('detecta un ciclo directo por ref nombrando hijo y contenedor', () => {
+    const schema = esquemaCon({
+      panel: tabs([{ id: 'self', label: 'Autorreferencia', ref: 'panel' }]),
+    });
+
+    expectaError(() => validateComposition(schema), 'orders.panel', 'self', 'ciclo');
+  });
+
+  it('detecta un ciclo transitivo por ref', () => {
+    const schema = esquemaCon({
+      a: tabs([{ id: 'ab', label: 'AB', ref: 'b' }]),
+      b: tabs([{ id: 'ba', label: 'BA', ref: 'a' }]),
+    });
+
+    expectaError(() => validateComposition(schema), 'ba', 'ciclo');
+  });
+
+  it('falla con un ref roto nombrando el hijo y el destino inexistente', () => {
+    const schema = esquemaCon({
+      panel: tabs([{ id: 'rows', label: 'Filas', ref: 'no-existe' }]),
+    });
+
+    expectaError(() => validateComposition(schema), 'orders.panel', 'rows', 'no-existe');
+  });
+
+  // ── Topes configurables (D2: MAX_DEPTH / MAX_NODES) ────────────────────────
+
+  it('acepta un anidamiento justo en el límite de profundidad', () => {
+    // a → b → c: los hijos de `c` quedan en profundidad MAX_DEPTH.
+    const schema = esquemaCon({
+      a: tabs([{ id: 'n1', label: 'N1', ref: 'b' }]),
+      b: tabs([{ id: 'n2', label: 'N2', ref: 'c' }]),
+      c: tabs([{ id: 'n3', label: 'N3', type: 'list' }]),
+    });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+
+  it('falla con profundidad sobre el límite nombrando el hijo y la profundidad observada', () => {
+    const schema = esquemaCon({
+      a: tabs([{ id: 'n1', label: 'N1', ref: 'b' }]),
+      b: tabs([{ id: 'n2', label: 'N2', ref: 'c' }]),
+      c: tabs([{ id: 'n3', label: 'N3', ref: 'd' }]),
+      d: tabs([{ id: 'n4', label: 'N4', type: 'list' }]),
+    });
+
+    expectaError(() => validateComposition(schema), 'n4', '4', String(MAX_DEPTH));
+  });
+
+  it('valida la profundidad ANIDADA dentro de un contenedor inline (no sólo vía ref)', () => {
+    // panel → n1 → n2 → n3 (todos tabs inline) ⇒ los hijos de n3 están en
+    // profundidad 4 y deben reventar ANTES del render (D2).
+    const schema = esquemaCon({
+      panel: tabs([
+        {
+          id: 'n1',
+          label: 'N1',
+          type: 'tabs',
+          config: {
+            children: [
+              {
+                id: 'n2',
+                label: 'N2',
+                type: 'tabs',
+                config: {
+                  children: [
+                    {
+                      id: 'n3',
+                      label: 'N3',
+                      type: 'tabs',
+                      config: { children: [hijo('n4')] },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      ]),
+    });
+
+    expectaError(() => validateComposition(schema), 'n4', 'profundidad', String(MAX_DEPTH));
+  });
+
+  it('detecta un ciclo que atraviesa un contenedor inline (D2)', () => {
+    const schema = esquemaCon({
+      panel: tabs([
+        {
+          id: 'hijo',
+          label: 'Hijo',
+          type: 'tabs',
+          config: { children: [{ id: 'loop', label: 'Loop', ref: 'panel' }] },
+        },
+      ]),
+    });
+
+    expectaError(() => validateComposition(schema), 'ciclo', 'panel');
+  });
+
+  it('acepta una composición con exactamente MAX_NODES nodos', () => {
+    const hijos = Array.from({ length: MAX_NODES }, (_, i) => hijo(`n${i}`));
+    const schema = esquemaCon({ panel: tabs(hijos) });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+
+  it('falla al superar MAX_NODES nombrando el tope', () => {
+    const hijos = Array.from({ length: MAX_NODES + 1 }, (_, i) => hijo(`n${i}`));
+    const schema = esquemaCon({ panel: tabs(hijos) });
+
+    expectaError(() => validateComposition(schema), 'límite de', String(MAX_NODES));
+  });
+
+  // ── Destino de navegación (spec view-navigation: URL cruda rechazada) ──────
+
+  it('rechaza una URL cruda como destino nombrando recurso, contenedor e hijo', () => {
+    const schema = esquemaCon({
+      panel: tabs([
+        {
+          id: 'rows',
+          label: 'Filas',
+          type: 'list',
+          select: {
+            on: 'open',
+            mode: 'route',
+            target: 'https://evil.com/x' as unknown as NavigationTarget,
+          },
+        },
+      ]),
+    });
+
+    expectaError(
+      () => validateComposition(schema),
+      'orders.panel',
+      'rows',
+      'URL cruda',
+      'https://evil.com/x',
+    );
+  });
+
+  it('rechaza una URL cruda declarada en una uiView raíz', () => {
+    const schema = esquemaCon({
+      list: {
+        type: 'list',
+        select: {
+          on: 'open',
+          mode: 'route',
+          target: '/dashboard' as unknown as NavigationTarget,
+        },
+      },
+    });
+
+    expectaError(() => validateComposition(schema), 'orders.list', 'URL cruda', '/dashboard');
+  });
+
+  function esquemaConSelect(target: NavigationTarget): ResourceSchema {
+    return esquemaCon({
+      list: { type: 'list', select: { on: 'open', mode: 'route', target } },
+    });
+  }
+
+  it('valida que el destino nombre un recurso y una uiView declarados', () => {
+    expectaError(
+      () => validateComposition(esquemaConSelect({ resource: 'fantasma', view: 'detail' })),
+      'orders.list',
+      'fantasma',
+    );
+    expectaError(
+      () => validateComposition(esquemaConSelect({ resource: 'orders', view: 'no-existe' })),
+      'orders.list',
+      'no-existe',
+    );
+  });
+
+  it('valida los params declarados contra la ruta del destino', () => {
+    // Param que la ruta del destino no tiene.
+    expectaError(
+      () =>
+        validateComposition(
+          esquemaConSelect({ resource: 'orders', view: 'detail', params: ['nope'] }),
+        ),
+      'nope',
+    );
+    // Falta declarar el param que la ruta `orders/:key` exige.
+    expectaError(
+      () => validateComposition(esquemaConSelect({ resource: 'orders', view: 'detail' })),
+      'key',
+    );
+  });
+
+  it('acepta un destino declarado con resource + view + params válidos', () => {
+    const schema = esquemaConSelect({
+      resource: 'orders',
+      view: 'detail',
+      params: ['key'],
+    });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+
+  // ── Fuente de filas incompatible (R9.9.2 · "incompatible sources") ─────────
+
+  function esquemaConSource(source: DataSource): ResourceSchema {
+    return esquemaCon({
+      panel: tabs([
+        {
+          id: 'cal',
+          label: 'Calendario',
+          type: 'calendar',
+          config: { startField: 'pickup_date', titleField: 'customer_name', source },
+        },
+      ]),
+    });
+  }
+
+  it('falla con una source sobre un recurso no declarado', () => {
+    expectaError(
+      () => validateComposition(esquemaConSource({ resource: 'fantasma' })),
+      'orders.panel',
+      'cal',
+      'fantasma',
+    );
+  });
+
+  it('falla con una source sobre una vista no declarada del recurso', () => {
+    expectaError(
+      () => validateComposition(esquemaConSource({ resource: 'orders', view: 'vista-fantasma' })),
+      'vista-fantasma',
+    );
+  });
+
+  it('acepta una source con recurso declarado y sin vista', () => {
+    expect(() => validateComposition(esquemaConSource({ resource: 'orders' }))).not.toThrow();
+  });
+
+  it('un binding mode none/inline no exige target', () => {
+    const schema = esquemaCon({
+      list: { type: 'list', select: { on: 'open', mode: 'inline' } satisfies SelectionBinding },
+    });
+
+    expect(() => validateComposition(schema)).not.toThrow();
+  });
+});

package/src/lib/core/registry/composition-validator.ts

@@ -0,0 +1,270 @@
+import { getSchema } from './schema-catalog';
+import type {
+  DataSource,
+  NavigationTarget,
+  ResourceSchema,
+  SelectionBinding,
+  UiViewDescriptor,
+  ViewChildNode,
+} from '../models/schema.model';
+import { get } from './render-registry';
+
+/**
+ * Validador de composición de vistas (R9.9.2 · D2/D3).
+ *
+ * Una composición (un `uiView` contenedor con `config.children`, p. ej.
+ * `tabs`) se valida ANTES del render con esta única función pura y síncrona:
+ *
+ *  - identidad de hijos (`id` presente y único entre hermanos);
+ *  - tipos resueltos con `get('view', type)` — **nunca** `resolve()`, cuyo
+ *    `fallback` silencioso dejaría un hijo inválido pintándose de todos modos;
+ *  - `ref` rotos y ciclos (directos o transitivos) que los `ref` permiten;
+ *  - profundidad y cantidad de nodos con topes configurables;
+ *  - destinos de navegación (`resource` + `view` + params) y fuentes de
+ *    filas — una URL cruda nunca es un destino válido;
+ *
+ * El llamante es D3: `resourceRoutes()` en `shell.routes.ts` (fail-loud al
+ * arrancar) y el guardián de montaje del composer. Cualquier violación lanza
+ * `SchemaCompositionError` con un mensaje legible que nombra recurso,
+ * contenedor e hijo: nada se oculta ni se sustituye en silencio.
+ *
+ * El tipo de una `uiView` RAÍZ no se chequea acá: eso ya lo hace
+ * `resourceRoutes()` con su error genérico de descriptor inexistente. Este
+ * validador cubre lo que ese recorrido no ve: la estructura de los hijos.
+ */
+
+/** Profundidad máxima de anidamiento de contenedores (hijos raíz = 1). */
+export const MAX_DEPTH = 3;
+
+/** Cantidad máxima de nodos-hijo declarados en la composición de un schema. */
+export const MAX_NODES = 50;
+
+/** Violación del contrato de composición, detectada antes del render. */
+export class SchemaCompositionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SchemaCompositionError';
+  }
+}
+
+/** Estado del recorrido: cuenta de nodos y camino actual (detección de ciclos). */
+interface Estado {
+  readonly esquema: ResourceSchema;
+  nodos: number;
+  readonly contados: Set<ViewChildNode>;
+  readonly camino: Set<string>;
+}
+
+/** `config` de la vista cuando la hay (`tabs` es el único contenedor hoy). */
+function configDe(vista: UiViewDescriptor | ViewChildNode): unknown {
+  return 'config' in vista ? vista.config : undefined;
+}
+
+/** Hijos declarados si la vista es un contenedor; `undefined` si no lo es. */
+function hijosDe(vista: UiViewDescriptor | ViewChildNode): ViewChildNode[] | undefined {
+  const hijos = (configDe(vista) as { children?: unknown } | undefined)?.children;
+  return Array.isArray(hijos) ? (hijos as ViewChildNode[]) : undefined;
+}
+
+/**
+ * Valida TODA la composición de un schema. Lanza `SchemaCompositionError`
+ * en la primera violación; no lanzar significa «apto para renderizar».
+ */
+export function validateComposition(schema: ResourceSchema): void {
+  const estado: Estado = { esquema: schema, nodos: 0, contados: new Set(), camino: new Set() };
+  for (const [nombre, vista] of Object.entries(schema.uiViews ?? {})) {
+    estado.camino.add(nombre);
+    validarContenido(nombre, vista, 1, estado);
+    estado.camino.delete(nombre);
+  }
+}
+
+/**
+ * Valida una `uiView` ya resuelta (raíz o referenciada por `ref`): sus
+ * bindings, su fuente de filas y —si es contenedor— sus hijos.
+ * `profundidadHijos` es la profundidad que tendrán sus hijos directos.
+ */
+function validarContenido(
+  nombre: string,
+  vista: UiViewDescriptor,
+  profundidadHijos: number,
+  estado: Estado,
+): void {
+  const donde = `${estado.esquema.id}.${nombre}`;
+  validarSelect(donde, (vista as { select?: SelectionBinding }).select);
+  validarSource(donde, (configDe(vista) as { source?: DataSource } | undefined)?.source);
+  const hijos = hijosDe(vista);
+  if (!hijos) return;
+  validarHijos(nombre, hijos, profundidadHijos, estado);
+}
+
+/** Valida la lista de hijos de un contenedor: identidad única entre hermanos. */
+function validarHijos(
+  contenedor: string,
+  hijos: readonly ViewChildNode[],
+  profundidad: number,
+  estado: Estado,
+): void {
+  const ids = new Set<string>();
+  for (const hijo of hijos) {
+    const id = (hijo as { id?: unknown }).id;
+    if (typeof id !== 'string' || id === '') {
+      throw new SchemaCompositionError(`${estado.esquema.id}.${contenedor}: hijo sin id`);
+    }
+    if (ids.has(id)) {
+      throw new SchemaCompositionError(`${estado.esquema.id}.${contenedor}: id duplicado '${id}'`);
+    }
+    ids.add(id);
+    validarHijo(hijo, contenedor, id, profundidad, estado);
+  }
+}
+
+/** Valida un hijo: topes de nodos/profundidad, ciclo, ref y tipo inline. */
+function validarHijo(
+  hijo: ViewChildNode,
+  contenedor: string,
+  id: string,
+  profundidad: number,
+  estado: Estado,
+): void {
+  const donde = `${estado.esquema.id}.${contenedor} → child '${id}'`;
+
+  if (!estado.contados.has(hijo)) {
+    estado.contados.add(hijo);
+    estado.nodos += 1;
+    if (estado.nodos > MAX_NODES) {
+      throw new SchemaCompositionError(
+        `${estado.esquema.id}: la composición supera el límite de ${MAX_NODES} nodos (observados ${estado.nodos})`,
+      );
+    }
+  }
+  if (profundidad > MAX_DEPTH) {
+    throw new SchemaCompositionError(
+      `${donde}: profundidad ${profundidad} supera el máximo ${MAX_DEPTH}`,
+    );
+  }
+
+  if ('ref' in hijo) {
+    validarRef(donde, (hijo as { ref?: unknown }).ref as string, profundidad, estado);
+    return;
+  }
+
+  const tipo = (hijo as { type?: unknown }).type as string;
+  if (!get('view', tipo)) {
+    throw new SchemaCompositionError(`${donde}: tipo desconocido '${tipo}'`);
+  }
+  validarSelect(donde, (hijo as { select?: SelectionBinding }).select);
+  validarSource(donde, (configDe(hijo) as { source?: DataSource } | undefined)?.source);
+  /**
+   * Contenedor inline: sus propios hijos también se validan. Sin esto, una
+   * composición anidada dentro de otro `tabs` inline se renderiza sin haber
+   * pasado por topes de profundidad/nodos ni por la detección de ciclos de
+   * sus `ref` (D2: invalid branch NUNCA llega al render). La profundidad
+   * CONTINUA desde este hijo — no se reinicia — y el camino de ciclo se
+   * mantiene intacto, porque un `ref` sólo puede volver a nombres que ya
+   * están en él.
+   */
+  const internos = hijosDe(hijo);
+  if (internos !== undefined) {
+    validarHijos(id, internos, profundidad + 1, estado);
+  }
+}
+
+/**
+ * Resuelve un hijo `ref` contra `schema.uiViews`: el destino debe existir y
+ * no formar parte del camino actual (ciclo directo o transitivo). El
+ * contenido del destino se valida en profundidad CONTINUANDO la del ref —
+ * un `ref` anida de verdad (R9.9.2).
+ */
+function validarRef(donde: string, target: string, profundidad: number, estado: Estado): void {
+  if (estado.camino.has(target)) {
+    throw new SchemaCompositionError(
+      `${donde}: ciclo detectado — '${target}' ya está en el camino`,
+    );
+  }
+  const vista = estado.esquema.uiViews?.[target];
+  if (!vista) {
+    throw new SchemaCompositionError(
+      `${donde}: ref '${target}' no existe en ${estado.esquema.id}.uiViews`,
+    );
+  }
+  estado.camino.add(target);
+  validarContenido(target, vista, profundidad + 1, estado);
+  estado.camino.delete(target);
+}
+
+/**
+ * Valida el binding de selección de una `uiView` o de un hijo (R9.9.4).
+ * Sólo `mode: 'route'` exige destino declarado; `none`/`inline` son locales.
+ */
+function validarSelect(donde: string, select: SelectionBinding | undefined): void {
+  if (select === undefined || select.mode !== 'route') return;
+  const target = (select as { target?: unknown }).target;
+  if (target === undefined || target === null) {
+    throw new SchemaCompositionError(`${donde}: select mode 'route' sin target`);
+  }
+  if (typeof target === 'string') {
+    throw new SchemaCompositionError(
+      `${donde}: destino con URL cruda '${target}' — declará resource + view`,
+    );
+  }
+  validarTarget(donde, target as NavigationTarget);
+}
+
+/**
+ * El destino sólo puede ser un recurso + `uiView` declarados, con los params
+ * declarados EXACTAMENTE igual que los params de la ruta del destino: ni
+ * params ajenos a la ruta ni params de la ruta sin declarar.
+ */
+function validarTarget(donde: string, target: NavigationTarget): void {
+  const { resource, view, params } = target;
+  if (typeof resource !== 'string' || resource === '' || typeof view !== 'string' || view === '') {
+    throw new SchemaCompositionError(`${donde}: destino sin resource + view`);
+  }
+  const destino = getSchema(resource);
+  if (!destino) {
+    throw new SchemaCompositionError(`${donde}: destino '${resource}' no existe`);
+  }
+  const vista = destino.uiViews?.[view];
+  if (!vista) {
+    throw new SchemaCompositionError(
+      `${donde}: destino ${resource}.${view} no tiene uiView declarada`,
+    );
+  }
+  const paramsRuta = (vista.path ?? '')
+    .split('/')
+    .filter((segmento) => segmento.startsWith(':'))
+    .map((segmento) => segmento.slice(1));
+  const declarados = params ?? [];
+  for (const param of declarados) {
+    if (!paramsRuta.includes(param)) {
+      throw new SchemaCompositionError(
+        `${donde}: param '${param}' no existe en la ruta ${resource}.${view}`,
+      );
+    }
+  }
+  for (const param of paramsRuta) {
+    if (!declarados.includes(param)) {
+      throw new SchemaCompositionError(
+        `${donde}: falta declarar el param '${param}' de la ruta ${resource}.${view}`,
+      );
+    }
+  }
+}
+
+/** Valida la fuente de filas (`config.source`) declarada por una vista (R9.8). */
+function validarSource(donde: string, source: DataSource | undefined): void {
+  if (source === undefined) return;
+  if (typeof source.resource !== 'string' || source.resource === '') {
+    throw new SchemaCompositionError(`${donde}: source sin resource`);
+  }
+  const origen = getSchema(source.resource);
+  if (!origen) {
+    throw new SchemaCompositionError(`${donde}: source '${source.resource}' no existe`);
+  }
+  if (source.view !== undefined && origen.views?.[source.view] === undefined) {
+    throw new SchemaCompositionError(
+      `${donde}: la vista '${source.view}' no existe en ${source.resource}.views`,
+    );
+  }
+}