Merge pull request #634 from frankieramirez/frankieramirez/wayfinder-issue-611-4

fix: fold folder scan diagnostics into debug logging

Author: frankieramirez

.changeset/folder-scan-follows-debug.md

@@ -0,0 +1,5 @@
+---
+"comicarr": patch
+---
+
+Debug logging now includes useful folder-scan diagnostics without a second hidden switch. Comicarr removes the legacy `folder_scan_log_verbose` setting during the configuration upgrade; set the single Log level to `2 · Debug` when diagnosing scan matching. Candidate-heavy scans now summarize their work per input file instead of flooding the log with one line for every comparison.

CONTEXT.md

@@ -24,6 +24,8 @@ The MangaDex UUID a manga Series polls for new chapters. MangaDex Series carry i
 
 Comicarr's single verbosity dial, named by the severity it admits: `0` warning, `1` info, `2` debug. Level `0` means warnings and errors, not silence, which is why it is never called "quiet" — `--quiet` and `--verbose` are flag spellings, not level names.
 
+Subsystem diagnostics, including folder-scan diagnostics, are Debug entries rather than independent verbosity controls. High-volume operations summarize their diagnostics instead of introducing another dial.
+
 ## Support bundle
 
 A downloadable archive of allowlisted diagnostic data, engineered for public issue attachment after operator review. If its contents appear sensitive, the operator shares it privately with maintainers instead; CarePackage is the legacy implementation name, not the user-facing term.

comicarr/app/config/registry.py

@@ -114,7 +114,7 @@ def as_definition(self) -> tuple[type, str, Any]:
 # ---------------------------------------------------------------------------
 
 _KEYS: tuple[ConfigKey, ...] = (
-    ConfigKey("CONFIG_VERSION", int, "General", 17),
+    ConfigKey("CONFIG_VERSION", int, "General", 18),
     ConfigKey("MINIMAL_INI", bool, "General", False),
     ConfigKey("CACHE_DIR", str, "General", None, readable=True),
     ConfigKey("DYNAMIC_UPDATE", int, "General", 0),
@@ -136,7 +136,6 @@ def as_definition(self) -> tuple[type, str, Any]:
     ConfigKey("UPDATE_ENDED", bool, "General", False),
     ConfigKey("NEWCOM_DIR", str, "Update", None),
     ConfigKey("FFTONEWCOM_DIR", bool, "Update", False),
-    ConfigKey("FOLDER_SCAN_LOG_VERBOSE", bool, "General", False),
     ConfigKey("INTERFACE", str, "General", "carbon"),
     ConfigKey("CORRECT_METADATA", bool, "General", False),
     ConfigKey("MOVE_FILES", bool, "General", False),

comicarr/config.py

@@ -254,7 +254,7 @@ def config_vals(self, update=False):
                 count = 0
 
             # this is the current version at this particular point in time.
-            self.newconfig = 17
+            self.newconfig = 18
 
             OLDCONFIG_VERSION = 0
             if count == 0:
@@ -504,6 +504,14 @@ def read(self, startup=False):
                         "[CONFIG] Removed host_return: the SABnzbd handoff now uploads the "
                         "nzb directly and no download client is given a Comicarr address."
                     )
+            if self.CONFIG_VERSION < 18:
+                # Folder-scan diagnostics now follow the single LOG_LEVEL dial;
+                # remove the retired, hidden verbosity switch from old configs.
+                if config.has_option("General", "folder_scan_log_verbose"):
+                    config.remove_option("General", "folder_scan_log_verbose")
+                    logger.info(
+                        "[CONFIG] Removed folder_scan_log_verbose: folder-scan diagnostics now follow LOG_LEVEL=debug."
+                    )
             self.OLDCONFIG_VERSION = str(self.CONFIG_VERSION)
             self.CONFIG_VERSION = self.newconfig
             config.set("General", "CONFIG_VERSION", str(self.newconfig))

comicarr/filechecker.py

@@ -310,16 +310,13 @@ def parseit(self, path, filename, subpath=None):
         # if it's a story-arc, make sure to remove any leading reading order #'s
         if self.sarc and comicarr.CONFIG.READ2FILENAME:
             removest = modfilename.find("-")  # the - gets removed above so we test for the first blank space...
