#!/usr/bin/env python3
"""Add standard doc header (Last Updated, Document Version, Status, ---) to docs missing it."""
import os
import sys

DOCS_DIR = os.path.join(os.path.dirname(__file__), "..")
HEADER_BLOCK = """
**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---
"""


def needs_header(path: str) -> bool:
    try:
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            first = f.read(600)
        return "**Last Updated:**" not in first
    except Exception:
        return False


def add_header(path: str) -> bool:
    try:
        with open(path, "r", encoding="utf-8", errors="replace") as f:
            lines = f.readlines()
    except Exception as e:
        print(f"Read error {path}: {e}", file=sys.stderr)
        return False
    if not lines:
        return False
    first_500 = "".join(lines[:25])[:500]
    if "**Last Updated:**" in first_500:
        return False
    # Insert after first line (title). Skip one leading --- in rest to avoid double.
    rest = lines[1:]
    while rest and rest[0].strip() == "":
        rest = rest[1:]
    if rest and rest[0].strip() == "---":
        rest = rest[1:]
    new_lines = [lines[0], "\n", "**Last Updated:** 2026-01-31  \n", "**Document Version:** 1.0  \n", "**Status:** Active Documentation\n", "\n", "---\n", "\n"] + rest
    try:
        with open(path, "w", encoding="utf-8", newline="\n") as f:
            f.writelines(new_lines)
    except Exception as e:
        print(f"Write error {path}: {e}", file=sys.stderr)
        return False
    return True


def main():
    count = 0
    for root, _dirs, files in os.walk(DOCS_DIR):
        if "archive" in root.split(os.sep):
            continue
        depth = root[len(DOCS_DIR) :].count(os.sep)
        if depth >= 3:
            continue
        for name in files:
            if not name.endswith(".md"):
                continue
            path = os.path.join(root, name)
            rel = os.path.relpath(path, DOCS_DIR)
            if needs_header(path) and add_header(path):
                count += 1
                print(rel)
    print(f"\nAdded header to {count} files.", file=sys.stderr)
    return 0


if __name__ == "__main__":
    sys.exit(main())