bddgenx 0.1.43 → 0.1.45

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,28 +1,46 @@
 # 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
+    # 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('../../assets/fonts', __dir__)
     end
 
-    # Carrega famílias de fontes TrueType para Prawn
+    # 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}. Usando fallback Courier."
         {}

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

data/lib/bddgenx/utils/pdf_exporter.rb

@@ -1,18 +1,34 @@
 # lib/bddgenx/pdf_exporter.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe PDFExporter, responsável por gerar documentos
+# PDF a partir de arquivos .feature, formatados no estilo pretty Cucumber em
+# preto e branco.
+# Utiliza a gem Prawn para renderização de texto e tabelas.
+
 require 'prawn'
 require 'prawn/table'
 require 'fileutils'
 require_relative 'fontLoader'
 
-# Suprime aviso de internacionalização para fontes AFM built-in
+# Suprime aviso de internacionalização para fontes AFM internas
 Prawn::Fonts::AFM.hide_m17n_warning = true
 
 module Bddgenx
+  # Gera documentos PDF baseados em arquivos .feature.
   class PDFExporter
-    # Gera PDFs a partir de arquivos .feature no estilo pretty Cucumber em P/B
-    # Params:
-    # +caminho_feature+:: (String) caminho para um arquivo .feature específico. Se nil, gera para todos em features/*.feature
-    # +only_new+:: (Boolean) se true, não sobrescreve PDFs já existentes
+    # Gera PDFs de features, criando um para cada arquivo .feature ou apenas para
+    # o especificado em caminho_feature.
+    #
+    # @param caminho_feature [String, nil]
+    #   Caminho para um arquivo .feature específico. Se nil ou vazio, gera para todos
+    #   os arquivos em features/*.feature.
+    # @param only_new [Boolean]
+    #   Se true, não sobrescreve arquivos PDF já existentes.
+    # @return [Hash<Symbol, Array<String>>]
+    #   Retorna um hash com duas chaves:
+    #   - :generated => array de caminhos dos PDFs gerados
+    #   - :skipped   => array de caminhos dos PDFs que foram pulados
     def self.exportar_todos(caminho_feature: nil, only_new: false)
       FileUtils.mkdir_p('reports/pdf')
       features_list = if caminho_feature && !caminho_feature.empty?
@@ -21,14 +37,17 @@ module Bddgenx
                         Dir.glob('features/*.feature')
                       end
 
-      generated, skipped = [], []
+      generated = []
+      skipped   = []
+
       features_list.each do |feature|
         unless File.file?(feature)
           warn "⚠️ Feature não encontrada: #{feature}"
           next
         end
-        nome    = File.basename(feature, '.feature')
-        destino = "reports/pdf/#{camel_case(nome)}.pdf"
+
+        nome     = File.basename(feature, '.feature')
+        destino  = "reports/pdf/#{camel_case(nome)}.pdf"
 
         if only_new && File.exist?(destino)
           skipped << destino
@@ -42,14 +61,22 @@ module Bddgenx
       { generated: generated, skipped: skipped }
     end
 
-    # Converte string para camelCase, removendo caracteres especiais
+    # Converte uma string para formato camelCase, removendo caracteres especiais.
+    #
+    # @param str [String] A string de entrada a ser transformada.
+    # @return [String] String no formato camelCase.
     def self.camel_case(str)
       clean = str.gsub(/[^0-9A-Za-z ]/, '')
       parts = clean.split(/ |_/)
       ([parts.first&.downcase] + (parts[1..] || []).map(&:capitalize)).join
     end
 
-    # Gera o PDF formatado a partir de um único arquivo .feature, sem executar testes
+    # Gera um documento PDF a partir de um arquivo .feature, aplicando estilos
+    # de cabeçalhos, cenários, passos e tabelas conforme padrões Cucumber.
+    #
+    # @param origem [String] Caminho para o arquivo .feature de origem.
+    # @param destino [String] Caminho onde o PDF será salvo.
+    # @return [void]
     def self.exportar_arquivo(origem, destino)
       FileUtils.mkdir_p(File.dirname(destino))
       conteudo = File.read(origem, encoding: 'utf-8')
