interface YAMLParserOptions {
  templateOrder?: string[]; // Property ordering preference
  strictMode?: boolean; // Default: false - allows relaxed parsing
  preserveQuotes?: boolean; // Default: false - optimize quotes
  arrayFormat?: 'auto' | 'bracket' | 'list'; // Default: 'auto'
  dateFormat?: string; // Default: 'YYYY-MM-DD'
  maxDepth?: number; // Default: 10 for frontmatter
  allowDuplicateKeys?: boolean; // Default: false
  trimWhitespace?: boolean; // Default: true
}

interface FrontmatterResult {
  success: boolean;
  data?: Record<string, any>;
  formatted?: string; // Consistently formatted YAML
  errors: YAMLError[];
  warnings: YAMLWarning[];
  metadata: {
    hasChanges: boolean;
    originalLength: number;
    formattedLength: number;
    processingTime: number;
    propertiesCount: number;
    arrayFields: string[];
    reorderedFields: string[];
  };
}

interface YAMLError {
  line?: number;
  column?: number;
  property?: string;
  message: string;
  code: YAMLErrorCode;
  severity: 'error' | 'warning' | 'info';
  suggestion?: string;
  context?: string;
}

interface TemplateValidationResult {
  valid: boolean;
  missingFields: string[];
  extraFields: string[];
  typeErrors: TemplateError[];
  warnings: TemplateWarning[];
  suggestions: string[];
}

// Main parsing functions
function parseFrontmatter(content: string, options?: YAMLParserOptions): Promise<FrontmatterResult>;
function extractFrontmatter(content: string): Record<string, any> | null;
function formatFrontmatter(frontmatter: Record<string, any>, templateOrder?: string[]): string;
function validateAgainstTemplate(frontmatter: Record<string, any>, template: ContentTemplate): TemplateValidationResult;
function updateFileFrontmatter(filePath: string, updates: Record<string, any>): Promise<void>;
function bulkProcessFiles(pattern: string, processor: (frontmatter: Record<string, any>) => Record<string, any>): Promise<BulkProcessResult>;

// Based on existing implementations from yamlFrontmatter.ts files
class YAMLParser {
  private options: Required<YAMLParserOptions>;
  private formattingRules: FormattingRules;
  
  constructor(options: YAMLParserOptions = {}) {
    this.options = {
      templateOrder: [],
      strictMode: false,
      preserveQuotes: false,
      arrayFormat: 'auto',
      dateFormat: 'YYYY-MM-DD',
      maxDepth: 10,
      allowDuplicateKeys: false,
      trimWhitespace: true,
      ...options
    };
    this.formattingRules = new FormattingRules();
  }

  // Frontmatter extraction optimized for markdown
  public extractFrontmatter(content: string): Record<string, any> | null {
    if (!content) return null;

    const frontmatterRegex = /^---\n((?:.|\n)*?)\n---/;
    const match = content.match(frontmatterRegex);
    if (!match || !match[1]) return null;

    return this.parseFrontmatterContent(match[1].trim());
  }

  private parseFrontmatterContent(yamlContent: string): Record<string, any> {
    const frontmatter: Record<string, any> = {};
    const lines = yamlContent.split('\n');
    let currentArrayProperty: string | null = null;
    let arrayValues: any[] = [];
    
    for (let line of lines) {
      line = line.trim();
      if (!line) continue;
      
      // Handle array items
      if (line.startsWith('- ') && currentArrayProperty) {
        arrayValues.push(this.parseValue(line.substring(2).trim()));
        continue;
      }
      
      // Finalize current array if we're starting a new property
      if (currentArrayProperty && !line.startsWith('- ')) {
        frontmatter[currentArrayProperty] = arrayValues;
        currentArrayProperty = null;
        arrayValues = [];
      }
      
      // Parse key-value pairs
      const colonIndex = line.indexOf(':');
      if (colonIndex > 0) {
        const key = line.substring(0, colonIndex).trim();
        const value = line.substring(colonIndex + 1).trim();
        
        if (!value) {
          // Start of array property
          currentArrayProperty = key;
          arrayValues = [];
          continue;
        }
        
        frontmatter[key] = this.parseValue(value, key);
      }
    }
    
    // Handle final array
    if (currentArrayProperty) {
      frontmatter[currentArrayProperty] = arrayValues;
    }
    
    return frontmatter;
  }

  private parseValue(value: string, key?: string): any {
    // Handle special cases for known properties
    if (key === 'tags' && value.startsWith('[') && value.endsWith(']')) {
      return this.parseBracketArray(value);
    }
    
    // Handle quoted values
    if ((value.startsWith('"') && value.endsWith('"')) || 
        (value.startsWith("'") && value.endsWith("'"))) {
      return value.substring(1, value.length - 1);
    }
    
    // Handle boolean values
    if (value === 'true') return true;
    if (value === 'false') return false;
    if (value === 'null') return null;
    
    // Handle numeric values
    if (!isNaN(Number(value)) && !value.startsWith('0') && value !== '') {
      return value.includes('.') ? parseFloat(value) : parseInt(value);
    }
    
    return value;
  }

  private parseBracketArray(value: string): string[] {
    const content = value.substring(1, value.length - 1).trim();
    if (content === '') return [];
    
    return content.split(',').map(item => {
      const trimmed = item.trim();
      // Remove quotes if present
      if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || 
          (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
        return trimmed.substring(1, trimmed.length - 1);
      }
      return trimmed;
    }).filter(item => item !== '');
  }

