Type probe pipeline internals: ProbeTarget, frozen ProbeHit, typed diff, validated PollResult

[henry0816191]

Summary

Replace untyped/mutable probe pipeline internals with named, validated types so callers cannot couple to bare tuples or silently mutate probe results.

• Add frozen ProbeTarget dataclass and remove the bare _Entry 6-tuple; update _build_probe_list, _build_hot_list, _build_cold_slice, and run_cycle to use named fields
• Type DataSource.diff as SourceDiff (DiffResult | list[ProbeHit] | list[OpenStdEntry]) and annotate WG21Index.diff → DiffResult (with TYPE_CHECKING import to preserve the sources ↔ monitor cycle break)
• Freeze ProbeHit (@dataclass(frozen=True, slots=True))
• Convert PollResult to a validated dataclass with __post_init__ checks for diff, probe_hits, dp_transitions, and per_user_matches

Test plan

• uv run pytest -q — 418 passed, 2 skipped
• uv run pytest tests/ --cov=paperscout --cov-fail-under=90 — 93.55% coverage
• uv run mypy src/paperscout/protocols.py src/paperscout/monitor.py src/paperscout/__main__.py — strict gate clean
• uv run ruff check src tests — clean
• uv run ruff format --check src tests — clean
• pre-commit run --all-files

Related issues

• Close Replace untyped probe pipeline internals: #86

Summary by CodeRabbit

• Bug Fixes
  • Improved monitoring stability by validating polling results at construction time and normalizing values for consistent downstream handling.
  • Tightened diff/probe typing to reduce malformed data causing runtime issues.
  • Updated probe scheduling output so scheduled probe targets are represented consistently, simplifying consumption during probe discovery and execution.
• Tests
  • Added unit tests covering polling result type validation error cases.
  • Updated source/prober tests to match the revised probe target output shape.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f01354ab-2e3f-4f19-97d4-bb7992040b20

📥 Commits

Reviewing files that changed from the base of the PR and between ca131f3 and 9f5a9e8.

📒 Files selected for processing (1)

• tests/test_monitor.py

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_monitor.py

---

📝 Walkthrough

Walkthrough

This PR replaces tuple-based probe entries with a typed ProbeTarget, tightens DataSource.diff and WG21Index.diff return types, and converts PollResult into a validated dataclass. Tests were updated to match the new object attributes and runtime type checks.

Changes

Typed probe pipeline refactor

Layer / File(s)	Summary
ProbeTarget definition src/paperscout/models.py	Adds a frozen, slotted ProbeTarget dataclass with url, tier, prefix, number, revision, and extension.
Probe scheduling uses ProbeTarget src/paperscout/sources.py	Removes the tuple-based probe entry shape and updates probe-list building, counting, and task dispatch to use ProbeTarget attributes.
Protocol and source diff typing src/paperscout/protocols.py, src/paperscout/sources.py	Adds SourceDiff, narrows DataSource.diff, and annotates WG21Index.diff as DiffResult.
PollResult validation and tests src/paperscout/monitor.py, tests/test_monitor.py	Converts PollResult to a slotted dataclass with default factories and runtime validation, and adds invalid-input tests.
ProbeTarget attribute test updates tests/test_sources.py	Updates probe-list assertions to use named attributes instead of tuple indexes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• cppalliance/paperscout#5: Shares the same sources.py probe/tiering flow that this PR refactors around ProbeTarget.
• cppalliance/paperscout#27: Also changes ISOProber probe-list construction and _probe_one wiring in sources.py.
• cppalliance/paperscout#50: Also modifies ISOProber.run_cycle() behavior in the same probing pipeline.

Suggested reviewers: wpak-ai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the probe-pipeline type-safety refactor and names the key changes.
Description check	✅ Passed	The description follows the template with Summary, Test plan, and Related issues sections filled in.
Linked Issues check	✅ Passed	The changes satisfy the linked issue by adding ProbeTarget, freezing ProbeHit, typing diffs, and validating PollResult.
Out of Scope Changes check	✅ Passed	No unrelated or out-of-scope changes are evident beyond tests and typing updates for the refactor.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/replace-untyped-internals

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/test_monitor.py`:
- Around line 205-228: The pytest assertions in test_rejects_invalid_diff_type,
test_rejects_invalid_probe_hit_element,
test_rejects_invalid_dp_transition_element, and
test_rejects_invalid_per_user_matches_value use raw regex patterns where the dot
in PollResult.* is being treated as a metacharacter. Update each match= string
to escape literal punctuation, or build the pattern with re.escape, so the
exception checks in PollResult and its related constructors are explicit and
unambiguous.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 211de7e1-331e-4459-aabb-3a526b509e6c

📥 Commits

Reviewing files that changed from the base of the PR and between 4970494 and ca131f3.

📒 Files selected for processing (6)

• src/paperscout/models.py
• src/paperscout/monitor.py
• src/paperscout/protocols.py
• src/paperscout/sources.py
• tests/test_monitor.py
• tests/test_sources.py