bddgenx 0.1.42 → 0.1.44

data/lib/bddgenx/runner.rb

@@ -1,4 +1,10 @@
 # lib/bddgenx/cli.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Runner (CLI) da gem bddgenx,
+# responsável por orquestrar o fluxo de leitura de histórias,
+# validação, geração de features, steps, backups e exportação de PDFs.
+
 require 'fileutils'
 require_relative 'utils/parser'
 require_relative 'generator'
@@ -8,17 +14,23 @@ require_relative 'utils/validator'
 require_relative 'utils/backup'
 
 module Bddgenx
+  # Ponto de entrada da gem: coordena todo o processo de geração BDD.
   class Runner
-    # Retorna arquivos a processar: usa ARGV ou prompt interativo
+    # Seleciona arquivos de entrada para processamento.
+    # Se houver argumentos em ARGV, usa-os como nomes de arquivos .txt;
+    # caso contrário, exibe prompt interativo para escolha.
+    #
+    # @param input_dir [String] Diretório onde estão os arquivos .txt de histórias
+    # @return [Array<String>] Lista de caminhos para os arquivos a serem processados
     def self.choose_files(input_dir)
-      if ARGV.any?
-        selecionar_arquivos_txt(input_dir)
-      else
-        choose_input(input_dir)
-      end
+      ARGV.any? ? selecionar_arquivos_txt(input_dir) : choose_input(input_dir)
     end
 
-    # Seleciona arquivos .txt via argumentos
+    # Mapeia ARGV para paths de arquivos .txt em input_dir.
+    # Adiciona extensão '.txt' se necessário e filtra arquivos inexistentes.
+    #
+    # @param input_dir [String] Diretório de entrada
+    # @return [Array<String>] Caminhos válidos para processamento
     def self.selecionar_arquivos_txt(input_dir)
       ARGV.map do |arg|
         nome = arg.end_with?('.txt') ? arg : "#{arg}.txt"
@@ -31,26 +43,42 @@ module Bddgenx
       end.compact
     end
 
-    # Prompt interativo único
+    # Exibe prompt interativo para o usuário escolher qual arquivo processar
+    # entre todos os .txt disponíveis em input_dir.
+    #
+    # @param input_dir [String] Diretório de entrada
+    # @exit [1] Se nenhum arquivo for encontrado ou escolha inválida
+    # @return [Array<String>] Um único arquivo escolhido ou todos se ENTER
     def self.choose_input(input_dir)
       files = Dir.glob(File.join(input_dir, '*.txt'))
       if files.empty?
-        warn "❌ Não há arquivos .txt no diretório #{input_dir}"
-        exit 1
+        warn "❌ Não há arquivos .txt no diretório #{input_dir}"; exit 1
       end
 
       puts "Selecione o arquivo de história para processar:"
-      files.each_with_index { |f,i| puts "#{i+1}. #{File.basename(f)}" }
+      files.each_with_index { |f, i| puts "#{i+1}. #{File.basename(f)}" }
       print "Digite o número correspondente (ou ENTER para todos): "
       choice = STDIN.gets.chomp
+
       return files if choice.empty?
       idx = choice.to_i - 1
-      unless idx.between?(0, files.size-1)
+      unless idx.between?(0, files.size - 1)
         warn "❌ Escolha inválida."; exit 1
       end
       [files[idx]]
     end
 
+    # Executa todo o fluxo de geração BDD.
+    # - Cria pasta 'input' se não existir
+    # - Seleciona arquivos de histórias
+    # - Para cada arquivo:
+    #   - Lê e valida a história
+    #   - Gera arquivo .feature e salva backup da versão anterior
+    #   - Gera definitions de steps
+    #   - Exporta PDFs novos via PDFExporter
+    # - Exibe resumo final com estatísticas
+    #
+    # @return [void]
     def self.execute
       input_dir = 'input'
       Dir.mkdir(input_dir) unless Dir.exist?(input_dir)
