fix(crossseed): prevent season packs matching episodes

[s0up4200]

Summary

• Prevents season pack cross-seeds from matching against single-episode torrents when FindIndividualEpisodes is enabled, avoiding incorrect matches and episode-style renames on pack torrents.
• Centralizes TV episode/season-pack detection and the forbidden-pair predicate to keep behavior consistent across apply, search, webhook checks, and alignment.
• Adds coverage for the forbidden pairing and uses a shared reject-reason constant.

Summary by CodeRabbit

• Bug Fixes

  • Prevented season-pack torrents from being paired with single-episode torrents across search, alignment, renaming, and webhook flows; added TV-aware guards, early rejection and explicit reject reasons so season-vs-episode matches are skipped and logged.

• Tests

  • Added unit tests validating episode vs. season-pack detection, forbidden pairing rejection, candidate-selection behavior, and propagation of reject reasons.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds TV-aware guards and rejection propagation to prevent season-pack releases from being cross-seeded against single-episode torrents; introduces TV classification helpers and updates matching, alignment, search, and webhook paths plus tests.

Changes

Cohort / File(s)	Summary
TV Matching Helpers internal/services/crossseed/matching.go	Adds isTVEpisode(), isTVSeasonPack(), rejectSeasonPackFromEpisode() and rejectReasonSeasonPackFromEpisode to detect and reject season-pack vs single-episode pairings.
Service Layer Rejections internal/services/crossseed/service.go	Enforces season-pack/episode rejection in findCandidates, findBestCandidateMatch, SearchTorrentMatches, and CheckWebhook; propagates bestRejectReason and adjusts TV size-ignore logic.
Alignment Logic Updates internal/services/crossseed/align.go	Adds early rejection in alignCrossSeedContentPaths; replaces previous field checks in shouldRenameTorrentDisplay and shouldAlignFilesWithCandidate with TV-specific guards and an explicit reject check.
Tests: New & Updated internal/services/crossseed/align_test.go, internal/services/crossseed/matching_forbidden_pairs_test.go, internal/services/crossseed/matching_layout_test.go	Updates expectations for season-pack vs episode case; adds unit tests for TV helpers and a layout test asserting season-pack rejection against episode candidates.
Comments / Docs internal/services/crossseed/models.go	Expanded/clarifying comments for FindIndividualEpisodes; no structural or API changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix(crossseed): improve matching with size validation and relaxed audio checks #845: Overlaps crossseed matching/align changes adding guards against season-pack vs single-episode pairings.
• fix(crossseed): use matched torrent save path instead of category path #700: Related adjustments to findBestCandidateMatch and reject-reason propagation in crossseed flows.
• fix(cross): performance improvements #629: Modifies align.go alignment decision logic (shouldRenameTorrentDisplay, shouldAlignFilesWithCandidate) that overlaps with these changes.

Suggested labels

tests

Suggested reviewers

• Audionut

Poem

🐰 I hop through releases, sniffing each plea,
Season packs and episodes — "No mix!" says me.
Helpers in place, I guard every trail,
Rejecting the mismatched with a twitch of my tail,
Safe torrents hop home, joyful and free. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: preventing season packs from matching episodes in the crossseed service.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/crossseed-block-pack-from-episode

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 788ae2f and 6d05d1a.

📒 Files selected for processing (1)

• internal/services/crossseed/matching.go

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: s0up4200
Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go:209-212
Timestamp: 2025-11-28T20:32:30.126Z
Learning: Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go
Learning: The cross-seed recheck-resume worker intentionally runs for the process lifetime and keys pending entries by hash only. This is acceptable under the current constraint that background seeded-search runs operate on a single instance at a time; graceful shutdown and instanceID|hash keying are deferred by design.

📚 Learning: 2025-11-28T20:32:30.126Z

Learnt from: s0up4200
Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go:209-212
Timestamp: 2025-11-28T20:32:30.126Z
Learning: Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go
Learning: The cross-seed recheck-resume worker intentionally runs for the process lifetime and keys pending entries by hash only. This is acceptable under the current constraint that background seeded-search runs operate on a single instance at a time; graceful shutdown and instanceID|hash keying are deferred by design.

Applied to files:

• internal/services/crossseed/matching.go

🔇 Additional comments (4)

internal/services/crossseed/matching.go (4)

23-26: LGTM - Clean TV episode detection helper.

The nil-safe check correctly identifies TV episodes by verifying both series and episode numbers are present.

---

28-31: LGTM - Clean season pack detection helper.

The nil-safe check correctly distinguishes season packs (series present, no episode number) from individual episodes.

---

33-35: LGTM - Clear rejection reason constant.

The constant provides a consistent, user-friendly message for the forbidden pairing rejection.

---

37-52: LGTM - Robust forbidden-pairing predicate.

The rejection logic correctly prevents season packs from being cross-seeded against single-episode torrents when episode-aware matching is enabled. The unidirectional check (new=pack, existing=episode) is appropriate, as the reverse direction (extracting an episode from a pack) remains valid. All edge cases are properly handled through the helper functions' nil-safety.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

internal/services/crossseed/service.go (2)

3500-3511: Hard safety guard in findBestCandidateMatch looks correct; consider refining reason selection

Using rejectSeasonPackFromEpisode(sourceRelease, candidateRelease, true) here is a good “belt and suspenders” safety net so apply paths can’t ever accept season-pack‑from‑episode pairings, regardless of UI settings.

One minor refinement: today the season‑pack/episode rejection reason only wins if bestRejectReason is still empty. If a prior candidate already set a more generic reason, the more specific season‑pack/episode reason is dropped. If you care about surfacing the most informative message, you could reuse the “longest reason wins” logic you already apply for getMatchTypeWithReason:

-       if reject, reason := rejectSeasonPackFromEpisode(sourceRelease, candidateRelease, true); reject {
-           if bestRejectReason == "" {
-               bestRejectReason = reason
-           }
-           continue
-       }
+       if reject, reason := rejectSeasonPackFromEpisode(sourceRelease, candidateRelease, true); reject {
+           if reason != "" && (bestRejectReason == "" || len(reason) > len(bestRejectReason)) {
+               bestRejectReason = reason
+           }
+           continue
+       }

---

4574-4588: Search‑time forbidden pair filter and TV size‑check exception are coherent

The extra rejectSeasonPackFromEpisode(candidateRelease, sourceRelease, opts.FindIndividualEpisodes) in SearchTorrentMatches correctly treats the Torznab result as “new” and the local torrent as “existing”, so searches won’t surface season‑pack candidates against episode sources when that mode is enabled.

The updated ignoreSizeCheck condition,

ignoreSizeCheck := opts.FindIndividualEpisodes && isTVSeasonPack(sourceRelease) && isTVEpisode(candidateRelease)

matches the intended semantics of allowing large size deltas only when searching from a TV season pack into individual TV episodes. That narrows the previous behavior without breaking the episode‑from‑pack scenario.

One small observability nit: releaseFilteredCount now aggregates both generic release mismatches and these forbidden‑pair rejections. If you ever need to distinguish them in logs/metrics, consider a dedicated counter for forbidden pairs.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ace0101 and 59a64ec.

📒 Files selected for processing (7)

• internal/services/crossseed/align.go
• internal/services/crossseed/align_test.go
• internal/services/crossseed/matching.go
• internal/services/crossseed/matching_forbidden_pairs_test.go
• internal/services/crossseed/matching_layout_test.go
• internal/services/crossseed/models.go
• internal/services/crossseed/service.go

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: s0up4200
Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go:209-212
Timestamp: 2025-11-28T20:32:30.126Z
Learning: Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go
Learning: The cross-seed recheck-resume worker intentionally runs for the process lifetime and keys pending entries by hash only. This is acceptable under the current constraint that background seeded-search runs operate on a single instance at a time; graceful shutdown and instanceID|hash keying are deferred by design.

📚 Learning: 2025-11-28T20:32:30.126Z

Learnt from: s0up4200
Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go:209-212
Timestamp: 2025-11-28T20:32:30.126Z
Learning: Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go
Learning: The cross-seed recheck-resume worker intentionally runs for the process lifetime and keys pending entries by hash only. This is acceptable under the current constraint that background seeded-search runs operate on a single instance at a time; graceful shutdown and instanceID|hash keying are deferred by design.

Applied to files:

• internal/services/crossseed/models.go
• internal/services/crossseed/align.go
• internal/services/crossseed/matching.go
• internal/services/crossseed/service.go

📚 Learning: 2025-11-28T22:21:20.730Z

Learnt from: s0up4200
Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go:2415-2457
Timestamp: 2025-11-28T22:21:20.730Z
Learning: Repo: autobrr/qui PR: 641
File: internal/services/crossseed/service.go
Learning: The determineSavePath function intentionally includes a contentLayout string parameter for future/content-layout branching and API consistency. Its presence is by design even if unused in the current body; do not flag as an issue in reviews.

Applied to files:

• internal/services/crossseed/align.go
• internal/services/crossseed/service.go

🧬 Code graph analysis (2)

internal/services/crossseed/matching_forbidden_pairs_test.go (1)

pkg/version/version.go (1)

• Release (19-34)

internal/services/crossseed/matching_layout_test.go (3)

pkg/releases/parser.go (1)

• NewDefaultParser (29-31)

pkg/stringutils/normalize.go (1)

• NewDefaultNormalizer (35-37)

internal/services/crossseed/models.go (1)

• CrossSeedCandidate (187-199)

🔇 Additional comments (14)

internal/services/crossseed/models.go (1)

36-42: Documentation accurately describes the new TV-aware matching behavior.

