fix(bot): improve autoplay source diversity

[LucasSantana-Dev]

Summary

• strengthen autoplay scoring so same-source candidates are penalized more heavily when equally viable alternatives exist
• add focused queue manipulation coverage for source-preference ordering and to prove the existing same-source cap still avoids refill starvation
• document the autoplay diversity tuning in the changelog

Test plan

• node ./node_modules/jest/bin/jest.js --config packages/bot/jest.config.cjs packages/bot/src/utils/music/queueManipulation.spec.ts --runInBand
• npm run type:check --workspace=packages/bot

Summary by CodeRabbit

• Improvements
  • Enhanced autoplay diversity: Autoplay recommendation scoring now more heavily penalizes same-source tracks, resulting in a queue that more reliably features tracks from varied sources for a richer listening experience.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lucky	Ready	Preview, Comment	Apr 6, 2026 9:59pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9fdf1177-614d-4449-8d74-5c91a2a939c2

📥 Commits

Reviewing files that changed from the base of the PR and between 1e59e63 and d7586fc.

📒 Files selected for processing (3)

• CHANGELOG.md
• packages/bot/src/utils/music/queueManipulation.spec.ts
• packages/bot/src/utils/music/queueManipulation.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: SonarCloud Scan
• GitHub Check: Quality Gates

🧰 Additional context used

📓 Path-based instructions (17)

**/*.{js,jsx,ts,tsx,vue,html}

📄 CodeRabbit inference engine (.cursor/rules/accessibility-openness.mdc)

Provide accessible UI components using semantic HTML and ARIA attributes where necessary

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/dependency-injection.mdc)

**/*.{ts,tsx,js,jsx}: Prefer constructor injection for classes that require dependencies
Avoid global mutable singletons unless necessary
Use explicit interfaces for external dependencies to make testing easier

**/*.{ts,tsx,js,jsx}: Include required references in PRs/code for non-trivial logic: TypeScript (official docs), MDN (JavaScript reference), and official docs for any runtime/framework/libraries used (e.g., Node.js, React) as applicable.
Before assuming behavior of an API, include the doc link and a ≤25-word quote when the change relies on it.

**/*.{ts,tsx,js,jsx}: Prefer named exports for clear usage and easier refactors in TypeScript/JavaScript
Keep import order consistent: external first, then internal modules
Remove dead code and unused imports

**/*.{ts,tsx,js,jsx}: Use PascalCase naming convention for React/UI components
Use camelCase naming convention for variables and functions
Use UPPER_SNAKE_CASE naming convention for constants
Maintain consistent import grouping and ordering within the project, keeping third-party imports separate from local imports
For external data sources (HTTP, database), always validate and sanitize input using type guards or schema validators

**/*.{ts,tsx,js,jsx}: Use Prettier with no semicolons, single quotes, 4-space indent, 80 character width
Files must not exceed 250 lines and this is enforced

Implement TypeScript typecheck and linter in CI quality checks

**/*.{ts,tsx,js,jsx}: Use TypeScript for enhanced type safety
Implement error handling and error logging
Avoid commenting code unless extremely necessary - code should explain itself with descriptive names
Leave NO todos, placeholders or missing pieces in the code
Variables and functions must use camelCase
Constants must use UPPER_SNAKE_CASE
Use arrow functions for methods and computed properties
Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
Maintain consistent import grouping/order: external imports first, then...

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/error-handling.mdc)

**/*.{js,jsx,ts,tsx}: Never throw strings. Throw Error (or typed subclasses) with descriptive messages
Include causal error as cause when available for better debugging
Define clear, stable error codes (e.g., ERR_AUTH_EXPIRED, ERR_NETWORK_TIMEOUT)
Provide optional metadata (e.g., details, retryable, status, correlationId) in error objects
Use domain error classes per area (e.g., AuthenticationError, ValidationError, NetworkError)
Log errors with structure (message, code, stack, cause, correlationId, user context where appropriate)
Mark retryable vs nonRetryable errors where helpful for operations
Set timeouts and handle aborts/cancellations; avoid dangling requests in API/network code
Implement backoff for transient failures; avoid infinite retries
Map HTTP status → domain errors; 4xx vs 5xx behave differently (e.g., retry for 5xx/network)

**/*.{js,jsx,ts,tsx}: Use functional components with hooks in React/React Native. Avoid class components.
Keep components focused on a single responsibility; extract complex logic into custom hooks.
Keep state local when possible. Use Context/Zustand/Redux only when necessary for state management.
If props or state traverse more than 3 levels, consider using context or a feature-scoped store instead of prop drilling.
Use performance optimization techniques: React.memo, useMemo, useCallback, Suspense (web), and virtualization for long lists; avoid unnecessary re-renders.
Web accessibility: use semantic HTML, labels, focus management, keyboard navigation, and aria-* attributes as needed.
React Native accessibility: use accessibility props (accessible, accessibilityLabel), proper roles and labels.
Identify and extract repetitive UI components proactively to components/ with clear props and minimal coupling.
Web styles: prefer co-located styles or design system tokens; avoid global style leakage.
React Native styles: prefer StyleSheet.create, design tokens, and theme providers; avoid in...

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/pattern.mdc)

Introduce interfaces at module boundaries to enable testing and substitutions

**/*.{ts,tsx}: Avoid using any type in TypeScript. If unavoidable, use unknown with type guards and justify with a code comment
Prefer interface for defining public object shapes in TypeScript, use type for unions and utility types
Use TypeScript utility types such as Partial, Pick, Omit, Readonly, and Record when appropriate
Use I{Name} naming convention for interfaces in TypeScript
Use T{Name} naming convention for type aliases and utility types in TypeScript

