bbk-utils 1.1.5.353947 → 1.1.6.359865

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57d03b7ce638f9f4479a442502913d783709256374857e5240d29bdaead8e065
-  data.tar.gz: 03ad2e62425fbba99d5b4fe0af1485770d1a6a1fdabd952b7a190bfb6178d2cf
+  metadata.gz: 7fe5c8597f68375fe0f5bc85ec04e99894353fc7f6b558bf7bea52abff51c0eb
+  data.tar.gz: ba14ee452fe704de69c9e4f1e378f4f6962f09245b2326fa3173ff8320e834b4
 SHA512:
-  metadata.gz: a371a7e342f26ba6456d2417ca0ad7d6d1d427f3641eb885624f4b3003afd40dc30690b1fc9ffca8ede575d55c28aceb23a4db9569d59ef70e4311c98264e2b0
-  data.tar.gz: 3469b76b5e933e19fdc2c703174eec2de0e697245438b3a23d04c175467ffde518926b3571b6748ad59eaa8c624131563fa8477055811176f757f774807bbe29
+  metadata.gz: eed9ae4a2d2f7562a8bea56deafdbbb27c4ccffcbef7f04729d432ee2eaf7c7b288e6185cc3cf59f656f7c06f9b6d32d85ec5cfad8a2de44490924f0de77c191
+  data.tar.gz: 84ecb583308143da125d3cd4106e5794f186c2f1ca02cd064cfdc07cb4b8f0d884372faa30fbf8e3a94f36be6c1a1025bd2427b37a03d15aa624a72af3496e63

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bbk-utils (1.1.5)
+    bbk-utils (1.1.6)
       activesupport (>= 7.0)
       russian
 
@@ -36,7 +36,7 @@ GEM
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
     concurrent-ruby (1.2.2)
-    connection_pool (2.5.0)
+    connection_pool (3.0.2)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.6.0)
@@ -62,7 +62,8 @@ GEM
     launchy (2.5.0)
       addressable (~> 2.7)
     logger (1.7.0)
-    minitest (6.0.1)
+    minitest (6.0.2)
+      drb (~> 2.0)
       prism (~> 1.5)
     mutex_m (0.3.0)
     ostruct (0.6.3)
@@ -110,7 +111,8 @@ GEM
     rubocop-rspec (2.6.0)
       rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
-    ruby_parser (3.18.1)
+    ruby_parser (3.22.0)
+      racc (~> 1.5)
       sexp_processor (~> 4.16)
     rubycritic (4.6.1)
       flay (~> 2.8)
@@ -126,7 +128,7 @@ GEM
     russian (0.6.0)
       i18n (>= 0.5.0)
     securerandom (0.4.1)
-    sexp_processor (4.16.0)
+    sexp_processor (4.17.5)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -176,4 +178,4 @@ DEPENDENCIES
   terminal-table
 
 BUNDLED WITH
-   2.2.33
+  2.7.2

data/README.md

