rxiv-maker 1.16.6__tar.gz → 1.16.8__tar.gz

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/.gitignore

@@ -52,7 +52,6 @@ output.txt
 *~
 
 # Claude Code configuration
-!CLAUDE.md
 .claude
 
 # Byte-compiled / optimized / DLL files
@@ -316,6 +315,7 @@ GEMINI.md
 !CHANGELOG.md
 !CONTRIBUTING.md
 !CODE_OF_CONDUCT.md
+!CLAUDE.md
 !docs/**/*.md
 !EXAMPLE_MANUSCRIPT/**/*.md
 !MANUSCRIPT/**/*.md
@@ -330,7 +330,6 @@ GEMINI.md
 todo*.md
 DOCKER_ACCELERATION.md
 GEMINI.md
-CLAUDE.md
 output.md
 
 # Temporary analysis files

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.16.8] - 2025-12-19
+
+### Added
+
+- **Automatic Poppler Installation**: Interactive installation prompt for DOCX export on macOS
+  - Detects missing poppler utilities when exporting to DOCX with PDF figures
+  - Offers automatic installation via Homebrew with user confirmation
+  - Shows clear installation instructions for Linux (apt) and other platforms
+  - Gracefully falls back to placeholders when poppler unavailable
+- **DOI Resolution Implementation**: `--resolve-dois` flag now fully functional for DOCX export
+  - Resolves missing DOIs using CrossRef API with intelligent title matching
+  - Cleans LaTeX commands from titles for accurate search results
+  - Validates matches using year information when available
+  - Handles network failures and timeouts gracefully
+  - Logs resolved DOIs for transparency
+- **Poppler Dependency Tracking**: Registered poppler in DependencyManager
+  - Added as system binary dependency with alternatives (pdftoppm, pdfinfo)
+  - Included in `rxiv check-installation` output
+  - Provides platform-specific installation hints
+
+### Fixed
+
+- **BST File Regex Bug**: Corrected bibliography style file generation to only modify `format.names`
+  - Previous regex matched both `format.names` and `format.full.names` functions
+  - Now specifically targets only `format.names` function using DOTALL flag
+  - Prevents corruption of citation labels in natbib
+  - Eliminates warning: "Found 2 format string patterns in .bst file"
+  - Raises error if unexpected matches found (defensive programming)
+- **PDF to Image Conversion**: Improved error handling for missing poppler utilities
+  - Distinguishes between poppler not installed, corrupted PDFs, and other errors
+  - Uses proper logging instead of print statements
+  - Re-raises poppler errors to allow CLI to offer installation
+  - Provides specific error messages for different failure types
+
+### Changed
+
+- **DOCX Export Experience**: Enhanced PDF figure embedding workflow
+  - Pre-flight check detects poppler availability before attempting conversion
+  - Caches poppler status to avoid repeated checks
+  - Shows helpful warnings with installation instructions
+  - PDF figures embed correctly when poppler is installed
+- **Homebrew Formula**: Added poppler as dependency
+  - Users installing via `brew install rxiv-maker` now get poppler automatically
+  - Ensures DOCX export works out of the box for Homebrew users
+
+## [1.16.7] - 2025-12-18
+
+### Changed
+
+- **Upgrade Workflow Centralization**: Migrated to henriqueslab-updater v1.2.0 for centralized upgrade management
+  - Simplified upgrade command implementation from 165 to 53 lines (68% reduction)
+  - Created custom `RxivUpgradeNotifier` implementing `UpgradeNotifier` protocol
+  - Integrated with existing changelog parser for rich change summaries with breaking change highlighting
+  - Maintains backward compatibility with all existing flags (`--yes`, `--check-only`)
+  - Reduces code duplication across HenriquesLab CLI tools
+  - Provides consistent upgrade UX across all HenriquesLab projects
+
 ## [1.16.6] - 2025-12-17
 
 ### Fixed

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rxiv-maker
-Version: 1.16.6
+Version: 1.16.8
 Summary: Write scientific preprints in Markdown. Generate publication-ready PDFs efficiently.
 Project-URL: Homepage, https://github.com/HenriquesLab/rxiv-maker
 Project-URL: Documentation, https://github.com/HenriquesLab/rxiv-maker#readme
