doc-drift-detector 1.0.0__tar.gz

doc_drift_detector-1.0.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: doc-drift-detector
+Version: 1.0.0
+Summary: Catch documentation drift in Pull Requests — static + AI hybrid
+License-Expression: MIT
+Keywords: documentation,drift,git,pr,devops,ci
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: colorama>=0.4.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+
+# 🧭 Documentation Drift Detector (DocDrift)
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.14-blue.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-green.svg)]()
+
+> **Automated Documentation Drift Detection for Pull Requests.**  
+> Catches outdated prose, config tables, default values, renamed flags, and removed features *before* they merge into production.
+
+---
+
+## 💥 The Problem
+
+Documentation silently drifts whenever code changes in a Pull Request:
+* An engineer updates `DEFAULT_TIMEOUT = 30` to `DEFAULT_TIMEOUT = 60` in `settings.py`.
+* The documentation in `docs/config.md` still reads:  
+  > *"The default timeout is 30 seconds."*
+* Existing validation tools (`python -m doctest`, `mktestdocs`, `Doc Detective`) **only validate executable code blocks**. They **CANNOT** detect whether explanatory prose, config tables, or tutorial instructions still match reality.
+
+**DocDrift** solves this by performing semantic diff analysis on code changes in a PR, locating affected documentation, and isolating the **exact sentence** that has drifted—with actionable fix suggestions.
+
+---
+
+## ⚡ Key Capabilities
+
+1. **Semantic PR Diff Parsing:** Analyzes git diffs (`base...head`) across Python, JavaScript/TypeScript, Go, Rust, Java, YAML, TOML, JSON, and `.env` files.
+2. **Four Specialized Semantic Detectors:**
+   - 🔢 **Changed Default Values:** Constants (`DEFAULT_TIMEOUT`), dict defaults, function kwargs, YAML/TOML keys, `.env` settings.
+   - 🚩 **Renamed Flags & Config Keys:** CLI options (`--old-flag` $\to$ `--new-flag` in argparse, Click, Typer) and renamed configuration keys.
+   - ⚙️ **Changed Function Parameters:** Added/removed parameters and modified default arguments via AST analysis.
+   - 🗑️ **Removed Features:** Deleted functions or classes verified to no longer exist in the codebase.
+3. **Smart Natural Language Normalization:** Bridges code and human writing (`DEFAULT_TIMEOUT` $\equiv$ `default_timeout` $\equiv$ `default timeout` $\equiv$ `default-timeout` $\equiv$ `defaultTimeout`).
+4. **False-Alarm Mitigation:** For default value changes, it **only** flags when the **old value** (e.g. `30` or `30s`) actually appears in the documentation sentence.
+5. **Exact Sentence Highlighting:** Extracts and pins the precise faulty sentence and table row.
+6. **First-Class GitHub Actions Workflow:** Generates inline PR diff annotations (`::error`, `::warning`) and PR Step Summaries.
+
+---
+
+## 📁 Project Structure
+
+```text
+doc-drift-detector/
+├── drift_detector.py                  # Main CLI entrypoint
+├── ai/
+│   ├── __init__.py                    # AI package exports
+│   ├── ollama_client.py               # Zero-dependency local Ollama REST client
+│   ├── semantic_verifier.py           # Layer 2: LLM reasoning verification
+│   └── prose_rewriter.py              # Layer 3: Natural prose rewriting
+├── detectors/
+│   ├── __init__.py                    # CodeChange data model & detector exports
+│   ├── default_value.py               # Detects changed default values & constants
+│   ├── flag_rename.py                 # Detects renamed CLI flags & config keys
+│   ├── param_change.py                # Detects changed function signatures & defaults
+│   └── feature_remove.py              # Detects deleted functions & classes
+├── utils/
+│   ├── __init__.py
+│   ├── diff_parser.py                 # Unified git diff parser with line tracking
+│   ├── doc_finder.py                  # Doc discovery, name normalizer, drift & auto-fix engine
+│   └── reporter.py                    # Colored terminal, JSON & GitHub action reporter
+├── .github/workflows/
+│   └── doc-drift.yml                  # Ready-to-use GitHub Action workflow
+├── requirements.txt                   # Dependencies
+├── README.md                          # Documentation
+└── tests/
+    └── test_basic.py                  # Complete test suite (15 passing tests)
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Installation
+
+DocDrift is built primarily using Python's standard library for zero-friction setup.
+
+```bash
+cd doc-drift-detector
+pip install -r requirements.txt
+```
+
+### 2. Analyze a Pull Request Diff
+
+```bash
+# Compare base branch (main) with current branch (HEAD)
+python drift_detector.py --base main --head HEAD
+
+# Analyze an offline diff file
+python drift_detector.py --diff-file my_pr.diff
+
+# Output JSON report
+python drift_detector.py --base main --head HEAD --json
+
+# Save report to a file
+python drift_detector.py --base main --head HEAD --output report.json
+```
+
+---
+
+## 📋 CLI Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base` | `str` | `None` | Base branch or commit SHA (e.g., `main`, `origin/main`, `HEAD~1`) |
+| `--head` | `str` | `None` | Head branch or commit SHA (e.g., `HEAD`) |
+| `--diff-file` | `path` | `None` | Path to pre-generated `.diff` or `.patch` file |
+| `--repo-dir` | `path` | `.` | Root directory of the repository to scan |
+| `--docs-dir` | `path` | `.` | Directory containing documentation files (`.md`, `.rst`, `.adoc`, `.txt`) |
+| `--format` | `choice` | `text` | Output format: `text`, `json`, `github`, or `markdown` |
+| `--json` | `flag` | `False` | Shorthand for `--format json` |
+| `--output` | `path` | `None` | File path to write the formatted report |
+| `--ai` | `flag` | `False` | Enable local Ollama AI hybrid verification & prose rewriting |
+| `--ai-model` | `str` | `auto` | Ollama model to use (e.g. `llama3.2:1b`, `llama3.2`, `mistral`) |
+| `--fix`, `--autofix` | `flag` | `False` | Automatically rewrite outdated documentation files on disk |
+| `--min-confidence` | `choice` | `medium`| Minimum issue confidence to report: `high`, `medium`, or `low` |
+| `--fail-on` | `choice` | `high` | Exit with code `1` if drift of this level is found: `high`, `medium`, `any`, `none` |
+| `-v`, `--verbose` | `flag` | `False` | Enable step-by-step pipeline logging |
+
+---
+
+## 🔍 How It Works (The 5-Step Pipeline)
+
+```mermaid
+flowchart TD
+    A["PR Git Diff<br>(git diff base...head)"] --> B["Step 1: Diff Parser<br>(Track +/- lines & code files)"]
+    B --> C["Step 2: Semantic Detectors<br>(Defaults, Flags, Params, Features)"]
+    C --> D["Step 3: Doc Finder<br>(Normalize names across .md, .rst, .adoc)"]
+    D --> E["Step 4: Smart Drift Engine<br>(Verify old value in text & score confidence)"]
+    E --> F["Step 5: Multi-Format Reporter<br>(CLI Boxes, JSON, GitHub Annotations)"]
+```
+
+### Step 1: Parse PR Diff (`utils/diff_parser.py`)
+- Executes `git diff <base>...<head> --unified=0`.
+- Isolates code files (`.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.yaml`, `.yml`, `.toml`, `.json`, `.env`, `.cfg`, `.ini`).
+- Extracts exact removed (`-`) and added (`+`) lines with source line numbers.
+
+### Step 2: Semantic Code Change Detection (`detectors/`)
+- **Default Values (`default_value.py`):** Pairs removed `VAR = OLD` with added `VAR = NEW`.
+- **Flag Renames (`flag_rename.py`):** Pairs removed `--old-flag` with added `--new-flag`, or renamed config keys with identical values.
+- **Param Changes (`param_change.py`):** Uses Python AST / regex to detect signature modifications and modified default arguments.
+- **Feature Removals (`feature_remove.py`):** Detects deleted functions or classes, verifying they don't exist elsewhere in the repo.
+
+### Step 3: Documentation Search (`utils/doc_finder.py`)
+- Scans `.md`, `.rst`, `.adoc`, and `.txt` files (excluding `.git`, `node_modules`, `venv`, etc.).
+- Normalizes names into searchable variants (`DEFAULT_TIMEOUT` $\to$ `"default timeout"`, `default-timeout`, etc.).
+- Extracts the exact sentence using punctuation boundaries and table row delimitation.
+
+### Step 4: Smart Drift Decision Engine
+- **DEFAULT_VALUE_CHANGED:** Flags **only** if the old value (e.g. `30` or `30s`) appears in the matched doc sentence. If the identifier is mentioned without the old value, it is skipped to prevent false alarms.
+- **FLAG_RENAMED:** Flags if the old flag name appears in documentation.
+- **PARAM_CHANGED:** Flags if removed parameter or old default is in documentation.
+- **FEATURE_REMOVED:** Flags if documentation references the deleted feature.
+
+#### Confidence Levels
+- 🔴 **HIGH (Merge Blocker):** Exact name match + old value confirmed in doc sentence.
+- 🟡 **MEDIUM (Warning):** Normalized match or function signature change.
+- ⚪ **LOW (Info):** Weak / partial match.
+
+### Step 5: Multi-Channel Reporting (`utils/reporter.py`)
+- **Human-Readable CLI:** Rich colored badges, exact file:line references, quotes, and suggested fixes.
+- **JSON Schema:** Machine-readable output for dashboards and metrics.
+- **GitHub PR Annotations:** Inline warnings directly in the GitHub PR review interface.
+
+---
+
+## 🖥️ Example CLI Output
+
+```text
+======================================================================
+  DOCUMENTATION DRIFT DETECTOR — PR ANALYSIS
+======================================================================
+Code Changes Analyzed: 3 | Doc Files Scanned: 4
+Drift Issues Found: 2 (2 HIGH, 0 MEDIUM, 0 LOW)
+----------------------------------------------------------------------
+
+Issue #1: DEFAULT VALUE DRIFT  [HIGH - MERGE BLOCKER]
+  Doc Location  : docs/configuration.md:42
+  Wrong Sentence: "The default timeout is 30 seconds before reconnecting."
+  Code Culprit  : src/config.py:12 [DEFAULT_TIMEOUT] (30 -> 60)
+  Suggested Fix : Update default value from '30' to '60'
+
+Issue #2: FLAG / CONFIG RENAME DRIFT  [HIGH - MERGE BLOCKER]
+  Doc Location  : docs/cli_reference.md:88
+  Wrong Sentence: "Run `worker --old-flag` to enable legacy processing mode."
+  Code Culprit  : src/cli.py:54 [--old-flag] (--old-flag -> --new-flag)
+  Suggested Fix : Rename flag/key '--old-flag' to '--new-flag'
+
+======================================================================
+ FAILED: 2 high-confidence drift issue(s) require documentation updates.
+======================================================================
+```
+
+---
+
+## 🤖 GitHub Actions Integration
+
+Add `.github/workflows/doc-drift.yml` to your repository:
+
+```yaml
+name: Documentation Drift Detection
+
+on:
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  check-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run DocDrift
+        run: |
+          python3 doc-drift-detector/drift_detector.py \
+            --base "${{ github.event.pull_request.base.sha }}" \
+            --head "${{ github.event.pull_request.head.sha }}" \
+            --format github
+```
+
+Inline GitHub PR annotations will appear directly on the changed documentation files, blocking merge until documentation is updated!
+
+---
+
+## 🧪 Running Tests
+
+The test suite covers all units, detectors, normalization logic, and end-to-end integration:
+
+```bash
+python3 -m pytest tests/test_basic.py -v
+```
+
+Output:
+```text
+tests/test_basic.py::test_diff_parser_filters_code_files PASSED
+tests/test_basic.py::test_diff_parser_tracks_lines PASSED
+tests/test_basic.py::test_detect_default_value_python_constant PASSED
+tests/test_basic.py::test_detect_default_value_yaml_json PASSED
+tests/test_basic.py::test_detect_default_value_env PASSED
+tests/test_basic.py::test_detect_flag_renames_cli PASSED
+tests/test_basic.py::test_detect_flag_renames_config_key PASSED
+tests/test_basic.py::test_detect_param_change_added_parameter PASSED
+tests/test_basic.py::test_detect_param_change_modified_default PASSED
+tests/test_basic.py::test_detect_feature_removal PASSED
+tests/test_basic.py::test_name_variants_normalization PASSED
+tests/test_basic.py::test_extract_exact_sentence PASSED
+tests/test_basic.py::test_drift_default_value_smart_filter PASSED
+tests/test_basic.py::test_end_to_end_pipeline PASSED
+```
+
+---
+
+## 🏆 Hackathon Highlights
+
+- **Zero-Dependency Core:** Runs everywhere without heavy ML or external network API calls.
+- **Precision First:** Smart filtering eliminates false alarms by validating value occurrences in context.
+- **Universal Code Support:** Works across Python, JS/TS, Go, Rust, Java, YAML, TOML, JSON, and ENV files.
+- **Developer Experience:** Clear, colored terminal UI and automated GitHub Action PR annotations.
+

