spreen-tracks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b2ac35193a300ae47b6855f8ffa96b23a757bf5615e4b1b121afc603e7e27f8
+  data.tar.gz: 33485326298b1398a225b3cedc8093086ef5f7ec91a7c6674f722be48b481e4b
+SHA512:
+  metadata.gz: 4d942f9e86af2045a0ae213cc7ad472d3de11cf5c220dbf2ba4fe167084ac86e56761789203609d88a8f4b17784ec10aaac65fa09922b6572a927cad9dfaabc6
+  data.tar.gz: 68ddcb70d10c0ddeade905bcaf3393a5d4a9c4d346e117c51477e4e14b4f8b0b2f235f68b030e81d87c58dacebeeb44855bf78ab3a7a22b508cfc6a0d446f841

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,98 @@
+## 1. Environment
+
+- Ruby 4.0.6
+- Gemfile 4.0.16
+- Bundler 4.0.16
+
+## 2. Installation
+
+```command
+$ gem install spreen-tracks
+```
+
+For development, install the dependencies via Gemfile and Bundler:
+
+```command
+$ bundle install
+$ bundle lock --add-checksums
+```
+
+## 3. Execution
+
+Run the command inside your music directory — with no options it dry-runs, printing every rename it would perform without touching a file:
+
+```command
+$ cd ~/Music
+$ track-delimiter
+Target extension is `.m4a`
+========== [DRY RUN] Total File Count to Clean: 4 ==========
+========== [DRY RUN] The delimiters of those files will be replaced with `_` ==========
+========== [DRY RUN] Start! ==========
+========== [DRY RUN] Replacing the delimiter: `./Artist/Album1/1-01 Title.m4a` => `./Artist/Album1/Disc1/01_Title.m4a` ==========
+========== [DRY RUN] Replacing the delimiter: `./Artist/Album1/2-01 Title.m4a` => `./Artist/Album1/Disc2/01_Title.m4a` ==========
+========== [DRY RUN] Replacing the delimiter: `./Artist/Album2/01 Title.m4a` => `./Artist/Album2/01_Title.m4a` ==========
+========== [DRY RUN] Replacing the delimiter: `./Artist/Album2/02 Title.m4a` => `./Artist/Album2/02_Title.m4a` ==========
+========== [DRY RUN] Done! ==========
+========== [DRY RUN] Total Target File Count: 4 ==========
+```
+
+When the plan looks right, execute it with `--mode e`; `--extension` and `--delimiter` override the defaults:
+
+```command
+$ track-delimiter --mode e
+$ track-delimiter --extension .mp3 --delimiter - --mode e
+```
+
+As a library:
+
+```ruby
+require 'spreen_tracks' # or require 'spreen-tracks'
+
+SpreenTracks::Application.run                            # dry run over ./**/*.m4a
+SpreenTracks::Application.run(delimiter: '-', mode: 'e') # execute the renames
+```
+
+## 4. Unit Test
+
+```command
+$ rake
+Run options: --seed 21935
+
+# Running:
+
+..........
+
+Finished in 2.362223s, 4.2333 runs/s, 10.1599 assertions/s.
+
+10 runs, 24 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-tracks.gemspec
+$ gem install ./spreen-tracks-0.1.0.gem
+```

data/exe/track-delimiter

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

data/lib/spreen-tracks.rb

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