  // Intelligent formatting with project-specific rules
  public formatFrontmatter(frontmatter: Record<string, any>, templateOrder?: string[]): string {
    const formatted = { ...frontmatter };
    const arrayFields = ['tags', 'authors', 'aliases'];
    const extractedArrays: Record<string, any[]> = {};
    
    // Extract arrays for special handling
    for (const field of arrayFields) {
      if (formatted[field] && Array.isArray(formatted[field])) {
        extractedArrays[field] = formatted[field];
        delete formatted[field];
      }
    }
    
    let yamlContent = '';
    
    // Handle template ordering
    if (templateOrder && Array.isArray(templateOrder)) {
      for (const key of templateOrder) {
        if (key in formatted) {
          yamlContent += this.formatProperty(key, formatted[key]);
          delete formatted[key];
        }
      }
    }
    
    // Add remaining properties
    for (const [key, value] of Object.entries(formatted)) {
      if (!arrayFields.includes(key)) {
        yamlContent += this.formatProperty(key, value);
      }
    }
    
    // Add arrays at the end
    for (const [field, values] of Object.entries(extractedArrays)) {
      yamlContent += this.formatArrayProperty(field, values);
    }
    
    return yamlContent;
  }

  private formatProperty(key: string, value: any): string {
    // Special handling for date fields
    if (key.startsWith('date_') && value) {
      return `${key}: ${this.formatDate(value)}\n`;
    }
    
    // Special handling for error messages
    if (key.endsWith('_error') || key.endsWith('_error_message')) {
      return `${key}: ${this.quoteForYAML(String(value))}\n`;
    }
    
    if (value === null) return `${key}: null\n`;
    if (typeof value === 'boolean') return `${key}: ${value}\n`;
    if (typeof value === 'number') return `${key}: ${value}\n`;
    if (typeof value === 'string') return `${key}: ${this.quoteForYAML(value)}\n`;
    
    // Fallback for complex types
    return `${key}: ${JSON.stringify(value)}\n`;
  }

  private formatArrayProperty(field: string, values: any[]): string {
    if (!values || values.length === 0) {
      return `${field}: []\n`;
    }
    
    // Determine format based on complexity
    const hasComplexValues = values.some(value => 
      typeof value === 'string' && /[\s:{}\[\]|>*&!%#`@,]/.test(value)
    );
    
    if (hasComplexValues || field === 'authors') {
      // Use list format
      let result = `${field}:\n`;
      for (const value of values) {
        result += `  - ${value}\n`;
      }
      return result;
    } else {
      // Use bracket format for simple arrays
      const valueList = values.join(', ');
      return `${field}: [${valueList}]\n`;
    }
  }

  // Intelligent quoting based on YAML reserved characters and project rules
  private quoteForYAML(value: string): string {
    // YAML reserved characters that require quoting
    const yamlReserved = /[:#>|{}\[\],&*!?\-<>=\%@`'"]/;
    
    // Don't quote if no special characters
    if (!yamlReserved.test(value) && value !== '') {
      return value;
    }
    
    // Handle mixed quotes
    if (value.includes("'") && value.includes('"')) {
      return `"${value.replace(/"/g, '\\"')}"`;
    }
    
    // Use double quotes if string contains single quotes
    if (value.includes("'")) {
      return `"${value}"`;
    }
    
    // Use single quotes if string contains double quotes
    if (value.includes('"')) {
      return `'${value}'`;
    }
    
    // Default to single quotes for reserved characters
    return `'${value}'`;
  }

  // Template validation
  public validateAgainstTemplate(
    frontmatter: Record<string, any>, 
    template: ContentTemplate
  ): TemplateValidationResult {
    const result: TemplateValidationResult = {
      valid: true,
      missingFields: [],
      extraFields: [],
      typeErrors: [],
      warnings: [],
      suggestions: []
    };
    
    // Check required fields
    for (const field of Object.keys(template.required || {})) {
      if (!(field in frontmatter)) {
        result.missingFields.push(field);
        result.valid = false;
      }
    }
    
    // Check for extra fields
    const allowedFields = new Set([
      ...Object.keys(template.required || {}),
      ...Object.keys(template.optional || {})
    ]);
    
    for (const field of Object.keys(frontmatter)) {
      if (!allowedFields.has(field)) {
        result.extraFields.push(field);
        result.warnings.push(`Unexpected field: ${field}`);
      }
    }
    
    return result;
  }

  // Bulk processing for large content repositories
  public async bulkProcessFiles(
    pattern: string,
    processor: (frontmatter: Record<string, any>) => Record<string, any>
  ): Promise<BulkProcessResult> {
    // Implementation would use file system operations
    // to process multiple files efficiently
    const result: BulkProcessResult = {
      totalFiles: 0,
      processedFiles: 0,
      errors: [],
      changes: [],
      processingTime: 0
    };
    
    // Actual implementation would iterate through files
    // apply the processor function, and track changes
    
    return result;
  }
}

// Supporting interfaces
interface ContentTemplate {
  required: Record<string, any>;
  optional: Record<string, any>;
  arrayFields?: string[];
  dateFields?: string[];
}

interface BulkProcessResult {
  totalFiles: number;
  processedFiles: number;
  errors: YAMLError[];
  changes: FileChange[];
  processingTime: number;
}

interface FileChange {
  filePath: string;
  changeType: 'updated' | 'formatted' | 'validated';
  details: string;
}

enum YAMLErrorCode {
  SYNTAX_ERROR = 'SYNTAX_ERROR',
  MISSING_REQUIRED = 'MISSING_REQUIRED',
  INVALID_TYPE = 'INVALID_TYPE',
  DUPLICATE_KEY = 'DUPLICATE_KEY',
  TEMPLATE_VIOLATION = 'TEMPLATE_VIOLATION',
  FORMATTING_ISSUE = 'FORMATTING_ISSUE'
}