equilibrium 0.1.1 → 0.3.0

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,25 +8,32 @@ 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": {},
     #   "unexpected_tags": {},
     #   "mismatched_tags": {},
-    #   "status": "perfect",
-    #   "remediation_plan": []
+    #   "status": "perfect"
     # }
     #
-    # Example output (requires remediation):
+    # Example output (with discrepancies):
     # {
     #   "repository_url": "gcr.io/datadoghq/example",
+    #   "repository_name": "example",
     #   "expected_count": 3,
     #   "actual_count": 2,
     #   "missing_tags": {
-    #     "latest": "sha256:abc123ef456789..."
+    #     "latest": {
+    #       "expected": "sha256:abc123ef456789...",
+    #       "actual": ""
+    #     }
     #   },
     #   "unexpected_tags": {
-    #     "dev": "sha256:xyz789ab123456..."
+    #     "dev": {
+    #       "expected": "",
+    #       "actual": "sha256:xyz789ab123456..."
+    #     }
     #   },
     #   "mismatched_tags": {
     #     "0.1": {
@@ -34,37 +41,47 @@ module Equilibrium
     #       "actual": "sha256:old123ef456789..."
     #     }
     #   },
-    #   "status": "missing_tags",
-    #   "remediation_plan": [
-    #     {
-    #       "action": "create_tag",
-    #       "tag": "latest",
-    #       "digest": "sha256:abc123ef456789...",
-    #       "command": "gcloud container images add-tag gcr.io/datadoghq/example@sha256:abc123... gcr.io/datadoghq/example:latest"
-    #     }
-    #   ]
+    #   "status": "missing_tags"
     # }
     ANALYZER_OUTPUT = {
       "$schema" => "https://json-schema.org/draft/2020-12/schema",
       "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"
+      ],
       "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"]},
         "missing_tags" => {
           "type" => "object",
           "patternProperties" => {
-            ".*" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"}
+            ".*" => {
+              "type" => "object",
+              "required" => ["expected", "actual"],
+              "properties" => {
+                "expected" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"},
+                "actual" => {"type" => "string", "enum" => [""]}
+              }
+            }
           }
         },
         "unexpected_tags" => {
           "type" => "object",
           "patternProperties" => {
-            ".*" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"}
+            ".*" => {
+              "type" => "object",
+              "required" => ["expected", "actual"],
+              "properties" => {
+                "expected" => {"type" => "string", "enum" => [""]},
+                "actual" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"}
+              }
+            }
           }
         },
         "mismatched_tags" => {
@@ -79,21 +96,6 @@ module Equilibrium
               }
             }
           }
-        },
-        "remediation_plan" => {
-          "type" => "array",
-          "items" => {
-            "type" => "object",
-            "required" => ["action", "tag", "command"],
-            "properties" => {
-              "action" => {"enum" => ["create_tag", "update_tag", "remove_tag"]},
-              "tag" => {"type" => "string"},
-              "digest" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"},
-              "old_digest" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"},
-              "new_digest" => {"type" => "string", "pattern" => "^sha256:[a-f0-9]{64}$"},
-              "command" => {"type" => "string"}
-            }
-          }
         }
       }
     }.freeze

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

@@ -43,9 +43,9 @@ module Equilibrium
         has_issues = true
         say "Missing Tags (should be created):"
         missing_table = [["Tag", "Should Point To"]]
-        analysis[:missing_tags].each do |tag, digest|
-          short_digest = digest ? digest.split(":").last[0..11] : "unknown"
-          missing_table << [tag, short_digest]
+        analysis[:missing_tags].each do |tag, details|
+          full_digest = details[:expected] || "unknown"
+          missing_table << [tag, full_digest]
         end
         print_table(missing_table, borders: true)
         say ""
@@ -58,10 +58,10 @@ module Equilibrium
         mismatched_table = [["Tag", "Expected", "Actual"]]
         analysis[:mismatched_tags].each do |tag, details|
           if details.is_a?(Hash)
-            expected = details[:expected] ? details[:expected].split(":").last[0..11] : "unknown"
-            actual = details[:actual] ? details[:actual].split(":").last[0..11] : "unknown"
+            expected = details[:expected] || "unknown"
+            actual = details[:actual] || "unknown"
           else
-            expected = details ? details.split(":").last[0..11] : "unknown"
+            expected = details || "unknown"
             actual = "unknown"
           end
           mismatched_table << [tag, expected, actual]
@@ -75,17 +75,17 @@ module Equilibrium
         has_issues = true
         say "Unexpected Tags (should be removed):"
         unexpected_table = [["Tag", "Currently Points To"]]
