classify-guides.py

#!/usr/bin/env python3
# Generated by Claude Code
"""
Classify Quarkus guides by Diataxis type using structural heuristics.

Reads quarkus.yaml for guide metadata and scans .adoc source files for
structural signals (tutorial scaffolding, config tables, code density, etc.)
to suggest a Diataxis type for each guide currently typed as "guide" (catch-all).

Output: a YAML file mapping each guide URL to its suggested type, confidence
level, detected signals, and (for mixed-type guides) the approximate line
where the type transition occurs — useful for manual splitting.

Usage:
    python3 classify-guides.py                      # scan current directory for .adoc files
    python3 classify-guides.py --adoc-dir /path/to/docs
    python3 classify-guides.py --yaml-file quarkus.yaml --all
    python3 classify-guides.py --llm                # use LLM for low-confidence guides
    python3 classify-guides.py --llm-all            # use LLM for all guides
    python3 classify-guides.py --llm-provider gemini
"""

import argparse
import re
import sys
from pathlib import Path

import yaml


# ---------------------------------------------------------------------------
# Heuristic signals
# ---------------------------------------------------------------------------

# Metadata attribute in AsciiDoc header
DIATAXIS_TYPE_ATTR = re.compile(r"^:diataxis-type:\s+(.+)", re.I)

# Tutorial scaffolding patterns (case-insensitive)
TUTORIAL_HEADING_PATTERNS = [
    re.compile(r"^==+\s+(Prerequisites|Solution|Bootstrapping|Quickstart)", re.I),
    re.compile(r"^==+\s+Creating\s+(the|your|a)\s+Maven\s+project", re.I),
    re.compile(r"^==+\s+Run(ning)?\s+the\s+application", re.I),
    re.compile(r"^==+\s+Packaging\s+and\s+run", re.I),
    re.compile(r"^==+\s+Explore\s+the\s+solution", re.I),
]
TUTORIAL_INCLUDE = re.compile(r"include::\{includes\}/devtools/")
TUTORIAL_STEP_BY_STEP = re.compile(r"step.by.step|follow.*instructions", re.I)

# Reference patterns
REFERENCE_HEADING = re.compile(
    r"^==+\s+(Configuration\s+[Rr]eference|Reference\s+[Gg]uide)", re.I
)
REFERENCE_TITLE = re.compile(r"reference|configuration", re.I)
GENERATED_CONFIG_INCLUDE = re.compile(r"include::\{generated-dir\}/config/")
CONFIG_TABLE = re.compile(r"^\[cols=")

# Concept patterns
CONCEPT_TITLE_WORDS = re.compile(
    r"\b(architecture|concepts?|understanding|how\s+.*\s+works|overview)\b", re.I
)
CONCEPT_HEADING_WORDS = re.compile(
    r"^==+\s+(Overview|What is|Introduction|Background|"
    r"Core components|Key concepts|Supported .+|Limitations|"
    r"How .+ works|Architecture|Design|Principles)\b", re.I
)
CONCEPT_EXPLANATORY_PROSE = re.compile(
    r"\b(is based on|consists of|represents a|refers to|"
    r"is used to|is designed to|is responsible for|"
    r"orchestrates|interacts with|works by|"
    r"there are (several|multiple|different|two|three))\b", re.I
)
CONCEPT_DIAGRAM = re.compile(r"^image::")