@@ -37,14 +37,28 @@ Or adding to your project:
 gem "bbk-utils", "~> 1.0.0"
 ```
 
-### Supported Ruby versions
+## Features
 
-* Ruby (MRI) >= 2.5.0
+### bbkdocs
 
-### Tested Ruby versions
+Создать `bin/bbkdocs`:
+
+```ruby
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'config', 'environment'))
+require 'bbk/utils/cli'
+
+BBK::Utils::Cli::Docs.new(ARGV).run
+```
+
+Добавить в `Rakefile`:
+
+```ruby
+# Загружаем таски из BBK::Utils. В частности генерацию документации
+BBK::Utils.load_tasks
+```
 
-* Ruby (MRI) 2.5.x
-* Ruby (MRI) 3.0.x
 
 ## Contributing
 

data/lib/bbk/utils/cli/bbkdocs.yml

@@ -0,0 +1,56 @@
+categories:
+  transport_amqp:
+    name: Transport Amqp
+    desc: Настройки подключения к RabbitMQ и работы с очередями 
+    order: 10
+    patterns:
+      - AMQP_
+      - MQ_
+    envs:
+      - CA_CERT
+      - CLIENT_CERT
+      - CLIENT_KEY
+
+  database:
+    name: База данных
+    desc: Настройки подключения к PostgreSQL
+    order: 20
+    patterns:
+      - DATABASE_
+      - REQUEST_CREATE_PARTITION_
+
+  redis:
+    name: Redis
+    desc: Настройки подключения к Redis для кэширования и очередей
+    order: 30
+    patterns:
+      - REDIS_
+
+  discovery:
+    name: Обнаружение сервисов
+    order: 40
+    patterns:
+      - CONSUL_
+
+  app:
+    name: Настройки приложения
+    order: 50
+    envs:
+      - RAILS_ENV
+      - LOG_LEVEL 
+
+  filator:
+    name: Файловое хранилище
+    desc: Настройки интеграции с файловым хранилищем
+    order: 60
+    patterns:
+      - FILATOR_
+
+  monitoring:
+    name: Мониторинг
+    desc: Настройки систем мониторинга и трейсинга
+    order: 70
+    patterns:
+      - ELASTIC_
+      - JAEGER_
+      - PROMETHEUS_

data/lib/bbk/utils/cli/docs/builder.rb

@@ -0,0 +1,149 @@
+module BBK
+  module Utils
+    module Cli
+      # Класс-строитель документации по категориям конфигурации
+      #
+      # Группирует конфигурационные параметры по категориям,
+      # обеспечивает сортировку и генерацию документации в различных форматах
+      class Docs::Builder
+        # Инициализирует строитель документации
+        #
+        # @param bbk [Hash] конфигурация BBK
+        # @param config [Hash] конфигурация документирования
+        # @option config [Hash] :categories настройки категорий
+        def initialize(bbk, config)
+          @bbk = bbk
+          @config = config
+
+          @categories = config[:categories].each_with_object({}) do |(name, c), cats|
+            cats[name.to_s] = Category.new(id: name.to_s, **c)
+          end
+
+          @default = Category.new(id: 'other', name: 'Other')
+          @categories[@default.id] = @default
+        end
+
+        # Выполняет разбор конфигурации по категориям
+        #
+        # @return [self] возвращает сам объект для цепочного вызова
+        def run
+          @bbk.each do |(env_name, cfg)|
+            category = @categories[cfg[:category]]
+            category ||= @categories.values.find { |c| c.match?(env_name) } || @default
+
+            category.add(cfg)
+          end
+
+          @sorted = @categories.values.sort_by { |category| [category.order, category.id.to_s] }
+          self
+        end
+
+        # Преобразует документацию в JSON-хеш
+        #
+        # @param _args [Array] игнорируемые аргументы
+        # @param _kwargs [Hash] игнорируемые именованные аргументы
+        # @return [Hash] хеш со структурой документации по категориям
+        def as_json(*_args, **_kwargs)
+          @sorted.each_with_object({}) do |category, result|
+            result[category.id] = category.as_json
+          end
+        end
+
+        # Преобразует документацию в JSON-строку
+        #
+        # @param args [Array] аргументы для JSON-генерации
+        # @param kwargs [Hash] именованные аргументы для JSON-генерации
+        # @return [String] JSON-строка документации
+        def to_json(*args, **kwargs)
+          as_json.to_json(*args, **kwargs)
+        end
+
+        # Генерирует документацию в формате Markdown
+        #
+        # @return [String] markdown-разметка полной документации
+        def to_markdown
+          markdown_opts = {
+            columns: { env: 'Название', _class: 'Тип', desc: 'Описание', default: 'Умолчание' },
+            alignments: { 1 => :center, 3 => :center }, # :left, :right, :center для каждой колонки
+            wrappers: { 1 => '`', 3 => '`' }, # символ или строка для обрамления значений колонки, например: "`", "```", "**"
+            title_level: 4, # уровень заголовка от 1 до 6
+            warning: {
+              column_index: 2,
+              # mode: :footnote # :footnote или :inline
+              mode: :inline # :footnote или :inline
+            }
+          }
+
+          generator = Docs::Markdown.new(markdown_opts)
+
+          @sorted.map do |category|
+            category.cfgs.any? ? generator.generate(category) : ''
+          end.join("\n")
+        end
+      end
+
+      # Структура категории для группировки конфигураций
+      #
+      # @!attribute [r] id
+      #   @return [String] идентификатор категории
+      # @!attribute [r] name
+      #   @return [String] название категории
+      # @!attribute [r] desc
+      #   @return [String] описание категории
+      # @!attribute [r] envs
+      #   @return [Array<String>] список переменных окружения категории
+      # @!attribute [r] order
+      #   @return [Numeric] порядок сортировки
+      # @!attribute [r] patterns
+      #   @return [Array<String>] шаблоны для поиска элементов категории
+      # @!attribute [r] cfgs
+      #   @return [Array<Hash>] конфигурации категории
+      Category = Struct.new(:id, :name, :desc, :envs, :order, :patterns, :cfgs, keyword_init: true) do
+        # Инициализирует категорию
+        #
+        # @param kwargs [Hash] параметры категории
+        # @option kwargs [String] :id идентификатор категории
+        # @option kwargs [String] :name название категории
+        # @option kwargs [String] :desc описание категории
+        # @option kwargs [Array<String>] :envs переменные окружения
+        # @option kwargs [Numeric] :order порядок сортировки
+        # @option kwargs [Array<String>] :patterns шаблоны поиска
+        # @option kwargs [Array<Hash>] :cfgs конфигурации
+        def initialize(**kwargs)
+          kwargs[:id] = kwargs[:id].to_s
+          kwargs[:name] = kwargs[:name].to_s || kwargs[:id].capitalize
+          kwargs[:desc] = kwargs[:desc].to_s
+
+          kwargs[:patterns] ||= []
+          kwargs[:envs] ||= []
+          kwargs[:order] ||= Float::INFINITY
+          kwargs[:cfgs] ||= []
+
+          super
+        end
+
+        # Проверяет соответствие имени переменной окружающей категории
+        #
+        # @param env_name [String, Symbol] имя переменной окружения
+        # @return [Boolean] true если соответствует категории
+        def match?(env_name)
+          return true if envs.any? { |e| e == env_name.to_s.strip }
+
+          return true if patterns.any? { |p| env_name.to_s.strip.start_with?(p) }
+
+          false
+        end
+
+        # Добавляет конфигурацию в категорию
+        #
+        # @param cfg [Hash] конфигурация для добавления
+        # @return [self] возвращает сам объект для цепочного вызова
+        def add(cfg)
+          cfgs << cfg
+          self.cfgs = cfgs.sort_by { |c| c[:env] }
+          self
+        end
+      end
+    end
+  end
+end

data/lib/bbk/utils/cli/docs/markdown.rb

@@ -0,0 +1,214 @@
+module BBK
+  module Utils
+    module Cli
+      # Класс для генерации документации в формате Markdown
+      #
+      # Создает таблицы с переменными окружения, параметрами конфигурации и т.д.
+      # Поддерживает настраиваемые колонки, выравнивание, обрамление значений
+      # и предупреждения в двух режимах: сноски или встроенные
+      class Docs::Markdown
+        # Генерация markdown-документации для категории
+        # category_data = {
+        #   category_data: {
+        #   },
+        #   env_vars: category.env_vars
+        # }
+        #
+        # options = {
+        #   columns: { env: "Название"},
+        #   alignments: { 1 => :center, 3 => :center }, # :left, :right, :center для каждой колонки
+        #   wrappers: { 1 => "`", 3 => "`" }, # wrappers - символ или строка для обрамления значений колонки, например: "`", "```", "**"
+        #   title_level: 4, # уровень заголовка от 1 до 6
+        #   warning: {
+        #     column_index: 3, # индекс колонки для вывода предупреждений
+        #     mode: :footnote # или :inline
+        #   }
+        # }
+
+        attr_reader :opts
+
+        # Инициализирует генератор Markdown
+        #
+        # @param opts [Hash] опции генерации
+        # @option opts [Hash] :columns отображаемые колонки с заголовками
+        # @option opts [Hash] :alignments выравнивание для каждой колонки
+        # @option opts [Hash] :wrappers обрамление значений колонок
+        # @option opts [Integer] :title_level уровень заголовка (1-6)
+        # @option opts [Hash] :warning настройки вывода предупреждений
+        def initialize(opts = {})
+          @opts = opts
+        end
+
+        # Генерирует markdown-документацию для заданной категории
+        #
+        # @param category [Docs::Builder::Category] категория конфигурации
+        # @return [String] markdown-разметка документации
+        def generate(category)
+          # Соберем заголовок
+          level = opts[:title_level].clamp(1, 6)
+          title = "#{'#' * level} (#{category.id}) #{category.name}"
+          desc = category.desc.to_s
+
+          # Конвертируем данные в формат для таблицы
+          rows, footnotes = generate_rows(category, opts)
+          # Создаем таблицу с заголовком и описанием
+
+          table = generate_table(opts[:columns].values, opts[:alignments], rows)
+          [
+            title,
+            '',
+            desc,
+            '',
+            *table,
+            '',
+            *footnotes
+          ].join("\n")
+        end
+
+        # Генерирует строки для таблицы документации
+        #
+        # @param category [Docs::Builder::Category] категория конфигурации
+        # @param opts [Hash] опции генерации
+        # @return [Array] массив строк и сносок
+        def generate_rows(category, opts)
+          # извлекаем даныне
+          rows = category.cfgs.map do |cfg|
+            opts[:columns].keys.each_with_object([]) do |key, row|
+              row << cfg[key.to_sym]
+            end
+          end
+
+          # Применяем обрамление к значениям
+          rows = wrap_row_values(rows, opts[:wrappers])
+
+          # Применяем форматирование предупреждений
+          rows, footnotes = process_warnings(rows, category, opts[:warning])
+
+          [rows, footnotes]
+        end
+
+        # Применяет обрамление к значениям в строках таблицы
+        #
+        # @param rows [Array<Array>] строки таблицы
+        # @param wrappers [Hash] хеш обрамления по индексам колонок
+        # @return [Array<Array>] строки с обрамленными значениями
+        def wrap_row_values(rows, wrappers)
+          return rows if wrappers.empty?
+
+          rows.map do |row|
+            row.each_with_index.map do |value, index|
+              wrapper = wrappers[index]
+              if wrapper && !value.nil? # может быть пустым
+                "#{wrapper}#{value}#{wrapper}"
+              else
+                value
+              end
+            end
+          end
+        end
+
+        # Обрабатывает предупреждения для строк таблицы
+        #
+        # @param rows [Array<Array>] строки таблицы
+        # @param category [Docs::Builder::Category] категория конфигурации
+        # @param warning_opts [Hash] опции обработки предупреждений
+        # @option warning_opts [Integer] :column_index индекс колонки для предупреждений
+        # @option warning_opts [Symbol] :mode режим вывода (:footnote или :inline)
+        # @return [Array] кортеж из обработанных строк и массива сносок
+        def process_warnings(rows, category, warning_opts)
+          return [rows, []] if !warning_opts || !warning_opts[:column_index]
+
+          column_index = warning_opts[:column_index]
+          mode = warning_opts[:mode] || :footnote
+          footnotes = []
+          footnote_counter = 1
+
+          processed_rows = rows.each_with_index.map do |row, row_index|
+            cfg = category.cfgs[row_index]
+            warning = cfg[:warning]
+
+            if warning && !warning.empty?
+              case mode
+              when :footnote
+                # Добавляем номер сноски
+                id = "#{category.id}_#{footnote_counter}"
+                row[column_index] = "#{row[column_index]} [^#{id}]"
+                footnotes << "[^#{id}]: #{warning}"
+                footnote_counter += 1
+              when :inline
+                # Добавляем предупреждение жирным текстом с переносом строки
+                row[column_index] = "#{row[column_index]}<br>⚠️ **#{warning}**"
+              end
+            end
+            row
+          end
+
+          [processed_rows, footnotes]
+        end
+
+        # Генерирует таблицу в формате Markdown
+        #
+        # @param headers [Array<String>] заголовки колонок
+        # @param alignments [Hash] выравнивание для каждой колонки
+        # @param rows [Array<Array>] строки данных таблицы
+        # @return [Array<String>] массив строк markdown-таблицы
+        def generate_table(headers = [], alignments = {}, rows)
+          # Вычисляем ширину колонок
+          column_widths = if headers.any?
+                            headers.map(&:size)
+                          else
+                            Array.new(rows[0].count, 0)
+                          end
+
+          rows.each do |row|
+            row.each_with_index do |data, i|
+              column_widths[i] = data.to_s.size if data.to_s.size > column_widths[i]
+            end
+          end
+
+          # Создаем заголовок таблицы
+          if headers.any?
+            header_string = '|'
+            separator_string = '|'
+
+            headers.each_with_index do |header, col|
+              header_string += " #{header.ljust(column_widths[col])} |"
+
+              # Создаем разделитель с учетом выравнивания
+              separator_string += case alignments[col]
+                                  when :right
+                                    "#{'-' * (column_widths[col] + 1)}:|"
+                                  when :center
+                                    if column_widths[col] >= 1
+                                      ":#{'-' * column_widths[col]}:|"
+                                    else
+                                      '::|'
+                                    end
+                                  when :left
+                                    ":#{'-' * (column_widths[col] + 1)}|"
+                                  else
+                                    "#{'-' * (column_widths[col] + 2)}|"
+                                  end
+            end
+
+          end
+
+          # Создаем строки данных
+          lines = rows.map do |row|
+            line = row.each_with_index.map do |value, col|
+              value.to_s.ljust(column_widths[col])
+            end.join(' | ')
+
+            "| #{line} |"
+          end
+
+          [
+            header_string,
+            separator_string,
+            *lines
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/bbk/utils/cli/docs.rb

@@ -0,0 +1,151 @@
+require 'fileutils'
+require 'yaml'
+require 'optparse'
+
+module BBK
+  module Utils
+    module Cli
+      # Класс для генерации документации по конфигурации BBK
+      #
+      # Обеспечивает парсинг аргументов командной строки, загрузку конфигурации
+      # и генерацию документации в форматах JSON и Markdown
+      class Docs
+        # Инициализирует объект генератора документации
+        #
+        # @param argv [Array<String>] аргументы командной строки
+        def initialize(argv)
+          @argv = argv
+        end
+
+        # Основной метод запуска генерации документации
+        #
+        # @param argv [Array<String>] аргументы командной строки
+        # @return [void]
+        def run(argv = @argv)
+          options = parse!(argv)
+
+          bbk = extract_bbk_config
+
+          config = load_configuration("#{__dir__}/bbkdocs.yml", options[:config])
+
+          @builder = Builder.new(bbk, config).tap do |b|
+            b.run
+          end
+
+          FileUtils.mkdir_p File.dirname(options[:categories])
+
+          File.open(options[:categories], 'w') do |file|
+            file << JSON.pretty_generate(@builder.as_json)
+            puts "Documentation JSON saved to: #{options[:categories]}"
+          end
+
+          FileUtils.mkdir_p File.dirname(options[:output])
+
+          File.open(options[:output], 'w') do |file|
+            file << @builder.to_markdown
+            puts "Documentation MArkdown saved to: #{options[:output]}"
+          end
+        end
+
+        # Парсит аргументы командной строки
+        #
+        # @param argv [Array<String>] аргументы командной строки
+        # @return [Hash] хеш с опциями конфигурации
+        def parse!(argv)
+          options = {
+            config: './.bbkdocs.yml',
+            output: './bbkdocs.md',
+            categories: './bbkdocs.json'
+          }
+
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: bundle exec bin/bbkdocs [options]'
+
+            opts.on('-c', '--config CONFIG', "Path to config file (default: #{options[:config]})") do |path|
+              options[:config] = File.absolute_path(path.to_s.strip)
+            end
+
+            opts.on('-o', '--output OUTPUT', "Path to output file (default: #{options[:output]})") do |path|
+              options[:output] = File.absolute_path(path.to_s.strip)
+            end
+
+            opts.on('-g', '--categories CATEGORIES',
+                    "Path to categories output file (default: #{options[:categories]})") do |path|
+              options[:categories] = File.absolute_path(path.to_s.strip)
+            end
+
+            opts.on('-h', '--help', 'Prints this help') do
+              puts opts
+              exit
+            end
+          end.parse!(argv)
+
+          options
+        end
+
+        # Загружает и объединяет конфигурации из нескольких файлов
+        #
+        # @param files [Array<String>] пути к файлам конфигурации YAML
+        # @return [Hash] объединенная конфигурация с символизированными ключами
+        def load_configuration(*files)
+          files.each_with_object({}) do |file, config|
+            loaded = YAML.load_file(file).deep_symbolize_keys!
+
+            config.deep_merge!(loaded) do |key, oldv, newv|
+              result = newv
+
+              if oldv.is_a?(Hash) || newv.is_a?(Hash)
+                result = (oldv || {}).deep_merge(newv || {})
+              elsif oldv.is_a?(Array) || newv.is_a?(Array)
+                result = if key.to_s == 'patterns' || key.to_s == 'envs'
+                           ([oldv].flatten + [newv].flatten).compact.map(&:to_s).map(&:strip)
+                         else
+                           (newv || [])
+                         end
+              else
+                newv
+              end
+
+              result
+            end
+          end
+        end
+
+        # Извлекает конфигурацию BBK и преобразует её в удобный формат
+        #
+        # @return [Hash] конфигурация BBK с дополнительной информацией о типах
+        def extract_bbk_config
+          bbk_cfg = BBK::Utils::Config.instance.as_json.deep_dup
+          bbk_cfg = bbk_cfg[BBK::Utils::Config.instance.name] unless BBK::Utils::Config.instance.name.nil?
+
+          BBK::Utils::Config.instance.send(:store_with_subconfigs).each do |k, v|
+            bbk_cfg[k][:default] = v[:default].original if v[:default]&.class&.to_s == 'Fugit::Duration'
+
+            bbk_cfg[k][:_class] = v[:default].class.to_s unless v[:default].nil?
+          end
+
+          bbk_cfg.deep_symbolize_keys
+        end
+      end
+    end
+  end
+end
+
+require_relative 'docs/builder'
+require_relative 'docs/markdown'
+
+# пример одного элемента bbk_cfg после преобразований и до засовывания в Env::CategoryBuilder
+#  "BILLING_ENABLED": {
+#    "env": "BILLING_ENABLED",
+#    "file": null,
+#    "required": false,
+#    "default": false,
+#    "desc": "Send data to billing by api",
+#    "bool": true,
+#    "type": "#<Method: BBK::Utils::Config::BooleanCaster.cast(value) /home/user/dev/rndsoft/aggredator/consumers/bbk/utils/lib/bbk/utils/config.rb:28>",
+#    "secure": false,
+#    "category": null,
+#    "warning": null,
+#    "value": false,
+#    "_class": "FalseClass"
+#  },

data/lib/bbk/utils/cli.rb

@@ -0,0 +1,8 @@
+require 'bbk/utils/cli/docs'
+
+module BBK
+  module Utils
+    module Cli
+    end
+  end
+end

data/lib/bbk/utils/config.rb

@@ -65,7 +65,7 @@ module BBK
         @env_prefix = normalize_key(@prefixes.join(PREFIX_SEP))
       end
 
-      def map(env, file, required: true, desc: nil, bool: false, key: nil, rewrite: true)
+      def map(env, file, required: true, desc: nil, bool: false, key: nil, rewrite: true, category: nil, warning: nil)
         conf_key = full_prefixed_key(env)
         return if @store.key?(conf_key) && !rewrite
 
@@ -75,11 +75,13 @@ module BBK
           required: required,
           desc:     desc,
           bool:     bool,
-          type:     nil
+          type:     nil,
+          category: category,
+          warning:  warning
         }
       end
 
-      def require(env, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false)
+      def require(env, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
         raise ArgumentError.new('Specified type and bool') if bool && type.present?
 
         type = BBK::Config::BooleanCaster.singleton_method(:cast) if bool
@@ -93,11 +95,13 @@ module BBK
           desc:     desc,
           bool:     bool,
           type:     type,
-          secure:   secure
+          secure:   secure,
+          category: category,
+          warning:  warning
         }
       end
 
-      def optional(env, default: nil, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false)
+      def optional(env, default: nil, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
         raise ArgumentError.new('Specified type and bool') if bool && type.present?
 
         type = BBK::Utils::Config::BooleanCaster.singleton_method(:cast) if bool
@@ -112,7 +116,9 @@ module BBK
           desc:     desc,
           bool:     true,
           type:     type,
-          secure:   secure
+          secure:   secure,
+          category: category,
+          warning:  warning
         }
       end
 

data/lib/bbk/utils/tasks/docs.rake

@@ -0,0 +1,16 @@
+require 'rake'
+
+namespace :bbk do
+  namespace :utils do
+    desc "Generate documentation for environment variables (options: BBKDOCS_CONFIG=./.bbkdocs.yml, BBKDOCS_OUTPUT=./bbkdocs.md, BBKDOCS_CATEGORIES=./bbkdocs.json)"
+    task :docs do
+      args = []
+      args.concat(['-c', ENV['BBKDOCS_CONFIG']]) if ENV['BBKDOCS_CONFIG']
+      args.concat(['-o', ENV['BBKDOCS_OUTPUT']]) if ENV['BBKDOCS_OUTPUT']
+      args.concat(['-g', ENV['BBKDOCS_CATEGORIES']]) if ENV['BBKDOCS_CATEGORIES']
+  
+      sh "ruby", "bin/bbkdocs", *args
+    end
+  end
+end
+

data/lib/bbk/utils/version.rb

@@ -3,7 +3,7 @@
 module BBK
   module Utils
 
-    VERSION = '1.1.5'
+    VERSION = '1.1.6'
 
   end
 end

data/lib/bbk/utils.rb

@@ -36,10 +36,18 @@ module BBK
         e.status
       end
 
+      def load_tasks
+        path = File.expand_path(__dir__)
+        Dir.glob("#{path}/utils/tasks/**/*.rake").each { |f| load f }
+      end
+
     end
 
     self.logger = ::BBK::Utils::Logger.default
 
+
+
+
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bbk-utils
 version: !ruby/object:Gem::Version
-  version: 1.1.5.353947
+  version: 1.1.6.359865
 platform: ruby
 authors:
 - Samoilenko Yuri
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-04 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -258,10 +258,12 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
-- bin/console
-- bin/setup
 - lib/bbk/utils.rb
-- lib/bbk/utils/cli/env_docs.rb
+- lib/bbk/utils/cli.rb
+- lib/bbk/utils/cli/bbkdocs.yml
+- lib/bbk/utils/cli/docs.rb
+- lib/bbk/utils/cli/docs/builder.rb
+- lib/bbk/utils/cli/docs/markdown.rb
 - lib/bbk/utils/combined_logger.rb
 - lib/bbk/utils/config.rb
 - lib/bbk/utils/crypt.rb
@@ -269,6 +271,7 @@ files:
 - lib/bbk/utils/log_formatter.rb
 - lib/bbk/utils/logger.rb
 - lib/bbk/utils/proxy_logger.rb
+- lib/bbk/utils/tasks/docs.rake
 - lib/bbk/utils/version.rb
 - lib/bbk/utils/xml.rb
 - sig/bbk/config.rbs

data/bin/console

@@ -1,16 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'bbk/utils'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
-

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/lib/bbk/utils/cli/env_docs.rb

@@ -1,163 +0,0 @@
-require 'yaml'
-require 'optparse'
-
-
-module BBK
-  module Utils
-    module Cli
-      class EnvDocs
-
-        def self.run(*args) new.run(*args) end
-
-        def run(*args)
-          options = {
-            config: './.env_docs.yml',
-            output: './env_docs.md'
-          }
-
-          OptionParser.new do |opts|
-             opts.banner = "Usage: env_docs [options]"
-
-             opts.on("-c", "--config CONFIG", "Path to config file (default: #{options[:config]})") do |c|
-               options[:config] = c
-             end
-
-             opts.on("-o", "--output OUTPUT", "Path to output file (default: #{options[:output]})") do |o|
-               options[:output] = o
-             end
-
-             opts.on("-h", "--help", "Prints this help") do
-               puts opts
-               exit
-             end
-          end.parse!(args)
-
-          output_file = Rails.root.join(options[:output])
-          config_file = Rails.root.join(options[:config])
-
-          if File.exist?(config_file)
-            config = YAML.load_file(config_file) || {}
-          else
-            puts "Config file not found: #{config_file}. Continuing without config."
-            config = {}
-          end
-
-          cfg = BBK::Utils::Config.instance.as_json.deep_dup
-          cfg = cfg[BBK::Utils::Config.instance.name] unless BBK::Utils::Config.instance.name.nil?
-
-          BBK::Utils::Config.instance.send(:store_with_subconfigs).each do |k, v|
-            if v[:default]&.class&.to_s == "Fugit::Duration"
-              cfg[k][:default] = v[:default].original
-            end
-
-            if v[:default]
-              cfg[k][:class] = "#{v[:default].class}"
-            end
-          end
-
-          env_prefix_order = config.fetch('env_prefix_order', [])
-
-          matching, remaining = separate(cfg, env_prefix_order)
-
-          File.open(output_file, 'w') do |file|
-            file.puts "# Переменные окружения\n\n"
-            file.puts to_markdown(matching)
-            file.puts "\n\n"
-            file.puts to_markdown(remaining.sort)
-          end
-
-          puts "Documentation saved to: #{output_file}"
-        end
-
-        def separate(cfg, env_prefix_order)
-          matching = {}
-          remaining = {}
-
-          cfg.each do |key, value|
-            matched = env_prefix_order.any? do |prefix|
-              key == prefix || key.start_with?(prefix + '_')
-            end
-
-            if matched
-              matching[key] = value
-            else
-              remaining[key] = value
-            end
-          end
-
-          [matching, remaining]
-        end
-
-        def to_markdown(cfg, columns = { :env => "Название", :desc => "Описание", :default => "По умолчанию", :class => "Тип"} )
-          rows = cfg_to_array(cfg, columns.keys)
-
-          create_markdown_table(rows, columns.values)
-        end
-
-
-        def cfg_to_array(cfg, keys)
-          cfg.each_with_object([]) do |entry, rows|
-            rows << keys.each_with_object([]) do |key, row|
-              row << entry[1][key]
-            end
-          end
-        end
-
-        def create_markdown_table(rows, headers = [])
-          return "| No data |" if rows.empty?
-
-          column_widths = if headers.size != 0
-            headers.map(&:size)
-          else
-            Array.new(rows[0].count, 0)
-          end
-
-          rows.each do |row|
-            row.each_with_index do |string, i|
-              column_widths[i] = string.to_s.size if string.present? && string.to_s.size > column_widths[i]
-            end
-          end
-
-          markdown_table = []
-
-          # Создаем заголовок таблицы, если он есть
-          if headers.size != 0
-            header_string = "|"
-            separator_string = "|"
-
-            headers.each_with_index do |header, col|
-              header_string += " #{header.ljust(column_widths[col])} |"
-              separator_string += "-#{'-' * column_widths[col]}-|"
-            end
-
-            markdown_table << header_string
-            markdown_table << separator_string
-          end
-
-          # Создаем строки данных
-          rows_string = []
-          rows.each do |row|
-            row_string = "|"
-            row.each_with_index do |data, col|
-              value = (data || '').to_s
-              row_string += " #{value.ljust(column_widths[col])} |"
-            end
-            rows_string << row_string
-          end
-          markdown_table += rows_string
-
-        end
-      end
-    end
-  end
-end
-
-#   "BILLING_ENABLED"=>
-#    {:env=>"BILLING_ENABLED",
-#     :file=>nil,
-#     :required=>false,
-#     :default=>false,
-#     :desc=>"Send data to billing by api",
-#     :bool=>true,
-#     :type=>
-#      #<Method: BBK::Utils::Config::BooleanCaster.cast(value) /home/user/.asdf/installs/ruby/3.2.2/lib/ruby/gems/3.2.0/gems/bbk-utils-1.1.2.304819/lib/bbk/utils/config.rb:27