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

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

@@ -1,358 +0,0 @@
-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

@@ -1,270 +0,0 @@
-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`,
-    );
-  }
-}