meno-core 1.0.0

package/lib/shared/validation/propValidator.ts

@@ -0,0 +1,238 @@
+/**
+ * Prop Validator
+ * Validates component props against their interface definitions
+ * Provides type checking and coercion for runtime safety
+ */
+
+import type { PropDefinition } from '../types/components';
+import { isI18nValue } from '../i18n';
+
+/**
+ * Validation error with context
+ */
+export interface ValidationError {
+  propName: string;
+  message: string;
+  receivedValue: unknown;
+  expectedType: string;
+}
+
+/**
+ * Validation result
+ */
+export type PropValidationResult =
+  | { valid: true; props: Record<string, unknown> }
+  | { valid: false; errors: ValidationError[]; props: Record<string, unknown> };
+
+/**
+ * Coerce a value to the expected type if safe
+ * Returns the coerced value or undefined if coercion is not safe
+ * Note: i18n values are passed through unchanged for later resolution
+ */
+function coerceValue(value: unknown, expectedType: PropDefinition['type']): unknown {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+
+  // Pass through i18n values unchanged - they will be resolved later by resolveI18nInProps
+  if (isI18nValue(value)) {
+    return value;
+  }
+
+  switch (expectedType) {
+    case 'string':
+      return String(value);
+    
+    case 'number':
+      if (typeof value === 'number') {
+        return value;
+      }
+      if (typeof value === 'string') {
+        const num = Number(value);
+        if (!isNaN(num) && isFinite(num)) {
+          return num;
+        }
+      }
+      return undefined;
+    
+    case 'boolean':
+      if (typeof value === 'boolean') {
+        return value;
+      }
+      if (typeof value === 'string') {
+        const lower = value.toLowerCase();
+        if (lower === 'true' || lower === '1') {
+          return true;
+        }
+        if (lower === 'false' || lower === '0') {
+          return false;
+        }
+      }
+      if (typeof value === 'number') {
+        return value !== 0;
+      }
+      return undefined;
+    
+    case 'select':
+      return String(value);
+    
+    default:
+      return value;
+  }
+}
+
+/**
+ * Validate a single prop value against its definition
+ */
+function validateSingleProp(
+  propName: string,
+  propDef: PropDefinition,
+  value: unknown
+): { valid: boolean; error?: ValidationError; coercedValue?: unknown } {
+  // If value is undefined, it's valid (will use default)
+  if (value === undefined) {
+    return { valid: true };
+  }
+
+  const { type, options } = propDef;
+
+  // Type checking and coercion
+  let coercedValue: unknown;
+  let typeValid = false;
+
+  switch (type) {
+    case 'string':
+      coercedValue = coerceValue(value, 'string');
+      // Accept both strings and i18n values (i18n values will be resolved later)
+      typeValid = typeof coercedValue === 'string' || isI18nValue(coercedValue);
+      break;
+
+    case 'number':
+      coercedValue = coerceValue(value, 'number');
+      typeValid = typeof coercedValue === 'number';
+      break;
+
+    case 'boolean':
+      coercedValue = coerceValue(value, 'boolean');
+      typeValid = typeof coercedValue === 'boolean';
+      break;
+
+    case 'select':
+      coercedValue = coerceValue(value, 'select');
+      typeValid = typeof coercedValue === 'string';
+      if (typeValid && options) {
+        // Validate against allowed options
+        if (!options.includes(coercedValue as string)) {
+          return {
+            valid: false,
+            error: {
+              propName,
+              message: `Value "${coercedValue}" is not in allowed options: ${options.join(', ')}`,
+              receivedValue: value,
+              expectedType: `select(${options.join('|')})`,
+            },
+          };
+        }
+      }
+      break;
+
+    case 'link':
+      // Link type expects an object with href (and optional target)
+      if (typeof value === 'object' && value !== null && 'href' in value) {
+        coercedValue = value;
+        typeValid = true;
+      } else {
+        typeValid = false;
+      }
+      break;
+
+    default:
+      return {
+        valid: false,
+        error: {
+          propName,
+          message: `Unknown prop type: ${type}`,
+          receivedValue: value,
+          expectedType: type,
+        },
+      };
+  }
+
+  if (!typeValid) {
+    return {
+      valid: false,
+      error: {
+        propName,
+        message: `Expected ${type}, got ${typeof value}`,
+        receivedValue: value,
+        expectedType: type,
+      },
+    };
+  }
+
+  return { valid: true, coercedValue };
+}
+
+/**
+ * Validate component props against their interface definition
+ * 
+ * @param propDefs - Component interface definition (prop name -> PropDefinition)
+ * @param passedProps - Props passed to the component instance
+ * @returns Validation result with validated/coerced props and any errors
+ * 
+ * @example
+ * ```typescript
+ * const result = validateComponentProps(
+ *   { title: { type: 'string', default: 'Hello' } },
+ *   { title: 'World', count: 123 }
+ * );
+ * if (result.valid) {
+ *   console.log(result.props); // { title: 'World', count: 123 }
+ * }
+ * ```
+ */
+export function validateComponentProps(
+  propDefs: Record<string, PropDefinition>,
+  passedProps: Record<string, unknown>
+): PropValidationResult {
+  const errors: ValidationError[] = [];
+  const validatedProps: Record<string, unknown> = {};
+
+  // Validate props defined in interface
+  for (const [propName, propDef] of Object.entries(propDefs)) {
+    const value = passedProps[propName];
+    const validation = validateSingleProp(propName, propDef, value);
+
+    if (validation.valid) {
+      // Use coerced value if available, otherwise use original or default
+      validatedProps[propName] = validation.coercedValue !== undefined
+        ? validation.coercedValue
+        : (value !== undefined ? value : propDef.default);
+    } else {
+      // Validation failed - log error but use default if available (backward compatibility)
+      if (validation.error) {
+        errors.push(validation.error);
+      }
+      // Use default value if available, otherwise use original value (graceful degradation)
+      validatedProps[propName] = propDef.default !== undefined
+        ? propDef.default
+        : value;
+    }
+  }
+
+  // Preserve unknown props for backward compatibility (but log warnings)
+  for (const [propName, value] of Object.entries(passedProps)) {
+    if (!(propName in propDefs)) {
+      // Unknown prop - preserve it but log a warning (backward compatibility)
+      validatedProps[propName] = value;
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors, props: validatedProps };
+  }
+
+  return { valid: true, props: validatedProps };
+}
+
+

