equilibrium 0.1.0 → 0.2.0

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 and generating remediation plan
+    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

@@ -26,29 +26,40 @@ module Equilibrium
   # by some registries (like GCR). Most registries follow the Docker Registry v2 spec
   # which only returns 'name' and 'tags' fields. To get digest information, separate
   # calls to /v2/<name>/manifests/<tag> are required per the official specification.
+  #
+  # PAGINATION ANALYSIS (August 2025):
+  # Current implementation fetches ALL tags in single API call. Analysis of production registries:
+  # - apm-inject: 29 tags
+  # - dd-lib-dotnet-init: 31 tags
+  # - dd-lib-java-init: 18 tags
+  # - dd-lib-js-init: 56 tags (largest)
+  # - dd-lib-php-init: 10 tags
+  # - dd-lib-python-init: 27 tags
+  # - dd-lib-ruby-init: 19 tags
+  # Total: 190 tags across all registries
+  #
+  # GCR PAGINATION RESEARCH FINDINGS:
+  # - DOCUMENTED LIMIT: 10,000 items for format-specific API requests
+  #   Source: https://cloud.google.com/artifact-registry/quotas
+  # - NO PAGINATION SUPPORT: GCR ignores Docker Registry v2 pagination parameters ('n', 'last')
+  #   Source: https://stackoverflow.com/questions/38307259 (unresolved since 2016)
+  # - ALL-OR-NOTHING: Returns complete tag lists up to 10k limit, then truncates unpredictably
+  # - NO PER-PAGE LIMIT: Not documented, not applicable due to lack of pagination support
+  #
+  # RECOMMENDATION: Current single-request approach is sufficient.
+  # Implementation complexity for pagination: 3-4 hours with minimal benefit.
+  # Consider only if individual repositories approach thousands of tags.
   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
@@ -58,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

data/lib/equilibrium/repository_url_validator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Equilibrium
+  module RepositoryUrlValidator
+    def self.validate(repository_url)
+      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
+  end
+end

data/lib/equilibrium/schema_validator.rb

@@ -14,8 +14,7 @@ module Equilibrium
     # @param error_prefix [String] Prefix for error messages (optional)
     # @raise [ValidationError] If validation fails
     def self.validate!(data, schema, error_prefix: "Schema validation failed")
-      schemer = JSONSchemer.schema(schema)
-      errors = schemer.validate(data).to_a
+      errors = validate(data, schema)
 
       return if errors.empty?
 
@@ -25,5 +24,14 @@ module Equilibrium
 
       raise ValidationError, "#{error_prefix}:\n#{error_messages.join("\n")}"
     end
+
+    # Validates data against a JSON Schema and returns validation errors
+    # @param data [Hash] The data to validate
+    # @param schema [Hash] The JSON Schema to validate against
+    # @return [Array] Array of validation errors (empty if valid)
+    def self.validate(data, schema)
+      schemer = JSONSchemer.schema(schema)
+      schemer.validate(data).to_a
+    end
   end
 end

data/lib/equilibrium/schemas/analyzer_output.rb

@@ -8,6 +8,7 @@ module Equilibrium
     # Example output (perfect equilibrium):
     # {
     #   "repository_url": "gcr.io/datadoghq/apm-inject",
+    #   "repository_name": "apm-inject",
     #   "expected_count": 28,
     #   "actual_count": 28,
     #   "missing_tags": {},
@@ -20,6 +21,7 @@ module Equilibrium
     # Example output (requires remediation):
     # {
     #   "repository_url": "gcr.io/datadoghq/example",
+    #   "repository_name": "example",
     #   "expected_count": 3,
     #   "actual_count": 2,
     #   "missing_tags": {
@@ -49,9 +51,13 @@ module Equilibrium
       "title" => "Equilibrium Analyzer Output Schema",
       "description" => "Schema for output from 'equilibrium analyze --format=json' command",
       "type" => "object",