data/lib/spreen_tracks/application.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+
+module SpreenTracks
+  # Walks the current directory looking for media files with the given extension
+  # and rewrites their filenames so the space delimiter becomes a configurable
+  # character (and `N-` disc prefixes become `DiscN/` subdirectories).
+  class Application
+    class InvalidModeError < StandardError; end
+
+    # @rbs extension: String
+    # @rbs delimiter: String
+    # @rbs mode: String
+    # @rbs return: void
+    def self.run(extension: '.m4a', delimiter: '_', mode: 'd')
+      instance = new(extension:, delimiter:, mode:)
+      instance.validate_mode!
+      instance.replace
+    end
+
+    # @rbs extension: String
+    # @rbs delimiter: String
+    # @rbs mode: String
+    # @rbs return: void
+    def initialize(extension: '.m4a', delimiter: '_', mode: 'd')
+      @paths     = Dir[File.join('.', '**', "*#{extension}")]
+      @extension = extension
+      @delimiter = delimiter
+      @mode      = mode
+    end
+
+    # @rbs return: void
+    def replace
+      puts "Target extension is `#{extension}`"
+      return announce_empty if paths.empty?
+
+      announce_start
+      apply_renames
+      announce_finish
+    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
+
+    private
+
+    attr_reader :paths, :extension, :delimiter, :mode
+
+    # @rbs return: void
+    def announce_empty
+      puts "========== [#{exec_mode}] No #{extension} Remains =========="
+    end
+
+    # @rbs return: void
+    def announce_start
+      puts "========== [#{exec_mode}] Total File Count to Clean: #{paths.length} =========="
+      puts "========== [#{exec_mode}] The delimiters of those files will be replaced with `#{delimiter}` =========="
+      puts "========== [#{exec_mode}] Start! =========="
+    end
+
+    # @rbs return: void
+    def announce_finish
+      puts "========== [#{exec_mode}] Done! =========="
+      puts "========== [#{exec_mode}] Total Target File Count: #{paths.length} =========="
+    end
+
+    # @rbs return: void
+    def apply_renames
+      file_conversion_map.each do |before, after|
+        puts "========== [#{exec_mode}] Replacing the delimiter: `#{before}` => `#{after}` =========="
+        rename(before, after) if mode == 'e'
+      end
+    end
+
+    # @rbs before: String
+    # @rbs after: String
+    # @rbs return: void
+    def rename(before, after)
+      FileUtils.mkdir_p(File.dirname(after)) if after.match?(%r{Disc\d{1}/})
+      FileUtils.mv(before, after) if before != after
+    end
+
+    # @rbs return: Hash[String, String]
+    def file_conversion_map
+      @file_conversion_map ||= paths.to_h { |path| [path, after(path)] }
+    end
+
+    # @rbs path: String
+    # @rbs return: String
+    def after(path)
+      elements     = path.split('/')
+      elements[-1] = rewrite_filename(elements.last)
+      elements.join('/')
+    end
+
+    # @rbs filename: String
+    # @rbs return: String
+    def rewrite_filename(filename)
+      unless filename.match?(/^\d{1}-/)
+        return filename.gsub(/(?<track_number>\d{2})\s/, "\\k<track_number>#{delimiter}")
+      end
+
+      filename
+        .gsub(/^(?<disc_number>\d{1})-/, 'Disc\k<disc_number>/')
+        .gsub(%r{(?<disc_number>Disc\d{1})/(?<track_number>\d{2})\s}, "\\k<disc_number>/\\k<track_number>#{delimiter}")
+    end
+
+    # @rbs return: String
+    def exec_mode
+      @exec_mode ||= mode == 'e' ? 'EXECUTION' : 'DRY RUN'
+    end
+  end
+end