# Howto patterns
HOWTO_TITLE_WORDS = re.compile(
    r"^(deploying|using|configuring|building|creating|writing|migrating|"
    r"testing|packaging|monitoring|securing)\b",
    re.I,
)
HOWTO_IMPERATIVE_TITLE = re.compile(
    r"^(Deploy|Use|Configure|Build|Create|Write|Migrate|Test|Package|"
    r"Monitor|Secure|Enable|Set up|Add|Install|Run|Manage|Connect|"
    r"Integrate|Customize|Extend|Implement|Automate|Optimize|Debug|"
    r"Troubleshoot)\b",
    re.I,
)
HOWTO_PROCEDURE_HEADING = re.compile(
    r"^==+\s+(Procedure|How to|Setting up|Adding|Enabling|Configuring|"
    r"Creating|Updating|Removing|Disabling|Implementing)\b", re.I
)
HOWTO_ORDERED_STEP = re.compile(r"^\. [A-Z]")
HOWTO_IMPERATIVE_SENTENCE = re.compile(
    r"^(Set|Add|Create|Configure|Enable|Run|Open|Edit|Define|Specify|"
    r"Include|Remove|Update|Build|Deploy|Install|Start|Stop|Restart|"
    r"Verify|Check|Ensure|Navigate|Select|Click|Enter|Copy|Paste)\s",
    re.I,
)
HOWTO_FILENAME_SUFFIX = re.compile(r"-howto\.adoc$")

# Section and code block markers
SECTION_HEADING = re.compile(r"^(={2,})\s+(.+)")
CODE_BLOCK_FENCE = re.compile(r"^----\s*$")
XREF_PATTERN = re.compile(r"xref:")


# ---------------------------------------------------------------------------
# File analysis
# ---------------------------------------------------------------------------

def analyze_adoc(filepath: Path) -> dict:
    """Analyze an .adoc file and return structural signals."""
    try:
        lines = filepath.read_text(encoding="utf-8").splitlines()
    except FileNotFoundError:
        return {"error": f"File not found: {filepath}"}

    total_lines = len(lines)
    title = ""
    diataxis_type = ""
    sections = []           # list of (line_number, level, heading_text)
    code_block_count = 0
    in_code_block = False
    tutorial_signals = []   # list of (line_number, signal_description)
    reference_signals = []
    howto_signals = []
    config_table_count = 0
    generated_config_includes = []
    devtools_includes = 0
    prose_sample = ""

    # Howto-specific counters
    ordered_step_count = 0
    imperative_sentence_count = 0
    has_procedure_heading = False

    # Concept-specific counters
    concept_heading_count = 0
    explanatory_sentence_count = 0
    diagram_count = 0
    xref_count = 0

    in_header = False  # Track AsciiDoc document header (title to first blank line)

    for i, line in enumerate(lines, 1):
        # Extract title (= Title)
        if not title and line.startswith("= ") and not line.startswith("== "):
            title = line[2:].strip()
            in_header = True

        # End of header: first blank line after title
        elif in_header and not line.strip():
            in_header = False

        # Extract :diataxis-type: from header only (not from body text)
        if in_header and not diataxis_type:
            m = DIATAXIS_TYPE_ATTR.match(line)
            if m:
                diataxis_type = m.group(1).strip().lower()

        # Capture prose sample (first non-attribute, non-heading paragraph)
        if (title and not prose_sample and not in_code_block
                and not line.startswith(":") and not line.startswith("=")
                and not line.startswith("[") and not line.startswith("//")
                and not line.startswith("include::") and line.strip()):
            prose_sample = line.strip()

        # Track sections
        m = SECTION_HEADING.match(line)
        if m:
            level = len(m.group(1))
            heading = m.group(2).strip()
            sections.append((i, level, heading))

        # Code blocks
        if CODE_BLOCK_FENCE.match(line):
            if in_code_block:
                in_code_block = False
            else:
                in_code_block = True
                code_block_count += 1

        # Tutorial signals
        for pat in TUTORIAL_HEADING_PATTERNS:
            if pat.match(line):
                tutorial_signals.append((i, f"heading: {line.strip()}"))
                break

        if TUTORIAL_INCLUDE.search(line):
            devtools_includes += 1
            tutorial_signals.append((i, "devtools include"))

        if TUTORIAL_STEP_BY_STEP.search(line) and not in_code_block:
            tutorial_signals.append((i, "step-by-step language"))

        # Reference signals
        if REFERENCE_HEADING.match(line):
            reference_signals.append((i, f"heading: {line.strip()}"))

        if GENERATED_CONFIG_INCLUDE.search(line):
            generated_config_includes.append(i)
            reference_signals.append((i, "generated config include"))

        if CONFIG_TABLE.match(line):
            config_table_count += 1

        # Howto signals
        if HOWTO_PROCEDURE_HEADING.match(line):
            howto_signals.append((i, f"procedure heading: {line.strip()}"))
            has_procedure_heading = True

        if HOWTO_ORDERED_STEP.match(line) and not in_code_block:
            ordered_step_count += 1

        if HOWTO_IMPERATIVE_SENTENCE.match(line) and not in_code_block:
            imperative_sentence_count += 1

        # Concept signals
        if CONCEPT_HEADING_WORDS.match(line):
            concept_heading_count += 1

        if CONCEPT_EXPLANATORY_PROSE.search(line) and not in_code_block:
            explanatory_sentence_count += 1

        if CONCEPT_DIAGRAM.match(line):
            diagram_count += 1

        if XREF_PATTERN.search(line) and not in_code_block:
            xref_count += 1

    return {
        "title": title,
        "diataxis_type": diataxis_type,
        "total_lines": total_lines,
        "section_count": len([s for s in sections if s[1] == 2]),
        "sections": sections,
        "code_block_count": code_block_count,
        "tutorial_signals": tutorial_signals,
        "reference_signals": reference_signals,
        "howto_signals": howto_signals,
        "config_table_count": config_table_count,
        "generated_config_includes": generated_config_includes,
        "devtools_includes": devtools_includes,
        "ordered_step_count": ordered_step_count,
        "imperative_sentence_count": imperative_sentence_count,
        "has_procedure_heading": has_procedure_heading,
        "concept_heading_count": concept_heading_count,
        "explanatory_sentence_count": explanatory_sentence_count,
        "diagram_count": diagram_count,
        "xref_count": xref_count,
        "prose_sample": prose_sample,
    }