-      "required" => ["repository_url", "expected_count", "actual_count", "missing_tags", "unexpected_tags", "mismatched_tags", "status", "remediation_plan"],
+      "required" => [
+        "repository_url",
+        "repository_name", "expected_count", "actual_count", "missing_tags", "unexpected_tags", "mismatched_tags", "status", "remediation_plan"
+      ],
       "properties" => {
         "repository_url" => {"type" => "string"},
+        "repository_name" => {"type" => "string"},
         "expected_count" => {"type" => "integer", "minimum" => 0},
         "actual_count" => {"type" => "integer", "minimum" => 0},
         "status" => {"enum" => ["perfect", "missing_tags", "mismatched", "extra_tags"]},
@@ -84,7 +90,7 @@ module Equilibrium
           "type" => "array",
           "items" => {
             "type" => "object",
-            "required" => ["action", "tag", "command"],
+            "required" => ["action", "tag"],
             "properties" => {
               "action" => {"enum" => ["create_tag", "update_tag", "remove_tag"]},
               "tag" => {"type" => "string"},

data/lib/equilibrium/schemas/catalog.rb

@@ -3,25 +3,24 @@
 module Equilibrium
   module Schemas
     # JSON Schema for catalog output format
-    # Used by `equilibrium catalog` command
+    # Used by `catalog` command
     #
     # Example output:
     # {
+    #   "repository_url": "gcr.io/datadoghq/apm-inject",
+    #   "repository_name": "apm-inject",
     #   "images": [
     #     {
-    #       "name": "apm-inject",
     #       "tag": "latest",
     #       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
     #       "canonical_version": "0.43.2"
     #     },
     #     {
-    #       "name": "apm-inject",
     #       "tag": "0",
     #       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
     #       "canonical_version": "0.43.2"
     #     },
     #     {
-    #       "name": "apm-inject",
     #       "tag": "0.43",
     #       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
     #       "canonical_version": "0.43.1"
@@ -33,22 +32,30 @@ module Equilibrium
       "title" => "Tag Resolver Schema",
       "description" => "Schema for Resolve tag",
       "type" => "object",
+      "required" => ["repository_url", "repository_name", "images"],
       "properties" => {
+        "repository_url" => {
+          "type" => "string",
+          "description" => "Full repository URL (e.g., 'gcr.io/project-id/image-name')",
+          "minLength" => 1,
+          "pattern" => "^[a-zA-Z0-9.-]+(/[a-zA-Z0-9._-]+)*$"
+        },
+        "repository_name" => {
+          "type" => "string",
+          "description" => "Repository name extracted from URL (e.g., 'apm-inject')",
+          "minLength" => 1,
+          "pattern" => "^[a-zA-Z0-9._-]+$"
+        },
         "images" => {
           "type" => "array",
           "items" => {
             "type" => "object",
             "required" => [
-              "name",
               "tag",
               "digest",
               "canonical_version"
             ],
             "properties" => {
-              "name" => {
-                "type" => "string",
-                "description" => "The name of the image"
-              },
               "tag" => {
                 "type" => "string",
                 "description" => "The mutable tag of the image"

data/lib/equilibrium/schemas/expected_actual.rb

@@ -3,7 +3,7 @@
 module Equilibrium
   module Schemas
     # JSON Schema for expected/actual command output format
-    # Used by `equilibrium expected` and `equilibrium actual` commands
+    # Used by `expected`, `actual` and `uncatalog` commands
     #
     # Example output:
     # {

data/lib/equilibrium/schemas/registry_api.rb

@@ -24,7 +24,7 @@ module Equilibrium
       "title" => "Docker Registry v2 Tags List Response Schema",
       "description" => "Schema for response from Docker Registry v2 API /v2/{name}/tags/list endpoint",
       "type" => "object",
-      "required" => ["name", "tags"],
+      "required" => ["name", "tags", "manifest"],
       "properties" => {
         "name" => {
           "type" => "string",

data/lib/equilibrium/summary_formatter.rb

@@ -104,7 +104,7 @@ module Equilibrium
 
       # Create table data: [["Tag", "Version", "Digest"]]
       table_data = [["Tag", "Version", "Digest"]]
-      mutable_tags.keys.sort.each do |tag|
+      mutable_tags.keys.each do |tag|
         canonical_version = canonical_versions[tag]
         digest = mutable_tags[tag]
         table_data << [tag, canonical_version, digest]

data/lib/equilibrium/tag_data_builder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "tag_sorter"
+
+module Equilibrium
+  class TagDataBuilder
+    def self.build_output(repository_url, repository_name, digests, canonical_versions)
+      {
+        "repository_url" => repository_url,
+        "repository_name" => repository_name,
+        "digests" => TagSorter.sort_descending(digests),
+        "canonical_versions" => TagSorter.sort_descending(canonical_versions)
+      }
+    end
+  end
+end