@gradial/aci 0.1.0 → 0.1.1

package/src/cli/compile-registry.mjs

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
+import { GradialImageSchema } from '../types/image.ts';
 
 const args = parseArgs(process.argv.slice(2));
 
@@ -38,6 +39,7 @@ async function compileRegistry(options) {
     schemaFiles.push(schemaPath);
     const renderModes = component.renderModes ?? component.render;
     const varyDimensions = component.varyDimensions ?? component.vary;
+    const imageSlots = normalizeImageSlots(component.imageSlots);
     componentEntries.push({
       name: component.name,
       schemaFile,
@@ -53,6 +55,7 @@ async function compileRegistry(options) {
       },
       ...(component.defaultIslandMode ? { defaultIslandMode: component.defaultIslandMode } : {}),
       ...(varyDimensions?.length ? { vary: varyDimensions, varyDimensions } : {}),
+      ...(Object.keys(imageSlots).length ? { imageSlots } : {}),
     });
   }
 
@@ -84,6 +87,7 @@ function validateComponent(component, index, seen) {
   seen.add(component.name);
   if (!component.schema) throw new Error(`components[${index}].schema is required`);
   validateZodSubset(component.schema, `components[${index}].schema`);
+  validateImageSlotSchemaMatch(component, index);
   const renderModes = component.renderModes ?? component.render;
   if (!renderModes) throw new Error(`components[${index}].renderModes is required`);
   const enabled = Boolean(renderModes.canStatic ?? renderModes.static)
@@ -92,6 +96,164 @@ function validateComponent(component, index, seen) {
   if (!enabled) throw new Error(`components[${index}].renderModes must enable at least one mode`);
 }
 
+function validateImageSlotSchemaMatch(component, index) {
+  const imageSlots = normalizeImageSlots(component.imageSlots);
+  const imageFields = collectGradialImageFields(component.schema);
+  for (const field of imageFields) {
+    if (!Object.prototype.hasOwnProperty.call(imageSlots, field)) {
+      throw new Error(`components[${index}].imageSlots.${field} is required because schema field ${field} uses GradialImageSchema`);
+    }
+  }
+  for (const field of Object.keys(imageSlots)) {
+    if (!imageFields.has(field)) {
+      throw new Error(`components[${index}].schema.${field} must use GradialImageSchema because imageSlots.${field} is declared`);
+    }
+  }
+}
+
+function normalizeImageSlots(imageSlots) {
+  if (imageSlots == null) return {};
+  if (typeof imageSlots !== 'object' || Array.isArray(imageSlots)) {
+    throw new Error('imageSlots must be an object');
+  }
+  const out = {};
+  for (const [key, slot] of Object.entries(imageSlots)) {
+    if (!key) throw new Error('imageSlots keys must be non-empty');
+    if (!slot || typeof slot !== 'object' || Array.isArray(slot)) {
+      throw new Error(`imageSlots.${key} must be an object`);
+    }
+    if (!Array.isArray(slot.outputs) || !slot.outputs.length) {
+      throw new Error(`imageSlots.${key}.outputs must be a non-empty array`);
+    }
+    if (!Array.isArray(slot.formats) || !slot.formats.length) {
+      throw new Error(`imageSlots.${key}.formats must be a non-empty array`);
+    }
+    if (typeof slot.sizes !== 'string' || !slot.sizes.trim()) {
+      throw new Error(`imageSlots.${key}.sizes must be a non-empty string`);
+    }
+    out[key] = {
+      outputs: slot.outputs.map((output, outputIndex) => normalizeSlotOutput(key, output, outputIndex)),
+      formats: slot.formats.map((format, formatIndex) => {
+        if (typeof format !== 'string' || !format.trim()) {
+          throw new Error(`imageSlots.${key}.formats[${formatIndex}] must be a non-empty string`);
+        }
+        return format;
+      }),
+      sizes: slot.sizes,
+    };
+  }
+  return out;
+}
+
+function normalizeSlotOutput(slotKey, output, outputIndex) {
+  if (!output || typeof output !== 'object' || Array.isArray(output)) {
+    throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}] must be an object`);
+  }
+  if (typeof output.aspectRatio !== 'string' || !output.aspectRatio.trim()) {
+    throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].aspectRatio must be a non-empty string`);
+  }
+  if (!Array.isArray(output.widths) || !output.widths.length) {
+    throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].widths must be a non-empty array`);
+  }
+  const widths = output.widths.map((width, widthIndex) => {
+    if (!Number.isInteger(width) || width <= 0) {
+      throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].widths[${widthIndex}] must be a positive integer`);
+    }
+    return width;
+  });
+  return {
+    aspectRatio: output.aspectRatio,
+    widths,
+    ...(typeof output.media === 'string' && output.media.trim() ? { media: output.media } : {}),
+  };
+}
+
+function collectGradialImageFields(schema) {
+  const out = new Set();
+
+  collectGradialImageFieldsFromSchema(schema, '', out);
+
+  return out;
+}
+
+function collectGradialImageFieldsFromSchema(schema, prefix, out) {
+  if (!schema) {
+    return;
+  }
+
+  if (prefix && isGradialImageSchema(schema)) {
+    out.add(prefix);
+    return;
+  }
+
+  const itemSchema = arrayItemSchema(schema);
+  if (itemSchema) {
+    collectGradialImageFieldsFromSchema(itemSchema, prefix, out);
+    return;
+  }
+
+  const def = unwrapSchema(schema)?._def;
+  const shape = typeof def?.shape === 'function' ? def.shape() : def?.shape;
+  if (!shape || typeof shape !== 'object') {
+    return;
+  }
+
+  for (const [field, fieldSchema] of Object.entries(shape)) {
+    const nextPrefix = prefix ? `${prefix}.${field}` : field;
+    collectGradialImageFieldsFromSchema(fieldSchema, nextPrefix, out);
+  }
+}
+
+function arrayItemSchema(schema) {
+  let current = schema;
+  const seen = new Set();
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const def = current?._def;
+    if (!def) {
+      // Zod 4 mini: check for ~standard array type
+      if (current?.type === 'array' && current?.element) return current.element;
+      return null;
+    }
+    if (def.typeName === 'ZodArray') return def.type;
+    // Zod 4: array element might be in def.element
+    if (def.type === 'array' && def.element) return def.element;
+    current = def.innerType ?? def.schema;
+  }
+  return null;
+}
+
+function isGradialImageSchema(schema) {
+  const unwrapped = unwrapSchema(schema);
+  if (unwrapped === GradialImageSchema) return true;
+  try {
+    const compiled = z.toJSONSchema(unwrapped, {
+      target: 'draft-2020-12',
+      unrepresentable: 'throw',
+    });
+    return compiled?.type === 'object'
+      && compiled?.properties?.$type?.const === 'gradial.image'
+      && compiled?.properties?.fallback?.type === 'object'
+      && compiled?.properties?.sources?.type === 'array';
+  } catch {
+    return false;
+  }
+}
+
+function unwrapSchema(schema) {
+  let current = schema;
+  const seen = new Set();
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    if (current === GradialImageSchema) return current;
+    const def = current._def;
+    const next = def?.innerType ?? def?.schema;
+    if (!next) break;
+    current = next;
+  }
+  return current;
+}
+
 function validateLayout(layout, index, seen) {
   if (!layout || typeof layout !== 'object') throw new Error(`layouts[${index}] must be an object`);
   if (!layout.name) throw new Error(`layouts[${index}].name is required`);

package/src/cli/css-stub-loader.mjs

@@ -0,0 +1,27 @@
+/**
+ * Node.js custom loader that stubs CSS module imports.
+ * Used by CLI tools (compile-registry, validate-content) that need to import
+ * component files without actually loading CSS.
+ *
+ * Usage: node --import tsx --loader ./css-stub-loader.mjs <script>
+ */
+
+const CSS_EXTENSIONS = ['.css', '.module.css', '.scss', '.module.scss', '.less'];
+
+export function resolve(specifier, context, nextResolve) {
+  if (CSS_EXTENSIONS.some((ext) => specifier.endsWith(ext))) {
+    return { url: `css-stub:${specifier}`, shortCircuit: true };
+  }
+  return nextResolve(specifier, context);
+}
+
+export function load(url, context, nextLoad) {
+  if (url.startsWith('css-stub:')) {
+    return {
+      format: 'module',
+      source: 'export default {};',
+      shortCircuit: true,
+    };
+  }
+  return nextLoad(url, context);
+}

package/src/cli/generate-registry.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * generate-registry — Derives a runtime registry from co-located component contracts.
+ *
+ * Usage:
+ *   baremetal generate-registry --contracts <path> --output <path>
+ *
+ * --contracts  Path to the aggregation module (default-exports an array of ComponentContract).
+ * --output     Path to the generated TypeScript file.
+ *
+ * The generated file imports the contracts module and derives:
+ *   - `registry`: a flat map of component name -> component function (for the renderer)
+ *   - `contractMap`: a flat map of component name -> full contract (for tooling/validation)
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.contracts) {
+  console.error('Error: --contracts <path> is required');
+  process.exitCode = 1;
+} else if (!args.output) {
+  console.error('Error: --output <path> is required');
+  process.exitCode = 1;
+} else {
+  try {
+    await generateRegistry(args);
+    console.log(`Registry generated at ${args.output}`);
+  } catch (error) {
+    console.error(`Error: ${error?.message ?? error}`);
+    process.exitCode = 1;
+  }
+}
+
+async function generateRegistry({ contracts, output }) {
+  const contractsPath = contracts.replace(/\.(ts|tsx|js|mjs)$/, '');
+  const outputPath = path.resolve(output);
+
+  await mkdir(path.dirname(outputPath), { recursive: true });
+
+  const content = `// AUTO-GENERATED — do not edit. Run \`baremetal generate-registry\` to regenerate.
+import type { ComponentContract } from '@baremetal/sdk';
+import contracts from '${contractsPath}';
+
+export const registry = Object.fromEntries(
+  contracts.filter((c) => c.component != null).map((c) => [c.name, c.component]),
+);
+
+export const contractMap: Record<string, ComponentContract> = Object.fromEntries(
+  contracts.map((c) => [c.name, c]),
+);
+`;
+
+  await writeFile(outputPath, content, 'utf-8');
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const body = arg.slice(2);
+    const equals = body.indexOf('=');
+    if (equals >= 0) {
+      out[body.slice(0, equals)] = body.slice(equals + 1);
+      continue;
+    }
+    out[body] = argv[++i];
+  }
+  return out;
+}

