readme-drift 1.0.0__tar.gz

readme_drift-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, readme-check contributors <Sachin Nandakumar>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

readme_drift-1.0.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.3
+Name: readme-drift
+Version: 1.0.0
+Summary: Detect stale README references after code changes — for pre-commit and CI.
+License: MIT
+Keywords: readme,documentation,pre-commit,ci,linting
+Author: Sachin Nandakumar
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: pyyaml (>=6.0)
+Project-URL: Homepage, https://github.com/sachn1/readme-drift
+Project-URL: Issues, https://github.com/sachn1/readme-drift/issues
+Description-Content-Type: text/markdown
+
+# readme-drift
+
+> Detect stale README references after code changes — for pre-commit and CI.
+
+When you rename a function, change a method signature, remove a class, or rename a key in a config file, `readme-drift` warns you if those names are still referenced in your README — before the commit lands.
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["git diff"] --> B["Changed .py files\nAST diff"]
+    A --> C["Changed config files\nKey-path diff"]
+    B --> D["Scan README\nbacktick + word-boundary"]
+    C --> D
+    D --> E{"Match?"}
+    E -->|Yes| F["❌ Fail"]
+    E -->|No| G["✅ Pass"]
+```
+
+---
+
+## Installation
+
+```bash
+pip install readme-drift
+```
+
+---
+
+## Usage
+
+### As a pre-commit hook (recommended)
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/sachn1/readme-drift
+    rev: v0.2.0
+    hooks:
+      - id: readme-drift
+```
+
+Then install the hook:
+
+```bash
+pre-commit install
+```
+
+Every `git commit` that changes `.py`, `.yml`, `.yaml`, `.json`, or `.toml` files will now check if the README needs updating.
+
+### As a CLI tool
+
+```bash
+# Check staged changes (same as pre-commit)
+readme-drift --staged
+
+# Check against a specific branch (for CI / PRs)
+readme-drift --base-ref origin/main
+
+# Warn only — don't fail the build
+readme-drift --base-ref origin/main --warn-only
+```
+
+### In CI (GitHub Actions)
+
+```yaml
+- name: Check README staleness
+  run: readme-drift --base-ref origin/${{ github.base_ref }}
+```
+
+---
+
+## Configuration
+
+All CLI flags can be set permanently in `pyproject.toml` under `[tool.readme-drift]`.
+CLI flags always take precedence over the file.
+
+```toml
+[tool.readme-drift]
+# Git ref to diff against. Default: "HEAD"
+base-ref = "origin/main"
+
+# Print warnings but never fail the build. Default: false
+warn-only = false
+
+# Track private (underscore-prefixed) symbols. Default: false
+include-private = false
+
+# Skip files or directories matching these glob patterns.
+# Each entry is equivalent to one --exclude flag on the CLI.
+# Default: []
+exclude = [
+    "generated/",
+    "tests/",
+    "docs/",
+]
+
+# Match symbols as plain text (word-boundary) in addition to backtick spans.
+# Default: true. Set to false to restrict matching to backtick spans only.
+plain-text-search = true
+```
+
+### Supported keys
+
+| Key | Type | CLI equivalent | Default |
+|---|---|---|---|
+| `base-ref` | string | `--base-ref` | `"HEAD"` |
+| `warn-only` | bool | `--warn-only=true/false` | `false` |
+| `include-private` | bool | `--include-private=true/false` | `false` |
+| `exclude` | list of strings | `--exclude` (repeatable) | `[]` |
+| `plain-text-search` | bool | `--plain-text-search=true/false` | `true` |
+
+`pyproject.toml` is discovered by walking up from the current directory (or `--repo-root` if set). If no `[tool.readme-drift]` section is present, all defaults apply.
+
+---
+
+## Developer reference
+
+A fully annotated [Jupyter notebook](notebooks/demo.ipynb) walks through each module in depth — AST parsing, signature extraction, config diffing, the README scanner, and the complete end-to-end pipeline without git. Useful for understanding the internals or experimenting with edge cases.
+
+---
+
+## Example output
+
+```
+readme-drift: ❌ README.md may be stale:
+
+  • `Client.connect` signature changed: connect(host, port) → connect(url)
+    in src/client.py
+    referenced in README.md line 42: …call `Client.connect(host, port)` to connect…
+
+  • `build` was removed
+    in package.json
+    referenced in README.md line 18: …run `npm run build` to compile…
+
+  → Please update the README or run with --no-verify to skip.
+```
+
+---
+
+## What it catches
+
+### Python files (`.py`)
+
+| Change | Detected? |
+|---|---|
+| Function renamed | ✅ old name flagged as removed |
+| Function removed | ✅ |
+| Method signature changed | ✅ |
+| Class removed | ✅ |
+| Private symbol changed (`_name`) | ➖ ignored by design |
+| README updated alongside code | ✅ passes silently |
+| No Python files changed | ✅ skipped |
+
+### Config files (`.yml`, `.yaml`, `.json`, `.toml`)
+
+| Change | Detected? |
+|---|---|
+| Script key removed (`"build"` → gone) | ✅ |
+| Job name removed (`build:` → gone) | ✅ |
+| Tool section removed (`[tool.black]` → gone) | ✅ |
+| Key renamed at same level | ✅ (reported as remove + add) |
+| Value changed, key unchanged | ➖ not tracked |
+
+## What it doesn't catch
+
+- Behavioral changes that don't affect the public API or config surface
+- Symbols not mentioned in the README
+
+---
+
+## Supported README formats
+
+Any file named `readme` (case-insensitive) with the extension `.md`, `.markdown`, `.rst`, `.txt`, or no extension is scanned. All README files in the repository are discovered recursively, including per-package READMEs in monorepos.
+
+The following directories are never searched:
+
+`.git` · `node_modules` · `venv` · `.venv` · `.tox` · `__pycache__` · `.pytest_cache` · `dist` · `build` · `.mypy_cache`
+
+---
+
+## License
+
+MIT
+

