spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/gap_analysis.py

@@ -0,0 +1,915 @@
+"""Gap analysis for documentation missions.
+
+This module provides functionality to audit existing documentation, classify
+docs into Divio types, build coverage matrices, and identify gaps.
+
+The multi-strategy approach:
+1. Detect documentation framework from file structure
+2. Parse frontmatter for explicit type classification
+3. Apply content heuristics if no explicit type
+4. Build coverage matrix showing what exists vs what's needed
+5. Prioritize gaps by user impact
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from ruamel.yaml import YAML
+
+
+class DocFramework(Enum):
+    """Supported documentation frameworks."""
+
+    SPHINX = "sphinx"
+    MKDOCS = "mkdocs"
+    DOCUSAURUS = "docusaurus"
+    JEKYLL = "jekyll"
+    HUGO = "hugo"
+    PLAIN_MARKDOWN = "plain-markdown"
+    UNKNOWN = "unknown"
+
+
+def detect_doc_framework(docs_dir: Path) -> DocFramework:
+    """Detect documentation framework from file structure.
+
+    Args:
+        docs_dir: Directory containing documentation
+
+    Returns:
+        Detected framework or UNKNOWN if cannot determine
+    """
+    # Sphinx: conf.py is definitive indicator
+    if (docs_dir / "conf.py").exists():
+        return DocFramework.SPHINX
+
+    # MkDocs: mkdocs.yml is definitive
+    if (docs_dir / "mkdocs.yml").exists():
+        return DocFramework.MKDOCS
+
+    # Docusaurus: docusaurus.config.js
+    if (docs_dir / "docusaurus.config.js").exists():
+        return DocFramework.DOCUSAURUS
+
+    # Jekyll: _config.yml
+    if (docs_dir / "_config.yml").exists():
+        return DocFramework.JEKYLL
+
+    # Hugo: config.toml or config.yaml
+    if (docs_dir / "config.toml").exists() or (docs_dir / "config.yaml").exists():
+        return DocFramework.HUGO
+
+    # Check for markdown files without framework
+    if list(docs_dir.rglob("*.md")):
+        return DocFramework.PLAIN_MARKDOWN
+
+    return DocFramework.UNKNOWN
+
+
+class DivioType(Enum):
+    """Divio documentation types."""
+
+    TUTORIAL = "tutorial"
+    HOWTO = "how-to"
+    REFERENCE = "reference"
+    EXPLANATION = "explanation"
+    UNCLASSIFIED = "unclassified"
+
+
+def parse_frontmatter(content: str) -> Optional[Dict[str, Any]]:
+    """Parse YAML frontmatter from markdown file.
+
+    Args:
+        content: File content
+
+    Returns:
+        Frontmatter dict if present, None otherwise
+    """
+    if not content.startswith("---"):
+        return None
+
+    # Find closing ---
+    lines = content.split("\n")
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        return None
+
+    # Parse YAML frontmatter
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    try:
+        frontmatter_text = "\n".join(lines[1:end_idx])
+        return yaml.load(frontmatter_text)
+    except Exception:
+        return None
+
+
+def classify_by_content_heuristics(content: str) -> DivioType:
+    """Classify document by analyzing content patterns.
+
+    Args:
+        content: Document content (without frontmatter)
+
+    Returns:
+        Best-guess Divio type based on content analysis
+    """
+    content_lower = content.lower()
+
+    # Tutorial markers
+    tutorial_markers = [
+        "step 1",
+        "step 2",
+        "first,",
+        "next,",
+        "now,",
+        "you should see",
+        "let's",
+        "you'll learn",
+        "by the end",
+        "what you'll build",
+    ]
+    tutorial_score = sum(1 for marker in tutorial_markers if marker in content_lower)
+
+    # How-to markers
+    howto_markers = [
+        "how to",
+        "to do",
+        "follow these steps",
+        "problem:",
+        "solution:",
+        "before you begin",
+        "prerequisites:",
+        "verification:",
+    ]
+    howto_score = sum(1 for marker in howto_markers if marker in content_lower)
+
+    # Reference markers
+    reference_markers = [
+        "parameters:",
+        "returns:",
+        "arguments:",
+        "options:",
+        "methods:",
+        "properties:",
+        "attributes:",
+        "class:",
+        "function:",
+        "api",
+    ]
+    reference_score = sum(1 for marker in reference_markers if marker in content_lower)
+
+    # Explanation markers
+    explanation_markers = [
+        "why",
+        "background",
+        "concepts",
+        "architecture",
+        "design decision",
+        "alternatives",
+        "trade-offs",
+        "how it works",
+        "understanding",
+    ]
+    explanation_score = sum(
+        1 for marker in explanation_markers if marker in content_lower
+    )
+
+    # Determine type by highest score
+    scores = {
+        DivioType.TUTORIAL: tutorial_score,
+        DivioType.HOWTO: howto_score,
+        DivioType.REFERENCE: reference_score,
+        DivioType.EXPLANATION: explanation_score,
+    }
+
+    max_score = max(scores.values())
+    if max_score == 0:
+        return DivioType.UNCLASSIFIED
+
+    # Return type with highest score
+    for divio_type, score in scores.items():
+        if score == max_score:
+            return divio_type
+
+    return DivioType.UNCLASSIFIED
+
+
+def classify_divio_type(content: str) -> Tuple[DivioType, float]:
+    """Classify document into Divio type.
+
+    Uses multi-strategy approach:
+    1. Check frontmatter for explicit 'type' field (confidence: 1.0)
+    2. Apply content heuristics (confidence: 0.7)
+
+    Args:
+        content: Full document content including frontmatter
+
+    Returns:
+        Tuple of (DivioType, confidence_score)
+    """
+    # Strategy 1: Frontmatter (explicit classification)
+    frontmatter = parse_frontmatter(content)
+    if frontmatter and "type" in frontmatter:
+        type_str = frontmatter["type"].lower()
+        type_map = {
+            "tutorial": DivioType.TUTORIAL,
+            "how-to": DivioType.HOWTO,
+            "howto": DivioType.HOWTO,
+            "reference": DivioType.REFERENCE,
+            "explanation": DivioType.EXPLANATION,
+        }
+        if type_str in type_map:
+            return (type_map[type_str], 1.0)  # High confidence
+
+    # Strategy 2: Content heuristics
+    divio_type = classify_by_content_heuristics(content)
+    confidence = 0.7 if divio_type != DivioType.UNCLASSIFIED else 0.0
+
+    return (divio_type, confidence)
+
+
+@dataclass
+class CoverageMatrix:
+    """Documentation coverage matrix showing Divio type coverage by project area.
+
+    The matrix shows which project areas (features, modules, components) have
+    documentation for each Divio type (tutorial, how-to, reference, explanation).
+    """
+
+    project_areas: List[str] = field(default_factory=list)  # e.g., ["auth", "api", "cli"]
+    divio_types: List[str] = field(
+        default_factory=lambda: ["tutorial", "how-to", "reference", "explanation"]
+    )
+
+    # Maps (area, type) to doc file path (None if missing)
+    cells: Dict[Tuple[str, str], Optional[Path]] = field(default_factory=dict)
+
+    def get_coverage_for_area(self, area: str) -> Dict[str, Optional[Path]]:
+        """Get all Divio type coverage for one project area.
+
+        Args:
+            area: Project area name
+
+        Returns:
+            Dict mapping Divio type to doc file path (or None if missing)
+        """
+        return {dtype: self.cells.get((area, dtype)) for dtype in self.divio_types}
+
+    def get_coverage_for_type(self, divio_type: str) -> Dict[str, Optional[Path]]:
+        """Get all project area coverage for one Divio type.
+
+        Args:
+            divio_type: Divio type name
+
+        Returns:
+            Dict mapping project area to doc file path (or None if missing)
+        """
+        return {
+            area: self.cells.get((area, divio_type)) for area in self.project_areas
+        }
+
+    def get_gaps(self) -> List[Tuple[str, str]]:
+        """Return list of (area, type) tuples with missing documentation.
+
+        Returns:
+            List of (area, divio_type) tuples where documentation is missing
+        """
+        gaps = []
+        for area in self.project_areas:
+            for dtype in self.divio_types:
+                if self.cells.get((area, dtype)) is None:
+                    gaps.append((area, dtype))
+        return gaps
+
+    def get_coverage_percentage(self) -> float:
+        """Calculate percentage of cells with documentation.
+
+        Returns:
+            Coverage percentage (0.0 to 1.0)
+        """
+        total_cells = len(self.project_areas) * len(self.divio_types)
+        if total_cells == 0:
+            return 0.0
+
+        filled_cells = sum(1 for path in self.cells.values() if path is not None)
+
+        return filled_cells / total_cells
+
+    def to_markdown_table(self) -> str:
+        """Generate Markdown table representation of coverage.
+
+        Returns:
+            Markdown table showing coverage matrix
+        """
+        if not self.project_areas:
+            return "No project areas identified."
+
+        # Build table header
+        header = "| Area | " + " | ".join(self.divio_types) + " |"
+        separator = "|" + "|".join(["---"] * (len(self.divio_types) + 1)) + "|"
+
+        # Build table rows
+        rows = []
+        for area in self.project_areas:
+            cells = []
+            for dtype in self.divio_types:
+                doc_path = self.cells.get((area, dtype))
+                if doc_path:
+                    cells.append("✓")
+                else:
+                    cells.append("✗")
+            row = f"| {area} | " + " | ".join(cells) + " |"
+            rows.append(row)
+
+        # Combine
+        table_lines = [header, separator] + rows
+
+        # Add coverage percentage
+        coverage_pct = self.get_coverage_percentage() * 100
+        summary = f"\n**Coverage**: {len([c for c in self.cells.values() if c])}/{len(self.cells)} cells = {coverage_pct:.1f}%"
+
+        return "\n".join(table_lines) + summary
+
+
+class GapPriority(Enum):
+    """Priority levels for documentation gaps."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class DocumentationGap:
+    """Represents a missing piece of documentation.
+
+    Attributes:
+        area: Project area missing documentation
+        divio_type: Which Divio type is missing
+        priority: How important this gap is (high/medium/low)
+        reason: Why this gap matters
+    """
+
+    area: str
+    divio_type: str
+    priority: GapPriority
+    reason: str
+
+    def __repr__(self) -> str:
+        return f"[{self.priority.value.upper()}] {self.area} → {self.divio_type}: {self.reason}"
+
+
+def prioritize_gaps(
+    gaps: List[Tuple[str, str]],
+    project_areas: List[str],
+    existing_docs: Dict[Path, DivioType],
+) -> List[DocumentationGap]:
+    """Assign priorities to documentation gaps based on user impact.
+
+    Prioritization rules (from research):
+    - HIGH: Missing tutorials (blocks new users)
+    - HIGH: Missing reference for core features (users can't find APIs)
+    - MEDIUM: Missing how-tos for common tasks (users struggle with problems)
+    - MEDIUM: Missing tutorials for advanced features
+    - LOW: Missing explanations (nice-to-have, not blocking)
+
+    Args:
+        gaps: List of (area, divio_type) tuples with missing docs
+        project_areas: All project areas
+        existing_docs: Map of doc paths to classified types (for context)
+
+    Returns:
+        List of DocumentationGap objects with priorities assigned
+    """
+    prioritized = []
+
+    for area, divio_type in gaps:
+        # Determine if this is a core area (heuristic: alphabetically first areas are core)
+        is_core_area = project_areas.index(area) < len(project_areas) // 2
+
+        # Prioritization logic
+        if divio_type == "tutorial":
+            if is_core_area:
+                priority = GapPriority.HIGH
+                reason = "New users need tutorials to get started with core functionality"
+            else:
+                priority = GapPriority.MEDIUM
+                reason = "Users need tutorials for advanced features"
+
+        elif divio_type == "reference":
+            if is_core_area:
+                priority = GapPriority.HIGH
+                reason = "Users need API reference to use core features"
+            else:
+                priority = GapPriority.MEDIUM
+                reason = "API reference helps users discover all capabilities"
+
+        elif divio_type == "how-to":
+            priority = GapPriority.MEDIUM
+            reason = "Users need how-tos to solve common problems and tasks"
+
+        elif divio_type == "explanation":
+            priority = GapPriority.LOW
+            reason = "Explanations aid understanding but are not blocking"
+
+        else:
+            priority = GapPriority.LOW
+            reason = "Unknown Divio type"
+
+        prioritized.append(
+            DocumentationGap(
+                area=area, divio_type=divio_type, priority=priority, reason=reason
+            )
+        )
+
+    # Sort by priority (high first)
+    priority_order = {GapPriority.HIGH: 0, GapPriority.MEDIUM: 1, GapPriority.LOW: 2}
+    prioritized.sort(key=lambda gap: priority_order[gap.priority])
+
+    return prioritized
+
+
+def extract_public_api_from_python(source_dir: Path) -> List[str]:
+    """Extract public API elements from Python source.
+
+    Finds:
+    - Public functions (not starting with _)
+    - Public classes (not starting with _)
+
+    Args:
+        source_dir: Directory containing Python source
+
+    Returns:
+        List of API element names (e.g., ["ClassName", "function_name"])
+    """
+    import ast
+
+    api_elements = []
+
+    for py_file in source_dir.rglob("*.py"):
+        try:
+            source = py_file.read_text()
+            tree = ast.parse(source)
+
+            for node in ast.walk(tree):
+                # Extract public functions
+                if isinstance(node, ast.FunctionDef):
+                    if not node.name.startswith("_"):
+                        api_elements.append(node.name)
+
+                # Extract public classes
+                elif isinstance(node, ast.ClassDef):
+                    if not node.name.startswith("_"):
+                        api_elements.append(node.name)
+
+        except Exception:
+            # Skip files that can't be parsed
+            continue
+
+    return sorted(set(api_elements))  # Unique, sorted
+
+
+def extract_documented_api_from_sphinx(docs_dir: Path) -> List[str]:
+    """Extract documented API elements from Sphinx documentation.
+
+    Parses generated Sphinx HTML or source .rst files for documented APIs.
+
+    Args:
+        docs_dir: Directory containing Sphinx documentation
+
+    Returns:
+        List of documented API element names
+    """
+    # Look for autodoc-generated files or .rst source
+    documented = []
+
+    # Check Sphinx build output
+    build_dir = docs_dir / "_build" / "html"
+    if build_dir.exists():
+        # Parse HTML for documented classes/functions
+        for html_file in build_dir.rglob("*.html"):
+            content = html_file.read_text()
+            # Simple heuristic: look for Sphinx autodoc class/function markers
+            # Example: <dt class="sig sig-object py" id="ClassName">
+            import re
+
+            matches = re.findall(r'id="([a-zA-Z_][a-zA-Z0-9_]*)"', content)
+            documented.extend(matches)
+
+    return sorted(set(documented))  # Unique, sorted
+
+
+def detect_version_mismatch(
+    code_dir: Path, docs_dir: Path, language: str = "python"
+) -> List[str]:
+    """Detect API elements in code that are missing from documentation.
+
+    Args:
+        code_dir: Directory containing source code
+        docs_dir: Directory containing documentation
+        language: Programming language (currently only "python" supported)
+
+    Returns:
+        List of API element names present in code but missing from docs
+    """
+    if language == "python":
+        code_api = extract_public_api_from_python(code_dir)
+        docs_api = extract_documented_api_from_sphinx(docs_dir)
+    else:
+        # Other languages not yet supported
+        return []
+
+    missing = set(code_api) - set(docs_api)
+    return sorted(missing)
+
+
+@dataclass
+class GapAnalysis:
+    """Complete gap analysis results.
+
+    Attributes:
+        project_name: Project being analyzed
+        analysis_date: When analysis was performed
+        framework: Detected documentation framework
+        coverage_matrix: Coverage matrix showing existing docs
+        gaps: Prioritized list of documentation gaps
+        outdated: List of outdated documentation files
+        existing: Map of existing doc files to their classified types
+    """
+
+    project_name: str
+    analysis_date: datetime
+    framework: DocFramework
+    coverage_matrix: CoverageMatrix
+    gaps: List[DocumentationGap]
+    outdated: List[Tuple[Path, str]] = field(
+        default_factory=list
+    )  # (file, reason)
+    existing: Dict[Path, Tuple[DivioType, float]] = field(
+        default_factory=dict
+    )  # (type, confidence)
+
+    def to_markdown(self) -> str:
+        """Generate Markdown report of gap analysis.
+
+        Returns:
+            Full gap analysis report as Markdown
+        """
+        lines = [
+            f"# Gap Analysis: {self.project_name}",
+            "",
+            f"**Analysis Date**: {self.analysis_date.strftime('%Y-%m-%d %H:%M:%S')}",
+            f"**Documentation Framework**: {self.framework.value}",
+            f"**Coverage**: {self.coverage_matrix.get_coverage_percentage() * 100:.1f}%",
+            "",
+            "## Coverage Matrix",
+            "",
+            self.coverage_matrix.to_markdown_table(),
+            "",
+            "## Identified Gaps",
+            "",
+        ]
+
+        if not self.gaps:
+            lines.append("No gaps identified - documentation coverage is complete!")
+        else:
+            lines.append(f"Found {len(self.gaps)} documentation gaps:")
+            lines.append("")
+
+            # Group by priority
+            high_gaps = [g for g in self.gaps if g.priority == GapPriority.HIGH]
+            medium_gaps = [g for g in self.gaps if g.priority == GapPriority.MEDIUM]
+            low_gaps = [g for g in self.gaps if g.priority == GapPriority.LOW]
+
+            if high_gaps:
+                lines.append("### High Priority")
+                lines.append("")
+                for gap in high_gaps:
+                    lines.append(
+                        f"- **{gap.area} → {gap.divio_type}**: {gap.reason}"
+                    )
+                lines.append("")
+
+            if medium_gaps:
+                lines.append("### Medium Priority")
+                lines.append("")
+                for gap in medium_gaps:
+                    lines.append(
+                        f"- **{gap.area} → {gap.divio_type}**: {gap.reason}"
+                    )
+                lines.append("")
+
+            if low_gaps:
+                lines.append("### Low Priority")
+                lines.append("")
+                for gap in low_gaps:
+                    lines.append(
+                        f"- **{gap.area} → {gap.divio_type}**: {gap.reason}"
+                    )
+                lines.append("")
+
+        # Existing documentation inventory
+        lines.extend(
+            [
+                "## Existing Documentation",
+                "",
+            ]
+        )
+
+        if not self.existing:
+            lines.append("No existing documentation found.")
+        else:
+            lines.append(f"Found {len(self.existing)} documentation files:")
+            lines.append("")
+
+            # Group by Divio type
+            by_type: Dict[DivioType, List[Tuple[Path, float]]] = {}
+            for path, (dtype, confidence) in self.existing.items():
+                if dtype not in by_type:
+                    by_type[dtype] = []
+                by_type[dtype].append((path, confidence))
+
+            for dtype in DivioType:
+                if dtype in by_type and dtype != DivioType.UNCLASSIFIED:
+                    lines.append(f"### {dtype.value.title()}")
+                    lines.append("")
+                    for path, confidence in by_type[dtype]:
+                        conf_str = (
+                            f"({confidence * 100:.0f}% confidence)"
+                            if confidence < 1.0
+                            else ""
+                        )
+                        lines.append(f"- {path} {conf_str}")
+                    lines.append("")
+
+            # Unclassified docs
+            if DivioType.UNCLASSIFIED in by_type:
+                lines.append("### Unclassified")
+                lines.append("")
+                for path, _ in by_type[DivioType.UNCLASSIFIED]:
+                    lines.append(f"- {path}")
+                lines.append("")
+
+        # Outdated documentation
+        if self.outdated:
+            lines.extend(
+                [
+                    "## Outdated Documentation",
+                    "",
+                    f"Found {len(self.outdated)} outdated documentation files:",
+                    "",
+                ]
+            )
+            for path, reason in self.outdated:
+                lines.append(f"- **{path}**: {reason}")
+            lines.append("")
+
+        # Recommendations
+        lines.extend(
+            [
+                "## Recommendations",
+                "",
+            ]
+        )
+
+        if high_gaps:
+            lines.append("**Immediate action needed**:")
+            for gap in high_gaps[:3]:  # Top 3 high-priority gaps
+                lines.append(
+                    f"1. Create {gap.divio_type} for {gap.area} - {gap.reason}"
+                )
+            lines.append("")
+
+        if medium_gaps:
+            lines.append("**Should address soon**:")
+            for gap in medium_gaps[:3]:  # Top 3 medium-priority gaps
+                lines.append(f"- Add {gap.divio_type} for {gap.area}")
+            lines.append("")
+
+        if low_gaps:
+            lines.append(
+                f"**Nice to have**: {len(low_gaps)} low-priority gaps (see above)"
+            )
+            lines.append("")
+
+        return "\n".join(lines)
+
+
+def detect_project_areas(docs_dir: Path, project_root: Path) -> List[str]:
+    """Detect project areas from directory structure.
+
+    Heuristics:
+    - Check docs/ subdirectories (e.g., docs/tutorials/auth/ → "auth" area)
+    - Check source code directories (e.g., src/api/ → "api" area)
+    - Fallback: Single area named after project
+
+    Args:
+        docs_dir: Documentation directory
+        project_root: Project root directory
+
+    Returns:
+        List of project area names
+    """
+    areas = set()
+
+    # Check docs subdirectories
+    for item in docs_dir.iterdir():
+        if item.is_dir() and item.name not in ["_build", "_static", "_templates"]:
+            areas.add(item.name)
+
+    # Check source code directories
+    src_dir = project_root / "src"
+    if src_dir.exists():
+        for item in src_dir.iterdir():
+            if item.is_dir():
+                areas.add(item.name)
+
+    # Fallback: project name as single area
+    if not areas:
+        areas.add(project_root.name)
+
+    return sorted(areas)
+
+
+def infer_area_from_path(doc_path: Path, project_areas: List[str]) -> Optional[str]:
+    """Infer which project area a doc file belongs to.
+
+    Args:
+        doc_path: Path to documentation file
+        project_areas: Known project areas
+
+    Returns:
+        Area name if match found, None otherwise
+    """
+    # Check if any area name appears in path
+    path_str = str(doc_path).lower()
+    for area in project_areas:
+        if area.lower() in path_str:
+            return area
+
+    # Fallback: use first area (generic)
+    return project_areas[0] if project_areas else None
+
+
+def build_coverage_matrix(
+    classified: Dict[Path, Tuple[DivioType, float]], project_areas: List[str]
+) -> CoverageMatrix:
+    """Build coverage matrix from classified documents.
+
+    Args:
+        classified: Map of doc paths to (DivioType, confidence)
+        project_areas: List of project area names
+
+    Returns:
+        CoverageMatrix showing coverage by area and type
+    """
+    matrix = CoverageMatrix(project_areas=project_areas)
+
+    # Map each classified doc to (area, type) cell
+    for doc_path, (divio_type, _) in classified.items():
+        if divio_type == DivioType.UNCLASSIFIED:
+            continue
+
+        # Infer area from path (heuristic: directory name or filename prefix)
+        area = infer_area_from_path(doc_path, project_areas)
+        if area:
+            matrix.cells[(area, divio_type.value)] = doc_path
+
+    return matrix
+
+
+def analyze_documentation_gaps(
+    docs_dir: Path, project_root: Optional[Path] = None
+) -> GapAnalysis:
+    """Analyze documentation directory and identify gaps.
+
+    Args:
+        docs_dir: Directory containing documentation
+        project_root: Project root (for code analysis), defaults to docs_dir.parent
+
+    Returns:
+        GapAnalysis object with coverage matrix, gaps, and recommendations
+    """
+    if project_root is None:
+        project_root = docs_dir.parent
+
+    project_name = project_root.name
+
+    # Detect framework
+    framework = detect_doc_framework(docs_dir)
+
+    # Discover all markdown files
+    doc_files = list(docs_dir.rglob("*.md"))
+
+    # Classify each file
+    classified = {}
+    for doc_file in doc_files:
+        try:
+            content = doc_file.read_text()
+            divio_type, confidence = classify_divio_type(content)
+            classified[doc_file] = (divio_type, confidence)
+        except Exception:
+            # Skip files that can't be read/classified
+            classified[doc_file] = (DivioType.UNCLASSIFIED, 0.0)
+
+    # Detect project areas from directory structure or code
+    project_areas = detect_project_areas(docs_dir, project_root)
+
+    # Build coverage matrix
+    coverage_matrix = build_coverage_matrix(classified, project_areas)
+
+    # Identify gaps
+    gap_tuples = coverage_matrix.get_gaps()
+
+    # Prioritize gaps
+    prioritized_gaps = prioritize_gaps(gap_tuples, project_areas, classified)
+
+    # Detect version mismatches (Python only for now)
+    outdated = []
+    # TODO: Implement version mismatch detection (T038)
+
+    return GapAnalysis(
+        project_name=project_name,
+        analysis_date=datetime.now(),
+        framework=framework,
+        coverage_matrix=coverage_matrix,
+        gaps=prioritized_gaps,
+        outdated=outdated,
+        existing=classified,
+    )
+
+
+def generate_gap_analysis_report(
+    docs_dir: Path, output_file: Path, project_root: Optional[Path] = None
+) -> GapAnalysis:
+    """Analyze documentation and generate gap analysis report.
+
+    This is the main entry point for gap analysis. It:
+    1. Detects documentation framework
+    2. Classifies existing docs into Divio types
+    3. Builds coverage matrix
+    4. Identifies gaps
+    5. Prioritizes gaps by impact
+    6. Detects outdated documentation
+    7. Generates comprehensive report
+
+    Args:
+        docs_dir: Directory containing documentation to analyze
+        output_file: Path where gap-analysis.md should be written
+        project_root: Project root directory (for code analysis)
+
+    Returns:
+        GapAnalysis object with full results
+
+    Raises:
+        FileNotFoundError: If docs_dir doesn't exist
+    """
+    if not docs_dir.exists():
+        raise FileNotFoundError(f"Documentation directory not found: {docs_dir}")
+
+    # Run analysis
+    analysis = analyze_documentation_gaps(docs_dir, project_root)
+
+    # Generate report
+    report_content = analysis.to_markdown()
+
+    # Write to file
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    output_file.write_text(report_content)
+
+    return analysis
+
+
+def run_gap_analysis_for_feature(feature_dir: Path) -> GapAnalysis:
+    """Run gap analysis for a documentation mission feature.
+
+    Assumes standard paths:
+    - Documentation: {project_root}/docs/
+    - Output: {feature_dir}/gap-analysis.md
+
+    Args:
+        feature_dir: Feature directory (kitty-specs/###-doc-feature/)
+
+    Returns:
+        GapAnalysis results
+    """
+    # Find project root (walk up from feature_dir to find docs/)
+    project_root = feature_dir
+    while project_root != project_root.parent:
+        if (project_root / "docs").exists():
+            break
+        project_root = project_root.parent
+
+    docs_dir = project_root / "docs"
+    output_file = feature_dir / "gap-analysis.md"
+
+    return generate_gap_analysis_report(docs_dir, output_file, project_root)