Ruby Script Analysis and Decomposition Guide

Initial Analysis Phase

1. Identify Script Purpose and Dependencies

   • What is the primary responsibility of this script?
   • What external gems or libraries does it require?
   • What system dependencies or external tools does it use?
   • Document any configuration or environment variables used

2. Data Structure Analysis

   • List all classes and modules defined in the script
   • Identify all data structures (hashes, arrays, custom objects)
   • Note any database or file system interactions
   • Document any global or class-level variables

3. Functional Analysis

   • List all methods and their primary responsibilities
   • Group methods by their domain/purpose
   • Identify shared functionality between methods
   • Note any side effects of each method

4. Dependency Flow

   • Map data flow between methods
   • Identify method call hierarchies
   • Document any circular dependencies
   • Note any external service calls

Decomposition Planning

5. Module Identification

   • Group related functionality into potential modules:
     • Data access/persistence logic
     • Business logic
     • External service interactions
     • Utility functions
     • Configuration management
     • Validation logic

6. Interface Definition

   • For each proposed module:
     • Define public methods
     • Document required inputs
     • Specify expected outputs
     • List error conditions
     • Note any side effects

7. File Organization

   • For each module, create a file structure:

     lib/
     ├── domain_name/
     │   ├── data_access.rb
     │   ├── business_logic.rb
     │   ├── service_client.rb
     │   └── validators.rb
     ├── utilities/
     │   └── helpers.rb
     └── configuration/
         └── settings.rb
     

Implementation Guidelines

8. Extraction Process

   • For each identified module:
     1. Create new file with appropriate name
     2. Copy relevant methods and dependencies
     3. Add necessary requires/imports
     4. Update method visibility (public/private)
     5. Add module documentation
     6. Add method documentation

9. Integration Requirements

   • Update original script to:
     • Require new module files
     • Initialize necessary objects
     • Handle any new error conditions
     • Maintain existing public interfaces

10. Validation Checklist

    • All dependencies are properly required
    • No unused methods remain
    • No duplicate code exists
    • Public interfaces are documented
    • Error handling is consistent
    • Tests are updated/created

Example Analysis Template

# Script Analysis: [filename.rb]

## Overview
- Primary purpose:
- Current dependencies:
- Environment requirements:

## Data Structures
- Classes:
- Modules:
- Key data structures:
- External data interactions:

## Methods
### Group 1: [Purpose]
- Method 1:
  - Inputs:
  - Outputs:
  - Dependencies:
  - Side effects:

### Group 2: [Purpose]
[...]

## Proposed Modules
1. Module Name: [name]
   - Purpose:
   - Methods:
   - Dependencies:
   - New filename:

2. Module Name: [name]
   [...]

## Integration Notes
- Required updates:
- Risk areas:
- Testing requirements:

Refactoring Example

Original script structure:

# process_book.rb
class BookProcessor
  def initialize(file)
    @file = file
    @config = load_config
  end
  
  def process
    validate_file
    convert_format
    optimize_images
    generate_output
  end
  
  private
  
  def load_config
    # config loading logic
  end
  
  def validate_file
    # validation logic
  end
  
  def convert_format
    # conversion logic
  end
  
  def optimize_images
    # image optimization
  end
  
  def generate_output
    # output generation
  end
end

Decomposed structure:

# lib/book_processing/config_loader.rb
module BookProcessing
  class ConfigLoader
    def self.load(file)
      # config loading logic
    end
  end
end

# lib/book_processing/validator.rb
module BookProcessing
  class Validator
    def self.validate(file)
      # validation logic
    end
  end
end

# lib/book_processing/converter.rb
module BookProcessing
  class Converter
    def self.convert(file, format)
      # conversion logic
    end
  end
end

# lib/book_processing/image_optimizer.rb
module BookProcessing
  class ImageOptimizer
    def self.optimize(images)
      # image optimization
    end
  end
end

# lib/book_processing/output_generator.rb
module BookProcessing
  class OutputGenerator
    def self.generate(data)
      # output generation
    end
  end
end

# process_book.rb
require_relative 'lib/book_processing/config_loader'
require_relative 'lib/book_processing/validator'
require_relative 'lib/book_processing/converter'
require_relative 'lib/book_processing/image_optimizer'
require_relative 'lib/book_processing/output_generator'

class BookProcessor
  def initialize(file)
    @file = file
    @config = BookProcessing::ConfigLoader.load(file)
  end
  
  def process
    BookProcessing::Validator.validate(@file)
    BookProcessing::Converter.convert(@file, @config.format)
    BookProcessing::ImageOptimizer.optimize(@file.images)
    BookProcessing::OutputGenerator.generate(@file)
  end
end

The next script to audit is