spreen-clean 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e66f0b99e7c90e702fa7fbcb8dc08d095d4eb1205ebdf7611242c5511bf6397
+  data.tar.gz: 74b300c46a20ba4c124a371fc808de72d0208089f5106d999578ec1d2ebceaff
+SHA512:
+  metadata.gz: 70301df0f5f2d0576e4bcbb21dc80cd53c2e4170a4d2ff8fde8bc3206f97191f10f0ec5023ca2dc39a7204bd93bd3a0092ba3d5fb6f09d304a9a05c9d2f2b2cc
+  data.tar.gz: 772a05fbb7f89c600777a2a7f96c590956eb03b271d799313f947c4fb4a44846a77872e4ac06874183434f10d06cb50e1c35e49aa66268d0caf9d9f70baa9ca3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 - present @hayat01sh1da
+
+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,114 @@
+## 1. Environment
+
+- Ruby 4.0.6
+- Gemfile 4.0.16
+- Bundler 4.0.16
+
+## 2. Installation
+
+```command
+$ gem install spreen-clean
+```
+
+For development, install the dependencies via Gemfile and Bundler:
+
+```command
+$ bundle install
+$ bundle lock --add-checksums
+```
+
+## 3. Execution
+
+```command
+$ file-clean '*.log' --dirname ./tmp
+Target dirname is /home/hayat01sh1da/workspace/tmp
+========== [DRY RUN] Total File Count to Clean: 2 ==========
+========== [DRY RUN] Start Cleaning *.log ==========
+========== [DRY RUN] Cleaning ./tmp/app.log ==========
+========== [DRY RUN] Cleaning ./tmp/jobs/worker.log ==========
+========== [DRY RUN] Cleaned *.log ==========
+========== [DRY RUN] Total Cleaned File Count: 2 ==========
+```
+
+The dry run above is the default. Once the list looks right, execute the deletion with `--mode e` (this cannot be undone):
+
+```command
+$ file-clean '*.log' --dirname ./tmp --mode e
+Target dirname is /home/hayat01sh1da/workspace/tmp
+========== [EXECUTION] Total File Count to Clean: 2 ==========
+========== [EXECUTION] Start Cleaning *.log ==========
+========== [EXECUTION] Cleaning ./tmp/app.log ==========
+========== [EXECUTION] Cleaning ./tmp/jobs/worker.log ==========
+========== [EXECUTION] Cleaned *.log ==========
+========== [EXECUTION] Total Cleaned File Count: 2 ==========
+```
+
+With no arguments, `file-clean` dry-runs every file under the current directory (`PATTERN` defaults to `*`, `--dirname` to `.`).
+
+Two guardrails back the dry-run default: a dirname resolving to a filesystem root (`/`, `C:\`, ...) is refused before anything is scanned, and when the execution mode matches more than 100 files the CLI asks for an explicit `y` first — pass `--yes` to skip the prompt in scripts:
+
+```command
+$ file-clean '*.log' --dirname ./tmp --mode e
+About to delete 101 files (more than 100). Type `y` to proceed: n
+Aborted the execution mode without deleting anything.
+```
+
+As a library:
+
+```ruby
+require 'spreen_clean' # or require 'spreen-clean'
+
+SpreenClean::Application.run(dirname: './tmp', pattern: '*.log')            # dry run
+SpreenClean::Application.run(dirname: './tmp', pattern: '*.log', mode: 'e') # execute
+
+# The progress log goes to stdout by default; pass any IO to capture it.
+require 'stringio'
+io = StringIO.new
+SpreenClean::Application.run(dirname: './tmp', pattern: '*.log', io:)
+io.string # => "Target dirname is ...\n========== [DRY RUN] ..."
+```
+
+## 4. Unit Test
+
+```command
+$ rake
+Run options: --seed 4809
+
+# Running:
+
+..................
+
+Finished in 13.872874s, 1.2975 runs/s, 4.1088 assertions/s.
+
+18 runs, 57 assertions, 0 failures, 0 errors, 0 skips
+```
+
+## 5. Static Code Analysis
+
+```command
+$ bundle exec rubocop
+Inspecting 12 files
+............
+
+12 files inspected, no offenses detected
+```
+
+## 6. Type Checks
+
+```command
+$ bundle exec rbs-inline --output sig/generated/ .
+🎉 Generated 7 RBS files under sig/generated
+$ bundle exec steep check
+# Type checking files:
+
+..............
+
+No type error detected. 🫖
+```
+
+## 7. Build
+
+```command
+$ gem build spreen-clean.gemspec
+$ gem install ./spreen-clean-0.1.0.gem
+```

data/exe/file-clean

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'spreen_clean'
+
+exit SpreenClean::CLI.start

data/lib/spreen-clean.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Convenience shim so that both `require 'spreen-clean'` (the gem name) and
+# `require 'spreen_clean'` (the conventional path) work.
+require_relative 'spreen_clean'

data/lib/spreen_clean/application.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+
+module SpreenClean
+  # Deletes files in a directory tree matching a glob pattern, with a dry-run
+  # mode that prints what would be removed without touching the filesystem.
+  class Application
+    class InvalidModeError < StandardError; end
+    class RootDirnameError < StandardError; end
+
+    # @rbs dirname: String
+    # @rbs pattern: String
+    # @rbs mode: String
+    # @rbs io: IO
+    # @rbs return: void
+    def self.run(dirname: '.', pattern: '*', mode: 'd', io: $stdout)
+      instance = new(dirname:, pattern:, mode:, io:)
+      instance.validate_mode!
+      instance.validate_dirname!
+      instance.run
+    end
+
+    # @rbs dirname: String
+    # @rbs pattern: String
+    # @rbs mode: String
+    # @rbs io: IO
+    # @rbs return: void
+    def initialize(dirname: '.', pattern: '*', mode: 'd', io: $stdout)
+      @dirname = dirname
+      @pattern = pattern
+      @mode    = mode
+      @io      = io
+    end
+
+    # @rbs return: void
+    def validate_mode!
+      case mode
+      when 'd', 'e'
+        nil
+      else
+        raise InvalidModeError, "#{mode} is invalid mode. Provide either `d`(default) or `e`."
+      end
+    end
+
+    # Refuses filesystem roots (`/`, `C:/`, ...) so a stray `file-clean` can
+    # never sweep an entire drive.
+    # @rbs return: void
+    def validate_dirname!
+      return unless File.dirname(absolute_dirname) == absolute_dirname
+
+      raise RootDirnameError, "#{absolute_dirname} is a filesystem root. Provide a narrower dirname."
+    end
+
+    # Matched lazily so validation can refuse a dirname before any globbing happens.
+    # @rbs return: Array[String]
+    def files
+      @files ||= Dir.glob(File.join(dirname, '**', pattern))
+    end
+
+    # @rbs return: void
+    def run
+      output "Target dirname is #{absolute_dirname}"
+      return announce_empty if files.empty?
+
+      announce_start
+      clean_files
+      announce_finish
+    end
+
+    private
+
+    attr_reader :dirname #: String
+    attr_reader :pattern #: String
+    attr_reader :mode #: String
+    attr_reader :io #: IO
+
+    # @rbs return: String
+    def absolute_dirname
+      @absolute_dirname ||= File.absolute_path(dirname)
+    end
+
+    # @rbs return: void
+    def announce_empty
+      output "========== [#{exec_mode}] No #{pattern} Remains =========="
+    end
+
+    # @rbs return: void
+    def announce_start
+      output "========== [#{exec_mode}] Total File Count to Clean: #{files.length} =========="
+      output "========== [#{exec_mode}] Start Cleaning #{pattern} =========="
+    end
+
+    # @rbs return: void
+    def clean_files
+      files.each { |file| output "========== [#{exec_mode}] Cleaning #{file} ==========" }
+      FileUtils.rm_rf(files) if mode == 'e'
+    end
+
+    # @rbs return: void
+    def announce_finish
+      output "========== [#{exec_mode}] Cleaned #{pattern} =========="
+      output "========== [#{exec_mode}] Total Cleaned File Count: #{files.length} =========="
+    end
+
+    # @rbs return: String
+    def exec_mode
+      @exec_mode ||= mode == 'e' ? 'EXECUTION' : 'DRY RUN'
+    end
+
+    # @rbs message: String
+    # @rbs return: void
+    def output(message)
+      io.puts message
+    end
+  end
+end

data/lib/spreen_clean/cli.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'optparse'
+require_relative 'version'
+require_relative 'application'
+
+module SpreenClean
+  # Command line interface behind the `file-clean` executable:
+  # `file-clean [PATTERN] [--dirname DIR] [--mode d|e] [--yes]`.
+  class CLI
+    MODES = %w[d e].freeze #: Array[String]
+    # The execution mode asks for confirmation above this many matches.
+    BULK_DELETE_THRESHOLD = 100 #: Integer
+
+    # @rbs argv: Array[String]
+    # @rbs return: Integer
+    def self.start(argv = ARGV)
+      new(argv).run
+    end
+
+    # @rbs argv: Array[String]
+    # @rbs return: void
+    def initialize(argv)
+      @argv              = argv.dup
+      @dirname           = '.'
+      @mode              = 'd'
+      @skip_confirmation = false
+      @action            = :clean_files
+    end
+
+    # @rbs return: Integer
+    def run
+      parser.parse!(argv)
+      __send__(action)
+    rescue Application::InvalidModeError, Application::RootDirnameError, OptionParser::ParseError => e
+      warn e.message
+      1
+    end
+
+    private
+
+    attr_reader :argv #: Array[String]
+    attr_reader :dirname #: String
+    attr_reader :mode #: String
+    attr_reader :skip_confirmation #: bool
+    attr_reader :action #: Symbol
+
+    # @rbs return: Integer
+    def clean_files
+      application = Application.new(dirname:, pattern:, mode:)
+      application.validate_mode!
+      application.validate_dirname!
+      unless confirmed?(application)
+        warn 'Aborted the execution mode without deleting anything.'
+        return 1
+      end
+
+      application.run
+      0
+    end
+
+    # Guards the execution mode against oversized sweeps: above
+    # BULK_DELETE_THRESHOLD matches it asks for an explicit `y`, unless
+    # `--yes` was given for scripted use.
+    # @rbs application: Application
+    # @rbs return: bool
+    def confirmed?(application)
+      return true unless mode == 'e'
+      return true if skip_confirmation
+
+      count = application.files.length
+      return true if count <= BULK_DELETE_THRESHOLD
+
+      print "About to delete #{count} files (more than #{BULK_DELETE_THRESHOLD}). Type `y` to proceed: "
+      answer = $stdin.gets
+      return false if answer.nil?
+
+      %w[y yes].include?(answer.strip.downcase)
+    end
+
+    # @rbs return: Integer
+    def print_version
+      puts VERSION
+      0
+    end
+
+    # @rbs return: Integer
+    def print_help
+      puts parser
+      0
+    end
+
+    # @rbs return: String
+    def pattern
+      argv.shift || '*'
+    end
+
+    # @rbs return: OptionParser
+    def parser
+      @parser ||= OptionParser.new('Usage: file-clean [PATTERN] [options]') do |opt|
+        opt.on('--dirname DIR', 'Directory tree to clean (default: .)') { |value| @dirname = value }
+        opt.on('--mode MODE', MODES,
+               "Operation mode (#{MODES.join(' or ')}; d = dry run, e = execute, default: d)") { |value| @mode = value }
+        opt.on('--yes', 'Skip the bulk-delete confirmation in the execution mode') { @skip_confirmation = true }
+        opt.on('--version', 'Print the version') { @action = :print_version }
+        opt.on('-h', '--help', 'Print this help') { @action = :print_help }
+      end
+    end
+  end
+end

data/lib/spreen_clean/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module SpreenClean
+  VERSION = '0.1.0'
+end

data/lib/spreen_clean.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'spreen_clean/version'
+require_relative 'spreen_clean/application'
+require_relative 'spreen_clean/cli'
+
+# Spreens your workspace clean — the falcon's stoop, then the preen: deletes
+# files in a directory tree matching a glob pattern, defaulting to a dry run
+# that prints what would be removed before anything is touched.
+module SpreenClean
+end

data/sig/generated/spreen-clean.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/spreen-clean.rb with RBS::Inline
+

data/sig/generated/spreen_clean/application.rbs

@@ -0,0 +1,74 @@
+# Generated from lib/spreen_clean/application.rb with RBS::Inline
+
+module SpreenClean
+  # Deletes files in a directory tree matching a glob pattern, with a dry-run
+  # mode that prints what would be removed without touching the filesystem.
+  class Application
+    class InvalidModeError < StandardError
+    end
+
+    class RootDirnameError < StandardError
+    end
+
+    # @rbs dirname: String
+    # @rbs pattern: String
+    # @rbs mode: String
+    # @rbs io: IO
+    # @rbs return: void
+    def self.run: (?dirname: String, ?pattern: String, ?mode: String, ?io: IO) -> void
+
+    # @rbs dirname: String
+    # @rbs pattern: String
+    # @rbs mode: String
+    # @rbs io: IO
+    # @rbs return: void
+    def initialize: (?dirname: String, ?pattern: String, ?mode: String, ?io: IO) -> void
+
+    # @rbs return: void
+    def validate_mode!: () -> void
+
+    # Refuses filesystem roots (`/`, `C:/`, ...) so a stray `file-clean` can
+    # never sweep an entire drive.
+    # @rbs return: void
+    def validate_dirname!: () -> void
+
+    # Matched lazily so validation can refuse a dirname before any globbing happens.
+    # @rbs return: Array[String]
+    def files: () -> Array[String]
+
+    # @rbs return: void
+    def run: () -> void
+
+    private
+
+    attr_reader dirname: String
+
+    attr_reader pattern: String
+
+    attr_reader mode: String
+
+    attr_reader io: IO
+
+    # @rbs return: String
+    def absolute_dirname: () -> String
+
+    # @rbs return: void
+    def announce_empty: () -> void
+
+    # @rbs return: void
+    def announce_start: () -> void
+
+    # @rbs return: void
+    def clean_files: () -> void
+
+    # @rbs return: void
+    def announce_finish: () -> void
+
+    # @rbs return: String
+    def exec_mode: () -> String
+
+    # @rbs message: String
+    # @rbs return: void
+    def output: (String message) -> void
+  end
+end

data/sig/generated/spreen_clean/cli.rbs

@@ -0,0 +1,57 @@
+# Generated from lib/spreen_clean/cli.rb with RBS::Inline
+
+module SpreenClean
+  # Command line interface behind the `file-clean` executable:
+  # `file-clean [PATTERN] [--dirname DIR] [--mode d|e] [--yes]`.
+  class CLI
+    MODES: Array[String]
+
+    # The execution mode asks for confirmation above this many matches.
+    BULK_DELETE_THRESHOLD: Integer
+
+    # @rbs argv: Array[String]
+    # @rbs return: Integer
+    def self.start: (?Array[String] argv) -> Integer
+
+    # @rbs argv: Array[String]
+    # @rbs return: void
+    def initialize: (Array[String] argv) -> void
+
+    # @rbs return: Integer
+    def run: () -> Integer
+
+    private
+
+    attr_reader argv: Array[String]
+
+    attr_reader dirname: String
+
+    attr_reader mode: String
+
+    attr_reader skip_confirmation: bool
+
+    attr_reader action: Symbol
+
+    # @rbs return: Integer
+    def clean_files: () -> Integer
+
+    # Guards the execution mode against oversized sweeps: above
+    # BULK_DELETE_THRESHOLD matches it asks for an explicit `y`, unless
+    # `--yes` was given for scripted use.
+    # @rbs application: Application
+    # @rbs return: bool
+    def confirmed?: (Application application) -> bool
+
+    # @rbs return: Integer
+    def print_version: () -> Integer
+
+    # @rbs return: Integer
+    def print_help: () -> Integer
+
+    # @rbs return: String
+    def pattern: () -> String
+
+    # @rbs return: OptionParser
+    def parser: () -> OptionParser
+  end
+end

data/sig/generated/spreen_clean/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/spreen_clean/version.rb with RBS::Inline
+
+module SpreenClean
+  VERSION: ::String
+end

data/sig/generated/spreen_clean.rbs

@@ -0,0 +1,7 @@
+# Generated from lib/spreen_clean.rb with RBS::Inline
+
+# Spreens your workspace clean — the falcon's stoop, then the preen: deletes
+# files in a directory tree matching a glob pattern, defaulting to a dry run
+# that prints what would be removed before anything is touched.
+module SpreenClean
+end

data/sig/generated/test/application_test.rbs

@@ -0,0 +1,31 @@
+# Generated from test/application_test.rb with RBS::Inline
+
+class ApplicationTest < Minitest::Test
+  def setup: () -> untyped
+
+  def teardown: () -> untyped
+
+  def test_invalid_mode: () -> untyped
+
+  def test_run_in_dry_run_mode_with_default_mode: () -> untyped
+
+  def test_run_in_dry_run_mode_with_explicit_d_mode: () -> untyped
+
+  def test_run_in_exec_mode: () -> untyped
+
+  def test_run_announces_the_dry_run_progress: () -> untyped
+
+  def test_run_announces_the_execution_progress: () -> untyped
+
+  def test_run_announces_empty_when_nothing_matches: () -> untyped
+
+  def test_run_refuses_a_filesystem_root: () -> untyped
+
+  private
+
+  attr_reader dirname: untyped
+
+  attr_reader pattern: untyped
+
+  attr_reader io: untyped
+end

data/sig/generated/test/cli_test.rbs

@@ -0,0 +1,41 @@
+# Generated from test/cli_test.rb with RBS::Inline
+
+class CLITest < Minitest::Test
+  def setup: () -> untyped
+
+  def teardown: () -> untyped
+
+  def test_dry_run_by_default: () -> untyped
+
+  def test_execution_mode: () -> untyped
+
+  def test_default_pattern_matches_everything: () -> untyped
+
+  def test_invalid_mode: () -> untyped
+
+  def test_root_dirname_refused: () -> untyped
+
+  def test_bulk_execution_aborts_when_declined: () -> untyped
+
+  def test_bulk_execution_proceeds_when_confirmed: () -> untyped
+
+  def test_bulk_execution_skips_confirmation_with_yes_flag: () -> untyped
+
+  def test_version: () -> untyped
+
+  def test_help: () -> untyped
+
+  private
+
+  attr_reader dirname: untyped
+
+  attr_reader pattern: untyped
+
+  # Tops the fixture up beyond BULK_DELETE_THRESHOLD (101 files in total).
+  def make_bulk_files: () -> untyped
+
+  # @rbs input: String
+  # @rbs &block: () -> [String, String]
+  # @rbs return: [String, String]
+  def with_stdin: (String input) { () -> [ String, String ] } -> [ String, String ]
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: spreen-clean
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- hayat01sh1da
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Spreen — the falcon's stoop, then the preen. Deletes files in a directory
+  tree matching a glob pattern via the file-clean CLI, defaulting to a dry-run mode
+  that prints every file that would be removed; pass `--mode e` to actually delete
+  them.
+executables:
+- file-clean
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/file-clean
+- lib/spreen-clean.rb
+- lib/spreen_clean.rb
+- lib/spreen_clean/application.rb
+- lib/spreen_clean/cli.rb
+- lib/spreen_clean/version.rb
+- sig/generated/spreen-clean.rbs
+- sig/generated/spreen_clean.rbs
+- sig/generated/spreen_clean/application.rbs
+- sig/generated/spreen_clean/cli.rbs
+- sig/generated/spreen_clean/version.rbs
+- sig/generated/test/application_test.rbs
+- sig/generated/test/cli_test.rbs
+homepage: https://github.com/hayat01sh1da/spreen-clean
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hayat01sh1da/spreen-clean
+  source_code_uri: https://github.com/hayat01sh1da/spreen-clean
+  changelog_uri: https://github.com/hayat01sh1da/spreen-clean/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/hayat01sh1da/spreen-clean/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Spreen your workspace: delete files matching a glob pattern, dry run first.'
+test_files: []