From 0364a3c8247cea5033595a94a3906475236fc48b Mon Sep 17 00:00:00 2001
From: Gronod <gordon@i3omb.com>
Date: Fri, 29 May 2026 12:57:01 +0100
Subject: [PATCH] refactor: add JSDoc examples and log helper tracing in
 titleMatches (#73)

---
 server/services/DownloadMatcher.js | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/server/services/DownloadMatcher.js b/server/services/DownloadMatcher.js
index 4ee72a1..28eb0d2 100644
--- a/server/services/DownloadMatcher.js
+++ b/server/services/DownloadMatcher.js
@@ -35,7 +35,7 @@ function normalizeTitle(str) {
  * and normalized (dots/dashes/underscores to spaces) forms bidirectionally.
  * Only logs on title fallback matches (when isFallback=true) to keep logs clean.
  */
-function titleMatches(clientName, arrTitle, { isFallback = true } = {}) {
+function titleMatches(clientName, arrTitle, { isFallback = true, caller = 'DownloadMatcher' } = {}) {
   if (!clientName || !arrTitle) return false;
   const a = clientName.toLowerCase();
   const b = arrTitle.toLowerCase();
@@ -48,7 +48,7 @@ function titleMatches(clientName, arrTitle, { isFallback = true } = {}) {
                   a.includes(bNorm) || bNorm.includes(a);
 
   if (matched && isFallback) {
-    logger.debug(`[DownloadMatcher] Title fallback match after normalization: "${clientName}" <-> "${arrTitle}"`);
+    logger.debug(`[DownloadMatcher] Title fallback match in ${caller} after normalization: "${clientName}" <-> "${arrTitle}"`);
   }
   return matched;
 }
@@ -56,6 +56,9 @@ function titleMatches(clientName, arrTitle, { isFallback = true } = {}) {
 /**
  * All callers (matchers + orphan path) must supply client, instanceId, and instanceName via options.
  * Defaults exist only as a last-resort safety net.
+ *
+ * @example
+ * buildArrDownload(sonarrMatch, context, { client: 'sabnzbd', instanceId: 'sabnzbd-default', instanceName: 'SABnzbd' })
  */
 function buildArrDownload(record, context, options = {}) {
   const {
@@ -251,13 +254,13 @@ async function matchSabSlots(slots, context) {
     if (!sonarrMatch) {
       sonarrMatch = sonarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabSlots' });
       });
     }
     if (!radarrMatch) {
       radarrMatch = radarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabSlots' });
       });
     }
 
@@ -265,13 +268,13 @@ async function matchSabSlots(slots, context) {
     if (!sonarrMatch) {
       sonarrMatch = sonarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabSlots' });
       });
     }
     if (!radarrMatch) {
       radarrMatch = radarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabSlots' });
       });
     }
 
@@ -362,13 +365,13 @@ async function matchSabHistory(slots, context) {
     if (!sonarrMatch) {
       sonarrMatch = sonarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabHistory' });
       });
     }
     if (!radarrMatch) {
       radarrMatch = radarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller: 'matchSabHistory' });
       });
     }
 
@@ -441,13 +444,13 @@ async function matchTorrents(torrents, context) {
     if (!sonarrMatch) {
       sonarrMatch = sonarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
     if (!radarrMatch) {
       radarrMatch = radarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
 
@@ -458,13 +461,13 @@ async function matchTorrents(torrents, context) {
     if (!sonarrHistoryMatch) {
       sonarrHistoryMatch = sonarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
     if (!radarrHistoryMatch) {
       radarrHistoryMatch = radarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }