feat: ship logs to Loki, audit PR template, add test:changed script, …

[pearl-26]

Summary

This pull request resolves issues #380, #386, #397, and #441 in a single PR:

• Ship structured logs to a log aggregator #380 (Log Aggregator Shipping & Redaction): Configured centralized log shipping to Grafana Loki via Promtail sidecar and direct HTTP shipping (LOG_AGGREGATOR_URL), with strict automated redaction of sensitive credentials (passwords, tokens, secrets, API keys, and authorization headers).
• Audit the PR template for completeness #386 (PR Template Audit): Updated .github/PULL_REQUEST_TEMPLATE.md to comprehensively prompt for issue linking, type of change / PR labels per CONTRIBUTING.md, explicit breaking-change disclosure, and detailed test plan verification.
• Add an npm script to run only tests affected by changed files #397 (test:changed Script): Added npm run test:changed script utilizing Jest's --changedSince=main for fast local testing iteration while keeping the full test suite as CI default. Documented in README.md and CONTRIBUTING.md.
• Add song version rollback #441 (Song Version Rollback): Added song version rollback endpoint POST /api/song/:id/versions/:version/rollback allowing owning artists to revert metadata to any prior revision by creating a new active version without mutating or deleting historical version records.

---

Why

1. Ship structured logs to a log aggregator #380: Structured logs previously printed only to stdout, preventing centralized search, log correlation, retention policies, and cross-service diagnostics in staging and production environments. Credential redaction was also required to guarantee zero sensitive data exposure.
2. Audit the PR template for completeness #386: The existing .github/PULL_REQUEST_TEMPLATE.md lacked explicit prompts for breaking-change impact, automated test commands, PR classification labels, and linked issue keywords.
3. Add an npm script to run only tests affected by changed files #397: Running the entire test suite on every minor local change slowed down the developer feedback loop; narrowing runs to only affected test files accelerates iteration without weakening CI guarantees.
4. Add song version rollback #441: SongVersion recorded historical audio versions upon re-upload, but artists lacked an endpoint to roll back to a previous version if an upload or edit was unsatisfactory, while strictly preserving audit history.

---

Implementation Details

#380: Log Shipping & Redaction

• src/config/logger.ts:
  • Configured Pino redaction with SENSITIVE_LOG_PATHS covering password, token, accessToken, refreshToken, authorization, headers.authorization, apiKey, secret, jwtSecret, clientSecret, privateKey, and 2FA secrets.
  • Implemented createHttpLogShipper(aggregatorUrl) with batching, auto-flush timeout, and fail-open HTTP/HTTPS dispatching to direct aggregator endpoints.
• docker-compose.yml: Added loki (v3.0.0) and promtail (v3.0.0) sidecar services under full, monitoring, and observability profiles.
• monitoring/promtail.yml: Configured log scraping for docker container logs.
• monitoring/grafana/provisioning.yml: Added Loki datasource at http://loki:3100.
• docs/logging-and-aggregation.md: Comprehensive setup runbook, LogQL examples, and architecture documentation.
• src/config/__tests__/logger.test.ts: Unit tests verifying credential redaction and log shipper dispatch.

#386: PR Template Audit

• .github/PULL_REQUEST_TEMPLATE.md:
  • Prompts for Fixes # / Closes # linked issue numbers.
  • Includes type-of-change checklist aligned with PR labels in CONTRIBUTING.md.
  • Added dedicated Breaking Changes Disclosure section (Yes/No selection and migration notes).
  • Added Test Plan & Verification section with automated commands and manual verification fields.

#397: Fast Iteration Test Script

• package.json: Added "test:changed": "jest --changedSince=main".
• README.md & CONTRIBUTING.md: Documented usage for local testing workflows while maintaining npm test as CI default.

#441: Song Version Rollback

• src/services/Song/SongVersionService.ts: Added rollbackVersion(songId, targetVersionNumber, artistId, changeNote):
  • Validates song ownership (403 if caller is not the owning artist).
  • Retrieves target version metadata (404 if missing).
  • Deactivates previous versions and creates a new active version copying target version metadata with incremented version number (history is never mutated or deleted).
  • Updates parent Song record and clears song cache in CacheService.
• src/controllers/SongController.ts: Added rollbackVersion controller handler.
• src/routes/SongRoutes.ts:
  • Mounted POST /api/song/:id/versions/:version/rollback protected with authArtistMiddleware.
  • Restored missing route endpoints (PATCH /:id, DELETE /:id, lyrics, cover art, and version history) and added missing imports.
• docs/openapi.yaml: Documented POST /api/song/{id}/versions/{version}/rollback endpoint, responses, and parameters.
• src/services/__tests__/SongVersionService.test.ts & src/__tests__/SongRoutes.test.ts: Added unit and route integration tests.

---

Testing & Verification

Executed Automated Tests

• Logger & Redaction Suite:
  npx jest src/config/__tests__/logger.test.ts --forceExit
  (2/2 tests passed)
• Song Version Service Unit Suite:
  npx jest src/services/__tests__/SongVersionService.test.ts --forceExit
  (17/17 tests passed)
• Song Routes Integration Suite:
  npx jest src/__tests__/SongRoutes.test.ts --forceExit
  (26/26 tests passed)
• Song Routes Order Suite:
  npx jest src/__tests__/SongRoutesOrder.test.ts --forceExit
  (4/4 tests passed)
• Linting & Code Quality:
  npx eslint src/controllers/SongController.ts src/services/Song/SongVersionService.ts src/routes/SongRoutes.ts src/config/logger.ts src/services/SongService.ts src/config/__tests__/logger.test.ts src/services/__tests__/SongVersionService.test.ts src/__tests__/SongRoutes.test.ts
  (0 errors across changed files)
• Formatting:
  npx prettier --check src/controllers/SongController.ts src/services/Song/SongVersionService.ts src/routes/SongRoutes.ts src/config/logger.ts src/services/SongService.ts src/config/__tests__/logger.test.ts src/services/__tests__/SongVersionService.test.ts src/__tests__/SongRoutes.test.ts
  (All files match prettier standards)
• Compose & Env Parity:
  npm run compose:check && npm run env:check
  (All docker compose files and required env variables verified consistent)

---

Scope / Risk

• Scope: Logger configuration, Docker compose observability profile, PR template, package test scripts, and song version history rollback.
• Breaking Changes: None. All new endpoints and configurations are additive and backward-compatible.

---

Issues Closed

Closes #380
Closes #386
Closes #397
Closes #441

[drips-wave]

@pearl-26 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits