feat(errors): add unified validation error types (#228)

Add FieldValidationError and UnifiedValidationResult interfaces with
readonly properties for type safety. Add deprecated toFieldError()
helper function for backward compatibility during migration.
- FieldValidationError: field-level error with field name and message
- UnifiedValidationResult: validation result with isValid and errors
- toFieldError(): parses "field: message" format strings (deprecated)
Test coverage: 8 test cases including edge cases for colon handling,
empty strings, whitespace trimming, and whitespace-only field names.

🖥️ IDE: [Cursor](https://cursor.sh)
🔌 Extension: [Claude Code](https://claude.ai/download)


Model-Raw: claude-opus-4-5-20251101

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: nullvariant

extensions/git-id-switcher/src/core/errors.ts

@@ -293,3 +293,84 @@ export function getUserSafeMessage(error: unknown): string {
   // For non-SecurityError, return a generic message
   return 'An unexpected error occurred';
 }
+
+// ============================================================================
+// Unified Validation Types (Phase 4)
+// ============================================================================
+
+/**
+ * Field-level validation error
+ *
+ * Represents a validation error for a specific field.
+ * Properties are readonly to ensure immutability after creation.
+ */
+export interface FieldValidationError {
+  /** Field name that failed validation */
+  readonly field: string;
+  /** Error message describing the validation failure */
+  readonly message: string;
+}
+
+/**
+ * Unified validation result
+ *
+ * A consistent structure for validation results across the codebase.
+ * Properties are readonly to ensure immutability after creation.
+ */
+export interface UnifiedValidationResult {
+  /** Whether validation passed */
+  readonly isValid: boolean;
+  /** List of field-level errors (empty if isValid is true) */
+  readonly errors: readonly FieldValidationError[];
+}
+
+/**
+ * Parse a string error message into a FieldValidationError
+ *
+ * @deprecated This function exists for backward compatibility during migration.
+ * New code should use structured validation that returns FieldValidationError directly.
+ *
+ * @param error - Error string in format "field: message" or plain message
+ * @returns FieldValidationError with parsed field and message
+ *
+ * @example
+ * ```typescript
+ * // Standard format with colon separator
+ * toFieldError('email: Invalid format')
+ * // Returns: { field: 'email', message: 'Invalid format' }
+ *
+ * // No colon - treated as unknown field
+ * toFieldError('Unknown error')
+ * // Returns: { field: 'unknown', message: 'Unknown error' }
+ *
+ * // Empty string
+ * toFieldError('')
+ * // Returns: { field: 'unknown', message: '' }
+ *
+ * // Empty field name (colon at start) - treated as unknown
+ * toFieldError(': message only')
+ * // Returns: { field: 'unknown', message: ': message only' }
+ * ```
+ */
+export function toFieldError(error: string): FieldValidationError {
+  const colonIndex = error.indexOf(':');
+  if (colonIndex === -1) {
+    return {
+      field: 'unknown',
+      message: error,
+    };
+  }
+
+  const field = error.slice(0, colonIndex).trim();
+  const message = error.slice(colonIndex + 1).trim();
+
+  // If field is empty after trim, use 'unknown'
+  if (!field) {
+    return {
+      field: 'unknown',
+      message: error,
+    };
+  }
+
+  return { field, message };
+}

extensions/git-id-switcher/src/test/errors.test.ts

@@ -13,6 +13,7 @@ import {
   wrapError,
   isSecurityError,
   getUserSafeMessage,
+  toFieldError,
 } from '../core/errors';
 
 /**
@@ -263,6 +264,71 @@ function testGetUserSafeMessageFunction(): void {
   console.log('✅ getUserSafeMessage function tests passed!');
 }
 
+/**
+ * Test toFieldError function
+ */
+function testToFieldError(): void {
+  console.log('Testing toFieldError...');
+
+  // Should parse colon-separated format
+  {
+    const result = toFieldError('email: Invalid format');
+    assert.strictEqual(result.field, 'email');
+    assert.strictEqual(result.message, 'Invalid format');
+  }
+
+  // Should handle no colon (plain error message)
+  {
+    const result = toFieldError('Unknown error');
+    assert.strictEqual(result.field, 'unknown');
+    assert.strictEqual(result.message, 'Unknown error');
+  }
+
+  // Should handle empty string
+  {
+    const result = toFieldError('');
+    assert.strictEqual(result.field, 'unknown');
+    assert.strictEqual(result.message, '');
+  }
+
+  // Should handle multiple colons (only split on first)
+  {
+    const result = toFieldError('path: /home/user: invalid');
+    assert.strictEqual(result.field, 'path');
+    assert.strictEqual(result.message, '/home/user: invalid');
+  }
+
+  // Should handle colon with no message
+  {
+    const result = toFieldError('field:');
+    assert.strictEqual(result.field, 'field');
+    assert.strictEqual(result.message, '');
+  }
+
+  // Should handle colon at the beginning (empty field)
+  {
+    const result = toFieldError(': message only');
+    assert.strictEqual(result.field, 'unknown');
+    assert.strictEqual(result.message, ': message only');
+  }
+
+  // Should trim whitespace
+  {
+    const result = toFieldError('  name  :  has spaces  ');
+    assert.strictEqual(result.field, 'name');
+    assert.strictEqual(result.message, 'has spaces');
+  }
+
+  // Should handle whitespace-only field name
+  {
+    const result = toFieldError('   : message');
+    assert.strictEqual(result.field, 'unknown');
+    assert.strictEqual(result.message, '   : message');
+  }
+
+  console.log('✅ toFieldError tests passed!');
+}
+
 /**
  * Run all error tests
  */
@@ -276,6 +342,7 @@ export async function runErrorTests(): Promise<void> {
     testFactoryFunctions();
     testTypeGuards();
     testGetUserSafeMessageFunction();
+    testToFieldError();
 
     console.log('\n✅ All error tests passed!\n');
   } catch (error) {