@@ -60,6 +88,7 @@ module Bddgenx
         warn "❌ Nenhum arquivo de história para processar."; exit 1
       end
 
+      # Inicializa contadores
       total = features = steps = ignored = 0
       skipped_steps = []
       generated_pdfs = []
@@ -71,29 +100,31 @@ module Bddgenx
 
         historia = Parser.ler_historia(arquivo)
         unless Validator.validar(historia)
-          ignored += 1; puts "❌ Arquivo inválido: #{arquivo}"; next
+          ignored += 1
+          puts "❌ História inválida: #{arquivo}"
+          next
         end
 
-        # Gera feature
+        # Geração de feature
         feature_path, feature_content = Generator.gerar_feature(historia)
         Backup.salvar_versao_antiga(feature_path)
         features += 1 if Generator.salvar_feature(feature_path, feature_content)
 
-        # Gera steps
+        # Geração de steps
         if StepsGenerator.gerar_passos(feature_path)
           steps += 1
         else
           skipped_steps << feature_path
         end
 
-        # Exporta PDFs
+        # Exportação de PDF (apenas novos)
         FileUtils.mkdir_p('reports')
-        results = PDFExporter.exportar_todos(only_new: true)
-        generated_pdfs.concat(results[:generated])
-        skipped_pdfs.concat(results[:skipped])
+        result = PDFExporter.exportar_todos(only_new: true)
+        generated_pdfs.concat(result[:generated])
+        skipped_pdfs.concat(result[:skipped])
       end
 
-      # Resumo final
+      # Exibe relatório final
       puts "\n✅ Processamento concluído"
       puts "- Total de histórias:    #{total}"
       puts "- Features geradas:      #{features}"
@@ -101,7 +132,7 @@ module Bddgenx
       puts "- Steps ignorados:       #{skipped_steps.size}"
       puts "- PDFs gerados:          #{generated_pdfs.size}"
       puts "- PDFs já existentes:    #{skipped_pdfs.size}"
-      puts "- Arquivos ignorados:    #{ignored}"
+      puts "- Histórias ignoradas:   #{ignored}"
     end
   end
 end

data/lib/bddgenx/steps_generator.rb

@@ -1,108 +1,137 @@
-require 'fileutils'
-require 'strscan'  # para usar ::StringScanner
-require_relative 'utils/tipo_param'
-
 # lib/bddgenx/steps_generator.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe StepsGenerator, responsável por gerar
+# definições de passos do Cucumber a partir de arquivos .feature.
+# Suporta palavras-chave Gherkin em Português e Inglês e parametriza
+# strings e números conforme necessário.
+
+require 'fileutils'
+require 'strscan'  # Para uso de StringScanner
 
 module Bddgenx
+  # Gera arquivos de definições de passos Ruby para Cucumber
+  # com base em arquivos .feature.
   class StepsGenerator
+    # Palavras-chave Gherkin em Português usadas em arquivos de feature
+    # @return [Array<String>]
     GHERKIN_KEYS_PT = %w[Dado Quando Então E Mas].freeze
+
+    # Palavras-chave Gherkin em Inglês usadas em arquivos de feature
+    # @return [Array<String>]
     GHERKIN_KEYS_EN = %w[Given When Then And But].freeze
-    ALL_KEYS        = GHERKIN_KEYS_PT + GHERKIN_KEYS_EN
 
-    # Converte texto para camelCase (para nomes de argumentos)
+    # Conjunto de todas as palavras-chave suportadas (PT + EN)
+    # @return [Array<String>]
+    ALL_KEYS = GHERKIN_KEYS_PT + GHERKIN_KEYS_EN
+
+    # Converte uma string para camelCase, útil para nomes de argumentos
+    #
+    # @param [String] str Texto de entrada a ser convertido
+    # @return [String] Versão em camelCase do texto
     def self.camelize(str)