**/*.{ts,tsx}: Functions must be less than 50 lines with cyclomatic complexity less than 10
Do not use any types - ESLint enforces this at error level

**/*.{ts,tsx}: Prefer types over interfaces for most cases
Don't ever use any - type safety always
Avoid enums; use const objects instead
For complex types, create a separate file to declare them and import them
Avoid using any type; if unavoidable, use unknown with type guards and justify with code comment
Prefer interface for public API shapes; use type for unions and utility types
Use TypeScript utility types (Partial, Pick, Omit, Readonly, Record)

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{js,ts,tsx,jsx}

📄 CodeRabbit inference engine (.cursor/rules/documentation.mdc)

**/*.{js,ts,tsx,jsx}: Minimize comments in code; explain the 'why' when non-obvious, let code express the 'what' through clear naming
Document trade-offs briefly when deviating from ideal patterns

**/*.{js,ts,tsx,jsx}: Store secrets, ports, and hosts in environment variables (.env, .env.example) and never hardcode them
Avoid redundant or decorative AI comments; code should be self-explanatory and only commented when logic is non-obvious; prefer refactoring over lengthy comments

Never hardcode secrets, IPs, or ports; use .env and docs/ for required configuration variables

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

packages/bot/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/lucky-discord-bot.mdc)

packages/bot/**/*.{ts,tsx}: Use useMainPlayer() from discord-player to access the player instance; do not instantiate player directly
Do not duplicate queue or player state outside Discord Player; use shared services from @lucky/shared for persistent data like track history and session information
Use errorLog and debugLog from @lucky/shared/utils for logging throughout the bot package
Use embed and reply utilities from @lucky/shared for consistent message formatting and error sanitization across the bot
Use services from @lucky/shared (DatabaseService, Redis client) for database and cache access; do not instantiate Prisma or Redis directly in the bot package

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

packages/bot/**

📄 CodeRabbit inference engine (.cursor/rules/lucky-project.mdc)

The bot package depends on shared and contains Discord bot commands and player handlers using Discord.js and Discord Player

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{js,mjs,ts,mts}

📄 CodeRabbit inference engine (.cursor/rules/lucky-project.mdc)

Use Node.js version ≥22 with ESM (ECMAScript modules) only; no CommonJS

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

packages/bot/src/**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/subagent-discord.mdc)

Use @lucky/shared for database, Redis, logging, and embed utilities instead of implementing them locally

Files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

{CHANGELOG.md,README.md}

📄 CodeRabbit inference engine (.cursor/rules/agent-rules.mdc)

ALWAYS update CHANGELOG.md and README.md as changes are made.

Files:

• CHANGELOG.md

CHANGELOG.md

📄 CodeRabbit inference engine (.cursor/rules/templates-examples.mdc)

CHANGELOG.md must be updated with all changes in pull requests

Always update CHANGELOG.md with all code changes

Update CHANGELOG.md with all changes, include breaking changes documentation, and reference issues and PRs

Files:

• CHANGELOG.md

{CHANGELOG.md,docs/**}

📄 CodeRabbit inference engine (.cursor/rules/lucky-project.mdc)

Update CHANGELOG.md and relevant docs/ files when behavior or setup changes

Files:

• CHANGELOG.md

**/*.{test,spec}.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/frontend.mdc)

**/*.{test,spec}.{js,jsx,ts,tsx}: Test behavior, not implementation. Prefer Testing Library utilities for testing React/React Native components.
For React Native tests: mock native modules and test component interactions and accessibility labels.

Files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{test,spec}.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/pattern.mdc)

**/*.{test,spec}.{ts,tsx,js,jsx}: Test behavior, not implementation details
Prefer unit tests for core logic; add integration tests at meaningful boundaries

Files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{test,spec}.{js,ts,jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/testing-quality.mdc)

**/*.{test,spec}.{js,ts,jsx,tsx}: Use Jest + a React testing library for unit and component tests as applicable
Test behavior, not implementation details

Files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.{spec,test}.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/quality.mdc)

**/*.{spec,test}.{ts,tsx,js,jsx}: Use Jest for unit and integration tests
Test behavior, not implementation details
Run unit, integration tests, and coverage report in CI quality checks

Files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

**/*.spec.ts

📄 CodeRabbit inference engine (.cursor/rules/quality.mdc)

Unit tests must use naming convention *.spec.ts

Files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

🧠 Learnings (5)

📚 Learning: 2026-03-09T20:21:52.065Z

Learnt from: CR
Repo: LucasSantana-Dev/Lucky PR: 0
File: .cursor/rules/subagent-discord.mdc:0-0
Timestamp: 2026-03-09T20:21:52.065Z
Learning: Applies to packages/bot/src/functions/music/**/*.ts : Use existing voice/queue/guild validators before manipulating player or queue state