@@ -59,17 +86,21 @@ module Bddgenx
         pdf.font_size 9
 
         table_buffer = []
+
         conteudo.each_line do |linha|
           text = linha.chomp
 
-          # Agrupa linhas de tabela e renderiza quando termina
+          # Agrega linhas de tabela até o bloco terminar
           if text =~ /^\s*\|.*\|/i
-            table_buffer << text.gsub(/^\s*\||\|\s*$/, '').split('|').map(&:strip)
+            # Remove bordas laterais e separa colunas
+            row = text.gsub(/^\s*\||\|\s*$/, '').split('|').map(&:strip)
+            table_buffer << row
             next
           elsif table_buffer.any?
+            # Renderiza tabela acumulada
             pdf.table(table_buffer, header: true, width: pdf.bounds.width) do
-              self.header = true
-              self.row_colors = ['EEEEEE', 'FFFFFF']
+              self.header      = true
+              self.row_colors  = ['EEEEEE', 'FFFFFF']
               self.cell_style = { size: 8, font: 'Courier' }
             end
             pdf.move_down 4
@@ -95,6 +126,7 @@ module Bddgenx
             pdf.text text, size: 8, style: :italic
             pdf.move_down 4
           when /^(?:\s*)(Given|When|Then|And|But|Dado|Quando|Então|E|Mas)\b/i