# ---------------------------------------------------------------------------
# Scoring functions
# ---------------------------------------------------------------------------

def compute_tutorial_score(analysis: dict) -> tuple[int, list[str]]:
    """Compute tutorial score from structural signals."""
    score = 0
    reasons = []

    tutorial_sigs = analysis["tutorial_signals"]
    devtools = analysis["devtools_includes"]

    if len(tutorial_sigs) >= 3:
        score += 4
        reasons.append(f"{len(tutorial_sigs)} tutorial signals")
    elif len(tutorial_sigs) >= 2:
        score += 3
        reasons.append(f"{len(tutorial_sigs)} tutorial signals")
    elif len(tutorial_sigs) == 1:
        score += 1
        reasons.append(f"1 tutorial signal")

    if devtools >= 1:
        score += 2
        reasons.append(f"{devtools} devtools includes")

    return score, reasons


def compute_reference_score(analysis: dict) -> tuple[int, list[str]]:
    """Compute reference score from structural signals."""
    score = 0
    reasons = []

    title = analysis["title"]
    reference_sigs = analysis["reference_signals"]
    config_tables = analysis["config_table_count"]
    gen_config = analysis["generated_config_includes"]

    if bool(REFERENCE_TITLE.search(title)):
        score += 3
        reasons.append("'reference' or 'configuration' in title")

    if len(gen_config) > 0:
        score += 3
        reasons.append(f"generated config at lines {gen_config[:3]}")

    if len(reference_sigs) >= 1:
        score += 2
        reasons.append(f"{len(reference_sigs)} reference heading signals")

    if config_tables >= 5:
        score += 3
        reasons.append(f"{config_tables} config tables")
    elif config_tables >= 3:
        score += 2
        reasons.append(f"{config_tables} config tables")

    return score, reasons


