docparity 0.1.0__tar.gz

docparity-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v

docparity-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

docparity-0.1.0/DETAILS.md

@@ -0,0 +1,57 @@
+# Design notes
+
+## The gap
+
+Docstring-vs-signature drift is distinct from every existing docstring
+tool:
+
+- `pydocstyle` / `flake8-docstrings` / `pydoclint` check *presence and
+  formatting conventions* (is there a docstring, does it start with a
+  capital letter, blank line rules). Some (pydoclint, darglint) do check
+  parameter lists against docstrings -- but they require adopting a full
+  docstring-linting workflow and tend to also demand full coverage
+  (every function must be fully documented), which produces high friction
+  and gets disabled. docparity does one narrow thing: catch *drift* in
+  code that already chose to document its parameters, with zero
+  configuration and zero opinion about which functions should have docs.
+- Type checkers (mypy/pyright) validate the type *signature*, never the
+  prose in a docstring.
+- `interrogate` measures docstring *coverage* (percentage of functions
+  documented), not correctness of what's already there.
+
+The genuinely tedious, currently-manual work this replaces: a reviewer
+(or nobody) has to notice, function by function, that a docstring's
+`Args:` block still lists a parameter that was renamed three refactors
+ago, or is missing one that was added last week. In a large codebase this
+is invisible until someone reading the docs gets misled, or an LLM
+coding assistant trusts the stale docstring and generates code calling
+the wrong parameter name.
+
+## Scope boundaries (v0.1)
+
+- Only two checks: stale documented parameter, missing documentation for
+  a real parameter that already has a params section.
+- Only triggers on functions that already document at least one
+  parameter -- never nags about undocumented functions. This is the
+  single biggest false-positive-avoidance decision: a tool that also
+  flags "no docstring at all" gets disabled on first run in any real
+  codebase.
+- No type-annotation cross-checking (documented type vs. real
+  annotation) in v0.1 -- name drift is the highest-value, lowest-noise
+  check to start with.
+- No return-value or raises-section checking in v0.1.
+- `self` and `cls` are always excluded from comparison.
+- `*args` / `**kwargs` are compared by their own names (`args`, `kwargs`),
+  matching how both Google and reST style documents them in practice.
+
+## Docstring styles supported
+
+Google, NumPy, and Sphinx/reST (`:param:`) -- detected independently per
+docstring, not configured globally, since large codebases often mix
+styles across modules.
+
+## Non-goals
+
+- Not a docstring-coverage tool (see `interrogate` for that).
+- Not a docstring-formatting linter (see `pydocstyle` for that).
+- Not a type-checker.

docparity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay
+
+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.

docparity-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: docparity
+Version: 0.1.0
+Summary: Detects drift between a function's docstring parameters and its real signature (Google, NumPy, and Sphinx styles).
+Author: Jay
+License: MIT
+License-File: LICENSE
+Keywords: code-quality,docstring,documentation,linter,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# docparity
+
+Detects drift between a function's **docstring parameters** and its **real
+signature** -- the classic case of renaming or removing a parameter and
+forgetting to update the docstring, so the documentation quietly lies to
+the next reader (or to an LLM/IDE that trusts it).
+
+Supports Google, NumPy, and Sphinx (`:param:`) docstring styles. Zero
+runtime dependencies, pure `ast`-based static analysis.
+
+## Why
+
+Docstrings drift silently:
+
+```python
+def charge_card(amount, currency):
+    """Charge a card.
+
+    Args:
+        amount (float): the amount to charge
+        card_token (str): the card token to charge   # <- renamed to `currency`, doc never updated
+    """
+```
+
+Nothing catches this today. Type checkers don't read docstrings. Linters
+that check docstring *presence* (pydocstyle, flake8-docstrings) don't check
+that documented parameter names still match the signature. The result is
+stale documentation that misleads humans, and misleads LLM coding
+assistants and IDEs that surface docstrings as ground truth.
+
+## Install
+
+```bash
+pip install docparity
+```
+
+## Usage
+
+```bash
+docparity src/                 # scan a directory recursively
+docparity mymodule.py          # scan a single file
+docparity --stale-only src/    # only report renamed/removed params, not missing docs
+```
+
+Exit codes: `0` clean, `1` findings reported, `2` usage/syntax error.
+
+## What it checks (v0.1)
+
+1. **Stale documented parameter** -- the docstring documents a parameter
+   name that no longer exists in the real signature (renamed or removed).
+2. **Missing documentation for a real parameter** -- the function already
+   has a params section, and a real parameter isn't in it (added to the
+   signature, forgotten in the docs).
+
+docparity only checks functions that **already document at least one
+parameter**. It never asks you to add documentation to an undocumented
+function -- that's a coverage tool's job, not a drift tool's job. This
+keeps false positives near zero.
+
+## Library usage
+
+```python
+from docparity import scan_file
+
+findings = scan_file("mymodule.py")
+for f in findings:
+    print(f)
+```
+
+See [docs/USAGE.md](docs/USAGE.md) for more, and [DETAILS.md](DETAILS.md)
+for design rationale and scope boundaries.
+
+## License
+
+MIT

docparity-0.1.0/README.md

@@ -0,0 +1,75 @@
+# docparity
+
+Detects drift between a function's **docstring parameters** and its **real
+signature** -- the classic case of renaming or removing a parameter and
+forgetting to update the docstring, so the documentation quietly lies to
+the next reader (or to an LLM/IDE that trusts it).
+
+Supports Google, NumPy, and Sphinx (`:param:`) docstring styles. Zero
+runtime dependencies, pure `ast`-based static analysis.
+
+## Why
+
+Docstrings drift silently:
+
+```python
+def charge_card(amount, currency):
+    """Charge a card.
+
+    Args:
+        amount (float): the amount to charge
+        card_token (str): the card token to charge   # <- renamed to `currency`, doc never updated
+    """
+```
+
+Nothing catches this today. Type checkers don't read docstrings. Linters
+that check docstring *presence* (pydocstyle, flake8-docstrings) don't check
+that documented parameter names still match the signature. The result is
+stale documentation that misleads humans, and misleads LLM coding
+assistants and IDEs that surface docstrings as ground truth.
+
+## Install
+
+```bash
+pip install docparity
+```
+
+## Usage
+
+```bash
+docparity src/                 # scan a directory recursively
+docparity mymodule.py          # scan a single file
+docparity --stale-only src/    # only report renamed/removed params, not missing docs
+```
+
+Exit codes: `0` clean, `1` findings reported, `2` usage/syntax error.
+
+## What it checks (v0.1)
+
+1. **Stale documented parameter** -- the docstring documents a parameter
+   name that no longer exists in the real signature (renamed or removed).
+2. **Missing documentation for a real parameter** -- the function already
+   has a params section, and a real parameter isn't in it (added to the
+   signature, forgotten in the docs).
+
+docparity only checks functions that **already document at least one
+parameter**. It never asks you to add documentation to an undocumented
+function -- that's a coverage tool's job, not a drift tool's job. This
+keeps false positives near zero.
+
+## Library usage
+
+```python
+from docparity import scan_file
+
+findings = scan_file("mymodule.py")
+for f in findings:
+    print(f)
+```
+
+See [docs/USAGE.md](docs/USAGE.md) for more, and [DETAILS.md](DETAILS.md)
+for design rationale and scope boundaries.
+
+## License
+
+MIT

docparity-0.1.0/docs/USAGE.md

@@ -0,0 +1,60 @@
+# Usage
+
+## CLI
+
+```bash
+docparity <path> [<path> ...] [--stale-only]
+```
+
+- `<path>` -- one or more files or directories. Directories are scanned
+  recursively for `*.py` files.
+- `--stale-only` -- only print "stale" findings (documented parameters
+  that no longer exist in the signature). Suppresses "missing
+  documentation" findings, useful if you want a stricter/quieter signal
+  in CI to start with.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0    | No findings |
+| 1    | One or more findings printed |
+| 2    | No Python files found, or a file failed to parse |
+
+## Example
+
+```
+$ docparity examples/drifted_example.py
+examples/drifted_example.py:4: charge_card(): docstring documents 'card_token' which is not a parameter
+examples/drifted_example.py:4: charge_card(): parameter 'currency' is not documented
+```
+
+## CI integration
+
+Add to a pre-commit hook or CI step:
+
+```yaml
+- name: Check docstring/signature drift
+  run: docparity src/
+```
+
+A non-zero exit fails the step only when a documented parameter has
+drifted from the real signature.
+
+## Library API
+
+```python
+from docparity import scan_file, scan_source
+
+# From a file on disk
+findings = scan_file("mymodule.py")
+
+# From a source string (e.g. in a pre-commit hook operating on staged content)
+findings = scan_source(source_text, filename="mymodule.py")
+
+for f in findings:
+    print(f.file, f.line, f.function, f.kind, f.param)
+```
+
+`Finding.kind` is either `"stale"` (documented, not a real parameter) or
+`"missing"` (real parameter, not documented).

docparity-0.1.0/examples/README.md

@@ -0,0 +1,7 @@
+# Examples
+
+- `drifted_example.py` -- a function whose docstring still documents a
+  parameter (`card_token`) that was renamed (`currency`) in the real
+  signature. Run `docparity examples/drifted_example.py` to see it flagged.
+- `clean_example.py` -- the same idea kept in sync, plus a function with no
+  params section at all (which docparity intentionally never flags).

docparity-0.1.0/examples/clean_example.py

@@ -0,0 +1,21 @@
+"""Example module with no drift -- docparity reports nothing here."""
+
+
+def charge_card(amount, currency):
+    """Charge a card.
+
+    Args:
+        amount (float): the amount to charge
+        currency (str): the ISO 4217 currency code
+    """
+    return amount, currency
+
+
+def refund(amount):
+    """Refund an amount without a documented params section.
+
+    docparity does not flag this: it never asks you to add
+    documentation, only to fix documentation that already exists and
+    has drifted from the real signature.
+    """
+    return amount

docparity-0.1.0/examples/drifted_example.py

@@ -0,0 +1,26 @@
+"""Example module with docstring/signature drift for docparity to catch."""
+
+
+def charge_card(amount, currency):
+    """Charge a card.
+
+    Args:
+        amount (float): the amount to charge
+        card_token (str): the card token to charge
+
+    A parameter was renamed from ``card_token`` to ``currency`` in the
+    signature, but the docstring was never updated. docparity reports:
+
+    - stale: 'card_token' is documented but no longer a real parameter
+    - missing: 'currency' is a real parameter but is not documented
+    """
+    return amount, currency
+
+
+def refund(amount):
+    """Refund an amount.
+
+    Args:
+        amount (float): the amount to refund
+    """
+    return amount

docparity-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docparity"
+version = "0.1.0"
+description = "Detects drift between a function's docstring parameters and its real signature (Google, NumPy, and Sphinx styles)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Jay" }]
+keywords = ["docstring", "static-analysis", "linter", "documentation", "code-quality"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+docparity = "docparity.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docparity"]

docparity-0.1.0/pytest.ini

@@ -0,0 +1 @@
+[pytest]

docparity-0.1.0/src/docparity/__init__.py

@@ -0,0 +1,7 @@
+"""docparity - detect drift between a function's docstring and its real signature."""
+
+from .scanner import scan_file, scan_source, Finding
+
+__all__ = ["scan_file", "scan_source", "Finding"]
+
+__version__ = "0.1.0"

docparity-0.1.0/src/docparity/cli.py

