equilibrium 0.1.1 → 0.3.0

data/lib/equilibrium/cli.rb

@@ -1,218 +1,55 @@
 # frozen_string_literal: true
 
 require "thor"
-require "json"
-require_relative "../equilibrium"
-require_relative "schema_validator"
-require_relative "schemas/expected_actual"
-require_relative "summary_formatter"
+require_relative "commands/analyze_command"
+require_relative "commands/expected_command"
+require_relative "commands/actual_command"
+require_relative "commands/catalog_command"
+require_relative "commands/uncatalog_command"
+require_relative "commands/version_command"
 
 module Equilibrium
+  # Main CLI class - acts as a router to individual command classes
+  # Each command delegates to its respective command class for execution
   class CLI < Thor
     def self.exit_on_failure?
       true
     end
 
-    desc "analyze", "Compare expected vs actual tags and generate remediation plan"
+    desc "analyze", "Compare expected vs actual tags and show analysis report"
     option :expected, type: :string, required: true, desc: "Expected tags JSON file"
     option :actual, type: :string, required: true, desc: "Actual tags JSON file"
     option :registry, type: :string, desc: "Repository URL for output"
     option :format, type: :string, default: "summary", enum: ["json", "summary"], desc: "Output format"
     def analyze
-      # Load and validate data files
-      expected_data = load_and_validate_json_file(options[:expected])
-      actual_data = load_and_validate_json_file(options[:actual])
-
-      analyzer = Analyzer.new
-      analysis = analyzer.analyze(expected_data, actual_data)
-
-      case options[:format]
-      when "json"
-        puts JSON.pretty_generate(analysis)
-      when "summary"
-        formatter = SummaryFormatter.new
-        formatter.print_analysis_summary(analysis)
-      end
-    rescue => e
-      error_and_exit(e.message)
+      Commands::AnalyzeCommand.new.execute(options)
     end
 
     desc "expected REPOSITORY_URL", "Output expected mutable tags to stdout"
     option :format, type: :string, default: "summary", enum: ["json", "summary"], desc: "Output format"
     def expected(registry)
-      client = RegistryClient.new
-      processor = TagProcessor.new
-
-      full_repository_url = validate_repository_url(registry)
-      all_tags = client.list_tags(full_repository_url)
-      semantic_tags = processor.filter_semantic_tags(all_tags)
-      virtual_tags_result = processor.compute_virtual_tags(semantic_tags)
-
-      # Extract repository name from URL
-      repository_name = extract_repository_name(full_repository_url)
-
-      # Sort both digests and canonical_versions in descending order right before output
-      sorted_digests = TagSorter.sort_descending(virtual_tags_result["digests"])
-      sorted_canonical_versions = TagSorter.sort_descending(virtual_tags_result["canonical_versions"])
-
-      output = {
-        "repository_url" => full_repository_url,
-        "repository_name" => repository_name,
-        "digests" => sorted_digests,
-        "canonical_versions" => sorted_canonical_versions
-      }
-
-      # Validate output against schema before writing
-      validate_expected_actual_schema(output)
-
-      case options[:format]
-      when "json"
-        puts JSON.pretty_generate(output)
-      when "summary"
-        formatter = SummaryFormatter.new
-        formatter.print_tags_summary(output, "expected")
-      end
-    rescue Thor::Error
-      raise  # Let Thor::Error bubble up for validation errors
-    rescue RegistryClient::Error => e
-      raise StandardError, e.message  # Convert for test compatibility
-    rescue => e
-      error_and_exit(e.message)
+      Commands::ExpectedCommand.new.execute(registry, options)
     end
 
     desc "actual REPOSITORY_URL", "Output actual mutable tags to stdout"
     option :format, type: :string, default: "summary", enum: ["json", "summary"], desc: "Output format"
     def actual(registry)