-            if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                logger.fdebug(
-                    "[SARC] Checking filename for Reading Order sequence - Reading Sequence Order found #: %s"
-                    % modfilename[:removest]
-                )
+            logger.fdebug(
+                "[SARC] Checking filename for Reading Order sequence - candidate: %s" % modfilename[:removest]
+            )
             if modfilename[:removest].isdigit() and removest <= 3:
                 reading_order = {"reading_sequence": str(modfilename[:removest]), "filename": filename[removest + 1 :]}
                 modfilename = modfilename[removest + 1 :]
-                if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                    logger.fdebug("[SARC] Removed Reading Order sequence from subname. Now set to : %s" % modfilename)
+                logger.fdebug("[SARC] Validated and removed Reading Order sequence. Filename is now: %s" % modfilename)
 
         # make sure all the brackets are properly spaced apart
         if modfilename.find(r"\s") == -1:
@@ -1846,11 +1843,7 @@ def matchIT(self, series_info):
                     == re.sub(r"[\|\s]", "", nspace_seriesname.lower()).strip()
                 ]
                 if len(loopchk) > 0 and loopchk[0] != "":
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("[FILECHECKER] This should be an alternate: %s" % loopchk)
                     if any(["annual" in series_name.lower(), "special" in series_name.lower()]):
-                        if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                            logger.fdebug("[FILECHECKER] Annual/Special detected - proceeding")
                         enable_annual = True
 
                 else:
@@ -1866,64 +1859,32 @@ def matchIT(self, series_info):
                     loopchk.append(nspace_watchcomic)
                     if any(["annual" in nspace_seriesname.lower(), "special" in nspace_seriesname.lower()]):
                         if "biannual" in nspace_seriesname.lower():
-                            if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                                logger.fdebug("[FILECHECKER] BiAnnual detected - wouldn't Deadpool be proud?")
                             nspace_seriesname = re.sub("biannual", "", nspace_seriesname).strip()
                             enable_annual = True
                         elif "annual" in nspace_seriesname.lower():
-                            if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                                logger.fdebug("[FILECHECKER] Annual detected - proceeding cautiously.")
                             off_year_check = re.findall(r"(\d{4})(?=[\s]|annual\b|$)", self.watchcomic, flags=re.I)
                             if off_year_check:
                                 n_name = "%s%s" % (off_year_check[0], "annual")
                                 nspace_seriesname = re.sub(n_name, "", nspace_seriesname.lower()).strip()
                             nspace_seriesname = re.sub("annual", "", nspace_seriesname.lower()).strip()
                             enable_annual = False
                         elif "special" in nspace_seriesname.lower():
-                            if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                                logger.fdebug("[FILECHECKER] Special detected - proceeding cautiously.")
                             nspace_seriesname = re.sub("special", "", nspace_seriesname).strip()
                             enable_annual = False
 
-                if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                    logger.fdebug(
-                        "[FILECHECKER] Complete matching list of names to this file [%s] : %s" % (len(loopchk), loopchk)
-                    )
-
-                for loopit in loopchk:
-                    # now that we have the list of all possible matches for the watchcomic + alternate search names, we go through the list until we find a match.
-                    modseries_name = loopit
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("[FILECHECKER] AS_Tuple : %s" % self.AS_Tuple)
-                        for ATS in self.AS_Tuple:
-                            if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                                logger.fdebug(
-                                    "[FILECHECKER] %s comparing to %s" % (ATS["AS_Alternate"], nspace_seriesname)
-                                )
-                            if (
-                                re.sub(r"\|", "", ATS["AS_Alternate"].lower()).strip()
-                                == re.sub(r"\|", "", nspace_seriesname.lower()).strip()
-                            ):
-                                if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                                    logger.fdebug("[FILECHECKER] Associating ComiciD : %s" % ATS["ComicID"])
-                                annual_comicid = str(ATS["ComicID"])
-                                modseries_name = ATS["AS_Alternate"]
-                                break
-
-                    logger.fdebug("[FILECHECKER] %s - watchlist match on : %s" % (modseries_name, filename))
+                for ATS in self.AS_Tuple:
+                    if (
+                        re.sub(r"\|", "", ATS["AS_Alternate"].lower()).strip()
+                        == re.sub(r"\|", "", nspace_seriesname.lower()).strip()
+                    ):
+                        annual_comicid = str(ATS["ComicID"])
+                        break
 
             if enable_annual:
                 if annual_comicid is not None:
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("enable annual is on")
-                        logger.fdebug("annual comicid is %s" % annual_comicid)
                     if "biannual" in nspace_watchcomic.lower():
