storage-guardian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d29b5d8b123281c76397d7cad89c3c4cca61ba4e1538c708a6cf7d495b589315
+  data.tar.gz: 7b2fafef38ba2b9821ae407cba74546c11c75861caf0be67edeae2ec3d3ae0a2
+SHA512:
+  metadata.gz: 84d013eed13183f67f266f4b1014064a0bd7d93c437c2c15054ba1a8ff67f94792374fd5cbc1f0f607f7fd7fccaf1b65081fff6f31c7ab46582549bcc6410a7d
+  data.tar.gz: e9c9e5ff18fe07b0fed185476fc735816166685e98cf25c2207f50a4df424da14b86290ff4abc3ed2d6e3414df0ccbd33a2b959e8084376fa826528d61953b69

data/README.md

@@ -0,0 +1,35 @@
+# Storage Guardian
+
+Storage conservation guardian — duplicate detection, bloat detection, cold file detection, and budget tracking.
+
+## Installation
+
+```bash
+gem install storage-guardian
+```
+
+## Usage
+
+```ruby
+require "storage_guardian"
+
+# Quick scan
+report = StorageGuardian.scan("/path/to/project")
+puts report
+
+# With custom budget
+budget = StorageGuardian::Budget.new(max_file_size_mb: 50, max_dir_size_mb: 500)
+report = StorageGuardian.scan("/path/to/project", budget: budget, cold_threshold_days: 60)
+puts report.summary
+```
+
+## Features
+
+- **Duplicate Detection** — SHA256 hash-based, groups identical files
+- **Bloat Detection** — oversized files and directories vs budget
+- **Cold File Detection** — files not modified in N days
+- **Budget Tracking** — configurable limits
+
+## License
+
+MIT

data/lib/storage_guardian/bloat_detector.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StorageGuardian
+  class BloatDetector
+    def initialize(entries, budget)
+      @entries = entries
+      @budget  = budget
+    end
+
+    def detect
+      findings = []
+
+      # Oversized files
+      max_file = @budget.limit_for(:max_file_size_mb) * 1024 * 1024
+      @entries.each do |e|
+        if e.size > max_file
+          findings << {
+            type:     :oversized_file,
+            severity: :high,
+            path:     e.path,
+            size_mb:  (e.size / 1024.0 / 1024.0).round(2),
+            limit_mb: @budget.limit_for(:max_file_size_mb),
+            message:  "File #{e.path} is #{(e.size / 1024.0 / 1024.0).round(2)}MB (limit: #{@budget.limit_for(:max_file_size_mb)}MB)"
+          }
+        end
+      end
+
+      # Bloated directories
+      max_dir = @budget.limit_for(:max_dir_size_mb) * 1024 * 1024
+      dir_sizes = @entries.each_with_object(Hash.new(0)) { |e, h| h[File.dirname(e.path)] += e.size }
+      dir_sizes.each do |dir, size|
+        if size > max_dir
+          findings << {
+            type:     :bloated_directory,
+            severity: :medium,
+            path:     dir,
+            size_mb:  (size / 1024.0 / 1024.0).round(2),
+            limit_mb: @budget.limit_for(:max_dir_size_mb),
+            message:  "Directory #{dir} is #{(size / 1024.0 / 1024.0).round(2)}MB (limit: #{@budget.limit_for(:max_dir_size_mb)}MB)"
+          }
+        end
+      end
+
+      findings
+    end
+  end
+end

data/lib/storage_guardian/budget.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module StorageGuardian
+  class Budget
+    DEFAULTS = {
+      max_file_size_mb:     100,
+      max_dir_size_mb:      1024,
+      max_file_count:       10_000,
+      max_duplicate_ratio:  0.1
+    }.freeze
+
+    attr_reader :limits
+
+    def initialize(limits = {})
+      @limits = DEFAULTS.merge(limits.transform_keys(&:to_sym))
+    end
+
+    def limit_for(key)
+      @limits[key.to_sym]
+    end
+  end
+end

data/lib/storage_guardian/cold_detector.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module StorageGuardian
+  class ColdDetector
+    def initialize(entries, threshold_days)
+      @entries         = entries
+      @threshold_days  = threshold_days
+      @cutoff          = Time.now - (threshold_days * 86400)
+    end
+
+    def detect
+      @entries.select { |e| e.mtime < @cutoff }.map do |e|
+        {
+          type:          :cold_file,
+          severity:      :low,
+          path:          e.path,
+          size_mb:       (e.size / 1024.0 / 1024.0).round(2),
+          last_modified: e.mtime,
+          days_old:      ((Time.now - e.mtime) / 86400).round,
+          message:       "File #{e.path} not modified for #{((Time.now - e.mtime) / 86400).round} days (#{(e.size / 1024.0 / 1024.0).round(2)}MB)"
+        }
+      end
+    end
+  end
+end

data/lib/storage_guardian/duplicate_detector.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module StorageGuardian
+  class DuplicateDetector
+    def initialize(entries)
+      @entries = entries
+    end
+
+    # Returns groups of entries that share the same content hash
+    def detect
+      size_groups = @entries.group_by { |e| e.size }
+      size_groups.reject! { |size, _| size == 0 }
+
+      groups = []
+      size_groups.each_value do |group|
+        next if group.size < 2
+
+        hashed = group.map { |e| [e, compute_hash(e.path)] }
+        hash_groups = hashed.group_by { |_, h| h }
+
+        hash_groups.each_value do |hash_group|
+          next if hash_group.size < 2
+          groups << hash_group.map { |entry, _| entry }
+        end
+      end
+      groups
+    end
+
+    private
+
+    def compute_hash(path)
+      Digest::SHA256.file(path).hexdigest
+    rescue Errno::ENOENT, Errno::EACCES
+      Digest::SHA256.hexdigest(path)
+    end
+  end
+end

data/lib/storage_guardian/report.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StorageGuardian
+  class Report
+    attr_reader :root, :entries, :duplicates, :bloat, :cold
+
+    def initialize(root, entries, duplicates, bloat, cold)
+      @root       = root
+      @entries    = entries
+      @duplicates = duplicates
+      @bloat      = bloat
+      @cold       = cold
+    end
+
+    def total_size
+      @entries.sum(&:size)
+    end
+
+    def duplicate_size
+      @duplicates.sum { |group| group.sum(&:size) - group.first.size }
+    end
+
+    def summary
+      {
+        total_files:      @entries.size,
+        total_size_mb:    (total_size / 1024.0 / 1024.0).round(2),
+        duplicate_groups: @duplicates.size,
+        duplicate_size_mb: (duplicate_size / 1024.0 / 1024.0).round(2),
+        bloat_findings:   @bloat.size,
+        cold_files:       @cold.size
+      }
+    end
+
+    def to_s
+      lines = []
+      lines << "=== Storage Guardian Report ==="
+      lines << "Root: #{@root}"
+      s = summary
+      lines << "Files: #{s[:total_files]} | Size: #{s[:total_size_mb]}MB"
+      lines << "Duplicates: #{s[:duplicate_groups]} groups (#{s[:duplicate_size_mb]}MB wasted)"
+      lines << "Bloat findings: #{s[:bloat_findings]}"
+      lines << "Cold files: #{s[:cold_files]}"
+      lines << ""
+
+      if @duplicates.any?
+        lines << "--- Duplicates ---"
+        @duplicates.each do |group|
+          lines << "  #{group.size} copies: #{group.map(&:path).join(', ')}"
+        end
+      end
+
+      if @bloat.any?
+        lines << "--- Bloat ---"
+        @bloat.each { |b| lines << "  [#{b[:severity].upcase}] #{b[:message]}" }
+      end
+
+      if @cold.any?
+        lines << "--- Cold Files (#{@cold.size}) ---"
+        @cold.first(5).each { |c| lines << "  #{c[:message]}" }
+        lines << "  ... and #{@cold.size - 5} more" if @cold.size > 5
+      end
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/storage_guardian/scanner.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module StorageGuardian
+  Entry = Struct.new(:path, :size, :mtime, :hash, keyword_init: true)
+
+  class Scanner
+    def initialize(root_path)
+      @root = root_path
+    end
+
+    def scan
+      entries = []
+      return entries unless File.directory?(@root)
+
+      Dir.glob(File.join(@root, "**", "*"), File::FNM_DOTMATCH).each do |path|
+        next if File.directory?(path)
+        next if File.symlink?(path)
+
+        begin
+          stat = File.stat(path)
+          entries << Entry.new(
+            path:   path,
+            size:   stat.size,
+            mtime:  stat.mtime,
+            hash:   nil  # computed lazily by DuplicateDetector
+          )
+        rescue Errno::ENOENT, Errno::EACCES
+          next
+        end
+      end
+      entries
+    end
+  end
+end

data/lib/storage_guardian.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "storage_guardian/budget"
+require_relative "storage_guardian/scanner"
+require_relative "storage_guardian/duplicate_detector"
+require_relative "storage_guardian/bloat_detector"
+require_relative "storage_guardian/cold_detector"
+require_relative "storage_guardian/report"
+
+module StorageGuardian
+  class Error < StandardError; end
+
+  def self.scan(path, budget: nil, cold_threshold_days: 90)
+    budget ||= Budget.new
+    scanner = Scanner.new(path)
+    entries = scanner.scan
+
+    duplicates = DuplicateDetector.new(entries).detect
+    bloat     = BloatDetector.new(entries, budget).detect
+    cold      = ColdDetector.new(entries, cold_threshold_days).detect
+
+    Report.new(path, entries, duplicates, bloat, cold)
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: storage-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: Detect duplicate files, bloated directories, cold storage candidates,
+  and track storage budgets for Ruby projects.
+email:
+- team@superinstance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/storage_guardian.rb
+- lib/storage_guardian/bloat_detector.rb
+- lib/storage_guardian/budget.rb
+- lib/storage_guardian/cold_detector.rb
+- lib/storage_guardian/duplicate_detector.rb
+- lib/storage_guardian/report.rb
+- lib/storage_guardian/scanner.rb
+homepage: https://github.com/SuperInstance/gem-storage-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: Storage conservation guardian — budget tracking, duplicate detection, bloat
+  detection
+test_files: []