def compute_howto_score(analysis: dict) -> tuple[int, list[str]]:
    """Compute howto score from structural signals."""
    score = 0
    reasons = []

    title = analysis["title"]
    has_procedure = analysis["has_procedure_heading"]
    ordered_steps = analysis["ordered_step_count"]
    imperative_sents = analysis["imperative_sentence_count"]
    sections_l2 = analysis["section_count"]
    code_blocks = analysis["code_block_count"]
    total_lines = analysis["total_lines"]

    if has_procedure:
        score += 3
        reasons.append("procedure/task heading found")

    if ordered_steps >= 5:
        score += 2
        reasons.append(f"{ordered_steps} ordered list steps")
    elif ordered_steps >= 3:
        score += 1
        reasons.append(f"{ordered_steps} ordered list steps")

    if imperative_sents >= 10:
        score += 2
        reasons.append(f"{imperative_sents} imperative sentences")
    elif imperative_sents >= 5:
        score += 1
        reasons.append(f"{imperative_sents} imperative sentences")

    filename = analysis.get("filename", "")
    if HOWTO_FILENAME_SUFFIX.search(filename):
        score += 2
        reasons.append("filename ends with -howto.adoc")

    if HOWTO_IMPERATIVE_TITLE.match(title):
        score += 1
        reasons.append("imperative verb in title")
    elif HOWTO_TITLE_WORDS.match(title.split()[0] if title else ""):
        score += 1
        reasons.append("gerund verb in title")

    if sections_l2 >= 6 and code_blocks >= 8:
        score += 1
        reasons.append(f"{sections_l2} sections, {code_blocks} code blocks")

    if code_blocks >= 5 and total_lines >= 150:
        score += 1
        reasons.append(f"substantial content ({total_lines} lines, {code_blocks} code blocks)")

    return score, reasons


def compute_concept_score(analysis: dict) -> tuple[int, list[str]]:
    """Compute concept score from structural signals."""
    score = 0
    reasons = []

    title = analysis["title"]
    total_lines = analysis["total_lines"]
    code_blocks = analysis["code_block_count"]
    concept_headings = analysis["concept_heading_count"]
    explanatory_sents = analysis["explanatory_sentence_count"]
    diagrams = analysis["diagram_count"]
    xrefs = analysis["xref_count"]
    sections_l2 = analysis["section_count"]

    if bool(CONCEPT_TITLE_WORDS.search(title)):
        score += 3
        reasons.append("concept keywords in title")

    if concept_headings >= 2:
        score += 2
        reasons.append(f"{concept_headings} explanatory headings")
    elif concept_headings >= 1:
        score += 1
        reasons.append(f"{concept_headings} explanatory heading")

    if explanatory_sents >= 10:
        score += 2
        reasons.append(f"{explanatory_sents} explanatory sentences")
    elif explanatory_sents >= 5:
        score += 1
        reasons.append(f"{explanatory_sents} explanatory sentences")

    if diagrams >= 1:
        score += 1
        reasons.append(f"{diagrams} diagram(s)")

    # High xref density with low code density = concept
    if sections_l2 > 0:
        xref_density = xrefs / sections_l2
        code_ratio = code_blocks / max(total_lines, 1)
        if xref_density >= 1.5 and code_ratio < 0.05:
            score += 1
            reasons.append("high xref density, low code density")

    # Short + few code blocks
    if total_lines < 300 and code_blocks <= 3:
        score += 1
        reasons.append(f"moderate size ({total_lines} lines, {code_blocks} code blocks)")

    return score, reasons


# ---------------------------------------------------------------------------
# Classification logic
# ---------------------------------------------------------------------------

VALID_DIATAXIS_TYPES = {"tutorial", "howto", "concept", "reference"}

# Minimum score to be considered for a type
SCORE_THRESHOLD = 2
# Minimum score for the secondary type to trigger mixed-type detection
MIXED_THRESHOLD = 3