-      client = RegistryClient.new
-      processor = TagProcessor.new
-
-      full_repository_url = validate_repository_url(registry)
-      all_tags = client.list_tags(full_repository_url)
-      mutable_tags = processor.filter_mutable_tags(all_tags)
-
-      # Get semantic tags to create canonical mapping for actual mutable tags
-      semantic_tags = processor.filter_semantic_tags(all_tags)
-      canonical_versions = {}
-
-      # For each actual mutable tag, find its canonical version by digest matching
-      mutable_tags.each do |mutable_tag, digest|
-        # Find semantic tag with same digest
-        canonical_version = semantic_tags.find { |_, sem_digest| sem_digest == digest }&.first
-        canonical_versions[mutable_tag] = canonical_version if canonical_version
-      end
-
-      # Extract repository name from URL
-      repository_name = extract_repository_name(full_repository_url)
-
-      # Sort both digests and canonical_versions in descending order right before output
-      sorted_digests = TagSorter.sort_descending(mutable_tags)
-      sorted_canonical_versions = TagSorter.sort_descending(canonical_versions)
-
-      output = {
-        "repository_url" => full_repository_url,
-        "repository_name" => repository_name,
-        "digests" => sorted_digests,
-        "canonical_versions" => sorted_canonical_versions
-      }
-
-      # Validate output against schema before writing
-      validate_expected_actual_schema(output)
-
-      case options[:format]
-      when "json"
-        puts JSON.pretty_generate(output)
-      when "summary"
-        formatter = SummaryFormatter.new
-        formatter.print_tags_summary(output, "actual")
-      end
-    rescue Thor::Error
-      raise  # Let Thor::Error bubble up for validation errors
-    rescue RegistryClient::Error => e
-      raise StandardError, e.message  # Convert for test compatibility
-    rescue => e
-      error_and_exit(e.message)
+      Commands::ActualCommand.new.execute(registry, options)
     end
 
     desc "catalog [FILE]", "Convert expected tags JSON to catalog format (reads from file or stdin)"
     def catalog(file_path = nil)
-      # Read from file or stdin
-      if file_path
-        unless File.exist?(file_path)
-          error_and_exit("File not found: #{file_path}")
-        end
-        input = File.read(file_path).strip
-      else
-        input = $stdin.read.strip
-        if input.empty?
-          error_and_exit("No input provided. Use: equilibrium expected registry | equilibrium catalog")
-        end
-      end
-
-      data = JSON.parse(input)
-
-      # Validate against expected/actual schema
-      validate_expected_actual_schema(data)
-
-      builder = CatalogBuilder.new
-      catalog = builder.build_catalog(data)
+      Commands::CatalogCommand.new.execute(file_path)
+    end
 
-      puts JSON.pretty_generate(catalog)
-    rescue JSON::ParserError => e
-      error_and_exit("Invalid JSON input: #{e.message}")
-    rescue => e
-      error_and_exit(e.message)
+    desc "uncatalog [FILE]", "Convert catalog format back to expected/actual format (reads from file or stdin)"
+    def uncatalog(file_path = nil)
+      Commands::UncatalogCommand.new.execute(file_path)
     end
 
     desc "version", "Show version information"
     def version
-      say "Equilibrium v#{Equilibrium::VERSION}"
-      say "Container tag validation tool"
-    end
-
-    private
-
-    def load_and_validate_json_file(file_path)
-      unless File.exist?(file_path)
-        raise "File not found: #{file_path}"
-      end
-
-      data = JSON.parse(File.read(file_path))
-      validate_expected_actual_schema(data)
-      data
-    rescue JSON::ParserError => e
-      raise "Invalid JSON in #{file_path}: #{e.message}"
-    end
-
-    def validate_repository_url(repository_url)
-      # Repository URL must include registry host, project/namespace, and image name
-      # Format: [REGISTRY_HOST]/[PROJECT_OR_NAMESPACE]/[IMAGE_NAME]
-      unless repository_url.include?("/")
-        raise Thor::Error, "Repository URL must be full format (e.g., 'gcr.io/project-id/image-name'), not '#{repository_url}'"
-      end
-
-      repository_url
-    end
-
-    def extract_repository_name(repository_url)
-      # Extract repository name from repository URL
-      # Examples:
-      #   gcr.io/project-id/repository-name -> repository-name
-      #   registry.com/namespace/repository-name -> repository-name
-      repository_url.split("/").last
-    end
-
-    def validate_expected_actual_schema(data)
-      SchemaValidator.validate!(data, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: "Schema validation failed")
-    rescue SchemaValidator::ValidationError => e
-      error_and_exit(e.message)
-    end
-
-    def error_and_exit(message, usage = nil)
-      error message
-      if usage
-        say usage, :red
-      end
-      exit 1
+      Commands::VersionCommand.execute
     end
   end
 end