data/lib/spreen_tracks/cli.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'optparse'
+require_relative 'version'
+require_relative 'application'
+
+module SpreenTracks
+  # Command line interface behind the `track-delimiter` executable:
+  # `track-delimiter [--extension EXT] [--delimiter CHAR] [--mode d|e]`.
+  class CLI
+    MODES = %w[d e].freeze #: Array[String]
+
+    # @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
+      @extension = '.m4a'
+      @delimiter = '_'
+      @mode      = 'd'
+      @action    = :replace_delimiters
+    end
+
+    # @rbs return: Integer
+    def run
+      parser.parse!(argv)
+      __send__(action)
+    rescue Application::InvalidModeError, OptionParser::ParseError => e
+      warn e.message
+      1
+    end
+
+    private
+
+    attr_reader :argv #: Array[String]
+    attr_reader :extension #: String
+    attr_reader :delimiter #: String
+    attr_reader :mode #: String
+    attr_reader :action #: Symbol
+
+    # @rbs return: Integer
+    def replace_delimiters
+      Application.run(extension:, delimiter:, mode:)
+      0
+    end
+
+    # @rbs return: Integer
+    def print_version
+      puts VERSION
+      0
+    end
+
+    # @rbs return: Integer
+    def print_help
+      puts parser
+      0
+    end
+
+    # @rbs return: OptionParser
+    def parser
+      @parser ||= OptionParser.new('Usage: track-delimiter [options]') do |opt|
+        replacement_options(opt)
+        opt.on('--version', 'Print the version') { @action = :print_version }
+        opt.on('-h', '--help', 'Print this help') { @action = :print_help }
+      end
+    end
+
+    # @rbs opt: OptionParser
+    # @rbs return: void
+    def replacement_options(opt)
+      opt.on('--extension EXT', 'Target extension of the files to rename (default: .m4a)') do |value|
+        @extension = value
+      end
+      opt.on('--delimiter CHAR', 'Delimiter that replaces the space after the track number (default: _)') do |value|
+        @delimiter = value
+      end
+      opt.on('--mode MODE', MODES,
+             "Execution mode (#{MODES.join(' or ')}, default: d for dry run; e executes)") do |value|
+        @mode = value
+      end
+    end
+  end
+end

data/lib/spreen_tracks/version.rb

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

data/lib/spreen_tracks.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'spreen_tracks/version'
+require_relative 'spreen_tracks/application'
+require_relative 'spreen_tracks/cli'
+
+# Spreens a music library — the falcon's stoop, then the preen: walks the
+# current directory for media files with a given extension and rewrites their
+# filenames so the space after the track number becomes a configurable
+# delimiter and `N-` disc prefixes become `DiscN/` subdirectories.
+module SpreenTracks
+end

data/sig/generated/spreen-tracks.rbs

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

data/sig/generated/spreen_tracks/application.rbs

@@ -0,0 +1,70 @@
+# Generated from lib/spreen_tracks/application.rb with RBS::Inline
+
+module SpreenTracks
+  # Walks the current directory looking for media files with the given extension
+  # and rewrites their filenames so the space delimiter becomes a configurable
+  # character (and `N-` disc prefixes become `DiscN/` subdirectories).
+  class Application
+    class InvalidModeError < StandardError
+    end
+
+    # @rbs extension: String
+    # @rbs delimiter: String
+    # @rbs mode: String
+    # @rbs return: void
+    def self.run: (?extension: String, ?delimiter: String, ?mode: String) -> void
+
+    # @rbs extension: String
+    # @rbs delimiter: String
+    # @rbs mode: String
+    # @rbs return: void
+    def initialize: (?extension: String, ?delimiter: String, ?mode: String) -> void
+
+    # @rbs return: void
+    def replace: () -> void
+
+    # @rbs return: void
+    def validate_mode!: () -> void
+
+    private
+
+    attr_reader paths: untyped
+
+    attr_reader extension: untyped
+
+    attr_reader delimiter: untyped
+
+    attr_reader mode: untyped
+
+    # @rbs return: void
+    def announce_empty: () -> void
+
+    # @rbs return: void
+    def announce_start: () -> void
+
+    # @rbs return: void
+    def announce_finish: () -> void
+
+    # @rbs return: void
+    def apply_renames: () -> void
+
+    # @rbs before: String
+    # @rbs after: String
+    # @rbs return: void
+    def rename: (String before, String after) -> void
+
+    # @rbs return: Hash[String, String]
+    def file_conversion_map: () -> Hash[String, String]
+
+    # @rbs path: String
+    # @rbs return: String
+    def after: (String path) -> String
+
+    # @rbs filename: String
+    # @rbs return: String
+    def rewrite_filename: (String filename) -> String
+
+    # @rbs return: String
+    def exec_mode: () -> String
+  end
+end

