anvil-dev-framework 0.1.6

package/global/lib/doc_coverage_service.py

@@ -0,0 +1,1305 @@
+#!/usr/bin/env python3
+"""
+doc_coverage_service.py - Documentation Coverage System (ANV-31)
+
+Provides intelligent tracking and enforcement of documentation coverage:
+- Maps source files to expected documentation
+- Extracts public exports from Python/TypeScript files
+- Calculates documentation coverage metrics
+- Detects gaps when code changes without doc updates
+
+Usage:
+    from doc_coverage_service import DocCoverageService
+
+    service = DocCoverageService()
+    coverage = service.calculate_coverage()
+    print(f"Coverage: {coverage.percent}%")
+
+CLI:
+    python doc_coverage_service.py --report
+    python doc_coverage_service.py --check
+    python doc_coverage_service.py --gaps
+"""
+
+import ast
+import fnmatch
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, ClassVar, Dict, List, Literal, Optional, Set
+
+# Import state manager for anvil-state.json integration
+try:
+    from state_manager import on_doc_coverage as _sync_state
+    STATE_MANAGER_AVAILABLE = True
+except ImportError:
+    try:
+        from .state_manager import on_doc_coverage as _sync_state
+        STATE_MANAGER_AVAILABLE = True
+    except ImportError:
+        STATE_MANAGER_AVAILABLE = False
+
+
+# =============================================================================
+# Data Classes
+# =============================================================================
+
+@dataclass
+class DocMapping:
+    """Configuration for mapping source files to documentation."""
+    source: str           # Glob pattern for source files (e.g., "global/lib/*.py")
+    docs: str             # Doc path template (e.g., "docs/api/{basename}.md")
+    doc_type: str = "api" # Type: api, command, hook, skill
+
+    def matches(self, source_path: str) -> bool:
+        """Check if a source path matches this mapping's pattern."""
+        return fnmatch.fnmatch(source_path, self.source)
+
+    def get_doc_path(self, source_path: str) -> str:
+        """Get the expected doc path for a source file."""
+        path = Path(source_path)
+        return self.docs.format(
+            basename=path.stem,
+            dirname=path.parent.name,
+            filename=path.name,
+            ext=path.suffix
+        )
+
+
+try:
+    import yaml
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+@dataclass
+class DocCoverageConfig:
+    """Configuration for documentation coverage checking."""
+    enabled: bool = True
+    gap_detection_enabled: bool = True  # ANV-218: Can disable gap detection separately
+    thresholds: Dict[str, int] = field(default_factory=lambda: {
+        "warning": 80,
+        "critical": 60
+    })
+    mappings: List[DocMapping] = field(default_factory=list)
+    exclude: List[str] = field(default_factory=lambda: [
+        "**/test_*.py",
+        "**/__pycache__/**",
+        "**/node_modules/**",
+        "**/*.test.ts",
+        "**/*.spec.ts"
+    ])
+    sensitivity: Literal["aggressive", "balanced", "quiet"] = "balanced"
+
+    @classmethod
+    def from_file(cls, config_path: str) -> "DocCoverageConfig":
+        """Load configuration from a YAML file.
+
+        Args:
+            config_path: Path to YAML configuration file
+
+        Returns:
+            DocCoverageConfig loaded from file, or default if file doesn't exist
+        """
+        path = Path(config_path)
+        if not path.exists() or not HAS_YAML:
+            return cls.default()
+
+        try:
+            with open(path, "r") as f:
+                data = yaml.safe_load(f) or {}
+
+            config = cls.default()
+
+            if "enabled" in data:
+                config.enabled = bool(data["enabled"])
+
+            if "gap_detection_enabled" in data:
+                config.gap_detection_enabled = bool(data["gap_detection_enabled"])
+
+            if "thresholds" in data:
+                config.thresholds.update(data["thresholds"])
+
+            if "sensitivity" in data:
+                config.sensitivity = data["sensitivity"]
+
+            if "exclude" in data:
+                config.exclude = data["exclude"]
+
+            if "mappings" in data:
+                config.mappings = [
+                    DocMapping(
+                        source=m.get("source", ""),
+                        docs=m.get("docs", ""),
+                        doc_type=m.get("type", "api")
+                    )
+                    for m in data["mappings"]
+                ]
+
+            return config
+        except Exception:
+            # Config loading is best-effort; silently fall back to defaults
+            # to allow the tool to work even with malformed config files
+            return cls.default()
+
+    @classmethod
+    def default(cls) -> "DocCoverageConfig":
+        """Create default configuration with standard mappings."""
+        return cls(
+            mappings=[
+                DocMapping(
+                    source="global/lib/*.py",
+                    docs="docs/api/{basename}.md",
+                    doc_type="api"
+                ),
+                DocMapping(
+                    source=".claude/commands/*.md",
+                    docs="docs/command-reference.md",
+                    doc_type="command"
+                ),
+                DocMapping(
+                    source="global/commands/*.md",
+                    docs="docs/command-reference.md",
+                    doc_type="command"
+                ),
+                DocMapping(
+                    source=".claude/hooks/*.py",
+                    docs=".claude/hooks/README.md",
+                    doc_type="hook"
+                ),
+                DocMapping(
+                    source="global/hooks/*.py",
+                    docs="global/hooks/README.md",
+                    doc_type="hook"
+                ),
+                DocMapping(
+                    source="global/skills/*/skill.md",
+                    docs="docs/skills/{dirname}.md",
+                    doc_type="skill"
+                ),
+            ]
+        )
+
+
+@dataclass
+class DocExport:
+    """Represents a public export extracted from a source file."""
+    name: str                          # Export name (function, class, etc.)
+    export_type: str                   # "function", "class", "variable", "command"
+    source_file: str                   # Source file path
+    line_number: int                   # Line number in source
+    docstring: Optional[str] = None    # Extracted docstring if any
+    signature: Optional[str] = None    # Function/method signature
+
+    @property
+    def qualified_name(self) -> str:
+        """Get fully qualified name (file:export)."""
+        return f"{self.source_file}:{self.name}"
+
+
+@dataclass
+class DocGap:
+    """Represents a documentation gap."""
+    export: DocExport                  # The undocumented export
+    expected_doc: str                  # Expected documentation path
+    doc_type: str                      # Type of documentation needed
+    severity: Literal["missing", "stale", "incomplete"] = "missing"
+    suggestion: Optional[str] = None   # Suggested action
+
+
+@dataclass
+class CoverageResult:
+    """Result of coverage calculation."""
+    total_exports: int
+    documented_exports: int
+    coverage_percent: float
+    gaps: List[DocGap]
+    by_type: Dict[str, Dict[str, int]]  # Coverage by doc type
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    @property
+    def status(self) -> Literal["healthy", "warning", "critical"]:
+        """Get health status based on coverage percentage.
+
+        Thresholds (matches DocCoverageConfig defaults):
+        - healthy: >= 80%
+        - warning: >= 60%
+        - critical: < 60%
+        """
+        if self.coverage_percent >= 80:
+            return "healthy"
+        elif self.coverage_percent >= 60:
+            return "warning"
+        return "critical"
+
+    @property
+    def status_emoji(self) -> str:
+        """Get emoji for status."""
+        return {"healthy": "✅", "warning": "⚠️", "critical": "❌"}[self.status]
+
+
+@dataclass
+class StaleDocWarning:
+    """Warning about potentially stale documentation."""
+    source_file: str           # Source file that changed
+    doc_file: str              # Related documentation file
+    source_mtime: float        # Source file modification time
+    doc_mtime: float           # Doc file modification time
+    days_stale: int            # Days since doc was updated
+    severity: Literal["info", "warning", "critical"] = "warning"
+
+    @property
+    def message(self) -> str:
+        """Human-readable warning message."""
+        return (
+            f"Documentation may be stale: {self.doc_file} "
+            f"(last updated {self.days_stale} days ago, "
+            f"source changed more recently)"
+        )
+
+
+@dataclass
+class GapDetectionResult:
+    """Result of gap detection analysis."""
+    stale_docs: List["StaleDocWarning"]
+    changed_files_without_docs: List[str]
+    total_warnings: int
+    sensitivity: Literal["aggressive", "balanced", "quiet"]
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_context_block(self) -> str:
+        """Format warnings for session context injection."""
+        if self.total_warnings == 0:
+            return ""
+
+        lines = ["## Documentation Coverage Warnings\n"]
+
+        if self.stale_docs:
+            lines.append("### Potentially Stale Documentation\n")
+            for warning in self.stale_docs:
+                lines.append(f"- {warning.message}")
+            lines.append("")
+
+        if self.changed_files_without_docs:
+            lines.append("### Changed Files Without Documentation\n")
+            for file in self.changed_files_without_docs[:5]:
+                lines.append(f"- `{file}`")
+            if len(self.changed_files_without_docs) > 5:
+                lines.append(f"- ... and {len(self.changed_files_without_docs) - 5} more")
+            lines.append("")
+
+        lines.append("Run `/doc-coverage --gaps` for details.\n")
+        return "\n".join(lines)
+
+
+# =============================================================================
+# GapDetector - Detects Stale and Missing Documentation
+# =============================================================================
+
+class GapDetector:
+    """Detects documentation gaps by analyzing file changes and timestamps.
+
+    Sensitivity levels:
+    - aggressive: Warn on any source change without doc update
+    - balanced: Warn if source is >7 days newer than doc (default)
+    - quiet: Warn if source is >30 days newer than doc
+    """
+
+    SENSITIVITY_THRESHOLDS: ClassVar[Dict[str, int]] = {
+        "aggressive": 0,
+        "balanced": 7,
+        "quiet": 30,
+    }
+
+    def __init__(
+        self,
+        config: "DocCoverageConfig",
+        sensitivity: Literal["aggressive", "balanced", "quiet"] = "balanced",
+    ):
+        """Initialize the gap detector.
+
+        Args:
+            config: Documentation coverage configuration
+            sensitivity: How sensitive to be about stale docs
+        """
+        self.config = config
+        self.sensitivity = sensitivity
+        self.threshold_days = self.SENSITIVITY_THRESHOLDS[sensitivity]
+
+    def detect_stale_docs(self, project_path: str = ".") -> List[StaleDocWarning]:
+        """Detect documentation that may be stale based on file timestamps.
+
+        Args:
+            project_path: Root path of the project
+
+        Returns:
+            List of warnings about potentially stale documentation
+        """
+        warnings: List[StaleDocWarning] = []
+        project = Path(project_path)
+
+        for mapping in self.config.mappings:
+            source_pattern = mapping.source
+            for source_path in project.glob(source_pattern):
+                if not source_path.is_file():
+                    continue
+
+                rel_source = str(source_path.relative_to(project))
+                if any(excl in rel_source for excl in self.config.exclude):
+                    continue
+
+                doc_path_str = mapping.get_doc_path(rel_source)
+                doc_path = project / doc_path_str
+
+                if not doc_path.exists():
+                    continue
+
+                source_mtime = source_path.stat().st_mtime
+                doc_mtime = doc_path.stat().st_mtime
+
+                if source_mtime > doc_mtime:
+                    days_stale = int((source_mtime - doc_mtime) / 86400)
+
+                    if days_stale >= self.threshold_days:
+                        sev: Literal["info", "warning", "critical"]
+                        if days_stale > 30:
+                            sev = "critical"
+                        elif days_stale > 7:
+                            sev = "warning"
+                        else:
+                            sev = "info"
+
+                        warnings.append(StaleDocWarning(
+                            source_file=rel_source,
+                            doc_file=doc_path_str,
+                            source_mtime=source_mtime,
+                            doc_mtime=doc_mtime,
+                            days_stale=days_stale,
+                            severity=sev,
+                        ))
+
+        return warnings
+
+    def detect_changed_without_docs(
+        self,
+        project_path: str = ".",
+        since_days: int = 7,
+    ) -> List[str]:
+        """Detect recently changed source files without documentation.
+
+        Args:
+            project_path: Root path of the project
+            since_days: Look at changes within this many days
+
+        Returns:
+            List of source file paths that changed without doc updates
+        """
+        import subprocess
+
+        project = Path(project_path)
+        changed_files: List[str] = []
+
+        try:
+            result = subprocess.run(
+                ["git", "log", f"--since={since_days} days ago",
+                 "--name-only", "--pretty=format:"],
+                cwd=project,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+
+            if result.returncode != 0:
+                return []
+
+            git_changed = set(
+                f.strip() for f in result.stdout.split("\n")
+                if f.strip() and not f.startswith(".")
+            )
+
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return []
+
+        for mapping in self.config.mappings:
+            source_pattern = mapping.source
+            for source_path in project.glob(source_pattern):
+                if not source_path.is_file():
+                    continue
+
+                rel_source = str(source_path.relative_to(project))
+
+                if rel_source not in git_changed:
+                    continue
+
+                if any(excl in rel_source for excl in self.config.exclude):
+                    continue
+
+                doc_path_str = mapping.get_doc_path(rel_source)
+                doc_path = project / doc_path_str
+
+                if not doc_path.exists():
+                    changed_files.append(rel_source)
+
+        return changed_files
+
+    def analyze(self, project_path: str = ".") -> GapDetectionResult:
+        """Run full gap detection analysis.
+
+        Args:
+            project_path: Root path of the project
+
+        Returns:
+            Complete gap detection result with all warnings
+        """
+        stale_docs = self.detect_stale_docs(project_path)
+        changed_without_docs = self.detect_changed_without_docs(project_path)
+
+        return GapDetectionResult(
+            stale_docs=stale_docs,
+            changed_files_without_docs=changed_without_docs,
+            total_warnings=len(stale_docs) + len(changed_without_docs),
+            sensitivity=self.sensitivity,
+        )
+
+
+# =============================================================================
+# DocIndexer - Scans and Extracts Exports
+# =============================================================================
+
+class DocIndexer:
+    """Scans source files and extracts public exports."""
+
+    def __init__(self, config: DocCoverageConfig):
+        """Initialize the indexer with configuration.
+
+        Args:
+            config: Documentation coverage configuration
+        """
+        self.config = config
+        self._exports_cache: Dict[str, List[DocExport]] = {}
+
+    def scan_directory(self, root_path: str) -> List[DocExport]:
+        """Scan a directory for source files and extract exports.
+
+        Args:
+            root_path: Root directory to scan
+
+        Returns:
+            List of discovered exports
+        """
+        all_exports: List[DocExport] = []
+        root = Path(root_path)
+
+        # Find all matching source files
+        for mapping in self.config.mappings:
+            # Handle glob pattern
+            for source_file in root.glob(mapping.source):
+                if self._is_excluded(str(source_file)):
+                    continue
+
+                relative_path = str(source_file.relative_to(root))
+                exports = self.extract_exports(str(source_file), relative_path)
+                all_exports.extend(exports)
+
+        return all_exports
+
+    def extract_exports(self, file_path: str, relative_path: str) -> List[DocExport]:
+        """Extract public exports from a file.
+
+        Args:
+            file_path: Absolute path to the file
+            relative_path: Relative path for display
+
+        Returns:
+            List of exports from the file
+        """
+        # Check cache
+        if relative_path in self._exports_cache:
+            return self._exports_cache[relative_path]
+
+        exports: List[DocExport] = []
+
+        if file_path.endswith(".py"):
+            exports = self._extract_python_exports(file_path, relative_path)
+        elif file_path.endswith(".md"):
+            exports = self._extract_markdown_command(file_path, relative_path)
+        elif file_path.endswith((".ts", ".tsx", ".js", ".jsx")):
+            exports = self._extract_typescript_exports(file_path, relative_path)
+
+        self._exports_cache[relative_path] = exports
+        return exports
+
+    def _extract_python_exports(self, file_path: str, relative_path: str) -> List[DocExport]:
+        """Extract public exports from a Python file using AST.
+
+        Args:
+            file_path: Path to Python file
+            relative_path: Relative path for display
+
+        Returns:
+            List of public exports
+        """
+        exports: List[DocExport] = []
+
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            tree = ast.parse(content, filename=file_path)
+
+            for node in ast.iter_child_nodes(tree):
+                # Skip private (underscore-prefixed) names
+                name = getattr(node, "name", None)
+                if name and name.startswith("_") and not name.startswith("__"):
+                    continue
+
+                if isinstance(node, ast.FunctionDef):
+                    # Public function
+                    docstring = ast.get_docstring(node)
+                    signature = self._get_function_signature(node)
+                    exports.append(DocExport(
+                        name=node.name,
+                        export_type="function",
+                        source_file=relative_path,
+                        line_number=node.lineno,
+                        docstring=docstring,
+                        signature=signature
+                    ))
+
+                elif isinstance(node, ast.AsyncFunctionDef):
+                    # Async function
+                    docstring = ast.get_docstring(node)
+                    signature = self._get_function_signature(node, async_func=True)
+                    exports.append(DocExport(
+                        name=node.name,
+                        export_type="function",
+                        source_file=relative_path,
+                        line_number=node.lineno,
+                        docstring=docstring,
+                        signature=signature
+                    ))
+
+                elif isinstance(node, ast.ClassDef):
+                    # Public class
+                    if not node.name.startswith("_"):
+                        docstring = ast.get_docstring(node)
+                        exports.append(DocExport(
+                            name=node.name,
+                            export_type="class",
+                            source_file=relative_path,
+                            line_number=node.lineno,
+                            docstring=docstring,
+                            signature=f"class {node.name}"
+                        ))
+
+                elif isinstance(node, ast.Assign):
+                    # Module-level variable (potential export)
+                    for target in node.targets:
+                        if isinstance(target, ast.Name):
+                            if not target.id.startswith("_") and target.id.isupper():
+                                # CONSTANT style variables
+                                exports.append(DocExport(
+                                    name=target.id,
+                                    export_type="variable",
+                                    source_file=relative_path,
+                                    line_number=node.lineno
+                                ))
+
+        except SyntaxError:
+            pass  # Skip files with syntax errors (common in WIP code)
+        except Exception:
+            pass  # Skip files that can't be parsed (encoding issues, etc.)
+
+        return exports
+
+    def _get_function_signature(self, node: ast.FunctionDef, async_func: bool = False) -> str:
+        """Extract function signature from AST node.
+
+        Args:
+            node: AST function definition node
+            async_func: Whether this is an async function
+
+        Returns:
+            Function signature string
+        """
+        args = []
+
+        # Regular arguments
+        for arg in node.args.args:
+            arg_str = arg.arg
+            if arg.annotation:
+                arg_str += f": {ast.unparse(arg.annotation)}"
+            args.append(arg_str)
+
+        # *args
+        if node.args.vararg:
+            args.append(f"*{node.args.vararg.arg}")
+
+        # **kwargs
+        if node.args.kwarg:
+            args.append(f"**{node.args.kwarg.arg}")
+
+        prefix = "async def" if async_func else "def"
+        return_annotation = ""
+        if node.returns:
+            return_annotation = f" -> {ast.unparse(node.returns)}"
+
+        return f"{prefix} {node.name}({', '.join(args)}){return_annotation}"
+
+    def _extract_markdown_command(self, file_path: str, relative_path: str) -> List[DocExport]:
+        """Extract command info from a markdown command file.
+
+        Args:
+            file_path: Path to markdown file
+            relative_path: Relative path for display
+
+        Returns:
+            List containing single command export
+        """
+        exports: List[DocExport] = []
+
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Extract command name from filename or first heading
+            path = Path(file_path)
+            command_name = path.stem
+
+            # Try to get description from first line after heading
+            lines = content.split("\n")
+            description = None
+            for i, line in enumerate(lines):
+                if line.startswith("# "):
+                    # Found heading, look for description
+                    if i + 1 < len(lines) and lines[i + 1].startswith("> "):
+                        description = lines[i + 1][2:].strip()
+                    break
+
+            exports.append(DocExport(
+                name=f"/{command_name}",
+                export_type="command",
+                source_file=relative_path,
+                line_number=1,
+                docstring=description
+            ))
+
+        except Exception:
+            pass  # Best-effort extraction; skip unreadable files
+
+        return exports
+
+    def _extract_typescript_exports(self, file_path: str, relative_path: str) -> List[DocExport]:
+        """Extract exports from TypeScript/JavaScript file using regex.
+
+        Note: This is a simplified implementation. For full accuracy,
+        use TypeScript compiler API.
+
+        Args:
+            file_path: Path to TS/JS file
+            relative_path: Relative path for display
+
+        Returns:
+            List of exports
+        """
+        exports: List[DocExport] = []
+
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Match export function/const/class declarations
+            patterns = [
+                # export function name(
+                (r"export\s+(?:async\s+)?function\s+(\w+)", "function"),
+                # export const name =
+                (r"export\s+const\s+(\w+)\s*=", "variable"),
+                # export class Name
+                (r"export\s+class\s+(\w+)", "class"),
+                # export default function/class
+                (r"export\s+default\s+(?:async\s+)?function\s+(\w+)", "function"),
+                (r"export\s+default\s+class\s+(\w+)", "class"),
+            ]
+
+            for pattern, export_type in patterns:
+                for match in re.finditer(pattern, content):
+                    name = match.group(1)
+                    # Find line number
+                    line_num = content[:match.start()].count("\n") + 1
+
+                    exports.append(DocExport(
+                        name=name,
+                        export_type=export_type,
+                        source_file=relative_path,
+                        line_number=line_num
+                    ))
+
+        except Exception:
+            pass  # Best-effort extraction; skip unreadable files
+
+        return exports
+
+    def _is_excluded(self, file_path: str) -> bool:
+        """Check if a file should be excluded.
+
+        Args:
+            file_path: File path to check
+
+        Returns:
+            True if file should be excluded
+        """
+        # Normalize path separators
+        normalized = file_path.replace("\\", "/")
+
+        for pattern in self.config.exclude:
+            # Handle ** patterns by checking directory containment
+            if pattern.startswith("**/") and pattern.endswith("/**"):
+                # Pattern like **/node_modules/** - check if dir is in path
+                dir_name = pattern[3:-3]  # Extract "node_modules"
+                if f"/{dir_name}/" in f"/{normalized}/" or normalized.startswith(f"{dir_name}/"):
+                    return True
+            elif pattern.startswith("**/"):
+                # Pattern like **/test_*.py - check filename pattern
+                suffix_pattern = pattern[3:]
+                if fnmatch.fnmatch(Path(normalized).name, suffix_pattern):
+                    return True
+                # Also check if any parent dir + filename matches
+                if fnmatch.fnmatch(normalized, f"*/{suffix_pattern}"):
+                    return True
+            else:
+                # Simple fnmatch pattern
+                if fnmatch.fnmatch(normalized, pattern):
+                    return True
+
+        return False
+
+    def clear_cache(self) -> None:
+        """Clear the exports cache."""
+        self._exports_cache.clear()
+
+
+# =============================================================================
+# DocCoverageService - Main Service
+# =============================================================================
+
+class DocCoverageService:
+    """Service for documentation coverage tracking and analysis.
+
+    Provides methods to:
+    - Index source files and extract exports
+    - Check which exports have documentation
+    - Calculate coverage metrics
+    - Detect documentation gaps
+    """
+
+    def __init__(self, project_path: Optional[str] = None, config: Optional[DocCoverageConfig] = None):
+        """Initialize the documentation coverage service.
+
+        Args:
+            project_path: Root path of the project (defaults to cwd)
+            config: Coverage configuration (defaults to standard config)
+        """
+        self.project_path = Path(project_path) if project_path else Path.cwd()
+        self.config = config or DocCoverageConfig.default()
+        self.indexer = DocIndexer(self.config)
+        self._doc_index: Dict[str, Set[str]] = {}  # doc_path -> set of documented items
+
+    def index_documentation(self) -> Dict[str, Set[str]]:
+        """Index all documentation files to find what's documented.
+
+        Returns:
+            Dict mapping doc paths to sets of documented export names
+        """
+        self._doc_index.clear()
+
+        for mapping in self.config.mappings:
+            # Get all potential doc files
+            doc_pattern = mapping.docs.replace("{basename}", "*").replace("{dirname}", "*")
+
+            for doc_file in self.project_path.glob(doc_pattern):
+                if not doc_file.exists():
+                    continue
+
+                relative_path = str(doc_file.relative_to(self.project_path))
+                documented_items = self._extract_documented_items(str(doc_file), mapping.doc_type)
+                self._doc_index[relative_path] = documented_items
+
+        # Also check README files and index files
+        readme_patterns = [
+            ".claude/hooks/README.md",
+            "global/hooks/README.md",
+            "docs/command-reference.md",
+            "docs/api/*.md"
+        ]
+
+        for pattern in readme_patterns:
+            for doc_file in self.project_path.glob(pattern):
+                if doc_file.exists():
+                    relative_path = str(doc_file.relative_to(self.project_path))
+                    if relative_path not in self._doc_index:
+                        documented_items = self._extract_documented_items(str(doc_file), "mixed")
+                        self._doc_index[relative_path] = documented_items
+
+        return self._doc_index
+
+    def _extract_documented_items(self, doc_path: str, doc_type: str) -> Set[str]:
+        """Extract names of documented items from a doc file.
+
+        Args:
+            doc_path: Path to documentation file
+            doc_type: Type of documentation (api, command, hook, etc.)
+
+        Returns:
+            Set of documented item names
+        """
+        documented: Set[str] = set()
+
+        try:
+            with open(doc_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Look for documented items based on doc type
+            if doc_type in ("api", "mixed"):
+                # Look for function/class references
+                # Pattern: ## FunctionName or ### `function_name`
+                patterns = [
+                    r"^##\s+(\w+)",           # ## FunctionName
+                    r"^###\s+`?(\w+)`?",      # ### `function_name`
+                    r"^\*\*(\w+)\*\*",        # **function_name**
+                    r"`(\w+)\(\)`",           # `function_name()`
+                    r"def\s+(\w+)\(",         # def function_name(
+                    r"class\s+(\w+)",         # class ClassName
+                ]
+                for pattern in patterns:
+                    for match in re.finditer(pattern, content, re.MULTILINE):
+                        documented.add(match.group(1))
+
+            if doc_type in ("command", "mixed"):
+                # Look for command references
+                patterns = [
+                    r"^##\s+/(\w+)",           # ## /command
+                    r"^\| `/(\w+)`",           # | `/command`
+                    r"`/(\w+)`",               # `/command`
+                ]
+                for pattern in patterns:
+                    for match in re.finditer(pattern, content, re.MULTILINE):
+                        documented.add(f"/{match.group(1)}")
+
+            if doc_type in ("hook", "mixed"):
+                # Look for hook references
+                patterns = [
+                    r"(\w+)\.py",              # hook_name.py
+                    r"^##\s+(\w+)",            # ## HookName
+                ]
+                for pattern in patterns:
+                    for match in re.finditer(pattern, content, re.MULTILINE):
+                        documented.add(match.group(1))
+
+        except Exception:
+            pass  # Best-effort extraction; skip unreadable doc files
+
+        return documented
+
+    def calculate_coverage(self) -> CoverageResult:
+        """Calculate documentation coverage for the project.
+
+        Returns:
+            CoverageResult with coverage metrics and gaps
+        """
+        # Index documentation first
+        self.index_documentation()
+
+        # Scan for all exports
+        all_exports = self.indexer.scan_directory(str(self.project_path))
+
+        # Check which exports are documented
+        documented_count = 0
+        gaps: List[DocGap] = []
+        by_type: Dict[str, Dict[str, int]] = {}
+
+        for export in all_exports:
+            # Find the mapping for this export
+            mapping = self._find_mapping(export.source_file)
+            if not mapping:
+                continue
+
+            # Initialize type counters
+            if mapping.doc_type not in by_type:
+                by_type[mapping.doc_type] = {"total": 0, "documented": 0}
+            by_type[mapping.doc_type]["total"] += 1
+
+            # Check if documented
+            expected_doc = mapping.get_doc_path(export.source_file)
+            is_documented = self._is_documented(export, expected_doc)
+
+            if is_documented:
+                documented_count += 1
+                by_type[mapping.doc_type]["documented"] += 1
+            else:
+                gaps.append(DocGap(
+                    export=export,
+                    expected_doc=expected_doc,
+                    doc_type=mapping.doc_type,
+                    severity="missing",
+                    suggestion=f"Add documentation for {export.name} in {expected_doc}"
+                ))
+
+        total = len(all_exports)
+        percent = (documented_count / total * 100) if total > 0 else 100.0
+
+        return CoverageResult(
+            total_exports=total,
+            documented_exports=documented_count,
+            coverage_percent=round(percent, 1),
+            gaps=gaps,
+            by_type=by_type
+        )
+
+    def _find_mapping(self, source_path: str) -> Optional[DocMapping]:
+        """Find the mapping configuration for a source file.
+
+        Args:
+            source_path: Relative path to source file
+
+        Returns:
+            Matching DocMapping or None
+        """
+        for mapping in self.config.mappings:
+            if mapping.matches(source_path):
+                return mapping
+        return None
+
+    def _is_documented(self, export: DocExport, _expected_doc: str) -> bool:
+        """Check if an export is documented.
+
+        Args:
+            export: The export to check
+            _expected_doc: Expected documentation path (reserved for future use)
+
+        Returns:
+            True if the export appears to be documented
+        """
+        # Check if export has a docstring (self-documenting)
+        if export.docstring and len(export.docstring) > 20:
+            return True
+
+        # Check indexed documentation
+        for _doc_path, documented_items in self._doc_index.items():
+            # Check if the export name appears in documented items
+            if export.name in documented_items:
+                return True
+
+            # For commands, check with slash prefix
+            if export.export_type == "command":
+                cmd_name = export.name.lstrip("/")
+                if cmd_name in documented_items or f"/{cmd_name}" in documented_items:
+                    return True
+
+        return False
+
+    def get_gaps(self) -> List[DocGap]:
+        """Get list of documentation gaps.
+
+        Returns:
+            List of DocGap objects
+        """
+        result = self.calculate_coverage()
+        return result.gaps
+
+    def generate_report(self, output_format: Literal["markdown", "json"] = "markdown") -> str:
+        """Generate a coverage report.
+
+        Args:
+            output_format: Output format (markdown or json)
+
+        Returns:
+            Report string
+        """
+        result = self.calculate_coverage()
+
+        if output_format == "json":
+            return json.dumps({
+                "total_exports": result.total_exports,
+                "documented_exports": result.documented_exports,
+                "coverage_percent": result.coverage_percent,
+                "status": result.status,
+                "by_type": result.by_type,
+                "gaps": [
+                    {
+                        "name": gap.export.name,
+                        "type": gap.export.export_type,
+                        "source": gap.export.source_file,
+                        "line": gap.export.line_number,
+                        "expected_doc": gap.expected_doc,
+                        "suggestion": gap.suggestion
+                    }
+                    for gap in result.gaps
+                ],
+                "timestamp": result.timestamp
+            }, indent=2)
+
+        # Markdown report
+        lines = [
+            "---",
+            f"generated: {result.timestamp}",
+            f"coverage: {result.coverage_percent}%",
+            f"status: {result.status}",
+            "---",
+            "",
+            "# Documentation Coverage Report",
+            "",
+            "## Summary",
+            "",
+            "| Metric | Value | Status |",
+            "|--------|-------|--------|",
+            f"| Total Exports | {result.total_exports} | — |",
+            f"| Documented | {result.documented_exports} | — |",
+            f"| Coverage | {result.coverage_percent}% | {result.status_emoji} {result.status.title()} |",
+            "",
+        ]
+
+        # Coverage by type
+        if result.by_type:
+            lines.extend([
+                "## Coverage by Type",
+                "",
+                "| Type | Total | Documented | Coverage |",
+                "|------|-------|------------|----------|",
+            ])
+            for doc_type, counts in result.by_type.items():
+                type_pct = (counts["documented"] / counts["total"] * 100) if counts["total"] > 0 else 100
+                lines.append(f"| {doc_type} | {counts['total']} | {counts['documented']} | {type_pct:.1f}% |")
+            lines.append("")
+
+        # Gaps
+        if result.gaps:
+            lines.extend([
+                "## Undocumented Exports",
+                "",
+                "| Export | Type | Source | Line | Suggested Doc |",
+                "|--------|------|--------|------|---------------|",
+            ])
+            for gap in result.gaps[:20]:  # Limit to 20 for readability
+                lines.append(
+                    f"| `{gap.export.name}` | {gap.export.export_type} | "
+                    f"{gap.export.source_file} | {gap.export.line_number} | {gap.expected_doc} |"
+                )
+
+            if len(result.gaps) > 20:
+                lines.append(f"| ... | ... | ... | ... | ({len(result.gaps) - 20} more) |")
+            lines.append("")
+        else:
+            lines.extend([
+                "## Undocumented Exports",
+                "",
+                "No documentation gaps found! 🎉",
+                ""
+            ])
+
+        return "\n".join(lines)
+
+    def check(self, threshold: Optional[int] = None) -> bool:
+        """Check if coverage meets threshold.
+
+        Args:
+            threshold: Coverage threshold (defaults to config warning threshold)
+
+        Returns:
+            True if coverage meets threshold
+        """
+        if threshold is None:
+            threshold = self.config.thresholds.get("warning", 80)
+
+        result = self.calculate_coverage()
+        return result.coverage_percent >= threshold
+
+    def detect_stale_docs(
+        self,
+        sensitivity: Optional[Literal["aggressive", "balanced", "quiet"]] = None,
+    ) -> GapDetectionResult:
+        """Detect potentially stale documentation using GapDetector.
+
+        Args:
+            sensitivity: Detection sensitivity level (defaults to config value):
+                - aggressive: Flag any timestamp difference
+                - balanced: Flag docs >7 days stale
+                - quiet: Flag docs >30 days stale
+
+        Returns:
+            GapDetectionResult with stale docs and changed files,
+            or empty result if gap detection is disabled
+        """
+        # Check if gap detection is disabled via config
+        if not self.config.gap_detection_enabled:
+            return GapDetectionResult(
+                stale_docs=[],
+                changed_files_without_docs=[],
+                total_warnings=0,
+                sensitivity=sensitivity or self.config.sensitivity,
+            )
+
+        sens = sensitivity or self.config.sensitivity
+        detector = GapDetector(self.config, sensitivity=sens)
+        return detector.analyze(str(self.project_path))
+
+    def get_session_warnings(
+        self,
+        sensitivity: Optional[Literal["aggressive", "balanced", "quiet"]] = None,
+    ) -> str:
+        """Get documentation warnings formatted for session context injection.
+
+        This is the main entry point for SessionStart hooks to get warnings
+        that can be injected into the session context.
+
+        Args:
+            sensitivity: Detection sensitivity level (defaults to config value)
+
+        Returns:
+            Formatted markdown block for session context, or empty string if
+            no warnings or gap detection is disabled
+        """
+        result = self.detect_stale_docs(sensitivity=sensitivity)
+        return result.to_context_block()
+
+
+# =============================================================================
+# State Integration
+# =============================================================================
+
+def _sync_coverage_to_state(result: CoverageResult) -> None:
+    """Sync coverage result to anvil-state.json for tracking."""
+    if not STATE_MANAGER_AVAILABLE:
+        return
+
+    try:
+        _sync_state(
+            percent=result.coverage_percent,
+            total=result.total_exports,
+            documented=result.documented_exports,
+            status=result.status,
+        )
+    except Exception:
+        # Don't fail CLI if state sync fails
+        pass
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+def main():
+    """CLI entry point for doc coverage service."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Documentation Coverage System (ANV-31)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    python doc_coverage_service.py --report
+    python doc_coverage_service.py --check
+    python doc_coverage_service.py --gaps
+    python doc_coverage_service.py --json
+        """
+    )
+
+    parser.add_argument(
+        "--report",
+        action="store_true",
+        help="Generate full coverage report"
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check coverage against threshold (exits 1 if below)"
+    )
+    parser.add_argument(
+        "--gaps",
+        action="store_true",
+        help="Show only documentation gaps"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format"
+    )
+    parser.add_argument(
+        "--threshold",
+        type=int,
+        default=80,
+        help="Coverage threshold for --check (default: 80)"
+    )
+    parser.add_argument(
+        "--project",
+        type=str,
+        default=".",
+        help="Project path (default: current directory)"
+    )
+
+    args = parser.parse_args()
+
+    # Initialize service
+    service = DocCoverageService(project_path=args.project)
+
+    if args.check:
+        # Check mode - exit with code 1 if below threshold
+        # Calculate once and use result for both check and display
+        result = service.calculate_coverage()
+        _sync_coverage_to_state(result)  # Sync to anvil-state.json
+        passed = result.coverage_percent >= args.threshold
+
+        if passed:
+            print(f"✅ Coverage: {result.coverage_percent}% (threshold: {args.threshold}%)")
+            return 0
+        else:
+            print(f"❌ Coverage: {result.coverage_percent}% (threshold: {args.threshold}%)")
+            print(f"   {len(result.gaps)} undocumented exports")
+            return 1
+
+    elif args.gaps:
+        # Show only gaps
+        gaps = service.get_gaps()
+
+        if not gaps:
+            print("No documentation gaps found! 🎉")
+            return 0
+
+        if args.json:
+            print(json.dumps([
+                {
+                    "name": g.export.name,
+                    "type": g.export.export_type,
+                    "source": g.export.source_file,
+                    "line": g.export.line_number,
+                    "expected_doc": g.expected_doc
+                }
+                for g in gaps
+            ], indent=2))
+        else:
+            print(f"Found {len(gaps)} documentation gaps:\n")
+            for gap in gaps:
+                print(f"  • {gap.export.name} ({gap.export.export_type})")
+                print(f"    Source: {gap.export.source_file}:{gap.export.line_number}")
+                print(f"    Expected: {gap.expected_doc}")
+                print()
+        return 0
+
+    else:
+        # Full report (default)
+        # Calculate coverage for state sync, then generate report
+        result = service.calculate_coverage()
+        _sync_coverage_to_state(result)  # Sync to anvil-state.json
+
+        output_format = "json" if args.json else "markdown"
+        report = service.generate_report(output_format=output_format)
+        print(report)
+        return 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())