Applied to files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

📚 Learning: 2026-03-09T20:21:52.065Z

Learnt from: CR
Repo: LucasSantana-Dev/Lucky PR: 0
File: .cursor/rules/subagent-discord.mdc:0-0
Timestamp: 2026-03-09T20:21:52.065Z
Learning: Applies to packages/bot/src/functions/music/commands/**/*.ts : Use `.cursor/skills/music-queue-player/SKILL.md` for play, queue, skip, volume commands and player lifecycle management

Applied to files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

📚 Learning: 2026-03-09T20:20:47.877Z

Learnt from: CR
Repo: LucasSantana-Dev/Lucky PR: 0
File: .cursor/rules/lucky-discord-bot.mdc:0-0
Timestamp: 2026-03-09T20:20:47.877Z
Learning: Applies to packages/bot/**/*.{ts,tsx} : Do not duplicate queue or player state outside Discord Player; use shared services from `lucky/shared` for persistent data like track history and session information

Applied to files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

📚 Learning: 2026-03-15T21:57:49.951Z

Learnt from: CR
Repo: LucasSantana-Dev/Lucky PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-15T21:57:49.951Z
Learning: When working on music queue/player features (play/queue/skip/volume, player lifecycle), use the `music-queue-player` skill

Applied to files:

• packages/bot/src/utils/music/queueManipulation.ts
• packages/bot/src/utils/music/queueManipulation.spec.ts

📚 Learning: 2026-03-09T20:21:08.612Z

Learnt from: CR
Repo: LucasSantana-Dev/Lucky PR: 0
File: .cursor/rules/lucky-project.mdc:0-0
Timestamp: 2026-03-09T20:21:08.612Z
Learning: Applies to {packages/*/tests/**/*.test.{js,ts},tests/**/*.test.{js,ts}} : Add or adjust unit and integration tests when changing behavior; follow existing patterns in `packages/*/tests` and root `tests/` directories

Applied to files:

• packages/bot/src/utils/music/queueManipulation.spec.ts

🔇 Additional comments (5)

packages/bot/src/utils/music/queueManipulation.ts (1)

704-708: LGTM!

The increased penalty (0.15 → 0.25) for same-source tracks aligns well with the existing artist penalty on line 702, creating a balanced scoring model. The change is appropriately scoped and maintains backward compatibility with the existing hard caps in selectDiverseCandidates.

CHANGELOG.md (1)

18-18: LGTM!

The changelog entry accurately documents the scoring change and correctly notes that existing hard caps remain in place. Good balance of technical detail and user-facing clarity.

packages/bot/src/utils/music/queueManipulation.spec.ts (3)

63-69: LGTM!

The optional history field matches the first branch of getHistoryTracks (line 642-643 in the implementation), which checks for .toArray() method. Good alignment with the production code's defensive handling.

---

654-716: Well-designed test for source diversity preference.

The test correctly sets up a scenario where both candidates are penalized for being in recent artists (via history), but the different-source candidate wins due to avoiding the 0.25 same-source penalty. The assertion on recommendationReason containing "source variety" validates the scoring path.

---

718-791: Good coverage of the cap behavior under single-source conditions.

This test validates that MAX_TRACKS_PER_SOURCE=3 still allows filling the queue when only one source is available, confirming the PR description's claim about preventing "refill starvation."

---

📝 Walkthrough

Walkthrough

The autoplay recommendation scoring penalty for same-source tracks was increased from 0.15 to 0.25 to encourage queue diversity. Tests were added to verify the candidate-selection logic prioritizes different-source tracks and validates queueing behavior under varied source conditions.

Changes

Cohort / File(s)	Summary
Changelog Documentation CHANGELOG.md	Added entry documenting the autoplay scoring penalty adjustment for same-source track penalization.
Queue Manipulation Tests packages/bot/src/utils/music/queueManipulation.spec.ts	Extended QueueMock to support history tracking; added two test cases verifying candidate-selection prefers different-source tracks and validating queue replenishment with limited source diversity.
Queue Manipulation Logic packages/bot/src/utils/music/queueManipulation.ts	Increased same-source penalty in calculateRecommendationScore from 0.15 to 0.25.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(bot): last.fm duration fix, normalizers, and top tracks seeds #382: Modifies the same queue manipulation module and adjusts candidate scoring/selection logic for autoplay recommendations.
• feat(bot): autoplay fix, button controls, and queue improvements #320: Updates calculateRecommendationScore in the same module, directly affecting recommendation scoring behavior.
• feat(music): improve autoplay recommendations and shuffle behavior #130: Adjusts same-source track penalty calculation in the autoplay candidate scoring logic within queueManipulation.ts.

Suggested labels

bot, size/s

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ 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 accurately describes the main change: improving source diversity in autoplay by increasing the penalty for same-source tracks, which is the central modification across all three files.

_{✏️ 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 feature/autoplay-diversity-mainline

---

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.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud