equilibrium 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22d45ae6c6368e01aa50e5c7abc828bee9a9f759beb57c2c80dc7f579e1b50da
-  data.tar.gz: 445f71cbc4c40d5d60bea3a456197a9de6d817bc32cc4bf87aa678d9c5691231
+  metadata.gz: 495555ab3b3d0695f4e559e5372c5d8ab83ff131d11a9758dde1aa0df497472e
+  data.tar.gz: 4ce686d07757a3f5732cdc58a3e48c9084a1ddf4eef2130ba1cb5af5e5b10b95
 SHA512:
-  metadata.gz: 0fbcb1559ecd07a6431b36342ca067f69cda326f547e32a70e256bfce35b762d76073b755a5365407b87ad6be9ff862eb5232a6866974a88d54ec1cebf1b304c
-  data.tar.gz: 1f1b80fa1c4d4b08546e7cf77c5254de3ebca107c63f0d0c15d317628380d211f247ab0586248d4476d9bb5ed4e86302ad2abb5bd1777b34d0c5fa34054a0d42
+  metadata.gz: 8b69760396a2992caaafcaf2f219290a78555dbf2c474e52a38120d5b5cd81a549ba9e9c01afc7990239706d1a8be7d9db3ac2218152ba3bf3bf1597eff1b196
+  data.tar.gz: b33a4bc6bd29f7492850af6e310996c1c3967bb93f577b587086025307cce85b39bc67bb4f47b1cc169f894ac98a29c6f52cc827824b83604b2aec2b2b2989ac

data/.ruby-version

@@ -1 +1 @@
-3.2.8
+3.4.5

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2025-08-26
+
+### Fixed
+- Fix changelog format
+
+## [0.3.0] - 2025-08-26
+
+### Added
+- Docker distribution support
+
+### Changed
+- Use Ruby 3.4.5
+- Unified tag structures across analyze command output
+- Improved summary format for better readability and consistency
+- Remove remediation_plan field from analyze command output
+
 ## [0.2.0] - 2025-08-15
 
 ### Added
@@ -54,6 +70,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Detailed architecture overview and data flow diagrams
 - Complete command reference and examples
 
+[0.3.1]: https://github.com/TonyCTHsu/equilibrium/releases/tag/v0.3.1
+[0.3.0]: https://github.com/TonyCTHsu/equilibrium/releases/tag/v0.3.0
 [0.2.0]: https://github.com/TonyCTHsu/equilibrium/releases/tag/v0.2.0
 [0.1.1]: https://github.com/TonyCTHsu/equilibrium/releases/tag/v0.1.1
 [0.1.0]: https://github.com/TonyCTHsu/equilibrium/releases/tag/v0.1.0

data/README.md

@@ -53,7 +53,7 @@ flowchart LR
     H --> I[Compare<br/>Expected vs<br/>Actual]
     F --> I
 
-    I --> J[Analysis &<br/>Remediation<br/>Update: latest]
+    I --> J[Analysis Report<br/>Missing: 1<br/>Mismatched: latest]
 
     H --> K[catalog<br/>Command]
     K --> L[Catalog Format<br/>External Integration]
@@ -81,7 +81,7 @@ flowchart LR
 2. **Filter Semantic**: Extract only valid semantic version tags (MAJOR.MINOR.PATCH)
 3. **Compute Expected**: Generate mutable tags based on semantic versions
 4. **Fetch Actual**: Query registry for current mutable tag state
-5. **Compare & Analyze**: Identify mismatches and generate remediation plan
+5. **Compare & Analyze**: Identify missing, unexpected, and mismatched tags with unified structure
 6. **Format Conversion**: Transform between expected/actual and catalog formats for external integration
 
 ## Installation
