@originals/sdk 1.2.0 → 1.4.2

package/src/kinds/validators/DocumentValidator.ts

@@ -0,0 +1,311 @@
+/**
+ * Document Kind Validator
+ * 
+ * Validates manifests for text documents with formatting and sections.
+ */
+
+import { OriginalKind, type OriginalManifest, type ValidationResult, type DocumentMetadata } from '../types';
+import { BaseKindValidator, ValidationUtils } from './base';
+
+/**
+ * Valid document formats
+ */
+const VALID_FORMATS = ['markdown', 'html', 'pdf', 'docx', 'txt', 'asciidoc', 'rst', 'latex'];
+
+/**
+ * Valid document statuses
+ */
+const VALID_STATUSES = ['draft', 'review', 'published', 'archived'];
+
+/**
+ * Validator for Document Originals
+ */
+export class DocumentValidator extends BaseKindValidator<OriginalKind.Document> {
+  readonly kind = OriginalKind.Document;
+  
+  protected validateKind(manifest: OriginalManifest<OriginalKind.Document>): ValidationResult {
+    const errors: ValidationResult['errors'] = [];
+    const warnings: ValidationResult['warnings'] = [];
+    const metadata = manifest.metadata as DocumentMetadata;
+    
+    // Validate metadata exists
+    if (!metadata || typeof metadata !== 'object') {
+      return ValidationUtils.failure([
+        ValidationUtils.error('MISSING_METADATA', 'Document manifest must have metadata', 'metadata'),
+      ]);
+    }
+    
+    // Validate format (required)
+    if (!metadata.format) {
+      errors.push(ValidationUtils.error(
+        'MISSING_FORMAT',
+        'Document must specify a format',
+        'metadata.format',
+      ));
+    } else if (!VALID_FORMATS.includes(metadata.format)) {
+      errors.push(ValidationUtils.error(
+        'INVALID_FORMAT',
+        `Invalid document format: "${metadata.format}". Must be one of: ${VALID_FORMATS.join(', ')}`,
+        'metadata.format',
+        metadata.format,
+      ));
+    }
+    
+    // Validate content (required)
+    if (!metadata.content || typeof metadata.content !== 'string') {
+      errors.push(ValidationUtils.error(
+        'MISSING_CONTENT',
+        'Document must specify a content resource',
+        'metadata.content',
+      ));
+    } else {
+      // Check if content references an existing resource
+      if (!ValidationUtils.resourceExists(metadata.content, manifest.resources)) {
+        warnings.push(ValidationUtils.warning(
+          'CONTENT_NOT_RESOURCE',
+          `Content "${metadata.content}" does not match a resource ID`,
+          'metadata.content',
+          'Ensure the content field references a valid resource ID',
+        ));
+      }
+    }
+    
+    // Validate language if specified
+    if (metadata.language) {
+      if (typeof metadata.language !== 'string') {
+        errors.push(ValidationUtils.error(
+          'INVALID_LANGUAGE',
+          'Language must be a string',
+          'metadata.language',
+        ));
+      } else if (!ValidationUtils.isValidLanguageCode(metadata.language)) {
+        warnings.push(ValidationUtils.warning(
+          'INVALID_LANGUAGE_CODE',
+          `Language "${metadata.language}" is not a valid ISO 639-1 code`,
+          'metadata.language',
+          'Use a 2-letter language code like "en", "es", "fr"',
+        ));
+      }
+    }
+    
+    // Validate toc if specified
+    if (metadata.toc) {
+      if (!Array.isArray(metadata.toc)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_TOC',
+          'Table of contents must be an array',
+          'metadata.toc',
+        ));
+      } else {
+        for (let i = 0; i < metadata.toc.length; i++) {
+          const entry = metadata.toc[i];
+          const entryPath = `metadata.toc[${i}]`;
+          
+          if (!entry || typeof entry !== 'object') {
+            errors.push(ValidationUtils.error(
+              'INVALID_TOC_ENTRY',
+              `TOC entry at index ${i} must be an object`,
+              entryPath,
+            ));
+            continue;
+          }
+          
+          if (!entry.title || typeof entry.title !== 'string') {
+            errors.push(ValidationUtils.error(
+              'MISSING_TOC_TITLE',
+              `TOC entry at index ${i} must have a title`,
+              `${entryPath}.title`,
+            ));
+          }
+          
+          if (typeof entry.level !== 'number' || entry.level < 1 || !Number.isInteger(entry.level)) {
+            errors.push(ValidationUtils.error(
+              'INVALID_TOC_LEVEL',
+              `TOC entry at index ${i} must have a valid level (positive integer)`,
+              `${entryPath}.level`,
+            ));
+          }
+        }
+      }
+    }
+    
+    // Validate pageCount if specified
+    if (metadata.pageCount !== undefined) {
+      if (typeof metadata.pageCount !== 'number' || metadata.pageCount <= 0 || !Number.isInteger(metadata.pageCount)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_PAGE_COUNT',
+          'Page count must be a positive integer',
+          'metadata.pageCount',
+        ));
+      }
+    }
+    
+    // Validate wordCount if specified
+    if (metadata.wordCount !== undefined) {
+      if (typeof metadata.wordCount !== 'number' || metadata.wordCount < 0 || !Number.isInteger(metadata.wordCount)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_WORD_COUNT',
+          'Word count must be a non-negative integer',
+          'metadata.wordCount',
+        ));
+      }
+    }
+    
+    // Validate readingTime if specified
+    if (metadata.readingTime !== undefined) {
+      if (typeof metadata.readingTime !== 'number' || metadata.readingTime <= 0) {
+        errors.push(ValidationUtils.error(
+          'INVALID_READING_TIME',
+          'Reading time must be a positive number (minutes)',
+          'metadata.readingTime',
+        ));
+      }
+    }
+    
+    // Validate keywords if specified
+    if (metadata.keywords) {
+      if (!Array.isArray(metadata.keywords)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_KEYWORDS',
+          'Keywords must be an array of strings',
+          'metadata.keywords',
+        ));
+      } else {
+        for (let i = 0; i < metadata.keywords.length; i++) {
+          if (typeof metadata.keywords[i] !== 'string') {
+            errors.push(ValidationUtils.error(
+              'INVALID_KEYWORD',
+              `Keyword at index ${i} must be a string`,
+              `metadata.keywords[${i}]`,
+            ));
+          }
+        }
+      }
+    }
+    
+    // Validate references if specified
+    if (metadata.references) {
+      if (!Array.isArray(metadata.references)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_REFERENCES',
+          'References must be an array',
+          'metadata.references',
+        ));
+      } else {
+        const refIds = new Set<string>();
+        
+        for (let i = 0; i < metadata.references.length; i++) {
+          const ref = metadata.references[i];
+          const refPath = `metadata.references[${i}]`;
+          
+          if (!ref || typeof ref !== 'object') {
+            errors.push(ValidationUtils.error(
+              'INVALID_REFERENCE',
+              `Reference at index ${i} must be an object`,
+              refPath,
+            ));
+            continue;
+          }
+          
+          if (!ref.id || typeof ref.id !== 'string') {
+            errors.push(ValidationUtils.error(
+              'MISSING_REFERENCE_ID',
+              `Reference at index ${i} must have an id`,
+              `${refPath}.id`,
+            ));
+          } else {
+            if (refIds.has(ref.id)) {
+              errors.push(ValidationUtils.error(
+                'DUPLICATE_REFERENCE_ID',
+                `Duplicate reference id: "${ref.id}"`,
+                `${refPath}.id`,
+              ));
+            }
+            refIds.add(ref.id);
+          }
+          
+          if (!ref.title || typeof ref.title !== 'string') {
+            errors.push(ValidationUtils.error(
+              'MISSING_REFERENCE_TITLE',
+              `Reference at index ${i} must have a title`,
+              `${refPath}.title`,
+            ));
+          }
+          
+          // Validate URL if present
+          if (ref.url && !ValidationUtils.isValidURL(ref.url)) {
+            warnings.push(ValidationUtils.warning(
+              'INVALID_REFERENCE_URL',
+              `Reference "${ref.id}" has an invalid URL`,
+              `${refPath}.url`,
+            ));
+          }
+        }
+      }
+    }
+    
+    // Validate status if specified
+    if (metadata.status) {
+      if (!VALID_STATUSES.includes(metadata.status)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_STATUS',
+          `Invalid document status: "${metadata.status}". Must be one of: ${VALID_STATUSES.join(', ')}`,
+          'metadata.status',
+          metadata.status,
+        ));
+      }
+    }
+    
+    // Validate revision if specified
+    if (metadata.revision !== undefined) {
+      if (typeof metadata.revision !== 'number' || metadata.revision < 1 || !Number.isInteger(metadata.revision)) {
+        errors.push(ValidationUtils.error(
+          'INVALID_REVISION',
+          'Revision must be a positive integer',
+          'metadata.revision',
+        ));
+      }
+    }
+    
+    // Suggest adding language
+    if (!metadata.language) {
+      warnings.push(ValidationUtils.warning(
+        'MISSING_LANGUAGE',
+        'Consider specifying the document language',
+        'metadata.language',
+        'Add a language code like "en" for English',
+      ));
+    }
+    
+    // Suggest adding abstract
+    if (!metadata.abstract) {
+      warnings.push(ValidationUtils.warning(
+        'MISSING_ABSTRACT',
+        'Consider adding an abstract or summary',
+        'metadata.abstract',
+      ));
+    }
+    
+    // Check that at least one document resource exists
+    const docResources = manifest.resources.filter(r => 
+      r.type === 'document' ||
+      r.type === 'text' ||
+      r.contentType.includes('text/') ||
+      r.contentType.includes('markdown') ||
+      r.contentType.includes('html') ||
+      r.contentType.includes('pdf')
+    );
+    if (docResources.length === 0) {
+      warnings.push(ValidationUtils.warning(
+        'NO_DOCUMENT_RESOURCES',
+        'No document resources found. Ensure resources have appropriate types',
+        'resources',
+      ));
+    }
+    
+    return errors.length > 0
+      ? ValidationUtils.failure(errors, warnings)
+      : ValidationUtils.success(warnings);
+  }
+}
+