readme_drift-1.0.0/README.md

@@ -0,0 +1,187 @@
+# readme-drift
+
+> Detect stale README references after code changes — for pre-commit and CI.
+
+When you rename a function, change a method signature, remove a class, or rename a key in a config file, `readme-drift` warns you if those names are still referenced in your README — before the commit lands.
+
+---
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["git diff"] --> B["Changed .py files\nAST diff"]
+    A --> C["Changed config files\nKey-path diff"]
+    B --> D["Scan README\nbacktick + word-boundary"]
+    C --> D
+    D --> E{"Match?"}
+    E -->|Yes| F["❌ Fail"]
+    E -->|No| G["✅ Pass"]
+```
+
+---
+
+## Installation
+
+```bash
+pip install readme-drift
+```
+
+---
+
+## Usage
+
+### As a pre-commit hook (recommended)
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/sachn1/readme-drift
+    rev: v0.2.0
+    hooks:
+      - id: readme-drift
+```
+
+Then install the hook:
+
+```bash
+pre-commit install
+```
+
+Every `git commit` that changes `.py`, `.yml`, `.yaml`, `.json`, or `.toml` files will now check if the README needs updating.
+
+### As a CLI tool
+
+```bash
+# Check staged changes (same as pre-commit)
+readme-drift --staged
+
+# Check against a specific branch (for CI / PRs)
+readme-drift --base-ref origin/main
+
+# Warn only — don't fail the build
+readme-drift --base-ref origin/main --warn-only
+```
+
+### In CI (GitHub Actions)
+
+```yaml
+- name: Check README staleness
+  run: readme-drift --base-ref origin/${{ github.base_ref }}
+```
+
+---
+
+## Configuration
+
+All CLI flags can be set permanently in `pyproject.toml` under `[tool.readme-drift]`.
+CLI flags always take precedence over the file.
+
+```toml
+[tool.readme-drift]
+# Git ref to diff against. Default: "HEAD"
+base-ref = "origin/main"
+
+# Print warnings but never fail the build. Default: false
+warn-only = false
+
+# Track private (underscore-prefixed) symbols. Default: false
+include-private = false
+
+# Skip files or directories matching these glob patterns.
+# Each entry is equivalent to one --exclude flag on the CLI.
+# Default: []
+exclude = [
+    "generated/",
+    "tests/",
+    "docs/",
+]
+
+# Match symbols as plain text (word-boundary) in addition to backtick spans.
+# Default: true. Set to false to restrict matching to backtick spans only.
+plain-text-search = true
+```
+
+### Supported keys
+
+| Key | Type | CLI equivalent | Default |
+|---|---|---|---|
+| `base-ref` | string | `--base-ref` | `"HEAD"` |
+| `warn-only` | bool | `--warn-only=true/false` | `false` |
+| `include-private` | bool | `--include-private=true/false` | `false` |
+| `exclude` | list of strings | `--exclude` (repeatable) | `[]` |
+| `plain-text-search` | bool | `--plain-text-search=true/false` | `true` |
+
+`pyproject.toml` is discovered by walking up from the current directory (or `--repo-root` if set). If no `[tool.readme-drift]` section is present, all defaults apply.
+
+---
+
+## Developer reference
+
+A fully annotated [Jupyter notebook](notebooks/demo.ipynb) walks through each module in depth — AST parsing, signature extraction, config diffing, the README scanner, and the complete end-to-end pipeline without git. Useful for understanding the internals or experimenting with edge cases.
+
+---
+
+## Example output
+
+```
+readme-drift: ❌ README.md may be stale:
+
+  • `Client.connect` signature changed: connect(host, port) → connect(url)
+    in src/client.py
+    referenced in README.md line 42: …call `Client.connect(host, port)` to connect…
+
+  • `build` was removed
+    in package.json
+    referenced in README.md line 18: …run `npm run build` to compile…
+
+  → Please update the README or run with --no-verify to skip.
+```
+
+---
+
+## What it catches
+
+### Python files (`.py`)
+
+| Change | Detected? |
+|---|---|
+| Function renamed | ✅ old name flagged as removed |
+| Function removed | ✅ |
+| Method signature changed | ✅ |
+| Class removed | ✅ |
+| Private symbol changed (`_name`) | ➖ ignored by design |
+| README updated alongside code | ✅ passes silently |
+| No Python files changed | ✅ skipped |
+
+### Config files (`.yml`, `.yaml`, `.json`, `.toml`)
+
+| Change | Detected? |
+|---|---|
+| Script key removed (`"build"` → gone) | ✅ |
+| Job name removed (`build:` → gone) | ✅ |
+| Tool section removed (`[tool.black]` → gone) | ✅ |
+| Key renamed at same level | ✅ (reported as remove + add) |
+| Value changed, key unchanged | ➖ not tracked |
+
+## What it doesn't catch
+
+- Behavioral changes that don't affect the public API or config surface
+- Symbols not mentioned in the README
+
+---
+
+## Supported README formats
+
+Any file named `readme` (case-insensitive) with the extension `.md`, `.markdown`, `.rst`, `.txt`, or no extension is scanned. All README files in the repository are discovered recursively, including per-package READMEs in monorepos.
+
+The following directories are never searched:
+
+`.git` · `node_modules` · `venv` · `.venv` · `.tox` · `__pycache__` · `.pytest_cache` · `dist` · `build` · `.mypy_cache`
+
+---
+
+## License
+
+MIT

