@gradial/aci 0.1.1 → 0.1.2

package/src/cli/compile-registry.mjs

@@ -5,6 +5,16 @@ import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { GradialImageSchema } from '../types/image.ts';
 
+// Shim React global so JSX-containing component files can be loaded.
+// The compile-registry only extracts contract metadata (schemas, imageSlots)
+// and never renders components, but importing .tsx files requires the JSX
+// runtime to be resolvable. Next.js uses jsx: "preserve" which leaves React
+// references in the transpiled output.
+try {
+  const React = await import('react');
+  if (!globalThis.React) globalThis.React = React;
+} catch { /* react not available — component files without JSX will still work */ }
+
 const args = parseArgs(process.argv.slice(2));
 
 try {
@@ -62,6 +72,19 @@ async function compileRegistry(options) {
   const seenLayouts = new Set();
   const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
 
+  // Post-compilation: detect nested block patterns in JSON schemas and
+  // validate that referenced component names exist in the registry.
+  const knownNames = new Set(componentEntries.map((c) => c.name));
+  for (const entry of componentEntries) {
+    const schemaPath = path.join(outDir, entry.schemaFile);
+    const schemaRaw = await import('node:fs/promises').then((fs) => fs.readFile(schemaPath, 'utf-8'));
+    const schema = JSON.parse(schemaRaw);
+    const nestedBlocks = collectNestedBlockRefs(schema, knownNames, entry.name);
+    if (nestedBlocks.length > 0) {
+      entry.nestedBlocks = nestedBlocks;
+    }
+  }
+
   const registry = {
     manifestVersion: '1',
     generatedAt: new Date().toISOString(),
@@ -192,6 +215,14 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
     return;
   }
 
+  const unionOptions = unionOptionSchemas(schema);
+  if (unionOptions) {
+    for (const option of unionOptions) {
+      collectGradialImageFieldsFromSchema(option, prefix, out);
+    }
+    return;
+  }
+
   const def = unwrapSchema(schema)?._def;
   const shape = typeof def?.shape === 'function' ? def.shape() : def?.shape;
   if (!shape || typeof shape !== 'object') {
@@ -204,6 +235,14 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
   }
 }
 
+function unionOptionSchemas(schema) {
+  const def = unwrapSchema(schema)?._def;
+  if (!def) return null;
+  if (Array.isArray(def.options)) return def.options;
+  if (def.options instanceof Map) return Array.from(def.options.values());
+  return null;
+}
+
 function arrayItemSchema(schema) {
   let current = schema;
   const seen = new Set();
@@ -231,10 +270,13 @@ function isGradialImageSchema(schema) {
       target: 'draft-2020-12',
       unrepresentable: 'throw',
     });
+    const sources = compiled?.properties?.sources;
+    const sourcesIsArray = sources?.type === 'array'
+      || (Array.isArray(sources?.anyOf) && sources.anyOf.some((s) => s?.type === 'array'));
     return compiled?.type === 'object'
       && compiled?.properties?.$type?.const === 'gradial.image'
       && compiled?.properties?.fallback?.type === 'object'
-      && compiled?.properties?.sources?.type === 'array';
+      && sourcesIsArray;
   } catch {
     return false;
   }
@@ -344,6 +386,105 @@ function childSchemas(def) {
   return children;
 }
 
