#!/usr/bin/env python3
"""
enrich-frontmatter.py — Add YAML frontmatter to .md files in .meshkore/docs/.

For each .md without frontmatter:
- title:     extracted from first H1, fallback to filename
- category:  inferred from first-level subdir under docs/
- updated:   from `git log -1 --format=%cs <file>` (yyyy-mm-dd), fallback today
- owner:     from --owner flag (default: rjj)
- status:    stable
- tags:      []

Usage:
    python3 enrich-frontmatter.py <docs-dir> [--owner NAME] [--dry-run]
"""
from __future__ import annotations

import argparse
import re
import subprocess
import sys
from datetime import date
from pathlib import Path

_FM_RE = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
_H1_RE = re.compile(r"^# (.+)$", re.MULTILINE)

SKIP_FILES = {"INDEX.md", "README.md", "governance.md"}


def has_frontmatter(text: str) -> bool:
    return bool(_FM_RE.match(text))


def extract_h1(text: str) -> str | None:
    m = _H1_RE.search(text)
    return m.group(1).strip() if m else None


def git_updated(file: Path) -> str:
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%cs", "--", str(file)],
            capture_output=True, text=True, timeout=5,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except Exception:
        pass
    return date.today().isoformat()


def make_frontmatter(title: str, category: str, updated: str, owner: str) -> str:
    return (
        "---\n"
        f"title: \"{title}\"\n"
        f"category: {category}\n"
        f"tags: []\n"
        f"updated: {updated}\n"
        f"owner: {owner}\n"
        f"status: stable\n"
        f"related: []\n"
        "---\n\n"
    )


def process(file: Path, docs_root: Path, owner: str, dry_run: bool) -> bool:
    if file.name in SKIP_FILES:
        return False
    text = file.read_text(encoding="utf-8")
    if has_frontmatter(text):
        return False

    rel = file.relative_to(docs_root)
    parts = rel.parts
    category = parts[0] if len(parts) > 1 else "uncategorized"

    title = extract_h1(text) or file.stem.replace("-", " ").title()
    updated = git_updated(file)

    fm = make_frontmatter(title, category, updated, owner)
    new_text = fm + text

    if dry_run:
        print(f"[DRY] would enrich: {rel}  ·  category={category}  ·  title={title}  ·  updated={updated}")
        return True

    file.write_text(new_text, encoding="utf-8")
    print(f"enriched: {rel}")
    return True


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("docs_dir", type=Path)
    ap.add_argument("--owner", default="rjj")
    ap.add_argument("--dry-run", action="store_true")
    args = ap.parse_args()

    docs = args.docs_dir.resolve()
    if not docs.exists():
        print(f"ERROR: {docs} does not exist", file=sys.stderr)
        sys.exit(1)

    count = 0
    for md in sorted(docs.rglob("*.md")):
        if process(md, docs, args.owner, args.dry_run):
            count += 1

    print(f"\nDone. {'Would enrich' if args.dry_run else 'Enriched'} {count} files.")


if __name__ == "__main__":
    main()