@@ -27,7 +27,7 @@ Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
 Requires-Dist: crossref-commons>=0.0.7
 Requires-Dist: gitpython>=3.1.0
-Requires-Dist: henriqueslab-updater>=1.1.3
+Requires-Dist: henriqueslab-updater>=1.2.0
 Requires-Dist: latex2mathml>=3.78.0
 Requires-Dist: matplotlib>=3.7.0
 Requires-Dist: numpy>=1.24.0
@@ -358,9 +358,14 @@ rxiv config --non-interactive  # Show current settings
 
 ### Maintenance
 ```bash
-rxiv upgrade               # Upgrade to latest version
-rxiv changelog             # View changelog and release notes
-rxiv changelog --recent 5  # View last 5 versions
+# Upgrade commands (auto-detects Homebrew, pip, uv, pipx)
+rxiv upgrade                 # Interactive upgrade with confirmation
+rxiv upgrade --yes           # Upgrade without confirmation
+rxiv upgrade --check-only    # Check for updates only
+
+# Changelog and version information
+rxiv changelog               # View changelog and release notes
+rxiv changelog --recent 5    # View last 5 versions
 ```
 
 > **💡 CI/Automation Note:** All interactive commands support non-interactive mode or configuration files for use in CI/CD pipelines and automated workflows. Use `--non-interactive` flag or configure via `~/.rxiv-maker/config` for non-TTY environments.

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/README.md

@@ -281,9 +281,14 @@ rxiv config --non-interactive  # Show current settings
 
 ### Maintenance
 ```bash
-rxiv upgrade               # Upgrade to latest version
-rxiv changelog             # View changelog and release notes
-rxiv changelog --recent 5  # View last 5 versions
+# Upgrade commands (auto-detects Homebrew, pip, uv, pipx)
+rxiv upgrade                 # Interactive upgrade with confirmation
+rxiv upgrade --yes           # Upgrade without confirmation
+rxiv upgrade --check-only    # Check for updates only
+
+# Changelog and version information
+rxiv changelog               # View changelog and release notes
+rxiv changelog --recent 5    # View last 5 versions
 ```
 
 > **💡 CI/Automation Note:** All interactive commands support non-interactive mode or configuration files for use in CI/CD pipelines and automated workflows. Use `--non-interactive` flag or configure via `~/.rxiv-maker/config` for non-TTY environments.

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/pyproject.toml

@@ -53,7 +53,7 @@ dependencies = [
     "GitPython>=3.1.0",
     "prompt_toolkit>=3.0.0",
     # Update checking
-    "henriqueslab-updater>=1.1.3",
+    "henriqueslab-updater>=1.2.0",
 ]
 
 [project.urls]

rxiv_maker-1.16.8/src/docs/api/README.md

@@ -0,0 +1,4 @@
+# API Documentation
+
+Welcome to the API documentation for rxiv-maker.
+

rxiv_maker-1.16.8/src/docs/api/index.md

@@ -0,0 +1,4 @@
+# API Documentation
+
+Welcome to the API documentation for rxiv-maker.
+

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/src/rxiv_maker/__version__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "1.16.6"
+__version__ = "1.16.8"

rxiv_maker-1.16.8/src/rxiv_maker/cli/commands/docx.py

