Enhancement: audit all enrichment rules against authoritative sources

[Alberto-Codes]

Description

Issue #387 revealed that _is_stub_function() diverged from ruff's is_stub() without documenting the divergence. Party-mode research session (2026-03-23) uncovered several additional gaps in stub/interface detection.

This issue tracks a broader audit: every enrichment rule should be grounded against its authoritative source (PEP, ruff rule, Google style guide) with a documented truth table of expected behavior.

Motivation

docvet positions itself as going beyond ruff's D rules. But undocumented divergence from ruff is perceived as a bug by users who use both tools. We need to explicitly state where we align, where we diverge, and why.

Scope

For each enrichment rule, document:

1. Authority: Which PEP, ruff rule, or style guide defines the expected behavior?
2. Skip conditions: What decorators, body patterns, or class contexts should suppress the rule? Compare against ruff's implementation.
3. Truth table: A matrix of inputs (body patterns, decorators, class types) vs expected output (finding / no finding).
4. Divergences: Any intentional differences from ruff, with rationale.

Specific areas to audit (from party-mode research)

• All forward rules: skip conditions for abstract/stub/overload
• All reverse rules: skip conditions via _should_skip_reverse_check
• @typing.override (PEP 698): Google style says overriding methods with @override don't need docstrings — do we handle this?
• raise NotImplemented (without Error): ruff accepts both; we only accept NotImplementedError
• typing.TYPE_CHECKING block functions: effectively stubs, not currently detected
• Protocol class membership: no tool detects this, but document the decision

Deliverable

A reference document (e.g., docs/rule-authority-matrix.md) mapping every rule to its grounding sources, plus any code fixes for identified gaps.

Related issues

• Bug: extra-returns-in-docstring false positive on Protocol/stub methods with docstring-only bodies #387 — docstring-only body false positive (stub detection gap)
• Bug: _is_stub_function rejects multi-statement stub bodies #388 — multi-statement stub body gap
• Bug: _should_skip_reverse_check misses deprecated abstract decorators #389 — deprecated abstract decorator gap

[Alberto-Codes]

Party-mode review findings (2026-03-24)

Fixes for #387, #388, #389 were implemented and reviewed in a party-mode session. Research confirmed alignment with ruff source code:

• _is_stub_function now uses all(_is_stub_statement(stmt) for stmt in body) — matches ruff's is_stub() in function_type.rs
• _is_abstract checks all 4 abc decorators — matches ruff's is_abstract() in visibility.rs
• Docstring-only bodies recognized as stubs — matches ruff (string literal arm in is_stub)

Confirmed remaining gap for this audit

• raise NotImplemented (without Error): ruff's is_stub() accepts both NotImplementedError and NotImplemented via map_callable resolution. Our _is_stub_statement only accepts NotImplementedError. This is low-risk (ruff flags bare NotImplemented as E711), but should be addressed or documented as intentional divergence.

Sources verified

• Ruff is_stub — function_type.rs
• Ruff is_abstract — visibility.rs
• Pyright isSuiteEmpty — parseTreeUtils.ts