-      parts = str.strip.split(/[^a-zA-Z0-9]+/)
-      parts.map.with_index { |w, i| i.zero? ? w.downcase : w.capitalize }.join
+      partes = str.strip.split(/[^a-zA-Z0-9]+/)
+      partes.map.with_index { |palavra, i| i.zero? ? palavra.downcase : palavra.capitalize }.join
     end
 
-    # Gera step definitions a partir de um arquivo .feature
-    # - "<nome>" => {string}
-    # - <nome>   => {int}
-    # - "texto" => {string}
-    # - numeros inteiros ou floats soltos => {int}
-    # Respeita idioma de entrada (pt/en) para keywords geradas
+    # Gera definições de passos a partir de um arquivo .feature
+    #
+    # @param [String] feature_path Caminho para o arquivo .feature
+    # @raise [ArgumentError] Se feature_path não for String
+    # @return [Boolean] Retorna true se passos foram gerados, false se não houver passos
     def self.gerar_passos(feature_path)
-      raise ArgumentError, "Caminho esperado como String, recebeu #{feature_path.class}" unless feature_path.is_a?(String)
+      # Valida tipo de entrada
+      unless feature_path.is_a?(String)
+        raise ArgumentError, "Caminho esperado como String, recebeu #{feature_path.class}"
+      end
+
+      linhas = File.readlines(feature_path)
 
-      lines = File.readlines(feature_path)
       # Detecta idioma no cabeçalho: "# language: pt" ou "# language: en"
