refactor: Replace direct logging.getLogger() with centralized project loggers

Resolves issue #2 by refactoring all modules to use the project's centralized
logging system (detail_logger and status_logger) instead of direct
logging.getLogger(__name__) calls.

## Changes Made

### Refactored 12 files to use centralized loggers:
- Core modules: dispatcher.py, article_retraction_checker.py, retry_utils.py
- Backend modules: doaj.py, retraction_watch.py
- Updater modules: predatoryjournals.py, custom.py, algerian_helpers/*, bealls_helpers/*
- Utility modules: bibtex_parser.py

### Logging categorization:
- detail_logger: Technical details, debug info, internal processing (file only)
- status_logger: User-facing progress, status, errors (console + file)

### Added enforcement infrastructure:
- scripts/check-logging.py: Automated consistency checker
- Integrated logging checks into scripts/run-quality-checks.sh

## Benefits
- ✅ Consistent logging practices across entire codebase
- ✅ Clear separation of technical vs user-facing messages
- ✅ Improved maintainability and user experience
- ✅ Automated prevention of future regressions

[AI-assisted]

Author: florath

scripts/check-logging.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Script to enforce consistent logging practices in the codebase.
+
+This script checks that no files use direct logging.getLogger() and instead
+use the project's centralized detail_logger and status_logger.
+
+Usage:
+    python scripts/check-logging.py
+
+Exit code:
+    0: All checks pass
+    1: Violations found
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def check_direct_logger_usage():
+    """Check for direct logging.getLogger() usage."""
+    violations = []
+
+    # Find all Python files in src directory
+    src_dir = Path("src")
+    if not src_dir.exists():
+        print("ERROR: src directory not found. Run this script from the project root.")
+        return False
+
+    # Search for logging.getLogger(__name__) pattern
+    try:
+        result = subprocess.run(
+            ["grep", "-r", "-n", "logging\\.getLogger(__name__)", str(src_dir)],
+            capture_output=True,
+            text=True
+        )
+
+        if result.returncode == 0:
+            violations = result.stdout.strip().split('\n')
+
+    except FileNotFoundError:
+        print("ERROR: grep command not found. Install grep to run this check.")
+        return False
+
+    if violations:
+        print("❌ LOGGING VIOLATIONS FOUND:")
+        print()
+        print("The following files use direct logging.getLogger() instead of project loggers:")
+        print()
+
+        for violation in violations:
+            print(f"  {violation}")
+
+        print()
+        print("Fix these by:")
+        print("1. Remove 'import logging' and 'logger = logging.getLogger(__name__)'")
+        print("2. Add: from .logging_config import get_detail_logger, get_status_logger")
+        print("3. Add: detail_logger = get_detail_logger(); status_logger = get_status_logger()")
+        print("4. Use detail_logger for technical details, status_logger for user messages")
+        print()
+        return False
+
+    print("✅ All logging checks pass!")
+    return True
+
+
+def check_logger_imports():
+    """Check that files using loggers import from logging_config."""
+    try:
+        # Find files that use detail_logger or status_logger but don't import them
+        result = subprocess.run(
+            ["grep", "-r", "-l", "--include=*.py", "detail_logger\\|status_logger", "src"],
+            capture_output=True,
+            text=True
+        )
+
+        if result.returncode != 0:
+            return True  # No files use loggers, that's fine
+
+        files_using_loggers = result.stdout.strip().split('\n')
+        violations = []
+
+        for file_path in files_using_loggers:
+            # Skip the logging_config.py file itself and __pycache__ files
+            if "logging_config.py" in file_path or "__pycache__" in file_path:
+                continue
+
+            # Check if file imports from logging_config
+            import_result = subprocess.run(
+                ["grep", "-q", "from.*logging_config import", file_path],
+                capture_output=True
+            )
+
+            if import_result.returncode != 0:
+                violations.append(file_path)
+
+        if violations:
+            print("❌ LOGGING IMPORT VIOLATIONS:")
+            print()
+            print("Files use loggers but don't import from logging_config:")
+            for violation in violations:
+                print(f"  {violation}")
+            print()
+            return False
+
+    except FileNotFoundError:
+        print("WARNING: Could not run logger import check (grep not available)")
+
+    return True
+
+
+def main():
+    """Run all logging checks."""
+    print("Checking logging consistency...")
+    print()
+
+    checks_pass = True
+
+    # Check for direct logger usage
+    if not check_direct_logger_usage():
+        checks_pass = False
+
+    print()
+
+    # Check for proper imports
+    if not check_logger_imports():
+        checks_pass = False
+
+    if checks_pass:
+        print("✅ All logging checks passed!")
+        return 0
+    else:
+        print("❌ Logging violations found. Please fix them before committing.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/run-quality-checks.sh

@@ -49,6 +49,9 @@ run_check "Mypy type checking" mypy src/ --strict || true
 # 4. Pytest with coverage
 run_check "Pytest with coverage" pytest --cov=src --cov-report=term-missing tests/ || true
 
+# 5. Logging consistency check
+run_check "Logging consistency" python scripts/check-logging.py || true
+
 # Final summary
 echo -e "${BLUE}========================================${NC}"
 if [ $FAILED -eq 0 ]; then

src/aletheia_probe/article_retraction_checker.py

@@ -1,15 +1,13 @@
 """Article-level retraction checking using multiple data sources."""
 
 import asyncio
-import logging
 from typing import Any
 
 import aiohttp
 
 from .cache import get_cache_manager
 from .logging_config import get_detail_logger, get_status_logger
 
-logger = logging.getLogger(__name__)
 status_logger = get_status_logger()
 detail_logger = get_detail_logger()
 

src/aletheia_probe/backends/doaj.py

@@ -1,19 +1,20 @@
 """DOAJ (Directory of Open Access Journals) backend for legitimate journal verification."""
 
 import asyncio
-import logging
 import time
 from typing import Any
 from urllib.parse import quote
 
 import aiohttp
 
 from ..enums import AssessmentType
+from ..logging_config import get_detail_logger, get_status_logger
 from ..models import BackendResult, BackendStatus, QueryInput
 from ..retry_utils import async_retry_with_backoff
 from .base import HybridBackend, get_backend_registry
 
-logger = logging.getLogger(__name__)
+detail_logger = get_detail_logger()
+status_logger = get_status_logger()
 
 
 class RateLimitError(Exception):
@@ -63,7 +64,7 @@ async def _query_api(self, query_input: QueryInput) -> BackendResult:
             )
 
         except RateLimitError as e:
-            logger.warning(f"DOAJ API rate limit exceeded: {e}")
+            status_logger.warning(f"DOAJ API rate limit exceeded: {e}")
             return BackendResult(
                 backend_name=self.get_name(),
                 status=BackendStatus.RATE_LIMITED,
@@ -73,7 +74,7 @@ async def _query_api(self, query_input: QueryInput) -> BackendResult:
                 response_time=time.time() - start_time,
             )
         except aiohttp.ClientError as e:
-            logger.error(f"DOAJ API network error: {e}")
+            status_logger.error(f"DOAJ API network error: {e}")
             return BackendResult(
                 backend_name=self.get_name(),
                 status=BackendStatus.ERROR,
@@ -83,7 +84,7 @@ async def _query_api(self, query_input: QueryInput) -> BackendResult:
                 response_time=time.time() - start_time,
             )
         except Exception as e:
-            logger.error(f"DOAJ API unexpected error: {e}")
+            status_logger.error(f"DOAJ API unexpected error: {e}")
             return BackendResult(
                 backend_name=self.get_name(),
                 status=BackendStatus.ERROR,
@@ -127,7 +128,7 @@ async def _fetch_from_doaj_api(
                     retry_after = response.headers.get("Retry-After")
                     retry_seconds = int(retry_after) if retry_after else 60
 
-                    logger.warning(
+                    detail_logger.debug(
                         f"DOAJ API rate limit hit. Retry-After: {retry_seconds}s. URL: {url}"
                     )
 

src/aletheia_probe/backends/retraction_watch.py

@@ -1,15 +1,16 @@
 """Retraction Watch backend for journal quality assessment based on retraction data."""
 
 import json
-import logging
 from typing import Any
 
 from ..cache import get_cache_manager
+from ..logging_config import get_detail_logger, get_status_logger
 from ..models import BackendResult, BackendStatus, QueryInput
 from ..openalex import get_publication_stats
 from .base import CachedBackend, get_backend_registry
 
-logger = logging.getLogger(__name__)
+detail_logger = get_detail_logger()
+status_logger = get_status_logger()
 
 
 class RetractionWatchBackend(CachedBackend):
@@ -202,11 +203,11 @@ async def _get_openalex_data_cached(
         # Check cache first
         cached = get_cache_manager().get_cached_value(cache_key)
         if cached is not None:
-            logger.debug(f"OpenAlex cache hit for {journal_name}")
+            detail_logger.debug(f"OpenAlex cache hit for {journal_name}")
             return json.loads(cached) if cached != "null" else None
 
         # Fetch from OpenAlex API
-        logger.info(f"Fetching OpenAlex data on-demand for: {journal_name}")
+        status_logger.info(f"Fetching OpenAlex data on-demand for: {journal_name}")
         try:
             openalex_data = await get_publication_stats(journal_name, issn)
 
@@ -219,7 +220,7 @@ async def _get_openalex_data_cached(
             return openalex_data
 
         except Exception as e:
-            logger.warning(f"Failed to fetch OpenAlex data for {journal_name}: {e}")
+            status_logger.warning(f"Failed to fetch OpenAlex data for {journal_name}: {e}")
             # Cache the failure for 1 day to avoid repeated API calls
             get_cache_manager().set_cached_value(cache_key, "null", ttl_hours=24)
             return None

src/aletheia_probe/bibtex_parser.py

@@ -1,6 +1,5 @@
 """BibTeX parsing utilities for journal assessment."""
 
-import logging
 from pathlib import Path
 
 from pybtex.database import (  # type: ignore
@@ -11,9 +10,11 @@
 )
 from pybtex.scanner import PybtexError, PybtexSyntaxError  # type: ignore
 
+from .logging_config import get_detail_logger, get_status_logger
 from .models import BibtexEntry
 
-logger = logging.getLogger(__name__)
+detail_logger = get_detail_logger()
+status_logger = get_status_logger()
 
 
 class BibtexParser:
@@ -56,7 +57,7 @@ def parse_bibtex_file(file_path: Path) -> list[BibtexEntry]:
 
         for encoding, description in encoding_strategies:
             try:
-                logger.debug(f"Attempting to parse {file_path.name} with {description}")
+                detail_logger.debug(f"Attempting to parse {file_path.name} with {description}")
 
                 if description.endswith("with errors='replace'"):
                     # For the final attempt, use error handling to replace problematic characters
@@ -81,19 +82,19 @@ def parse_bibtex_file(file_path: Path) -> list[BibtexEntry]:
                         else:
                             skipped_entries += 1
                     except Exception as e:
-                        logger.warning(
+                        status_logger.warning(
                             f"Skipping entry '{entry_key}' due to processing error: {e}"
                         )
                         skipped_entries += 1
                         continue
 
                 if skipped_entries > 0:
-                    logger.info(
+                    status_logger.info(
                         f"Successfully parsed {len(entries)} entries from {file_path.name} "
                         f"with {description}, skipped {skipped_entries} problematic entries"
                     )
                 else:
-                    logger.debug(
+                    detail_logger.debug(
                         f"Successfully parsed {len(entries)} entries from {file_path.name} "
                         f"with {description}"
                     )
@@ -102,7 +103,7 @@ def parse_bibtex_file(file_path: Path) -> list[BibtexEntry]:
 
             except UnicodeDecodeError as e:
                 last_error = e
-                logger.debug(f"{description} decoding failed for {file_path.name}: {e}")
+                detail_logger.debug(f"{description} decoding failed for {file_path.name}: {e}")
                 continue
 
             except PybtexSyntaxError as e:
@@ -116,7 +117,7 @@ def parse_bibtex_file(file_path: Path) -> list[BibtexEntry]:
 
             except PybtexError as e:
                 last_error = e
-                logger.debug(
+                detail_logger.debug(
                     f"PyBTeX error with {description} for {file_path.name}: {e}"
                 )
                 continue
@@ -182,7 +183,7 @@ def _process_entry_safely(entry_key: str, entry: Entry) -> BibtexEntry | None:
                 raw_entry=entry,
             )
         except Exception as e:
-            logger.warning(f"Error processing entry {entry_key}: {e}")
+            detail_logger.debug(f"Error processing entry {entry_key}: {e}")
             return None
 
     @staticmethod
@@ -275,7 +276,7 @@ def _extract_authors_safely(entry: Entry) -> str | None:
                                 author_str = str(person)
                                 authors.append(author_str)
                             except (UnicodeDecodeError, UnicodeEncodeError) as e:
-                                logger.debug(f"Encoding error in author field: {e}")
+                                detail_logger.debug(f"Encoding error in author field: {e}")
                                 # Try to get a safe representation
                                 author_str = repr(person)
                                 authors.append(author_str)
@@ -286,7 +287,7 @@ def _extract_authors_safely(entry: Entry) -> str | None:
             # Fallback to raw field value
             return BibtexParser._get_field_safely(entry, "author")
         except Exception as e:
-            logger.debug(f"Error extracting authors: {e}")
+            detail_logger.debug(f"Error extracting authors: {e}")
             return None
 
     @staticmethod
@@ -319,7 +320,7 @@ def _get_field_safely(entry: Entry, field_name: str) -> str | None:
                         cleaned = value.strip("{}").strip()
                         return cleaned if cleaned else None
                     except (UnicodeDecodeError, UnicodeEncodeError) as e:
-                        logger.debug(f"Encoding error in field '{field_name}': {e}")
+                        detail_logger.debug(f"Encoding error in field '{field_name}': {e}")
                         # Try to get a safe representation
                         try:
                             # Attempt to encode/decode safely
@@ -333,7 +334,7 @@ def _get_field_safely(entry: Entry, field_name: str) -> str | None:
                             return repr(value).strip("'\"")
             return None
         except Exception as e:
-            logger.debug(f"Error getting field '{field_name}': {e}")
+            detail_logger.debug(f"Error getting field '{field_name}': {e}")
             return None
 
     @staticmethod