-        analysis[:unexpected_tags].each do |tag, digest|
-          short_digest = digest ? digest.split(":").last[0..11] : "unknown"
-          unexpected_table << [tag, short_digest]
+        analysis[:unexpected_tags].each do |tag, details|
+          full_digest = details[:actual] || "unknown"
+          unexpected_table << [tag, full_digest]
         end
         print_table(unexpected_table, borders: true)
         say ""
       end
 
       if has_issues
-        say "To see detailed remediation commands, use:"
-        say "  equilibrium analyze --expected expected.json --actual actual.json --format=json | jq '.remediation_plan'"
+        say "To see detailed analysis data, use:"
+        say "  equilibrium analyze --expected expected.json --actual actual.json --format=json"
       else
         say "✓ Registry is in perfect equilibrium!", :green
       end

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

data/lib/equilibrium/tag_processor.rb

@@ -8,6 +8,14 @@ module Equilibrium
       new.compute_virtual_tags(semantic_tags)
     end
 
+    def self.filter_semantic_tags(tagged_digests)
+      new.filter_semantic_tags(tagged_digests)
+    end
+
+    def self.filter_mutable_tags(tagged_digests)
+      new.filter_mutable_tags(tagged_digests)
+    end
+
     def compute_virtual_tags(semantic_tags)
       return {"digests" => {}, "canonical_versions" => {}} if semantic_tags.empty?
 
@@ -55,26 +63,32 @@ module Equilibrium
       {"digests" => digests, "canonical_versions" => canonical_versions}
     end
 
-    def filter_semantic_tags(all_tags)
-      # Filter semantic tags (canonical_tags.json): exact major.minor.patch format
-      all_tags.select { |tag, _| semantic_version?(tag) }
+    def filter_semantic_tags(tagged_digests)
+      tagged_digests.select { |tag, _| semantic_version?(tag) }
     end
 
-    def filter_mutable_tags(all_tags)
-      # Filter mutable tags (actual_tags.json): latest, digits, or major.minor format
-      all_tags.select { |tag, _| mutable_tag?(tag) }
+    def filter_mutable_tags(tagged_digests)
+      tagged_digests.select { |tag, _| mutable_tag?(tag) }
     end
 
     private
 
     def semantic_version?(tag)
-      SemanticVersion.valid?(tag)
+      # Strictly validate MAJOR.MINOR.PATCH format where:
+      # - MAJOR, MINOR, PATCH are non-negative integers
+      # - No leading zeros (except for '0' itself)
+      # - No prefixes (like 'v1.2.3', 'release-1.2.3')
+      # - No suffixes (like '1.2.3-alpha', '1.2.3+build')
+      # - No prereleases (like '1.2.3-rc.1', '1.2.3-beta.2')
+      tag.match?(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/)
     end
 
     def mutable_tag?(tag)
-      tag.match?(/^latest$/) ||
-        tag.match?(/^[0-9]+$/) ||
-        tag.match?(/^[0-9]+\.[0-9]+$/)
+      # Validate mutable tags: latest, major versions (digits only), or major.minor format
+      # - 'latest' is the special case for the highest overall version
+      # - Major versions: non-negative integers without leading zeros (e.g., '1', '0', '42')
+      # - Minor versions: MAJOR.MINOR format with same zero-leading rules (e.g., '1.2', '0.9')
+      tag.match?(/^(latest|(0|[1-9]\d*)(\.(0|[1-9]\d*))?)$/)
     end
   end
 end

data/lib/equilibrium/tag_sorter.rb

@@ -4,10 +4,6 @@ module Equilibrium
   class TagSorter
     # Sort tags in descending version order: latest first, then major versions (descending), then minor versions (descending)
     def self.sort_descending(tags_hash)
-      new.sort_descending(tags_hash)
-    end
-
-    def sort_descending(tags_hash)
       return {} if tags_hash.nil? || tags_hash.empty?
 
       sorted = {}
@@ -20,10 +16,10 @@ module Equilibrium
       # Sort other tags by version (descending)
       other_tags = tags_hash.keys.reject { |k| k == "latest" }
       sorted_tags = other_tags.sort_by do |tag|
-        if major_version?(tag)
+        if tag.match?(/^[0-9]+$/)
           # Major version: sort by numeric value (descending)
           [-tag.to_i]
-        elsif minor_version?(tag)
+        elsif tag.match?(/^[0-9]+\.[0-9]+$/)
           # Minor version: sort by version (descending)
           parts = tag.split(".").map(&:to_i)
           [-parts[0], -parts[1]]
@@ -39,15 +35,5 @@ module Equilibrium
 
       sorted
     end
-
-    private
-
-    def major_version?(tag)
-      tag.match?(/^[0-9]+$/)
-    end
-
-    def minor_version?(tag)
-      tag.match?(/^[0-9]+\.[0-9]+$/)
-    end
   end
 end

