Refactor duplicated error handling and validation utilities

packages/ums-cli/src/utils/file-operations.ts

@@ -12,27 +12,38 @@ import { join } from 'path';
 import { glob } from 'glob';
 
 /**
- * Reads a persona file and returns its content as a string
+ * Extracts error message from unknown error type
  */
-export async function readPersonaFile(path: string): Promise<string> {
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Generic file read operation with error handling
+ */
+async function readFileWithContext(
+  path: string,
+  context: string
+): Promise<string> {
   try {
     return await readFileAsync(path, 'utf-8');
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to read persona file '${path}': ${message}`);
+    throw new Error(`Failed to read ${context} '${path}': ${getErrorMessage(error)}`);
   }
 }
 
+/**
+ * Reads a persona file and returns its content as a string
+ */
+export async function readPersonaFile(path: string): Promise<string> {
+  return readFileWithContext(path, 'persona file');
+}
+
 /**
  * Reads a module file and returns its content as a string
  */
 export async function readModuleFile(path: string): Promise<string> {
-  try {
-    return await readFileAsync(path, 'utf-8');
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to read module file '${path}': ${message}`);
-  }
+  return readFileWithContext(path, 'module file');
 }
 
 /**
@@ -45,8 +56,7 @@ export async function writeOutputFile(
   try {
     await writeFileAsync(path, content, 'utf-8');
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to write output file '${path}': ${message}`);
+    throw new Error(`Failed to write output file '${path}': ${getErrorMessage(error)}`);
   }
 }
 
@@ -66,9 +76,8 @@ export async function discoverModuleFiles(paths: string[]): Promise<string[]> {
         allFiles.push(...files);
       }
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
       throw new Error(
-        `Failed to discover modules in path '${path}': ${message}`
+        `Failed to discover modules in path '${path}': ${getErrorMessage(error)}`
       );
     }
   }

packages/ums-sdk/src/loaders/loader-utils.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for loader utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { filePathToUrl, formatValidationErrors } from './loader-utils.js';
+import type { ValidationResult } from 'ums-lib';
+
+describe('loader-utils', () => {
+  describe('filePathToUrl', () => {
+    it('should convert file path to file URL', () => {
+      const filePath = '/path/to/module.ts';
+      const url = filePathToUrl(filePath);
+
+      expect(url).toContain('file://');
+      expect(url).toContain('module.ts');
+    });
+
+    it('should handle paths with special characters', () => {
+      const filePath = '/path/to/my module.ts';
+      const url = filePathToUrl(filePath);
+
+      expect(url).toContain('file://');
+      expect(url).toContain('my%20module.ts');
+    });
+  });
+
+  describe('formatValidationErrors', () => {
+    it('should format validation errors with paths', () => {
+      const validation: ValidationResult = {
+        valid: false,
+        errors: [
+          { path: 'metadata.name', message: 'Name is required' },
+          { path: 'components[0]', message: 'Invalid component' }
+        ],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation);
+      expect(result).toBe('metadata.name: Name is required; components[0]: Invalid component');
+    });
+
+    it('should use default path for errors without path', () => {
+      const validation: ValidationResult = {
+        valid: false,
+        errors: [
+          { message: 'Invalid structure' }
+        ],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation);
+      expect(result).toBe('module: Invalid structure');
+    });
+
+    it('should use custom default path', () => {
+      const validation: ValidationResult = {
+        valid: false,
+        errors: [
+          { message: 'Invalid structure' }
+        ],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation, 'persona');
+      expect(result).toBe('persona: Invalid structure');
+    });
+
+    it('should handle mixed errors with and without paths', () => {
+      const validation: ValidationResult = {
+        valid: false,
+        errors: [
+          { path: 'id', message: 'ID is required' },
+          { message: 'Missing schema version' },
+          { path: 'version', message: 'Invalid version format' }
+        ],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation);
+      expect(result).toBe('id: ID is required; module: Missing schema version; version: Invalid version format');
+    });
+
+    it('should handle single error', () => {
+      const validation: ValidationResult = {
+        valid: false,
+        errors: [
+          { path: 'id', message: 'ID is required' }
+        ],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation);
+      expect(result).toBe('id: ID is required');
+    });
+
+    it('should handle empty errors array', () => {
+      const validation: ValidationResult = {
+        valid: true,
+        errors: [],
+        warnings: []
+      };
+
+      const result = formatValidationErrors(validation);
+      expect(result).toBe('');
+    });
+  });
+});

packages/ums-sdk/src/loaders/loader-utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared utilities for module and persona loaders
+ */
+
+import { pathToFileURL } from 'node:url';
+import type { ValidationResult } from 'ums-lib';
+
+/**
+ * Convert file path to file URL for dynamic import
+ * @param filePath - Absolute path to file
+ * @returns File URL string suitable for dynamic import
+ */
+export function filePathToUrl(filePath: string): string {
+  return pathToFileURL(filePath).href;
+}
+
+/**
+ * Format validation errors into a single error message
+ * @param validation - Validation result from ums-lib
+ * @param defaultPath - Default path to use if error has no path (e.g., 'module', 'persona')
+ * @returns Formatted error message string
+ */
+export function formatValidationErrors(
+  validation: ValidationResult,
+  defaultPath = 'module'
+): string {
+  return validation.errors
+    .map(e => `${e.path ?? defaultPath}: ${e.message}`)
+    .join('; ');
+}

