Bug: terminal summary counts suppressed findings, disagreeing with JSON summary and exit code

[Alberto-Codes]

Description

The terminal summary line counts suppressed findings toward its total and its per-category breakdown. A file whose findings are entirely suppressed reports a non-zero finding count while printing no findings and exiting 0. The JSON summary reports the same run as total: 0, so the two output formats disagree about the same data.

Steps to Reproduce

1. Create b.py:

# docvet: ignore-file
"""Module."""
from __future__ import annotations


def foo():
    """Do a thing."""
    raise ValueError("x")

2. docvet enrichment b.py
3. docvet --format json enrichment b.py

Expected Behavior

The summary line reflects active findings only, consistent with the exit code and the JSON summary:

Vetted 1 files [enrichment] — no findings.

Actual Behavior

$ docvet enrichment b.py
Vetted 1 files [enrichment] — 4 findings (1 required, 3 recommended). (0.0s)
$ echo $?
0

Nothing is listed under the summary, and the exit code is 0. Meanwhile:

$ docvet --format json enrichment b.py | jq .summary
{"total": 0, "by_category": {"required": 0, "recommended": 0, "scaffold": 0}, "files_checked": 1}

The mismatch also shows up in the partial-suppression case. For a file with one suppressed missing-raises and one active, the summary reports 2 required while only one required finding is active and printed.

Environment

• Python: 3.12
• OS: Linux
• docvet version: 1.15.1 (reproduced on main at 257310e)

Possible Cause

Story 32.4 wired suppression as a post-filter in _output_and_exit(). Task 3.1 filters findings_by_check before flattening "so both output and exit code exclude suppressed findings" — and both do, correctly. The terminal summary line appears to be computed from the pre-filter collection, or from a count captured before the filter runs, while format_json builds its summary from the post-filter list.

Likely a one-line fix in the summary construction in src/docvet/cli/_output.py. Worth a regression test asserting the terminal summary and the JSON summary.total agree for the same input — none of story 32.4's ten ACs covered the summary line, which is how this slipped through.

Found while verifying story 32.4's acceptance criteria (#426).

[Alberto-Codes]

Root cause traced

Confirmed on main. format_summary() is called with the pre-suppression findings list, while _apply_suppressions() runs later inside _output_and_exit():

Location	Call
src/docvet/cli/_output.py:243	findings_by_check, all_suppressed = _apply_suppressions(findings_by_check)
src/docvet/cli/__init__.py	format_summary(...) at lines 531, 619, 691, 765, 828, 904

All six format_summary call sites execute before the filter, so the summary is computed from findings that suppression later removes.

Scope is wider than first reported. This is not limited to docvet check — the six call sites cover check, presence, enrichment, freshness, coverage, and griffe. Every command that prints a summary line is affected.

That also means the fix is not the one-liner I originally guessed. Either the summary must be computed after suppression (moving the format_summary calls behind the filter, or threading the post-filter list back out to them), or _apply_suppressions must move earlier so all six sites see filtered findings. The second is likely cleaner but touches the shared output pipeline — worth a quick design note before implementing.

A regression test should assert the terminal summary and JSON summary.total agree for each of the six commands, not just check.

Found during code review of #426.