docs: clear pydoclint baseline; run docstring gate via pytest

Finishes the docstring-consistency work: burn the pydoclint baseline down to
zero and move the gate into the pytest suite.

- Document all remaining flagged class attributes (ClassVar constants via
  `Attributes:`, exception/marker instance attrs via bare annotations) and
  add the missing `Args:`/`Returns:`/`Yields:` sections across vgi/.
- Delete `.pydoclint-baseline` and drop the `baseline` setting — vgi/ now
  passes the full gate with no grandfathered exceptions.
- Add tests/test_docstrings.py: runs `pydoclint vgi/` (same [tool.pydoclint]
  config) inside pytest, so `uv run pytest` catches docstring drift like it
  already catches ruff via pytest-ruff.
- Remove the standalone CI "Docstring lint (pydoclint)" step now that the
  pytest test covers it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

.github/workflows/ci.yml

@@ -55,12 +55,8 @@ jobs:
       - name: Check linting
         run: uv run ruff check .
 
-      # Docstring consistency: documented args/attributes must match the code.
-      # Config + frozen baseline live in pyproject.toml ([tool.pydoclint]); only
-      # NEW violations fail. Regenerate the baseline with:
-      #   uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi/
-      - name: Docstring lint (pydoclint)
-        run: uv run pydoclint vgi/
+      # Docstring consistency (pydoclint) runs inside the pytest suite via
+      # tests/test_docstrings.py, so it's not a separate CI lint step.
 
       - name: Type check (mypy)
         run: uv run mypy vgi/

.pydoclint-baseline

@@ -145,12 +145,10 @@ skip_checking_raises = true
 # DOC301). pydoclint 0.8.x has no per-code ignore, so the noisy families are
 # turned off via these family switches instead.
 allow_init_docstring = true
-# Everything else still flagged (ClassVar constants like ARROW_SCHEMA /
-# FIXED_SCHEMA, undocumented args on private helpers + exception __init__s, and
-# the handful of DOC201 missing-Returns on multi-line docstrings) is frozen in
-# the baseline; only NEW violations fail. Regenerate after intentional changes:
+# No baseline: vgi/ is fully clean under this config, so the gate enforces
+# every in-scope violation with no grandfathered exceptions. If a future change
+# needs to defer cleanup, freeze the current state and re-add `baseline`:
 #   uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi/
-baseline = ".pydoclint-baseline"
 
 [tool.mypy]
 python_version = "3.13"

pyproject.toml