data/sig/generated/spreen_tracks/cli.rbs

@@ -0,0 +1,48 @@
+# Generated from lib/spreen_tracks/cli.rb with RBS::Inline
+
+module SpreenTracks
+  # Command line interface behind the `track-delimiter` executable:
+  # `track-delimiter [--extension EXT] [--delimiter CHAR] [--mode d|e]`.
+  class CLI
+    MODES: Array[String]
+
+    # @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 extension: String
+
+    attr_reader delimiter: String
+
+    attr_reader mode: String
+
+    attr_reader action: Symbol
+
+    # @rbs return: Integer
+    def replace_delimiters: () -> Integer
+
+    # @rbs return: Integer
+    def print_version: () -> Integer
+
+    # @rbs return: Integer
+    def print_help: () -> Integer
+
+    # @rbs return: OptionParser
+    def parser: () -> OptionParser
+
+    # @rbs opt: OptionParser
+    # @rbs return: void
+    def replacement_options: (OptionParser opt) -> void
+  end
+end

data/sig/generated/spreen_tracks/version.rbs

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

data/sig/generated/spreen_tracks.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/spreen_tracks.rb with RBS::Inline
+
+# Spreens a music library — the falcon's stoop, then the preen: walks the
+# current directory for media files with a given extension and rewrites their
+# filenames so the space after the track number becomes a configurable
+# delimiter and `N-` disc prefixes become `DiscN/` subdirectories.
+module SpreenTracks
+end

data/sig/generated/test/application_test.rbs

@@ -0,0 +1,22 @@
+# 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_replace_space_with_underscore_in_dry_run_mode: () -> untyped
+
+  def test_replace_space_with_underscore_in_execution_mode: () -> untyped
+
+  def test_replace_space_with_specific_delimiter_in_execution_mode: () -> untyped
+
+  private
+
+  attr_reader base_dir: untyped
+
+  # @rbs return: Array[String]
+  def fixture_paths: () -> Array[String]
+end

data/sig/generated/test/cli_test.rbs

@@ -0,0 +1,26 @@
+# 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_with_specific_delimiter: () -> untyped
+
+  def test_extension_option: () -> untyped
+
+  def test_invalid_mode: () -> untyped
+
+  def test_version: () -> untyped
+
+  def test_help: () -> untyped
+
+  private
+
+  attr_reader base_dir: untyped
+
+  # @rbs return: Array[String]
+  def fixture_paths: () -> Array[String]
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: spreen-tracks
+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. Walks the current directory
+  for media files with a given extension and rewrites their filenames so the space
+  after the track number becomes a configurable delimiter and `N-` disc prefixes become
+  `DiscN/` subdirectories, dry run by default, via the track-delimiter CLI.
+executables:
+- track-delimiter
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/track-delimiter
+- lib/spreen-tracks.rb
+- lib/spreen_tracks.rb
+- lib/spreen_tracks/application.rb
+- lib/spreen_tracks/cli.rb
+- lib/spreen_tracks/version.rb
+- sig/generated/spreen-tracks.rbs
+- sig/generated/spreen_tracks.rbs
+- sig/generated/spreen_tracks/application.rbs
+- sig/generated/spreen_tracks/cli.rbs
+- sig/generated/spreen_tracks/version.rbs
+- sig/generated/test/application_test.rbs
+- sig/generated/test/cli_test.rbs
+homepage: https://github.com/hayat01sh1da/spreen-tracks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hayat01sh1da/spreen-tracks
+  source_code_uri: https://github.com/hayat01sh1da/spreen-tracks
+  changelog_uri: https://github.com/hayat01sh1da/spreen-tracks/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/hayat01sh1da/spreen-tracks/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 tracks: normalise iTunes-imported filenames with a configurable
+  delimiter.'
+test_files: []