-                        if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                            logger.fdebug("bi annual detected")
                         justthedigits = "BiAnnual %s" % justthedigits
                     elif "annual" in nspace_watchcomic.lower():
-                        if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                            logger.fdebug("annual detected")
                         justthedigits = "Annual %s" % justthedigits
                     elif "special" in nspace_watchcomic.lower():
                         justthedigits = "Special %s" % justthedigits
@@ -2152,16 +2113,10 @@ def altcheck(self):
                     # if it's !! present, it's the comicid associated with the series as an added annual.
                     # extract the !!, store it and then remove it so things will continue.
                     as_start = AS_Alternate.find("!!")
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("as_start: %s --- %s" % (as_start, AS_Alternate[as_start:]))
                     as_end = AS_Alternate.find("##", as_start)
                     if as_end == -1:
                         as_end = len(AS_Alternate)
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("as_start: %s --- %s" % (as_end, AS_Alternate[as_start:as_end]))
                     AS_ComicID = AS_Alternate[as_start + 2 : as_end]
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug("[FILECHECKER] Extracted comicid for given annual : %s" % AS_ComicID)
                     AS_Alternate = re.sub("!!" + str(AS_ComicID), "", AS_Alternate)
                     AS_tupled = True
                 as_dyninfo = self.dynamic_replace(AS_Alternate)
@@ -2318,10 +2273,6 @@ def normalize(s):
         ratio = difflib.SequenceMatcher(None, parsed_name, comic_name).ratio()
         name_score = int(ratio * 40)
         score += name_score
-        if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-            logger.fdebug(
-                '[CONFIDENCE] Name match: "%s" vs "%s" = %.2f (%d pts)' % (parsed_name, comic_name, ratio, name_score)
-            )
 
     # 2. Year Match (15 pts)
     parsed_year = parsed_info.get("issue_year") or parsed_info.get("ComicYear")

comicarr/postprocessor.py

@@ -57,6 +57,34 @@
 _POSTPROCESS_INPUT_STAGE = PostProcessInputStage()
 
 
