bddgenx 0.1.43 → 0.1.44

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bddgenx
 version: !ruby/object:Gem::Version
-  version: 0.1.43
+  version: 0.1.44
 platform: ruby
 authors:
 - David Nascimento
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: prawn-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: prawn-svg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Transforma arquivos .txt com histórias em arquivos .feature, com steps,
   rastreabilidade e integração com CI/CD.
 email:
@@ -49,7 +77,6 @@ files:
 - lib/bddgenx/utils/fontLoader.rb
 - lib/bddgenx/utils/parser.rb
 - lib/bddgenx/utils/pdf_exporter.rb
-- lib/bddgenx/utils/tipo_param.rb
 - lib/bddgenx/utils/tracer.rb
 - lib/bddgenx/utils/validator.rb
 - lib/bddgenx/version.rb

data/lib/bddgenx/utils/tipo_param.rb

@@ -1,16 +0,0 @@
-
-module Bddgenx
-  # Módulo para inferir o tipo de parâmetro a partir de exemplos
-  class TipoParam
-    # Retorna 'string', 'int', 'float' ou 'boolean'
-    def self.determine_type(nome, estrutura)
-      return 'string' unless estrutura[:cabecalho].include?(nome)
-      idx = estrutura[:cabecalho].index(nome)
-      vals = estrutura[:linhas].map { |l| l[idx] }
-      return 'boolean' if vals.all? { |v| %w[true false].include?(v.downcase) }
-      return 'int'     if vals.all? { |v| v.match?(/^\d+$/) }
-      return 'float'   if vals.all? { |v| v.match?(/^\d+\.\d+$/) }
-      'string'
-    end
-  end
-end