"""Lightweight Markdown formatter: normalizes first-line H1, adds code-fence language hints for common shebangs, trims trailing whitespace.

This is intentionally small and non-destructive; it touches only files under docs/ and makes safe changes.
"""
import re
from pathlib import Path

DOCS = Path(__file__).resolve().parents[1] / "docs"

CODE_LANG_HINTS = {
    'powershell': ('powershell',),
    'bash': ('bash', 'sh'),
    'sql': ('sql',),
    'python': ('python',),
}


def add_code_fence_language(match):
    fence = match.group(0)
    inner = match.group(1)
    # If language already present, return unchanged
    if fence.startswith('```') and len(fence.splitlines()[0].strip()) > 3:
        return fence
    # Try to infer language from the code content
    code = inner.strip().splitlines()[0] if inner.strip() else ''
    lang = ''
    if code.startswith('$') or code.startswith('PS') or code.lower().startswith('powershell'):
        lang = 'powershell'
    elif code.startswith('#') or code.startswith('import') or code.startswith('from'):
        lang = 'python'
    elif re.match(r'^(select|insert|update|create)\b', code.strip(), re.I):
        lang = 'sql'
    elif code.startswith('git') or code.startswith('./') or code.startswith('sudo'):
        lang = 'bash'
    if lang:
        return f'```{lang}\n{inner}\n```'
    return fence


def normalize_file(path: Path):
    text = path.read_text(encoding='utf-8')
    orig = text
    # Trim trailing whitespace and ensure single trailing newline
    text = '\n'.join(line.rstrip() for line in text.splitlines()) + '\n'
    # Ensure first non-empty line is H1
    lines = text.splitlines()
    for i, ln in enumerate(lines):
        if ln.strip():
            if not ln.startswith('#'):
                lines[i] = '# ' + ln
            break
    text = '\n'.join(lines) + '\n'
    # Add basic code fence languages where missing (simple heuristic)
    text = re.sub(r'```\n([\s\S]*?)\n```', add_code_fence_language, text)
    if text != orig:
        path.write_text(text, encoding='utf-8')
        return True
    return False


def main():
    changed = []
    for p in DOCS.rglob('*.md'):
        if p.is_file():
            try:
                if normalize_file(p):
                    changed.append(str(p.relative_to(Path.cwd())))
            except Exception as e:
                print(f"Failed to format {p}: {e}")
    if changed:
        print('Formatted files:')
        for c in changed:
            print(' -', c)
    else:
        print('No formatting changes required.')


if __name__ == '__main__':
    main()