conservation-guardian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 017bb06291f703c2bbb5d8d07d5efac74460f64c2eba4a4ff56b7312453d8f73
+  data.tar.gz: 59d2a23f363cfb005b8f8c6e785cbc1faf25d9d69a7fa938a8875de6428157de
+SHA512:
+  metadata.gz: cbbdcec8e4a8b22a0d9b1468a9948ada0818a9974a533a64cb065369e710180d738d6b9b22b1bd550b9405e0f0557375b642887f6b7cef955b038542c9b1ad70
+  data.tar.gz: 74831bf3304f302668035688043adb4224d69b2f631484610bc81ea80005a4e46c9853aa874f7af783ebf9834e246c42c66a8fa07e7c02ab7e3918ada032a035

data/README.md

@@ -0,0 +1,84 @@
+# Conservation Guardian
+
+Universal **Budget → Profile → Detect → Report** pattern for resource conservation in any Ruby project.
+
+## Installation
+
+```bash
+gem install conservation-guardian
+```
+
+## Usage
+
+```ruby
+require "conservation_guardian"
+
+# Define a budget
+budget = ConservationGuardian::Budget.new(
+  name: "server_resources",
+  limits: { memory_mb: 512, cpu_percent: 80 }
+)
+
+# Profile usage
+profiler = ConservationGuardian::Profiler.new(budget)
+profiler.ingest([
+  { category: :memory_mb, value: 200, label: "worker_1" },
+  { category: :memory_mb, value: 600, label: "worker_2" },
+  { category: :cpu_percent, value: 45, label: "worker_1" },
+  { category: :cpu_percent, value: 95, label: "worker_2" }
+])
+
+# Detect waste
+detector = ConservationGuardian::Detector.new(budget, profiler)
+findings = detector.detect
+
+# Generate report
+report = ConservationGuardian::Report.new(budget, profiler, findings)
+puts report
+
+# Or use the convenience method
+report = ConservationGuardian.analyze(budget: budget, samples: samples)
+```
+
+## API
+
+### Budget
+
+Defines resource limits by category.
+
+```ruby
+budget = ConservationGuardian::Budget.new(name: "limits", limits: { memory: 512 })
+budget.exceeded?(:memory, 600)  # => true
+budget.limit_for(:memory)       # => 512
+```
+
+### Profiler
+
+Tracks usage samples per category.
+
+```ruby
+profiler.ingest({ category: :memory, value: 200, label: "process" })
+profiler.stats_for(:memory)  # => { count:, min:, max:, sum:, avg: }
+```
+
+### Detector
+
+Finds over-budget and anomalous usage.
+
+```ruby
+detector.detect  # => [{ type: :over_budget, severity: :high, ... }]
+```
+
+### Report
+
+Human-readable and machine-parseable output.
+
+```ruby
+report.to_h      # => Hash with budget, stats, findings, summary
+report.to_s      # => formatted text
+report.summary   # => { total_samples:, total_findings:, ... }
+```
+
+## License
+
+MIT

data/lib/conservation_guardian/budget.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConservationGuardian
+  class Budget
+    attr_reader :limits, :name
+
+    # limits: Hash of { category_name => max_value }
+    def initialize(name: "default", limits: {})
+      @name   = name
+      @limits = limits.transform_keys(&:to_sym)
+      freeze
+    end
+
+    def limit_for(category)
+      @limits[category.to_sym]
+    end
+
+    def exceeded?(category, value)
+      max = limit_for(category)
+      return false if max.nil?
+
+      value > max
+    end
+
+    def categories
+      @limits.keys
+    end
+
+    def to_h
+      { name: @name, limits: @limits.dup }
+    end
+  end
+end

data/lib/conservation_guardian/detector.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ConservationGuardian
+  class Detector
+    attr_reader :budget, :profiler
+
+    def initialize(budget, profiler)
+      @budget   = budget
+      @profiler = profiler
+    end
+
+    def detect
+      findings = []
+      findings.concat(detect_over_budget)
+      findings.concat(detect_anomalies)
+      findings
+    end
+
+    private
+
+    def detect_over_budget
+      profiler.over_budget_samples.map do |sample|
+        {
+          type:       :over_budget,
+          severity:   :high,
+          category:   sample[:category],
+          value:      sample[:value],
+          limit:      budget.limit_for(sample[:category]),
+          label:      sample[:label],
+          message:    "#{sample[:label]} (#{sample[:value]}) exceeds limit #{budget.limit_for(sample[:category])} for #{sample[:category]}"
+        }
+      end
+    end
+
+    def detect_anomalies
+      findings = []
+      profiler.samples.map { |s| s[:category] }.uniq.each do |cat|
+        stats = profiler.stats_for(cat)
+        next unless stats && stats[:count] >= 2
+
+        threshold = stats[:avg] * 2
+        profiler.samples.select { |s| s[:category] == cat && s[:value] > threshold }.each do |sample|
+          findings << {
+            type:     :anomaly,
+            severity: :medium,
+            category: cat,
+            value:    sample[:value],
+            avg:      stats[:avg],
+            label:    sample[:label],
+            message:  "#{sample[:label]} (#{sample[:value]}) is >2x the average (#{stats[:avg].round(2)}) for #{cat}"
+          }
+        end
+      end
+      findings
+    end
+  end
+end

data/lib/conservation_guardian/profiler.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ConservationGuardian
+  class Profiler
+    attr_reader :samples, :budget
+
+    def initialize(budget)
+      @budget  = budget
+      @samples = []
+    end
+
+    # samples: Array of { category:, value:, label: }
+    # or pass a single sample at a time
+    def ingest(samples)
+      samples = [samples] if samples.is_a?(Hash)
+      samples.each do |s|
+        @samples << {
+          category: s[:category].to_sym,
+          value:    s[:value].to_f,
+          label:    s[:label].to_s,
+          timestamp: Time.now
+        }
+      end
+    end
+
+    def stats_for(category)
+      cat = category.to_sym
+      vals = @samples.select { |s| s[:category] == cat }.map { |s| s[:value] }
+      return nil if vals.empty?
+
+      {
+        count: vals.size,
+        min:   vals.min,
+        max:   vals.max,
+        sum:   vals.sum,
+        avg:   vals.sum / vals.size
+      }
+    end
+
+    def all_stats
+      @samples.map { |s| s[:category] }.uniq.each_with_object({}) do |cat, h|
+        h[cat] = stats_for(cat)
+      end
+    end
+
+    def over_budget_samples
+      @samples.select { |s| @budget.exceeded?(s[:category], s[:value]) }
+    end
+
+    def clear!
+      @samples.clear
+    end
+  end
+end

data/lib/conservation_guardian/report.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ConservationGuardian
+  class Report
+    attr_reader :budget, :profiler, :findings
+
+    def initialize(budget, profiler, findings)
+      @budget   = budget
+      @profiler = profiler
+      @findings = findings
+    end
+
+    def to_h
+      {
+        budget:   budget.to_h,
+        stats:    profiler.all_stats,
+        findings: findings,
+        summary:  summary
+      }
+    end
+
+    def summary
+      {
+        total_samples: profiler.samples.size,
+        total_findings: findings.size,
+        over_budget: findings.count { |f| f[:type] == :over_budget },
+        anomalies: findings.count { |f| f[:type] == :anomaly },
+        categories_checked: budget.categories.size
+      }
+    end
+
+    def to_s
+      lines = []
+      lines << "=== Conservation Guardian Report ==="
+      lines << "Budget: #{budget.name}"
+      lines << "Samples analyzed: #{summary[:total_samples]}"
+      lines << "Findings: #{summary[:total_findings]} (#{summary[:over_budget]} over budget, #{summary[:anomalies]} anomalies)"
+      lines << ""
+
+      if findings.any?
+        lines << "--- Findings ---"
+        findings.each do |f|
+          lines << "[#{f[:severity].upcase}] #{f[:message]}"
+        end
+      else
+        lines << "✅ No waste detected. All clear!"
+      end
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/conservation_guardian.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "conservation_guardian/budget"
+require_relative "conservation_guardian/profiler"
+require_relative "conservation_guardian/detector"
+require_relative "conservation_guardian/report"
+
+module ConservationGuardian
+  class Error < StandardError; end
+
+  # Convenience: run the full pipeline and return a Report
+  def self.analyze(budget:, samples:)
+    profiler = Profiler.new(budget)
+    profiler.ingest(samples)
+    detector = Detector.new(budget, profiler)
+    findings = detector.detect
+    Report.new(budget, profiler, findings)
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: conservation-guardian
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SuperInstance
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-02 00:00:00.000000000 Z
+dependencies: []
+description: A guardian pattern library that provides budget tracking, usage profiling,
+  waste detection, and conservation reporting for any Ruby project.
+email:
+- team@superinstance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/conservation_guardian.rb
+- lib/conservation_guardian/budget.rb
+- lib/conservation_guardian/detector.rb
+- lib/conservation_guardian/profiler.rb
+- lib/conservation_guardian/report.rb
+homepage: https://github.com/SuperInstance/gem-conservation-guardian
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Universal Budget → Profile → Detect → Report pattern for resource conservation
+test_files: []