-      lang = if (m = lines.find { |l| l =~ /^#\s*language:\s*(\w+)/i })
+      lang = if (m = linhas.find { |l| l =~ /^#\s*language:\s*(\w+)/i })
                m[/^#\s*language:\s*(\w+)/i, 1].downcase
              else
                'pt'
              end
 
-      pt_to_en = GHERKIN_KEYS_PT.zip(GHERKIN_KEYS_EN).to_h
-      en_to_pt = GHERKIN_KEYS_EN.zip(GHERKIN_KEYS_PT).to_h
+      # Mapas de tradução entre PT e EN
+      pt_para_en = GHERKIN_KEYS_PT.zip(GHERKIN_KEYS_EN).to_h
+      en_para_pt = GHERKIN_KEYS_EN.zip(GHERKIN_KEYS_PT).to_h
 
-      # Seleciona apenas linhas de passo
-      step_lines = lines.map(&:strip).select do |l|
-        ALL_KEYS.any? { |k| l.start_with?(k + ' ') }
+      # Seleciona linhas que começam com palavras-chave Gherkin
+      linhas_passos = linhas.map(&:strip).select do |linha|
+        ALL_KEYS.any? { |chave| linha.start_with?(chave + ' ') }
       end
-      return false if step_lines.empty?
 
-      dir = File.join(File.dirname(feature_path), 'steps')
-      FileUtils.mkdir_p(dir)
-      file = File.join(dir, "#{File.basename(feature_path, '.feature')}_steps.rb")
+      # Se não encontrar passos, retorna false
+      return false if linhas_passos.empty?
 
-      content = +"# encoding: utf-8\n# Auto-generated step definitions for #{File.basename(feature_path)}\n\n"
+      # Cria diretório e arquivo de saída
+      dir_saida = File.join(File.dirname(feature_path), 'steps')
+      FileUtils.mkdir_p(dir_saida)
+      arquivo_saida = File.join(dir_saida, "#{File.basename(feature_path, '.feature')}_steps.rb")
 
-      step_lines.each do |line|
-        # Extrai keyword original e resto do passo
-        orig_kw, rest = line.split(' ', 2)
-        # Converte keyword conforme idioma de entrada
-        kw = case lang
-             when 'en' then pt_to_en[orig_kw] || orig_kw
-             else         en_to_pt[orig_kw] || orig_kw
-             end
-        raw = rest.dup
+      # Cabeçalho do arquivo gerado
+      conteudo = +"# encoding: utf-8\n"
+      conteudo << "# Definições de passos geradas automaticamente para #{File.basename(feature_path)}\n\n"
+
+      linhas_passos.each do |linha|
+        palavra_original, restante = linha.split(' ', 2)
+
+        # Define palavra-chave no idioma de saída
+        chave = case lang
+                when 'en' then pt_para_en[palavra_original] || palavra_original
+                else         en_para_pt[palavra_original] || palavra_original
+                end
 
-        scanner = ::StringScanner.new(rest)
-        pattern = ''
-        tokens  = []
+        texto_bruto = restante.dup
+        scanner = ::StringScanner.new(restante)
+        padrao = ''
+        tokens = []
 
         until scanner.eos?
           if scanner.check(/"<([^>]+)>"/)
             scanner.scan(/"<([^>]+)>"/)
             tokens << scanner[1]
-            pattern << '{string}'
+            padrao << '{string}'
           elsif scanner.check(/<([^>]+)>/)
             scanner.scan(/<([^>]+)>/)
             tokens << scanner[1]
-            pattern << '{int}'
+            padrao << '{int}'
           elsif scanner.check(/"([^"<>]+)"/)
             scanner.scan(/"([^"<>]+)"/)
             tokens << scanner[1]
-            pattern << '{string}'
+            padrao << '{string}'
           elsif scanner.check(/\d+(?:\.\d+)?/)
-            num = scanner.scan(/\d+(?:\.\d+)?/)
-            tokens << num
-            pattern << '{int}'
+            numero = scanner.scan(/\d+(?:\.\d+)?/)
+            tokens << numero
+            padrao << '{int}'
           else
-            pattern << scanner.getch
+            padrao << scanner.getch
           end
         end
 
-        # Escapa aspas no padrão final
-        safe_pattern = pattern.gsub('"', '\\"')
-        signature = "#{kw}(\"#{safe_pattern}\")"
+        # Escapa aspas no padrão
+        padrao_seguro = padrao.gsub('"', '\\"')
+        assinatura = "#{chave}(\"#{padrao_seguro}\")"
 
+        # Adiciona parâmetros se existirem tokens
         if tokens.any?
-          args = tokens.each_index.map { |i| "args#{i+1}" }.join(', ')
-          signature += " do |#{args}|"
+          argumentos = tokens.each_index.map { |i| "arg#{i+1}" }.join(', ')
+          assinatura << " do |#{argumentos}|"
         else
-          signature += ' do'
+          assinatura << ' do'
         end
 
-        content << signature << "\n"
-        content << "  pending 'Implementar passo: #{raw}'\n"
-        content << "end\n\n"
+        conteudo << "#{assinatura}\n"
+        conteudo << "  pending 'Implementar passo: #{texto_bruto}'\n"
+        conteudo << "end\n\n"
       end
 
-      File.write(file, content)
-      puts "✅ Steps gerados: #{file}"
+      # Escreve arquivo de saída
+      File.write(arquivo_saida, conteudo)
+      puts "✅ Steps gerados: #{arquivo_saida}"
       true
     end
   end
-end
+end

data/lib/bddgenx/utils/backup.rb

@@ -1,16 +1,31 @@
+# lib/bddgenx/backup.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Backup, responsável por criar cópias de segurança
+# de arquivos .feature antes de serem sobrescritos.
+# As cópias são salvas em 'reports/backup' com timestamp no nome.
+
 require 'fileutils'
 require 'time'
 
 module Bddgenx
+  # Gerencia a criação de backups de arquivos .feature
   class Backup
+    # Salva uma versão antiga de um arquivo .feature em reports/backup,
+    # adicionando um timestamp ao nome do arquivo.
+    #
+    # @param caminho [String] Caminho completo para o arquivo .feature original
+    # @return [void]
+    # @note Se o arquivo não existir, não faz nada
     def self.salvar_versao_antiga(caminho)
       return unless File.exist?(caminho)
 
-      pasta = 'reports/backup'
+      pasta     = 'reports/backup'
       FileUtils.mkdir_p(pasta)
-      base = File.basename(caminho, ".feature")
-      timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
-      destino = "reports/backup/#{base}_#{timestamp}.feature"
+
+      base      = File.basename(caminho, '.feature')
+      timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+      destino   = "reports/backup/#{base}_#{timestamp}.feature"
 
       FileUtils.cp(caminho, destino)
       puts "📦 Backup criado: #{destino}"

data/lib/bddgenx/utils/fontLoader.rb

@@ -1,30 +1,48 @@
 # lib/bddgenx/font_loader.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe FontLoader, responsável por localizar e carregar
+# famílias de fontes TrueType para uso com Prawn em geração de PDFs.
+# Busca os arquivos de fonte no diretório assets/fonts dentro da gem.
+
 require 'prawn'
-require 'rubygems'  # para Gem.loaded_specs
+require 'rubygems'  # para Gem.loaded_specs se necessário
 
 module Bddgenx
+  # Gerencia o carregamento de fontes TTF para os documentos PDF.
   class FontLoader
-    # Retorna o diretório assets/fonts dentro da gem, mesmo em dev local
+    # Retorna o caminho absoluto para a pasta assets/fonts dentro da gem
+    #
+    # @return [String] Caminho completo para o diretório de fontes
     def self.fonts_path
-      File.expand_path('../../bddgenx/assets/fonts', __dir__)
+      File.expand_path('../../assets/fonts', __dir__)
     end
 
-    # Retorna famílias de fontes TrueType para Prawn; vazio se faltar arquivos
+    # Cria o hash de famílias de fontes para registro no Prawn
+    #
+    # Verifica se os arquivos de fonte DejaVuSansMono incluem normal, bold,
+    # italic e bold_italic e têm tamanho mínimo aceitável.
+    # Se estiverem ausentes ou corrompidas, retorna hash vazio para usar fallback.
+    #
+    # @return [Hash{String => Hash<Symbol, String>}]
+    #   - Chave: nome da família ('DejaVuSansMono')
+    #   - Valor: mapa de estilos (:normal, :bold, :italic, :bold_italic) para os caminhos dos arquivos
     def self.families
       base = fonts_path
       return {} unless Dir.exist?(base)
 
-      files = {
+      arquivos = {
         normal:      File.join(base, 'DejaVuSansMono.ttf'),
         bold:        File.join(base, 'DejaVuSansMono-Bold.ttf'),
         italic:      File.join(base, 'DejaVuSansMono-Oblique.ttf'),
         bold_italic: File.join(base, 'DejaVuSansMono-BoldOblique.ttf')
       }
 
-      if files.values.all? { |path| File.file?(path) && File.size(path) > 12 }
-        { 'DejaVuSansMono' => files }
+      # Verifica existência e tamanho mínimo de cada arquivo
+      if arquivos.values.all? { |path| File.file?(path) && File.size(path) > 12 }
+        { 'DejaVuSansMono' => arquivos }
       else
-        warn "⚠️ Fontes DejaVuSansMono ausentes ou corrompidas em #{base}."
+        warn "⚠️ Fontes DejaVuSansMono ausentes ou corrompidas em #{base}. Usando fallback Courier."
         {}
       end
     end

data/lib/bddgenx/utils/parser.rb

@@ -1,25 +1,56 @@
+# lib/bddgenx/parser.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Parser, responsável por ler e interpretar
+# arquivos de história (.txt), extraindo cabeçalho e blocos de passos e exemplos.
+# Utiliza constantes para identificação de tipos de blocos e suporta idiomas
+# Português e Inglês na marcação de idioma e blocos de exemplos.
+
 module Bddgenx
-  # Tipos de blocos GUARDADOS, incluindo português EXEMPLO/EXEMPLOS
+  # Tipos de blocos reconhecidos na história (.txt), incluindo variações em Português
+  # e Inglês para blocos de exemplo.
+  # @return [Array<String>]
   TIPOS_BLOCOS = %w[
     CONTEXT SUCCESS FAILURE ERROR EXCEPTION
     VALIDATION PERMISSION EDGE_CASE PERFORMANCE
     EXEMPLO EXEMPLOS RULE
   ].freeze
 
+  # Parser de arquivos de história, converte .txt em estrutura de hash
+  # com elementos :como, :quero, :para, :idioma e lista de :grupos.
   class Parser
-    # Lê arquivo de história (.txt) e retorna hash com atributos e grupos
+    # Lê e analisa um arquivo de história, retornando um Hash com a estrutura:
+    # {
+    #   como:       String ou nil,
+    #   quero:      String ou nil,
+    #   para:      String ou nil,
+    #   idioma:     'pt' ou 'en',
+    #   grupos: [
+    #     {
+    #       tipo:     String (tipo de bloco),
+    #       tag:      String ou nil (tag opcional após o bloco),
+    #       passos:   Array<String> (linhas de passo),
+    #       exemplos: Array<String> (linhas de exemplo)
+    #     },
+    #     ...
+    #   ]
+    # }
+    #
+    # @param caminho_arquivo [String] Caminho para o arquivo .txt de história
+    # @raise [Errno::ENOENT] Se o arquivo não for encontrado
+    # @return [Hash] Estrutura da história pronta para geração de feature
     def self.ler_historia(caminho_arquivo)
-      # Lê todas as linhas, mantendo vazias
+      # Carrega linhas do arquivo, preservando linhas vazias e encoding UTF-8
       linhas = File.readlines(caminho_arquivo, encoding: 'utf-8').map(&:rstrip)
 
-      # Detecta idioma: aceita "# lang: en" ou "# language: en"
+      # Detecta idioma no topo do arquivo: suporta '# lang: <codigo>' ou '# language: <codigo>'
       idioma = 'pt'
       if linhas.first =~ /^#\s*lang(?:uage)?\s*:\s*(\w+)/i
         idioma = Regexp.last_match(1).downcase
         linhas.shift
       end
 
-      # Extrai Cabeçalho Como/Quero/Para
+      # Extrai cabeçalho: linhas que começam com Como/Quero/Para (variações PT/EN)
       como, quero, para = nil, nil, nil
       linhas.reject! do |l|
         if l =~ /^\s*(?:como|eu como|as a)/i && como.nil?
@@ -36,19 +67,27 @@ module Bddgenx
         end
       end
 
-      historia = { como: como, quero: quero, para: para, idioma: idioma, grupos: [] }
+      # Inicializa estrutura da história
+      historia = {
+        como:   como,
+        quero:  quero,
+        para:   para,
+        idioma: idioma,
+        grupos: []
+      }
       exemplos_mode = false
 
+      # Processa cada linha restante para blocos e exemplos
       linhas.each do |linha|
-        # Início de bloco de exemplos: [EXEMPLO] ou [EXEMPLOS] ou [EXAMPLES]
+        # Início de bloco de exemplos: [EXEMPLO], [EXEMPLOS] ou [EXAMPLES] com tag opcional
         if linha =~ /^\[(?:EXEMPLO|EXEMPLOS|EXAMPLES)\](?:@(\w+))?$/i
           exemplos_mode = true
-          # inicia array se for o primeiro exemplo
+          # Cria array de exemplos no último grupo, se ainda não existir
           historia[:grupos].last[:exemplos] = []
           next
         end
 
-        # Início de bloco de tipo (SUCCESS, FAILURE, REGRA etc.)
+        # Início de bloco com tipo definido em TIPOS_BLOCOS e tag opcional
         if linha =~ /^\[(#{TIPOS_BLOCOS.join('|')})\](?:@(\w+))?$/i
           exemplos_mode = false
           tipo = Regexp.last_match(1).upcase
@@ -57,7 +96,7 @@ module Bddgenx
           next
         end
 
-        # Atribui linhas ao último grupo
+        # Atribui linha ao último bloco, como passo ou exemplo conforme modo
         next if historia[:grupos].empty?
         bloco = historia[:grupos].last
         if exemplos_mode