equilibrium 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d710d1c2fea441e38c5b328c036506115b7b80ade1aae20ffda4badbf9c72b76
-  data.tar.gz: c99ba87639818a92306c31c2764a604238a98607d4d655b63e6536c32b64af67
+  metadata.gz: 2a837a7453d70ee952b97888dde397411eaa7b2e22ba7a9147caf07b75ccfc17
+  data.tar.gz: 7367d2d4aed721970a617a15aec9ba81cb4e16cbaf1151d57aec4cd4a5d564e3
 SHA512:
-  metadata.gz: d5ccfd2ac6a95cf83efeed1dc59b27e1c474f9211e6155da8ae35938bc9a4316c002509e9fb60757403c3130359b1f854a0aaf84bfd9c470caacdaa5cb8c9f14
-  data.tar.gz: 76445a5a0e8e0f2e0a1f347394b44700a9e65fd2b3d23eaad0d8c1f387d54619aad184d9aa2fa50b6286660e140221cfef8e03def80768cbf5b5421e7aa61e2e
+  metadata.gz: 0fcc623d3164a2c20afb658d1f164b3ee391622290db618d27e1d628c1144e1eb0f7434d6e1e29bead38bf47c45115edbe5748bf520bb5462898cf7c988aaa37
+  data.tar.gz: 35bcc231d9e5f55e80b344586365b93345738a8edfb3e681ff9bada813e9922358b20e96e04cdac48a9b2e353c732269d218d53870a9ba32495a96270e425151

data/.ruby-version

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

data/CHANGELOG.md

@@ -5,22 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1] - 2025-08-06
+## [Unreleased]
+
+## [0.3.0] - 2025-08-26
 
 ### Added
-- GitHub Packages publishing support in release workflow
-- Draft mode for GitHub releases requiring manual review
-- Enhanced release automation with artifact attachment
+- Docker distribution support
+
+### Changed
+- Use Ruby 3.4.5
+- Unified tag structures across analyze command output
+- Improved summary format for better readability and consistency
+
+### Removed
+- Remove remediation_plan field from analyze command output
+
+## [0.2.0] - 2025-08-15
+
+### Added
+- Add `uncatalog` command for reverse catalog conversion
+
+### Changed
+- Catalog schema includes `repository_url` and `repository_name` at root level
+
+### Fixed
+- Fix changelog reference links
+
+## [0.1.1] - 2025-08-06
 
 ### Fixed
 - Preserve descending tag order in summary format output
 - Consistent descending ordering for expected and actual outputs
 
-### Changed
-- Reorganized spec files to mirror lib directory structure
-- Extracted TagSorter utility with comprehensive unit tests
-- Enhanced RegistryClient with pagination analysis capabilities
-
 ## [0.1.0] - 2025-08-05
 
 ### Added
@@ -38,8 +54,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CI/CD pipeline with GitHub Actions
 - Trusted publishing support for RubyGems
 - Standard rake task integration
-
-### Features
 - **Tag Validation**: Validates equilibrium between mutable tags and semantic version tags
 - **Registry Client**: Pure Ruby HTTP client for container registry API access
 - **Tag Processing**: Computes expected mutable tags from semantic versions (latest, major, minor)
