@sprig-and-prose/sprig-universe 0.4.1 → 0.4.2

package/src/universe/validator.js

@@ -0,0 +1,862 @@
+/**
+ * @fileoverview Scene file source validator
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname, join, relative } from 'path';
+import { glob } from 'glob';
+import { parse as parseYaml } from 'yaml';
+import { validateMysqlSource, closeAllConnections as closeMysqlConnections } from '../validators/mysql/validator.js';
+
+/**
+ * @typedef {Object} ValidationError
+ * @property {string} actorName - Name of the actor
+ * @property {string} sourceKind - "file"
+ * @property {string} path - File path that failed (legacy, kept for compatibility)
+ * @property {string} message - Error message (legacy, kept for compatibility)
+ * @property {Object} [location] - Source location (legacy, kept for compatibility)
+ * @property {string} [hint] - Optional hint for fixing the error
+ * @property {string} [fieldName] - Field name if applicable, or "<root>" for shape errors
+ * @property {string} errorKind - Error kind: enum, typeMismatch, missingRequired, identityDuplicate, shapeMismatch, parseError, fileNotFound, etc.
+ * @property {'error'|'warning'|'info'} [severity] - Severity level: 'error' (default), 'warning', or 'info'
+ * @property {string|Object} [expected] - Expected value or type
+ * @property {string|Object} [actual] - Actual value or type
+ * @property {Object} schemaLocation - Where the rule is defined (file, start, end)
+ * @property {Object} occurrence - Where the failing data is
+ * @property {string} occurrence.dataFile - File path (absolute or repo-relative)
+ * @property {number|null} occurrence.recordIndex - Record index (null for shape-level errors)
+ * @property {string} [occurrence.dataPath] - Optional JSON-pointer path like "/tools/3/tier"
+ */
+
+/**
+ * @typedef {Object} ValidationReport
+ * @property {number} totalActors - Total actors validated
+ * @property {number} totalFiles - Total files validated
+ * @property {number} totalErrors - Total errors found
+ * @property {ValidationError[]} errors - Array of validation errors
+ */
+
+/**
+ * Validates a value against a type AST
+ * @param {any} value - Value to validate
+ * @param {Object} typeAst - Type AST from manifest
+ * @param {string} [dataPath] - Optional JSON-pointer path for nested errors
+ * @param {Map<string, Object>} [actorMap] - Optional map of actor names to actor definitions for reference validation
+ * @returns {{ errorKind: string, expected: string, actual: string, dataPath?: string, fieldLocation?: Object }|null} Error info or null if valid
+ */
+function validateValueAgainstType(value, typeAst, dataPath = '', actorMap = null) {
+  if (!typeAst || typeAst.kind === 'unknown') {
+    return null; // Skip unknown types
+  }
+
+  switch (typeAst.kind) {
+    case 'primitive':
+      const primitiveError = validatePrimitive(value, typeAst.name);
+      if (primitiveError) {
+        return {
+          errorKind: 'typeMismatch',
+          expected: typeAst.name,
+          actual: typeof value,
+          dataPath: dataPath || undefined,
+        };
+      }
+      return null;
+    case 'optional':
+      if (value === null || value === undefined) {
+        return null; // Optional values can be null/undefined
+      }
+      return validateValueAgainstType(value, typeAst.of, dataPath, actorMap);
+    case 'array':
+      if (!Array.isArray(value)) {
+        return {
+          errorKind: 'typeMismatch',
+          expected: 'array',
+          actual: typeof value,
+          dataPath: dataPath || undefined,
+        };
+      }
+      for (let i = 0; i < value.length; i++) {
+        const elementPath = dataPath ? `${dataPath}/${i}` : `/${i}`;
+        const error = validateValueAgainstType(value[i], typeAst.elementType, elementPath, actorMap);
+        if (error) {
+          return error;
+        }
+      }
+      return null;
+    case 'oneOf':
+      if (!typeAst.values.includes(value)) {
+        return {
+          errorKind: 'enum',
+          expected: `one of: ${typeAst.values.map((v) => JSON.stringify(v)).join(', ')}`,
+          actual: JSON.stringify(value),
+          dataPath: dataPath || undefined,
+        };
+      }
+      // Also validate base type
+      if (typeAst.valueType === 'string' && typeof value !== 'string') {
+        return {
+          errorKind: 'typeMismatch',
+          expected: 'string',
+          actual: typeof value,
+          dataPath: dataPath || undefined,
+        };
+      }
+      if (typeAst.valueType === 'number' && typeof value !== 'number') {
+        return {
+          errorKind: 'typeMismatch',
+          expected: 'number',
+          actual: typeof value,
+          dataPath: dataPath || undefined,
+        };
+      }
+      return null;
+    case 'reference':
+      // Validate against the referenced actor's type definition
+      if (!actorMap || !typeAst.name) {
+        return null; // Skip if no actor map or no name
+      }
+      
+      const referencedActor = actorMap.get(typeAst.name);
+      if (!referencedActor || !referencedActor.type || !referencedActor.type.fields) {
+        return null; // Skip if referenced actor not found or has no type definition
+      }
+      
+      // Validate that value is an object
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {
+          errorKind: 'typeMismatch',
+          expected: 'object',
+          actual: Array.isArray(value) ? 'array' : typeof value,
+          dataPath: dataPath || undefined,
+        };
+      }
+      
+      // Validate each field in the referenced actor's type
+      for (const field of referencedActor.type.fields) {
+        if (field.required && !(field.name in value)) {
+          return {
+            errorKind: 'missingRequired',
+            expected: `field '${field.name}'`,
+            actual: 'field missing',
+            dataPath: dataPath || undefined,
+            fieldLocation: field.location || undefined,
+          };
+        }
+        
+        if (field.name in value) {
+          const fieldValue = value[field.name];
+          const fieldPath = dataPath ? `${dataPath}/${field.name}` : `/${field.name}`;
+          const fieldError = validateValueAgainstType(fieldValue, field.type, fieldPath, actorMap);
+          if (fieldError) {
+            // If the error doesn't have a fieldLocation but this field does, add it
+            if (!fieldError.fieldLocation && field.location) {
+              fieldError.fieldLocation = field.location;
+            }
+            return fieldError;
+          }
+        }
+      }
+      
+      return null;
+    default:
+      return null; // Unknown type kind, skip
+  }
+}
+
+/**
+ * Validates a primitive value
+ * @param {any} value - Value to validate
+ * @param {string} typeName - Primitive type name
+ * @returns {string|null} Error message or null if valid
+ */
+function validatePrimitive(value, typeName) {
+  switch (typeName) {
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return `Expected integer, got ${typeof value}`;
+      }
+      return null;
+    case 'string':
+      if (typeof value !== 'string') {
+        return `Expected string, got ${typeof value}`;
+      }
+      return null;
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        return `Expected boolean, got ${typeof value}`;
+      }
+      return null;
+    case 'number':
+    case 'float':
+    case 'double':
+      if (typeof value !== 'number') {
+        return `Expected number, got ${typeof value}`;
+      }
+      return null;
+    default:
+      return null; // Unknown primitive, skip validation
+  }
+}
+
+/**
+ * Resolves file paths from glob patterns
+ * Paths are relative to repo root, even if they start with /
+ * @param {string[]} patterns - Array of glob patterns
+ * @param {string} repoRoot - Repository root directory
+ * @returns {string[]} Resolved file paths (sorted)
+ */
+async function resolveFilePaths(patterns, repoRoot) {
+  const allFiles = [];
+  for (const pattern of patterns) {
+    // If pattern starts with /, treat it as relative to repo root (not absolute)
+    // This is common in config files where /data means repo-root/data
+    const normalizedPattern = pattern.startsWith('/') ? pattern.slice(1) : pattern;
+    const resolvedPattern = resolve(repoRoot, normalizedPattern);
+    const files = await glob(resolvedPattern, { absolute: true });
+    allFiles.push(...files);
+  }
+  // Sort for deterministic ordering
+  return allFiles.sort();
+}
+
+/**
+ * Parses a file based on format
+ * @param {string} filePath - Path to file
+ * @param {string} format - File format ('yaml', 'json', etc.)
+ * @returns {any} Parsed content
+ * @throws {Error} If parsing fails
+ */
+function parseFile(filePath, format) {
+  const content = readFileSync(filePath, 'utf-8');
+  
+  switch (format) {
+    case 'yaml':
+    case 'yml':
+      try {
+        return parseYaml(content);
+      } catch (error) {
+        throw new Error(`Failed to parse YAML: ${error.message}`);
+      }
+    case 'json':
+      try {
+        return JSON.parse(content);
+      } catch (error) {
+        throw new Error(`Failed to parse JSON: ${error.message}`);
+      }
+    default:
+      throw new Error(`Unsupported format: ${format}`);
+  }
+}
+
+/**
+ * Validates shape of parsed data
+ * @param {any} data - Parsed data
+ * @param {string} shape - Expected shape ('list' or 'record')
+ * @returns {string|null} Error message or null if valid
+ */
+function validateShape(data, shape) {
+  if (shape === 'list') {
+    if (!Array.isArray(data)) {
+      return `Shape is 'list' but root is not an array (got ${typeof data})`;
+    }
+    return null;
+  } else if (shape === 'record') {
+    if (Array.isArray(data)) {
+      return `Shape is 'record' but root is an array; change shape to { list } or change the file`;
+    }
+    if (typeof data !== 'object' || data === null) {
+      return `Shape is 'record' but root is not an object (got ${typeof data})`;
+    }
+    return null;
+  }
+  return null; // Unknown shape, skip validation
+}
+
+/**
+ * Extracts identity field name from identity AST
+ * @param {string} identityAst - Raw identity AST string
+ * @returns {string|null} Field name or null if not parseable
+ */
+function extractIdentityField(identityAst) {
+  if (!identityAst) return null;
+  const trimmed = identityAst.trim();
+  // Simple case: single identifier
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed)) {
+    return trimmed;
+  }
+  // For now, only support single-field identities
+  return null;
+}
+
+/**
+ * Validates a file source for an actor
+ * @param {Object} actor - Actor from manifest
+ * @param {Object} fileSource - File source block from manifest
+ * @param {string} repoRoot - Repository root directory (fallback if no repository specified)
+ * @param {Object} repositories - Repository configuration from config
+ * @param {Map<string, Object>} [actorMap] - Optional map of actor names to actor definitions for reference validation
+ * @returns {ValidationError[]} Array of validation errors
+ */
+async function validateFileSource(actor, fileSource, repoRoot, repositories = {}, actorMap = null) {
+  const errors = [];
+  
+  // Extract source configuration
+  const paths = fileSource.paths || [];
+  const format = fileSource.format || 'yaml';
+  const shape = fileSource.shape || 'list';
+  const repository = fileSource.repository;
+  const sourceLocation = fileSource.location;
+  
+  if (paths.length === 0) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'file',
+      path: '<no paths specified>',
+      message: 'File source has no paths specified',
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'configError',
+      expected: 'paths array with at least one pattern',
+      actual: 'empty or missing paths',
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: '<no paths specified>',
+        recordIndex: null,
+      },
+    });
+    return errors;
+  }
+  
+  // Determine base path: use repository localPath if specified, otherwise use repoRoot
+  let basePath = repoRoot;
+  if (repository) {
+    const repoConfig = repositories[repository];
+    if (repoConfig && repoConfig.localPath) {
+      basePath = repoConfig.localPath;
+    } else {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'file',
+        path: paths.join(', '),
+        message: `Repository '${repository}' not found in config or missing localPath`,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'configError',
+        expected: `repository '${repository}' with localPath`,
+        actual: 'repository not found or missing localPath',
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: paths.join(', '),
+          recordIndex: null,
+        },
+        hint: `Add '${repository}' to repositories section in sprig.config.json with a localPath`,
+      });
+      return errors;
+    }
+  }
+  
+  // Resolve file paths
+  let filePaths;
+  try {
+    filePaths = await resolveFilePaths(paths, basePath);
+  } catch (error) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'file',
+      path: paths.join(', '),
+      message: `Failed to resolve file paths: ${error.message}`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'configError',
+      expected: 'valid glob patterns',
+      actual: `error: ${error.message}`,
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: paths.join(', '),
+        recordIndex: null,
+      },
+    });
+    return errors;
+  }
+  
+  if (filePaths.length === 0) {
+    errors.push({
+      actorName: actor.name,
+      sourceKind: 'file',
+      path: paths.join(', '),
+      message: `No files found matching paths: ${paths.join(', ')}`,
+      location: sourceLocation,
+      fieldName: '<root>',
+      errorKind: 'fileNotFound',
+      expected: 'at least one matching file',
+      actual: '0 files found',
+      schemaLocation: sourceLocation || actor.location,
+      occurrence: {
+        dataFile: paths.join(', '),
+        recordIndex: null,
+      },
+      hint: 'Check that the glob patterns match existing files',
+    });
+    return errors;
+  }
+  
+  // Get actor type fields
+  const typeFields = actor.type?.fields || [];
+  const fieldsByName = new Map();
+  for (const field of typeFields) {
+    fieldsByName.set(field.name, field);
+  }
+  
+  // Extract identity field
+  const identityField = actor.identity
+    ? extractIdentityField(actor.identity.ast)
+    : null;
+  
+  // Track identity values for uniqueness check
+  const identityValues = new Map(); // value -> { file, recordIndex }
+  
+  // Try to get repo-relative path for display
+  let repoRelativeBase = repoRoot;
+  if (repository) {
+    const repoConfig = repositories[repository];
+    if (repoConfig && repoConfig.localPath) {
+      repoRelativeBase = repoConfig.localPath;
+    }
+  }
+
+  // Validate each file
+  for (const filePath of filePaths) {
+    // Try to make path repo-relative for display
+    let displayPath = filePath;
+    try {
+      displayPath = relative(repoRelativeBase, filePath);
+    } catch {
+      // If relative fails, use absolute path
+      displayPath = filePath;
+    }
+
+    if (!existsSync(filePath)) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'file',
+        path: filePath,
+        message: `File does not exist`,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'fileNotFound',
+        expected: 'file exists',
+        actual: 'file not found',
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: displayPath,
+          recordIndex: null,
+        },
+      });
+      continue;
+    }
+    
+    // Parse file
+    let data;
+    try {
+      data = parseFile(filePath, format);
+    } catch (error) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'file',
+        path: filePath,
+        message: `Failed to parse ${format} file: ${error.message}`,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'parseError',
+        expected: `valid ${format} file`,
+        actual: `parse error: ${error.message}`,
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: displayPath,
+          recordIndex: null,
+        },
+      });
+      continue;
+    }
+    
+    // Validate shape
+    const shapeError = validateShape(data, shape);
+    if (shapeError) {
+      errors.push({
+        actorName: actor.name,
+        sourceKind: 'file',
+        path: filePath,
+        message: shapeError,
+        location: sourceLocation,
+        fieldName: '<root>',
+        errorKind: 'shapeMismatch',
+        expected: shape === 'list' ? 'array' : 'object',
+        actual: Array.isArray(data) ? 'array' : typeof data,
+        schemaLocation: sourceLocation || actor.location,
+        occurrence: {
+          dataFile: displayPath,
+          recordIndex: null,
+        },
+        hint: shape === 'list'
+          ? "Change shape to { record } or ensure the file contains an array"
+          : "Change shape to { list } or ensure the file contains a single object",
+      });
+      continue;
+    }
+    
+    // Get records based on shape
+    const records = shape === 'list' ? data : [data];
+    
+    // Validate each record
+    for (let recordIndex = 0; recordIndex < records.length; recordIndex++) {
+      const record = records[recordIndex];
+      
+      if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+        errors.push({
+          actorName: actor.name,
+          sourceKind: 'file',
+          path: filePath,
+          message: `Record at index ${recordIndex} is not an object`,
+          location: fieldsByName.get(typeFields[0]?.name)?.location || sourceLocation,
+          fieldName: '<root>',
+          errorKind: 'typeMismatch',
+          expected: 'object',
+          actual: Array.isArray(record) ? 'array' : typeof record,
+          schemaLocation: sourceLocation || actor.location,
+          occurrence: {
+            dataFile: displayPath,
+            recordIndex,
+          },
+        });
+        continue;
+      }
+      
+      // Validate required fields
+      for (const field of typeFields) {
+        if (field.required && !(field.name in record)) {
+          errors.push({
+            actorName: actor.name,
+            sourceKind: 'file',
+            path: filePath,
+            message: `Missing required field '${field.name}' in record at index ${recordIndex}`,
+            location: field.location || sourceLocation,
+            fieldName: field.name,
+            errorKind: 'missingRequired',
+            expected: `field '${field.name}' (${field.typeExpr || 'required'})`,
+            actual: 'field missing',
+            schemaLocation: field.location || sourceLocation || actor.location,
+            occurrence: {
+              dataFile: displayPath,
+              recordIndex,
+            },
+          });
+        }
+        
+        // Validate field type if present
+        if (field.name in record) {
+          const value = record[field.name];
+          
+          // Handle nested object types
+          if (field.type && field.type.kind === 'object' && field.type.nested) {
+            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+              errors.push({
+                actorName: actor.name,
+                sourceKind: 'file',
+                path: filePath,
+                message: `Field '${field.name}' in record at index ${recordIndex}: Expected object, got ${Array.isArray(value) ? 'array' : typeof value}`,
+                location: field.location || sourceLocation,
+                fieldName: field.name,
+                errorKind: 'typeMismatch',
+                expected: 'object',
+                actual: Array.isArray(value) ? 'array' : typeof value,
+                schemaLocation: field.location || sourceLocation || actor.location,
+                occurrence: {
+                  dataFile: displayPath,
+                  recordIndex,
+                },
+              });
+            } else {
+              // Validate nested object fields if they exist
+              if (field.nestedFields && Array.isArray(field.nestedFields)) {
+                const nestedObject = value;
+                
+                // Validate required nested fields
+                for (const nestedField of field.nestedFields) {
+                  if (nestedField.required && !(nestedField.name in nestedObject)) {
+                    errors.push({
+                      actorName: actor.name,
+                      sourceKind: 'file',
+                      path: filePath,
+                      message: `Field '${field.name}.${nestedField.name}' in record at index ${recordIndex}: Missing required nested field`,
+                      location: nestedField.location || field.location || sourceLocation,
+                      fieldName: `${field.name}.${nestedField.name}`,
+                      errorKind: 'missingRequired',
+                      expected: `field '${nestedField.name}' (${nestedField.typeExpr || 'required'})`,
+                      actual: 'field missing',
+                      schemaLocation: nestedField.location || field.location || sourceLocation || actor.location,
+                      occurrence: {
+                        dataFile: displayPath,
+                        recordIndex,
+                        dataPath: `/${field.name}`,
+                      },
+                    });
+                  }
+                  
+                  // Validate nested field type if present
+                  if (nestedField.name in nestedObject) {
+                    const nestedValue = nestedObject[nestedField.name];
+                    
+                    // Handle nested objects recursively
+                    if (nestedField.type && nestedField.type.kind === 'object' && nestedField.type.nested) {
+                      if (typeof nestedValue !== 'object' || nestedValue === null || Array.isArray(nestedValue)) {
+                        errors.push({
+                          actorName: actor.name,
+                          sourceKind: 'file',
+                          path: filePath,
+                          message: `Field '${field.name}.${nestedField.name}' in record at index ${recordIndex}: Expected object, got ${Array.isArray(nestedValue) ? 'array' : typeof nestedValue}`,
+                          location: nestedField.location || field.location || sourceLocation,
+                          fieldName: `${field.name}.${nestedField.name}`,
+                          errorKind: 'typeMismatch',
+                          expected: 'object',
+                          actual: Array.isArray(nestedValue) ? 'array' : typeof nestedValue,
+                          schemaLocation: nestedField.location || field.location || sourceLocation || actor.location,
+                          occurrence: {
+                            dataFile: displayPath,
+                            recordIndex,
+                            dataPath: `/${field.name}/${nestedField.name}`,
+                          },
+                        });
+                      }
+                      // Could recurse further if needed, but for now stop at 2 levels
+                    } else {
+                      // Standard type validation for nested field
+                      const typeError = validateValueAgainstType(nestedValue, nestedField.type, `/${field.name}/${nestedField.name}`, actorMap);
+                      if (typeError) {
+                        errors.push({
+                          actorName: actor.name,
+                          sourceKind: 'file',
+                          path: filePath,
+                          message: `Field '${field.name}.${nestedField.name}' in record at index ${recordIndex}: ${typeError.errorKind === 'enum' ? `Value "${nestedValue}" is not one of: ${typeError.expected}` : `${typeError.expected} expected, got ${typeError.actual}`}`,
+                          location: nestedField.location || field.location || sourceLocation,
+                          fieldName: `${field.name}.${nestedField.name}`,
+                          errorKind: typeError.errorKind,
+                          expected: typeError.expected,
+                          actual: typeError.actual,
+                          schemaLocation: nestedField.location || field.location || sourceLocation || actor.location,
+                          occurrence: {
+                            dataFile: displayPath,
+                            recordIndex,
+                            dataPath: typeError.dataPath || `/${field.name}/${nestedField.name}`,
+                          },
+                        });
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          } else {
+            // Standard type validation
+            const typeError = validateValueAgainstType(value, field.type, '', actorMap);
+            if (typeError) {
+              // Use the referenced field's location if available (for reference type validation)
+              const errorFieldLocation = typeError.fieldLocation || field.location;
+              errors.push({
+                actorName: actor.name,
+                sourceKind: 'file',
+                path: filePath,
+                message: `Field '${field.name}' in record at index ${recordIndex}: ${typeError.errorKind === 'enum' ? `Value "${value}" is not one of: ${typeError.expected}` : `${typeError.expected} expected, got ${typeError.actual}`}`,
+                location: errorFieldLocation || sourceLocation,
+                fieldName: field.name,
+                errorKind: typeError.errorKind,
+                expected: typeError.expected,
+                actual: typeError.actual,
+                schemaLocation: errorFieldLocation || sourceLocation || actor.location,
+                occurrence: {
+                  dataFile: displayPath,
+                  recordIndex,
+                  dataPath: typeError.dataPath,
+                },
+              });
+            }
+          }
+        }
+      }
+      
+      // Check identity field
+      if (identityField) {
+        const identityFieldDef = fieldsByName.get(identityField);
+        if (!identityFieldDef) {
+          // Identity field doesn't exist in type - this is a configuration error
+          // but we'll skip it for now as per requirements
+        } else {
+          // Identity field must be present (even if type is optional)
+          if (!(identityField in record)) {
+            errors.push({
+              actorName: actor.name,
+              sourceKind: 'file',
+              path: filePath,
+              message: `Missing identity field '${identityField}' in record at index ${recordIndex} (identity fields are required)`,
+              location: identityFieldDef.location || sourceLocation,
+              fieldName: identityField,
+              errorKind: 'missingRequired',
+              expected: `identity field '${identityField}'`,
+              actual: 'field missing',
+              schemaLocation: actor.identity?.location || identityFieldDef.location || actor.location,
+              occurrence: {
+                dataFile: displayPath,
+                recordIndex,
+              },
+            });
+          } else {
+            const identityValue = record[identityField];
+            // Check uniqueness
+            const identityKey = String(identityValue);
+            if (identityValues.has(identityKey)) {
+              const existing = identityValues.get(identityKey);
+              // Use relative paths for better readability
+              let relativeExisting;
+              try {
+                relativeExisting = relative(repoRelativeBase, existing.file);
+              } catch {
+                // If relative fails, use absolute path
+                relativeExisting = existing.file;
+              }
+              errors.push({
+                actorName: actor.name,
+                sourceKind: 'file',
+                path: filePath,
+                message: `Duplicate identity value '${identityValue}' for field '${identityField}' (already exists in ${relativeExisting} at index ${existing.recordIndex})`,
+                location: identityFieldDef.location || sourceLocation,
+                fieldName: identityField,
+                errorKind: 'identityDuplicate',
+                expected: 'unique value',
+                actual: `duplicate of value '${identityValue}'`,
+                schemaLocation: actor.identity?.location || identityFieldDef.location || actor.location,
+                occurrence: {
+                  dataFile: displayPath,
+                  recordIndex,
+                },
+                hint: 'Identity fields must be unique across all files for this actor',
+              });
+            } else {
+              identityValues.set(identityKey, { file: filePath, recordIndex });
+            }
+          }
+        }
+      }
+    }
+  }
+  
+  return errors;
+}
+
+/**
+ * Validates scenes from a manifest
+ * @param {Object} config - Config object from sprig.config.json
+ * @param {Object} scenesManifest - Scenes manifest JSON
+ * @param {string} configPath - Path to config file (for resolving repo root)
+ * @returns {ValidationReport}
+ */
+export async function validateScenes(config, scenesManifest, configPath) {
+  const repoRoot = dirname(configPath);
+  const repositories = config.repositories || {};
+  const errors = [];
+  let totalActors = 0;
+  let totalFiles = 0;
+  
+  if (!scenesManifest.scenes || !Array.isArray(scenesManifest.scenes)) {
+    return {
+      totalActors: 0,
+      totalFiles: 0,
+      totalErrors: 0,
+      errors: [],
+    };
+  }
+  
+  // Collect all file paths we'll validate (for counting)
+  const filePathsSet = new Set();
+  
+  const connections = config.connections || {};
+
+  // Build a map of actor names to actor definitions for reference validation
+  const actorMap = new Map();
+  for (const scene of scenesManifest.scenes) {
+    if (!scene.actors || !Array.isArray(scene.actors)) {
+      continue;
+    }
+    for (const actor of scene.actors) {
+      actorMap.set(actor.name, actor);
+    }
+  }
+
+  for (const scene of scenesManifest.scenes) {
+    if (!scene.actors || !Array.isArray(scene.actors)) {
+      continue;
+    }
+    
+    for (const actor of scene.actors) {
+      // Validate file sources
+      if (actor.sources && actor.sources.file) {
+        totalActors++;
+        
+        // Handle both single file source and array of file sources
+        const fileSources = Array.isArray(actor.sources.file)
+          ? actor.sources.file
+          : [actor.sources.file];
+        
+        for (const fileSource of fileSources) {
+          const sourcePaths = fileSource.paths || [];
+          if (sourcePaths.length > 0) {
+            // Determine base path for counting
+            let basePath = repoRoot;
+            if (fileSource.repository) {
+              const repoConfig = repositories[fileSource.repository];
+              if (repoConfig && repoConfig.localPath) {
+                basePath = repoConfig.localPath;
+              }
+            }
+            
+            // Resolve paths to count files
+            try {
+              const resolvedPaths = await resolveFilePaths(sourcePaths, basePath);
+              resolvedPaths.forEach((p) => filePathsSet.add(p));
+              totalFiles += resolvedPaths.length;
+            } catch {
+              // Will be caught in validation
+            }
+          }
+          
+          const sourceErrors = await validateFileSource(actor, fileSource, repoRoot, repositories, actorMap);
+          errors.push(...sourceErrors);
+        }
+      }
+
+      // Validate MySQL sources
+      if (actor.sources && actor.sources.mysql) {
+        totalActors++;
+        
+        // Handle both single mysql source and array of mysql sources
+        const mysqlSources = Array.isArray(actor.sources.mysql)
+          ? actor.sources.mysql
+          : [actor.sources.mysql];
+        
+        for (const mysqlSource of mysqlSources) {
+          const sourceErrors = await validateMysqlSource(actor, mysqlSource, connections);
+          errors.push(...sourceErrors);
+        }
+      }
+    }
+  }
+
+  // Close all MySQL connections after validation
+  await closeMysqlConnections();
+  
+  return {
+    totalActors,
+    totalFiles: filePathsSet.size,
+    totalErrors: errors.length,
+    errors,
+  };
+}
+