@@ -90,6 +90,13 @@ flowchart LR
 gem install equilibrium
 ```
 
+For containerized environments, use the Docker image:
+
+```bash
+# Pull the latest version
+docker pull ghcr.io/tonycthsu/equilibrium:latest
+```
+
 *For other installation methods, see `equilibrium help`*
 
 ## Quick Start
@@ -102,7 +109,7 @@ equilibrium expected "$REPO"
 # 2. Check what mutable tags actually exist
 equilibrium actual "$REPO"
 
-# 3. Compare and get remediation plan
+# 3. Compare and analyze differences
 equilibrium expected "$REPO" --format json > expected.json
 equilibrium actual "$REPO" --format json > actual.json
 equilibrium analyze --expected expected.json --actual actual.json
@@ -209,37 +216,49 @@ All commands output structured JSON following validated schemas (see [schemas](l
 ```json
 {
   "repository_url": "gcr.io/project/image",
+  "repository_name": "image",
   "expected_count": 3,
   "actual_count": 2,
   "missing_tags": {
-    "1.2": "sha256:abc123ef456789012345678901234567890123456789012345678901234567890"
+    "1.2": {
+      "expected": "sha256:abc123ef456789012345678901234567890123456789012345678901234567890",
+      "actual": ""
+    }
+  },
+  "unexpected_tags": {
+    "dev": {
+      "expected": "",
+      "actual": "sha256:xyz789ab123456789012345678901234567890123456789012345678901234"
+    }
   },
-  "unexpected_tags": {},
   "mismatched_tags": {
     "latest": {
       "expected": "sha256:def456ab789123456789012345678901234567890123456789012345678901",
       "actual": "sha256:old123ef456789012345678901234567890123456789012345678901234567890"
     }
   },
-  "status": "missing_tags",
-  "remediation_plan": [
-    {
-      "action": "create_tag",
-      "tag": "1.2",
-      "digest": "sha256:abc123ef456789012345678901234567890123456789012345678901234567890",
-      "command": "gcloud container images add-tag gcr.io/project/image@sha256:abc123... gcr.io/project/image:1.2"
-    },
-    {
-      "action": "update_tag",
-      "tag": "latest",
-      "old_digest": "sha256:old123ef456789012345678901234567890123456789012345678901234567890",
-      "new_digest": "sha256:def456ab789123456789012345678901234567890123456789012345678901",
-      "command": "gcloud container images add-tag gcr.io/project/image@sha256:def456... gcr.io/project/image:latest"
-    }
-  ]
+  "status": "missing_tags"
 }
 ```
 
+#### Unified Tag Structure
+
+All tag analysis results (`missing_tags`, `unexpected_tags`, `mismatched_tags`) use a consistent structure:
+
+- **`missing_tags`**: Tags that should exist but don't
+  - `expected`: The SHA256 digest the tag should point to
+  - `actual`: Empty string (tag doesn't exist)
+
+- **`unexpected_tags`**: Tags that exist but shouldn't
+  - `expected`: Empty string (tag shouldn't exist)
+  - `actual`: The SHA256 digest the tag currently points to
+
+- **`mismatched_tags`**: Tags that exist but point to wrong digest
+  - `expected`: The SHA256 digest the tag should point to
+  - `actual`: The SHA256 digest the tag currently points to
+
+This unified structure makes programmatic processing easier and provides clear semantics about what was expected versus what was actually found.
+
 **Catalog Command** ([schema](lib/equilibrium/schemas/catalog.rb)):
 ```json
 {
@@ -276,6 +295,24 @@ Human-readable table format for quick visual inspection.
 - **Tag Format**: Only processes semantic version tags (MAJOR.MINOR.PATCH)
 - **URL Format**: Requires full repository URLs: `[REGISTRY_HOST]/[NAMESPACE]/[REPOSITORY]`
 
+### Local Image Build
+
+To build the Docker image locally, you need the gem artifact in the `pkg/` directory:
+
+```bash
+# Build the gem using the same method as CI
+bundle exec rake clobber  # Clean previous builds
+bundle exec rake build    # Rebuild gem
+
+# Build image
+podman build -f docker/Dockerfile -t equilibrium:local .
+
+# Test the local build
+podman run --rm localhost/equilibrium:local equilibrium version
+```
+
+**Note**: The Dockerfile expects the gem artifact in `pkg/*.gem`. Using `bundle exec rake build` ensures you build the gem exactly the same way as the CI pipeline.
+
 ## Development
 
 ### Prerequisites

data/lib/equilibrium/analyzer.rb

@@ -26,7 +26,7 @@ module Equilibrium
       final_repository_name = expected_name
       final_repository_url = expected_url || actual_url
 
-      analysis = {
+      {
         repository_url: final_repository_url,
         repository_name: final_repository_name,
         expected_count: expected_tags.size,
@@ -36,54 +36,34 @@ module Equilibrium
         mismatched_tags: find_mismatched_tags(expected_tags, actual_tags),
         status: determine_status(expected_tags, actual_tags)
       }.compact
-
-      # Add remediation plan for JSON format
-      analysis[:remediation_plan] = generate_remediation_plan(analysis, final_repository_url, final_repository_name)
-      analysis
     end
 
     private
 
-    def generate_remediation_plan(analysis, repository_url, repository_name)
-      plan = []
-
-      analysis[:missing_tags].each do |tag, digest|
-        plan << {
-          action: "create_tag",
-          tag: tag,
-          digest: digest,
-          command: "gcloud container images add-tag #{repository_url}@#{digest} #{repository_url}:#{tag}"
-        }.compact
-      end
-
-      analysis[:mismatched_tags].each do |tag, data|
-        plan << {
-          action: "update_tag",
-          tag: tag,
-          old_digest: data[:actual],
-          new_digest: data[:expected],
-          command: "gcloud container images add-tag #{repository_url}@#{data[:expected]} #{repository_url}:#{tag}"
-        }.compact
-      end
-
-      analysis[:unexpected_tags].each do |tag, digest|
-        plan << {
-          action: "remove_tag",
-          tag: tag,
-          digest: digest,
-          command: "gcloud container images untag #{repository_url}:#{tag}"
-        }.compact
-      end
-
-      plan
-    end
-
     def find_missing_tags(expected, actual)
-      expected.reject { |tag, digest| actual.key?(tag) }
+      missing = {}
+      expected.each do |tag, digest|
+        unless actual.key?(tag)
+          missing[tag] = {
+            expected: digest,
+            actual: ""
+          }
+        end
+      end
+      missing
     end
 
     def find_unexpected_tags(expected, actual)
-      actual.reject { |tag, _| expected.key?(tag) }
+      unexpected = {}
+      actual.each do |tag, digest|
+        unless expected.key?(tag)
+          unexpected[tag] = {
+            expected: "",
+            actual: digest
+          }
+        end
+      end
+      unexpected
     end
 
     def find_mismatched_tags(expected, actual)

data/lib/equilibrium/cli.rb

@@ -16,7 +16,7 @@ module Equilibrium
       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"

data/lib/equilibrium/commands/analyze_command.rb

@@ -11,7 +11,7 @@ require_relative "../analyzer"
 
 module Equilibrium
   module Commands
-    # Command for analyzing expected vs actual tags and generating remediation plan
+    # Command for analyzing expected vs actual tags with unified structure
     class AnalyzeCommand
       include Mixins::ErrorHandling
       include Mixins::InputOutput

data/lib/equilibrium/schemas/analyzer_output.rb

@@ -14,21 +14,26 @@ module Equilibrium
     #   "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": {
@@ -36,15 +41,7 @@ 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",
@@ -53,7 +50,7 @@ module Equilibrium
       "type" => "object",
       "required" => [
         "repository_url",
-        "repository_name", "expected_count", "actual_count", "missing_tags", "unexpected_tags", "mismatched_tags", "status", "remediation_plan"
+        "repository_name", "expected_count", "actual_count", "missing_tags", "unexpected_tags", "mismatched_tags", "status"
       ],
       "properties" => {
         "repository_url" => {"type" => "string"},
@@ -64,13 +61,27 @@ module Equilibrium
         "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" => {
@@ -85,21 +96,6 @@ module Equilibrium
               }
             }
           }
-        },
-        "remediation_plan" => {
-          "type" => "array",
-          "items" => {
-            "type" => "object",
-            "required" => ["action", "tag"],
-            "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/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/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: equilibrium
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Tony Hsu
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -96,16 +95,14 @@ files:
 - 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/v0.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/TonyCTHsu/equilibrium/blob/v0.3.1/CHANGELOG.md
   github_repo: ssh://github.com/TonyCTHsu/equilibrium
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,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/tmp/.gitkeep

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