equilibrium 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5420df18928550fa411f853968f4b5ac331fbcd3bcc682dce61370c330dd69bc
+  data.tar.gz: 062322ae383ea3aba97d0d60980f8530808e7877e5bb5a6ce311435ec6a86814
+SHA512:
+  metadata.gz: 3900bcb75092a001f250dbe206d4085419435e7d2b370c3a68e57e82619e1a7b014dd32a71510f887e060244c122336f70f946bd836e1c2ef956d5500416d93c
+  data.tar.gz: 2678994b5a362aa3e282618dd49f401aa63d50905f13b0fc74323d0747dc73d076aa872c915843e8d4002a9f1042992e33b5251a5f10cbeb9405d8bb2d29454d

data/.rspec

@@ -0,0 +1 @@
+--format documentation

data/.ruby-version

@@ -0,0 +1 @@
+3.2.8

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+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.0] - 2025-08-05
+
+### Added
+- Initial release of Equilibrium container image validation tool
+- Core CLI with Unix-style command interface (`expected`, `actual`, `analyze`, `catalog`)
+- Support for Google Container Registry (GCR) public repositories
+- Semantic version tag processing and mutable tag computation
+- JSON schema validation for all command outputs
+- Comprehensive analysis and remediation planning functionality
+- Ruby gem packaging with executable installation
+- Thor-based command-line interface with table formatting
+- Dual format output support (summary and JSON) for analysis
+- Catalog generation with canonical version mapping
+- Comprehensive test suite with RSpec
+- 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)
+- **Analysis Engine**: Compares expected vs actual tags with detailed remediation planning
+- **Schema Validation**: Embedded JSON schemas for all data formats
+- **Unix Philosophy**: Composable commands that work well in pipelines
+- **Output Formats**: Multiple output formats including JSON, summary tables, and catalog
+
+### Documentation
+- Comprehensive README with usage examples and API documentation
+- 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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tony Hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,312 @@
+# Equilibrium
+
+[![Gem Version](https://badge.fury.io/rb/equilibrium.svg)](https://badge.fury.io/rb/equilibrium)
+[![GitHub Actions](https://github.com/TonyCTHsu/equilibrium/workflows/CI/badge.svg)](https://github.com/TonyCTHsu/equilibrium/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A container image tool that validates equilibrium between mutable tags and semantic version tags.
+
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [How Equilibrium Solves It](#how-equilibrium-solves-it)
+- [Tag Conversion Logic](#tag-conversion-logic)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Output Formats & Schemas](#output-formats--schemas)
+- [Constraints](#constraints)
+- [Examples](#examples)
+- [License](#license)
+
+## The Problem
+
+Container registries create a web of mutable tags that should point to specific semantic versions, but these relationships can break over time:
+
+**The Challenge:**
+- When you publish `myapp:1.2.3`, registries should automatically create `myapp:latest`, `myapp:1`, `myapp:1.2`
+- But what happens when you later publish `myapp:1.2.4` or `myapp:1.3.0`?
+- Do all the mutable tags get updated correctly?
+- How do you verify the entire tag ecosystem is in equilibrium?
+
+**Real-World Impact:**
+- `latest` might point to an outdated version
+- Major version tags like `1` might miss recent patches
+- Minor version tags like `1.2` might not reflect the latest patch
+- Users pulling `myapp:1` expect the latest `1.x.x`, but get an old version
+
+## How Equilibrium Solves It
+
+Equilibrium validates your container registry's tag ecosystem through a clear data flow:
+
+```mermaid
+flowchart LR
+    A[Registry Query] --> B[All Tags<br/>1.0.0<br/>1.1.0<br/>latest<br/>1<br/>1.1<br/>dev]
+
+    B --> C[Filter<br/>Semantic<br/>Versions]
+    B --> D[Filter<br/>Mutable<br/>Tags]
+
+    C --> E[Semantic Versions<br/>1.0.0<br/>1.1.0]
+    D --> F[Actual Mutable<br/>latest→1.0<br/>1→1.0.0<br/>1.1→1.1.0]
+
+    E --> G[Compute<br/>Expected<br/>Mutable Tags]
+    G --> H[Expected Mutable<br/>latest→1.1<br/>1→1.1.0<br/>1.1→1.1.0]
+
+    H --> I[Compare<br/>Expected vs<br/>Actual]
+    F --> I
+
+    I --> J[Analysis &<br/>Remediation<br/>Update: latest]
+
+    classDef source fill:#e1d5e7
+    classDef process fill:#fff2cc
+    classDef expected fill:#d5e8d4
+    classDef actual fill:#f8cecc
+    classDef result fill:#ffcccc
+
+    class A source
+    class C,D,G,I process
+    class E,H expected
+    class F actual
+    class J result
+```
+
+**Process Steps:**
+1. **Fetch All Tags**: Query registry for complete tag list
+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
+
+## Installation
+
+```bash
+gem install equilibrium
+```
+
+*For other installation methods, see `equilibrium help`*
+
+## Quick Start
+
+```bash
+REPO="gcr.io/datadoghq/apm-inject"
+# 1. Check what mutable tags should exist
+equilibrium expected "$REPO"
+
+# 2. Check what mutable tags actually exist
+equilibrium actual "$REPO"
+
+# 3. Compare and get remediation plan
+equilibrium expected "$REPO" --format json > expected.json
+equilibrium actual "$REPO" --format json > actual.json
+equilibrium analyze --expected expected.json --actual actual.json
+```
+
+*For detailed command options, run `equilibrium help [command]`*
+
+## Tag Conversion Logic
+
+Equilibrium transforms semantic version tags into their expected mutable tag ecosystem:
+
+### Core Principle
+For any semantic version `MAJOR.MINOR.PATCH`, create mutable tags for each component level, pointing to the **highest available version** at that level.
+
+### Detailed Examples
+
+**Scenario 1: Single Version**
+```
+Semantic versions: ["1.0.0"]
+
+Expected mutable tags:
+├── latest → 1.0.0    (highest overall)
+├── 1      → 1.0.0    (highest major 1)
+└── 1.0    → 1.0.0    (highest minor 1.0)
+```
+
+**Scenario 2: Multiple Patch Versions**
+```
+Semantic versions: ["1.0.0", "1.0.1", "1.0.2"]
+
+Expected mutable tags:
+├── latest → 1.0.2    (highest overall)
+├── 1      → 1.0.2    (highest major 1)
+└── 1.0    → 1.0.2    (highest minor 1.0)
+```
+
+**Scenario 3: Multiple Minor Versions**
+```
+Semantic versions: ["1.0.0", "1.0.1", "1.1.0", "1.1.3"]
+
+Expected mutable tags:
+├── latest → 1.1.3    (highest overall)
+├── 1      → 1.1.3    (highest major 1)
+├── 1.0    → 1.0.1    (highest minor 1.0)
+└── 1.1    → 1.1.3    (highest minor 1.1)
+```
+
+**Scenario 4: Multiple Major Versions**
+```
+Semantic versions: ["0.9.0", "1.0.0", "1.2.3", "2.0.0", "2.1.0"]
+
+Expected mutable tags:
+├── latest → 2.1.0    (highest overall)
+├── 0      → 0.9.0    (highest major 0)
+├── 0.9    → 0.9.0    (highest minor 0.9)
+├── 1      → 1.2.3    (highest major 1)
+├── 1.0    → 1.0.0    (highest minor 1.0)
+├── 1.2    → 1.2.3    (highest minor 1.2)
+├── 2      → 2.1.0    (highest major 2)
+├── 2.0    → 2.0.0    (highest minor 2.0)
+└── 2.1    → 2.1.0    (highest minor 2.1)
+```
+
+**Scenario 5: Pre-release and Non-semantic Tags (Filtered Out)**
+```
+All tags: ["1.0.0", "1.1.0-beta", "1.1.0-rc1", "1.1.0", "latest", "dev"]
+Semantic versions: ["1.0.0", "1.1.0"]  # Pre-releases and existing mutable tags filtered
+
+Expected mutable tags:
+├── latest → 1.1.0    (highest overall)
+├── 1      → 1.1.0    (highest major 1)
+├── 1.0    → 1.0.0    (highest minor 1.0)
+└── 1.1    → 1.1.0    (highest minor 1.1)
+```
+
+## Output Formats & Schemas
+
+### JSON Format
+All commands output structured JSON following validated schemas (see [schemas](lib/equilibrium/schemas/)):
+
+**Expected/Actual Commands** ([schema](lib/equilibrium/schemas/expected_actual.rb)):
+```json
+{
+  "repository_url": "gcr.io/project/image",
+  "repository_name": "image",
+  "digests": {
+    "latest": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
+    "1": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c",
+    "1.2": "sha256:5fcfe7ac14f6eeb0fe086ac7021d013d764af573b8c2d98113abf26b4d09b58c"
+  },
+  "canonical_versions": {
+    "latest": "1.2.3",
+    "1": "1.2.3",
+    "1.2": "1.2.3"
+  }
+}
+```
+
+**Analyze Command** ([schema](lib/equilibrium/schemas/analyzer_output.rb)):
+```json
+{
+  "repository_url": "gcr.io/project/image",
+  "expected_count": 3,
+  "actual_count": 2,
+  "missing_tags": {
+    "1.2": "sha256:abc123ef456789012345678901234567890123456789012345678901234567890"
+  },
+  "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"
+    }
+  ]
+}
+```
+
+**Catalog Command** ([schema](lib/equilibrium/schemas/catalog.rb)):
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+### Summary Format
+Human-readable table format for quick visual inspection.
+
+## Constraints
+
+- **Registry Support**: Public Google Container Registry (GCR) only
+- **Tag Format**: Only processes semantic version tags (MAJOR.MINOR.PATCH)
+- **URL Format**: Requires full repository URLs: `[REGISTRY_HOST]/[NAMESPACE]/[REPOSITORY]`
+
+## Examples
+
+### Example 1: Perfect Equilibrium
+```bash
+$ equilibrium expected gcr.io/google-containers/pause
+# Shows: latest→3.9, 3→3.9, 3.9→3.9
+
+$ equilibrium actual gcr.io/google-containers/pause
+# Shows: latest→3.9, 3→3.9, 3.9→3.9
+
+$ equilibrium analyze --expected expected.json --actual actual.json
+# Status: ✅ in_equilibrium
+```
+
+### 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)
+
+$ 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
+```
+
+### Example 3: Automation Pipeline
+```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
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:standard, :spec]

data/equilibrium

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Equilibrium - Container tag validation tool
+# Ruby implementation entry point
+
+require_relative "lib/equilibrium/cli"
+
+Equilibrium::CLI.start(ARGV)

data/exe/equilibrium

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/equilibrium/cli"
+
+Equilibrium::CLI.start(ARGV)

data/lib/equilibrium/analyzer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Equilibrium
+  class Analyzer
+    def initialize
+    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
+      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}'"
+      end
+
+      final_repository_url = expected_url
+
+      analysis = {
+        repository_url: final_repository_url,
+        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
+    end
+
+    private
+
+    def find_missing_tags(expected, actual)
+      expected.reject { |tag, digest| actual.key?(tag) }
+    end
+
+    def find_unexpected_tags(expected, actual)
+      actual.reject { |tag, _| expected.key?(tag) }
+    end
+
+    def find_mismatched_tags(expected, actual)
+      mismatched = {}
+      expected.each do |tag, expected_digest|
+        if actual.key?(tag) && actual[tag] != expected_digest
+          mismatched[tag] = {
+            expected: expected_digest,
+            actual: actual[tag]
+          }
+        end
+      end
+      mismatched
+    end
+
+    def determine_status(expected, actual)
+      return "perfect" if expected == actual
+      return "mismatched" if find_mismatched_tags(expected, actual).any?
+      return "missing_tags" if find_missing_tags(expected, actual).any?
+      return "extra_tags" if find_unexpected_tags(expected, actual).any?
+
+      "perfect"  # Default to perfect if no differences found
+    end
+  end
+end

data/lib/equilibrium/catalog_builder.rb

@@ -0,0 +1,45 @@
+# 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
+      repository_name = data["repository_name"]
+      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 = {
+        "images" => images
+      }
+
+      validate_catalog(catalog)
+      catalog
+    end
+
+    private
+
+    def validate_catalog(catalog)
+      schemer = JSONSchemer.schema(Equilibrium::Schemas::CATALOG)
+      errors = schemer.validate(catalog).to_a
+
+      unless errors.empty?
+        raise Error, "Catalog validation failed: #{errors.map(&:to_s).join(", ")}"
+      end
+    end
+  end
+end