Fix PerUserMatches circular import

[henry0816191]

Summary

Code

• src/paperscout/models.py - Added Tier, ProbeHit, and PerUserMatches (with datetime import for ProbeHit.last_modified).
• src/paperscout/sources.py - Removed duplicate Tier / ProbeHit; import Paper, ProbeHit, Tier from .models; dropped unused Enum and field imports.
• src/paperscout/monitor.py - Removed PerUserMatches; import Paper, PerUserMatches, ProbeHit from .models; removed unused field import.
• src/paperscout/storage.py - from .models import PerUserMatches at module load; removed TYPE_CHECKING import from monitor and the inner matches_for_users import.
• src/paperscout/scout.py - Tier from .models with Paper.

Tests & docs

• tests/test_monitor.py, tests/test_scout.py, tests/test_scout_extra.py, tests/test_storage.py – Imports updated to paperscout.models where needed.
• README.md - Architecture lines updated for models.py / monitor.py.

Verification

• PYTHONPATH=src python -c "import paperscout.models; import paperscout.storage; import paperscout.scout" succeeds (using project .venv).
• pytest -q – all tests passed (background job exit code 0).
• ruff check on touched paths – clean after removing the unused field import in sources.py.

Test plan

• ./run check (or make check)
• pre-commit run --all-files

Related issues

close #24

Summary by CodeRabbit

• Refactor
  • Consolidated and reorganized internal data type definitions across modules to improve code structure and maintainability. No impact to user-facing functionality.

[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: 09500a4c-46a9-43ee-855b-b8697456aec6

📥 Commits

Reviewing files that changed from the base of the PR and between 2153f63 and 1dd0cf6.

📒 Files selected for processing (10)

• README.md
• src/paperscout/models.py
• src/paperscout/monitor.py
• src/paperscout/scout.py
• src/paperscout/sources.py
• src/paperscout/storage.py
• tests/test_monitor.py
• tests/test_scout.py
• tests/test_scout_extra.py
• tests/test_storage.py

---

📝 Walkthrough

Walkthrough

This PR consolidates three shared domain types (Tier, ProbeHit, PerUserMatches) into models.py to eliminate circular import dependencies, then updates all import statements across the codebase and tests to reference the new central location.

Changes

Domain Type Consolidation

Layer / File(s)	Summary
Define domain types in models.py src/paperscout/models.py	Add datetime import and define three new dataclasses: Tier (enum for probe priority), ProbeHit (HEAD match metadata with optional last_modified and is_recent flag), and PerUserMatches (per-user aggregation of papers and probe hits).
Update sources.py and monitor.py imports src/paperscout/sources.py, src/paperscout/monitor.py	Remove local definitions of Tier and ProbeHit from sources.py; remove PerUserMatches from monitor.py. Both modules now import these types from models.py instead.
Update scout.py and storage.py imports src/paperscout/scout.py, src/paperscout/storage.py	Scout.py moves Tier import from sources to models; storage.py pulls PerUserMatches to module scope from models, eliminating in-function import.
Align test imports tests/test_monitor.py, tests/test_scout.py, tests/test_scout_extra.py, tests/test_storage.py	Update test imports so PerUserMatches, ProbeHit, and Tier are sourced from paperscout.models rather than their previous module-specific locations.
Update Architecture documentation README.md	Update module responsibility listing to show models.py now contains Tier, ProbeHit, and PerUserMatches; remove PerUserMatches from monitor.py's documented scope.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• cppalliance/paperscout#5: Introduces and modifies Tier and ProbeHit types; this PR consolidates those types into models.py and coordinates imports across the codebase.

Suggested reviewers

• wpak-ai

Poem

🐰 Types were scattered, imports were tangled,
A circular dance that left us mangled.
Now models stands central, a beacon so bright,
Tier, ProbeHit, PerUserMatches—all in one place, all right!
The DAG flows clean, no cycles remain,
A victory for refactoring... hip-hip-hooray! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fix PerUserMatches circular import' clearly and specifically summarizes the main change: moving PerUserMatches to models.py to resolve circular import issues.
Description check	✅ Passed	The description is comprehensive and follows the template structure with Summary, Test plan, and Related issues sections, detailing all code changes and verification steps performed.
Linked Issues check	✅ Passed	The PR successfully meets all acceptance criteria from issue #24: PerUserMatches moved to models.py, all imports updated, circular import fixed, module DAG remains acyclic, and all tests pass.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to resolving the circular import issue: moving domain types to models.py, updating imports across modules, and adjusting tests and documentation accordingly.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 bugfix/PerUserMatches-Circular-Import

---

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