bddgenx 0.1.43 → 0.1.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27d5aae37397f6f4cbebc64d87ea9046812aa8ca9754f15963f7a943e04c870f
-  data.tar.gz: cad3d2ef7e11724824d2cd3c3a31ffd09725d189f6f20813488fd5164db1ea01
+  metadata.gz: bd8038688d2588671b6f69f67410b65bef4883160f91c1cee24e92d8b33ef959
+  data.tar.gz: 02277bee62f245aa0419ab0e9adf40986d09db1fe497bed70519e9fd196104b1
 SHA512:
-  metadata.gz: 8f9d4ff065c91d9b4c20e77fa2ef267c13c43d574d5f825afa0eb07f90518ba1994666a95464058152a8f8346a1283a9419311ad4ee3a55ed42ce75ae492a222
-  data.tar.gz: b7f6fc413a78140a23812ab38db086b49c5cb5db1fdd0f51251e5607df6a6c57481c07acee2c95303b9e99ffa1120ae8f165dde5a698dca4c915ab9c7ad0c1cb
+  metadata.gz: ac24edf1de0092569cd84ce8809b8bf0d4ede815070410870baf0e3cc0eec01f62c52a034479c4952c2206cbb3e235db2fbb1a3e5ece42bba76ded1b4a1573b4
+  data.tar.gz: 6ad785d7ecc283e2931c705c0b1e5d95b7cd627e84a58a79d8760f3b2d70d1a10a62e3b8a7350f9058f3e3c67aa2eaccddf083092ec85f9f6f95a7bf45db4d29

data/README.md

@@ -1,142 +1,82 @@
-# 🧪 Gerador de BDD Automático em Ruby
+# Gerador Automático de BDD em Ruby
 [![Gem Version](https://badge.fury.io/rb/bddgenx.svg)](https://badge.fury.io/rb/bddgenx)
 
-Este projeto gera arquivos `.feature` (Gherkin) e `steps.rb` automaticamente a partir de arquivos `.txt` com histórias de usuário, seguindo padrões ISTQB, parametrização com `Examples` e integração com pipelines.
+## Visão Geral
 
----
+Ferramenta Ruby para gerar automaticamente arquivos Gherkin (`.feature`) e definições de passos (`steps.rb`) a partir de histórias em texto. Atende aos padrões ISTQB, suporta parametrização com blocos de exemplos e fornece relatórios de QA (rastreabilidade, backups e PDF).
 
-## 📂 Estrutura do Projeto
-```txt
-bddgenx/  
-├── bin/bddgenx              # CLI executável  
-├── input/                   # .txt de histórias de usuário  
-├── features/                # .feature geradas  
-├── features/<nome>/steps/   # step definitions por feature (se existir)  
-├── reports/                 # todos os artefatos de saída  
-│   ├── backup/              # versões antigas de .feature  
-│   ├── output/              # rastreabilidade.csv  
-│   └── pdf/                 # relatórios camelCase  
-├── lib/  
-│   ├── bddgenx/  
-│   │   ├── parser.rb  
-│   │   ├── validator.rb  
-│   │   ├── generator.rb  
-│   │   ├── steps_generator.rb  
-│   │   ├── tracer.rb  
-│   │   ├── backup.rb  
-│   │   └── pdf_exporter.rb  
-│   └── bddgenx.rb           # Runner que orquestra tudo  
-├── Gemfile  
-├── bddgenx.gemspec  
-├── Rakefile 
-├── VERSION
-├── bump_version.sh  
-└── README.md
-```
-## ▶️ Como Executar
+## Instalação
 
-### 🔧 Requisitos
-- Ruby 3.x
-- `bundle install` (caso use gems como `prawn` ou `jira-ruby`)
+Adicione ao seu `Gemfile`:
 
-### 🏁 Comando direto:
+```ruby
+gem 'bddgenx'
+```
+
+Execute:
 
 ```bash
-ruby main.rb
+bundle install
 ```
 
-🧱 Com Rake:
+Ou instale diretamente:
+
 ```bash
-rake bddgen:gerar
+gem install bddgenx
 ```
 
-📥 Como Escrever um .txt de Entrada
-```txt
-# language: pt
-Como um usuario do sistema
-Quero fazer login com sucesso
-Para acessar minha conta
-
-[FAILURE]
-Quando preencho email e senha válidos
-Então vejo a tela inicial
+## Uso no Código
 
-[SUCCESS]
-Quando tento logar com "<email>" e "<senha>"
-Então recebo "<resultado>"
+```ruby
+require 'bddgenx'
 
-[EXAMPLES]
-| email            | senha   | resultado               |
-| user@site.com    | 123456  | login realizado         |
-| errado@site.com  | senha   | credenciais inválidas   |
+# Gera todas as features e steps a partir dos .txt em input/
+Bddgenx::Runner.execute
 ```
-✅ Blocos Suportados
-[CONTEXT] – contexto comum
 
-[SUCCESS] – cenário positivo
+## Tarefa Rake (opcional)
 
-[FAILURE] – cenário negativo
+Em um projeto Rails ou Ruby com Rake, adicione ao `Rakefile`:
 
-[ERROR], [EXCEPTION], [PERFORMANCE], etc.
+```ruby
+require 'bddgenx'
+require 'rake'
 
-[REGRA] ou [RULE] – regras de negócio
+namespace :bddgenx do
+  desc 'Gera .feature e steps a partir de histórias em input/'
+  task :gerar do
+    Bddgenx::Runner.execute
+  end
+end
+```
 
-[EXAMPLES] – tabela de dados para Scenario Outline
+## Formato do Arquivo de Entrada (`.txt`)
 
-🧠 Saída esperada (feature)
-```gherkin
+```txt
 # language: pt
-Funcionalidade: adicionar produtos ao carrinho
-
-  Como um cliente do e-commerce
-  Quero adicionar produtos ao carrinho
-  Para finalizar minha compra com praticidade
+Como um usuário do sistema
+Quero fazer login
+Para acessar minha conta
 
-  Regra: O carrinho não deve permitir produtos fora de estoque
-    E o valor total deve refletir o desconto promocional
+[SUCCESS]
+Quando preencho <email> e <senha>
+Então vejo a tela inicial
 
-  Contexto:
-    Dado que estou logado na plataforma
-    E tenho produtos disponíveis
+[EXAMPLES]
+| email            | senha   | resultado               |
+| user@site.com    | 123456  | login realizado         |
+| errado@site.com  | senha   | credenciais inválidas   |
+```
 
-  @success
-  Cenário: Teste Positivo - adiciono um produto ao carrinho - ele aparece na listagem do carrinho
-    Quando adiciono um produto ao carrinho
-    Então ele aparece na listagem do carrinho
+## Artefatos de QA
 
-  Esquema do Cenário: Gerado a partir de dados de exemplo
-    Quando adiciono "<produto>" com quantidade <quantidade>
-    Então vejo o total <total esperado>
+* **Backup**: versões antigas de `.feature` em `reports/backup` com timestamp
+* **PDF**: exporta features em P/B para `reports/pdf` via `PDFExporter`
 
-    Exemplos:
-      | produto        | quantidade | total esperado |
-      | Camiseta Azul  | 2          | 100            |
-      | Tênis Branco   | 1          | 250            |
-```
+## Integração CI/CD
 
-🧩 Step Definitions geradas
-```ruby
-Quando('adiciono "<produto>" com quantidade <quantidade>') do |produto, quantidade|
-  pending 'Implementar passo: adiciono "<produto>" com quantidade <quantidade>'
-end
+Exemplo de GitHub Actions:
 
-Então('vejo o total <total esperado>') do |total_esperado|
-  pending 'Implementar passo: vejo o total <total esperado>'
-end
-```
-🧾 Rastreabilidade
-- Gera automaticamente um CSV em output/rastreabilidade.csv com:
-- Nome do cenário
-- Tipo (SUCCESS, FAILURE, etc.)
-- Caminho do .feature
-- Origem do .txt
-
-🔄 Backup
-Toda vez que um .feature existente for sobrescrito, a versão anterior é salva em:
-```
-backup/
-```
-✅ Execução em CI/CD (GitHub Actions)
 ```yaml
 jobs:
   gerar_bdd:
@@ -145,26 +85,11 @@ jobs:
       - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
-      - run: ruby main.rb
+          ruby-version: '3.x'
+      - run: bundle install
+      - run: bundle exec ruby -e "require 'bddgenx'; Bddgenx::Runner.execute(only_new: true)"
 ```
-⚙️ Alternativa: Usar via Rake
-
-Você também pode executar a gem bddgenx com Rake, como em projetos Rails:
-
-Crie um arquivo Rakefile:
-```ruby
-require "bddgenx"
-require "rake"
 
-namespace :bddgenx do
-  desc "Gera arquivos .feature e steps a partir de arquivos .txt"
-  task :gerar do
-    Bddgenx::Runner.execute
-  end
-end
-```
+## Licença
 
-👨‍💻 Autor
-David Nascimento – Projeto de automação BDD com Ruby – 2025
----
+MIT © 2025 David Nascimento

data/Rakefile

@@ -1,54 +1,55 @@
+# Rakefile
+# Tarefas para geração automática de BDD e relatórios com bddgenx
+
 require 'rake'
-require_relative 'lib/bddgenx.rb'
-require_relative 'lib/bddgenx/utils/porter'
-require_relative 'lib/bddgenx/integrations/jira'
-require_relative 'lib/bddgenx/integrations/testlink'
+require 'fileutils'
+require 'bddgenx'
 
 namespace :bddgenx do
+  desc 'Gerar arquivos .feature, steps, rastreabilidade e backups'
+  task :gerar, [:only_new, :input_dir] do |t, args|
+    # Parâmetros: only_new (true/false), input_dir (pasta com .txt)
+    args.with_defaults(only_new: 'false', input_dir: 'input')
+    only_new = args.only_new == 'true'
+    input_dir = args.input_dir
+
+    files = FileList["#{input_dir}/*.txt"]
+    if files.empty?
+      puts "❌ Nenhum arquivo encontrado em \#{input_dir}"
+      next
+    end
+
+    files.each do |file|
+      puts "🔄 Processando história: \#{file}"
+      historia = Bddgenx::Parser.ler_historia(file)
+      next unless Bddgenx::Validator.validar(historia)
+
+      feature_path, conteudo = Bddgenx::Generator.gerar_feature(historia)
+
+      Bddgenx::Backup.salvar_versao_antiga(feature_path)
+      Bddgenx::Generator.salvar_feature(feature_path, conteudo)
 
-  desc "Gerar arquivos .feature, steps, rastreabilidade e backups"
-  task :gerar do
-    arquivos = Bddgenx::CLI.todos_arquivos('input')
-    arquivos.each do |arquivo|
-      puts "🔁 Executando: ruby bddgen.rb"
-      system("ruby lib/bddgen.rb")
+      Bddgenx::StepsGenerator.gerar_passos(feature_path)
+      Bddgenx::Tracer.adicionar_entrada(historia, feature_path)
     end
 
+    puts "✅ Geração concluída#{' (apenas novos)' if only_new}!"
   end
 
-  desc "Exportar todos os arquivos .feature para PDF"
+  desc 'Exportar todos os arquivos .feature para PDF'
   task :pdf do
-    puts "📦 Exportando para PDF..."
-    Bddgenx::PDFExporter.exportar_todos
+    puts '📦 Exportando features para PDF...'
+    result = Bddgenx::PDFExporter.exportar_todos
+    puts "   Gerados: \#{result[:generated].size}, Pulados: \#{result[:skipped].size}"
   end
 
-  desc "Enviar todos os cenários para o Jira"
-  task :jira do
-    jira = Bddgenx::Integrations::Jira.new(
-      username: ENV['JIRA_USER'],
-      api_token: ENV['JIRA_TOKEN'],
-      site: ENV['JIRA_SITE'],
-      project_key: ENV['JIRA_PROJECT']
-    )
-
-    Dir.glob("features/*.feature") do |arquivo|
-      conteudo = File.read(arquivo)
-      titulo = File.basename(arquivo, ".feature").gsub('_', ' ').capitalize
-      jira.enviar_cenario(titulo, conteudo)
-    end
-  end
-
-  desc "Enviar todos os cenários para o TestLink"
-  task :testlink do
-    testlink = Bddgen::Integrations::TestLink.new(
-      ENV['TESTLINK_TOKEN'],
-      ENV['TESTLINK_URL']
-    )
-
-    Dir.glob("features/*.feature") do |arquivo|
-      conteudo = File.readlines(arquivo).reject { |l| l.strip.start_with?("#") || l.strip.empty? }
-      titulo = File.basename(arquivo, ".feature").gsub('_', ' ').capitalize
-      testlink.criar_caso_teste(ENV['TESTLINK_PLAN_ID'].to_i, titulo, conteudo)
+  desc 'Remover diretórios gerados (reports/ e features/)'
+  task :clean do
+    %w[reports features].each do |dir|
+      FileUtils.rm_rf(dir)
+      puts "🗑️  Diretório removido: \#{dir}"
     end
   end
 end
+
+task default: 'bddgenx:gerar'

data/VERSION

@@ -1 +1 @@
-0.1.43
+0.1.45

data/lib/bddgenx/generator.rb

@@ -1,37 +1,82 @@
+# lib/bddgenx/generator.rb
+# encoding: utf-8
+#
+# Este arquivo define a classe Generator, responsável por gerar arquivos
+# .feature a partir de um hash de história ou de um arquivo de história em texto.
+# Suporta Gherkin em Português e Inglês, inclusão de tags, cenários simples
+# e esquemas de cenário com exemplos.
+
 require 'fileutils'
-require_relative 'utils/tipo_param'
 
 module Bddgenx
+  # Gera cenários e arquivos .feature baseados em histórias e grupos de passos.
   class Generator
+    # Palavras-chave Gherkin em Português
+    # @return [Array<String>]
     GHERKIN_KEYS_PT = %w[Dado Quando Então E Mas].freeze
+
+    # Palavras-chave Gherkin em Inglês
+    # @return [Array<String>]
     GHERKIN_KEYS_EN = %w[Given When Then And But].freeze
+
+    # Mapeamento PT -> EN
+    # @return [Hash{String=>String}]
     GHERKIN_MAP_PT_EN = GHERKIN_KEYS_PT.zip(GHERKIN_KEYS_EN).to_h
+
+    # Mapeamento EN -> PT
+    # @return [Hash{String=>String}]
     GHERKIN_MAP_EN_PT = GHERKIN_KEYS_EN.zip(GHERKIN_KEYS_PT).to_h
+
+    # Conjunto de todas as palavras-chave suportadas (PT + EN)
+    # @return [Array<String>]
     ALL_KEYS = GHERKIN_KEYS_PT + GHERKIN_KEYS_EN
 
-    # Divide raw example blocks into a single table
+    # Seleciona apenas as linhas que representam exemplos do cenário
+    #
+    # @param raw [Array<String>] Lista de linhas brutas do bloco de exemplos
+    # @return [Array<String>] Linhas que começam com '|' representando a tabela de exemplos
     def self.dividir_examples(raw)
       raw.select { |l| l.strip.start_with?('|') }
     end
 
-    # Gera .feature a partir de hash ou arquivo de história
-    # Respeita idioma em historia[:idioma]
+    # Gera conteúdo de um arquivo .feature a partir de um hash de história ou caminho para arquivo
+    #
+    # @param input [Hash, String]
+    #   Objeto de história com chaves :idioma, :quero, :como, :para, :grupos
+    #   Ou caminho para um arquivo de história que será lido via Parser.ler_historia
+    # @param override_path [String, nil]
+    #   Caminho de saída alternativo para o arquivo .feature
+    # @raise [ArgumentError] Se Parser.ler_historia lançar erro ao ler arquivo
+    # @return [Array(String, String)] Array com caminho e conteúdo gerado
     def self.gerar_feature(input, override_path = nil)
       historia = input.is_a?(String) ? Parser.ler_historia(input) : input
-      idioma = historia[:idioma] || 'pt'
-      nome_base = historia[:quero].gsub(/[^a-z0-9]/i, '_')
-                                  .downcase.split('_',3)[0,3].join('_')
-      caminho = override_path.is_a?(String) ? override_path : "features/#{nome_base}.feature"
+      idioma   = historia[:idioma] || 'pt'
+
+      # Geração do nome base do arquivo
+      nome_base = historia[:quero]
+                    .gsub(/[^a-z0-9]/i, '_')
+                    .downcase
+                    .split('_', 3)
+                    .first(3)
+                    .join('_')
+
+      caminho = if override_path.is_a?(String)
+                  override_path
+                else
+                  "features/#{nome_base}.feature"
+                end
 
+      # Definição das palavras-chave Gherkin conforme idioma
       palavras = {
-        feature:   idioma=='en' ? 'Feature'           : 'Funcionalidade',
-        contexto:  idioma=='en' ? 'Background'        : 'Contexto',
-        cenario:   idioma=='en' ? 'Scenario'          : 'Cenário',
-        esquema:   idioma=='en' ? 'Scenario Outline'  : 'Esquema do Cenário',
-        exemplos:  idioma=='en' ? 'Examples'          : 'Exemplos',
-        regra:     idioma=='en' ? 'Rule'              : 'Regra'
+        feature:  idioma == 'en' ? 'Feature'          : 'Funcionalidade',
+        contexto: idioma == 'en' ? 'Background'       : 'Contexto',
+        cenario:  idioma == 'en' ? 'Scenario'         : 'Cenário',
+        esquema:  idioma == 'en' ? 'Scenario Outline' : 'Esquema do Cenário',
+        exemplos: idioma == 'en' ? 'Examples'         : 'Exemplos',
+        regra:    idioma == 'en' ? 'Rule'             : 'Regra'
       }
 
+      # Cabeçalho do arquivo .feature
       conteudo = <<~GHK
         # language: #{idioma}
         #{palavras[:feature]}: #{historia[:quero].sub(/^Quero\s*/i,'')}
@@ -41,56 +86,51 @@ module Bddgenx
 
       GHK
 
-      pt_map = GHERKIN_MAP_PT_EN
-      en_map = GHERKIN_MAP_EN_PT
-      detect = ALL_KEYS
+      pt_map  = GHERKIN_MAP_PT_EN
+      en_map  = GHERKIN_MAP_EN_PT
+      detect  = ALL_KEYS
 
-      historia[:grupos].each_with_index do |grupo, idx|
-        passos = grupo[:passos] || []
+      historia[:grupos].each do |grupo|
+        passos   = grupo[:passos]  || []
         exemplos = grupo[:exemplos] || []
         next if passos.empty?
 
-        tag_line = ["@#{grupo[:tipo].downcase}", ("@#{grupo[:tag]}" if grupo[:tag])].compact.join(' ')
+        # Linha de tags para o grupo
+        tag_line = ["@#{grupo[:tipo].downcase}",
+                    ("@#{grupo[:tag]}" if grupo[:tag])]
+                     .compact.join(' ')
 
         if exemplos.any?
-          # Scenario Outline
+          # Cenário com Esquema
           conteudo << "    #{tag_line}\n"
           conteudo << "    #{palavras[:esquema]}: #{historia[:quero]}\n"
 
-          # Renderiza cada passo, mapeando connector mesmo se não for Gherkin padrão
+          # Passos do cenário
           passos.each do |p|
-            line = p.strip
-            parts = line.split(' ', 2)
-            # match connector case-insensitive
+            parts = p.strip.split(' ', 2)
             con_in = detect.find { |k| k.casecmp(parts[0]) == 0 } || parts[0]
-            text = parts[1] || ''
-            out_conn = idioma=='en' ? pt_map[con_in] || con_in : en_map[con_in] || con_in
-            conteudo << "      #{out_conn} #{text}
-"
+            text   = parts[1] || ''
+            out_conn = idioma == 'en' ? pt_map[con_in] || con_in : en_map[con_in] || con_in
+            conteudo << "      #{out_conn} #{text}\n"
           end
 
-          # Monta tabela de exemplos completa
-          # Renderiza o bloco de Examples exatamente como veio no TXT
+          # Bloco de exemplos original
           conteudo << "\n      #{palavras[:exemplos]}:\n"
           exemplos.select { |l| l.strip.start_with?('|') }.each do |line|
-            # Remove aspas apenas das células, mantendo todas as colunas e valores originais
             cleaned = line.strip.gsub(/^"|"$/, '')
             conteudo << "        #{cleaned}\n"
           end
           conteudo << "\n"
         else
-          # Scenario simples
+          # Cenário simples
           conteudo << "    #{tag_line}\n"
           conteudo << "    #{palavras[:cenario]}: #{grupo[:tipo].capitalize}\n"
           passos.each do |p|
-            line = p.strip
-            parts = line.split(' ', 2)
-            # match connector case-insensitive
+            parts = p.strip.split(' ', 2)
             con_in = detect.find { |k| k.casecmp(parts[0]) == 0 } || parts[0]
-            text = parts[1] || ''
-            out_conn = idioma=='en' ? pt_map[con_in] || con_in : en_map[con_in] || con_in
-            conteudo << "      #{out_conn} #{text}
-"
+            text   = parts[1] || ''
+            out_conn = idioma == 'en' ? pt_map[con_in] || con_in : en_map[con_in] || con_in
+            conteudo << "      #{out_conn} #{text}\n"
           end
           conteudo << "\n"
         end
@@ -99,10 +139,15 @@ module Bddgenx
       [caminho, conteudo]
     end
 
+    # Salva o conteúdo gerado em arquivo .feature no disco
+    #
+    # @param caminho [String] Caminho completo para salvar o arquivo
+    # @param conteudo [String] Conteúdo do arquivo .feature
+    # @return [nil]
     def self.salvar_feature(caminho, conteudo)
       FileUtils.mkdir_p(File.dirname(caminho))
       File.write(caminho, conteudo)
       puts "✅ Arquivo .feature gerado: #{caminho}"
     end
   end
-end
+end

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