data/lib/equilibrium/commands/actual_command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../mixins/error_handling"
+require_relative "../mixins/input_output"
+require_relative "../repository_url_validator"
+require_relative "../schema_validator"
+require_relative "../schemas/expected_actual"
+require_relative "../tags_operation_service"
+
+module Equilibrium
+  module Commands
+    # Command for generating actual mutable tags from registry
+    class ActualCommand
+      include Mixins::ErrorHandling
+      include Mixins::InputOutput
+
+      # Execute the actual command
+      # @param registry [String] Repository URL
+      # @param options [Hash] Command options (format, etc.)
+      def execute(registry, options = {})
+        with_error_handling do
+          full_repository_url = RepositoryUrlValidator.validate(registry)
+
+          # Generate complete actual output using high-level service
+          output = TagsOperationService.generate_actual_output(full_repository_url)
+
+          # Validate output against schema before writing
+          SchemaValidator.validate!(output, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: "Schema validation failed")
+
+          # Format and display output
+          format_output(output, options[:format] || "summary", "actual")
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/commands/analyze_command.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../mixins/error_handling"
+require_relative "../mixins/input_output"
+require_relative "../schema_validator"
+require_relative "../schemas/expected_actual"
+require_relative "../schemas/analyzer_output"
+require_relative "../analyzer"
+
+module Equilibrium
+  module Commands
+    # Command for analyzing expected vs actual tags with unified structure
+    class AnalyzeCommand
+      include Mixins::ErrorHandling
+      include Mixins::InputOutput
+
+      # Execute the analyze command
+      # @param options [Hash] Command options (expected, actual, format, etc.)
+      def execute(options = {})
+        with_error_handling do
+          # Load and validate data files
+          expected_data = load_and_validate_json_file(options[:expected], error_prefix: "Expected data schema validation failed")
+          actual_data = load_and_validate_json_file(options[:actual], error_prefix: "Actual data schema validation failed")
+
+          # Perform analysis
+          analysis = Analyzer.analyze(expected_data, actual_data)
+
+          # Validate output schema
+          SchemaValidator.validate!(analysis, Equilibrium::Schemas::ANALYZER_OUTPUT, error_prefix: "Analyzer output schema validation failed")
+
+          # Format and display output
+          format_output(analysis, options[:format] || "summary", "analysis")
+        end
+      end
+
+      private
+
+      def load_and_validate_json_file(file_path, error_prefix:)
+        raise "File not found: #{file_path}" unless File.exist?(file_path)
+
+        JSON.parse(File.read(file_path)).tap do |json|
+          SchemaValidator.validate!(json, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: error_prefix)
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/commands/catalog_command.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../mixins/error_handling"
+require_relative "../mixins/input_output"
+require_relative "../schema_validator"
+require_relative "../schemas/expected_actual"
+require_relative "../catalog_builder"
+
+module Equilibrium
+  module Commands
+    # Command for converting expected tags JSON to catalog format
+    class CatalogCommand
+      include Mixins::ErrorHandling
+      include Mixins::InputOutput
+
+      # Execute the catalog command
+      # @param file_path [String, nil] Optional file path, uses stdin if nil
+      def execute(file_path = nil)
+        with_error_handling do
+          # Read input from file or stdin
+          input = read_input_data(file_path, "No input provided. Use: equilibrium expected registry | equilibrium catalog")
+
+          # Parse and validate JSON
+          data = JSON.parse(input)
+          SchemaValidator.validate!(data, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: "Schema validation failed")
+
+          # Convert to catalog format
+          catalog = CatalogBuilder.build_catalog(data)
+
+          # Output as JSON
+          puts JSON.pretty_generate(catalog)
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/commands/expected_command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../mixins/error_handling"
+require_relative "../mixins/input_output"
+require_relative "../repository_url_validator"
+require_relative "../schema_validator"
+require_relative "../schemas/expected_actual"
+require_relative "../tags_operation_service"
+
+module Equilibrium
+  module Commands
+    # Command for generating expected mutable tags based on semantic versions
+    class ExpectedCommand
+      include Mixins::ErrorHandling
+      include Mixins::InputOutput
+
+      # Execute the expected command
+      # @param registry [String] Repository URL
+      # @param options [Hash] Command options (format, etc.)
+      def execute(registry, options = {})
+        with_error_handling do
+          full_repository_url = RepositoryUrlValidator.validate(registry)
+
+          # Generate complete expected output using high-level service
+          output = TagsOperationService.generate_expected_output(full_repository_url)
+
+          # Validate output against schema before writing
+          SchemaValidator.validate!(output, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: "Schema validation failed")
+
+          # Format and display output
+          format_output(output, options[:format] || "summary", "expected")
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/commands/uncatalog_command.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../mixins/error_handling"
+require_relative "../mixins/input_output"
+require_relative "../schema_validator"
+require_relative "../schemas/catalog"
+require_relative "../schemas/expected_actual"
+require_relative "../catalog_builder"
+
+module Equilibrium
+  module Commands
+    # Command for converting catalog format back to expected/actual format
+    class UncatalogCommand
+      include Mixins::ErrorHandling
+      include Mixins::InputOutput
+
+      # Execute the uncatalog command
+      # @param file_path [String, nil] Optional file path, uses stdin if nil
+      def execute(file_path = nil)
+        with_error_handling do
+          # Read input from file or stdin
+          input = read_input_data(file_path, "No input provided. Use: equilibrium catalog registry | equilibrium uncatalog")
+
+          # Parse and validate JSON
+          data = JSON.parse(input)
+          SchemaValidator.validate!(data, Equilibrium::Schemas::CATALOG, error_prefix: "Catalog schema validation failed")
+
+          # Convert back to expected/actual format
+          result = CatalogBuilder.reverse_catalog(data)
+
+          # Validate output before printing
+          SchemaValidator.validate!(result, Equilibrium::Schemas::EXPECTED_ACTUAL, error_prefix: "Output validation failed")
+
+          # Output as JSON
+          puts JSON.pretty_generate(result)
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/commands/version_command.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+module Equilibrium
+  module Commands
+    # Command for displaying version information
+    class VersionCommand
+      # Execute the version command
+      def self.execute
+        puts "Equilibrium v#{Equilibrium::VERSION}"
+        puts "Container tag validation tool"
+      end
+    end
+  end
+end

