@zalify/storefront-kit 0.1.0

package/src/schemas/validate.ts

@@ -0,0 +1,302 @@
+/**
+ * Contract validators. Pure functions returning issue lists (never
+ * throwing): callers decide whether an issue is fatal. Structural
+ * invariants always run; schema-aware checks (block whitelists,
+ * max_blocks) run only when a manifest is provided, so templates can
+ * be validated before the component registry is known.
+ */
+import type {BlockData, SectionGroupData, TemplateData} from './data.ts';
+import type {ThemeEditorManifest} from './manifest.ts';
+import {
+  DEFAULT_MAX_BLOCKS,
+  allowedChildTypes,
+  isInputSetting,
+  isLocalBlockDefinition,
+  type SectionBlockEntry,
+  type SettingDefinition,
+  type ThemeBlockSchema,
+} from './schema.ts';
+
+export interface ValidationIssue {
+  /** JSON-pointer-ish location, e.g. "sections.hero.blocks.slide". */
+  path: string;
+  code:
+    | 'order-unknown-key'
+    | 'order-duplicate-key'
+    | 'unknown-type'
+    | 'block-not-allowed'
+    | 'max-blocks-exceeded'
+    | 'setting-missing-id'
+    | 'setting-duplicate-id'
+    | 'manifest-missing-field';
+  message: string;
+}
+
+interface SchemaContext {
+  manifest: ThemeEditorManifest;
+  allBlockTypes: string[];
+}
+
+function checkOrder(
+  order: string[] | undefined,
+  keys: Record<string, unknown> | undefined,
+  path: string,
+  issues: ValidationIssue[],
+): void {
+  if (!order) return;
+  const seen = new Set<string>();
+  for (const key of order) {
+    if (seen.has(key)) {
+      issues.push({
+        path,
+        code: 'order-duplicate-key',
+        message: `"${key}" appears more than once in the order array`,
+      });
+    }
+    seen.add(key);
+    if (!keys || !(key in keys)) {
+      issues.push({
+        path,
+        code: 'order-unknown-key',
+        message: `order references "${key}" which has no entry`,
+      });
+    }
+  }
+}
+
+/** Local block definitions in a section's schema, keyed by type. */
+function localDefinitions(
+  rules: SectionBlockEntry[] | undefined,
+): Record<string, ThemeBlockSchema> {
+  const defs: Record<string, ThemeBlockSchema> = {};
+  for (const rule of rules ?? []) {
+    if (isLocalBlockDefinition(rule)) {
+      defs[rule.type] = {name: rule.name, settings: rule.settings};
+    }
+  }
+  return defs;
+}
+
+function checkBlocks(
+  parentPath: string,
+  parentRules: SectionBlockEntry[] | undefined,
+  parentMaxBlocks: number | undefined,
+  blocks: Record<string, BlockData> | undefined,
+  blockOrder: string[] | undefined,
+  ctx: SchemaContext | null,
+  issues: ValidationIssue[],
+): void {
+  checkOrder(blockOrder, blocks, parentPath, issues);
+  if (!blocks) return;
+
+  if (ctx) {
+    const allowed = allowedChildTypes(parentRules, ctx.allBlockTypes);
+    const localDefs = localDefinitions(parentRules);
+    const count = blockOrder?.length ?? Object.keys(blocks).length;
+    const cap = parentRules?.length
+      ? (parentMaxBlocks ?? DEFAULT_MAX_BLOCKS)
+      : 0;
+    if (count > cap) {
+      issues.push({
+        path: parentPath,
+        code: 'max-blocks-exceeded',
+        message: `${count} blocks exceed the allowed maximum of ${cap}`,
+      });
+    }
+    for (const [key, block] of Object.entries(blocks)) {
+      const blockPath = `${parentPath}.blocks.${key}`;
+      const schema = ctx.manifest.blocks[block.type] ?? localDefs[block.type];
+      if (!schema) {
+        issues.push({
+          path: blockPath,
+          code: 'unknown-type',
+          message: `block type "${block.type}" is not in the manifest`,
+        });
+      } else if (!allowed.includes(block.type)) {
+        issues.push({
+          path: blockPath,
+          code: 'block-not-allowed',
+          message: `block type "${block.type}" is not allowed here`,
+        });
+      }
+      checkBlocks(
+        blockPath,
+        schema?.blocks,
+        undefined,
+        block.blocks,
+        block.block_order,
+        ctx,
+        issues,
+      );
+    }
+  } else {
+    for (const [key, block] of Object.entries(blocks)) {
+      checkBlocks(
+        `${parentPath}.blocks.${key}`,
+        undefined,
+        undefined,
+        block.blocks,
+        block.block_order,
+        null,
+        issues,
+      );
+    }
+  }
+}
+
+/**
+ * Validate a template (or section group) against the L1 invariants,
+ * and — when a manifest is given — against the section/block schemas.
+ */
+export function validateTemplate(
+  template: TemplateData | SectionGroupData,
+  manifest?: ThemeEditorManifest,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const ctx: SchemaContext | null = manifest
+    ? {manifest, allBlockTypes: Object.keys(manifest.blocks)}
+    : null;
+
+  checkOrder(template.order, template.sections, 'order', issues);
+  for (const [key, section] of Object.entries(template.sections ?? {})) {
+    const sectionPath = `sections.${key}`;
+    const schema = ctx?.manifest.sections[section.type];
+    if (ctx && !schema) {
+      issues.push({
+        path: sectionPath,
+        code: 'unknown-type',
+        message: `section type "${section.type}" is not in the manifest`,
+      });
+    }
+    checkBlocks(
+      sectionPath,
+      schema?.blocks,
+      schema?.max_blocks,
+      section.blocks,
+      section.block_order,
+      ctx,
+      issues,
+    );
+  }
+  return issues;
+}
+
+function checkSettings(
+  settings: SettingDefinition[] | undefined,
+  path: string,
+  issues: ValidationIssue[],
+): void {
+  if (!settings) return;
+  const ids = new Set<string>();
+  for (const [index, setting] of settings.entries()) {
+    if (!isInputSetting(setting)) continue;
+    if (!setting.id) {
+      issues.push({
+        path: `${path}[${index}]`,
+        code: 'setting-missing-id',
+        message: `input setting of type "${setting.type}" has no id`,
+      });
+      continue;
+    }
+    if (ids.has(setting.id)) {
+      issues.push({
+        path: `${path}[${index}]`,
+        code: 'setting-duplicate-id',
+        message: `duplicate setting id "${setting.id}"`,
+      });
+    }
+    ids.add(setting.id);
+  }
+}
+
+/** Validate a manifest's own consistency. */
+export function validateManifest(
+  manifest: ThemeEditorManifest,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  for (const field of [
+    'contractVersion',
+    'theme',
+    'sections',
+    'blocks',
+    'settingsSchema',
+    'templates',
+    'sectionGroups',
+    'locales',
+    'hash',
+  ] as const) {
+    if (manifest[field] === undefined || manifest[field] === null) {
+      issues.push({
+        path: field,
+        code: 'manifest-missing-field',
+        message: `manifest is missing "${field}"`,
+      });
+    }
+  }
+
+  const allBlockTypes = Object.keys(manifest.blocks ?? {});
+  for (const [type, section] of Object.entries(manifest.sections ?? {})) {
+    checkSettings(section.settings, `sections.${type}.settings`, issues);
+    for (const [ruleIndex, rule] of (section.blocks ?? []).entries()) {
+      if (isLocalBlockDefinition(rule)) {
+        checkSettings(
+          rule.settings,
+          `sections.${type}.blocks[${ruleIndex}].settings`,
+          issues,
+        );
+      } else if (
+        rule.type !== '@theme' &&
+        rule.type !== '@app' &&
+        !allBlockTypes.includes(rule.type)
+      ) {
+        issues.push({
+          path: `sections.${type}.blocks`,
+          code: 'unknown-type',
+          message: `block rule references unknown block type "${rule.type}"`,
+        });
+      }
+    }
+    for (const [index, preset] of (section.presets ?? []).entries()) {
+      const allowed = allowedChildTypes(section.blocks, allBlockTypes);
+      const walk = (
+        blocks: Array<{type: string; blocks?: unknown}> | undefined,
+        rules: string[],
+        where: string,
+      ): void => {
+        for (const block of blocks ?? []) {
+          if (!rules.includes(block.type)) {
+            issues.push({
+              path: where,
+              code: 'block-not-allowed',
+              message: `preset uses block type "${block.type}" which the parent does not allow`,
+            });
+          }
+          const child = manifest.blocks[block.type];
+          walk(
+            block.blocks as Array<{type: string; blocks?: unknown}> | undefined,
+            allowedChildTypes(child?.blocks, allBlockTypes),
+            where,
+          );
+        }
+      };
+      walk(preset.blocks, allowed, `sections.${type}.presets[${index}]`);
+    }
+  }
+  for (const [type, block] of Object.entries(manifest.blocks ?? {})) {
+    checkSettings(block.settings, `blocks.${type}.settings`, issues);
+    for (const rule of block.blocks ?? []) {
+      if (
+        rule.type !== '@theme' &&
+        rule.type !== '@app' &&
+        !allBlockTypes.includes(rule.type)
+      ) {
+        issues.push({
+          path: `blocks.${type}.blocks`,
+          code: 'unknown-type',
+          message: `block rule references unknown block type "${rule.type}"`,
+        });
+      }
+    }
+  }
+  return issues;
+}