@@ -0,0 +1,177 @@
+"""DOCX export command for rxiv-maker CLI."""
+
+import platform
+import shutil
+import subprocess
+
+import rich_click as click
+from rich.console import Console
+
+from ...core.logging_config import get_logger
+from ...core.managers.dependency_manager import DependencyStatus, get_dependency_manager
+from ...exporters.docx_exporter import DocxExporter
+
+logger = get_logger()
+console = Console()
+
+
+def _check_and_offer_poppler_installation(console: Console, quiet: bool, verbose: bool) -> None:
+    """Check poppler availability and offer automatic installation via brew.
+
+    Args:
+        console: Rich console for output
+        quiet: Whether to suppress output
+        verbose: Whether verbose mode is enabled
+    """
+    # Check if poppler is installed
+    manager = get_dependency_manager()
+    result = manager.check_dependency("pdftoppm")
+
+    if result.status == DependencyStatus.AVAILABLE:
+        if verbose:
+            console.print("[dim]✓ Poppler utilities available[/dim]")
+        return
+
+    # Poppler is missing - offer to install
+    system = platform.system()
+
+    if system == "Darwin" and shutil.which("brew"):
+        # macOS with Homebrew
+        if not quiet:
+            console.print("[yellow]⚠️  Poppler not found[/yellow]")
+            console.print("   Poppler is needed to embed PDF figures in DOCX files.")
+            console.print("   Without it, PDF figures will appear as placeholders.")
+            console.print()
+
+        if click.confirm("   Would you like to install poppler now via Homebrew?", default=True):
+            console.print("[cyan]Installing poppler...[/cyan]")
+            try:
+                result = subprocess.run(
+                    ["brew", "install", "poppler"],
+                    capture_output=True,
+                    text=True,
+                    timeout=300,
+                )
+
+                if result.returncode == 0:
+                    console.print("[green]✅ Poppler installed successfully![/green]")
+                    # Clear dependency cache so it gets re-checked
+                    manager.clear_cache()
+                else:
+                    console.print(f"[red]❌ Installation failed:[/red] {result.stderr}")
+                    console.print("   You can install manually with: brew install poppler")
+            except subprocess.TimeoutExpired:
+                console.print("[red]❌ Installation timed out[/red]")
+            except Exception as e:
+                console.print(f"[red]❌ Installation error:[/red] {e}")
+        else:
+            console.print("   [dim]Skipping poppler installation. PDF figures will show as placeholders.[/dim]")
+
+    elif system == "Linux":
+        # Linux
+        if not quiet:
+            console.print("[yellow]⚠️  Poppler not found[/yellow]")
+            console.print("   Install with: sudo apt install poppler-utils")
+            console.print()
+    else:
+        # Other platforms or brew not available
+        if not quiet:
+            console.print("[yellow]⚠️  Poppler not found[/yellow]")
+            console.print(f"   Install instructions: {result.resolution_hint}")
+            console.print()
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument(
+    "manuscript_path",
+    type=click.Path(exists=True, file_okay=False),
+    required=False,
+    metavar="[MANUSCRIPT_PATH]",
+)
+@click.option(
+    "--resolve-dois",
+    "-r",
+    is_flag=True,
+    help="Attempt to resolve missing DOIs from metadata",
+)
+@click.option(
+    "--no-footnotes",
+    is_flag=True,
+    help="Disable references section (citations only)",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
+@click.option("--quiet", "-q", is_flag=True, help="Suppress non-essential output")
+def docx(
+    manuscript_path: str | None,
+    resolve_dois: bool,
+    no_footnotes: bool,
+    verbose: bool,
+    quiet: bool,
+) -> None:
+    """Export manuscript to DOCX format for collaborative review.
+
+    Generates a Word document with numbered citations, embedded figures,
+    and a complete references section with DOI links. Output is automatically
+    saved to the manuscript directory with the same naming pattern as the PDF.
+
+    **MANUSCRIPT_PATH**: Directory containing manuscript files.
+    Defaults to MANUSCRIPT/
+
+    **Output**: Automatically saved to MANUSCRIPT/YEAR__lastname_et_al__rxiv.docx
+
+    ## Examples
+
+    **Basic export:**
+
+        $ rxiv docx
+
+    **Export from custom directory:**
+
+        $ rxiv docx MY_PAPER/
+
+    **With DOI resolution for missing entries:**
+
+        $ rxiv docx --resolve-dois
+
+    **Without references section (citations only):**
+
+        $ rxiv docx --no-footnotes
+    """
+    try:
+        # Configure logging
+        if verbose:
+            logger.set_level("DEBUG")
+        elif quiet:
+            logger.set_level("WARNING")
+
+        # Set manuscript path
+        manuscript_path = manuscript_path or "MANUSCRIPT"
+
+        # Create exporter
+        if not quiet:
+            console.print("[cyan]📄 Exporting manuscript to DOCX...[/cyan]")
+
+        exporter = DocxExporter(
+            manuscript_path=manuscript_path,
+            resolve_dois=resolve_dois,
+            include_footnotes=not no_footnotes,
+        )
+
+        # Pre-flight check for poppler (if manuscript contains PDF figures)
+        _check_and_offer_poppler_installation(console, quiet, verbose)
+
+        # Perform export
+        docx_path = exporter.export()
+
+        # Success message
+        if not quiet:
+            console.print(f"[green]✅ DOCX exported:[/green] {docx_path}")
+
+    except FileNotFoundError as e:
+        console.print(f"[red]❌ Error:[/red] {e}")
+        raise click.Abort() from e
+    except Exception as e:
+        if verbose:
+            logger.error(f"DOCX export failed: {e}")
+        console.print(f"[red]❌ Export failed:[/red] {e}")
+        raise click.Abort() from e

rxiv_maker-1.16.8/src/rxiv_maker/cli/commands/upgrade.py

@@ -0,0 +1,52 @@
+"""Upgrade command for rxiv-maker CLI."""
+
+import sys
+
+import click
+from henriqueslab_updater import handle_upgrade_workflow
+from rich.console import Console
+
+from ... import __version__
+from ...utils.install_detector import detect_install_method
+from ...utils.rich_upgrade_notifier import RxivUpgradeNotifier
+
+console = Console()
+
+
+@click.command()
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+@click.option("--check-only", "-c", is_flag=True, help="Only check for updates, don't upgrade")
+@click.pass_context
+def upgrade(ctx: click.Context, yes: bool, check_only: bool) -> None:
+    """Upgrade rxiv-maker to the latest version.
+
+    This command automatically detects how rxiv-maker was installed
+    (Homebrew, pip, uv, pipx, etc.) and runs the appropriate upgrade command.
+
+    Examples:
+        rxiv upgrade              # Check and upgrade with confirmation
+        rxiv upgrade --yes        # Upgrade without confirmation
+        rxiv upgrade --check-only # Only check for updates
+    """
+    # Handle development installations specially
+    install_method = detect_install_method()
+    if install_method == "dev":
+        console.print("⚠️  Development installation detected", style="yellow")
+        console.print("   To update, pull the latest changes from git:", style="yellow")
+        console.print("   [cyan]cd <repo> && git pull && uv sync[/cyan]", style="yellow")
+        sys.exit(0)
+
+    # Use centralized upgrade workflow
+    notifier = RxivUpgradeNotifier(console)
+    success, error = handle_upgrade_workflow(
+        package_name="rxiv-maker",
+        current_version=__version__,
+        check_only=check_only,
+        skip_confirmation=yes,
+        notifier=notifier,
+        github_org="HenriquesLab",
+        github_repo="rxiv-maker",
+    )
+
+    if not success and error:
+        sys.exit(1)

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/src/rxiv_maker/core/managers/dependency_manager.py

@@ -487,6 +487,18 @@ class DependencyManager:
                 )
             )
 