package/src/kinds/validators/MediaValidator.ts

@@ -0,0 +1,269 @@
+/**
+ * Media Kind Validator
+ * 
+ * Validates manifests for media content (image, audio, video) with format metadata.
+ */
+
+import { OriginalKind, type OriginalManifest, type ValidationResult, type MediaMetadata } from '../types';
+import { BaseKindValidator, ValidationUtils } from './base';
+
+/**
+ * Valid media types
+ */
+const VALID_MEDIA_TYPES = ['image', 'audio', 'video', '3d', 'animation'];
+
+/**
+ * Common MIME types by media type
+ */
+const COMMON_MIME_TYPES: Record<string, string[]> = {
+  image: [
+    'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml',
+    'image/avif', 'image/bmp', 'image/tiff', 'image/heic', 'image/heif',
+  ],
+  audio: [
+    'audio/mpeg', 'audio/mp3', 'audio/wav', 'audio/ogg', 'audio/flac',
+    'audio/aac', 'audio/webm', 'audio/midi', 'audio/x-wav',
+  ],
+  video: [
+    'video/mp4', 'video/webm', 'video/ogg', 'video/quicktime', 'video/x-msvideo',
+    'video/x-matroska', 'video/mpeg',
+  ],
+  '3d': [
+    'model/gltf+json', 'model/gltf-binary', 'model/obj', 'model/stl',
+    'application/octet-stream',
+  ],
+  animation: [
+    'image/gif', 'video/mp4', 'video/webm', 'application/json', // Lottie
+  ],
+};
+
+/**
+ * Validator for Media Originals
+ */
+export class MediaValidator extends BaseKindValidator<OriginalKind.Media> {
+  readonly kind = OriginalKind.Media;
+  
+  protected validateKind(manifest: OriginalManifest<OriginalKind.Media>): ValidationResult {
+    const errors: ValidationResult['errors'] = [];
+    const warnings: ValidationResult['warnings'] = [];
+    const metadata = manifest.metadata as MediaMetadata;
+    
+    // Validate metadata exists
+    if (!metadata || typeof metadata !== 'object') {
+      return ValidationUtils.failure([
+        ValidationUtils.error('MISSING_METADATA', 'Media manifest must have metadata', 'metadata'),
+      ]);
+    }
+    
+    // Validate mediaType (required)
+    if (!metadata.mediaType) {
+      errors.push(ValidationUtils.error(
+        'MISSING_MEDIA_TYPE',
+        'Media must specify a mediaType',
+        'metadata.mediaType',
+      ));
+    } else if (!VALID_MEDIA_TYPES.includes(metadata.mediaType)) {
+      errors.push(ValidationUtils.error(
+        'INVALID_MEDIA_TYPE',
+        `Invalid mediaType: "${metadata.mediaType}". Must be one of: ${VALID_MEDIA_TYPES.join(', ')}`,
+        'metadata.mediaType',
+        metadata.mediaType,
+      ));
+    }
+    
+    // Validate mimeType (required)
+    if (!metadata.mimeType || typeof metadata.mimeType !== 'string') {
+      errors.push(ValidationUtils.error(
+        'MISSING_MIME_TYPE',
+        'Media must specify a mimeType',
+        'metadata.mimeType',
+      ));
+    } else if (!ValidationUtils.isValidMimeType(metadata.mimeType)) {
+      errors.push(ValidationUtils.error(
+        'INVALID_MIME_TYPE',
+        `Invalid mimeType format: "${metadata.mimeType}"`,
+        'metadata.mimeType',
+        metadata.mimeType,
+      ));
+    } else if (metadata.mediaType) {
+      // Check if MIME type matches the declared media type
+      const expectedMimeTypes = COMMON_MIME_TYPES[metadata.mediaType];
+      if (expectedMimeTypes && !expectedMimeTypes.includes(metadata.mimeType)) {
+        warnings.push(ValidationUtils.warning(
+          'MIME_TYPE_MISMATCH',
+          `mimeType "${metadata.mimeType}" is not typically associated with mediaType "${metadata.mediaType}"`,
+          'metadata.mimeType',
+        ));
+      }
+    }
+    
+    // Validate dimensions for images and video
+    if (metadata.mediaType === 'image' || metadata.mediaType === 'video') {
+      if (metadata.dimensions) {
+        if (typeof metadata.dimensions !== 'object') {
+          errors.push(ValidationUtils.error(
+            'INVALID_DIMENSIONS',
+            'Dimensions must be an object',
+            'metadata.dimensions',
+          ));
+        } else {
+          if (typeof metadata.dimensions.width !== 'number' || metadata.dimensions.width <= 0) {
+            errors.push(ValidationUtils.error(
+              'INVALID_WIDTH',
+              'Width must be a positive number',
+              'metadata.dimensions.width',
+            ));
+          }
+          if (typeof metadata.dimensions.height !== 'number' || metadata.dimensions.height <= 0) {
+            errors.push(ValidationUtils.error(
+              'INVALID_HEIGHT',
+              'Height must be a positive number',
+              'metadata.dimensions.height',
+            ));
+          }
+        }
+      } else {
+        warnings.push(ValidationUtils.warning(
+          'MISSING_DIMENSIONS',
+          `Consider specifying dimensions for ${metadata.mediaType} content`,
+          'metadata.dimensions',
+        ));
+      }
+    }
+    
+    // Validate duration for audio and video
+    if (metadata.mediaType === 'audio' || metadata.mediaType === 'video') {
+      if (metadata.duration !== undefined) {
+        if (typeof metadata.duration !== 'number' || metadata.duration < 0) {
+          errors.push(ValidationUtils.error(
+            'INVALID_DURATION',
+            'Duration must be a non-negative number (seconds)',
+            'metadata.duration',
+          ));
+        }
+      } else {
+        warnings.push(ValidationUtils.warning(
+          'MISSING_DURATION',
+          `Consider specifying duration for ${metadata.mediaType} content`,
+          'metadata.duration',
+        ));
+      }
+    }
+    
+    // Validate frameRate for video
+    if (metadata.mediaType === 'video' || metadata.mediaType === 'animation') {
+      if (metadata.frameRate !== undefined) {
+        if (typeof metadata.frameRate !== 'number' || metadata.frameRate <= 0) {
+          errors.push(ValidationUtils.error(
+            'INVALID_FRAME_RATE',
+            'Frame rate must be a positive number',
+            'metadata.frameRate',
+          ));
+        }
+      }
+    }
+    
+    // Validate audio-specific fields
+    if (metadata.mediaType === 'audio' || metadata.mediaType === 'video') {
+      if (metadata.audioChannels !== undefined) {
+        if (typeof metadata.audioChannels !== 'number' || 
+            metadata.audioChannels <= 0 || 
+            !Number.isInteger(metadata.audioChannels)) {
+          errors.push(ValidationUtils.error(
+            'INVALID_AUDIO_CHANNELS',
+            'Audio channels must be a positive integer',
+            'metadata.audioChannels',
+          ));
+        }
+      }
+      
+      if (metadata.sampleRate !== undefined) {
+        if (typeof metadata.sampleRate !== 'number' || metadata.sampleRate <= 0) {
+          errors.push(ValidationUtils.error(
+            'INVALID_SAMPLE_RATE',
+            'Sample rate must be a positive number',
+            'metadata.sampleRate',
+          ));
+        }
+      }
+    }
+    
+    // Validate bitrate if specified
+    if (metadata.bitrate !== undefined) {
+      if (typeof metadata.bitrate !== 'number' || metadata.bitrate <= 0) {
+        errors.push(ValidationUtils.error(
+          'INVALID_BITRATE',
+          'Bitrate must be a positive number (kbps)',
+          'metadata.bitrate',
+        ));
+      }
+    }
+    
+    // Validate thumbnail if specified
+    if (metadata.thumbnail) {
+      if (typeof metadata.thumbnail !== 'string') {
+        errors.push(ValidationUtils.error(
+          'INVALID_THUMBNAIL',
+          'Thumbnail must be a string (resource ID)',
+          'metadata.thumbnail',
+        ));
+      } else if (!ValidationUtils.resourceExists(metadata.thumbnail, manifest.resources)) {
+        warnings.push(ValidationUtils.warning(
+          'THUMBNAIL_NOT_RESOURCE',
+          `Thumbnail "${metadata.thumbnail}" does not match a resource ID`,
+          'metadata.thumbnail',
+        ));
+      }
+    }
+    
+    // Validate preview if specified
+    if (metadata.preview) {
+      if (typeof metadata.preview !== 'string') {
+        errors.push(ValidationUtils.error(
+          'INVALID_PREVIEW',
+          'Preview must be a string (resource ID)',
+          'metadata.preview',
+        ));
+      } else if (!ValidationUtils.resourceExists(metadata.preview, manifest.resources)) {
+        warnings.push(ValidationUtils.warning(
+          'PREVIEW_NOT_RESOURCE',
+          `Preview "${metadata.preview}" does not match a resource ID`,
+          'metadata.preview',
+        ));
+      }
+    }
+    
+    // Suggest adding alt text for accessibility
+    if (!metadata.altText && metadata.mediaType === 'image') {
+      warnings.push(ValidationUtils.warning(
+        'MISSING_ALT_TEXT',
+        'Consider adding altText for accessibility',
+        'metadata.altText',
+      ));
+    }
+    
+    // Check that at least one media resource exists
+    const mediaResources = manifest.resources.filter(r => 
+      r.type === 'media' ||
+      r.type === 'image' ||
+      r.type === 'audio' ||
+      r.type === 'video' ||
+      r.contentType.startsWith('image/') ||
+      r.contentType.startsWith('audio/') ||
+      r.contentType.startsWith('video/') ||
+      r.contentType.startsWith('model/')
+    );
+    if (mediaResources.length === 0) {
+      warnings.push(ValidationUtils.warning(
+        'NO_MEDIA_RESOURCES',
+        'No media resources found. Ensure resources have appropriate types',
+        'resources',
+      ));
+    }
+    
+    return errors.length > 0
+      ? ValidationUtils.failure(errors, warnings)
+      : ValidationUtils.success(warnings);
+  }
+}
+