docvet 1.0.0__tar.gz

docvet-1.0.0/LICENSE

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

docvet-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: docvet
+Version: 1.0.0
+Summary: Comprehensive docstring quality vetting for Python projects
+Keywords: docstring,linter,mkdocs,interrogate,pydocstyle,darglint,documentation,quality
+Author: Alberto-Codes
+Author-email: Alberto-Codes <alberto.codes.dev@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Alberto-Codes
+         
+         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.
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: typer>=0.9
+Requires-Dist: griffe>=1.0 ; extra == 'griffe'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Alberto-Codes/docvet
+Project-URL: Source, https://github.com/Alberto-Codes/docvet
+Project-URL: Issues, https://github.com/Alberto-Codes/docvet/issues
+Provides-Extra: griffe
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/docvet)](https://pypi.org/project/docvet/)
+[![CI](https://img.shields.io/github/actions/workflow/status/Alberto-Codes/docvet/ci.yml?branch=develop)](https://github.com/Alberto-Codes/docvet/actions)
+[![License](https://img.shields.io/pypi/l/docvet)](https://github.com/Alberto-Codes/docvet/blob/develop/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/docvet)](https://pypi.org/project/docvet/)
+[![docs vetted](https://img.shields.io/badge/docs%20vetted-docvet-blue)](https://github.com/Alberto-Codes/docvet)
+
+# docvet
+
+**ruff checks how your docstrings look. interrogate checks if they exist. docvet checks if they're right.**
+
+Existing tools cover presence and style. docvet delivers the layers they miss:
+
+| Layer | Check | ruff | interrogate | pydoclint | **docvet** |
+|-------|-------|------|-------------|-----------|------------|
+| 1. Presence | "Does a docstring exist?" | -- | Yes | -- | -- |
+| 2. Style | "Is it formatted correctly?" | Yes | -- | -- | -- |
+| 3. Completeness | "Does it have all required sections?" | -- | -- | Partial | **Yes** |
+| 4. Accuracy | "Does it match the current code?" | -- | -- | -- | **Yes** |
+| 5. Rendering | "Will mkdocs render it correctly?" | -- | -- | -- | **Yes** |
+| 6. Visibility | "Will mkdocs even see the file?" | -- | -- | -- | **Yes** |
+
+**pydoclint** checks Args/Returns/Raises alignment with function signatures (structural completeness). docvet's enrichment covers that plus Yields, Receives, Warns, Attributes, Examples, typed attributes, and cross-references -- 19 rules across 4 checks. docvet also covers freshness (git diff/blame), griffe rendering compatibility, and mkdocs coverage -- territory no other tool touches.
+
+## What It Checks
+
+**Enrichment** (completeness) -- 10 rules:
+`missing-raises` `missing-yields` `missing-receives` `missing-warns` `missing-other-parameters` `missing-attributes` `missing-typed-attributes` `missing-examples` `missing-cross-references` `prefer-fenced-code-blocks`
+
+**Freshness** (accuracy) -- 5 rules:
+`stale-signature` `stale-body` `stale-import` `stale-drift` `stale-age`
+
+**Griffe** (rendering) -- 3 rules:
+`griffe-unknown-param` `griffe-missing-type` `griffe-format-warning`
+
+**Coverage** (visibility) -- 1 rule:
+`missing-init`
+
+## Quickstart
+
+```bash
+pip install docvet && docvet check --all
+```
+
+For optional griffe rendering checks:
+
+```bash
+pip install docvet[griffe]
+```
+
+Example output:
+
+```
+src/mypackage/utils.py:42: missing-raises Function 'parse_config' raises ValueError but has no Raises section
+src/mypackage/models.py:15: stale-signature Function 'process' signature changed but docstring not updated
+src/mypackage/api.py:1: missing-init Package directory missing __init__.py (invisible to mkdocs)
+```
+
+## Configuration
+
+Configure via `[tool.docvet]` in your `pyproject.toml`. All checks run and print findings. Checks listed in `fail-on` cause a non-zero exit code; unlisted checks are treated as warnings.
+
+```toml
+[tool.docvet]
+exclude = ["tests", "scripts"]
+fail-on = ["griffe", "coverage"]
+
+[tool.docvet.freshness]
+drift-threshold = 30
+age-threshold = 90
+```
+
+## Pre-commit
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/Alberto-Codes/docvet
+    rev: v1.0.0
+    hooks:
+      - id: docvet
+```
+
+For griffe rendering checks, add the optional dependency:
+
+```yaml
+repos:
+  - repo: https://github.com/Alberto-Codes/docvet
+    rev: v1.0.0
+    hooks:
+      - id: docvet
+        additional_dependencies: [griffe]
+```
+
+## GitHub Action
+
+Add docvet to your GitHub Actions workflow:
+
+```yaml
+- uses: Alberto-Codes/docvet@v1
+```
+
+With version pinning and custom arguments:
+
+```yaml
+- uses: Alberto-Codes/docvet@v1
+  with:
+    version: '1.0.0'
+    args: 'check --all'
+```
+
+For griffe rendering checks, install griffe before running docvet:
+
+```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.12'
+- run: pip install griffe
+- uses: Alberto-Codes/docvet@v1
+  with:
+    args: 'check --all'
+```
+
+## Better Docstrings, Better AI
+
+AI coding agents rely on docstrings as context when generating and modifying code. Research shows stale or incorrect documentation is actively harmful -- worse than no docs at all:
+
+- Incorrect docs [degrade LLM task success by 22.6 percentage points](https://arxiv.org/abs/2404.03114)
+- Comment density [improves code generation by 40-54%](https://arxiv.org/abs/2402.13013)
+- Misleading comments [reduce LLM fault localization accuracy to 24.55%](https://arxiv.org/abs/2504.04372)
+- Performance [drops substantially without docstrings](https://arxiv.org/abs/2508.09537)
+
+As the [2025 DORA report](https://cloud.google.com/resources/content/2025-dora-ai-assisted-software-development-report) puts it: "AI doesn't fix a team; it amplifies what's already there." The [only signal correlating with AI productivity is code quality](https://stackoverflow.blog/2026/02/04/code-smells-for-ai-agents-q-and-a-with-eno-reyes-of-factory).
+
+docvet's freshness checking catches the accuracy gap that stale docs create, and its enrichment rules ensure the docstring sections that agents use as context are complete. Run `docvet check` in your CI, pre-commit hooks, or agent toolchain.
+
+## Badge
+
+Add a badge to your project to show your docs are vetted:
+
+```markdown
+[![docs vetted | docvet](https://img.shields.io/badge/docs%20vetted-docvet-blue)](https://github.com/Alberto-Codes/docvet)
+```
+
+## Used By
+
+Are you using docvet? Open a pull request to add your project here.
+
+## License
+
+MIT -- see [LICENSE](https://github.com/Alberto-Codes/docvet/blob/develop/LICENSE) for details.

docvet-1.0.0/README.md

@@ -0,0 +1,151 @@
+[![PyPI](https://img.shields.io/pypi/v/docvet)](https://pypi.org/project/docvet/)
+[![CI](https://img.shields.io/github/actions/workflow/status/Alberto-Codes/docvet/ci.yml?branch=develop)](https://github.com/Alberto-Codes/docvet/actions)
+[![License](https://img.shields.io/pypi/l/docvet)](https://github.com/Alberto-Codes/docvet/blob/develop/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/docvet)](https://pypi.org/project/docvet/)
+[![docs vetted](https://img.shields.io/badge/docs%20vetted-docvet-blue)](https://github.com/Alberto-Codes/docvet)
+
+# docvet
+
+**ruff checks how your docstrings look. interrogate checks if they exist. docvet checks if they're right.**
+
+Existing tools cover presence and style. docvet delivers the layers they miss:
+
+| Layer | Check | ruff | interrogate | pydoclint | **docvet** |
+|-------|-------|------|-------------|-----------|------------|
+| 1. Presence | "Does a docstring exist?" | -- | Yes | -- | -- |
+| 2. Style | "Is it formatted correctly?" | Yes | -- | -- | -- |
+| 3. Completeness | "Does it have all required sections?" | -- | -- | Partial | **Yes** |
+| 4. Accuracy | "Does it match the current code?" | -- | -- | -- | **Yes** |
+| 5. Rendering | "Will mkdocs render it correctly?" | -- | -- | -- | **Yes** |
+| 6. Visibility | "Will mkdocs even see the file?" | -- | -- | -- | **Yes** |
+
+**pydoclint** checks Args/Returns/Raises alignment with function signatures (structural completeness). docvet's enrichment covers that plus Yields, Receives, Warns, Attributes, Examples, typed attributes, and cross-references -- 19 rules across 4 checks. docvet also covers freshness (git diff/blame), griffe rendering compatibility, and mkdocs coverage -- territory no other tool touches.
+
+## What It Checks
+
+**Enrichment** (completeness) -- 10 rules:
+`missing-raises` `missing-yields` `missing-receives` `missing-warns` `missing-other-parameters` `missing-attributes` `missing-typed-attributes` `missing-examples` `missing-cross-references` `prefer-fenced-code-blocks`
+
+**Freshness** (accuracy) -- 5 rules:
+`stale-signature` `stale-body` `stale-import` `stale-drift` `stale-age`
+
+**Griffe** (rendering) -- 3 rules:
+`griffe-unknown-param` `griffe-missing-type` `griffe-format-warning`
+
+**Coverage** (visibility) -- 1 rule:
+`missing-init`
+
+## Quickstart
+
+```bash
+pip install docvet && docvet check --all
+```
+
+For optional griffe rendering checks:
+
+```bash
+pip install docvet[griffe]
+```
+
+Example output:
+
+```
+src/mypackage/utils.py:42: missing-raises Function 'parse_config' raises ValueError but has no Raises section
+src/mypackage/models.py:15: stale-signature Function 'process' signature changed but docstring not updated
+src/mypackage/api.py:1: missing-init Package directory missing __init__.py (invisible to mkdocs)
+```
+
+## Configuration
+
+Configure via `[tool.docvet]` in your `pyproject.toml`. All checks run and print findings. Checks listed in `fail-on` cause a non-zero exit code; unlisted checks are treated as warnings.
+
+```toml
+[tool.docvet]
+exclude = ["tests", "scripts"]
+fail-on = ["griffe", "coverage"]
+
+[tool.docvet.freshness]
+drift-threshold = 30
+age-threshold = 90
+```
+
+## Pre-commit
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/Alberto-Codes/docvet
+    rev: v1.0.0
+    hooks:
+      - id: docvet
+```
+
+For griffe rendering checks, add the optional dependency:
+
+```yaml
+repos:
+  - repo: https://github.com/Alberto-Codes/docvet
+    rev: v1.0.0
+    hooks:
+      - id: docvet
+        additional_dependencies: [griffe]
+```
+
+## GitHub Action
+
+Add docvet to your GitHub Actions workflow:
+
+```yaml
+- uses: Alberto-Codes/docvet@v1
+```
+
+With version pinning and custom arguments:
+
+```yaml
+- uses: Alberto-Codes/docvet@v1
+  with:
+    version: '1.0.0'
+    args: 'check --all'
+```
+
+For griffe rendering checks, install griffe before running docvet:
+
+```yaml
+- uses: actions/setup-python@v5
+  with:
+    python-version: '3.12'
+- run: pip install griffe
+- uses: Alberto-Codes/docvet@v1
+  with:
+    args: 'check --all'
+```
+
+## Better Docstrings, Better AI
+
+AI coding agents rely on docstrings as context when generating and modifying code. Research shows stale or incorrect documentation is actively harmful -- worse than no docs at all:
+
+- Incorrect docs [degrade LLM task success by 22.6 percentage points](https://arxiv.org/abs/2404.03114)
+- Comment density [improves code generation by 40-54%](https://arxiv.org/abs/2402.13013)
+- Misleading comments [reduce LLM fault localization accuracy to 24.55%](https://arxiv.org/abs/2504.04372)
+- Performance [drops substantially without docstrings](https://arxiv.org/abs/2508.09537)
+
+As the [2025 DORA report](https://cloud.google.com/resources/content/2025-dora-ai-assisted-software-development-report) puts it: "AI doesn't fix a team; it amplifies what's already there." The [only signal correlating with AI productivity is code quality](https://stackoverflow.blog/2026/02/04/code-smells-for-ai-agents-q-and-a-with-eno-reyes-of-factory).
+
+docvet's freshness checking catches the accuracy gap that stale docs create, and its enrichment rules ensure the docstring sections that agents use as context are complete. Run `docvet check` in your CI, pre-commit hooks, or agent toolchain.
+
+## Badge
+
+Add a badge to your project to show your docs are vetted:
+
+```markdown
+[![docs vetted | docvet](https://img.shields.io/badge/docs%20vetted-docvet-blue)](https://github.com/Alberto-Codes/docvet)
+```
+
+## Used By
+
+Are you using docvet? Open a pull request to add your project here.
+
+## License
+
+MIT -- see [LICENSE](https://github.com/Alberto-Codes/docvet/blob/develop/LICENSE) for details.

docvet-1.0.0/pyproject.toml

@@ -0,0 +1,137 @@
+[project]
+name = "docvet"
+version = "1.0.0"
+description = "Comprehensive docstring quality vetting for Python projects"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    { name = "Alberto-Codes", email = "alberto.codes.dev@gmail.com" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+keywords = [
+    "docstring",
+    "linter",
+    "mkdocs",
+    "interrogate",
+    "pydocstyle",
+    "darglint",
+    "documentation",
+    "quality",
+]
+dependencies = [
+    "typer>=0.9",
+]
+
+[project.optional-dependencies]
+griffe = [
+    "griffe>=1.0",
+]
+
+[project.scripts]
+docvet = "docvet.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/Alberto-Codes/docvet"
+Source = "https://github.com/Alberto-Codes/docvet"
+Issues = "https://github.com/Alberto-Codes/docvet/issues"
+
+[build-system]
+requires = ["uv_build>=0.7,<1"]
+build-backend = "uv_build"
+
+# --------------------------------------------------------------------------- #
+# uv — TestPyPI publishing index
+# --------------------------------------------------------------------------- #
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+# --------------------------------------------------------------------------- #
+# Ruff
+# --------------------------------------------------------------------------- #
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+exclude = [".venv", "__pycache__", "*.egg-info"]
+
+[tool.ruff.lint]
+extend-select = ["E501", "I", "D"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 100
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "D100", "D101", "D102", "D103", "D104"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["docvet"]
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+# --------------------------------------------------------------------------- #
+# Interrogate
+# --------------------------------------------------------------------------- #
+[tool.interrogate]
+verbose = 1
+fail-under = 95
+ignore-init-method = true
+ignore-init-module = false
+ignore-magic = true
+ignore-private = true
+exclude = ["tests", "scripts"]
+
+# --------------------------------------------------------------------------- #
+# Ty (type checker)
+# --------------------------------------------------------------------------- #
+[tool.ty.src]
+include = ["src", "tests"]
+
+# --------------------------------------------------------------------------- #
+# Pytest
+# --------------------------------------------------------------------------- #
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "unit: Unit tests (fast, isolated)",
+    "integration: Integration tests (temp git repos, slower)",
+    "slow: Slow-running tests",
+]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+]
+
+# --------------------------------------------------------------------------- #
+# Dev dependencies
+# --------------------------------------------------------------------------- #
+[dependency-groups]
+dev = [
+    "interrogate>=1.5",
+    "pytest>=9.0",
+    "pytest-cov>=7.0",
+    "pytest-mock>=3.15",
+    "pytest-randomly>=4.0",
+    "readme-renderer[md]>=44.0",
+    "ruff>=0.11",
+    "ty>=0.0.1a33",
+]

docvet-1.0.0/src/docvet/__init__.py

@@ -0,0 +1,28 @@
+"""Docstring quality vetting for Python projects.
+
+Provides a six-layer docstring quality model, implementing layers 3-6
+(completeness, accuracy, rendering, and visibility). Use the ``docvet``
+CLI command or import check functions programmatically.
+
+Attributes:
+    Finding: Re-exported from ``docvet.checks`` for convenience.
+
+Examples:
+    Run all checks on changed files::
+
+        $ docvet check
+
+    Run all checks on the entire codebase::
+
+        $ docvet check --all
+
+See Also:
+    `docvet.checks`: Check modules and the Finding dataclass.
+    `docvet.cli`: CLI entry point and subcommands.
+"""
+
+from __future__ import annotations
+
+from docvet.checks import Finding
+
+__all__ = ["Finding"]