Doc Drift Detector

{
  "repository": "/path/to/example-project",
  "scan_date": "2026-03-18T14:30:00Z",
  "tool_version": "2.0.0",
  "summary": {
    "total_docs": 8,
    "drifted_docs": 3,
    "overall_score": 62,
    "broken_links": 5,
    "api_mismatches": 7
  },
  "staleness_scores": [
    {"file": "README.md", "score": 78, "last_updated": "2026-03-01", "status": "good"},
    {"file": "docs/api.md", "score": 34, "last_updated": "2025-12-15", "status": "critical"},
    {"file": "docs/architecture.md", "score": 85, "last_updated": "2026-02-20", "status": "good"},
    {"file": "CONTRIBUTING.md", "score": 92, "last_updated": "2026-03-10", "status": "excellent"},
    {"file": "CHANGELOG.md", "score": 45, "last_updated": "2026-01-30", "status": "stale"},
    {"file": "docs/deployment.md", "score": 58, "last_updated": "2026-02-01", "status": "stale"},
    {"file": "docs/testing.md", "score": 71, "last_updated": "2026-02-15", "status": "good"},
    {"file": "docs/security.md", "score": 88, "last_updated": "2026-03-05", "status": "good"}
  ],
  "drift_issues": [
    {
      "file": "docs/api.md",
      "severity": "high",
      "category": "factual",
      "description": "Function create_user() signature changed: added 'role' parameter",
      "fix_type": "semi",
      "source_file": "src/handlers/users.py",
      "source_line": 45
    },
    {
      "file": "README.md",
      "severity": "medium",
      "category": "temporal",
      "description": "Version string says 1.8.0, current version is 2.0.0",
      "fix_type": "auto",
      "source_file": "pyproject.toml",
      "source_line": 3
    },
    {
      "file": "docs/api.md",
      "severity": "high",
      "category": "structural",
      "description": "Module 'src/handlers/webhooks.py' has no documentation section",
      "fix_type": "manual",
      "source_file": "src/handlers/webhooks.py",
      "source_line": null
    },
    {
      "file": "CHANGELOG.md",
      "severity": "medium",
      "category": "structural",
      "description": "No entries for version 2.0.0 (released 2026-03-15)",
      "fix_type": "semi",
      "source_file": null,
      "source_line": null
    },
    {
      "file": "docs/deployment.md",
      "severity": "low",
      "category": "referential",
      "description": "Link to 'scripts/deploy.sh' broken - file moved to 'bin/deploy.sh'",
      "fix_type": "auto",
      "source_file": "bin/deploy.sh",
      "source_line": null
    }
  ],
  "score_breakdown": {
    "last_updated": {"weight": 0.20, "score": 65, "weighted": 13.0},
    "code_doc_alignment": {"weight": 0.30, "score": 48, "weighted": 14.4},
    "link_health": {"weight": 0.15, "score": 72, "weighted": 10.8},
    "completeness": {"weight": 0.20, "score": 70, "weighted": 14.0},
    "accuracy": {"weight": 0.15, "score": 65, "weighted": 9.75}
  }
}

#!/usr/bin/env python3
"""
API Documentation Validator

Extracts function and class signatures from Python source files using the ast module
and compares them against API documentation in markdown files.

Detects:
- Functions/classes in code but missing from docs
- Functions/classes documented but removed from code
- Parameter mismatches (missing, extra, wrong defaults)
- Deprecated items still documented as current
- Return type annotation mismatches

Usage:
    python api_doc_validator.py /path/to/src /path/to/docs/api.md
    python api_doc_validator.py /path/to/src /path/to/docs/ --recursive
    python api_doc_validator.py /path/to/src /path/to/docs/api.md --json
    python api_doc_validator.py /path/to/src /path/to/docs/ --include-private
"""

import argparse
import ast
import json
import os
import re
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple


# --- AST Source Extraction ---

class SourceSignature:
    """Represents an extracted function or class signature."""

    def __init__(
        self,
        name: str,
        kind: str,  # "function", "method", "class"
        file_path: str,
        line_number: int,
        parameters: List[Dict[str, Any]],
        return_annotation: Optional[str] = None,
        decorators: Optional[List[str]] = None,
        docstring: Optional[str] = None,
        is_private: bool = False,
        parent_class: Optional[str] = None,
    ):
        self.name = name
        self.kind = kind
        self.file_path = file_path
        self.line_number = line_number
        self.parameters = parameters
        self.return_annotation = return_annotation
        self.decorators = decorators or []
        self.docstring = docstring
        self.is_private = is_private
        self.parent_class = parent_class

    @property
    def qualified_name(self) -> str:
        if self.parent_class:
            return f"{self.parent_class}.{self.name}"
        return self.name

    @property
    def is_deprecated(self) -> bool:
        return any("deprecated" in d.lower() for d in self.decorators)

    def to_dict(self) -> Dict[str, Any]:
        return {
            "name": self.name,
            "qualified_name": self.qualified_name,
            "kind": self.kind,
            "file": self.file_path,
            "line": self.line_number,
            "parameters": self.parameters,
            "return_annotation": self.return_annotation,
            "decorators": self.decorators,
            "is_private": self.is_private,
            "is_deprecated": self.is_deprecated,
        }


def _annotation_to_str(node: Optional[ast.expr]) -> Optional[str]:
    """Convert an AST annotation node to a string representation."""
    if node is None:
        return None
    try:
        return ast.unparse(node)
    except AttributeError:
        # Python < 3.9 fallback
        if isinstance(node, ast.Name):
            return node.id
        elif isinstance(node, ast.Constant):
            return repr(node.value)
        elif isinstance(node, ast.Attribute):
            return f"{_annotation_to_str(node.value)}.{node.attr}"
        elif isinstance(node, ast.Subscript):
            return f"{_annotation_to_str(node.value)}[{_annotation_to_str(node.slice)}]"
        return str(type(node).__name__)


