#!/usr/bin/env python3
"""
Validate command examples and code blocks in markdown documentation.

Purpose: Extract code blocks from markdown files and validate syntax/formatting.
Author: Generated by documentation methodology experiment
Version: 1.0
"""

import re
import sys
import subprocess
from pathlib import Path
from typing import List, Tuple, Dict
from dataclasses import dataclass


@dataclass
class CodeBlock:
    """Represents a code block found in markdown."""
    language: str
    content: str
    line_number: int
    file_path: Path


@dataclass
class ValidationResult:
    """Result of validating a code block."""
    code_block: CodeBlock
    is_valid: bool
    error_message: str = ""


class MarkdownValidator:
    """Extract and validate code blocks from markdown files."""

    def __init__(self):
        self.supported_validators = {
            'bash': self._validate_bash,
            'sh': self._validate_bash,
            'shell': self._validate_bash,
            'python': self._validate_python,
            'go': self._validate_go,
            'json': self._validate_json,
            'yaml': self._validate_yaml,
            'yml': self._validate_yaml,
        }

    def extract_code_blocks(self, file_path: Path) -> List[CodeBlock]:
        """Extract all code blocks from markdown file."""
        code_blocks = []

        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
            lines = content.split('\n')

        in_code_block = False
        current_language = ""
        current_content = []
        start_line = 0

        for line_num, line in enumerate(lines, start=1):
            # Match code block start (```language)
            start_match = re.match(r'^```(\w+)?', line)
            if start_match and not in_code_block:
                in_code_block = True
                current_language = start_match.group(1) or ''
                current_content = []
                start_line = line_num
                continue

            # Match code block end (```)
            if line.startswith('```') and in_code_block:
                code_blocks.append(CodeBlock(
                    language=current_language,
                    content='\n'.join(current_content),
                    line_number=start_line,
                    file_path=file_path
                ))
                in_code_block = False
                current_language = ""
                current_content = []
                continue

            # Accumulate code block content
            if in_code_block:
                current_content.append(line)

        return code_blocks

    def validate_code_block(self, code_block: CodeBlock) -> ValidationResult:
        """Validate a single code block based on its language."""
        if not code_block.language:
            # No language specified, skip validation
            return ValidationResult(
                code_block=code_block,
                is_valid=True,
                error_message=""
            )

        language = code_block.language.lower()

        if language not in self.supported_validators:
            # Language not supported for validation, skip
            return ValidationResult(
                code_block=code_block,
                is_valid=True,
                error_message=f"Validation not supported for language: {language}"
            )

        validator = self.supported_validators[language]
        return validator(code_block)

    def _validate_bash(self, code_block: CodeBlock) -> ValidationResult:
        """Validate bash/shell syntax using shellcheck or basic parsing."""
        # Check for common bash syntax errors
        content = code_block.content

        # Skip if it's just comments or examples (not executable)
        lines = [line.strip() for line in content.split('\n') if line.strip()]
        if all(line.startswith('#') or not line for line in lines):
            return ValidationResult(code_block=code_block, is_valid=True)

        # Check for unmatched quotes
        single_quotes = content.count("'") - content.count("\\'")
        double_quotes = content.count('"') - content.count('\\"')

        if single_quotes % 2 != 0:
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message="Unmatched single quote"
            )

        if double_quotes % 2 != 0:
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message="Unmatched double quote"
            )

        # Check for unmatched braces/brackets
        if content.count('{') != content.count('}'):
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message="Unmatched curly braces"
            )

        if content.count('[') != content.count(']'):
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message="Unmatched square brackets"
            )

        if content.count('(') != content.count(')'):
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message="Unmatched parentheses"
            )

        # Try shellcheck if available
        try:
            result = subprocess.run(
                ['shellcheck', '-'],
                input=content.encode('utf-8'),
                capture_output=True,
                timeout=5
            )
            if result.returncode != 0:
                error = result.stdout.decode('utf-8')
                # Extract first meaningful error
                error_lines = [l for l in error.split('\n') if l.strip() and not l.startswith('In -')]
                error_msg = error_lines[0] if error_lines else "Shellcheck validation failed"
                return ValidationResult(
                    code_block=code_block,
                    is_valid=False,
                    error_message=f"shellcheck: {error_msg}"
                )
        except (subprocess.TimeoutExpired, FileNotFoundError):
            # shellcheck not available or timed out, basic validation passed
            pass

        return ValidationResult(code_block=code_block, is_valid=True)

    def _validate_python(self, code_block: CodeBlock) -> ValidationResult:
        """Validate Python syntax using ast.parse."""
        import ast

        try:
            ast.parse(code_block.content)
            return ValidationResult(code_block=code_block, is_valid=True)
        except SyntaxError as e:
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message=f"Python syntax error: {e.msg} at line {e.lineno}"
            )

    def _validate_go(self, code_block: CodeBlock) -> ValidationResult:
        """Validate Go syntax using gofmt."""
        try:
            result = subprocess.run(
                ['gofmt', '-e'],
                input=code_block.content.encode('utf-8'),
                capture_output=True,
                timeout=5
            )
            if result.returncode != 0:
                error = result.stderr.decode('utf-8')
                return ValidationResult(
                    code_block=code_block,
                    is_valid=False,
                    error_message=f"gofmt: {error.strip()}"
                )
            return ValidationResult(code_block=code_block, is_valid=True)
        except (subprocess.TimeoutExpired, FileNotFoundError):
            # gofmt not available, skip validation
            return ValidationResult(
                code_block=code_block,
                is_valid=True,
                error_message="gofmt not available"
            )

    def _validate_json(self, code_block: CodeBlock) -> ValidationResult:
        """Validate JSON syntax."""
        import json

        try:
            json.loads(code_block.content)
            return ValidationResult(code_block=code_block, is_valid=True)
        except json.JSONDecodeError as e:
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message=f"JSON error: {e.msg} at line {e.lineno}"
            )

    def _validate_yaml(self, code_block: CodeBlock) -> ValidationResult:
        """Validate YAML syntax."""
        try:
            import yaml
            yaml.safe_load(code_block.content)
            return ValidationResult(code_block=code_block, is_valid=True)
        except ImportError:
            return ValidationResult(
                code_block=code_block,
                is_valid=True,
                error_message="PyYAML not installed, skipping validation"
            )
        except yaml.YAMLError as e:
            return ValidationResult(
                code_block=code_block,
                is_valid=False,
                error_message=f"YAML error: {str(e)}"
            )

    def validate_file(self, file_path: Path) -> List[ValidationResult]:
        """Extract and validate all code blocks in a file."""
        code_blocks = self.extract_code_blocks(file_path)
        results = []

        for code_block in code_blocks:
            result = self.validate_code_block(code_block)
            results.append(result)

        return results


