kutils 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1a0dbd2603aa516690550052fbf03ca008593c92e73f93e5eef44996b4dce20
+  data.tar.gz: c78052b564ced2d8dca8fd04ad0e84620a11f187d477ca312a7d24191a8cc667
+SHA512:
+  metadata.gz: 18dc7a53a371f61801d9cd3708fede1ec8c199f991787ab86ef43d4984809ebe8cac581189d066688d7c7e6b95cba637cad1ae712d876078bc4364cdd1321167
+  data.tar.gz: 8d3722ff06a964b27f008f232d3a7967f3de0a56b71d921837b2f05a7bb82c94779ec241e03ffdd9deb1efc62c91005e7656a15cc0f9c6e63b82826dfc3b01d6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kk
+
+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,97 @@
+# kutils
+
+> Ruby 通用工具库 —— 统一命名空间、极简高效、自动化工程最佳实践
+
+---
+
+## 项目简介
+
+Kutils 是一个现代 Ruby 通用工具库，涵盖字符串、时间、文件、加解密、数组、验证、调试、DSL、格式化等常用场景，全部模块统一挂载于 `Kutils` 命名空间，极易集成与扩展。支持自动化测试、文档、CI/CD、安全扫描与 Gem 发布。
+
+---
+
+## 特性
+
+- 统一命名空间：`Kutils::模块名.方法`
+- 覆盖常用开发场景（字符串、时间、文件、加密、数组、验证等）
+- 代码与文档，支持黑白主题切换
+- 自动化测试、代码规范、CI/CD、文档部署、安全扫描
+- 支持 Ruby 2.7+，兼容 Ruby 3.x
+- 可作为 Gem 直接集成
+
+---
+
+## 安装
+
+```sh
+git clone https://github.com/kk/kutils.git
+cd kutils
+bundle install
+```
+
+或在你的 Gemfile 中添加（发布后）：
+
+```ruby
+gem 'kutils', git: 'https://github.com/kk/kutils.git'
+```
+
+---
+
+## 用法示例
+
+```ruby
+require 'kutils'
+
+puts Kutils::StringUtils.camelize('hello_world') # => HelloWorld
+puts Kutils::TimeUtils.now_iso8601
+puts Kutils::FileUtils.safe_read('foo.txt')
+puts Kutils::CryptoUtils.md5('abc')
+puts Kutils::ArrayUtils.deep_flatten([[1], [2]])
+puts Kutils::Validator.email?('foo@bar.com')
+Kutils::DebugUtils.log({foo: 1})
+Kutils::DSLBuilder.new { task('deploy') { puts 'Deploying...' } }
+puts Kutils::FormatUtils.markdown_title('Hello')
+```
+
+更多用法见 [docs/USAGE.md](docs/USAGE.md)
+
+---
+
+## API 文档
+
+- [API 参考 (Markdown)](docs/API.md)
+- [自动化 YARD API 文档（支持黑白主题切换）](https://your-gh-pages-url/yardoc/index.html)
+
+---
+
+## 测试与质量保障
+
+- RSpec 单元测试覆盖所有模块
+- RuboCop 代码规范
+- GitHub Actions 自动化测试、文档部署、安全扫描
+- Bundler Audit & Dependabot 依赖安全
+
+本地运行：
+
+```sh
+bundle exec rspec      # 运行所有测试
+bundle exec rubocop    # 代码规范检查
+rake yard              # 生成 API 文档
+```
+
+---
+
+## 贡献指南
+
+欢迎 PR、Issue 及建议！
+
+1. Fork & 新建分支
+2. 保持代码风格与注释一致
+3. 补充/完善测试
+4. 提交 PR 前确保 CI 通过
+
+---
+
+## 许可证
+
+MIT License. © 2025 kk

data/lib/kutils.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+require 'zeitwerk'
+require_relative 'utils/version'
+
+module Kutils
+  VERSION = ::Kutils::VERSION
+end
+
+loader = Zeitwerk::Loader.for_gem
+loader.push_dir(File.expand_path('utils', __dir__))
+loader.setup

data/lib/utils/array_utils.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # ArrayUtils provides array flattening and safe mapping utilities.
+  module ArrayUtils
+    # Deeply flatten an array (1 level at a time)
+    # @param arr [Array]
+    # @return [Array]
+    def self.deep_flatten(arr)
+      arr.flatten(1) while arr.any? { |a| a.is_a?(Array) }
+      arr
+    end
+
+    # Map array safely (nil returns empty array)
+    # @param arr [Array, nil]
+    # @yield [item]
+    # @return [Array]
+    def self.safe_map(arr, &block)
+      (arr || []).map(&block)
+    end
+  end
+end

data/lib/utils/crypto_utils.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+require 'digest'
+require 'base64'
+require 'openssl'
+
+module Kutils
+  # CryptoUtils provides common hash and encoding utilities.
+  module CryptoUtils
+    # Calculate MD5 hex digest
+    # @param str [String]
+    # @return [String]
+    def self.md5(str)
+      Digest::MD5.hexdigest(str)
+    end
+
+    # Calculate HMAC-SHA256 hex digest
+    # @param data [String]
+    # @param key [String]
+    # @return [String]
+    def self.hmac_sha256(data, key)
+      OpenSSL::HMAC.hexdigest('SHA256', key, data)
+    end
+
+    # Base64 encode string
+    # @param str [String]
+    # @return [String]
+    def self.base64_encode(str)
+      Base64.strict_encode64(str)
+    end
+  end
+end

data/lib/utils/debug_utils.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+require 'pp'
+
+module Kutils
+  # DebugUtils provides quick debug print utilities.
+  module DebugUtils
+    # Pretty print object with optional label
+    # @param obj [Object]
+    # @param label [String, nil]
+    # @return [void]
+    def self.log(obj, label = nil)
+      puts "==== #{label || 'DEBUG'} ===="
+      pp obj
+    end
+  end
+end

data/lib/utils/dsl_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # DSLBuilder provides a simple DSL for configuration or scripting.
+  class DSLBuilder
+    # @yield DSL block
+    def initialize(&block)
+      instance_eval(&block) if block_given?
+    end
+
+    # Define a task with a name and block
+    # @param name [String]
+    # @yield Block to execute for the task
+    def task(name, &block)
+      puts "Define task: #{name}"
+      block.call if block_given?
+    end
+  end
+end

data/lib/utils/file_utils.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # FileUtils provides safe file and directory operations.
+  # ⚠️ 注意：如与 Ruby 标准库 FileUtils 冲突，可改名为 SafeFileUtils。
+  module FileUtils
+    # Safely read file content if file exists
+    # @param path [String]
+    # @return [String, nil]
+    # @example
+    #   Kutils::FileUtils.safe_read('foo.txt')
+    def self.safe_read(path)
+      File.exist?(path) ? File.read(path) : nil
+    end
+
+    # Create directory if not exists
+    # @param path [String]
+    # @return [void]
+    # @example
+    #   Kutils::FileUtils.mkdir_p('tmp/data')
+    def self.mkdir_p(path)
+      Dir.mkdir(path) unless Dir.exist?(path)
+    end
+  end
+end

data/lib/utils/format_utils.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # FormatUtils provides formatting helpers for markdown and colored text.
+  module FormatUtils
+    # Format a markdown title
+    # @param title [String]
+    # @return [String]
+    def self.markdown_title(title)
+      "# #{title}\n\n"
+    end
+
+    # Colorize text in terminal
+    # @param text [String]
+    # @param color [Symbol]
+    # @return [String]
+    def self.color_text(text, color)
+      "\e[#{color_code(color)}m#{text}\e[0m"
+    end
+
+    # Get ANSI color code
+    # @param color [Symbol]
+    # @return [Integer]
+    def self.color_code(color)
+      { red: 31, green: 32, yellow: 33, blue: 34 }[color] || 0
+    end
+  end
+end

data/lib/utils/string_utils.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # StringUtils provides string format conversion and cleaning utilities.
+  module StringUtils
+    # Convert snake_case to CamelCase
+    # @param str [String]
+    # @return [String]
+    # @example
+    #   Kutils::StringUtils.camelize('hello_world') #=> 'HelloWorld'
+    def self.camelize(str)
+      str.split('_').map(&:capitalize).join
+    end
+
+    # Convert CamelCase or kebab-case to snake_case
+    # @param str [String]
+    # @return [String]
+    # @example
+    #   Kutils::StringUtils.underscore('HelloWorld') #=> 'hello_world'
+    def self.underscore(str)
+      str.gsub(/::/, '/').gsub(/([A-Z]+)([A-Z][a-z])/,'\\1_\\2').gsub(/([a-z\d])([A-Z])/,'\\1_\\2').tr("-", "_").downcase
+    end
+
+    # Convert string to URL slug (lowercase, dash-separated, alphanumeric)
+    # @param str [String]
+    # @return [String]
+    # @example
+    #   Kutils::StringUtils.slugify('Hello Ruby!') #=> 'hello-ruby'
+    def self.slugify(str)
+      str.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '')
+    end
+  end
+end