@@ -53,5 +67,7 @@ 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.1.1]: https://github.com/DataDog/equilibrium/releases/tag/v0.1.1
-[0.1.0]: https://github.com/DataDog/equilibrium/releases/tag/v0.1.0
+[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

@@ -15,7 +15,6 @@ A container image tool that validates equilibrium between mutable tags and seman
 - [Quick Start](#quick-start)
 - [Output Formats & Schemas](#output-formats--schemas)
 - [Constraints](#constraints)
-- [Examples](#examples)
 - [License](#license)
 
 ## The Problem
@@ -54,19 +53,27 @@ 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]
+    L --> M[uncatalog<br/>Command]
+    M --> N[Back to Expected/<br/>Actual Format]
 
     classDef source fill:#e1d5e7
     classDef process fill:#fff2cc
     classDef expected fill:#d5e8d4
     classDef actual fill:#f8cecc
     classDef result fill:#ffcccc
+    classDef catalog fill:#dae8fc
 
     class A source
     class C,D,G,I process
     class E,H expected
     class F actual
     class J result
+    class K,M catalog
+    class L,N catalog
 ```
 
 **Process Steps:**
@@ -74,7 +81,8 @@ 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
 
@@ -82,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
@@ -94,10 +109,14 @@ 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
+
+# 4. Convert to catalog format and back (Round trip)
+equilibrium catalog expected.json  | tee catalog.json
+equilibrium uncatalog catalog.json | tee uncatalog.json
 ```
 
 *For detailed command options, run `equilibrium help [command]`*
@@ -197,55 +216,66 @@ 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
 {
+  "repository_url": "gcr.io/project/image",
+  "repository_name": "image",
   "images": [
     {
-      "name": "image",
       "tag": "latest",
       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
       "canonical_version": "1.2.3"
     },
     {
-      "name": "image",
       "tag": "1",
       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
       "canonical_version": "1.2.3"
     },
     {
-      "name": "image",
       "tag": "1.2",
       "digest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
       "canonical_version": "1.2.3"
@@ -254,6 +284,8 @@ All commands output structured JSON following validated schemas (see [schemas](l
 }
 ```
 
+**Uncatalog Command**: Converts catalog format back to expected/actual format (same schema as expected/actual commands).
+
 ### Summary Format
 Human-readable table format for quick visual inspection.
 
@@ -263,50 +295,59 @@ 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]`
 
-## Examples
+### Local Image Build
+
+To build the Docker image locally, you need the gem artifact in the `pkg/` directory:
 
-### Example 1: Perfect Equilibrium
 ```bash
-$ equilibrium expected gcr.io/google-containers/pause
-# Shows: latest→3.9, 3→3.9, 3.9→3.9
+# Build the gem using the same method as CI
+bundle exec rake clobber  # Clean previous builds
+bundle exec rake build    # Rebuild gem
 
-$ equilibrium actual gcr.io/google-containers/pause
-# Shows: latest→3.9, 3→3.9, 3.9→3.9
+# Build image
+podman build -f docker/Dockerfile -t equilibrium:local .
 
-$ equilibrium analyze --expected expected.json --actual actual.json
-# Status: ✅ in_equilibrium
+# Test the local build
+podman run --rm localhost/equilibrium:local equilibrium version
 ```
 
-### Example 2: Out of Equilibrium
-```bash
-$ equilibrium expected gcr.io/project/myapp
-# Expected: latest→2.1.0, 1→1.5.3, 2→2.1.0, 2.1→2.1.0
+**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.
 
-$ equilibrium actual gcr.io/project/myapp
-# Actual: latest→1.5.3, 1→1.5.3 (missing: 2, 2.1)
+## Development
 
-$ equilibrium analyze --expected expected.json --actual actual.json
-# Status: ❌ out_of_equilibrium
-# Remediation: Create tags: 2→2.1.0, 2.1→2.1.0; Update: latest→2.1.0
+### Prerequisites
+
+- **Ruby** (>= 3.0.0) with Bundler
+- **No authentication required** for public Google Container Registry (GCR) access
+- **Pure Ruby implementation** - uses only Ruby standard library (Net::HTTP) for HTTP requests
+
+### Code Quality
+
+```bash
+# Ruby linting
+bundle exec standardrb
+bundle exec standardrb --fix
+
+# Run tests
+bundle exec rspec
 ```
 
-### Example 3: Automation Pipeline
+### Release Process
+
+To create a new release:
+
 ```bash
-#!/bin/bash
-REPO="gcr.io/project/image"
-
-# Daily equilibrium check
-equilibrium expected "$REPO" > expected.json
-equilibrium actual "$REPO" > actual.json
-equilibrium analyze --expected expected.json --actual actual.json --format json > report.json
-
-# Alert if out of equilibrium
-if grep -q '"status": "out_of_equilibrium"' report.json; then
-  echo "⚠️  Repository $REPO is out of equilibrium!"
-  equilibrium analyze --expected expected.json --actual actual.json
-fi
+# Update version in lib/equilibrium/version.rb, then:
+./bin/release
 ```
 
+The script automatically:
+1. Reads the version from `equilibrium.gemspec`
+2. Creates a git tag with `v` prefix (e.g., `v0.1.1`)
+3. Pushes the tag to trigger the automated release workflow
+
+The GitHub Actions workflow validates that the tag version matches the gemspec version before publishing to RubyGems and GitHub Packages.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.

data/lib/equilibrium/analyzer.rb

@@ -4,84 +4,66 @@ require "json"
 
 module Equilibrium
   class Analyzer
-    def initialize
+    def self.analyze(expected_data, actual_data)
+      new.analyze(expected_data, actual_data)
     end
 
-    # Analyzes validated expected/actual data in schema format
     def analyze(expected_data, actual_data)
       # Extract digests from validated schema format
       expected_tags = expected_data["digests"]
       actual_tags = actual_data["digests"]
 
-      # Extract and validate repository URLs match
+      # Extract and validate repository names match
+      expected_name = expected_data["repository_name"]
+      actual_name = actual_data["repository_name"]
       expected_url = expected_data["repository_url"]
       actual_url = actual_data["repository_url"]
 
-      if expected_url != actual_url
-        raise ArgumentError, "Repository URLs do not match: expected '#{expected_url}', actual '#{actual_url}'"
+      if expected_name != actual_name
+        raise ArgumentError, "Repository names do not match: expected '#{expected_name}', actual '#{actual_name}'"
       end
 
-      final_repository_url = expected_url
+      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,
         actual_count: actual_tags.size,
         missing_tags: find_missing_tags(expected_tags, actual_tags),
         unexpected_tags: find_unexpected_tags(expected_tags, actual_tags),
         mismatched_tags: find_mismatched_tags(expected_tags, actual_tags),
         status: determine_status(expected_tags, actual_tags)
-      }
-
-      # Add remediation plan for JSON format
-      analysis[:remediation_plan] = generate_remediation_plan(analysis, final_repository_url)
-      analysis
-    end
-
-    private
-
-    def generate_remediation_plan(analysis, repository_url)
-      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}"
-        }
-      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}"
-        }
-      end
-
-      analysis[:unexpected_tags].each do |tag, digest|
-        plan << {
-          action: "remove_tag",
-          tag: tag,
-          digest: digest,
-          command: "gcloud container images untag #{repository_url}:#{tag}"
-        }
-      end
-
-      plan
+      }.compact
     end
 
     private
 
     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/canonical_version_mapper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Equilibrium
+  class CanonicalVersionMapper
+    def self.map_to_canonical_versions(mutable_tags, semantic_tags)
+      canonical_versions = {}
+
+      mutable_tags.each do |mutable_tag, m_digest|
+        # Find semantic tag with same digest, raise if not found
+        canonical_version = semantic_tags.key(m_digest) ||
+          (raise "No semantic tag found with digest #{m_digest} for mutable tag '#{mutable_tag}'")
+
+        canonical_versions[mutable_tag] = canonical_version
+      end
+
+      canonical_versions
+    end
+  end
+end

data/lib/equilibrium/catalog_builder.rb

@@ -1,45 +1,61 @@
 # frozen_string_literal: true
 
 require "json"
-require "json_schemer"
-require_relative "schemas/catalog"
 
 module Equilibrium
   class CatalogBuilder
     class Error < StandardError; end
 
-    def build_catalog(data)
-      # Extract repository name, digests, and canonical versions from the validated data structure
+    def self.build_catalog(data)
       repository_name = data["repository_name"]
+      repository_url = data["repository_url"]
       digests = data["digests"]
       canonical_versions = data["canonical_versions"]
 
       images = digests.map do |tag, digest|
         {
-          "name" => repository_name,
           "tag" => tag,
           "digest" => digest,
           "canonical_version" => canonical_versions[tag]
         }
       end
 
-      catalog = {
+      {
+        "repository_url" => repository_url,
+        "repository_name" => repository_name,
         "images" => images
       }
-
-      validate_catalog(catalog)
-      catalog
     end
 
-    private
+    def self.reverse_catalog(catalog_data)
+      images = catalog_data["images"]
+      repository_url = catalog_data["repository_url"]
+      repository_name = catalog_data["repository_name"]
+
+      if images.nil? || images.empty?
+        return {
+          "repository_url" => repository_url || "",
+          "repository_name" => repository_name || "",
+          "digests" => {},
+          "canonical_versions" => {}
+        }
+      end
 
-    def validate_catalog(catalog)
-      schemer = JSONSchemer.schema(Equilibrium::Schemas::CATALOG)
-      errors = schemer.validate(catalog).to_a
+      digests = {}
+      canonical_versions = {}
 
-      unless errors.empty?
-        raise Error, "Catalog validation failed: #{errors.map(&:to_s).join(", ")}"
+      images.each do |image|
+        tag = image["tag"]
+        digests[tag] = image["digest"]
+        canonical_versions[tag] = image["canonical_version"]
       end
+
+      {
+        "repository_url" => repository_url,
+        "repository_name" => repository_name,
+        "digests" => digests,
+        "canonical_versions" => canonical_versions
+      }
     end
   end
 end