data/lib/equilibrium/mixins/error_handling.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "json"
+require "thor"
+require_relative "../schema_validator"
+
+module Equilibrium
+  module Mixins
+    # Module for consistent error handling across all commands
+    module ErrorHandling
+      def with_error_handling(&block)
+        block.call
+      rescue Thor::Error
+        raise  # Let Thor::Error bubble up for validation errors
+      rescue RegistryClient::Error => e
+        raise StandardError, e.message  # Convert for test compatibility
+      rescue SchemaValidator::ValidationError => e
+        error_and_exit(e.message)
+      rescue JSON::ParserError => e
+        error_and_exit("Invalid JSON input: #{e.message}")
+      rescue => e
+        error_and_exit(e.message)
+      end
+
+      private
+
+      # Exit with error message
+      def error_and_exit(message, usage = nil)
+        warn message
+        exit 1
+      end
+    end
+  end
+end

data/lib/equilibrium/mixins/input_output.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../summary_formatter"
+
+module Equilibrium
+  module Mixins
+    # Module for input/output operations - reading files, parsing JSON, formatting output
+    module InputOutput
+      def read_input_data(file_path = nil, usage_message = "No input provided")
+        input = file_path ? File.read(file_path) : $stdin.read
+        input = input.strip
+
+        raise usage_message if input.empty?
+        input
+      end
+
+      def format_output(data, format, summary_type = nil)
+        case format
+        when "json"
+          puts JSON.pretty_generate(data)
+        when "summary"
+          if summary_type
+            formatter = SummaryFormatter.new
+            case summary_type
+            when "expected", "actual"
+              formatter.print_tags_summary(data, summary_type)
+            when "analysis"
+              formatter.print_analysis_summary(data)
+            end
+          else
+            puts JSON.pretty_generate(data)
+          end
+        else
+          puts JSON.pretty_generate(data)
+        end
+      end
+    end
+  end
+end

data/lib/equilibrium/registry_client.rb

@@ -52,26 +52,14 @@ module Equilibrium
   class RegistryClient
     class Error < StandardError; end
 
-    def list_tags(registry)
-      url = build_api_url(registry)
-      data = fetch_tags_data(url)
-      parse_response(data)
-    end
-
-    private
-
-    def build_api_url(registry)
-      parts = registry.split("/")
-      raise Error, "Invalid GCR registry format: #{registry}" if parts.length < 3
-
-      host, project, *image = parts
+    attr_reader :uri
 