package/src/cli/validate-content.mjs

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+/**
+ * validate-content — validate authored page content against compiled JSON schemas.
+ *
+ * Usage:
+ *   node validate-content.mjs \
+ *     --registry <path-to-compiled-registry-dir> \
+ *     --compiled <path-to-compiled-content-dir>
+ *
+ * Prerequisites:
+ *   1. Run compile-registry to generate registry.json + schemas/*.schema.json
+ *   2. Run content build to generate compiled routes + fragments
+ *
+ * Validates every block in the COMPILED output against JSON schemas.
+ * This validates the build result — after DAM resolution, fragment inlining, etc.
+ * Fails with exit code 1 if any published page has validation errors.
+ * Warns (but does not fail) for draft pages.
+ *
+ * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
+ * imports needed, same schemas usable by Go backend or other tools.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const args = parseArgs(process.argv.slice(2));
+
+try {
+  const result = await validateContent(args);
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.success) process.exitCode = 1;
+} catch (error) {
+  console.error(JSON.stringify({
+    success: false,
+    errors: [{ message: String(error?.message ?? error) }],
+  }, null, 2));
+  process.exitCode = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function validateContent(options) {
+  if (!options.registry) throw new Error('missing --registry (path to compiled registry directory)');
+  if (!options.compiled) throw new Error('missing --compiled (path to compiled content output directory)');
+
+  const registryDir = path.resolve(options.registry);
+  const contentRoot = path.resolve(options.compiled);
+
+  // Load compiled registry
+  const registryPath = path.join(registryDir, 'registry.json');
+  const registryRaw = await readFile(registryPath, 'utf-8');
+  const registry = JSON.parse(registryRaw);
+
+  // Build schema map: component name → JSON Schema object
+  const schemaMap = new Map();
+  const knownComponents = new Set();
+  for (const component of registry.components) {
+    knownComponents.add(component.name);
+    if (component.schemaFile) {
+      const schemaPath = path.join(registryDir, component.schemaFile);
+      const schemaRaw = await readFile(schemaPath, 'utf-8');
+      schemaMap.set(component.name, JSON.parse(schemaRaw));
+    }
+  }
+
+  // Find all compiled route files
+  const routesDir = path.join(contentRoot, 'routes');
+  const pageFiles = await findJsonFiles(routesDir);
+
+  const errors = [];
+  const warnings = [];
+  let pagesValidated = 0;
+  let blocksValidated = 0;
+
+  for (const pageFile of pageFiles) {
+    const relativePath = path.relative(contentRoot, pageFile);
+    let pageData;
+    try {
+      const raw = await readFile(pageFile, 'utf-8');
+      pageData = JSON.parse(raw);
+    } catch (err) {
+      errors.push({ page: relativePath, message: `failed to parse JSON: ${err.message}` });
+      continue;
+    }
+
+    pagesValidated++;
+    const isPublished = pageData.status === 'published';
+    const collector = isPublished ? errors : warnings;
+
+    const blocks = collectBlocks(pageData);
+
+    for (const block of blocks) {
+      blocksValidated++;
+
+      if (!block.component) {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          message: 'block is missing "component" field',
+        });
+        continue;
+      }
+
+      // Check component exists in registry
+      if (!knownComponents.has(block.component)) {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          component: block.component,
+          message: `unknown component: "${block.component}"`,
+        });
+        continue;
+      }
+
+      // Validate props against JSON Schema
+      const schema = schemaMap.get(block.component);
+      if (!schema) continue; // no schema file — component registered but no schema to check
+
+      const props = block.props ?? {};
+      const issues = validateJsonSchema(props, schema, 'props');
+      for (const issue of issues) {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          component: block.component,
+          path: issue.path,
+          message: issue.message,
+        });
+      }
+    }
+  }
+
+  // Also validate fragments
+  const fragmentsDir = path.join(contentRoot, 'fragments');
+  const fragmentFiles = await findJsonFiles(fragmentsDir);
+
+  for (const fragmentFile of fragmentFiles) {
+    const relativePath = path.relative(contentRoot, fragmentFile);
+    let fragmentData;
+    try {
+      const raw = await readFile(fragmentFile, 'utf-8');
+      fragmentData = JSON.parse(raw);
+    } catch (err) {
+      errors.push({ fragment: relativePath, message: `failed to parse JSON: ${err.message}` });
+      continue;
+    }
+
+    if (!fragmentData.component) continue;
+    blocksValidated++;
+
+    if (!knownComponents.has(fragmentData.component)) {
+      errors.push({
+        fragment: relativePath,
+        component: fragmentData.component,
+        message: `unknown component: "${fragmentData.component}"`,
+      });
+      continue;
+    }
+
+    const schema = schemaMap.get(fragmentData.component);
+    if (!schema) continue;
+
+    const props = fragmentData.props ?? {};
+    const issues = validateJsonSchema(props, schema, 'props');
+    for (const issue of issues) {
+      errors.push({
+        fragment: relativePath,
+        component: fragmentData.component,
+        path: issue.path,
+        message: issue.message,
+      });
+    }
+  }
+
+  const success = errors.length === 0;
+  return {
+    success,
+    pagesValidated,
+    blocksValidated,
+    errors,
+    ...(warnings.length > 0 ? { warnings } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Lightweight JSON Schema draft-2020-12 validator
+//
+// Covers the subset that Zod generates via z.toJSONSchema:
+//   type, required, properties, additionalProperties,
+//   minLength, minimum, maximum, enum, const,
+//   items, minItems, maxItems, anyOf, allOf, $ref (local)
+// ---------------------------------------------------------------------------
+
+function validateJsonSchema(value, schema, pathPrefix = '') {
+  const issues = [];
+  _validate(value, schema, pathPrefix, issues, schema);
+  return issues;
+}
+
+function _validate(value, schema, currentPath, issues, rootSchema) {
+  if (!schema || typeof schema !== 'object') return;
+
+  // $ref — resolve local references
+  if (schema.$ref) {
+    const resolved = resolveRef(schema.$ref, rootSchema);
+    if (resolved) {
+      _validate(value, resolved, currentPath, issues, rootSchema);
+    }
+    return;
+  }
+
+  // anyOf — value must match at least one
+  if (Array.isArray(schema.anyOf)) {
+    const anyMatches = schema.anyOf.some((sub) => {
+      const subIssues = [];
+      _validate(value, sub, currentPath, subIssues, rootSchema);
+      return subIssues.length === 0;
+    });
+    if (!anyMatches) {
+      issues.push({ path: currentPath, message: `${currentPath}: does not match any allowed schema` });
+    }
+    return;
+  }
+
+  // allOf — value must match all
+  if (Array.isArray(schema.allOf)) {
+    for (const sub of schema.allOf) {
+      _validate(value, sub, currentPath, issues, rootSchema);
+    }
+    return;
+  }
+
+  // const
+  if ('const' in schema) {
+    if (value !== schema.const) {
+      issues.push({ path: currentPath, message: `${currentPath}: expected constant "${schema.const}", got ${JSON.stringify(value)}` });
+    }
+    return;
+  }
+
+  // enum
+  if (Array.isArray(schema.enum)) {
+    if (!schema.enum.includes(value)) {
+      issues.push({ path: currentPath, message: `${currentPath}: expected one of [${schema.enum.join(', ')}], got ${JSON.stringify(value)}` });
+    }
+    return;
+  }
+
+  // type checking
+  const types = schema.type ? (Array.isArray(schema.type) ? schema.type : [schema.type]) : null;
+  if (types) {
+    const actualType = getJsonType(value);
+    const typeMatch = types.some((t) =>
+      t === actualType || (t === 'integer' && actualType === 'number' && Number.isInteger(value))
+    );
+    if (!typeMatch) {
+      // Allow null for nullable schemas
+      if (value !== null || !types.includes('null')) {
+        issues.push({ path: currentPath, message: `${currentPath}: expected type ${types.join('|')}, got ${actualType}` });
+        return; // Stop further checks if type is wrong
+      }
+    }
+  }
+
+  if (value === null || value === undefined) return;
+
+  // String checks
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      issues.push({ path: currentPath, message: `${currentPath}: string length ${value.length} is less than minLength ${schema.minLength}` });
+    }
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+      issues.push({ path: currentPath, message: `${currentPath}: string length ${value.length} exceeds maxLength ${schema.maxLength}` });
+    }
+  }
+
+  // Number checks
+  if (typeof value === 'number') {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) {
+      issues.push({ path: currentPath, message: `${currentPath}: ${value} is less than minimum ${schema.minimum}` });
+    }
+    if (typeof schema.maximum === 'number' && value > schema.maximum) {
+      issues.push({ path: currentPath, message: `${currentPath}: ${value} exceeds maximum ${schema.maximum}` });
+    }
+  }
+
+  // Array checks
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+      issues.push({ path: currentPath, message: `${currentPath}: array has ${value.length} items, minimum is ${schema.minItems}` });
+    }
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+      issues.push({ path: currentPath, message: `${currentPath}: array has ${value.length} items, maximum is ${schema.maxItems}` });
+    }
+    if (schema.items) {
+      for (let i = 0; i < value.length; i++) {
+        _validate(value[i], schema.items, `${currentPath}[${i}]`, issues, rootSchema);
+      }
+    }
+  }
+
+  // Object checks
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    // Required fields
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!(key in value) || value[key] === undefined) {
+          issues.push({ path: `${currentPath}.${key}`, message: `${currentPath}.${key}: required field is missing` });
+        }
+      }
+    }
+    // Properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in value) {
+          _validate(value[key], propSchema, `${currentPath}.${key}`, issues, rootSchema);
+        }
+      }
+    }
+  }
+}
+
+function getJsonType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function resolveRef(ref, rootSchema) {
+  if (!ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  let current = rootSchema;
+  for (const part of parts) {
+    current = current?.[part];
+  }
+  return current ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Content helpers
+// ---------------------------------------------------------------------------
+
+function collectBlocks(pageData) {
+  const blocks = [];
+  if (pageData.regions && typeof pageData.regions === 'object') {
+    for (const region of Object.values(pageData.regions)) {
+      if (Array.isArray(region)) blocks.push(...region);
+      else if (region && typeof region === 'object' && Array.isArray(region.children)) blocks.push(...region.children);
+    }
+  }
+  if (Array.isArray(pageData.blocks)) blocks.push(...pageData.blocks);
+  return blocks;
+}
+
+async function findPageFiles(dir) {
+  return findFilesMatching(dir, (name) => name === '_index.json');
+}
+
+async function findJsonFiles(dir) {
+  return findFilesMatching(dir, (name) => name.endsWith('.json'));
+}
+
+async function findFilesMatching(dir, predicate) {
+  const results = [];
+  try { await collectFiles(dir, predicate, results); }
+  catch (err) { if (err.code !== 'ENOENT') throw err; }
+  return results;
+}
+
+async function collectFiles(dir, predicate, results) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) await collectFiles(full, predicate, results);
+    else if (predicate(entry.name)) results.push(full);
+  }
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const body = arg.slice(2);
+    const equals = body.indexOf('=');
+    if (equals >= 0) { out[body.slice(0, equals)] = body.slice(equals + 1); continue; }
+    out[body] = argv[++i];
+  }
+  return out;
+}