@@ -0,0 +1,77 @@
+"""docparity command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .scanner import scan_file
+
+
+def _iter_python_files(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_dir():
+            files.extend(sorted(p.rglob("*.py")))
+        elif p.suffix == ".py":
+            files.append(p)
+    return files
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docparity",
+        description=(
+            "Detect drift between a function's docstring parameters and its "
+            "real signature (Google, NumPy, and Sphinx docstring styles)."
+        ),
+    )
+    parser.add_argument(
+        "paths", nargs="+", help="Python files or directories to scan"
+    )
+    parser.add_argument(
+        "--stale-only",
+        action="store_true",
+        help=(
+            "Only report stale documented parameters (removed/renamed in "
+            "the signature). Suppresses 'missing documentation' findings."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    files = _iter_python_files(args.paths)
+    if not files:
+        print("docparity: no Python files found", file=sys.stderr)
+        return 2
+
+    total = 0
+    had_error = False
+    for f in files:
+        try:
+            findings = scan_file(f)
+        except SyntaxError as exc:
+            print(f"docparity: {f}: syntax error: {exc}", file=sys.stderr)
+            had_error = True
+            continue
+
+        if args.stale_only:
+            findings = [fnd for fnd in findings if fnd.kind == "stale"]
+
+        for finding in findings:
+            print(str(finding))
+            total += 1
+
+    if had_error:
+        return 2
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docparity-0.1.0/src/docparity/docstring_parser.py

@@ -0,0 +1,126 @@
+"""Extract documented parameter names from a docstring.
+
+Supports the three docstring styles used in practice:
+
+- Google style::
+
+    Args:
+        name (str): description
+        other: description
+
+- NumPy style::
+
+    Parameters
+    ----------
+    name : str
+        description
+
+- Sphinx / reST style::
+
+    :param name: description
+    :param str other: description
+
+Only the *names* of documented parameters are extracted -- docparity
+compares names against the real signature, it does not attempt to
+validate types or descriptions.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParsedDocstring:
+    documented_params: list[str] = field(default_factory=list)
+    has_params_section: bool = False
+
+
+_GOOGLE_SECTION_RE = re.compile(
+    r"^\s*(Args|Arguments|Parameters)\s*:\s*$", re.MULTILINE
+)
+_GOOGLE_PARAM_RE = re.compile(
+    r"^\s{2,}(\*{0,2}[A-Za-z_][A-Za-z0-9_]*)\s*(\(.*?\))?\s*:", re.MULTILINE
+)
+_GOOGLE_SECTION_STOP_RE = re.compile(
+    r"^\s*(Returns|Yields|Raises|Examples?|Note|Notes|Attributes)\s*:\s*$",
+    re.MULTILINE,
+)
+
+_NUMPY_SECTION_RE = re.compile(
+    r"^\s*Parameters\s*\n\s*-{3,}\s*$", re.MULTILINE
+)
+_NUMPY_PARAM_RE = re.compile(
+    r"^([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*(:.*)?$"
+)
+_NUMPY_SECTION_STOP_RE = re.compile(
+    r"^\s*(Returns|Yields|Raises|Examples?|Notes?|Attributes)\s*\n\s*-{3,}\s*$",
+    re.MULTILINE,
+)
+
+_SPHINX_PARAM_RE = re.compile(
+    r"^\s*:param\s+(?:[A-Za-z_][A-Za-z0-9_.\[\]]*\s+)?\*{0,2}([A-Za-z_][A-Za-z0-9_]*)\s*:",
+    re.MULTILINE,
+)
+
+
+def _extract_google(doc: str) -> list[str] | None:
+    m = _GOOGLE_SECTION_RE.search(doc)
+    if not m:
+        return None
+    start = m.end()
+    stop_m = _GOOGLE_SECTION_STOP_RE.search(doc, pos=start)
+    end = stop_m.start() if stop_m else len(doc)
+    section = doc[start:end]
+    return [pm.group(1).lstrip("*") for pm in _GOOGLE_PARAM_RE.finditer(section)]
+
+
+def _extract_numpy(doc: str) -> list[str] | None:
+    m = _NUMPY_SECTION_RE.search(doc)
+    if not m:
+        return None
+    start = m.end()
+    stop_m = _NUMPY_SECTION_STOP_RE.search(doc, pos=start)
+    end = stop_m.start() if stop_m else len(doc)
+    section = doc[start:end]
+    names: list[str] = []
+    for raw_line in section.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        # Only lines that look like "name : type" or "name" (not indented
+        # description text, which NumPy style indents further than the name).
+        indent = len(raw_line) - len(raw_line.lstrip(" "))
+        if indent > 4:
+            continue
+        pm = _NUMPY_PARAM_RE.match(line)
+        if pm:
+            for n in pm.group(1).split(","):
+                names.append(n.strip())
+    return names
+
+
+def _extract_sphinx(doc: str) -> list[str] | None:
+    names = [pm.group(1) for pm in _SPHINX_PARAM_RE.finditer(doc)]
+    return names or None
+
+
+def parse_docstring(doc: str | None) -> ParsedDocstring:
+    """Parse a docstring and return the set of documented parameter names.
+
+    Returns an empty, ``has_params_section=False`` result when no
+    recognizable parameter section is found. docparity intentionally does
+    not flag functions with no params section at all -- only functions
+    that already document *some* parameters but have drifted from the
+    real signature.
+    """
+    if not doc:
+        return ParsedDocstring()
+
+    for extractor in (_extract_google, _extract_numpy, _extract_sphinx):
+        names = extractor(doc)
+        if names is not None:
+            return ParsedDocstring(documented_params=names, has_params_section=True)
+
+    return ParsedDocstring()

