doc-drift-detector 1.0.0__py3-none-any.whl

ai/__init__.py

@@ -0,0 +1,18 @@
+"""
+ai
+==
+AI-Powered Semantic Verification and Prose Rewriting module.
+Integrates with local Ollama daemon (e.g. Llama 3.2, Mistral).
+"""
+
+from .ollama_client import OllamaClient
+from .semantic_verifier import SemanticVerifier, VerificationResult
+from .prose_rewriter import ProseRewriter
+
+__all__ = [
+    "OllamaClient",
+    "SemanticVerifier",
+    "VerificationResult",
+    "ProseRewriter",
+]
+

ai/ollama_client.py

@@ -0,0 +1,117 @@
+"""
+ai/ollama_client.py
+===================
+Lightweight, zero-dependency REST client for local Ollama instance.
+Communicates directly with http://localhost:11434 (or OLLAMA_HOST).
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+
+DEFAULT_OLLAMA_HOST = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+PREFERRED_MODELS = [
+    "llama3.2", "llama3.2:1b", "llama3.2:3b", "llama3.1",
+    "llama3", "mistral", "qwen2.5", "qwen2.5-coder", "phi3"
+]
+
+
+class OllamaClient:
+    """Zero-dependency HTTP client for interacting with a local Ollama daemon."""
+
+    def __init__(self, host: str = DEFAULT_OLLAMA_HOST, timeout: float = 15.0):
+        self.host = host.rstrip("/")
+        self.timeout = timeout
+        self._cached_available: Optional[bool] = None
+        self._cached_models: Optional[List[str]] = None
+
+    def is_available(self) -> bool:
+        """Checks if the local Ollama server is running and responsive."""
+        try:
+            req = urllib.request.Request(
+                f"{self.host}/api/tags",
+                headers={"User-Agent": "DocDrift/1.0"}
+            )
+            with urllib.request.urlopen(req, timeout=2.0) as resp:
+                if resp.status == 200:
+                    self._cached_available = True
+                    return True
+        except Exception:
+            pass
+        self._cached_available = False
+        return False
+
+    def list_models(self) -> List[str]:
+        """Returns list of model names downloaded in local Ollama."""
+        if not self.is_available():
+            return []
+        try:
+            req = urllib.request.Request(f"{self.host}/api/tags")
+            with urllib.request.urlopen(req, timeout=3.0) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+                models = [m.get("name", "") for m in data.get("models", [])]
+                self._cached_models = models
+                return models
+        except Exception:
+            return []
+
+    def get_preferred_model(self) -> Optional[str]:
+        """
+        Determines the best available model on the user's Ollama instance.
+        Prioritizes fast models: llama3.2 -> llama3 -> mistral -> first available.
+        """
+        installed = self.list_models()
+        if not installed:
+            return None
+
+        # Check preferred list
+        for preferred in PREFERRED_MODELS:
+            for inst in installed:
+                if inst == preferred or inst.startswith(f"{preferred}:"):
+                    return inst
+
+        # Return first installed model as fallback
+        return installed[0]
+
+    def chat(
+        self,
+        messages: List[Dict[str, str]],
+        model: Optional[str] = None,
+        json_format: bool = False,
+        temperature: float = 0.1
+    ) -> Optional[str]:
+        """
+        Executes a chat completion request to Ollama /api/chat.
+        """
+        active_model = model or self.get_preferred_model()
+        if not active_model:
+            return None
+
+        payload: Dict[str, Any] = {
+            "model": active_model,
+            "messages": messages,
+            "stream": False,
+            "options": {
+                "temperature": temperature,
+            }
+        }
+        if json_format:
+            payload["format"] = "json"
+
+        try:
+            req_data = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(
+                f"{self.host}/api/chat",
+                data=req_data,
+                headers={"Content-Type": "application/json"}
+            )
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                result = json.loads(resp.read().decode("utf-8"))
+                message = result.get("message", {})
+                return message.get("content", "").strip()
+        except Exception:
+            return None
+

ai/prose_rewriter.py

@@ -0,0 +1,81 @@
+"""
+ai/prose_rewriter.py
+====================
+Layer 3: AI Prose Rewriting via Ollama.
+
+Generates natural, context-aware sentence and paragraph updates for confirmed
+documentation drift issues using local Ollama LLMs.
+"""
+
+from typing import Optional
+
+from detectors import CodeChange
+from .ollama_client import OllamaClient
+
+
+SYSTEM_PROMPT = """You are an expert technical documentation editor.
+Your job is to update a single documentation sentence so it accurately reflects a code change.
+
+Strict Rules:
+1. Replace ONLY the outdated value, flag name, or parameter with the new one from the code change.
+2. Preserve the author's tone, formatting, and markdown (backticks ``, bold **, list markers -).
+3. Do NOT output code blocks, markdown headers, or multiple lines.
+4. Do NOT add explanations, commentary, or filler text.
+5. Output ONLY the single updated sentence — nothing else."""
+
+
+class ProseRewriter:
+    """Generates natural documentation sentence rewrites using local Ollama LLMs."""
+
+    def __init__(self, client: Optional[OllamaClient] = None):
+        self.client = client or OllamaClient()
+
+    def rewrite_sentence(
+        self,
+        sentence: str,
+        change: CodeChange,
+        model: Optional[str] = None
+    ) -> Optional[str]:
+        """
+        Uses Ollama to generate a fluent rewrite of the outdated sentence.
+        """
+        if not self.client.is_available():
+            return None
+
+        diff_summary = ""
+        if change.old_value is not None and change.new_value is not None:
+            diff_summary = f"- Old value/signature: {change.old_value}\n- New value/signature: {change.new_value}"
+        elif change.old_name is not None and change.new_name is not None:
+            diff_summary = f"- Old name: {change.old_name}\n- New name: {change.new_name}"
+
+        user_content = (
+            f"Original sentence: \"{sentence}\"\n"
+            f"Code Change: '{change.name}' {diff_summary} in {change.file}:{change.line}.\n"
+            f"Write ONLY the corrected sentence (no code blocks, no extra lines):"
+        )
+
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_content}
+        ]
+
+        rewritten = self.client.chat(messages, model=model, temperature=0.1)
+        if not rewritten:
+            return None
+
+        # Clean up surrounding quotes the LLM may have added
+        cleaned = rewritten.strip()
+        if (cleaned.startswith('"') and cleaned.endswith('"')) or (cleaned.startswith("'") and cleaned.endswith("'")):
+            cleaned = cleaned[1:-1].strip()
+
+        # If LLM returned a code block, extract first usable line
+        if "```" in cleaned:
+            lines = [ln for ln in cleaned.splitlines() if ln.strip() and not ln.strip().startswith("```")]
+            cleaned = lines[0].strip() if lines else ""
+
+        # If LLM returned multiple lines, take only the first (the sentence itself)
+        if "\n" in cleaned:
+            cleaned = cleaned.splitlines()[0].strip()
+
+        return cleaned if cleaned else None
+

ai/semantic_verifier.py

@@ -0,0 +1,96 @@
+"""
+ai/semantic_verifier.py
+=======================
+Layer 2: AI Semantic Verification via Ollama.
+
+Evaluates candidate (code_change, doc_match) pairs using a local LLM to:
+1. Verify whether the prose is genuinely out-of-date or merely mentions the feature.
+2. Produce a clear, human-like explanation of WHY the documentation drifted.
+3. Eliminate edge-case false positives that static rules might miss.
+"""
+
+from dataclasses import dataclass
+import json
+from typing import Optional, Tuple
+
+from detectors import CodeChange
+from utils.doc_finder import DocMatch
+from .ollama_client import OllamaClient
+
+
+@dataclass
+class VerificationResult:
+    is_drift: bool
+    confidence: float
+    reasoning: str
+    suggested_action: str
+
+
+SYSTEM_PROMPT = """You are an expert Documentation Drift Verification Agent.
+You compare a code change against a documentation sentence to check if the documentation is now factually outdated.
+
+Rules:
+1. If the documentation mentions an old value (e.g. '30 seconds') but the code changed it (e.g. to '60'), this is DRIFT: return {"is_drift": true, ...}.
+2. If the documentation mentions an old flag (e.g. '--legacy-auth') or deleted function, this is DRIFT: return {"is_drift": true, ...}.
+3. If the documentation does not contradict the code change, return {"is_drift": false, ...}.
+
+Always respond in valid JSON format:
+{
+  "is_drift": boolean,
+  "confidence": float (between 0.0 and 1.0),
+  "reasoning": "1-sentence explanation of why this is or is not drift",
+  "suggested_action": "Specific edit instruction if drifted"
+}"""
+
+
+class SemanticVerifier:
+    """Verifies potential drift issues using Ollama LLM reasoning."""
+
+    def __init__(self, client: Optional[OllamaClient] = None):
+        self.client = client or OllamaClient()
+
+    def verify_candidate(
+        self,
+        change: CodeChange,
+        match: DocMatch,
+        model: Optional[str] = None
+    ) -> Optional[VerificationResult]:
+        """
+        Sends candidate drift pair to Ollama to verify if documentation genuinely drifted.
+        """
+        if not self.client.is_available():
+            return None
+
+        # Build context prompt
+        diff_summary = ""
+        if change.old_value is not None and change.new_value is not None:
+            diff_summary = f"Changed from '{change.old_value}' to '{change.new_value}'"
+        elif change.old_name is not None and change.new_name is not None:
+            diff_summary = f"Renamed from '{change.old_name}' to '{change.new_name}'"
+
+        user_content = (
+            f"Code Change: Identifier '{change.name}' {diff_summary} in {change.file}:{change.line}.\n"
+            f"Documentation Sentence: \"{match.sentence}\"\n\n"
+            f"Does this documentation sentence contain factually outdated information based on this code change? Respond in JSON:"
+        )
+
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_content}
+        ]
+
+        response_text = self.client.chat(messages, model=model, json_format=True, temperature=0.1)
+        if not response_text:
+            return None
+
+        try:
+            data = json.loads(response_text)
+            return VerificationResult(
+                is_drift=bool(data.get("is_drift", False)),
+                confidence=float(data.get("confidence", 0.8)),
+                reasoning=str(data.get("reasoning", "")),
+                suggested_action=str(data.get("suggested_action", ""))
+            )
+        except Exception:
+            return None
+

detectors/__init__.py

@@ -0,0 +1,63 @@
+"""
+detectors
+=========
+STEP 2: EXTRACT CODE CHANGES (semantic)
+
+Contains specialized semantic detectors for:
+- DEFAULT_VALUE_CHANGED: constants, kwargs, config keys, .env
+- FLAG_RENAMED: CLI flags (--old-flag -> --new-flag) and config keys
+- PARAM_CHANGED: function signature & default parameter modifications
+- FEATURE_REMOVED: deleted functions/classes no longer in codebase
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class CodeChange:
+    """Represents a semantic code change detected in a PR diff."""
+    change_type: str
+    name: str
+    file: str
+    line: int
+    old_value: Optional[str] = None
+    new_value: Optional[str] = None
+    old_name: Optional[str] = None
+    new_name: Optional[str] = None
+    details: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert code change object to dictionary format."""
+        data = {
+            "type": self.change_type,
+            "name": self.name,
+            "file": self.file,
+            "line": self.line,
+        }
+        if self.old_value is not None:
+            data["old_value"] = self.old_value
+        if self.new_value is not None:
+            data["new_value"] = self.new_value
+        if self.old_name is not None:
+            data["old_name"] = self.old_name
+        if self.new_name is not None:
+            data["new_name"] = self.new_name
+        if self.details:
+            data["details"] = self.details
+        return data
+
+
+from .default_value import detect_default_values
+from .flag_rename import detect_flag_renames
+from .param_change import detect_param_changes
+from .feature_remove import detect_feature_removals
+
+__all__ = [
+    "CodeChange",
+    "detect_default_values",
+    "detect_flag_renames",
+    "detect_param_changes",
+    "detect_feature_removals",
+]
+

detectors/default_value.py

@@ -0,0 +1,135 @@
+"""
+detectors/default_value.py
+==========================
+STEP 2A: DEFAULT VALUE CHANGED DETECTOR
+
+Detects when default values, configuration constants, or parameter defaults have
+changed in code files.
+
+Patterns handled:
+1. Python:
+   - UPPER_CASE constants: `DEFAULT_TIMEOUT = 30` -> `DEFAULT_TIMEOUT = 60`
+   - Lowercase config variables: `timeout = 30` -> `timeout = 60`
+   - Dictionary key/value defaults: `"timeout": 30` -> `"timeout": 60`
+   - Function parameter default values: `def foo(timeout=30)` -> `def foo(timeout=60)`
+2. YAML / TOML / JSON:
+   - `timeout: 30` -> `timeout: 60`
+   - `port = 8080` -> `port = 9000`
+3. .env / .ini / .cfg files:
+   - `DEFAULT_PORT=3000` -> `DEFAULT_PORT=8080`
+
+Output:
+  CodeChange(type="DEFAULT_VALUE_CHANGED", name=..., old_value=..., new_value=..., file=..., line=...)
+"""
+
+from pathlib import Path
+import re
+from typing import Dict, List, Optional, Tuple
+
+from utils.diff_parser import FileDiff, DiffLine
+from . import CodeChange
+
+
+def clean_value(val: str) -> str:
+    """
+    Strips surrounding whitespace, quotes, trailing commas, and trailing comments.
+    E.g. '"30",  # timeout in seconds' -> '30'
+    """
+    if not val:
+        return ""
+    val = val.strip()
+    # Strip inline comments (e.g., # or //)
+    val = re.sub(r"\s*(?:#|//).*$", "", val).strip()
+    # Strip trailing commas
+    val = val.rstrip(",;").strip()
+    # Strip matching surrounding quotes
+    if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
+        val = val[1:-1]
+    return val.strip()
+
+
+def extract_assignment(line_text: str) -> Optional[Tuple[str, str]]:
+    """
+    Extracts variable/key name and assigned value from a line of code or config.
+    Supports:
+      - Variable assignment: `NAME = VALUE` or `self.name = VALUE`
+      - Dictionary / YAML / JSON: `'key': value`, `"key": value`, `key: value`
+      - TOML / .env: `KEY = VALUE`, `KEY=VALUE`
+    """
+    stripped = line_text.strip()
+    if not stripped or stripped.startswith(("#", "//", "/*", "*")):
+        return None
+
+    # Pattern 1: Dict or YAML/JSON style -> "key": value or key: value
+    dict_match = re.match(r"^['\"]?([a-zA-Z0-9_\.\-]+)['\"]?\s*:\s*([^#\n]+)", stripped)
+    if dict_match:
+        name = dict_match.group(1).strip()
+        val = clean_value(dict_match.group(2))
+        return name, val
+
+    # Pattern 2: Assignment style -> NAME = VALUE or self.NAME = VALUE
+    assign_match = re.match(r"^(?:(?:self|cls)\.)?([a-zA-Z0-9_\.\-]+)\s*=\s*([^#\n]+)", stripped)
+    if assign_match:
+        name = assign_match.group(1).strip()
+        val = clean_value(assign_match.group(2))
+        return name, val
+
+    # Pattern 3: Function kwarg default within a def/function line: def foo(..., name=value, ...)
+    kwarg_match = re.findall(r"([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*([a-zA-Z0-9_\"'\.\-]+)", stripped)
+    # If it's a def line with a single kwarg change or we need to extract kwargs
+    if stripped.startswith("def ") or stripped.startswith("function "):
+        # Return first kwarg match if any
+        if kwarg_match:
+            return kwarg_match[0][0], clean_value(kwarg_match[0][1])
+
+    return None
+
+
+def detect_default_values(file_diff: FileDiff) -> List[CodeChange]:
+    """
+    STEP 2A: Detect changed default values in a FileDiff.
+    Compares removed lines (-) against added lines (+) looking for identical
+    variable/key names whose values differ.
+    """
+    changes: List[CodeChange] = []
+
+    # Map removed assignments: name -> (old_value, line_number)
+    removed_assignments: Dict[str, Tuple[str, int]] = {}
+
+    for line in file_diff.removed_lines:
+        extracted = extract_assignment(line.content)
+        if extracted:
+            name, old_val = extracted
+            # Only store non-empty values
+            if old_val:
+                removed_assignments[name] = (old_val, line.line_number)
+
+    # Now inspect added lines to find matching names with new values
+    matched_names = set()
+    for line in file_diff.added_lines:
+        extracted = extract_assignment(line.content)
+        if extracted:
+            name, new_val = extracted
+            if name in removed_assignments:
+                old_val, old_line_num = removed_assignments[name]
+                # Only flag if value has actually changed!
+                if old_val != new_val and name not in matched_names:
+                    matched_names.add(name)
+                    changes.append(
+                        CodeChange(
+                            change_type="DEFAULT_VALUE_CHANGED",
+                            name=name,
+                            file=file_diff.file_path,
+                            line=line.line_number,
+                            old_value=old_val,
+                            new_value=new_val,
+                            details={
+                                "old_line": old_line_num,
+                                "new_line": line.line_number,
+                                "raw_diff": f"- {name} = {old_val} / + {name} = {new_val}"
+                            }
+                        )
+                    )
+
+    return changes
+

detectors/feature_remove.py

@@ -0,0 +1,143 @@
+"""
+detectors/feature_remove.py
+===========================
+STEP 2D: FEATURE REMOVED DETECTOR
+
+Detects when functions, classes, or public features have been deleted from code:
+- Python: `def feature_name(` or `class FeatureName`
+- JavaScript / TypeScript: `function featureName(`, `class FeatureName`
+- Go: `func FeatureName(`
+- Rust: `fn feature_name(`
+
+Verification check:
+- Present in removed lines (-)
+- NOT present in added lines (+)
+- NOT found anywhere else in the repository (to avoid false alarms if a function
+  was merely moved or refactored into a different module).
+
+Output:
+  CodeChange(type="FEATURE_REMOVED", name=feature_name, file=..., line=...)
+"""
+
+from pathlib import Path
+import re
+from typing import List, Optional, Set, Tuple
+
+from utils.diff_parser import FileDiff, DiffLine, CODE_EXTENSIONS
+from . import CodeChange
+
+
+FEATURE_DEF_REGEX = re.compile(
+    r"""
+    ^\s*(?:async\s+)?(?:export\s+)?(?:default\s+)?
+    (?:def|class|function|func|fn)\s+
+    ([a-zA-Z_][a-zA-Z0-9_]*)
+    """,
+    re.VERBOSE
+)
+
+
+def extract_feature_name(line_text: str) -> Optional[str]:
+    """Extracts function or class name from a declaration line."""
+    match = FEATURE_DEF_REGEX.match(line_text.strip())
+    if match:
+        name = match.group(1)
+        # Skip special dunder methods like __init__, __str__
+        if name.startswith("__") and name.endswith("__"):
+            return None
+        return name
+    return None
+
+
+def exists_elsewhere_in_repo(feature_name: str, repo_dir: str, skip_file: str) -> bool:
+    """
+    Checks if feature_name definition still exists anywhere else in the repo.
+    Searches only code files, excluding documentation and ignored directories.
+    """
+    repo_path = Path(repo_dir)
+    target_pattern = re.compile(
+        rf"(?:def|class|function|func|fn)\s+{re.escape(feature_name)}\b"
+    )
+
+    ignore_dirs = {".git", "node_modules", "venv", ".venv", "dist", "build", "__pycache__", ".tox"}
+
+    try:
+        for p in repo_path.rglob("*"):
+            if not p.is_file():
+                continue
+            # Skip ignored directories
+            if any(ignored in p.parts for ignored in ignore_dirs):
+                continue
+            # Skip the file being modified
+            if str(p.relative_to(repo_path)) == skip_file or str(p) == skip_file:
+                continue
+            # Only check code files
+            if p.suffix.lower() not in CODE_EXTENSIONS:
+                continue
+
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                if target_pattern.search(content):
+                    return True
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    return False
+
+
+def detect_feature_removals(
+    file_diff: FileDiff,
+    all_added_lines_by_name: Optional[Set[str]] = None,
+    repo_dir: str = "."
+) -> List[CodeChange]:
+    """
+    STEP 2D: Detect removed functions or classes in a FileDiff.
+    Ensures feature is NOT added back anywhere in the diff, and does NOT exist
+    elsewhere in the repo.
+    """
+    changes: List[CodeChange] = []
+
+    # Features added in this file
+    added_in_file = set()
+    for line in file_diff.added_lines:
+        feat = extract_feature_name(line.content)
+        if feat:
+            added_in_file.add(feat)
+
+    # Features removed in this file
+    removed_features: List[Tuple[str, int]] = []
+    for line in file_diff.removed_lines:
+        feat = extract_feature_name(line.content)
+        if feat:
+            removed_features.append((feat, line.line_number))
+
+    for feat_name, line_num in removed_features:
+        # 1. Must NOT be in added lines of this file
+        if feat_name in added_in_file:
+            continue
+
+        # 2. Must NOT be added in any other modified file in the diff
+        if all_added_lines_by_name and feat_name in all_added_lines_by_name:
+            continue
+
+        # 3. Must NOT exist elsewhere in the repo
+        if exists_elsewhere_in_repo(feat_name, repo_dir, file_diff.file_path):
+            continue
+
+        changes.append(
+            CodeChange(
+                change_type="FEATURE_REMOVED",
+                name=feat_name,
+                file=file_diff.file_path,
+                line=line_num,
+                details={
+                    "kind": "function_or_class",
+                    "raw_diff": f"- deleted {feat_name}"
+                }
+            )
+        )
+
+    return changes
+