def classify(analysis: dict) -> dict:
    """Classify a guide based on structural analysis. Returns type + reasoning."""
    if "error" in analysis:
        return {
            "suggested_type": "unknown",
            "confidence": "none",
            "reason": analysis["error"],
            "source": "error",
        }

    # ---- Check metadata first ----
    diataxis_type = analysis.get("diataxis_type", "")
    if diataxis_type in VALID_DIATAXIS_TYPES:
        return {
            "suggested_type": diataxis_type,
            "confidence": "high",
            "reason": f"explicit :diataxis-type: {diataxis_type} attribute in file header",
            "source": "metadata",
        }

    # ---- Compute scores for each type ----
    tutorial_score, tutorial_reasons = compute_tutorial_score(analysis)
    reference_score, reference_reasons = compute_reference_score(analysis)
    howto_score, howto_reasons = compute_howto_score(analysis)
    concept_score, concept_reasons = compute_concept_score(analysis)

    scores = {
        "tutorial": (tutorial_score, tutorial_reasons),
        "reference": (reference_score, reference_reasons),
        "howto": (howto_score, howto_reasons),
        "concept": (concept_score, concept_reasons),
    }

    # Sort by score descending
    ranked = sorted(scores.items(), key=lambda x: x[1][0], reverse=True)
    top_type, (top_score, top_reasons) = ranked[0]
    second_type, (second_score, second_reasons) = ranked[1]

    # ---- Check for mixed types ----
    if top_score >= MIXED_THRESHOLD and second_score >= MIXED_THRESHOLD:
        tutorial_sigs = analysis["tutorial_signals"]
        reference_sigs = analysis["reference_signals"]

        result = {
            "suggested_type": f"mixed:{top_type}+{second_type}",
            "confidence": "high" if top_score >= 4 else "medium",
            "reason": (
                f"{top_type} signals: {'; '.join(top_reasons)}. "
                f"{second_type} signals: {'; '.join(second_reasons)}"
            ),
            "source": "heuristic",
        }

        # Add split point info for tutorial+reference (backward compat)
        if {"tutorial", "reference"} == {top_type, second_type}:
            if tutorial_sigs and reference_sigs:
                last_tutorial_line = max(s[0] for s in tutorial_sigs)
                first_reference_line = min(s[0] for s in reference_sigs)
                result["split_point"] = first_reference_line
                result["tutorial_ends_near"] = last_tutorial_line
                result["reference_starts_near"] = first_reference_line

        return result

    # ---- Single type classification ----
    if top_score >= SCORE_THRESHOLD:
        if top_score >= 5:
            confidence = "high"
        elif top_score >= 3:
            confidence = "medium"
        else:
            confidence = "low"

        return {
            "suggested_type": top_type,
            "confidence": confidence,
            "reason": "; ".join(top_reasons),
            "source": "heuristic",
        }

    # ---- Unclassified ----
    total_lines = analysis["total_lines"]
    code_blocks = analysis["code_block_count"]
    sections_l2 = analysis["section_count"]
    tutorial_sigs = analysis["tutorial_signals"]
    reference_sigs = analysis["reference_signals"]

    return {
        "suggested_type": "guide",
        "confidence": "none",
        "reason": (
            f"No strong signals. {total_lines} lines, {code_blocks} code blocks, "
            f"{sections_l2} sections, {len(tutorial_sigs)} tutorial signals, "
            f"{len(reference_sigs)} reference signals. "
            f"Scores: tutorial={tutorial_score}, reference={reference_score}, "
            f"howto={howto_score}, concept={concept_score}"
        ),
        "source": "heuristic",
    }


# ---------------------------------------------------------------------------
# LLM integration
# ---------------------------------------------------------------------------

def merge_classification(heuristic: dict, llm: dict) -> dict:
    """Merge heuristic and LLM classifications.

    Strategy: LLM is a weighted tiebreaker, not an override.
    """
    h_type = heuristic["suggested_type"]
    h_conf = heuristic["confidence"]
    l_type = llm.get("type", "")
    l_conf = llm.get("confidence", "low")

    # If heuristic is HIGH confidence, trust it (record LLM for comparison)
    if h_conf == "high":
        result = dict(heuristic)
        result["llm_type"] = l_type
        result["llm_agrees"] = (l_type == h_type)
        return result

    # If both agree, boost confidence
    if h_type == l_type:
        result = dict(heuristic)
        result["confidence"] = "high"
        result["reason"] += f"; LLM agrees: {l_type}"
        result["source"] = "heuristic+llm"
        result["llm_type"] = l_type
        result["llm_agrees"] = True
        return result

    # If heuristic is LOW/NONE but LLM is confident, use LLM
    if h_conf in ("low", "none") and l_conf in ("high", "medium"):
        return {
            "suggested_type": l_type,
            "confidence": "medium",  # cap at medium since it's LLM-only
            "reason": (
                f"LLM classification: {llm.get('reason', '')}; "
                f"heuristic was: {h_type} ({h_conf})"
            ),
            "source": "llm",
            "llm_type": l_type,
            "llm_agrees": False,
        }

    # Disagreement with medium heuristic: report both
    result = dict(heuristic)
    result["llm_type"] = l_type
    result["llm_confidence"] = l_conf
    result["llm_reason"] = llm.get("reason", "")
    result["llm_agrees"] = False
    return result


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------