+def format_scan_summary(filename, candidate_count, selected_items, annual_count, story_arc):
+    """Format the bounded Debug summary emitted once for each scanned file."""
+    selected = (
+        ", ".join("%s/%s" % (item.get("ComicID", "?"), item.get("ComicName", "?")) for item in selected_items) or "none"
+    )
+    return "[SCAN SUMMARY] %s: candidates=%s, selected=%s, annual_or_special=%s, story_arc=%s" % (
+        filename,
+        candidate_count,
+        selected,
+        annual_count,
+        story_arc,
+    )
+
+
+def log_scan_summary(module, filename, candidate_count, selected_items, annual_count, story_arc):
+    logger.fdebug(
+        "%s%s" % (module, format_scan_summary(filename, candidate_count, selected_items, annual_count, story_arc))
+    )
+
+
+def summarize_scan_matches(normal_items, arc_items):
+    """Build summary fields from the matches selected for one input file."""
+    selected_items = normal_items + arc_items
+    annual_count = sum(1 for item in selected_items if item.get("AnnualType"))
+    story_arc = bool(arc_items or any(item.get("IssueArcID") for item in normal_items))
+    return selected_items, annual_count, story_arc
+
+
 class PostProcessor(object):
     """
     A class which will process a media file according to the post processing settings in the config.
@@ -666,7 +694,6 @@ def Process(self):
                     self.comicid = cid["ComicID"]
                 else:
                     if "_" in self.issueid:
-                        logger.fdebug("Story Arc post-processing request detected.")
                         self.issuearcid = self.issueid
                         self.issueid = None
                         logger.fdebug(
@@ -713,6 +740,8 @@ def Process(self):
             oneoff_issuelist = []
             manual_list = []
             for fl in filelist["comiclist"]:
+                manual_list_start = len(manual_list)
+                manual_arclist_start = len(manual_arclist)
                 if (
                     all([fl["series_name"] is not None, fl["series_name"] != ""])
                     and comicarr.CONFIG.IGNORE_COVERS is True
@@ -1132,7 +1161,6 @@ def Process(self):
                             #    continue
                 watchvals = []
                 for wv in comicseries:
-                    logger.info("Now checking: %s [%s]" % (wv["ComicName"], wv["ComicID"]))
                     # do some extra checks in here to ignore these types:
                     # check for valid issue number - if not, don't even bother checking it
                     try:
@@ -1201,11 +1229,6 @@ def Process(self):
                     wv_latestissue = wv["LatestIssue"]
                     wv_intlatestissue = wv["intLatestIssue"]
                     wv_forcecontinuing = bool(wv["ForceContinuing"])
-                    if comicarr.CONFIG.FOLDER_SCAN_LOG_VERBOSE:
-                        logger.fdebug(
-                            "Queuing to Check: %s [%s] -- %s" % (wv["ComicName"], wv["ComicYear"], wv["ComicID"])
-                        )
-
                     # force it to use the Publication Date of the latest issue instead of the Latest Date (which could be anything)
                     ld_check = db.select_one(
                         select(issues.c.ReleaseDate, issues.c.Issue_Number, issues.c.Int_IssueNumber)
@@ -2898,6 +2921,19 @@ def Process(self):
                                 self.matched = True
                                 break
 
+                selected_items, annual_count, story_arc_matched = summarize_scan_matches(
+                    manual_list[manual_list_start:],
+                    manual_arclist[manual_arclist_start:],
+                )
+                log_scan_summary(
+                    module,
+                    fl["comicfilename"],
+                    len(watchvals),
+                    selected_items,
+                    annual_count,
+                    story_arc_matched,
+                )
+
             if filelist["comiccount"] > 0:
                 logger.fdebug(
                     "%s There are %s files found that match on your watchlist, %s files are considered one-off's, and %s files do not match anything"

docs/architecture/logging-levels.md

@@ -184,6 +184,14 @@ choose by what they are actually asking.
 
 ## Two rules that fall out of it
 
+**Subsystem diagnostics are entries, not dials.** Folder scanning used to put
+some of its `DEBUG` entries behind `FOLDER_SCAN_LOG_VERBOSE`, a hidden legacy
+`config.ini` key. That made level `2` an incomplete promise: an operator could
+ask for everything and still miss the matching details they needed. Folder-scan
+diagnostics now follow the log level like every other entry. High-cardinality
+matching work is summarized per input file instead of requiring a second switch
+to keep candidate-by-candidate chatter manageable.
+
 **Level 0 is "warnings and errors", not silence.** An operator who turns the
 dial down is asking for less noise, not for failures to be hidden. This is why
 the setup-token announcement in `app/system/service.py` echoes to stdout at

frontend/tests/e2e/support-bundle.smoke.spec.ts

@@ -37,7 +37,7 @@ test("Settings → About creates a Support bundle ZIP", async ({
   );
 
   await page.goto("/settings?section=about");
-  await expect(page.getByText("Support bundle")).toBeVisible();
+  await expect(page.getByText("Support bundle", { exact: true })).toBeVisible();
   await expect(page.getByText("1. Create")).toBeVisible();
   await expect(page.getByText("2. Inspect")).toBeVisible();
   await expect(page.getByText("3. Share")).toBeVisible();
@@ -87,7 +87,12 @@ test("Settings → About creates a Support bundle ZIP", async ({
   }
 
   // Unauthenticated request cannot invoke the endpoint.
-  const bare = await page.context().browser()!.newContext();
+  const bare = await page
+    .context()
+    .browser()!
+    .newContext({
+      storageState: { cookies: [], origins: [] },
+    });
   const bareResp = await bare.request.post("/api/system/support-bundle", {
     headers: { "X-Requested-With": "ComicarrFrontend" },
   });