doc_drift_detector-1.0.0/README.md

@@ -0,0 +1,263 @@
+# 🧭 Documentation Drift Detector (DocDrift)
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.14-blue.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-green.svg)]()
+
+> **Automated Documentation Drift Detection for Pull Requests.**  
+> Catches outdated prose, config tables, default values, renamed flags, and removed features *before* they merge into production.
+
+---
+
+## 💥 The Problem
+
+Documentation silently drifts whenever code changes in a Pull Request:
+* An engineer updates `DEFAULT_TIMEOUT = 30` to `DEFAULT_TIMEOUT = 60` in `settings.py`.
+* The documentation in `docs/config.md` still reads:  
+  > *"The default timeout is 30 seconds."*
+* Existing validation tools (`python -m doctest`, `mktestdocs`, `Doc Detective`) **only validate executable code blocks**. They **CANNOT** detect whether explanatory prose, config tables, or tutorial instructions still match reality.
+
+**DocDrift** solves this by performing semantic diff analysis on code changes in a PR, locating affected documentation, and isolating the **exact sentence** that has drifted—with actionable fix suggestions.
+
+---
+
+## ⚡ Key Capabilities
+
+1. **Semantic PR Diff Parsing:** Analyzes git diffs (`base...head`) across Python, JavaScript/TypeScript, Go, Rust, Java, YAML, TOML, JSON, and `.env` files.
+2. **Four Specialized Semantic Detectors:**
+   - 🔢 **Changed Default Values:** Constants (`DEFAULT_TIMEOUT`), dict defaults, function kwargs, YAML/TOML keys, `.env` settings.
+   - 🚩 **Renamed Flags & Config Keys:** CLI options (`--old-flag` $\to$ `--new-flag` in argparse, Click, Typer) and renamed configuration keys.
+   - ⚙️ **Changed Function Parameters:** Added/removed parameters and modified default arguments via AST analysis.
+   - 🗑️ **Removed Features:** Deleted functions or classes verified to no longer exist in the codebase.
+3. **Smart Natural Language Normalization:** Bridges code and human writing (`DEFAULT_TIMEOUT` $\equiv$ `default_timeout` $\equiv$ `default timeout` $\equiv$ `default-timeout` $\equiv$ `defaultTimeout`).
+4. **False-Alarm Mitigation:** For default value changes, it **only** flags when the **old value** (e.g. `30` or `30s`) actually appears in the documentation sentence.
+5. **Exact Sentence Highlighting:** Extracts and pins the precise faulty sentence and table row.
+6. **First-Class GitHub Actions Workflow:** Generates inline PR diff annotations (`::error`, `::warning`) and PR Step Summaries.
+
+---
+
+## 📁 Project Structure
+
+```text
+doc-drift-detector/
+├── drift_detector.py                  # Main CLI entrypoint
+├── ai/
+│   ├── __init__.py                    # AI package exports
+│   ├── ollama_client.py               # Zero-dependency local Ollama REST client
+│   ├── semantic_verifier.py           # Layer 2: LLM reasoning verification
+│   └── prose_rewriter.py              # Layer 3: Natural prose rewriting
+├── detectors/
+│   ├── __init__.py                    # CodeChange data model & detector exports
+│   ├── default_value.py               # Detects changed default values & constants
+│   ├── flag_rename.py                 # Detects renamed CLI flags & config keys
+│   ├── param_change.py                # Detects changed function signatures & defaults
+│   └── feature_remove.py              # Detects deleted functions & classes
+├── utils/
+│   ├── __init__.py
+│   ├── diff_parser.py                 # Unified git diff parser with line tracking
+│   ├── doc_finder.py                  # Doc discovery, name normalizer, drift & auto-fix engine
+│   └── reporter.py                    # Colored terminal, JSON & GitHub action reporter
+├── .github/workflows/
+│   └── doc-drift.yml                  # Ready-to-use GitHub Action workflow
+├── requirements.txt                   # Dependencies
+├── README.md                          # Documentation
+└── tests/
+    └── test_basic.py                  # Complete test suite (15 passing tests)
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Installation
+
+DocDrift is built primarily using Python's standard library for zero-friction setup.
+
+```bash
+cd doc-drift-detector
+pip install -r requirements.txt
+```
+
+### 2. Analyze a Pull Request Diff
+
+```bash
+# Compare base branch (main) with current branch (HEAD)
+python drift_detector.py --base main --head HEAD
+
+# Analyze an offline diff file
+python drift_detector.py --diff-file my_pr.diff
+
+# Output JSON report
+python drift_detector.py --base main --head HEAD --json
+
+# Save report to a file
+python drift_detector.py --base main --head HEAD --output report.json
+```
+
+---
+
+## 📋 CLI Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base` | `str` | `None` | Base branch or commit SHA (e.g., `main`, `origin/main`, `HEAD~1`) |
+| `--head` | `str` | `None` | Head branch or commit SHA (e.g., `HEAD`) |
+| `--diff-file` | `path` | `None` | Path to pre-generated `.diff` or `.patch` file |
+| `--repo-dir` | `path` | `.` | Root directory of the repository to scan |
+| `--docs-dir` | `path` | `.` | Directory containing documentation files (`.md`, `.rst`, `.adoc`, `.txt`) |
+| `--format` | `choice` | `text` | Output format: `text`, `json`, `github`, or `markdown` |
+| `--json` | `flag` | `False` | Shorthand for `--format json` |
+| `--output` | `path` | `None` | File path to write the formatted report |
+| `--ai` | `flag` | `False` | Enable local Ollama AI hybrid verification & prose rewriting |
+| `--ai-model` | `str` | `auto` | Ollama model to use (e.g. `llama3.2:1b`, `llama3.2`, `mistral`) |
+| `--fix`, `--autofix` | `flag` | `False` | Automatically rewrite outdated documentation files on disk |
+| `--min-confidence` | `choice` | `medium`| Minimum issue confidence to report: `high`, `medium`, or `low` |
+| `--fail-on` | `choice` | `high` | Exit with code `1` if drift of this level is found: `high`, `medium`, `any`, `none` |
+| `-v`, `--verbose` | `flag` | `False` | Enable step-by-step pipeline logging |
+
+---
+
+## 🔍 How It Works (The 5-Step Pipeline)
+
+```mermaid
+flowchart TD
+    A["PR Git Diff<br>(git diff base...head)"] --> B["Step 1: Diff Parser<br>(Track +/- lines & code files)"]
+    B --> C["Step 2: Semantic Detectors<br>(Defaults, Flags, Params, Features)"]
+    C --> D["Step 3: Doc Finder<br>(Normalize names across .md, .rst, .adoc)"]
+    D --> E["Step 4: Smart Drift Engine<br>(Verify old value in text & score confidence)"]
+    E --> F["Step 5: Multi-Format Reporter<br>(CLI Boxes, JSON, GitHub Annotations)"]
+```
+
+### Step 1: Parse PR Diff (`utils/diff_parser.py`)
+- Executes `git diff <base>...<head> --unified=0`.
+- Isolates code files (`.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.yaml`, `.yml`, `.toml`, `.json`, `.env`, `.cfg`, `.ini`).
+- Extracts exact removed (`-`) and added (`+`) lines with source line numbers.
+
+### Step 2: Semantic Code Change Detection (`detectors/`)
+- **Default Values (`default_value.py`):** Pairs removed `VAR = OLD` with added `VAR = NEW`.
+- **Flag Renames (`flag_rename.py`):** Pairs removed `--old-flag` with added `--new-flag`, or renamed config keys with identical values.
+- **Param Changes (`param_change.py`):** Uses Python AST / regex to detect signature modifications and modified default arguments.
+- **Feature Removals (`feature_remove.py`):** Detects deleted functions or classes, verifying they don't exist elsewhere in the repo.
+
+### Step 3: Documentation Search (`utils/doc_finder.py`)
+- Scans `.md`, `.rst`, `.adoc`, and `.txt` files (excluding `.git`, `node_modules`, `venv`, etc.).
+- Normalizes names into searchable variants (`DEFAULT_TIMEOUT` $\to$ `"default timeout"`, `default-timeout`, etc.).
+- Extracts the exact sentence using punctuation boundaries and table row delimitation.
+
+### Step 4: Smart Drift Decision Engine
+- **DEFAULT_VALUE_CHANGED:** Flags **only** if the old value (e.g. `30` or `30s`) appears in the matched doc sentence. If the identifier is mentioned without the old value, it is skipped to prevent false alarms.
+- **FLAG_RENAMED:** Flags if the old flag name appears in documentation.
+- **PARAM_CHANGED:** Flags if removed parameter or old default is in documentation.
+- **FEATURE_REMOVED:** Flags if documentation references the deleted feature.
+
+#### Confidence Levels
+- 🔴 **HIGH (Merge Blocker):** Exact name match + old value confirmed in doc sentence.
+- 🟡 **MEDIUM (Warning):** Normalized match or function signature change.
+- ⚪ **LOW (Info):** Weak / partial match.
+
+### Step 5: Multi-Channel Reporting (`utils/reporter.py`)
+- **Human-Readable CLI:** Rich colored badges, exact file:line references, quotes, and suggested fixes.
+- **JSON Schema:** Machine-readable output for dashboards and metrics.
+- **GitHub PR Annotations:** Inline warnings directly in the GitHub PR review interface.
+
+---
+
+## 🖥️ Example CLI Output
+
+```text
+======================================================================
+  DOCUMENTATION DRIFT DETECTOR — PR ANALYSIS
+======================================================================
+Code Changes Analyzed: 3 | Doc Files Scanned: 4
+Drift Issues Found: 2 (2 HIGH, 0 MEDIUM, 0 LOW)
+----------------------------------------------------------------------
+
+Issue #1: DEFAULT VALUE DRIFT  [HIGH - MERGE BLOCKER]
+  Doc Location  : docs/configuration.md:42
+  Wrong Sentence: "The default timeout is 30 seconds before reconnecting."
+  Code Culprit  : src/config.py:12 [DEFAULT_TIMEOUT] (30 -> 60)
+  Suggested Fix : Update default value from '30' to '60'
+
+Issue #2: FLAG / CONFIG RENAME DRIFT  [HIGH - MERGE BLOCKER]
+  Doc Location  : docs/cli_reference.md:88
+  Wrong Sentence: "Run `worker --old-flag` to enable legacy processing mode."
+  Code Culprit  : src/cli.py:54 [--old-flag] (--old-flag -> --new-flag)
+  Suggested Fix : Rename flag/key '--old-flag' to '--new-flag'
+
+======================================================================
+ FAILED: 2 high-confidence drift issue(s) require documentation updates.
+======================================================================
+```
+
+---
+
+## 🤖 GitHub Actions Integration
+
+Add `.github/workflows/doc-drift.yml` to your repository:
+
+```yaml
+name: Documentation Drift Detection
+
+on:
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  check-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run DocDrift
+        run: |
+          python3 doc-drift-detector/drift_detector.py \
+            --base "${{ github.event.pull_request.base.sha }}" \
+            --head "${{ github.event.pull_request.head.sha }}" \
+            --format github
+```
+
+Inline GitHub PR annotations will appear directly on the changed documentation files, blocking merge until documentation is updated!
+
+---
+
+## 🧪 Running Tests
+
+The test suite covers all units, detectors, normalization logic, and end-to-end integration:
+
+```bash
+python3 -m pytest tests/test_basic.py -v
+```
+
+Output:
+```text
+tests/test_basic.py::test_diff_parser_filters_code_files PASSED
+tests/test_basic.py::test_diff_parser_tracks_lines PASSED
+tests/test_basic.py::test_detect_default_value_python_constant PASSED
+tests/test_basic.py::test_detect_default_value_yaml_json PASSED
+tests/test_basic.py::test_detect_default_value_env PASSED
+tests/test_basic.py::test_detect_flag_renames_cli PASSED
+tests/test_basic.py::test_detect_flag_renames_config_key PASSED
+tests/test_basic.py::test_detect_param_change_added_parameter PASSED
+tests/test_basic.py::test_detect_param_change_modified_default PASSED
+tests/test_basic.py::test_detect_feature_removal PASSED
+tests/test_basic.py::test_name_variants_normalization PASSED
+tests/test_basic.py::test_extract_exact_sentence PASSED
+tests/test_basic.py::test_drift_default_value_smart_filter PASSED
+tests/test_basic.py::test_end_to_end_pipeline PASSED
+```
+
+---
+
+## 🏆 Hackathon Highlights
+
+- **Zero-Dependency Core:** Runs everywhere without heavy ML or external network API calls.
+- **Precision First:** Smart filtering eliminates false alarms by validating value occurrences in context.
+- **Universal Code Support:** Works across Python, JS/TS, Go, Rust, Java, YAML, TOML, JSON, and ENV files.
+- **Developer Experience:** Clear, colored terminal UI and automated GitHub Action PR annotations.
+

doc_drift_detector-1.0.0/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",
+]
+

doc_drift_detector-1.0.0/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
+