data/lib/utils/time_utils.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+require 'time'
+
+module Kutils
+  # TimeUtils provides time formatting and duration utilities.
+  module TimeUtils
+    # Get current UTC time in ISO8601 format
+    # @return [String]
+    # @example
+    #   Kutils::TimeUtils.now_iso8601 #=> '2025-01-01T12:00:00Z'
+    def self.now_iso8601
+      Time.now.utc.iso8601
+    end
+
+    # Format seconds as HH:MM:SS
+    # @param seconds [Integer]
+    # @return [String]
+    # @example
+    #   Kutils::TimeUtils.human_duration(3661) #=> '01:01:01'
+    def self.human_duration(seconds)
+      mm, ss = seconds.divmod(60)
+      hh, mm = mm.divmod(60)
+      format('%02d:%02d:%02d', hh, mm, ss)
+    end
+  end
+end

data/lib/utils/validator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  # Validator provides simple parameter validation utilities.
+  module Validator
+    # Check if value is present (not nil or empty string)
+    # @param val [Object]
+    # @return [Boolean]
+    def self.required?(val)
+      !val.nil? && val != ''
+    end
+
+    # Check if value is a valid email address
+    # @param val [String]
+    # @return [Boolean]
+    def self.email?(val)
+      !!(val =~ /\A[^@\s]+@[^@\s]+\z/)
+    end
+  end
+end

data/lib/utils/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# Copyright (c) 2025 kk
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+module Kutils
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: kutils
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: String, time, file, crypto, array, validation, debug, DSL, formatting
+  and more.
+email:
+- kk@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kutils.rb
+- lib/utils/array_utils.rb
+- lib/utils/crypto_utils.rb
+- lib/utils/debug_utils.rb
+- lib/utils/dsl_builder.rb
+- lib/utils/file_utils.rb
+- lib/utils/format_utils.rb
+- lib/utils/string_utils.rb
+- lib/utils/time_utils.rb
+- lib/utils/validator.rb
+- lib/utils/version.rb
+homepage: https://github.com/kk/kutils
+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.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: A collection of geek-style Ruby utility modules.
+test_files: []