docparity-0.1.0/src/docparity/scanner.py

@@ -0,0 +1,108 @@
+"""Scan Python source for docstring-vs-signature parameter drift."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+from .docstring_parser import parse_docstring
+
+# Parameters that are conventionally excluded from docstrings and should
+# never trigger an "undocumented parameter" finding.
+_IGNORED_PARAMS = {"self", "cls"}
+
+
+@dataclass
+class Finding:
+    file: str
+    line: int
+    function: str
+    kind: str  # "stale" (documented but not in signature) or "missing" (in
+    # signature but not documented)
+    param: str
+
+    def __str__(self) -> str:
+        if self.kind == "stale":
+            msg = f"docstring documents '{self.param}' which is not a parameter"
+        else:
+            msg = f"parameter '{self.param}' is not documented"
+        return f"{self.file}:{self.line}: {self.function}(): {msg}"
+
+
+def _real_params(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    args = node.args
+    names = []
+    for a in args.posonlyargs:
+        names.append(a.arg)
+    for a in args.args:
+        names.append(a.arg)
+    if args.vararg:
+        names.append(args.vararg.arg)
+    for a in args.kwonlyargs:
+        names.append(a.arg)
+    if args.kwarg:
+        names.append(args.kwarg.arg)
+    return [n for n in names if n not in _IGNORED_PARAMS]
+
+
+def _check_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef, filename: str
+) -> list[Finding]:
+    findings: list[Finding] = []
+    doc = ast.get_docstring(node)
+    parsed = parse_docstring(doc)
+    if not parsed.has_params_section:
+        # No documented parameter section -- nothing to compare, and
+        # flagging undocumented functions is out of scope (that is a
+        # coverage tool's job, not a drift tool's job).
+        return findings
+
+    real = _real_params(node)
+    real_set = set(real)
+    documented = parsed.documented_params
+    documented_set = set(documented)
+
+    for name in documented:
+        if name not in real_set:
+            findings.append(
+                Finding(
+                    file=filename,
+                    line=node.lineno,
+                    function=node.name,
+                    kind="stale",
+                    param=name,
+                )
+            )
+
+    for name in real:
+        if name not in documented_set:
+            findings.append(
+                Finding(
+                    file=filename,
+                    line=node.lineno,
+                    function=node.name,
+                    kind="missing",
+                    param=name,
+                )
+            )
+
+    return findings
+
+
+def scan_source(source: str, filename: str = "<string>") -> list[Finding]:
+    """Scan a source string and return a list of drift findings."""
+    tree = ast.parse(source, filename=filename)
+    findings: list[Finding] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            findings.extend(_check_function(node, filename))
+    findings.sort(key=lambda f: (f.line, f.function, f.param))
+    return findings
+
+
+def scan_file(path: str | Path) -> list[Finding]:
+    """Scan a single Python file on disk and return a list of drift findings."""
+    path = Path(path)
+    source = path.read_text(encoding="utf-8")
+    return scan_source(source, filename=str(path))

docparity-0.1.0/tests/test_cli.py

@@ -0,0 +1,86 @@
+import textwrap
+
+from docparity.cli import main
+
+
+def _write(tmp_path, name, content):
+    p = tmp_path / name
+    p.write_text(textwrap.dedent(content))
+    return p
+
+
+def test_cli_exits_zero_when_clean(tmp_path, capsys):
+    _write(
+        tmp_path,
+        "clean.py",
+        '''
+        def greet(name):
+            """Greet.
+
+            Args:
+                name: the name
+            """
+            return name
+        ''',
+    )
+    code = main([str(tmp_path)])
+    assert code == 0
+    out = capsys.readouterr().out
+    assert out == ""
+
+
+def test_cli_exits_one_and_prints_findings(tmp_path, capsys):
+    _write(
+        tmp_path,
+        "drift.py",
+        '''
+        def greet(name):
+            """Greet.
+
+            Args:
+                name: the name
+                title: stale
+            """
+            return name
+        ''',
+    )
+    code = main([str(tmp_path)])
+    assert code == 1
+    out = capsys.readouterr().out
+    assert "title" in out
+    assert "drift.py" in out
+
+
+def test_cli_stale_only_filters_missing_findings(tmp_path, capsys):
+    _write(
+        tmp_path,
+        "drift.py",
+        '''
+        def greet(name, title):
+            """Greet.
+
+            Args:
+                name: the name
+            """
+            return name
+        ''',
+    )
+    code = main([str(tmp_path), "--stale-only"])
+    assert code == 0
+    out = capsys.readouterr().out
+    assert out == ""
+
+
+def test_cli_no_python_files_found(tmp_path, capsys):
+    code = main([str(tmp_path)])
+    assert code == 2
+    err = capsys.readouterr().err
+    assert "no Python files found" in err
+
+
+def test_cli_syntax_error_reported(tmp_path, capsys):
+    _write(tmp_path, "bad.py", "def f(:\n")
+    code = main([str(tmp_path)])
+    assert code == 2
+    err = capsys.readouterr().err
+    assert "syntax error" in err

docparity-0.1.0/tests/test_docstring_parser.py

@@ -0,0 +1,82 @@
+from docparity.docstring_parser import parse_docstring
+
+
+def test_no_docstring():
+    result = parse_docstring(None)
+    assert result.has_params_section is False
+    assert result.documented_params == []
+
+
+def test_docstring_with_no_params_section():
+    result = parse_docstring("Just a summary line.\n\nNo params documented here.")
+    assert result.has_params_section is False
+
+
+def test_google_style_args():
+    doc = """Do a thing.
+
+    Args:
+        name (str): the name
+        count (int): how many
+
+    Returns:
+        bool: success
+    """
+    result = parse_docstring(doc)
+    assert result.has_params_section is True
+    assert result.documented_params == ["name", "count"]
+
+
+def test_google_style_arguments_header_and_star_args():
+    doc = """Do a thing.
+
+    Arguments:
+        *args: positional
+        **kwargs: keyword
+    """
+    result = parse_docstring(doc)
+    assert result.documented_params == ["args", "kwargs"]
+
+
+def test_numpy_style():
+    doc = """Do a thing.
+
+    Parameters
+    ----------
+    name : str
+        the name
+    count : int
+        how many
+
+    Returns
+    -------
+    bool
+        success
+    """
+    result = parse_docstring(doc)
+    assert result.has_params_section is True
+    assert result.documented_params == ["name", "count"]
+
+
+def test_numpy_style_combined_names():
+    doc = """Summary.
+
+    Parameters
+    ----------
+    x, y : int
+        coordinates
+    """
+    result = parse_docstring(doc)
+    assert result.documented_params == ["x", "y"]
+
+
+def test_sphinx_style():
+    doc = """Do a thing.
+
+    :param name: the name
+    :param int count: how many
+    :returns: success
+    """
+    result = parse_docstring(doc)
+    assert result.has_params_section is True
+    assert result.documented_params == ["name", "count"]

docparity-0.1.0/tests/test_scanner.py

@@ -0,0 +1,212 @@
+from docparity.scanner import scan_source
+
+
+def test_no_findings_when_no_docstring():
+    src = '''
+def add(a, b):
+    return a + b
+'''
+    assert scan_source(src) == []
+
+
+def test_no_findings_when_docstring_has_no_params_section():
+    src = '''
+def add(a, b):
+    """Add two numbers."""
+    return a + b
+'''
+    assert scan_source(src) == []
+
+
+def test_stale_param_detected_removed_from_signature():
+    src = '''
+def greet(name):
+    """Greet someone.
+
+    Args:
+        name (str): the name
+        title (str): the honorific
+    """
+    return name
+'''
+    findings = scan_source(src, filename="f.py")
+    assert len(findings) == 1
+    assert findings[0].kind == "stale"
+    assert findings[0].param == "title"
+    assert findings[0].function == "greet"
+
+
+def test_missing_param_detected_added_to_signature():
+    src = '''
+def greet(name, title):
+    """Greet someone.
+
+    Args:
+        name (str): the name
+    """
+    return name
+'''
+    findings = scan_source(src, filename="f.py")
+    assert len(findings) == 1
+    assert findings[0].kind == "missing"
+    assert findings[0].param == "title"
+
+
+def test_renamed_param_produces_both_stale_and_missing():
+    src = '''
+def greet(full_name):
+    """Greet someone.
+
+    Args:
+        name (str): the name
+    """
+    return full_name
+'''
+    findings = scan_source(src, filename="f.py")
+    kinds = sorted((f.kind, f.param) for f in findings)
+    assert kinds == [("missing", "full_name"), ("stale", "name")]
+
+
+def test_matching_params_produce_no_findings():
+    src = '''
+def greet(name, title):
+    """Greet someone.
+
+    Args:
+        name (str): the name
+        title (str): the honorific
+    """
+    return name
+'''
+    assert scan_source(src) == []
+
+
+def test_self_and_cls_never_flagged():
+    src = '''
+class Greeter:
+    def greet(self, name):
+        """Greet someone.
+
+        Args:
+            name (str): the name
+        """
+        return name
+
+    @classmethod
+    def make(cls, name):
+        """Make a greeter.
+
+        Args:
+            name (str): the name
+        """
+        return cls()
+'''
+    assert scan_source(src) == []
+
+
+def test_async_function_supported():
+    src = '''
+async def greet(name):
+    """Greet someone.
+
+    Args:
+        name (str): the name
+        title (str): the honorific
+    """
+    return name
+'''
+    findings = scan_source(src)
+    assert len(findings) == 1
+    assert findings[0].kind == "stale"
+    assert findings[0].param == "title"
+
+
+def test_numpy_style_drift_detected():
+    src = '''
+def scale(x, factor):
+    """Scale a value.
+
+    Parameters
+    ----------
+    x : float
+        value to scale
+    """
+    return x * factor
+'''
+    findings = scan_source(src)
+    assert len(findings) == 1
+    assert findings[0].kind == "missing"
+    assert findings[0].param == "factor"
+
+
+def test_sphinx_style_drift_detected():
+    src = '''
+def scale(x):
+    """Scale a value.
+
+    :param x: value to scale
+    :param factor: unused now
+    """
+    return x
+'''
+    findings = scan_source(src)
+    assert len(findings) == 1
+    assert findings[0].kind == "stale"
+    assert findings[0].param == "factor"
+
+
+def test_varargs_and_kwargs_matched_by_name():
+    src = '''
+def run(*args, **kwargs):
+    """Run something.
+
+    Args:
+        args: positional args
+        kwargs: keyword args
+    """
+    pass
+'''
+    assert scan_source(src) == []
+
+
+def test_findings_sorted_by_line_then_function():
+    src = '''
+def b(x):
+    """B.
+
+    Args:
+        x: val
+        y: stale
+    """
+    return x
+
+
+def a(x):
+    """A.
+
+    Args:
+        x: val
+        z: stale
+    """
+    return x
+'''
+    findings = scan_source(src)
+    assert [f.function for f in findings] == ["b", "a"]
+
+
+def test_finding_str_format():
+    src = '''
+def greet(name):
+    """Greet.
+
+    Args:
+        name: the name
+        title: stale
+    """
+    return name
+'''
+    findings = scan_source(src, filename="pkg/mod.py")
+    s = str(findings[0])
+    assert "pkg/mod.py" in s
+    assert "greet" in s
+    assert "title" in s