def load_guide_entries(yaml_path: Path) -> list[dict]:
    """Load guide entries from quarkus.yaml, return those with type 'guide'."""
    with open(yaml_path, encoding="utf-8") as f:
        data = yaml.safe_load(f)

    guides = []
    for type_name, entries in data.get("types", {}).items():
        for entry in entries:
            entry["_current_type"] = type_name
            guides.append(entry)

    return guides


def main():
    parser = argparse.ArgumentParser(
        description="Classify Quarkus guides by Diataxis type."
    )
    parser.add_argument(
        "--adoc-dir",
        type=Path,
        default=Path("."),
        help="Directory containing .adoc guide files (default: current directory)",
    )
    parser.add_argument(
        "--yaml-file",
        type=Path,
        default=None,
        help="Path to quarkus.yaml metadata file (optional; without it, scans --adoc-dir directly)",
    )
    parser.add_argument(
        "--output",
        type=Path,
        default=Path("guide-classifications.yaml"),
        help="Output YAML file",
    )
    parser.add_argument(
        "--all",
        action="store_true",
        help="Classify all guides, not just type:guide entries",
    )
    # LLM options
    parser.add_argument(
        "--llm",
        action="store_true",
        help="Use LLM classification for low-confidence or unclassified guides",
    )
    parser.add_argument(
        "--llm-all",
        action="store_true",
        help="Use LLM classification for ALL guides (not just low-confidence)",
    )
    parser.add_argument(
        "--llm-provider",
        choices=["auto", "gemini", "anthropic", "ollama"],
        default="auto",
        help="LLM provider to use (default: auto-detect)",
    )
    parser.add_argument(
        "--llm-api-key",
        help="API key for LLM provider (default: read from environment)",
    )
    args = parser.parse_args()

    if args.yaml_file:
        if not args.yaml_file.exists():
            print(f"Error: {args.yaml_file} not found", file=sys.stderr)
            sys.exit(1)
        entries = load_guide_entries(args.yaml_file)
        if not args.all:
            entries = [e for e in entries if e["_current_type"] == "guide"]
    else:
        # No YAML file — scan --adoc-dir for .adoc files directly
        adoc_files = sorted(args.adoc_dir.glob("*.adoc"))
        if not adoc_files:
            print(f"Error: No .adoc files found in {args.adoc_dir}", file=sys.stderr)
            sys.exit(1)
        entries = [
            {"url": f"/guides/{f.stem}", "filename": f.name, "_current_type": "guide"}
            for f in adoc_files
        ]

    print(f"Analyzing {len(entries)} guides...\n")

    # Initialize LLM classifier if requested
    llm_classifier = None
    if args.llm or args.llm_all:
        try:
            from doc_utils.llm_classifier import LLMClassifier
            llm_classifier = LLMClassifier(
                provider=args.llm_provider,
                api_key=args.llm_api_key,
            )
            if not llm_classifier.is_available():
                print(
                    "Warning: No LLM provider available. "
                    "Set GEMINI_API_KEY, ANTHROPIC_API_KEY, or run Ollama.",
                    file=sys.stderr,
                )
                llm_classifier = None
            else:
                print(f"Using LLM provider: {llm_classifier.provider_name}\n")
        except ImportError:
            print(
                "Warning: doc_utils.llm_classifier not found. "
                "Install doc-utils or run from the doc-utils directory.",
                file=sys.stderr,
            )

    results = {"classified": [], "summary": {}}
    type_counts: dict[str, int] = {}
    confidence_counts: dict[str, int] = {}
    source_counts: dict[str, int] = {}

    for entry in sorted(entries, key=lambda e: e.get("url", "")):
        url = entry.get("url", "")
        filename = entry.get("filename", "")

        if not filename:
            # Derive filename from URL
            filename = url.rstrip("/").split("/")[-1] + ".adoc"

        adoc_path = args.adoc_dir / filename
        analysis = analyze_adoc(adoc_path)
        analysis["filename"] = filename  # pass filename for howto suffix check
        classification = classify(analysis)

        # Optional LLM classification
        if llm_classifier:
            needs_llm = args.llm_all or classification["confidence"] in ("low", "none")
            if needs_llm:
                llm_result = llm_classifier.classify(analysis)
                if llm_result and "error" not in llm_result:
                    classification = merge_classification(classification, llm_result)

        result = {
            "url": url,
            "filename": filename,
            "title": analysis.get("title", entry.get("title", "")),
            "current_type": entry["_current_type"],
            "suggested_type": classification["suggested_type"],
            "confidence": classification["confidence"],
            "reason": classification["reason"],
            "source": classification.get("source", "heuristic"),
            "lines": analysis.get("total_lines", 0),
            "code_blocks": analysis.get("code_block_count", 0),
            "sections": analysis.get("section_count", 0),
        }

        # For mixed types, include split point info
        if "split_point" in classification:
            result["split_point"] = classification["split_point"]
            result["tutorial_ends_near"] = classification["tutorial_ends_near"]
            result["reference_starts_near"] = classification["reference_starts_near"]

        # LLM comparison fields
        if "llm_type" in classification:
            result["llm_type"] = classification["llm_type"]
            result["llm_agrees"] = classification["llm_agrees"]
        if "llm_confidence" in classification:
            result["llm_confidence"] = classification["llm_confidence"]
            result["llm_reason"] = classification.get("llm_reason", "")

        results["classified"].append(result)

        t = classification["suggested_type"]
        type_counts[t] = type_counts.get(t, 0) + 1
        c = classification["confidence"]
        confidence_counts[c] = confidence_counts.get(c, 0) + 1
        s = classification.get("source", "heuristic")
        source_counts[s] = source_counts.get(s, 0) + 1

    results["summary"] = {
        "total_analyzed": len(entries),
        "by_type": dict(sorted(type_counts.items())),
        "by_confidence": dict(sorted(confidence_counts.items())),
        "by_source": dict(sorted(source_counts.items())),
    }

    # Write output
    with open(args.output, "w", encoding="utf-8") as f:
        yaml.dump(results, f, default_flow_style=False, sort_keys=False, width=120)

    # Print summary
    print("=== Classification Summary ===\n")
    print(f"  Total analyzed: {len(entries)}\n")

    print("  By suggested type:")
    for t, count in sorted(type_counts.items(), key=lambda x: -x[1]):
        print(f"    {t:30s} {count:4d}")

    print(f"\n  By confidence:")
    for c, count in sorted(confidence_counts.items()):
        print(f"    {c:30s} {count:4d}")

    print(f"\n  By source:")
    for s, count in sorted(source_counts.items()):
        print(f"    {s:30s} {count:4d}")

    # Print mixed-type guides with split points
    mixed = [r for r in results["classified"] if r["suggested_type"].startswith("mixed:")]
    if mixed:
        print(f"\n=== Mixed-Type Guides ({len(mixed)}) — Review for Splitting ===\n")
        for r in mixed:
            print(f"  {r['filename']}")
            print(f"    Title: {r['title']}")
            print(f"    Lines: {r['lines']}")
            if "tutorial_ends_near" in r:
                print(f"    Tutorial ends near line:    {r.get('tutorial_ends_near', '?')}")
                print(f"    Reference starts near line: {r.get('reference_starts_near', '?')}")
            print()

    print(f"\nResults written to {args.output}")


if __name__ == "__main__":
    main()