The expanded comment clearly explains the dual nature of FindIndividualEpisodes: enabling episode-aware matching for discovery while preventing incorrect season-pack-from-episode cross-seeds. The same documentation is consistently applied across all relevant structs.

internal/services/crossseed/align_test.go (1)

188-191: Test expectation correctly updated to reflect new rejection logic.

The change from True to False for shouldRenameTorrentDisplay(&seasonPack, &episode) correctly aligns with the PR's objective to prevent season pack torrents from being renamed to match episode names. The test coverage for all four combinations (episode→pack, pack→episode, pack→pack, episode→otherPack) is comprehensive.

internal/services/crossseed/matching_layout_test.go (1)

116-149: Comprehensive test for season-pack-to-episode rejection.

The test correctly validates the new rejection behavior by:

1. Setting up a season pack source with multiple episode files
2. Providing only a single-episode candidate
3. Asserting that findBestCandidateMatch returns nil torrent/files and the specific rejection reason

This provides good coverage for the core rejection logic in the matching flow.

internal/services/crossseed/align.go (3)

48-59: Good defense-in-depth guard for forbidden pairings.

The safety check at alignment stage is appropriately defensive - while the rejection should be caught earlier in the flow, having this guard prevents data corruption if earlier checks are bypassed. The debug logging provides useful context for troubleshooting.

---

525-536: Rename guards correctly implement TV-aware logic.

The two guards work together:

1. Line 527-529: Prevents episode torrents from being renamed to season pack names (keeps episode named as episode)
2. Line 532-534: Prevents season pack torrents from being renamed to episode names (forbidden pairing)

The discarded error from rejectSeasonPackFromEpisode is acceptable since the function signature returns an error for future extensibility but currently always returns nil.

---

539-544: Alignment skip logic correctly updated.

Using the isTVEpisode and isTVSeasonPack helpers makes the condition more readable than the previous explicit field checks. The behavior is correct: when an episode points at season pack files, it uses a subset of the pack's files directly without needing alignment.

internal/services/crossseed/matching.go (2)

23-31: Clean helper functions with proper nil safety.

The isTVEpisode and isTVSeasonPack helpers are well-designed:

• Nil checks prevent panics when called with uninitialized releases
• Logic correctly distinguishes episodes (Series > 0 && Episode > 0) from season packs (Series > 0 && Episode == 0)
• Functions are pure and have no side effects, making them easy to test and use across the codebase

---

37-52: Rejection logic correctly implements the unidirectional constraint.

The function only rejects the forbidden direction (season pack → episode) while allowing the valid direction (episode → season pack). Key design decisions:

1. episodeMatching parameter: Allows callers to bypass rejection when the feature is disabled
2. Unidirectional check: isTVSeasonPack(newR) && isTVEpisode(existingR) specifically catches season packs trying to use episode files
3. Return values: (reject bool, reason string) allows callers to use just the boolean or include the reason in logs/responses

The documentation clearly explains the purpose and parameters.

internal/services/crossseed/matching_forbidden_pairs_test.go (4)

1-56: Comprehensive test coverage for isTVEpisode.

The test cases cover all relevant scenarios including nil handling, empty releases, non-TV content, season packs, and episodes. Using t.Parallel() at both the parent and subtest levels enables efficient parallel execution.

---

58-104: Thorough test coverage for isTVSeasonPack.

The test correctly validates that season packs are identified by having Series > 0 and Episode == 0, while other combinations return false.

---

106-220: Excellent test coverage for rejectSeasonPackFromEpisode.

The test matrix covers:

• The forbidden pairing in both enabled/disabled states
• Bidirectional checks (pack→episode vs episode→pack)
• Same-type pairings (episode→episode, pack→pack)
• Nil handling for both parameters
• Non-TV content (movies)
• Cross-type content (movie vs TV)

This provides high confidence in the rejection logic's correctness.

---

222-229: Good defensive test for the constant value.

Testing that the constant contains expected substrings ("Season packs" and "single-episode") helps catch accidental modifications to the error message while allowing minor wording adjustments.

internal/services/crossseed/service.go (2)

2226-2231: Season-pack/episode guard in findCandidates is well-placed

Short‑circuiting candidates via rejectSeasonPackFromEpisode(targetRelease, candidateRelease, req.FindIndividualEpisodes) before releasesMatch and file loading is correct and avoids unnecessary work. Argument ordering (new vs existing) is consistent with later call sites.

---

7400-7406: Webhook check now correctly excludes season‑pack‑from‑episode pairings

The new rejectSeasonPackFromEpisode(incomingRelease, existingRelease, findIndividualEpisodes) guard in CheckWebhook keeps incoming season packs from being treated as matches against existing single‑episode torrents when that mode is enabled, aligning webhook behavior with apply/search logic and preventing misleading “can cross‑seed” signals for those pairs.