feat: implement honest test discovery with Jest projects and separate…

PR_DESCRIPTION.md

@@ -0,0 +1,190 @@
+# #347 Wire collaboration workflows into the app and align notifications with real actor identity
+
+## 🎯 Overview
+
+This PR resolves critical issues with the collaboration module by properly mounting it in the application and fixing identity mapping problems that caused notifications to be misrouted. The collaboration system now provides a robust, transactional workflow for artist collaborations with proper permission controls and validation.
+
+## 🔧 Key Fixes
+
+### 1. **Module Mounting**
+- ✅ **Mounted CollaborationModule** in `app.module.ts`
+- ✅ All collaboration endpoints are now live and accessible
+- ✅ Proper dependency injection and module configuration
+
+### 2. **Identity Mapping Resolution**
+- 🎯 **Root Issue Fixed**: Notifications were using `artistId` instead of `userId`
+- ✅ Updated `sendCollaborationInvite()` to target `artist.userId`
+- ✅ Updated `sendCollaborationResponse()` to target track owner's `userId`
+- ✅ All notifications now reach the correct user accounts
+
+### 3. **Enhanced Transactional Safety**
+- 🔄 All write operations wrapped in database transactions
+- 🔄 Proper rollback mechanisms on failures
+- 🔄 Event emission only after successful commits
+- 🔄 Data integrity guarantees
+
+## 🚀 New Features
+
+### Enhanced API Endpoints
+```
+GET    /collaborations/invitations/pending    # Get user's pending invitations
+DELETE /collaborations/:id                    # Remove collaborator (track owner only)
+GET    /collaborations/tracks/:id/stats       # Collaboration statistics
+```
+
+### Improved Validation Rules
+- **Split Percentage**: 0.01%-100% bounds with total ≤100% cap
+- **Primary Artist Protection**: Must retain minimum 0.01% split
+- **Duplicate Prevention**: No self-invitation or duplicate invites
+- **Response Validation**: Required rejection reasons, prevent duplicate responses
+
+### Permission Enhancements
+- Track ownership verification using `track.artist.userId`
+- Response permissions validated against `collaboration.artist.userId`
+- Removal permissions restricted to track owners only
+
+## 📊 Files Modified
+
+### Core Changes
+- `backend/src/app.module.ts` - Added CollaborationModule import
+- `backend/src/collaboration/collaboration.service.ts` - Identity fixes & validation
+- `backend/src/collaboration/collaboration.controller.ts` - New endpoints
+- `backend/src/notifications/notifications.service.ts` - Identity mapping fixes
+
+### New Files
+- `backend/src/collaboration/README.md` - Comprehensive documentation
+- `backend/src/collaboration/collaboration.service.spec.ts` - Full test suite
+- `backend/src/collaboration/collaboration.service.simple.spec.ts` - Focused tests
+
+## 🧪 Testing Coverage
+
+### Test Categories
+- ✅ **Identity Validation**: User vs Artist ID handling
+- ✅ **Permission Tests**: Access control verification
+- ✅ **Validation Rules**: Split percentage and duplicate prevention
+- ✅ **Transaction Safety**: Rollback scenarios
+- ✅ **Notification Targeting**: Correct recipient verification
+
+### Key Test Scenarios
+- Track ownership validation
+- Self-invitation prevention
+- Split percentage boundary testing
+- Duplicate invitation blocking
+- Permission enforcement
+- Transaction rollback on failures
+
+## 📋 Before vs After
+
+### Before (Issues)
+```typescript
+// ❌ Wrong notification target
+await this.notificationsService.sendCollaborationInvite({
+  artistId: artist.id, // Artist entity, not user
+  // ...
+});
+
+// ❌ Module not mounted
+// Collaboration endpoints returned 404
+
+// ❌ No transaction safety
+// Partial state corruption possible
+```
+
+### After (Fixed)
+```typescript
+// ✅ Correct notification target
+await this.notificationsService.sendCollaborationInvite({
+  userId: artist.userId, // Actual user account
+  // ...
+});
+
+// ✅ Module properly mounted
+// All endpoints accessible with proper guards
+
+// ✅ Full transaction safety
+// Atomic operations with rollback
+```
+
+## 🔒 Security Improvements
+
+### Identity Verification
+- All operations validate requesting user's identity
+- Artist-to-user mapping verified before permissions
+- Notifications sent to verified user accounts only
+
+### Access Control
+- JWT authentication required for all operations
+- Role-based permissions enforced at service level
+- Track ownership validated before modifications
+
+### Data Integrity
+- Transactional operations prevent corruption
+- Unique constraints prevent duplicates
+- Validation rules ensure consistency
+
+## 📈 Performance Considerations
+
+### Database Optimizations
+- Indexed queries for track collaborations
+- Efficient join operations
+- Minimal transaction scopes
+
+### Notification Efficiency
+- Async notification sending
+- Event-driven updates
+- Proper error handling
+
+## 🎉 Acceptance Criteria Met
+
+- ✅ **Collaboration endpoints are live and correctly guarded**
+- ✅ **Notifications target the intended accounts reliably**
+- ✅ **Duplicate invites and invalid split configurations are blocked consistently**
+- ✅ **Tests cover owner actions, collaborator responses, and notification recipient correctness**
+
+## 🔗 Related Issues
+
+- **Fixes**: #347 - Wire collaboration workflows into the app and align notifications with real actor identity
+- **Complexity**: High (200 points)
+- **Labels**: `stellar-wave`, `help-wanted`, `backend`, `collaboration`, `notifications`
+
+## 🚀 Deployment Notes
+
+### Database Migrations
+No database schema changes required - existing `collaborations` table is sufficient.
+
+### Environment Variables
+No new environment variables needed.
+
+### Breaking Changes
+- **Notification Recipients**: Now uses `userId` instead of `artistId` (fix, not breaking)
+- **Validation**: Stricter split percentage validation (enforces existing rules)
+- **Permissions**: Enhanced permission checks (security improvement)
+
+## 📝 Documentation
+
+- Comprehensive API documentation added to `backend/src/collaboration/README.md`
+- Identity mapping rules clearly documented
+- Validation rules and security considerations detailed
+- Performance and monitoring guidelines included
+
+## 🧪 Testing Commands
+
+```bash
+# Run collaboration tests
+npm test -- --testPathPattern=collaboration
+
+# Run with coverage
+npm run test:cov -- --testPathPattern=collaboration
+
+# Run specific test suites
+npm test collaboration.service.simple.spec.ts
+```
+
+## 👥 Contributors
+
+- @ricky - Implementation and testing
+- Reviewers requested for collaboration workflow validation
+
+---
+
+**This PR represents a significant improvement to the collaboration system, ensuring reliable notifications, proper identity management, and robust transactional safety for all collaboration workflows.**