#!/usr/bin/env python3
"""Generate repository knowledge indexes and inventories."""

from __future__ import annotations

from dataclasses import dataclass
import json
from pathlib import Path
import re


ROOT = Path(__file__).resolve().parents[1]
DOCS_ROOT = ROOT / "docs"
GENERATED_COMMENT = (
    "<!-- Generated by scripts/build_repo_knowledge_index.py. Do not edit manually. -->"
)
FRONTMATTER_FIELDS = (
    "title",
    "status",
    "owner_surface",
    "last_reviewed",
    "canonical",
)
BOUNDARY_BASELINE_PATH = DOCS_ROOT / "generated" / "architecture-boundary-baseline.json"
HARNESS_HEALTH_PATH = DOCS_ROOT / "generated" / "harness-health.md"
GARDENING_SUMMARY_PATH = DOCS_ROOT / "generated" / "harness-gardening-summary.md"
REQUIRED_HARNESS_WORKFLOWS = (
    ROOT / ".github" / "workflows" / "repo-harness.yml",
    ROOT / ".github" / "workflows" / "runtime-harness.yml",
    ROOT / ".github" / "workflows" / "harness-gardening.yml",
)
REQUIRED_RUNTIME_ASSETS = (
    ROOT / "scripts" / "check_architecture_boundaries.py",
    ROOT / "src" / "api" / "scripts" / "harness_diagnostics.py",
    ROOT / "src" / "cook-web" / "e2e" / "smoke.spec.ts",
    ROOT / "docker" / "docker-compose.dev.yml",
    ROOT / "docker" / "observability" / "loki-config.yml",
    ROOT / "docker" / "observability" / "tempo-config.yml",
    ROOT / "docker" / "observability" / "prometheus.yml",
    ROOT / "docker" / "observability" / "promtail-config.yml",
    ROOT / "docker" / "observability" / "otel-collector-config.yml",
)


@dataclass(frozen=True)
class DocRecord:
    path: Path
    title: str
    category: str
    status: str
    owner_surface: str
    last_reviewed: str
    canonical: str


FRONTMATTER_PATTERN = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
HEADING_PATTERN = re.compile(r"^#{1,6}\s+(.*)$", re.MULTILINE)


def parse_frontmatter(path: Path) -> dict[str, str]:
    text = path.read_text(encoding="utf-8")
    match = FRONTMATTER_PATTERN.match(text)
    if not match:
        return {}
    metadata: dict[str, str] = {}
    for raw_line in match.group(1).splitlines():
        line = raw_line.strip()
        if not line or ":" not in line:
            continue
        key, value = line.split(":", 1)
        metadata[key.strip()] = value.strip()
    return metadata


def extract_title(path: Path) -> str:
    text = path.read_text(encoding="utf-8")
    match = HEADING_PATTERN.search(text)
    if match:
        return match.group(1).strip()
    return path.stem.replace("-", " ").title()


def build_frontmatter_records(category_dir: Path, category: str) -> list[DocRecord]:
    records: list[DocRecord] = []
    for path in sorted(category_dir.glob("*.md")):
        if path.name == "index.md":
            continue
        metadata = parse_frontmatter(path)
        title = metadata.get("title") or extract_title(path)
        records.append(
            DocRecord(
                path=path,
                title=title,
                category=category,
                status=metadata.get("status", ""),
                owner_surface=metadata.get("owner_surface", ""),
                last_reviewed=metadata.get("last_reviewed", ""),
                canonical=metadata.get("canonical", ""),
            )
        )
    return records


def build_reference_records() -> list[DocRecord]:
    records: list[DocRecord] = []
    for path in sorted((DOCS_ROOT / "references").glob("*.md")):
        if path.name == "index.md":
            continue
        records.append(
            DocRecord(
                path=path,
                title=extract_title(path),
                category="reference",
                status="reference",
                owner_surface="repo",
                last_reviewed="",
                canonical="true",
            )
        )
    return records


def build_execplan_records(subdir: str, status: str) -> list[DocRecord]:
    plan_dir = DOCS_ROOT / "exec-plans" / subdir
    records: list[DocRecord] = []
    for path in sorted(plan_dir.glob("*.md")):
        records.append(
            DocRecord(
                path=path,
                title=extract_title(path),
                category=f"exec-plan-{subdir}",
                status=status,
                owner_surface="repo",
                last_reviewed="",
                canonical="true",
            )
        )
    return records


def rel_doc(path: Path) -> str:
    return path.relative_to(ROOT).as_posix()


def render_section_index(title: str, intro: str, records: list[DocRecord]) -> str:
    lines = [GENERATED_COMMENT, "", f"# {title}", "", intro, ""]
    if not records:
        lines.extend(["No documents are currently indexed here.", ""])
        return "\n".join(lines).rstrip() + "\n"

    for record in records:
        lines.append(
            f"- [{record.title}](../{record.path.relative_to(DOCS_ROOT).as_posix()})"
        )
        if record.category in {"design-doc", "product-spec"}:
            lines.append(
                f"  - Status: `{record.status}` | Owner: `{record.owner_surface}` | "
                f"Last reviewed: `{record.last_reviewed}` | Canonical: `{record.canonical}`"
            )
    lines.append("")
    return "\n".join(lines).rstrip() + "\n"


def render_execplan_index(
    active: list[DocRecord], completed: list[DocRecord], tracker: Path
) -> str:
    lines = [
        GENERATED_COMMENT,
        "",
        "# Execution Plans",
        "",
        "Active and completed ExecPlans live here. The structure and required "
        "sections are defined in [`PLANS.md`](../../PLANS.md).",
        "",
        "## Active",
        "",
    ]
    if active:
        for record in active:
            lines.append(f"- [{record.title}](./active/{record.path.name})")
    else:
        lines.append("- No active ExecPlans.")
    lines.extend(["", "## Completed", ""])
    if completed:
        for record in completed:
            lines.append(f"- [{record.title}](./completed/{record.path.name})")
    else:
        lines.append("- No completed ExecPlans.")
    lines.extend(
        [
            "",
            "## Supporting Tracker",
            "",
            f"- [Tech Debt Tracker](./{tracker.name})",
            "",
        ]
    )
    return "\n".join(lines).rstrip() + "\n"


def render_inventory(records: list[DocRecord]) -> str:
    lines = [
        GENERATED_COMMENT,
        "",
        "# Repository Knowledge Inventory",
        "",
        "| Path | Title | Category | Status | Owner | Last Reviewed | Canonical |",
        "| --- | --- | --- | --- | --- | --- | --- |",
    ]
    for record in records:
        lines.append(
            "| "
            + " | ".join(
                [
                    f"`{rel_doc(record.path)}`",
                    record.title.replace("|", "\\|"),
                    f"`{record.category}`",
                    f"`{record.status or '-'}`",
                    f"`{record.owner_surface or '-'}`",
                    f"`{record.last_reviewed or '-'}`",
                    f"`{record.canonical or '-'}`",
                ]
            )
            + " |"
        )
    lines.append("")
    return "\n".join(lines).rstrip() + "\n"


def load_boundary_baseline() -> tuple[int, dict[str, int]]:
    if not BOUNDARY_BASELINE_PATH.exists():
        return 0, {}
    payload = json.loads(BOUNDARY_BASELINE_PATH.read_text(encoding="utf-8"))
    violations = payload.get("violations", [])
    counts: dict[str, int] = {}
    for item in violations:
        rule_id = str(item.get("rule_id", "") or "")
        if not rule_id:
            continue
        counts[rule_id] = counts.get(rule_id, 0) + 1
    return len(violations), counts