def print_results(results: List[ValidationResult], verbose: bool = False):
    """Print validation results."""
    total_blocks = len(results)
    valid_blocks = sum(1 for r in results if r.is_valid)
    invalid_blocks = total_blocks - valid_blocks

    if verbose or invalid_blocks > 0:
        for result in results:
            if not result.is_valid:
                print(f"❌ {result.code_block.file_path}:{result.code_block.line_number}")
                print(f"   Language: {result.code_block.language}")
                print(f"   Error: {result.error_message}")
                print()
            elif verbose:
                print(f"✅ {result.code_block.file_path}:{result.code_block.line_number} ({result.code_block.language})")

    print(f"\nValidation Summary:")
    print(f"  Total code blocks: {total_blocks}")
    print(f"  Valid: {valid_blocks}")
    print(f"  Invalid: {invalid_blocks}")

    if invalid_blocks == 0:
        print("\n✅ All code blocks validated successfully!")
    else:
        print(f"\n❌ {invalid_blocks} code block(s) have validation errors")


def main():
    """Main entry point."""
    import argparse

    parser = argparse.ArgumentParser(
        description='Validate code blocks in markdown documentation'
    )
    parser.add_argument(
        'files',
        nargs='+',
        type=Path,
        help='Markdown files to validate'
    )
    parser.add_argument(
        '-v', '--verbose',
        action='store_true',
        help='Show all validation results (not just errors)'
    )

    args = parser.parse_args()

    validator = MarkdownValidator()
    all_results = []

    for file_path in args.files:
        if not file_path.exists():
            print(f"Error: File not found: {file_path}", file=sys.stderr)
            sys.exit(1)

        if not file_path.suffix == '.md':
            print(f"Warning: Skipping non-markdown file: {file_path}", file=sys.stderr)
            continue

        results = validator.validate_file(file_path)
        all_results.extend(results)

    print_results(all_results, verbose=args.verbose)

    # Exit with error code if any validation failed
    if any(not r.is_valid for r in all_results):
        sys.exit(1)

    sys.exit(0)


if __name__ == '__main__':
    main()