+        # Poppler utilities for PDF to image conversion (DOCX export)
+        self.register_dependency(
+            DependencySpec(
+                name="pdftoppm",
+                type=DependencyType.SYSTEM_BINARY,
+                required=False,  # Only needed for DOCX export with PDF figures
+                alternatives=["pdfinfo"],
+                contexts={"docx", "export"},
+                install_hint="macOS: brew install poppler | Linux: sudo apt install poppler-utils",
+            )
+        )
+
     def register_dependency(self, spec: DependencySpec) -> None:
         """Register a dependency specification.
 

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/src/rxiv_maker/exporters/docx_exporter.py

@@ -318,9 +318,13 @@ class DocxExporter:
             # Get DOI from entry
             doi = entry.fields.get("doi")
 
-            # TODO: Implement DOI resolution if requested and DOI missing
-            # if self.resolve_dois and not doi:
-            #     doi = self._resolve_doi_from_metadata(entry)
+            # Attempt DOI resolution if requested and DOI missing
+            if self.resolve_dois and not doi:
+                doi = self._resolve_doi_from_metadata(entry)
+                if doi:
+                    # Store in entry for this export
+                    entry.fields["doi"] = doi
+                    logger.info(f"Resolved DOI for {key}: {doi}")
 
             # Format entry (full format for DOCX bibliography)
             formatted = format_bibliography_entry(entry, doi, slim=False, author_format=self.author_format)
@@ -332,6 +336,99 @@ class DocxExporter:
 
         return bibliography
 
+    def _resolve_doi_from_metadata(self, entry) -> str | None:
+        """Resolve DOI from entry metadata using CrossRef API.
+
+        Args:
+            entry: Bibliography entry to resolve DOI for
+
+        Returns:
+            Resolved DOI if found, None otherwise
+        """
+        import requests
+
+        # Try to construct a search query from available fields
+        title = entry.fields.get("title", "").strip()
+        year = entry.fields.get("year", "").strip()
+
+        if not title:
+            logger.debug(f"Cannot resolve DOI for {entry.key}: no title")
+            return None
+
+        # Clean title for search (remove LaTeX commands, braces, etc.)
+        search_title = self._clean_title_for_search(title)
+
+        # Try CrossRef search API
+        try:
+            url = "https://api.crossref.org/works"
+            params = {
+                "query.title": search_title,
+                "rows": 5,  # Get top 5 results
+            }
+
+            response = requests.get(url, params=params, timeout=10)
+
+            if response.status_code == 200:
+                data = response.json()
+                items = data.get("message", {}).get("items", [])
+
+                # Find best match
+                for item in items:
+                    item_title = item.get("title", [""])[0].lower()
+                    search_title_lower = search_title.lower()
+
+                    # Simple similarity check - titles should be very similar
+                    if item_title and (search_title_lower in item_title or item_title in search_title_lower):
+                        # Verify year matches if available
+                        if year:
+                            item_year = item.get("published", {}).get("date-parts", [[None]])[0][0]
+                            if item_year and str(item_year) != year:
+                                continue
+
+                        doi = item.get("DOI")
+                        if doi:
+                            logger.info(f"Resolved DOI for {entry.key}: {doi}")
+                            return doi
+
+            logger.debug(f"Could not resolve DOI for {entry.key} via CrossRef")
+            return None
+
+        except requests.exceptions.Timeout:
+            logger.debug(f"CrossRef API timeout resolving DOI for {entry.key}")
+            return None
+        except requests.exceptions.ConnectionError:
+            logger.debug(f"CrossRef API connection error for {entry.key}")
+            return None
+        except Exception as e:
+            logger.debug(f"Error resolving DOI for {entry.key}: {e}")
+            return None
+
+    def _clean_title_for_search(self, title: str) -> str:
+        """Clean title for CrossRef search by removing LaTeX commands.
+
+        Args:
+            title: Raw title from BibTeX entry
+
+        Returns:
+            Cleaned title suitable for search
+        """
+        import re
+
+        # Remove LaTeX commands
+        title = re.sub(r"\\[a-zA-Z]+\{([^}]*)\}", r"\1", title)  # \textit{foo} -> foo
+        title = re.sub(r"\\[a-zA-Z]+", "", title)  # \LaTeX -> LaTeX
+
+        # Remove braces
+        title = title.replace("{", "").replace("}", "")
+
+        # Remove special characters
+        title = re.sub(r"[^a-zA-Z0-9\s\-]", " ", title)
+
+        # Normalize whitespace
+        title = " ".join(title.split())
+
+        return title.strip()
+
     def _get_metadata(self) -> Dict[str, Any]:
         """Extract metadata for title page.
 

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/src/rxiv_maker/exporters/docx_writer.py