def render_harness_health_report(
    *,
    design_records: list[DocRecord],
    product_records: list[DocRecord],
    reference_records: list[DocRecord],
    active_plans: list[DocRecord],
    completed_plans: list[DocRecord],
) -> str:
    baseline_count, baseline_breakdown = load_boundary_baseline()
    lines = [
        GENERATED_COMMENT,
        "",
        "# Harness Health",
        "",
        "This generated report summarizes the repository harness control plane.",
        "",
        "## Knowledge System",
        "",
        f"- Design docs: `{len(design_records)}`",
        f"- Product specs: `{len(product_records)}`",
        f"- References: `{len(reference_records)}`",
        f"- Active ExecPlans: `{len(active_plans)}`",
        f"- Completed ExecPlans: `{len(completed_plans)}`",
        "",
        "## Boundary Baseline",
        "",
        f"- Baseline entries: `{baseline_count}`",
    ]
    if baseline_breakdown:
        for rule_id, count in sorted(baseline_breakdown.items()):
            lines.append(f"- `{rule_id}`: `{count}`")
    else:
        lines.append("- No boundary baseline has been recorded yet.")

    lines.extend(["", "## Critical Assets", ""])
    for path in REQUIRED_RUNTIME_ASSETS + REQUIRED_HARNESS_WORKFLOWS:
        rel = path.relative_to(ROOT).as_posix()
        lines.append(f"- {'OK' if path.exists() else 'MISSING'} `{rel}`")
    lines.append("")
    return "\n".join(lines).rstrip() + "\n"


def build_knowledge_docs() -> dict[Path, str]:
    design_records = build_frontmatter_records(DOCS_ROOT / "design-docs", "design-doc")
    product_records = build_frontmatter_records(
        DOCS_ROOT / "product-specs", "product-spec"
    )
    reference_records = build_reference_records()
    active_plans = build_execplan_records("active", "active")
    completed_plans = build_execplan_records("completed", "completed")
    tracker = DOCS_ROOT / "exec-plans" / "tech-debt-tracker.md"

    all_records = (
        design_records
        + product_records
        + reference_records
        + active_plans
        + completed_plans
        + [
            DocRecord(
                path=ROOT / "ARCHITECTURE.md",
                title="AI-Shifu Architecture Map",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=ROOT / "PLANS.md",
                title="AI-Shifu ExecPlans",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=DOCS_ROOT / "engineering-baseline.md",
                title="Engineering Baseline",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=DOCS_ROOT / "QUALITY_SCORE.md",
                title="Quality Score",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=DOCS_ROOT / "RELIABILITY.md",
                title="Reliability",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=DOCS_ROOT / "SECURITY.md",
                title="Security",
                category="root-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=tracker,
                title="Tech Debt Tracker",
                category="exec-plan-support",
                status="active",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=HARNESS_HEALTH_PATH,
                title="Harness Health",
                category="generated-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
            DocRecord(
                path=GARDENING_SUMMARY_PATH,
                title="Harness Gardening Summary",
                category="generated-doc",
                status="reference",
                owner_surface="repo",
                last_reviewed="2026-04-17",
                canonical="true",
            ),
        ]
    )

    return {
        DOCS_ROOT / "design-docs" / "index.md": render_section_index(
            "Design Docs",
            "Implementation and architecture decisions that shape repository "
            "behavior live here.",
            design_records,
        ),
        DOCS_ROOT / "product-specs" / "index.md": render_section_index(
            "Product Specs",
            "User-facing workflow and page behavior specifications live here.",
            product_records,
        ),
        DOCS_ROOT / "references" / "index.md": render_section_index(
            "References",
            "Evergreen repository references and operational guides live here.",
            reference_records,
        ),
        DOCS_ROOT / "exec-plans" / "index.md": render_execplan_index(
            active_plans, completed_plans, tracker
        ),
        DOCS_ROOT / "generated" / "doc-inventory.md": render_inventory(
            sorted(all_records, key=lambda record: rel_doc(record.path))
        ),
        HARNESS_HEALTH_PATH: render_harness_health_report(
            design_records=design_records,
            product_records=product_records,
            reference_records=reference_records,
            active_plans=active_plans,
            completed_plans=completed_plans,
        ),
    }


def write_documents() -> int:
    docs = build_knowledge_docs()
    for path, content in sorted(docs.items()):
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(content, encoding="utf-8")
    print(f"Wrote {len(docs)} repository knowledge documents.")
    return 0


def main() -> int:
    return write_documents()


if __name__ == "__main__":
    raise SystemExit(main())