+            # Passo Gherkin: destaca palavra-chave e texto
             keyword, rest = text.strip.split(' ', 2)
             pdf.indent(20) do
               pdf.formatted_text [
@@ -110,20 +142,21 @@ module Bddgenx
           end
         end
 
-        # Renderiza qualquer tabela remanescente
+        # Renderiza tabela remanescente, se houver
         if table_buffer.any?
           pdf.table(table_buffer, header: true, width: pdf.bounds.width) do
-            self.header = true
-            self.row_colors = ['EEEEEE', 'FFFFFF']
+            self.header      = true
+            self.row_colors  = ['EEEEEE', 'FFFFFF']
             self.cell_style = { size: 8, font: 'Courier' }
           end
           pdf.move_down 4
         end
 
+        # Numeração de páginas
         pdf.number_pages 'Página <page> de <total>', align: :right, size: 8
       end
     rescue => e
       warn "❌ Erro ao gerar PDF de #{origem}: #{e.message}"
     end
   end
-end
+end

data/lib/bddgenx/utils/tracer.rb

@@ -1,20 +1,40 @@
+# lib/bddgenx/tracer.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Tracer, responsável por gerar e manter
+# informações de rastreabilidade de cenários e passos em um arquivo CSV.
+# Útil para auditoria e análise de cobertura de cenários gerados.
+
 require 'csv'
 require 'fileutils'
 
 module Bddgenx
+  # Classe para adicionar registros de rastreabilidade a um relatório CSV.
   class Tracer
+    # Adiciona entradas de rastreabilidade para cada passo de cada grupo
+    # da história em um arquivo CSV localizado em 'reports/output/rastreabilidade.csv'.
+    #
+    # @param historia [Hash]
+    #   Objeto de história contendo :quero (título da funcionalidade) e :grupos,
+    #   onde cada grupo possui :tipo, :tag, e :passos (Array<String>)
+    # @param nome_arquivo_feature [String]
+    #   Nome do arquivo .feature de onde os passos foram gerados
+    # @return [void]
     def self.adicionar_entrada(historia, nome_arquivo_feature)
+      # Garante existência do diretório de saída
       FileUtils.mkdir_p('reports/output')
       arquivo_csv = 'reports/output/rastreabilidade.csv'
 
+      # Cabeçalho padrão do CSV: identifica colunas
       cabecalho = ['Funcionalidade', 'Tipo', 'Tag', 'Cenário', 'Passo', 'Origem']
 
       linhas = []
 
+      # Itera sobre grupos de passos para compor linhas de rastreabilidade
       historia[:grupos].each_with_index do |grupo, idx|
-        tipo = grupo[:tipo]
-        tag  = grupo[:tag]
-        passos = grupo[:passos]
+        tipo  = grupo[:tipo]
+        tag   = grupo[:tag]
+        passos = grupo[:passos] || []
 
         nome_funcionalidade = historia[:quero].gsub(/^Quero\s*/, '').strip
         nome_cenario = "Cenário #{idx + 1}"
@@ -31,10 +51,18 @@ module Bddgenx
         end
       end
 
+      # Escreve ou anexa as linhas geradas ao CSV
       escrever_csv(arquivo_csv, cabecalho, linhas)
     end
 
+    # Escreve ou anexa registros em um arquivo CSV, criando cabeçalho se necessário.
+    #
+    # @param caminho [String] Caminho completo para o arquivo CSV de rastreabilidade
+    # @param cabecalho [Array<String>] Array de títulos das colunas a serem escritos
+    # @param linhas [Array<Array<String>>] Dados a serem gravados no CSV (cada sub-array é uma linha)
+    # @return [void]
     def self.escrever_csv(caminho, cabecalho, linhas)
+      # Verifica se é um novo arquivo para incluir o cabeçalho
       novo_arquivo = !File.exist?(caminho)
 
       CSV.open(caminho, 'a+', col_sep: ';', force_quotes: true) do |csv|

data/lib/bddgenx/utils/validator.rb

@@ -1,32 +1,58 @@
+# lib/bddgenx/validator.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Validator, responsável por validar a estrutura
+# de uma história antes de gerar cenários ou arquivos .feature.
+# Verifica presença de cabeçalho obrigatório e integridade dos grupos de passos.
+
 module Bddgenx
+  # Valida objetos de história garantindo que possuam campos e blocos corretos.
   class Validator
+    # Valida o hash de história fornecido.
+    #
+    # Verifica:
+    # - Presença das chaves :como, :quero, :para no cabeçalho
+    # - Presença de pelo menos um grupo em :grupos
+    # - Cada grupo deve ter ao menos passos ou exemplos
+    # - Grupos do tipo "EXAMPLES" devem conter uma tabela de exemplos válida
+    #
+    # @param historia [Hash] Objeto de história com chaves :como, :quero, :para e :grupos
+    # @return [Boolean] Retorna true se a história for válida; caso contrário, false
     def self.validar(historia)
       erros = []
 
+      # Verificação do cabeçalho obrigatório
       unless historia[:como] && historia[:quero] && historia[:para]
         erros << "❌ Cabeçalho incompleto (Como, Quero, Para obrigatórios)"
       end
 
-      if historia[:grupos].empty?
+      # Verificação de grupos de passos
+      if historia[:grupos].nil? || historia[:grupos].empty?
         erros << "❌ Nenhum grupo de blocos detectado"
       else
         historia[:grupos].each_with_index do |grupo, idx|
-          if grupo[:passos].empty? && grupo[:exemplos].empty?
+          # Cada grupo deve conter passos ou exemplos
+          if (grupo[:passos].nil? || grupo[:passos].empty?) &&
+             (grupo[:exemplos].nil? || grupo[:exemplos].empty?)
             erros << "❌ Grupo #{idx + 1} do tipo [#{grupo[:tipo]}] está vazio"
           end
 
-          if grupo[:tipo] == "EXAMPLES" && grupo[:exemplos].none? { |l| l.strip.start_with?('|') }
+          # Validação específica para blocos de exemplos
+          if grupo[:tipo].casecmp('EXAMPLES').zero? &&
+             grupo[:exemplos].none? { |l| l.strip.start_with?('|') }
             erros << "❌ Grupo de EXAMPLES no bloco #{idx + 1} não contém tabela válida"
           end
         end
       end
 
+      # Exibe erros e retorna false se houver falhas
       if erros.any?
         puts "⚠️  Erros encontrados no arquivo:"
         erros.each { |e| puts "   - #{e}" }
         return false
       end
 
+      # História válida
       true
     end
   end