-      "https://#{host}/v2/#{project}/#{image.join("/")}/tags/list"
+    def initialize(registry)
+      @registry = registry
+      @uri = URI(build_api_url(registry))
     end
 
-    def fetch_tags_data(url)
-      uri = URI(url)
-
+    def tagged_digests
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
       http.read_timeout = 30
@@ -81,44 +69,45 @@ module Equilibrium
 
       raise Error, "API request failed: #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
 
-      data = JSON.parse(response.body)
-      validate_registry_response(data)
-      data
-    rescue JSON::ParserError => e
-      raise Error, "Invalid JSON response: #{e.message}"
-    rescue => e
-      raise Error, "Request failed: #{e.message}"
-    end
-
-    def validate_registry_response(data)
-      SchemaValidator.validate!(data, Equilibrium::Schemas::REGISTRY_API_RESPONSE, error_prefix: "Registry API response validation failed")
-    rescue SchemaValidator::ValidationError => e
-      raise Error, e.message
-    end
+      data = JSON.parse(response.body).tap do |json|
+        SchemaValidator.validate!(json, Equilibrium::Schemas::REGISTRY_API_RESPONSE, error_prefix: "Registry API response validation failed")
+      end
 
-    def parse_response(data)
       # Data is already validated by schema, safe to process
-      tags = data["tags"]
+      all_tags = data["tags"]
 
       # The 'manifest' field is a non-standard extension provided by some registries (like GCR)
       # Most registries (GHCR, Docker Hub, ECR) only return 'name' and 'tags' per Docker Registry v2 spec
       # When manifest data is missing, digest information is not available from the tags endpoint
-      tag_to_digest = build_digest_mapping(data["manifest"] || {})
+      manifests = data.fetch("manifest")
 
-      tags.each_with_object({}) do |tag, result|
-        # Map tags to their digests. For registries without manifest data, digest will be nil
-        # This is expected behavior - digest info requires separate manifest API calls per tag
-        result[tag] = tag_to_digest[tag]
-      end
-    end
-
-    def build_digest_mapping(manifests)
       # Build mapping from tag names to their SHA256 digests
       # Only works when registry provides non-standard 'manifest' field in tags response
-      manifests.each_with_object({}) do |(digest, manifest_info), mapping|
-        tags = manifest_info["tag"]
-        tags.each { |tag| mapping[tag] = digest }
+      tag_to_digest = manifests.each_with_object({}) do |(digest, manifest_info), mapping|
+        tags_for_digest = manifest_info["tag"]
+        tags_for_digest.each { |tag| mapping[tag] = digest }
+      end
+
+      # Validate that all_tags from API response matches tag_to_digest keys
+      all_tags_set = all_tags.to_set
+      manifest_tags_set = tag_to_digest.keys.to_set
+
+      unless all_tags_set == manifest_tags_set
+        raise Error, "Tag mismatch: API tags #{all_tags_set.to_a.sort} != manifest tags #{manifest_tags_set.to_a.sort}"
       end
+
+      tag_to_digest
+    end
+
+    private
+
+    def build_api_url(registry)
+      parts = registry.split("/")
+      raise Error, "Invalid GCR registry format: #{registry}" if parts.length < 3
+
+      host, project, *image = parts
+
+      "https://#{host}/v2/#{project}/#{image.join("/")}/tags/list"
     end
   end
 end

data/lib/equilibrium/repository_tags_service.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "registry_client"
+require_relative "tag_processor"
+require_relative "canonical_version_mapper"
+
+module Equilibrium
+  class RepositoryTagsService
+    def self.generate_expected_tags(repository_url)
+      registry_client = RegistryClient.new(repository_url)
+
+      tagged_digests = registry_client.tagged_digests
+      semantic_tags = TagProcessor.filter_semantic_tags(tagged_digests)
+      TagProcessor.compute_virtual_tags(semantic_tags)
+    end
+
+    def self.generate_actual_tags(repository_url)
+      registry_client = RegistryClient.new(repository_url)
+
+      tagged_digests = registry_client.tagged_digests
+      semantic_tags = TagProcessor.filter_semantic_tags(tagged_digests)
+
+      mutable_tags = TagProcessor.filter_mutable_tags(tagged_digests)
+      canonical_versions = CanonicalVersionMapper.map_to_canonical_versions(mutable_tags, semantic_tags)
+
+      {
+        "digests" => mutable_tags,
+        "canonical_versions" => canonical_versions
+      }
+    end
+  end
+end