feat: Add conference-acronym CLI command group for managing acronyms (#101)

* feat: Add conference-acronym CLI command group for managing acronyms

Implements issue #87 by adding a new command group to manage the conference
acronym database with the following subcommands:

- conference-acronym status: Show database status (total count)
- conference-acronym stats: Show detailed statistics (most recent, oldest)
- conference-acronym list: List all acronym mappings with pagination
- conference-acronym clear: Clear all acronym entries with confirmation
- conference-acronym add: Manually add acronym mappings

The command group uses a hyphenated name to allow for future expansion
(e.g., journal-acronym) and follows existing CLI patterns for consistency.

Added helper methods to CacheManager:
- get_acronym_stats(): Returns statistics about acronym database
- list_all_acronyms(): Lists all mappings with optional pagination
- clear_acronym_database(): Clears all entries and returns count

All commands include proper error handling, confirmation prompts where
appropriate, and comprehensive unit tests.

[AI-assisted]

* feat: Add normalized venue name to conference-acronym list output

Added the normalized form of each full name to the conference-acronym list
command output. This shows users exactly what the system searches for after
normalization (after removing "Proceedings of" prefixes, year/edition suffixes,
parenthetical notes, and extra whitespace).

Example output now includes:
  Acronym: ICML
    Full Name: Proceedings of the 40th International Conference on Machine Learning (ICML 2023)
    Normalized: international conference on machine learning
    Source: bibtex_extraction
    Created: 2024-01-10 09:00:00
    Last Used: 2024-01-15 10:30:00

The normalization is performed using the input_normalizer which applies the
same cleaning and normalization logic used during actual assessment queries.

Updated tests to mock the normalizer and verify the normalized output is
displayed correctly.

[AI-assisted]

* refactor: Remove code duplication in conference-acronym status command

The status command was directly querying the database with SQL, duplicating
the logic already present in get_acronym_stats(). Now it uses the existing
CacheManager method for consistency and maintainability.

Also simplified the status tests to mock get_acronym_stats() instead of
creating real databases, making them faster and more focused.

Changes:
- status command now calls cache_manager.get_acronym_stats()
- Removed direct SQL query: SELECT COUNT(*) FROM conference_acronyms
- Updated tests to mock get_acronym_stats() return value
- Removed tempfile and sqlite3 setup from status tests

This eliminates code duplication and follows the DRY principle.

[AI-assisted]

---------

Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>

Author: coding-ai-assistant[bot]

src/aletheia_probe/cache.py

@@ -1189,6 +1189,118 @@ def store_acronym_mapping(
             )
             conn.commit()
 
+    def get_acronym_stats(self) -> dict[str, int | str]:
+        """
+        Get statistics about the acronym database.
+
+        Returns:
+            Dictionary containing count, most_recent, and oldest entry info
+        """
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+
+            # Get total count
+            cursor.execute("SELECT COUNT(*) as count FROM conference_acronyms")
+            count = cursor.fetchone()["count"]
+
+            # Get most recently used
+            cursor.execute(
+                """
+                SELECT acronym, full_name, last_used_at
+                FROM conference_acronyms
+                ORDER BY last_used_at DESC
+                LIMIT 1
+                """
+            )
+            most_recent = cursor.fetchone()
+
+            # Get oldest entry
+            cursor.execute(
+                """
+                SELECT acronym, full_name, created_at
+                FROM conference_acronyms
+                ORDER BY created_at ASC
+                LIMIT 1
+                """
+            )
+            oldest = cursor.fetchone()
+
+            stats = {"total_count": count}
+
+            if most_recent:
+                stats["most_recent_acronym"] = most_recent["acronym"]
+                stats["most_recent_full_name"] = most_recent["full_name"]
+                stats["most_recent_used"] = most_recent["last_used_at"]
+
+            if oldest:
+                stats["oldest_acronym"] = oldest["acronym"]
+                stats["oldest_full_name"] = oldest["full_name"]
+                stats["oldest_created"] = oldest["created_at"]
+
+            return stats
+
+    def list_all_acronyms(
+        self, limit: int | None = None, offset: int = 0
+    ) -> list[dict[str, str]]:
+        """
+        List all acronym mappings in the database.
+
+        Args:
+            limit: Maximum number of entries to return (None for all)
+            offset: Number of entries to skip
+
+        Returns:
+            List of dictionaries containing acronym details
+        """
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+
+            query = """
+                SELECT acronym, full_name, source, created_at, last_used_at
+                FROM conference_acronyms
+                ORDER BY acronym ASC
+            """
+
+            if limit is not None:
+                query += f" LIMIT {limit} OFFSET {offset}"
+
+            cursor.execute(query)
+            rows = cursor.fetchall()
+
+            return [
+                {
+                    "acronym": row["acronym"],
+                    "full_name": row["full_name"],
+                    "source": row["source"],
+                    "created_at": row["created_at"],
+                    "last_used_at": row["last_used_at"],
+                }
+                for row in rows
+            ]
+
+    def clear_acronym_database(self) -> int:
+        """
+        Clear all entries from the acronym database.
+
+        Returns:
+            Number of entries deleted
+        """
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+
+            # Get count before deletion
+            cursor.execute("SELECT COUNT(*) FROM conference_acronyms")
+            result = cursor.fetchone()
+            count: int = result[0] if result else 0
+
+            # Delete all entries
+            cursor.execute("DELETE FROM conference_acronyms")
+            conn.commit()
+
+            return count
+
 
 # Global cache manager instance with factory pattern
 _cache_manager_instance: CacheManager | None = None

src/aletheia_probe/cli.py

@@ -297,6 +297,167 @@ def bibtex(
     asyncio.run(_async_bibtex_main(bibtex_file, verbose, output_format, relax_bibtex))
 
 
+@main.group(name="conference-acronym")
+def conference_acronym() -> None:
+    """Manage the conference acronym database."""
+    pass
+
+
+@conference_acronym.command(name="status")
+def acronym_status() -> None:
+    """Show conference acronym database status."""
+    status_logger = get_status_logger()
+
+    try:
+        cache_manager = get_cache_manager()
+        stats = cache_manager.get_acronym_stats()
+        count = stats.get("total_count", 0)
+
+        status_logger.info("Conference Acronym Database Status")
+        status_logger.info("=" * 40)
+
+        if count == 0:
+            status_logger.info("Database is empty (no acronyms stored)")
+        else:
+            status_logger.info(f"Total acronyms: {count:,}")
+
+    except Exception as e:
+        status_logger.error(f"Error getting acronym database status: {e}")
+        exit(1)
+
+
+@conference_acronym.command()
+def stats() -> None:
+    """Show detailed statistics about the acronym database."""
+    status_logger = get_status_logger()
+
+    try:
+        cache_manager = get_cache_manager()
+        stats = cache_manager.get_acronym_stats()
+
+        status_logger.info("Conference Acronym Database Statistics")
+        status_logger.info("=" * 40)
+
+        total = stats.get("total_count", 0)
+
+        if total == 0:
+            status_logger.info("Database is empty (no acronyms stored)")
+            return
+
+        status_logger.info(f"Total acronyms: {total:,}")
+
+        if "most_recent_acronym" in stats:
+            status_logger.info("\nMost Recently Used:")
+            status_logger.info(f"  Acronym: {stats['most_recent_acronym']}")
+            status_logger.info(f"  Full Name: {stats['most_recent_full_name']}")
+            status_logger.info(f"  Last Used: {stats['most_recent_used']}")
+
+        if "oldest_acronym" in stats:
+            status_logger.info("\nOldest Entry:")
+            status_logger.info(f"  Acronym: {stats['oldest_acronym']}")
+            status_logger.info(f"  Full Name: {stats['oldest_full_name']}")
+            status_logger.info(f"  Created: {stats['oldest_created']}")
+
+    except Exception as e:
+        status_logger.error(f"Error getting acronym statistics: {e}")
+        exit(1)
+
+
+@conference_acronym.command()
+@click.option("--limit", type=int, help="Maximum number of entries to display")
+@click.option("--offset", type=int, default=0, help="Number of entries to skip")
+def list(limit: int | None, offset: int) -> None:
+    """List all acronym mappings in the database."""
+    status_logger = get_status_logger()
+
+    try:
+        cache_manager = get_cache_manager()
+        acronyms = cache_manager.list_all_acronyms(limit=limit, offset=offset)
+
+        if not acronyms:
+            status_logger.info("No acronyms found in the database.")
+            return
+
+        status_logger.info("Conference Acronym Mappings")
+        status_logger.info("=" * 80)
+
+        for entry in acronyms:
+            # Normalize the full name to show what the system actually searches for
+            normalized_name = input_normalizer.normalize(
+                entry["full_name"]
+            ).normalized_name
+
+            status_logger.info(f"\nAcronym: {entry['acronym']}")
+            status_logger.info(f"  Full Name: {entry['full_name']}")
+            status_logger.info(f"  Normalized: {normalized_name}")
+            status_logger.info(f"  Source: {entry['source']}")
+            status_logger.info(f"  Created: {entry['created_at']}")
+            status_logger.info(f"  Last Used: {entry['last_used_at']}")
+
+        total_count = cache_manager.get_acronym_stats()["total_count"]
+        shown = len(acronyms)
+
+        if limit is not None or offset > 0:
+            status_logger.info(f"\nShowing {shown} of {total_count:,} total acronyms")
+
+    except Exception as e:
+        status_logger.error(f"Error listing acronyms: {e}")
+        exit(1)
+
+
+@conference_acronym.command()
+@click.option("--confirm", is_flag=True, help="Skip confirmation prompt")
+def clear(confirm: bool) -> None:
+    """Clear all entries from the acronym database."""
+    status_logger = get_status_logger()
+
+    if not confirm:
+        click.confirm(
+            "This will delete all conference acronym mappings. Continue?", abort=True
+        )
+
+    try:
+        cache_manager = get_cache_manager()
+        count = cache_manager.clear_acronym_database()
+
+        if count == 0:
+            status_logger.info("Acronym database is already empty.")
+        else:
+            status_logger.info(f"Cleared {count:,} acronym mapping(s).")
+
+    except Exception as e:
+        status_logger.error(f"Error clearing acronym database: {e}")
+        exit(1)
+
+
+@conference_acronym.command()
+@click.argument("acronym")
+@click.argument("full_name")
+@click.option(
+    "--source",
+    default="manual",
+    help="Source of the mapping (default: manual)",
+)
+def add(acronym: str, full_name: str, source: str) -> None:
+    """Manually add an acronym mapping to the database.
+
+    ACRONYM: The conference acronym (e.g., ICML)
+    FULL_NAME: The full conference name
+    """
+    status_logger = get_status_logger()
+
+    try:
+        cache_manager = get_cache_manager()
+        cache_manager.store_acronym_mapping(acronym, full_name, source)
+
+        status_logger.info(f"Added acronym mapping: {acronym} -> {full_name}")
+        status_logger.info(f"Source: {source}")
+
+    except Exception as e:
+        status_logger.error(f"Error adding acronym mapping: {e}")
+        exit(1)
+
+
 async def _async_bibtex_main(
     bibtex_file: str, verbose: bool, output_format: str, relax_bibtex: bool
 ) -> None: