Ruby Scripts Audit and Refactoring Plan

Project Overview

The elib-a-fuller-explanation project is a Ruby-based ebook conversion system that transforms LaTeX manuscripts into various ebook formats (PDF, EPUB, etc.). Based on the replatforming document, the long-term goal is to migrate this system to Elixir to leverage concurrency, fault tolerance, and other OTP benefits.

Before migration, we need to audit the current Ruby scripts to ensure they function correctly, then refactor them to make the transition to Elixir smoother.

1. Scripts Inventory

Here's an inventory of the Ruby scripts we need to audit:

Main Scripts (src/scripts)

• book_deployer.rb - Handles book deployment
• build_ebooks.rb - Main script for building ebooks in different formats
• ebook_validator.rb - Validates generated ebooks
• export_to_markdown.rb - Converts book content to markdown
• latex_checker.rb - Checks LaTeX syntax and structure
• latex_to_pandoc_converter.rb - Converts LaTeX to Pandoc format
• latex_to_wikijs.rb - Converts LaTeX to WikiJS format
• latex_validator.rb - Validates LaTeX content
• metadata_loader.rb - Loads and processes book metadata
• prepare_for_wikijs.rb - Prepares content for WikiJS
• upload_to_trimtab_book_club.rb - Uploads content to book club platform

Utility Scripts (src/scripts/utils)

• aws_upload.rb - Uploads files to AWS
• convert_gif_to_png.rb - Converts GIF images to PNG
• cover_converter.rb - Processes book covers
• docx_to_tex_converter.rb - Converts DOCX to LaTeX
• fix_file_name_case.rb - Fixes file name casing
• fix_section_case.rb - Fixes section title casing
• generate_cover_svg.rb - Generates SVG covers
• image_processor.rb - Processes book images
• rename_jpeg.rb - Renames JPEG files
• setup_project.rb - Sets up project structure
• setup_tools.rb - Sets up required tools
• split_md_into_chapters.rb - Splits markdown into chapters
• sync_scans_to_s3.rb - Syncs scans to S3
• test_meta.rb - Tests metadata functionality
• update_ebook_system.rb - Updates ebook system
• update_latex_tools.rb - Updates LaTeX tools
• update_meta.rb - Updates metadata

Refactored Scripts

The latest refactored ruby classes and modules are in lib/

2. Audit Process

For each script, we'll perform the following checks:

1. Functionality Verification:

   • Confirm the script runs without errors
   • Verify the script performs its intended function
   • Document any runtime warnings or deprecation notices

2. Code Quality Assessment:

   • Check error handling practices
   • Assess logging adequacy
   • Review hardcoded values or paths
   • Analyze code organization and readability
   • Identify any performance bottlenecks

3. Dependency Analysis:

   • Document external dependencies (gems, system tools)
   • Map dependencies between scripts
   • Identify potentially outdated or unnecessary dependencies

4. Test Coverage:

   • Check existing tests (if any)
   • Document areas lacking test coverage
   • Note test execution issues

3. Refactoring Strategy

Based on the audit findings, we'll refactor the Ruby scripts with these goals:

1. Improve Modularity:

   • Extract reusable functionality into proper classes/modules
   • Group related functionality
   • Move hardcoded values to configuration files

2. Enhance Testing:

   • Add missing tests
   • Improve test coverage
   • Make tests more robust

3. Streamline Dependencies:

   • Update outdated dependencies
   • Remove unnecessary dependencies
   • Standardize dependency management

4. Improve Error Handling:

   • Implement consistent error handling patterns
   • Add better error reporting
   • Improve recovery mechanisms

5. Enhance Logging:

   • Standardize logging
   • Ensure appropriate log levels
   • Add context to log entries

6. Fix Path Management:

   • Eliminate hardcoded paths
   • Use relative paths consistently
   • Centralize path configuration

7. Add Documentation:

   • Add/update inline documentation
   • Create overview documentation for each script
   • Document interdependencies

4. Execution Plan

Phase 1: Initial Audit (2 weeks)

• Create audit templates for consistency
• Perform basic functionality tests for all scripts
• Document immediate issues and dependencies
• Set up testing environment
• Produce initial audit report

Phase 2: Deep Audit (2 weeks)

• Review code quality in detail
• Analyze script interactions
• Identify common patterns and shared functionality
• Map full dependency graph
• Prioritize refactoring tasks

Phase 3: Refactoring (3-4 weeks)

• Implement code improvements based on audit findings
• Extract common functionality into shared libraries
• Improve error handling and logging
• Enhance test coverage
• Fix identified bugs

Phase 4: Validation (1-2 weeks)

• Verify all scripts function correctly after refactoring
• Run end-to-end tests
• Document remaining issues or limitations
• Prepare final report with recommendations for Elixir migration

5. Elixir Migration Preparation

As part of the refactoring process, we'll prepare for Elixir migration by:

1. Identifying Ruby-specific code that will need special attention during migration
2. Mapping Ruby classes/modules to potential Elixir modules
3. Noting areas where OTP features can provide significant improvements
4. Documenting Ruby patterns that would benefit from Elixir's functional approach
5. Planning for potential parallel operation during transition

6. Tools and Resources

For the audit and refactoring process, we'll use:

• RuboCop: Static code analysis and style checking
• SimpleCov: Test coverage analysis
• Yard: Documentation generation
• Pry: Interactive debugging
• RSpec: Testing framework
• Git: Version control with branching strategy for safe refactoring

7. Next Steps

1. Set up a shared project management board to track audit and refactoring progress
2. Create audit templates and checklists
3. Begin with the core scripts that other scripts depend on
4. Prioritize scripts based on complexity and dependency relationships
5. Establish regular check-ins to assess progress and adjust priorities

Appendix: Script Dependency Map

A preliminary map of script dependencies based on initial analysis:

build_ebooks.rb
  ├── metadata_handler.rb
  ├── book_processing/builders/pdf_builder.rb
  ├── book_processing/builders/ebook_formats_builder.rb
  ├── book_processing/converters/latex_to_wikijs.rb
  └── book_processing/quality_checker.rb

setup_tools.rb
  ├── system/validator.rb
  ├── config/package_definitions.rb
  ├── package_managers/homebrew_manager.rb
  ├── package_managers/tex_manager.rb
  └── package_managers/kindle_manager.rb
  
[Additional dependencies to be mapped during audit]

This dependency map will be expanded and refined during the audit process.