/**
 * TypeScript-style interfaces and type definitions for AppWrite Repair System
 * 
 * This file defines all data models, interfaces, and type structures used
 * throughout the AppWrite userId attribute repair system.
 * 
 * Requirements: 1.1, 2.1, 4.1
 */

/**
 * Properties of a userId attribute in AppWrite
 * @typedef {Object} UserIdAttributeProperties
 * @property {string} type - Attribute type (should be 'string')
 * @property {number} size - Maximum character length (should be 255)
 * @property {boolean} required - Whether the attribute is required
 * @property {boolean} array - Whether the attribute is an array
 * @property {string} [key] - Attribute key/name
 * @property {string} [status] - Attribute status
 */

/**
 * Collection permissions configuration
 * @typedef {Object} CollectionPermissions
 * @property {string[]} create - Create permissions array
 * @property {string[]} read - Read permissions array
 * @property {string[]} update - Update permissions array
 * @property {string[]} delete - Delete permissions array
 */

/**
 * Result of analyzing a single collection
 * @typedef {Object} CollectionAnalysisResult
 * @property {string} collectionId - Collection identifier
 * @property {boolean} exists - Whether the collection exists
 * @property {boolean} hasUserId - Whether userId attribute exists
 * @property {UserIdAttributeProperties|null} userIdProperties - Properties of userId attribute
 * @property {CollectionPermissions} permissions - Current collection permissions
 * @property {string[]} issues - List of identified issues
 * @property {'critical'|'warning'|'info'} severity - Issue severity level
 * @property {Date} analyzedAt - When analysis was performed
 */

/**
 * Result of a repair operation
 * @typedef {Object} RepairOperationResult
 * @property {string} collectionId - Collection identifier
 * @property {'add_attribute'|'set_permissions'|'validate'} operation - Type of operation
 * @property {boolean} success - Whether operation succeeded
 * @property {string} [error] - Error message if operation failed
 * @property {string} details - Operation details
 * @property {Date} timestamp - When operation was performed
 * @property {number} [retryCount] - Number of retries attempted
 */

/**
 * Result of validating a collection
 * @typedef {Object} ValidationResult
 * @property {string} collectionId - Collection identifier
 * @property {boolean} userIdQueryTest - Whether userId query test passed
 * @property {boolean} permissionTest - Whether permission test passed
 * @property {'pass'|'fail'|'warning'} overallStatus - Overall validation status
 * @property {string[]} issues - List of validation issues
 * @property {string[]} recommendations - Recommended actions
 * @property {Date} validatedAt - When validation was performed
 */

/**
 * Comprehensive report of all repair operations
 * @typedef {Object} ComprehensiveReport
 * @property {Date} timestamp - When report was generated
 * @property {number} collectionsAnalyzed - Number of collections analyzed
 * @property {number} collectionsRepaired - Number of collections repaired
 * @property {number} collectionsValidated - Number of collections validated
 * @property {'success'|'partial'|'failed'} overallStatus - Overall operation status
 * @property {Object.<string, CollectionReport>} collections - Per-collection results
 * @property {ReportSummary} summary - Summary statistics
 * @property {string[]} recommendations - Overall recommendations
 * @property {AuditLogEntry[]} auditLog - Complete audit trail
 */

/**
 * Report for a single collection
 * @typedef {Object} CollectionReport
 * @property {CollectionAnalysisResult} analysis - Analysis results
 * @property {RepairOperationResult[]} repairs - Repair operation results
 * @property {ValidationResult} validation - Validation results
 * @property {'success'|'partial'|'failed'} status - Overall collection status
 */

/**
 * Summary statistics for the repair report
 * @typedef {Object} ReportSummary
 * @property {number} criticalIssues - Number of critical issues found
 * @property {number} warningIssues - Number of warning issues found
 * @property {number} successfulRepairs - Number of successful repairs
 * @property {number} failedRepairs - Number of failed repairs
 * @property {number} totalOperations - Total number of operations performed
 * @property {number} duration - Total operation duration in milliseconds
 */

/**
 * Audit log entry for tracking operations
 * @typedef {Object} AuditLogEntry
 * @property {Date} timestamp - When operation occurred
 * @property {'analysis'|'repair'|'validation'|'error'} type - Operation type
 * @property {string} collectionId - Collection involved
 * @property {string} operation - Operation description
 * @property {Object} details - Operation details
 * @property {boolean} success - Whether operation succeeded
 * @property {string} [error] - Error message if failed
 */

/**
 * Configuration options for repair operations
 * @typedef {Object} RepairOptions
 * @property {boolean} analysisOnly - Whether to run analysis only
 * @property {string[]} [collections] - Specific collections to process
 * @property {boolean} [dryRun] - Whether to simulate operations without changes
 * @property {boolean} [continueOnError] - Whether to continue after errors
 * @property {number} [maxRetries] - Maximum retry attempts for failed operations
 * @property {boolean} [verbose] - Whether to provide verbose logging
 */

/**
 * Progress information for UI updates
 * @typedef {Object} ProgressInfo
 * @property {string} step - Current step description
 * @property {number} progress - Progress percentage (0-100)
 * @property {string} collectionId - Current collection being processed
 * @property {string} operation - Current operation
 * @property {number} completed - Number of completed operations
 * @property {number} total - Total number of operations
 * @property {string} [message] - Additional progress message
 */

/**
 * Error information with recovery instructions
 * @typedef {Object} RepairError
 * @property {string} code - Error code
 * @property {string} message - Error message
 * @property {string} collectionId - Collection where error occurred
 * @property {string} operation - Operation that failed
 * @property {string[]} instructions - Manual fix instructions
 * @property {boolean} recoverable - Whether error is recoverable
 * @property {Date} timestamp - When error occurred
 */

/**
 * User interface state
 * @typedef {Object} InterfaceState
 * @property {'idle'|'analyzing'|'repairing'|'validating'|'complete'|'error'} status - Current status
 * @property {ProgressInfo} [progress] - Current progress information
 * @property {ComprehensiveReport} [report] - Final report
 * @property {RepairError[]} errors - List of errors encountered
 * @property {boolean} canCancel - Whether operation can be cancelled
 */

// Export all types for use in other modules
export const RepairTypes = {
    // Type validation functions
    isValidCollectionId: (id) => typeof id === 'string' && id.length > 0,
    isValidSeverity: (severity) => ['critical', 'warning', 'info'].includes(severity),
    isValidOperationType: (type) => ['add_attribute', 'set_permissions', 'validate'].includes(type),
    isValidStatus: (status) => ['pass', 'fail', 'warning'].includes(status),
    isValidOverallStatus: (status) => ['success', 'partial', 'failed'].includes(status),
    
    // Default values
    defaultUserIdProperties: {
        type: 'string',
        size: 255,
        required: true,
        array: false
    },
    
    defaultPermissions: {
        create: ['users'],
        read: ['user:$userId'],
        update: ['user:$userId'],
        delete: ['user:$userId']
    }
};