@@ -0,0 +1,41 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Docstring-consistency gate.
+
+Runs pydoclint over the ``vgi/`` package as part of the test suite, mirroring
+the CI ``Docstring lint (pydoclint)`` step. pydoclint complements ruff's ``D``
+rules: ruff checks docstring *shape*, while pydoclint verifies that documented
+arguments, return values, yields, and dataclass attributes actually match the
+code. Configuration lives in ``[tool.pydoclint]`` in ``pyproject.toml`` — this
+test invokes the same CLI, so there is no duplicated rule set.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_pydoclint_clean() -> None:
+    """``vgi/`` must pass the pydoclint docstring gate (config in pyproject.toml)."""
+    pydoclint = shutil.which("pydoclint")
+    if pydoclint is None:  # pragma: no cover - dev dependency should always be present
+        pytest.skip("pydoclint is not installed")
+
+    result = subprocess.run(
+        [pydoclint, "vgi/"],
+        cwd=_REPO_ROOT,
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0, (
+        "pydoclint found docstring violations:\n\n"
+        f"{result.stdout}{result.stderr}\n"
+        "Fix the docstrings, or run "
+        "`uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi/` "
+        "to defer them (see [tool.pydoclint] in pyproject.toml)."
+    )

tests/test_docstrings.py

@@ -32,6 +32,9 @@ def engine_module() -> ModuleType:
 
     The result is cached for the life of the process.
 
+    Returns:
+        The resolved engine module (``haybarn`` if available, else ``duckdb``).
+
     Raises:
         ImportError: if neither engine is installed.
 

vgi/_duckdb.py

@@ -190,19 +190,25 @@ def combine(cls, source: DynamicState, target: DynamicState, params: ProcessPara
     # when DuckDB batches many partitions into shared buffers.
 
     @staticmethod
-    def _slice_to_frame(  # noqa: D417
+    def _slice_to_frame(
         partition: WindowPartition,
         subframes: list[tuple[int, int]],
         data_start: int,
     ) -> pa.Table:
         """Slice all partition columns to the frame rows.
 
         Args:
+            partition: The window partition whose columns are sliced.
+            subframes: List of ``(begin, end)`` index tuples describing the
+                row ranges to include in the frame.
             data_start: Index where data columns begin (header columns are
                 ``[0 .. data_start)``). NULL-drop is applied on data columns
                 only — matches the filtering ``_do_update`` performs in the
                 non-window path.
 
+        Returns:
+            A table containing only the frame rows across all partition columns.
+
         """
         num_cols = partition.inputs.num_columns
         cols = [partition.inputs.column(i) for i in range(num_cols)]

vgi/_test_fixtures/aggregate/dynamic.py

@@ -116,6 +116,9 @@ class FilterEchoFunction(TableFunctionGenerator[FilterEchoFunctionArgs, FilterEc
     SELECT * FROM filter_echo(10) WHERE n >= 8
     Returns: rows 8-9 with pushed_filters showing "n >= 8"
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     class Meta:
@@ -473,6 +476,9 @@ class DictFilterEchoFunction(TableFunctionGenerator[_DictFilterEchoArgs, _DictFi
     SELECT * FROM dict_filter_echo(6) WHERE s = 'green'
     Returns: rows 1 and 4.
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     class Meta:
@@ -602,6 +608,9 @@ class SpatialFilterExampleFunction(TableFunctionGenerator[_SpatialFilterArgs, _S
     SELECT * FROM spatial_filter_example(100) WHERE geom && ST_MakeEnvelope(0, 0, 0.5, 0.5)
     Returns: points in the lower-left quadrant of the unit square.
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     class Meta:

vgi/_test_fixtures/table/filters.py

@@ -148,6 +148,9 @@ class LateMaterializationFunction(TableFunctionGenerator[LateMaterializationFunc
     -------
     SELECT row_id, payload FROM late_materialization(100000) ORDER BY ord LIMIT 10
 
+    Attributes:
+        FunctionArguments: The argument dataclass type bound to this function.
+
     """
 
     FunctionArguments = LateMaterializationFunctionArgs

vgi/_test_fixtures/table/late_materialization.py

@@ -77,6 +77,9 @@ class MakeSeriesCountFunction(TableFunctionGenerator[MakeSeriesCountArgs, MakeSe
         SELECT * FROM make_series(5)
         Returns: 0, 1, 2, 3, 4
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     FIXED_SCHEMA: ClassVar[pa.Schema] = MAKE_SERIES_SCHEMA
@@ -113,6 +116,9 @@ class MakeSeriesRangeFunction(TableFunctionGenerator[MakeSeriesRangeArgs, MakeSe
         SELECT * FROM make_series(3, 7)
         Returns: 3, 4, 5, 6
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     FIXED_SCHEMA: ClassVar[pa.Schema] = MAKE_SERIES_SCHEMA
@@ -149,6 +155,9 @@ class MakeSeriesStepFunction(TableFunctionGenerator[MakeSeriesStepArgs, MakeSeri
         SELECT * FROM make_series(0, 10, 3)
         Returns: 0, 3, 6, 9
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     FIXED_SCHEMA: ClassVar[pa.Schema] = MAKE_SERIES_SCHEMA
@@ -195,6 +204,9 @@ class MakeSeriesCsvFunction(TableFunctionGenerator[MakeSeriesCsvArgs, MakeSeries
         SELECT * FROM make_series('10,20,30')
         Returns: 10, 20, 30
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     FIXED_SCHEMA: ClassVar[pa.Schema] = MAKE_SERIES_SCHEMA
@@ -243,6 +255,9 @@ class MakeSeriesFloatFunction(TableFunctionGenerator[MakeSeriesFloatArgs, MakeSe
         SELECT * FROM make_series(0.5)
         Returns: 0.0, 0.5, 1.0, ..., 4.5
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+
     """
 
     FIXED_SCHEMA: ClassVar[pa.Schema] = MAKE_SERIES_FLOAT_SCHEMA

vgi/_test_fixtures/table/make_series.py

@@ -178,6 +178,10 @@ class ProjectedDataFunction(TableFunctionGenerator[ProjectedDataFunctionArgument
     SELECT id, value FROM projected_data(10)  -- Only computes id and value
     Returns: 10 rows with id and value columns only
 
+    Attributes:
+        FIXED_SCHEMA: The fixed Arrow output schema this function always produces.
+        BATCH_SIZE: Number of rows emitted per output batch.
+
     """
 
     class Meta: