equilibrium 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5420df18928550fa411f853968f4b5ac331fbcd3bcc682dce61370c330dd69bc
-  data.tar.gz: 062322ae383ea3aba97d0d60980f8530808e7877e5bb5a6ce311435ec6a86814
+  metadata.gz: 22d45ae6c6368e01aa50e5c7abc828bee9a9f759beb57c2c80dc7f579e1b50da
+  data.tar.gz: 445f71cbc4c40d5d60bea3a456197a9de6d817bc32cc4bf87aa678d9c5691231
 SHA512:
-  metadata.gz: 3900bcb75092a001f250dbe206d4085419435e7d2b370c3a68e57e82619e1a7b014dd32a71510f887e060244c122336f70f946bd836e1c2ef956d5500416d93c
-  data.tar.gz: 2678994b5a362aa3e282618dd49f401aa63d50905f13b0fc74323d0747dc73d076aa872c915843e8d4002a9f1042992e33b5251a5f10cbeb9405d8bb2d29454d
+  metadata.gz: 0fbcb1559ecd07a6431b36342ca067f69cda326f547e32a70e256bfce35b762d76073b755a5365407b87ad6be9ff862eb5232a6866974a88d54ec1cebf1b304c
+  data.tar.gz: 1f1b80fa1c4d4b08546e7cf77c5254de3ebca107c63f0d0c15d317628380d211f247ab0586248d4476d9bb5ed4e86302ad2abb5bd1777b34d0c5fa34054a0d42

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [Unreleased]
+
+## [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
+
 ## [0.1.0] - 2025-08-05
 
 ### Added
@@ -22,8 +41,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)
@@ -37,4 +54,6 @@ 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.0]: https://github.com/DataDog/equilibrium/releases/tag/v0.1.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
@@ -56,17 +55,25 @@ flowchart LR
 
     I --> J[Analysis &<br/>Remediation<br/>Update: 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:**
@@ -75,6 +82,7 @@ flowchart LR
 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
+6. **Format Conversion**: Transform between expected/actual and catalog formats for external integration
 
 ## Installation
 
@@ -98,6 +106,10 @@ equilibrium actual "$REPO"
 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]`*
@@ -231,21 +243,20 @@ All commands output structured JSON following validated schemas (see [schemas](l
 **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 +265,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 +276,41 @@ 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
+## Development
 
-### Example 1: Perfect Equilibrium
-```bash
-$ equilibrium expected gcr.io/google-containers/pause
-# Shows: latest→3.9, 3→3.9, 3.9→3.9
+### Prerequisites
 
-$ equilibrium actual gcr.io/google-containers/pause
-# Shows: latest→3.9, 3→3.9, 3.9→3.9
+- **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
 
-$ equilibrium analyze --expected expected.json --actual actual.json
-# Status: ✅ in_equilibrium
-```
+### Code Quality
 
-### 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
-
-$ equilibrium actual gcr.io/project/myapp
-# Actual: latest→1.5.3, 1→1.5.3 (missing: 2, 2.1)
+# Ruby linting
+bundle exec standardrb
+bundle exec standardrb --fix
 
-$ 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
+# 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,43 +4,47 @@ 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)
-      }
+      }.compact
 
       # Add remediation plan for JSON format
-      analysis[:remediation_plan] = generate_remediation_plan(analysis, final_repository_url)
+      analysis[:remediation_plan] = generate_remediation_plan(analysis, final_repository_url, final_repository_name)
       analysis
     end
 
     private
 
-    def generate_remediation_plan(analysis, repository_url)
+    def generate_remediation_plan(analysis, repository_url, repository_name)
       plan = []
 
       analysis[:missing_tags].each do |tag, digest|
@@ -49,7 +53,7 @@ module Equilibrium
           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|
@@ -59,7 +63,7 @@ module Equilibrium
           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|
@@ -68,14 +72,12 @@ module Equilibrium
           tag: tag,
           digest: digest,
           command: "gcloud container images untag #{repository_url}:#{tag}"
-        }
+        }.compact
       end
 
       plan
     end
 
-    private
-
     def find_missing_tags(expected, actual)
       expected.reject { |tag, digest| actual.key?(tag) }
     end

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

data/lib/equilibrium/cli.rb

@@ -1,13 +1,16 @@
 # 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
@@ -19,192 +22,34 @@ module Equilibrium
     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)
-
-      output = {
-        "repository_url" => full_repository_url,
-        "repository_name" => repository_name,
-        "digests" => virtual_tags_result["digests"],
-        "canonical_versions" => virtual_tags_result["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)
-
-      output = {
-        "repository_url" => full_repository_url,
-        "repository_name" => repository_name,
-        "digests" => mutable_tags,
-        "canonical_versions" => 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