data/lib/equilibrium/tags_operation_service.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "repository_tags_service"
+require_relative "tag_data_builder"
+
+module Equilibrium
+  class TagsOperationService
+    def self.generate_expected_output(repository_url)
+      tag_data = RepositoryTagsService.generate_expected_tags(repository_url)
+      repository_name = repository_url.split("/").last
+
+      TagDataBuilder.build_output(
+        repository_url,
+        repository_name,
+        tag_data["digests"],
+        tag_data["canonical_versions"]
+      )
+    end
+
+    def self.generate_actual_output(repository_url)
+      tag_data = RepositoryTagsService.generate_actual_tags(repository_url)
+      repository_name = repository_url.split("/").last
+
+      TagDataBuilder.build_output(
+        repository_url,
+        repository_name,
+        tag_data["digests"],
+        tag_data["canonical_versions"]
+      )
+    end
+  end
+end

data/lib/equilibrium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Equilibrium
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/equilibrium.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "equilibrium/version"
-require_relative "equilibrium/semantic_version"
 require_relative "equilibrium/registry_client"
 require_relative "equilibrium/tag_processor"
 require_relative "equilibrium/tag_sorter"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: equilibrium
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Hsu
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -71,29 +70,39 @@ files:
 - exe/equilibrium
 - lib/equilibrium.rb
 - lib/equilibrium/analyzer.rb
+- lib/equilibrium/canonical_version_mapper.rb
 - lib/equilibrium/catalog_builder.rb
 - lib/equilibrium/cli.rb
+- lib/equilibrium/commands/actual_command.rb
+- lib/equilibrium/commands/analyze_command.rb
+- lib/equilibrium/commands/catalog_command.rb
+- lib/equilibrium/commands/expected_command.rb
+- lib/equilibrium/commands/uncatalog_command.rb
+- lib/equilibrium/commands/version_command.rb
+- lib/equilibrium/mixins/error_handling.rb
+- lib/equilibrium/mixins/input_output.rb
 - lib/equilibrium/registry_client.rb
+- lib/equilibrium/repository_tags_service.rb
+- lib/equilibrium/repository_url_validator.rb
 - lib/equilibrium/schema_validator.rb
 - lib/equilibrium/schemas/analyzer_output.rb
 - lib/equilibrium/schemas/catalog.rb
 - lib/equilibrium/schemas/expected_actual.rb
 - lib/equilibrium/schemas/registry_api.rb
-- lib/equilibrium/semantic_version.rb
 - lib/equilibrium/summary_formatter.rb
+- lib/equilibrium/tag_data_builder.rb
 - lib/equilibrium/tag_processor.rb
 - lib/equilibrium/tag_sorter.rb
+- lib/equilibrium/tags_operation_service.rb
 - lib/equilibrium/version.rb
-- tmp/.gitkeep
 homepage: https://github.com/TonyCTHsu/equilibrium
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/TonyCTHsu/equilibrium
   source_code_uri: https://github.com/TonyCTHsu/equilibrium
-  changelog_uri: https://github.com/TonyCTHsu/equilibrium/blob/master/CHANGELOG.md
-  github_repo: ssh://github.com/TonyCTHsu/tobee
-post_install_message:
+  changelog_uri: https://github.com/TonyCTHsu/equilibrium/blob/v0.3.0/CHANGELOG.md
+  github_repo: ssh://github.com/TonyCTHsu/equilibrium
 rdoc_options: []
 require_paths:
 - lib
@@ -108,8 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Container image tag validation tool
 test_files: []

data/lib/equilibrium/semantic_version.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Equilibrium
-  module SemanticVersion
-    # Strictly validate MAJOR.MINOR.PATCH format where:
-    # - MAJOR, MINOR, PATCH are non-negative integers
-    # - No leading zeros (except for '0' itself)
-    # - No prefixes (like 'v1.2.3', 'release-1.2.3')
-    # - No suffixes (like '1.2.3-alpha', '1.2.3+build')
-    # - No prereleases (like '1.2.3-rc.1', '1.2.3-beta.2')
-    def self.valid?(tag)
-      # Strict regex: each component must be either '0' or a number without leading zeros
-      return false unless tag.match?(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/)
-
-      # Additional validation: ensure it's a valid Gem::Version
-      begin
-        Gem::Version.new(tag)
-        true
-      rescue ArgumentError
-        false
-      end
-    end
-  end
-end

data/tmp/.gitkeep

@@ -1,2 +0,0 @@
-# This file ensures the tmp/ directory is tracked by git
-# while keeping all other contents ignored via .gitignore