readme_drift-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "readme-drift"
+version = "1.0.0"
+description = "Detect stale README references after code changes — for pre-commit and CI."
+authors = ["Sachin Nandakumar"]
+readme = "README.md"
+license = "MIT"
+keywords = ["readme", "documentation", "pre-commit", "ci", "linting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+]
+packages = [{ include = "readme_drift" }]
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+pyyaml = ">=6.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.0"
+pytest-cov = ">=4.0"
+ruff = ">=0.4"
+commitizen = ">=4.1.1,<5"
+types-PyYAML = ">=6.0"
+
+[tool.poetry.scripts]
+readme-drift = "readme_drift.cli:main"
+
+[tool.poetry.urls]
+Homepage = "https://github.com/sachn1/readme-drift"
+Issues = "https://github.com/sachn1/readme-drift/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "poetry"
+version_scheme = "semver2"
+tag_format = "v$version"
+update_changelog_on_bump = false
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+exclude = ["docs", "*.md", "*.ipynb"]

readme_drift-1.0.0/readme_drift/ast_diff.py

@@ -0,0 +1,224 @@
+"""AST-based diffing to extract changed public symbols between two code versions."""
+
+import ast
+
+from .models import ChangeType, PublicAPI, SymbolChange
+
+
+def _is_public(name: str) -> bool:
+    """Determine if a name is public (does not start with an underscore)."""
+    return not name.startswith("_")
+
+
+def _positional_args_with_defaults(
+    arg_list: list[ast.arg],
+    offset: int,
+    num_all: int,
+    defaults: list[ast.expr],
+) -> list[str]:
+    """Format a slice of positional args, resolving the shared defaults array."""
+    num_defaults = len(defaults)
+    result = []
+    for i, arg in enumerate(arg_list):
+        if arg.arg in ("self", "cls"):
+            continue
+        default_index = (offset + i) - (num_all - num_defaults)
+
+        # default_index >= 0 means this arg has a default value in the defaults array
+        if default_index >= 0:
+            result.append(f"{arg.arg}={ast.unparse(defaults[default_index])}")
+        else:
+            result.append(arg.arg)
+    return result
+
+
+def _kwonly_args(
+    kwonlyargs: list[ast.arg],
+    kw_defaults: list[ast.expr | None],
+) -> list[str]:
+    """Format keyword-only args with their optional defaults."""
+    result = []
+    for arg, default in zip(kwonlyargs, kw_defaults):
+        if default is not None:
+            result.append(f"{arg.arg}={ast.unparse(default)}")
+        else:
+            result.append(arg.arg)
+    return result
+
+
+def _format_signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Format a function/method signature as a readable string.
+
+    ast.unparse is intentionally avoided: it retains self/cls and type
+    annotations, which only affects report readability — the signature
+    string is never used for detection, only for display in the output.
+    """
+    func_args = node.args
+    num_all = len(func_args.posonlyargs) + len(func_args.args)
+
+    posonly = _positional_args_with_defaults(
+        func_args.posonlyargs, 0, num_all, func_args.defaults
+    )
+
+    regular = _positional_args_with_defaults(
+        func_args.args, len(func_args.posonlyargs), num_all, func_args.defaults
+    )
+
+    parts = [*posonly]
+    if posonly:
+        parts.append("/")
+    parts.extend(regular)
+
+    if func_args.vararg:
+        parts.append(f"*{func_args.vararg.arg}")
+    elif func_args.kwonlyargs:
+        parts.append("*")
+
+    parts.extend(_kwonly_args(func_args.kwonlyargs, func_args.kw_defaults))
+
+    if func_args.kwarg:
+        parts.append(f"**{func_args.kwarg.arg}")
+
+    return f"{node.name}({', '.join(parts)})"
+
+
+def extract_public_api(source: str, *, include_private: bool = False) -> PublicAPI:
+    """Parse Python source and extract the public API surface.
+
+    Parameters
+    ----------
+    source : str
+        The source code of a Python module.
+
+    Returns
+    -------
+    PublicAPI
+        An object containing the public functions, classes, and methods defined in the source.
+    """
+    if not source.strip():
+        return PublicAPI()
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return PublicAPI()
+
+    api = PublicAPI()
+
+    is_visible = (lambda _: True) if include_private else _is_public
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef) and is_visible(node.name):
+            method_sigs: set[str] = set()
+            for item in node.body:
+                if isinstance(
+                    item, (ast.FunctionDef, ast.AsyncFunctionDef)
+                ) and is_visible(item.name):
+                    sig = _format_signature(item)
+                    method_sigs.add(sig)
+                    api.methods[f"{node.name}.{item.name}"] = sig
+            api.classes[node.name] = method_sigs
+
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and is_visible(
+            node.name
+        ):
+            # Only top-level functions
+            api.functions[node.name] = _format_signature(node)
+
+    return api
+
+
+def diff_apis(
+    old_source: str,
+    new_source: str,
+    file: str = "",
+    *,
+    include_private: bool = False,
+) -> list[SymbolChange]:
+    """Compare two versions of a Python file and return what changed.
+
+    Parameters
+    ----------
+    old_source : str
+        The source code of the old version of the Python module.
+    new_source : str
+        The source code of the new version of the Python module.
+    file : str, optional
+        The name of the file being compared, by default "".
+    include_private : bool, optional
+        If True, include private (underscore-prefixed) symbols, by default False.
+
+    Returns
+    -------
+    list[SymbolChange]
+        A list of changes detected between the old and new versions.
+    """
+    old_api = extract_public_api(old_source, include_private=include_private)
+    new_api = extract_public_api(new_source, include_private=include_private)
+
+    changes: list[SymbolChange] = []
+
+    # Diff top-level functions
+    changes.extend(_diff_signatures(old_api.functions, new_api.functions, file))
+
+    # Diff classes
+    old_classes = set(old_api.classes)
+    new_classes = set(new_api.classes)
+
+    for cls in old_classes - new_classes:
+        changes.append(SymbolChange(cls, ChangeType.REMOVED, file=file))
+
+    for cls in new_classes - old_classes:
+        changes.append(SymbolChange(cls, ChangeType.ADDED, file=file))
+
+    # Diff methods within classes that exist in both
+    for cls in old_classes & new_classes:
+        old_methods = {
+            k.split(".")[1]: v
+            for k, v in old_api.methods.items()
+            if k.startswith(f"{cls}.")
+        }
+        new_methods = {
+            k.split(".")[1]: v
+            for k, v in new_api.methods.items()
+            if k.startswith(f"{cls}.")
+        }
+        for change in _diff_signatures(old_methods, new_methods, file):
+            # Prefix with class name
+            change.name = f"{cls}.{change.name}"
+            if change.old_signature:
+                change.old_signature = f"{cls}.{change.old_signature}"
+            if change.new_signature:
+                change.new_signature = f"{cls}.{change.new_signature}"
+            changes.append(change)
+
+    return changes
+
+
+def _diff_signatures(
+    old: dict[str, str],
+    new: dict[str, str],
+    file: str,
+) -> list[SymbolChange]:
+    """Helper to diff two sets of signatures (functions or methods)."""
+    changes: list[SymbolChange] = []
+
+    for name in set(old) - set(new):
+        changes.append(SymbolChange(name, ChangeType.REMOVED, file=file))
+
+    for name in set(new) - set(old):
+        changes.append(SymbolChange(name, ChangeType.ADDED, file=file))
+
+    for name in set(old) & set(new):
+        if old[name] != new[name]:
+            changes.append(
+                SymbolChange(
+                    name=name,
+                    change_type=ChangeType.SIGNATURE_CHANGED,
+                    old_signature=old[name],
+                    new_signature=new[name],
+                    file=file,
+                )
+            )
+
+    return changes