packages/ums-sdk/src/loaders/module-loader.ts

@@ -13,7 +13,6 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
 import {
   moduleIdToExportName,
   parseModule,
@@ -25,7 +24,8 @@ import {
   ModuleNotFoundError,
   InvalidExportError,
 } from '../errors/index.js';
-import { checkFileExists } from '../utils/file-utils.js';
+import { checkFileExists, isFileNotFoundError } from '../utils/file-utils.js';
+import { filePathToUrl, formatValidationErrors } from './loader-utils.js';
 
 /**
  * Checks if an object looks like a UMS Module (duck typing).
@@ -66,7 +66,7 @@ export class ModuleLoader {
       await checkFileExists(filePath);
 
       // Convert file path to file URL for dynamic import
-      const fileUrl = pathToFileURL(filePath).href;
+      const fileUrl = filePathToUrl(filePath);
 
       // Dynamically import the TypeScript file (tsx handles compilation)
       const moduleExports = (await import(fileUrl)) as Record<string, unknown>;
@@ -120,11 +120,8 @@ export class ModuleLoader {
       // Delegate to ums-lib for full UMS v2.0 spec validation
       const validation = validateModule(parsedModule);
       if (!validation.valid) {
-        const errorMessages = validation.errors
-          .map(e => `${e.path ?? 'module'}: ${e.message}`)
-          .join('; ');
         throw new ModuleLoadError(
-          `Module validation failed: ${errorMessages}`,
+          `Module validation failed: ${formatValidationErrors(validation, 'module')}`,
           filePath
         );
       }
@@ -162,11 +159,8 @@ export class ModuleLoader {
     try {
       return await readFile(filePath, 'utf-8');
     } catch (error) {
-      if (error && typeof error === 'object' && 'code' in error) {
-        const nodeError = error as NodeJS.ErrnoException;
-        if (nodeError.code === 'ENOENT') {
-          throw new ModuleNotFoundError(filePath);
-        }
+      if (isFileNotFoundError(error)) {
+        throw new ModuleNotFoundError(filePath);
       }
       throw new ModuleLoadError(
         `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,

packages/ums-sdk/src/loaders/persona-loader.ts

@@ -12,10 +12,10 @@
  * - Validation (UMS v2.0 spec compliance)
  */
 
-import { pathToFileURL } from 'node:url';
 import { parsePersona, validatePersona, type Persona } from 'ums-lib';
 import { ModuleLoadError, ModuleNotFoundError } from '../errors/index.js';
 import { checkFileExists } from '../utils/file-utils.js';
+import { filePathToUrl, formatValidationErrors } from './loader-utils.js';
 
 /**
  * PersonaLoader - Loads and validates TypeScript persona files
@@ -34,7 +34,7 @@ export class PersonaLoader {
       await checkFileExists(filePath);
 
       // Convert file path to file URL for dynamic import
-      const fileUrl = pathToFileURL(filePath).href;
+      const fileUrl = filePathToUrl(filePath);
 
       // Dynamically import the TypeScript file
       const personaExports = (await import(fileUrl)) as Record<string, unknown>;
@@ -69,11 +69,8 @@ export class PersonaLoader {
       // Delegate to ums-lib for full UMS v2.0 spec validation
       const validation = validatePersona(parsedPersona);
       if (!validation.valid) {
-        const errorMessages = validation.errors
-          .map(e => `${e.path ?? 'persona'}: ${e.message}`)
-          .join('; ');
         throw new ModuleLoadError(
-          `Persona validation failed: ${errorMessages}`,
+          `Persona validation failed: ${formatValidationErrors(validation, 'persona')}`,
           filePath
         );
       }