def _extract_decorator_names(decorator_list: List[ast.expr]) -> List[str]:
    """Extract decorator names from AST decorator list."""
    names = []
    for dec in decorator_list:
        if isinstance(dec, ast.Name):
            names.append(dec.id)
        elif isinstance(dec, ast.Attribute):
            names.append(f"{_annotation_to_str(dec.value)}.{dec.attr}")
        elif isinstance(dec, ast.Call):
            if isinstance(dec.func, ast.Name):
                names.append(dec.func.id)
            elif isinstance(dec.func, ast.Attribute):
                names.append(f"{_annotation_to_str(dec.func.value)}.{dec.func.attr}")
    return names


def _extract_parameters(func_node: ast.FunctionDef) -> List[Dict[str, Any]]:
    """Extract parameter information from a function definition."""
    params = []
    args = func_node.args

    # Calculate defaults offset
    num_args = len(args.args)
    num_defaults = len(args.defaults)
    default_offset = num_args - num_defaults

    for i, arg in enumerate(args.args):
        if arg.arg == "self" or arg.arg == "cls":
            continue
        param: Dict[str, Any] = {
            "name": arg.arg,
            "annotation": _annotation_to_str(arg.annotation),
            "has_default": False,
            "default": None,
        }
        # Check if this arg has a default
        default_idx = i - default_offset
        if default_idx >= 0 and default_idx < len(args.defaults):
            param["has_default"] = True
            try:
                param["default"] = ast.unparse(args.defaults[default_idx])
            except AttributeError:
                param["default"] = "..."
        params.append(param)

    # *args
    if args.vararg:
        params.append({
            "name": f"*{args.vararg.arg}",
            "annotation": _annotation_to_str(args.vararg.annotation),
            "has_default": False,
            "default": None,
        })

    # keyword-only args
    for i, arg in enumerate(args.kwonlyargs):
        param = {
            "name": arg.arg,
            "annotation": _annotation_to_str(arg.annotation),
            "has_default": False,
            "default": None,
        }
        if i < len(args.kw_defaults) and args.kw_defaults[i] is not None:
            param["has_default"] = True
            try:
                param["default"] = ast.unparse(args.kw_defaults[i])
            except AttributeError:
                param["default"] = "..."
        params.append(param)

    # **kwargs
    if args.kwarg:
        params.append({
            "name": f"**{args.kwarg.arg}",
            "annotation": _annotation_to_str(args.kwarg.annotation),
            "has_default": False,
            "default": None,
        })

    return params


def extract_signatures(source_path: str, include_private: bool = False) -> List[SourceSignature]:
    """Extract all function and class signatures from a Python file."""
    signatures = []
    try:
        with open(source_path, "r", encoding="utf-8", errors="ignore") as f:
            source = f.read()
        tree = ast.parse(source, filename=source_path)
    except (SyntaxError, OSError, IOError):
        return signatures

    rel_path = source_path  # Will be made relative by caller

    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) or isinstance(node, ast.AsyncFunctionDef):
            is_private = node.name.startswith("_")
            if is_private and not include_private:
                continue

            # Determine if it's a method (inside a class)
            parent_class = None
            kind = "function"
            for parent in ast.walk(tree):
                if isinstance(parent, ast.ClassDef):
                    for item in parent.body:
                        if item is node:
                            parent_class = parent.name
                            kind = "method"
                            break

            docstring = ast.get_docstring(node)
            decorators = _extract_decorator_names(node.decorator_list)
            parameters = _extract_parameters(node)
            return_annotation = _annotation_to_str(node.returns)

            sig = SourceSignature(
                name=node.name,
                kind=kind,
                file_path=rel_path,
                line_number=node.lineno,
                parameters=parameters,
                return_annotation=return_annotation,
                decorators=decorators,
                docstring=docstring,
                is_private=is_private,
                parent_class=parent_class,
            )
            signatures.append(sig)

        elif isinstance(node, ast.ClassDef):
            is_private = node.name.startswith("_")
            if is_private and not include_private:
                continue

            docstring = ast.get_docstring(node)
            decorators = _extract_decorator_names(node.decorator_list)

            # Extract __init__ params as the class params
            init_params = []
            for item in node.body:
                if isinstance(item, ast.FunctionDef) and item.name == "__init__":
                    init_params = _extract_parameters(item)
                    break

            sig = SourceSignature(
                name=node.name,
                kind="class",
                file_path=rel_path,
                line_number=node.lineno,
                parameters=init_params,
                decorators=decorators,
                docstring=docstring,
                is_private=is_private,
            )
            signatures.append(sig)

    return signatures


def extract_all_signatures(
    source_dir: str, include_private: bool = False
) -> Dict[str, List[SourceSignature]]:
    """Extract signatures from all Python files in a directory."""
    all_sigs: Dict[str, List[SourceSignature]] = {}
    skip_dirs = {"__pycache__", ".venv", "venv", ".git", "node_modules", ".tox"}

    for root, dirs, files in os.walk(source_dir):
        dirs[:] = [d for d in dirs if d not in skip_dirs]
        for f in files:
            if f.endswith(".py"):
                full_path = os.path.join(root, f)
                rel_path = os.path.relpath(full_path, source_dir)
                sigs = extract_signatures(full_path, include_private)
                # Update file paths to be relative
                for s in sigs:
                    s.file_path = rel_path
                if sigs:
                    all_sigs[rel_path] = sigs

    return all_sigs


# --- Documentation Parsing ---

def extract_documented_items(doc_path: str) -> Dict[str, Dict[str, Any]]:
    """Extract function/class references from markdown documentation."""
    items: Dict[str, Dict[str, Any]] = {}

    try:
        with open(doc_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return items

    lines = content.splitlines()

    # Pattern 1: Function headings like ### `function_name()` or ### function_name
    heading_func = re.compile(r'^#{1,6}\s+`?(\w+(?:\.\w+)*)\(`?.*\)?`?\s*$')
    # Pattern 2: Function in backticks with params like `function_name(param1, param2)`
    inline_func = re.compile(r'`(\w+(?:\.\w+)*)\(([^)]*)\)`')
    # Pattern 3: Class headings like ### class ClassName or ### ClassName
    heading_class = re.compile(r'^#{1,6}\s+(?:class\s+)?`?(\w+)`?\s*$')
    # Pattern 4: Parameter lists like - `param_name` (type): description
    param_pattern = re.compile(r'^\s*[-*]\s+`(\w+)`\s*(?:\(([^)]+)\))?\s*(?::|--)?\s*(.*)')

    current_item = None
    current_params: List[Dict[str, Any]] = []

    for i, line in enumerate(lines):
        # Check for function heading
        match = heading_func.match(line)
        if match:
            if current_item and current_item in items:
                items[current_item]["parameters"] = current_params

            func_name = match.group(1)
            items[func_name] = {
                "name": func_name,
                "line": i + 1,
                "kind": "function",
                "file": doc_path,
                "parameters": [],
            }
            current_item = func_name
            current_params = []
            continue

        # Check for inline function definitions
        for match in inline_func.finditer(line):
            func_name = match.group(1)
            param_str = match.group(2)
            if func_name not in items:
                params = []
                if param_str:
                    for p in param_str.split(","):
                        p = p.strip()
                        if p and p not in ("self", "cls", "..."):
                            # Handle type annotations like param: type
                            parts = p.split(":")
                            param_name = parts[0].strip().split("=")[0].strip()
                            if param_name and param_name.replace("*", "").isidentifier():
                                params.append({"name": param_name})
                items[func_name] = {
                    "name": func_name,
                    "line": i + 1,
                    "kind": "function",
                    "file": doc_path,
                    "parameters": params,
                }

        # Check for parameter list items
        param_match = param_pattern.match(line)
        if param_match and current_item:
            param_name = param_match.group(1)
            param_type = param_match.group(2)
            current_params.append({
                "name": param_name,
                "annotation": param_type,
            })

    # Finalize last item
    if current_item and current_item in items:
        items[current_item]["parameters"] = current_params

    return items


def extract_all_documented_items(
    doc_path: str, recursive: bool = False
) -> Dict[str, Dict[str, Any]]:
    """Extract documented items from one or more markdown files."""
    all_items: Dict[str, Dict[str, Any]] = {}

    if os.path.isfile(doc_path):
        return extract_documented_items(doc_path)

    if os.path.isdir(doc_path) and recursive:
        for root, dirs, files in os.walk(doc_path):
            dirs[:] = [d for d in dirs if d not in {".git", "node_modules"}]
            for f in files:
                if f.endswith((".md", ".rst")):
                    full_path = os.path.join(root, f)
                    items = extract_documented_items(full_path)
                    all_items.update(items)
    elif os.path.isdir(doc_path):
        # Non-recursive: just top-level files
        for f in os.listdir(doc_path):
            if f.endswith((".md", ".rst")):
                full_path = os.path.join(doc_path, f)
                items = extract_documented_items(full_path)
                all_items.update(items)

    return all_items


# --- Validation ---

def validate_api_docs(
    source_sigs: Dict[str, List[SourceSignature]],
    documented_items: Dict[str, Dict[str, Any]],
) -> List[Dict[str, Any]]:
    """Compare source signatures against documented items and find mismatches."""
    issues = []

    # Build lookup of all source signatures by name and qualified name
    source_by_name: Dict[str, SourceSignature] = {}
    for file_sigs in source_sigs.values():
        for sig in file_sigs:
            source_by_name[sig.name] = sig
            source_by_name[sig.qualified_name] = sig

    documented_names = set(documented_items.keys())
    source_names = set(source_by_name.keys())

    # 1. Documented but not in source (removed or renamed)
    for name in documented_names:
        if name not in source_names:
            doc_item = documented_items[name]
            issues.append({
                "type": "documented_not_in_source",
                "severity": "high",
                "name": name,
                "doc_file": doc_item.get("file", "unknown"),
                "doc_line": doc_item.get("line", 0),
                "description": f"'{name}' is documented but not found in source code (removed or renamed)",
            })

    # 2. In source but not documented
    for name, sig in source_by_name.items():
        # Skip qualified names that are also present as simple names
        if "." in name and name.split(".")[-1] in source_by_name:
            # Only report on the simple name to avoid duplicates
            continue
        if name not in documented_names and sig.qualified_name not in documented_names:
            if not sig.is_private:
                issues.append({
                    "type": "undocumented",
                    "severity": "medium",
                    "name": sig.qualified_name,
                    "source_file": sig.file_path,
                    "source_line": sig.line_number,
                    "description": f"'{sig.qualified_name}' ({sig.kind}) exists in source but is not documented",
                })

    # 3. Parameter mismatches
    for name in documented_names & source_names:
        sig = source_by_name[name]
        doc_item = documented_items[name]

        doc_params = doc_item.get("parameters", [])
        source_params = sig.parameters

        if not doc_params and not source_params:
            continue

        doc_param_names = {p["name"] for p in doc_params if "name" in p}
        source_param_names = {
            p["name"].lstrip("*") for p in source_params if "name" in p
        }

        # Parameters in source but not in docs
        missing_in_docs = source_param_names - doc_param_names
        for param in missing_in_docs:
            if param not in ("self", "cls"):
                issues.append({
                    "type": "missing_param_in_docs",
                    "severity": "medium",
                    "name": name,
                    "parameter": param,
                    "source_file": sig.file_path,
                    "source_line": sig.line_number,
                    "description": f"Parameter '{param}' of '{name}' exists in source but not in docs",
                })

        # Parameters in docs but not in source
        extra_in_docs = doc_param_names - source_param_names
        for param in extra_in_docs:
            issues.append({
                "type": "extra_param_in_docs",
                "severity": "medium",
                "name": name,
                "parameter": param,
                "doc_file": doc_item.get("file", "unknown"),
                "doc_line": doc_item.get("line", 0),
                "description": f"Parameter '{param}' documented for '{name}' but not in source",
            })

    # 4. Deprecated items still documented without deprecation notice
    for name in documented_names & source_names:
        sig = source_by_name[name]
        if sig.is_deprecated:
            doc_item = documented_items[name]
            # Check if doc mentions "deprecated"
            # This is a simple heuristic; we check the item's doc context
            issues.append({
                "type": "deprecated_still_documented",
                "severity": "low",
                "name": name,
                "source_file": sig.file_path,
                "source_line": sig.line_number,
                "description": f"'{name}' has @deprecated decorator but may still be documented as current",
            })

    return issues


# --- Report ---

def generate_report(issues: List[Dict[str, Any]], source_count: int, doc_count: int, as_json: bool = False) -> str:
    """Generate a validation report."""
    report_data = {
        "summary": {
            "source_signatures": source_count,
            "documented_items": doc_count,
            "total_issues": len(issues),
            "by_type": {},
            "by_severity": {},
        },
        "issues": issues,
    }

    for issue in issues:
        itype = issue.get("type", "unknown")
        sev = issue.get("severity", "unknown")
        report_data["summary"]["by_type"][itype] = report_data["summary"]["by_type"].get(itype, 0) + 1
        report_data["summary"]["by_severity"][sev] = report_data["summary"]["by_severity"].get(sev, 0) + 1

    if as_json:
        return json.dumps(report_data, indent=2, default=str)

    lines = []
    lines.append("API Documentation Validation Report")
    lines.append("=" * 60)
    lines.append(f"Source signatures found: {source_count}")
    lines.append(f"Documented items found:  {doc_count}")
    lines.append(f"Issues found:            {len(issues)}")
    lines.append("")

    if not issues:
        lines.append("No issues found. API documentation matches source code.")
        return "\n".join(lines)

    # Group by severity
    severity_order = ["high", "medium", "low"]
    for severity in severity_order:
        sev_issues = [i for i in issues if i.get("severity") == severity]
        if not sev_issues:
            continue
        lines.append(f"{severity.upper()} ({len(sev_issues)} issues):")
        lines.append("-" * 40)
        for issue in sev_issues:
            lines.append(f"  [{issue.get('type', 'unknown')}] {issue['description']}")
            if "source_file" in issue:
                lines.append(f"    Source: {issue['source_file']}:{issue.get('source_line', '?')}")
            if "doc_file" in issue:
                lines.append(f"    Doc:    {issue['doc_file']}:{issue.get('doc_line', '?')}")
            lines.append("")
        lines.append("")

    # Summary by type
    lines.append("SUMMARY BY TYPE:")
    lines.append("-" * 40)
    type_labels = {
        "undocumented": "Undocumented items",
        "documented_not_in_source": "Documented but not in source",
        "missing_param_in_docs": "Missing parameters in docs",
        "extra_param_in_docs": "Extra parameters in docs",
        "deprecated_still_documented": "Deprecated items still documented",
    }
    for itype, count in sorted(report_data["summary"]["by_type"].items()):
        label = type_labels.get(itype, itype)
        lines.append(f"  {label}: {count}")

    return "\n".join(lines)


# --- Main ---

def main():
    parser = argparse.ArgumentParser(
        description="Validate API documentation against Python source code",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("source_path", help="Path to Python source directory")
    parser.add_argument("doc_path", help="Path to API documentation (file or directory)")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--recursive", action="store_true", help="Recursively scan doc directory")
    parser.add_argument("--include-private", action="store_true", help="Include private (_prefixed) items")

    args = parser.parse_args()

    source_path = os.path.abspath(args.source_path)
    doc_path = os.path.abspath(args.doc_path)

    if not os.path.exists(source_path):
        print(f"Error: Source path '{source_path}' does not exist", file=sys.stderr)
        sys.exit(2)

    if not os.path.exists(doc_path):
        print(f"Error: Doc path '{doc_path}' does not exist", file=sys.stderr)
        sys.exit(2)

    # Extract source signatures
    if os.path.isfile(source_path) and source_path.endswith(".py"):
        sigs = extract_signatures(source_path, args.include_private)
        source_sigs = {os.path.basename(source_path): sigs}
    elif os.path.isdir(source_path):
        source_sigs = extract_all_signatures(source_path, args.include_private)
    else:
        print(f"Error: Source path must be a Python file or directory", file=sys.stderr)
        sys.exit(2)

    # Extract documented items
    documented_items = extract_all_documented_items(doc_path, recursive=args.recursive)

    # Count totals
    source_count = sum(len(sigs) for sigs in source_sigs.values())
    doc_count = len(documented_items)

    # Validate
    issues = validate_api_docs(source_sigs, documented_items)

    # Report
    report = generate_report(issues, source_count, doc_count, as_json=args.json)
    print(report)

    # Exit code
    has_high = any(i.get("severity") == "high" for i in issues)
    sys.exit(1 if has_high else 0)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Documentation Staleness Scorer

Scores documentation freshness on a 0-100 scale using five weighted dimensions:
- Last Updated (20%): How recently the doc was modified
- Code-Doc Alignment (30%): Whether documented items still match code
- Link Health (15%): Percentage of links that resolve
- Completeness (20%): Whether expected sections exist
- Accuracy (15%): Version strings, file paths, verifiable facts

Usage:
    python doc_staleness_scorer.py /path/to/repo
    python doc_staleness_scorer.py /path/to/repo --json
    python doc_staleness_scorer.py /path/to/repo --threshold 60
    python doc_staleness_scorer.py /path/to/repo --readme-focus
    python doc_staleness_scorer.py /path/to/repo --required-sections "Installation,Usage,API"
"""

import argparse
import json
import os
import re
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


# --- Constants ---

DOC_EXTENSIONS = {".md", ".rst", ".txt", ".adoc"}
CODE_EXTENSIONS = {
    ".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".java",
    ".c", ".cpp", ".h", ".hpp", ".rb", ".php",
}
SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".tox", "dist", "build"}

DEFAULT_WEIGHTS = {
    "last_updated": 0.20,
    "code_doc_alignment": 0.30,
    "link_health": 0.15,
    "completeness": 0.20,
    "accuracy": 0.15,
}

DEFAULT_README_SECTIONS = [
    "installation", "usage", "api", "contributing", "license",
]

SCORE_LABELS = {
    (90, 101): "excellent",
    (70, 90): "good",
    (50, 70): "stale",
    (30, 50): "critical",
    (0, 30): "abandoned",
}


def get_label(score: float) -> str:
    for (low, high), label in SCORE_LABELS.items():
        if low <= score < high:
            return label
    return "unknown"


# --- Git Helpers ---

def run_git(repo_path: str, args: List[str], default: str = "") -> str:
    try:
        result = subprocess.run(
            ["git", "-C", repo_path] + args,
            capture_output=True, text=True, timeout=30,
        )
        return result.stdout.strip() if result.returncode == 0 else default
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return default


def get_file_last_commit_date(repo_path: str, file_path: str) -> Optional[datetime]:
    output = run_git(repo_path, ["log", "-1", "--format=%aI", "--", file_path])
    if output:
        try:
            return datetime.fromisoformat(output)
        except ValueError:
            pass
    return None


def get_code_changes_since(repo_path: str, since_date: str, directory: str = "") -> int:
    args = ["log", "--since", since_date, "--oneline", "--", directory or "."]
    output = run_git(repo_path, args)
    return len([l for l in output.splitlines() if l.strip()]) if output else 0


def get_latest_tag(repo_path: str) -> Optional[str]:
    output = run_git(repo_path, ["describe", "--tags", "--abbrev=0"])
    return output.lstrip("v") if output else None


# --- File Discovery ---

def find_doc_files(repo_path: str) -> List[str]:
    doc_files = []
    for root, dirs, files in os.walk(repo_path):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
        for f in files:
            if Path(f).suffix.lower() in DOC_EXTENSIONS:
                doc_files.append(os.path.relpath(os.path.join(root, f), repo_path))
    return sorted(doc_files)


# --- Scoring Dimensions ---

def score_last_updated(repo_path: str, doc_path: str) -> Tuple[float, Dict[str, Any]]:
    """Score based on how recently the doc was modified. 0-100."""
    last_modified = get_file_last_commit_date(repo_path, doc_path)
    details = {}

    if not last_modified:
        details["reason"] = "No git history found"
        return 50.0, details

    now = datetime.now(timezone.utc)
    if last_modified.tzinfo is None:
        last_modified = last_modified.replace(tzinfo=timezone.utc)

    days_ago = (now - last_modified).days
    details["last_modified"] = last_modified.strftime("%Y-%m-%d")
    details["days_ago"] = days_ago

    # Score: 100 if updated today, decays over time
    if days_ago <= 7:
        score = 100.0
    elif days_ago <= 30:
        score = 90.0 - (days_ago - 7) * 0.4
    elif days_ago <= 90:
        score = 80.0 - (days_ago - 30) * 0.5
    elif days_ago <= 180:
        score = 50.0 - (days_ago - 90) * 0.3
    elif days_ago <= 365:
        score = 25.0 - (days_ago - 180) * 0.1
    else:
        score = max(0.0, 10.0 - (days_ago - 365) * 0.02)

    return max(0.0, min(100.0, score)), details


def score_code_doc_alignment(repo_path: str, doc_path: str) -> Tuple[float, Dict[str, Any]]:
    """Score based on whether documented items still exist in code. 0-100."""
    full_path = os.path.join(repo_path, doc_path)
    details = {"referenced_files": 0, "existing_files": 0, "referenced_functions": 0}

    try:
        with open(full_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return 50.0, details

    # Extract file references
    file_refs = set()
    # Markdown links
    for match in re.finditer(r'\[([^\]]*)\]\(([^)]+)\)', content):
        target = match.group(2).split("#")[0]
        if not target.startswith(("http://", "https://", "mailto:")) and target:
            file_refs.add(target)
    # Backtick file references
    for match in re.finditer(r'`([^\s`]+\.\w{1,5})`', content):
        candidate = match.group(1)
        if Path(candidate).suffix.lower() in CODE_EXTENSIONS | DOC_EXTENSIONS:
            file_refs.add(candidate)

    if not file_refs:
        # No explicit references; check if associated code dir has changed
        doc_dir = os.path.dirname(doc_path)
        last_mod = get_file_last_commit_date(repo_path, doc_path)
        if last_mod:
            since = last_mod.strftime("%Y-%m-%d")
            changes = get_code_changes_since(repo_path, since, doc_dir)
            details["code_changes_since_update"] = changes
            if changes == 0:
                return 100.0, details
            elif changes < 5:
                return 80.0, details
            elif changes < 20:
                return 60.0, details
            else:
                return 40.0, details
        return 70.0, details

    # Check which referenced files exist
    doc_dir = os.path.dirname(doc_path)
    existing = 0
    for ref in file_refs:
        # Try relative to doc location
        resolved = os.path.normpath(os.path.join(repo_path, doc_dir, ref))
        if os.path.exists(resolved):
            existing += 1
            continue
        # Try relative to repo root
        resolved_root = os.path.normpath(os.path.join(repo_path, ref))
        if os.path.exists(resolved_root):
            existing += 1

    details["referenced_files"] = len(file_refs)
    details["existing_files"] = existing

    if len(file_refs) == 0:
        return 70.0, details

    ratio = existing / len(file_refs)
    return ratio * 100.0, details


def score_link_health(repo_path: str, doc_path: str) -> Tuple[float, Dict[str, Any]]:
    """Score based on percentage of valid internal links. 0-100."""
    full_path = os.path.join(repo_path, doc_path)
    details = {"total_links": 0, "valid_links": 0, "broken_links": []}

    try:
        with open(full_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return 100.0, details

    doc_dir = os.path.dirname(doc_path)

    # Extract markdown links
    links = []
    for match in re.finditer(r'\[([^\]]*)\]\(([^)]+)\)', content):
        target = match.group(2)
        if not target.startswith(("http://", "https://", "mailto:")):
            links.append(target)

    if not links:
        return 100.0, details

    details["total_links"] = len(links)
    valid = 0

    for link in links:
        anchor = None
        if "#" in link:
            file_part, anchor = link.split("#", 1)
        else:
            file_part = link

        if not file_part:
            # Anchor-only link within same doc
            if anchor:
                headings = _extract_headings(content)
                slug = _slugify(anchor)
                if slug in headings:
                    valid += 1
                else:
                    details["broken_links"].append(f"#{anchor}")
            else:
                valid += 1
            continue

        # Check file existence
        resolved = os.path.normpath(os.path.join(repo_path, doc_dir, file_part))
        if not os.path.exists(resolved):
            resolved = os.path.normpath(os.path.join(repo_path, file_part))

        if os.path.exists(resolved):
            if anchor and resolved.endswith((".md", ".rst")):
                # Validate anchor in target file
                try:
                    with open(resolved, "r", encoding="utf-8", errors="ignore") as f:
                        target_content = f.read()
                    headings = _extract_headings(target_content)
                    if _slugify(anchor) in headings:
                        valid += 1
                    else:
                        details["broken_links"].append(link)
                except (OSError, IOError):
                    valid += 1  # Give benefit of doubt
            else:
                valid += 1
        else:
            details["broken_links"].append(link)

    details["valid_links"] = valid
    if len(links) == 0:
        return 100.0, details
    return (valid / len(links)) * 100.0, details


def score_completeness(repo_path: str, doc_path: str, required_sections: List[str]) -> Tuple[float, Dict[str, Any]]:
    """Score based on whether expected sections are present. 0-100."""
    full_path = os.path.join(repo_path, doc_path)
    details = {"expected_sections": required_sections, "found_sections": [], "missing_sections": []}

    try:
        with open(full_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return 0.0, details

    # Extract headings
    headings_lower = set()
    for line in content.splitlines():
        match = re.match(r'^#{1,4}\s+(.+)', line)
        if match:
            headings_lower.add(match.group(1).strip().lower())

    # Also check heading words
    heading_words = set()
    for h in headings_lower:
        heading_words.update(h.split())

    found = []
    missing = []
    for section in required_sections:
        section_lower = section.lower()
        if section_lower in headings_lower or section_lower in heading_words:
            found.append(section)
        elif any(section_lower in h for h in headings_lower):
            found.append(section)
        else:
            missing.append(section)

    details["found_sections"] = found
    details["missing_sections"] = missing

    if not required_sections:
        return 100.0, details

    # Also score based on content length (very short docs are incomplete)
    content_lines = len([l for l in content.splitlines() if l.strip()])
    length_penalty = 0
    if content_lines < 10:
        length_penalty = 30
    elif content_lines < 30:
        length_penalty = 15

    section_score = (len(found) / len(required_sections)) * 100.0
    return max(0.0, section_score - length_penalty), details


def score_accuracy(repo_path: str, doc_path: str) -> Tuple[float, Dict[str, Any]]:
    """Score based on accuracy of verifiable facts (versions, dates, paths). 0-100."""
    full_path = os.path.join(repo_path, doc_path)
    details = {"checks": [], "issues": []}

    try:
        with open(full_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return 50.0, details

    checks_passed = 0
    checks_total = 0

    # Check 1: Version strings match latest tag
    git_version = get_latest_tag(repo_path)
    if git_version:
        version_refs = re.findall(r'(?:v|version[:\s]*)(\d+\.\d+(?:\.\d+)?)', content, re.IGNORECASE)
        if version_refs:
            checks_total += 1
            if any(v == git_version for v in version_refs):
                checks_passed += 1
                details["checks"].append("version_match: PASS")
            else:
                details["checks"].append(f"version_match: FAIL (doc has {version_refs}, git has {git_version})")
                details["issues"].append(f"Version mismatch: doc={version_refs}, git={git_version}")

    # Check 2: Package version from manifests
    for manifest in ["package.json", "pyproject.toml", "setup.py", "Cargo.toml"]:
        manifest_path = os.path.join(repo_path, manifest)
        if os.path.exists(manifest_path):
            manifest_version = _extract_version_from_manifest(manifest_path, manifest)
            if manifest_version:
                version_refs = re.findall(r'(?:v|version[:\s]*)(\d+\.\d+(?:\.\d+)?)', content, re.IGNORECASE)
                if version_refs:
                    checks_total += 1
                    if manifest_version in version_refs:
                        checks_passed += 1
                        details["checks"].append(f"manifest_version ({manifest}): PASS")
                    else:
                        details["checks"].append(
                            f"manifest_version ({manifest}): FAIL "
                            f"(doc={version_refs}, manifest={manifest_version})"
                        )
                        details["issues"].append(
                            f"Manifest version mismatch: {manifest} has {manifest_version}"
                        )

    # Check 3: Referenced file paths exist
    file_refs = re.findall(r'`([^\s`]+/[^\s`]+\.\w{1,5})`', content)
    if file_refs:
        doc_dir = os.path.dirname(doc_path)
        existing_count = 0
        for ref in file_refs:
            resolved = os.path.normpath(os.path.join(repo_path, doc_dir, ref))
            if os.path.exists(resolved):
                existing_count += 1
            else:
                resolved_root = os.path.normpath(os.path.join(repo_path, ref))
                if os.path.exists(resolved_root):
                    existing_count += 1
        checks_total += 1
        if len(file_refs) > 0 and existing_count == len(file_refs):
            checks_passed += 1
            details["checks"].append(f"file_paths: PASS ({existing_count}/{len(file_refs)})")
        else:
            ratio = existing_count / len(file_refs) if file_refs else 0
            # Partial credit
            checks_passed += ratio
            details["checks"].append(f"file_paths: PARTIAL ({existing_count}/{len(file_refs)})")
            details["issues"].append(f"{len(file_refs) - existing_count} referenced file paths not found")

    # Check 4: Dates are not in the future and not suspiciously old
    date_pattern = re.compile(r'(\d{4}-\d{2}-\d{2})')
    dates_found = date_pattern.findall(content)
    if dates_found:
        checks_total += 1
        now = datetime.now(timezone.utc)
        all_ok = True
        for date_str in dates_found:
            try:
                d = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
                if d > now:
                    details["issues"].append(f"Future date found: {date_str}")
                    all_ok = False
            except ValueError:
                pass
        if all_ok:
            checks_passed += 1
            details["checks"].append("dates: PASS")
        else:
            details["checks"].append("dates: FAIL")

    if checks_total == 0:
        return 75.0, details  # No verifiable facts found, assume reasonable

    return (checks_passed / checks_total) * 100.0, details


# --- Helpers ---

def _extract_headings(content: str) -> set:
    """Extract heading slugs from markdown content."""
    slugs = set()
    for line in content.splitlines():
        match = re.match(r'^#{1,6}\s+(.+)', line)
        if match:
            slugs.add(_slugify(match.group(1).strip()))
    return slugs


def _slugify(text: str) -> str:
    """Convert heading text to anchor slug (GitHub-style)."""
    text = text.lower()
    text = re.sub(r'[^\w\s-]', '', text)
    text = re.sub(r'[\s]+', '-', text)
    text = text.strip('-')
    return text


def _extract_version_from_manifest(path: str, filename: str) -> Optional[str]:
    """Extract version string from a package manifest."""
    try:
        with open(path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read()
    except (OSError, IOError):
        return None

    if filename == "package.json":
        match = re.search(r'"version"\s*:\s*"([^"]+)"', content)
        return match.group(1) if match else None
    elif filename == "pyproject.toml":
        match = re.search(r'version\s*=\s*"([^"]+)"', content)
        return match.group(1) if match else None
    elif filename == "setup.py":
        match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content)
        return match.group(1) if match else None
    elif filename == "Cargo.toml":
        match = re.search(r'version\s*=\s*"([^"]+)"', content)
        return match.group(1) if match else None
    return None


# --- Scoring Engine ---

def score_document(
    repo_path: str,
    doc_path: str,
    weights: Dict[str, float],
    required_sections: List[str],
) -> Dict[str, Any]:
    """Score a single documentation file across all dimensions."""
    updated_score, updated_details = score_last_updated(repo_path, doc_path)
    alignment_score, alignment_details = score_code_doc_alignment(repo_path, doc_path)
    link_score, link_details = score_link_health(repo_path, doc_path)
    completeness_score, completeness_details = score_completeness(repo_path, doc_path, required_sections)
    accuracy_score, accuracy_details = score_accuracy(repo_path, doc_path)

    weighted_total = (
        updated_score * weights["last_updated"]
        + alignment_score * weights["code_doc_alignment"]
        + link_score * weights["link_health"]
        + completeness_score * weights["completeness"]
        + accuracy_score * weights["accuracy"]
    )

    return {
        "file": doc_path,
        "total_score": round(weighted_total, 1),
        "label": get_label(weighted_total),
        "dimensions": {
            "last_updated": {
                "score": round(updated_score, 1),
                "weight": weights["last_updated"],
                "weighted": round(updated_score * weights["last_updated"], 1),
                "details": updated_details,
            },
            "code_doc_alignment": {
                "score": round(alignment_score, 1),
                "weight": weights["code_doc_alignment"],
                "weighted": round(alignment_score * weights["code_doc_alignment"], 1),
                "details": alignment_details,
            },
            "link_health": {
                "score": round(link_score, 1),
                "weight": weights["link_health"],
                "weighted": round(link_score * weights["link_health"], 1),
                "details": link_details,
            },
            "completeness": {
                "score": round(completeness_score, 1),
                "weight": weights["completeness"],
                "weighted": round(completeness_score * weights["completeness"], 1),
                "details": completeness_details,
            },
            "accuracy": {
                "score": round(accuracy_score, 1),
                "weight": weights["accuracy"],
                "weighted": round(accuracy_score * weights["accuracy"], 1),
                "details": accuracy_details,
            },
        },
    }


# --- Report ---

def generate_report(scores: List[Dict[str, Any]], as_json: bool = False) -> str:
    """Generate a staleness report from scored documents."""
    if not scores:
        if as_json:
            return json.dumps({"documents": [], "aggregate_score": 0}, indent=2)
        return "No documentation files found to score."

    aggregate = sum(s["total_score"] for s in scores) / len(scores)

    report_data = {
        "aggregate_score": round(aggregate, 1),
        "aggregate_label": get_label(aggregate),
        "total_documents": len(scores),
        "documents": scores,
    }

    if as_json:
        return json.dumps(report_data, indent=2, default=str)

    # Human-readable
    lines = []
    lines.append("Documentation Staleness Report")
    lines.append("=" * 60)
    lines.append(f"Aggregate Score: {aggregate:.1f}/100 ({get_label(aggregate)})")
    lines.append(f"Documents Scored: {len(scores)}")
    lines.append("")

    # Sort by score ascending (worst first)
    sorted_scores = sorted(scores, key=lambda s: s["total_score"])

    lines.append(f"{'File':<45} {'Score':>6} {'Label':>12}")
    lines.append("-" * 65)
    for s in sorted_scores:
        lines.append(f"{s['file']:<45} {s['total_score']:>5.1f} {s['label']:>12}")

    lines.append("")
    lines.append("DIMENSION BREAKDOWN (worst scoring files):")
    lines.append("-" * 60)

    # Show detailed breakdown for bottom 5
    for s in sorted_scores[:5]:
        lines.append(f"\n  {s['file']} (score: {s['total_score']:.1f})")
        for dim_name, dim_data in s["dimensions"].items():
            bar = _score_bar(dim_data["score"])
            lines.append(
                f"    {dim_name:<25} {dim_data['score']:>5.1f} "
                f"(x{dim_data['weight']:.2f} = {dim_data['weighted']:>5.1f}) {bar}"
            )

    lines.append("")
    return "\n".join(lines)


def _score_bar(score: float, width: int = 20) -> str:
    """Generate a simple ASCII bar for a score."""
    filled = int(score / 100 * width)
    return "[" + "#" * filled + "." * (width - filled) + "]"


# --- Main ---

def main():
    parser = argparse.ArgumentParser(
        description="Score documentation freshness on a 0-100 scale",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("repo_path", help="Path to the git repository")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument(
        "--threshold", type=float, default=None,
        help="Fail (exit 1) if aggregate score is below this value",
    )
    parser.add_argument("--readme-focus", action="store_true", help="Only score README files")
    parser.add_argument(
        "--required-sections", default=None,
        help="Comma-separated required sections for completeness scoring",
    )
    parser.add_argument("--quiet", action="store_true", help="Only output score number")
    parser.add_argument("--weight-updated", type=float, default=None)
    parser.add_argument("--weight-alignment", type=float, default=None)
    parser.add_argument("--weight-links", type=float, default=None)
    parser.add_argument("--weight-completeness", type=float, default=None)
    parser.add_argument("--weight-accuracy", type=float, default=None)

    args = parser.parse_args()

    repo_path = os.path.abspath(args.repo_path)
    if not os.path.isdir(repo_path):
        print(f"Error: {repo_path} is not a directory", file=sys.stderr)
        sys.exit(2)

    # Build weights
    weights = dict(DEFAULT_WEIGHTS)
    if args.weight_updated is not None:
        weights["last_updated"] = args.weight_updated
    if args.weight_alignment is not None:
        weights["code_doc_alignment"] = args.weight_alignment
    if args.weight_links is not None:
        weights["link_health"] = args.weight_links
    if args.weight_completeness is not None:
        weights["completeness"] = args.weight_completeness
    if args.weight_accuracy is not None:
        weights["accuracy"] = args.weight_accuracy

    # Normalize weights to sum to 1.0
    total_weight = sum(weights.values())
    if total_weight > 0:
        weights = {k: v / total_weight for k, v in weights.items()}

    # Required sections
    required_sections = DEFAULT_README_SECTIONS
    if args.required_sections:
        required_sections = [s.strip() for s in args.required_sections.split(",")]

    # Find docs
    doc_files = find_doc_files(repo_path)
    if args.readme_focus:
        doc_files = [d for d in doc_files if os.path.basename(d).lower().startswith("readme")]

    if not doc_files:
        if args.quiet:
            print("0")
        elif args.json:
            print(json.dumps({"error": "No documentation files found"}, indent=2))
        else:
            print("No documentation files found.")
        sys.exit(0)

    # Score each document
    scores = []
    for doc in doc_files:
        score = score_document(repo_path, doc, weights, required_sections)
        scores.append(score)

    aggregate = sum(s["total_score"] for s in scores) / len(scores) if scores else 0

    if args.quiet:
        print(f"{aggregate:.1f}")
    else:
        report = generate_report(scores, as_json=args.json)
        print(report)

    # Threshold check
    if args.threshold is not None and aggregate < args.threshold:
        if not args.quiet:
            print(
                f"\nFAILED: Aggregate score {aggregate:.1f} is below threshold {args.threshold}",
                file=sys.stderr,
            )
        sys.exit(1)

    sys.exit(0)


if __name__ == "__main__":
    main()