@@ -404,6 +404,19 @@ class DocxWriter:
         paragraph_format = paragraph.paragraph_format
         paragraph_format.left_indent = Pt(36)  # Indent code blocks
 
+    def _check_poppler_availability(self) -> bool:
+        """Check if poppler is available for PDF conversion.
+
+        Returns:
+            True if poppler is available, False otherwise
+        """
+        from ..core.managers.dependency_manager import DependencyStatus, get_dependency_manager
+
+        manager = get_dependency_manager()
+        result = manager.check_dependency("pdftoppm")
+
+        return result.status == DependencyStatus.AVAILABLE
+
     def _add_figure(self, doc: Document, section: Dict[str, Any], figure_number: int = None):
         """Add figure to document with caption.
 
@@ -425,9 +438,31 @@ class DocxWriter:
         if not figure_path.exists():
             logger.warning(f"Figure file not found: {figure_path}")
         elif figure_path.suffix.lower() == ".pdf":
-            # Convert PDF to image
-            img_source = convert_pdf_to_image(figure_path)
-            logger.debug(f"  PDF converted: {img_source is not None}")
+            # Check poppler availability first (cached after first check)
+            if not hasattr(self, "_poppler_checked"):
+                self._poppler_available = self._check_poppler_availability()
+                self._poppler_checked = True
+
+                if not self._poppler_available:
+                    logger.warning(
+                        "Poppler not installed - PDF figures will be shown as placeholders. "
+                        "Install with: brew install poppler (macOS) or sudo apt install poppler-utils (Linux)"
+                    )
+
+            if self._poppler_available:
+                # Convert PDF to image
+                try:
+                    from pdf2image.exceptions import PDFInfoNotInstalledError, PopplerNotInstalledError
+
+                    img_source = convert_pdf_to_image(figure_path)
+                    logger.debug(f"  PDF converted: {img_source is not None}")
+                except (PopplerNotInstalledError, PDFInfoNotInstalledError) as e:
+                    logger.error(f"Poppler utilities not found: {e}")
+                    img_source = None
+                    # Update our cached status
+                    self._poppler_available = False
+            else:
+                img_source = None
         elif figure_path.suffix.lower() in [".png", ".jpg", ".jpeg", ".gif", ".bmp"]:
             # Use image file directly
             img_source = str(figure_path)

{rxiv_maker-1.16.6 → rxiv_maker-1.16.8}/src/rxiv_maker/utils/bst_generator.py

@@ -81,21 +81,41 @@ def generate_bst_file(format_type: str, output_dir: Path) -> Path:
     except IOError as e:
         raise IOError(f"Failed to read template .bst file: {e}") from e
 
-    # Replace the format string on line 222
+    # Replace the format string in the format.names function (line ~222)
     # The line looks like: s nameptr "{ff~}{vv~}{ll}{, jj}" format.name$ 't :=
-    # We need to replace the format string in quotes
-    pattern = r'(s\s+nameptr\s+")([^"]+)("\s+format\.name\$)'
+    # We need to replace ONLY in format.names, NOT in format.full.names
+    #
+    # Strategy: Match the FUNCTION {format.names} block specifically
+    # This ensures we don't modify format.full.names which is used for citation labels
+    #
+    # Pattern explanation:
+    # 1. Match "FUNCTION {format.names}" to find the start of the function
+    # 2. Use non-greedy match (.*?) to capture until we find our target line
+    # 3. Match and capture the format string in quotes
+    # 4. This avoids matching format.full.names which appears later in the file
+    pattern = r'(FUNCTION\s+\{format\.names\}.*?s\s+nameptr\s+")([^"]+)("\s+format\.name\$)'
     replacement = rf"\1{format_string}\3"
 
-    modified_content, num_subs = re.subn(pattern, replacement, bst_content)
+    modified_content, num_subs = re.subn(pattern, replacement, bst_content, flags=re.DOTALL)
 
     if num_subs == 0:
-        logger.warning("No format string pattern found in .bst file. The .bst file may have been modified.")
+        logger.warning(
+            "No format string pattern found in format.names function. "
+            "The .bst file structure may have changed. "
+            "Citation formatting may not work as expected."
+        )
         # Still write the file but log a warning
     elif num_subs > 1:
-        logger.warning(
-            f"Found {num_subs} format string patterns in .bst file. Expected only 1. All have been replaced."
+        # This should never happen with the new pattern, but keep the check
+        logger.error(
+            f"Found {num_subs} matches in .bst file. Expected exactly 1. "
+            "This indicates an unexpected .bst file structure. "
+            "Please report this issue."
         )
+        raise ValueError(f"Unexpected .bst file structure: found {num_subs} matches for format.names, expected 1")
+    else:
+        # Success - exactly one match
+        logger.debug(f"Successfully updated format.names function with format '{format_type}'")
 
     # Create output directory if it doesn't exist
     output_dir = Path(output_dir)