+// ---------------------------------------------------------------------------
+// Nested block detection — walks generated JSON schemas to find blockRef
+// patterns (objects with `component` enum + `props`) and validates that
+// referenced component names exist in the registry.
+// ---------------------------------------------------------------------------
+
+function collectNestedBlockRefs(schema, knownNames, componentName) {
+  const results = [];
+  _walkSchemaForBlockRefs(schema, schema, '', results, knownNames, componentName);
+  return results;
+}
+
+function _walkSchemaForBlockRefs(node, rootSchema, currentPath, results, knownNames, componentName) {
+  if (!node || typeof node !== 'object') return;
+
+  // Resolve $ref
+  if (node.$ref) {
+    const resolved = resolveJsonSchemaRef(node.$ref, rootSchema);
+    if (resolved) _walkSchemaForBlockRefs(resolved, rootSchema, currentPath, results, knownNames, componentName);
+    return;
+  }
+
+  // Check if this object matches the blockRef signature:
+  // { type: "object", properties: { id, component, props } }
+  if (isBlockRefSchema(node)) {
+    const allow = extractBlockRefAllow(node, rootSchema);
+    // Validate allowed names exist
+    for (const name of allow) {
+      if (!knownNames.has(name)) {
+        throw new Error(
+          `${componentName}: nested block allowlist references unknown component "${name}" at ${currentPath || '(root)'}`,
+        );
+      }
+    }
+    results.push({
+      path: currentPath || '(root)',
+      ...(allow.length > 0 ? { allow } : {}),
+    });
+    return; // Don't recurse into the block schema itself
+  }
+
+  // Recurse into object properties
+  if (node.properties) {
+    for (const [key, propSchema] of Object.entries(node.properties)) {
+      const nextPath = currentPath ? `${currentPath}.${key}` : key;
+      _walkSchemaForBlockRefs(propSchema, rootSchema, nextPath, results, knownNames, componentName);
+    }
+  }
+
+  // Recurse into array items
+  if (node.items) {
+    _walkSchemaForBlockRefs(node.items, rootSchema, `${currentPath}[]`, results, knownNames, componentName);
+  }
+
+  // Recurse into anyOf / allOf / oneOf
+  for (const keyword of ['anyOf', 'allOf', 'oneOf']) {
+    if (Array.isArray(node[keyword])) {
+      for (const sub of node[keyword]) {
+        _walkSchemaForBlockRefs(sub, rootSchema, currentPath, results, knownNames, componentName);
+      }
+    }
+  }
+}
+
+function isBlockRefSchema(node) {
+  if (node.type !== 'object' || !node.properties) return false;
+  const props = node.properties;
+  // Must have component and props fields
+  if (!props.component || !props.props) return false;
+  // component must be a string or enum
+  const comp = props.component;
+  if (comp.type !== 'string' && !Array.isArray(comp.enum)) return false;
+  // props must be an object (record)
+  if (props.props.type !== 'object') return false;
+  return true;
+}
+
+function extractBlockRefAllow(node, rootSchema) {
+  let comp = node.properties.component;
+  // Resolve $ref on the component field
+  if (comp.$ref) {
+    comp = resolveJsonSchemaRef(comp.$ref, rootSchema) ?? comp;
+  }
+  if (Array.isArray(comp.enum)) {
+    return comp.enum.filter((v) => typeof v === 'string');
+  }
+  return [];
+}
+
+function resolveJsonSchemaRef(ref, rootSchema) {
+  if (!ref || !ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  let current = rootSchema;
+  for (const part of parts) {
+    current = current?.[part];
+  }
+  return current ?? null;
+}
+
 function parseArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i++) {

package/src/cli/validate-content.mjs

@@ -53,8 +53,10 @@ async function validateContent(options) {
   const registry = JSON.parse(registryRaw);
 
   // Build schema map: component name → JSON Schema object
+  // Build nested blocks map: component name → array of { path, allow? }
   const schemaMap = new Map();
   const knownComponents = new Set();
+  const nestedBlocksMap = new Map();
   for (const component of registry.components) {
     knownComponents.add(component.name);
     if (component.schemaFile) {
@@ -62,6 +64,9 @@ async function validateContent(options) {
       const schemaRaw = await readFile(schemaPath, 'utf-8');
       schemaMap.set(component.name, JSON.parse(schemaRaw));
     }
+    if (Array.isArray(component.nestedBlocks) && component.nestedBlocks.length > 0) {
+      nestedBlocksMap.set(component.name, component.nestedBlocks);
+    }
   }
 
   // Find all compiled route files
@@ -128,6 +133,19 @@ async function validateContent(options) {
           message: issue.message,
         });
       }
+
+      // Recursively validate nested blocks (blockRef patterns)
+      const nestedIssues = validateNestedBlocks(
+        block.component, props, knownComponents, schemaMap, nestedBlocksMap,
+      );
+      for (const issue of nestedIssues) {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          component: block.component,
+          ...issue,
+        });
+      }
     }
   }
 
@@ -341,6 +359,86 @@ function resolveRef(ref, rootSchema) {
 // Content helpers
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Nested block validation — recursively validates blocks inside blockRef slots
+// ---------------------------------------------------------------------------
+
+function validateNestedBlocks(parentComponent, props, knownComponents, schemaMap, nestedBlocksMap) {
+  const issues = [];
+  // Find all block-shaped arrays in props by walking the data
+  const nestedBlocks = findNestedBlockArrays(props);
+  for (const { path: blockPath, blocks } of nestedBlocks) {
+    for (const [index, nestedBlock] of blocks.entries()) {
+      if (!nestedBlock || typeof nestedBlock !== 'object') continue;
+      const childComponent = nestedBlock.component;
+      if (!childComponent || typeof childComponent !== 'string') continue;
+
+      const nestedPath = `${blockPath}[${index}]`;
+
+      // Check nested component exists in registry
+      if (!knownComponents.has(childComponent)) {
+        issues.push({
+          path: `${nestedPath}.component`,
+          message: `${parentComponent} → ${nestedPath}: unknown nested component "${childComponent}"`,
+        });
+        continue;
+      }
+
+      // Validate nested block's props against its own schema
+      const childSchema = schemaMap.get(childComponent);
+      if (!childSchema) continue;
+
+      const childProps = nestedBlock.props ?? {};
+      const childIssues = validateJsonSchema(childProps, childSchema, `${nestedPath}.props`);
+      for (const issue of childIssues) {
+        issues.push({
+          nestedComponent: childComponent,
+          path: issue.path,
+          message: `${parentComponent} → ${childComponent}: ${issue.message}`,
+        });
+      }
+
+      // Recurse further if the nested component itself has nested blocks
+      const deeperIssues = validateNestedBlocks(
+        childComponent, childProps, knownComponents, schemaMap, nestedBlocksMap,
+      );
+      issues.push(...deeperIssues);
+    }
+  }
+  return issues;
+}
+
+/**
+ * Walks a props object looking for arrays of block-shaped objects
+ * (objects with `component` + `props` fields).
+ */
+function findNestedBlockArrays(obj, prefix = 'props') {
+  const results = [];
+  if (!obj || typeof obj !== 'object') return results;
+
+  for (const [key, value] of Object.entries(obj)) {
+    const currentPath = `${prefix}.${key}`;
+    if (Array.isArray(value)) {
+      // Check if array contains block-shaped objects
+      const hasBlocks = value.some(
+        (item) => item && typeof item === 'object' && typeof item.component === 'string' && 'props' in item,
+      );
+      if (hasBlocks) {
+        results.push({ path: currentPath, blocks: value });
+      }
+      // Also recurse into array items that are objects (for nested structures like tabs[].blocks[])
+      for (const item of value) {
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          results.push(...findNestedBlockArrays(item, currentPath + '[]'));
+        }
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      results.push(...findNestedBlockArrays(value, currentPath));
+    }
+  }
+  return results;
+}
+
 function collectBlocks(pageData) {
   const blocks = [];
   if (pageData.regions && typeof pageData.regions === 'object') {

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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-#!/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;
-}