package/lib/shared/validation/schemas.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Schema Validation Tests
+ * Critical path tests for zod schema validation
+ */
+
+import { describe, test, expect } from 'bun:test';
+import {
+  PropDefinitionSchema,
+  ComponentNodeSchema,
+  ComponentDefinitionSchema,
+  PageDataSchema,
+} from './schemas';
+
+describe('Schema Validation', () => {
+  describe('Valid component definitions pass', () => {
+    test('valid prop definition', () => {
+      const propDef = {
+        type: 'string',
+        default: 'Hello',
+      };
+      
+      const result = PropDefinitionSchema.safeParse(propDef);
+      
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.type).toBe('string');
+        expect(result.data.default).toBe('Hello');
+      }
+    });
+
+    test('valid select prop definition', () => {
+      const propDef = {
+        type: 'select',
+        default: 'primary',
+        options: ['primary', 'secondary'],
+      };
+      
+      const result = PropDefinitionSchema.safeParse(propDef);
+      
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.type).toBe('select');
+        expect(result.data.options).toEqual(['primary', 'secondary']);
+      }
+    });
+
+    test('valid component node', () => {
+      const node = {
+        type: 'node',
+        tag: 'div',
+        children: [],
+      };
+      
+      const result = ComponentNodeSchema.safeParse(node);
+      
+      expect(result.success).toBe(true);
+    });
+
+    test('valid component definition', () => {
+      const def = {
+        type: 'component',
+        component: {
+          interface: {
+            title: { type: 'string', default: 'Hello' },
+          },
+          structure: {
+            type: 'node',
+            tag: 'div',
+            children: [],
+          },
+        },
+      };
+      
+      const result = ComponentDefinitionSchema.safeParse(def);
+      
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Invalid structures caught', () => {
+    test('invalid prop type', () => {
+      const propDef = {
+        type: 'invalid-type',
+        default: 'Hello',
+      };
+      
+      const result = PropDefinitionSchema.safeParse(propDef);
+      
+      expect(result.success).toBe(false);
+    });
+
+    test('missing required node type', () => {
+      const node = {
+        tag: 'div',
+        children: [],
+      };
+      
+      const result = ComponentNodeSchema.safeParse(node);
+      
+      expect(result.success).toBe(false);
+    });
+
+    test('invalid component definition structure', () => {
+      const def = {
+        component: {
+          // Missing required structure
+        },
+      };
+      
+      const result = ComponentDefinitionSchema.safeParse(def);
+      
+      // Should fail or pass with passthrough (backward compatibility)
+      // The schema uses passthrough, so it might pass but log warnings
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('Missing required fields handled', () => {
+    test('prop definition without default', () => {
+      const propDef = {
+        type: 'string',
+      };
+      
+      const result = PropDefinitionSchema.safeParse(propDef);
+      
+      // Should pass (default is optional)
+      expect(result.success).toBe(true);
+    });
+
+    test('component node without children', () => {
+      const node = {
+        type: 'node',
+        tag: 'div',
+      };
+      
+      const result = ComponentNodeSchema.safeParse(node);
+      
+      // Should pass (children is optional)
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Unknown fields preserved (backward compatibility)', () => {
+    test('prop definition with unknown fields', () => {
+      const propDef = {
+        type: 'string',
+        default: 'Hello',
+        unknownField: 'preserved',
+      };
+      
+      const result = PropDefinitionSchema.safeParse(propDef);
+      
+      expect(result.success).toBe(true);
+      if (result.success) {
+        // Passthrough should preserve unknown fields
+        expect((propDef as any).unknownField).toBe('preserved');
+      }
+    });
+
+    test('component node with unknown fields', () => {
+      const node = {
+        type: 'node',
+        tag: 'div',
+        unknownField: 'preserved',
+        children: [],
+      };
+      
+      const result = ComponentNodeSchema.safeParse(node);
+      
+      expect(result.success).toBe(true);
+      // Passthrough preserves unknown fields
+      expect((node as any).unknownField).toBe('preserved');
+    });
+  });
+});
+
+