cukedep 0.0.1

data/lib/cukedep/config.rb

@@ -0,0 +1,31 @@
+# File: config.rb
+
+module Cukedep # Module used as a namespace
+
+FileMetaData = Struct.new(:name)
+
+Config = Struct.new(
+  :proj_dir,    # The directory of the cucumber project
+  :feature2id,  # Meta-data about the feature => feature id report
+  :id2feature,  # Meta-data about the feature id => feature report
+  :graph_file,  # Meta-data about the dependency graph file
+  :rake_file,   # Name of the output rake file
+  :cucumber_args # Command-line syntax to use for the cucumber application
+)
+
+# Re-open the class for further customisation
+  
+# Configuration object for the Cukedep application.
+class Config
+  # Factory method. Build a config object with default settings.
+  def self.default()
+    Config.new(nil, FileMetaData.new('feature2id.csv'), 
+      FileMetaData.new('feature2id.csv'), FileMetaData.new('dependencies.dot'),
+      'cukedep.rake', [])
+  end
+
+end # class
+
+end # module
+
+# End of file

data/lib/cukedep/constants.rb

@@ -0,0 +1,29 @@
+# File: constants.rb
+# Purpose: definition of Cukedep constants.
+
+module Cukedep # Module used as a namespace
+  # The version number of the gem.
+  Version = '0.0.1'
+
+  # Brief description of the gem.
+  Description = 'Manage dependencies between Cucumber feature files'
+
+  # Constant Cukedep::RootDir contains the absolute path of Rodent's
+  # root directory. Note: it also ends with a slash character.
+  unless defined?(RootDir)
+  # The initialisation of constant RootDir is guarded in order 
+  # to avoid multiple initialisation (not allowed for constants)
+
+    # The root folder of Cukedep.
+    RootDir = begin
+      require 'pathname'	# Load Pathname class from standard library
+      rootdir = Pathname(__FILE__).dirname.parent.parent.expand_path
+      rootdir.to_s + '/'	# Append trailing slash character to it
+    end
+    
+    # The file name for the user's settings
+    YMLFilename = '.cukedep.yml'
+  end
+end # module
+
+# End of file

data/lib/cukedep/feature-model.rb

@@ -0,0 +1,285 @@
+# File: feature-model.rb
+
+require 'tsort'
+require 'csv'
+require 'erb'
+require 'pathname'
+
+module Cukedep # This module is used as a namespace
+
+
+# The internal representation of a set of feature files.
+# Dependencies: use topological sort
+# TSort module http://ruby-doc.org/stdlib-1.9.3/libdoc/tsort/rdoc/TSort.html
+# See also: Is this topological sort in Ruby flawed?
+class FeatureModel
+
+FeatureDependencies = Struct.new(:dependee, :dependents)
+
+
+class DepGraph
+  include TSort # Mix-in module for topological sorting
+  
+  attr_reader(:dependencies)
+  
+  # Inverse lookup: from the feature file => FeatureDependencies
+  attr_reader(:lookup)
+  
+  def initialize(theDependencies)
+    @dependencies = theDependencies
+    @lookup = dependencies.each_with_object({}) do |f_dependencies, sub_result|
+      sub_result[f_dependencies.dependee] = f_dependencies
+    end
+  end
+  
+  # Method required by TSort module.
+  # It is used to iterate over all the nodes of the dependency graph
+  def tsort_each_node(&aBlock)
+    return dependencies.each(&aBlock)
+  end
+
+  # Method required by TSort module.
+  # It is used to iterate over all the children nodes of the given node.
+  def tsort_each_child(aDependency, &aBlock)
+    dependents = aDependency.dependents
+    children = dependents.map { |feature| lookup[feature] }
+    children.each(&aBlock)
+  end
+
+end # class
+
+
+  attr_reader(:feature_files)
+  
+  # An Array of FeatureDependencies
+  attr_reader(:dependencies)
+
+  def initialize(theFeatureFiles)
+    @feature_files = validated_model(theFeatureFiles)
+  end
+
+  # Retrieve the feature file matching the given feature identifiers
+  # theIds one or more Strings, each being one feature identifier
+  def select_by_ids(*theIds)
+    features_by_ids = id2features()
+    selection = theIds.each_with_object([]) do |an_id, sub_result|
+      found_feature = features_by_ids[an_id]
+      if found_feature.nil?
+        fail(StandardError, "No feature file with identifier '#{an_id}'.")
+      end
+      sub_result << found_feature
+    end
+    
+    return selection
+  end
+  
+  # The list of feature files without identifiers
+  def anonymous_features()
+    feature_files.select { |ff| ff.feature.anonymous? }
+  end
+
+  # Build an array of FileDependencies objects.
+  def dependency_links()
+    if @dependencies.nil?
+      # Build the mapping: feature identifier => feature
+      features_by_id = id2features()
+      
+      # Resolve the dependency tags
+      resolve_dependencies(features_by_id)
+    end
+    
+    return @dependencies
+  end
+
+
+  # Sort the feature files by dependency order.
+  def sort_features_by_dep()
+    dep_links = dependency_links()
+    graph = DepGraph.new(dep_links)
+    sorted_deps = graph.tsort()
+
+    all_sorted = sorted_deps.map(&:dependee)
+    @sorted_features = all_sorted.reject { |f| f.feature.anonymous? }
+  end
+  
+  # Generate CSV files detailing the feature to identifier mapping
+  # and vise versa
+  def mapping_reports(fileFeature2id, fileId2Feature, isVerbose = false)
+    puts "  #{fileFeature2id}" if isVerbose
+    # Generate the feature file name => feature identifier report
+    CSV.open(fileFeature2id, 'wb') do |f|
+      f << ['Feature file', 'Identifier']
+      feature_files.each do |ff|
+        identifier = ff.feature.identifier
+        filename = File.basename(ff.filepath)
+        f << [filename, identifier.nil? ? 'nil' : identifier]
+      end
+    end
+    
+    # Generate the feature file name => feature identifier report
+    puts "  #{fileId2Feature}" if isVerbose
+    CSV.open(fileId2Feature, 'wb') do |f|
+      f << ['identifier', 'feature file']
+      feature_files.each do |ff|
+        identifier = ff.feature.identifier
+        filename = File.basename(ff.filepath)
+        f << [identifier, filename] unless identifier.nil?
+      end
+    end    
+  end
+
+  # Create a graphical representation of the dependencies.
+  # The result is a DOT file that can be rendered via the DOT
+  # application from the GraphViz distribution.
+  def draw_dependency_graph(theDOTfile, isVerbose = false)
+    puts "  #{theDOTfile}" if isVerbose
+    dot_file = File.open(theDOTfile, 'w')
+    emit_heading(dot_file)
+    emit_body(dot_file)
+    emit_trailing(dot_file)
+  end
+  
+  
+  def emit_heading(anIO)
+    dir = File.dirname(File.absolute_path(feature_files[0].filepath))
+    heading =<<-EOS
+// Graph of dependencies of feature files in directory:
+// '#{dir}'
+// This file uses the DOT syntax, a free utility from the Graphviz toolset.
+// Graphviz is available at: www.graphviz.org
+// File generated on #{Time.now.asctime}.
+
+digraph g {
+  size = "7, 11"; // Dimensions in inches...
+  center = true;  
+  rankdir = BT; // Draw from bottom to top
+  label = "\\nDependency graph of '#{dir}'";  
+  
+  // Nodes represent feature files
+EOS
+    anIO.write heading
+  end
+  
+  # Output the nodes as graph vertices + their edges with parent node
+  def emit_body(anIO)
+  anIO.puts  <<-EOS
+  subgraph island {
+    node [shape = box, style=filled, color=lightgray];
+EOS
+    feature_files.each_with_index { |ff, i| draw_node(anIO, ff, i) if ff.feature.anonymous? }
+    
+    anIO.puts <<-EOS
+    label = "Isolated features";
+    }
+
+  subgraph dependencies {
+    node [shape = box, fillcolor = none];
+EOS
+    feature_files.each_with_index { |ff, i| draw_node(anIO, ff, i) unless ff.feature.anonymous? }
+    anIO.puts <<-EOS
+    label = "Dependencies";
+  }
+
+  // The edges represent dependencies
+EOS
+    dependencies.each {|a_dep| draw_edge(anIO, a_dep) }
+  end
+  
+  # Output the closing part of the graph drawing
+  def emit_trailing(anIO)
+    anIO.puts "} // End of graph" 
+  end
+  
+  # Draw a refinement node in DOT format
+  def draw_node(anIO, aFeatureFile, anIndex)
+    basename = File.basename(aFeatureFile.filepath, '.feature')
+    identifier_suffix = aFeatureFile.feature.anonymous? ? '' : " -- #{aFeatureFile.feature.identifier}"
+    anIO.puts %Q|    node_#{anIndex} [label = "#{basename}#{identifier_suffix}"];|
+  end
+  
+  # Draw an edge between feature files having dependencies.
+  def draw_edge(anIO, aDependency)
+    source_id = feature_files.find_index(aDependency.dependee)
+    target_ids = aDependency.dependents.map do |a_target|
+      feature_files.find_index(a_target)
+    end
+
+    target_ids.each do |t_id|
+      anIO.puts "\tnode_#{source_id} -> node_#{t_id};"
+    end
+  end
+
+
+  def generate_rake_tasks(rakefile, theProjDir)
+    puts "  #{rakefile}"
+    template_filepath = Pathname.new(File.dirname(__FILE__)).parent.parent + './templates/rake.erb'
+    template_source = File.read(template_filepath)
+
+    # Create one template engine instance     
+    engine = ERB.new(template_source)
+
+    source_dir = File.absolute_path(Dir.getwd())
+    proj_dir = File.absolute_path(theProjDir)
+    anonymous = anonymous_features.map {|ff| ff.basename}
+    feature_ids = feature_files.map { |ff| ff.feature.identifier }
+    feature_ids.compact!
+    deps = dependencies.reject {|dep| dep.dependee.feature.anonymous?}
+
+    # Generate the text representation with given context
+    file_source = engine.result(binding)
+    File.open(rakefile, 'w') { |f| f.write(file_source) }
+  end
+
+
+  protected
+  def validated_model(theFeatureFiles)
+    return theFeatureFiles
+  end
+
+  # Build the mapping: feature identifier => feature
+  def id2features()
+    mapping = feature_files.each_with_object({}) do |file, mp|
+      feature_id = file.feature.identifier
+      mp[feature_id] = file unless feature_id.nil?
+    end
+
+    return mapping
+  end
+  
+  # Given a feature identifier => feature mapping,
+  # resolve the dependency tags; that is,
+  # Establish links between a feature file object and its
+  # dependent feature file objects.
+  def resolve_dependencies(aMapping)
+    @dependencies = []
+    
+    feature_files.each do |feature_file|
+      feature = feature_file.feature
+      its_id = feature.identifier
+      dep_tags = feature.dependency_tags
+      # Complain when self dependency detected
+      if dep_tags.include?(its_id)
+        msg = "Feature #{} with identifier #{its_id} depends on itself!"
+        fail(StandardError, msg)
+      end
+      
+      # Complain when dependency tag refers to an unknown feature
+      dependents = dep_tags.map do |a_tag|
+        unless aMapping.include?(a_tag)
+          msg = "Feature with identifier '#{its_id}' depends on unknown feature '#{a_tag}'"
+          fail(StandardError, msg)
+        end
+        aMapping[a_tag]
+      end
+      
+      @dependencies << FeatureDependencies.new(feature_file, dependents)
+    end
+    
+    return @dependencies
+  end
+
+end # class
+
+end # module
+
+# end of file

data/lib/cukedep/feature-rep.rb

@@ -0,0 +1,49 @@
+# File: feature-rep.rb
+
+module Cukedep # This module is used as a namespace
+
+
+# A FeatureRep is the internal representation of a Gherkin feature.
+class FeatureRep
+  # Constant that specifies how feature identifier tags should begin
+  FeatureIdPrefix = /^feature:/
+  
+  # Constant that specifies how dependency tags should begin
+  DependencyPrefix = /^depends_on:/
+  
+  # The sorted list of all tags of the feature.
+  # The @ prefix is stripped from each tag text.
+  attr_reader(:tags)
+  
+  # The identifier of the feature. 
+  # It comes from a tag with the following syntax '@feature_' + identifier.
+  # Note that the @feature_ prefix is removed.
+  attr_reader(:identifier)
+
+
+  # theTags the tags objects from the Gherkin parser
+  def initialize(theTags)
+    # Strip first character of tag literal.
+    @tags = theTags.map { |t| t[1..-1] }
+    
+    @identifier = tags.find { |tg| tg =~ FeatureIdPrefix }
+    @identifier = @identifier.sub(FeatureIdPrefix, '') unless identifier.nil?
+  end
+  
+  public
+  # The list of all feature identifiers retrieved from the dependency tags
+  def dependency_tags()
+    dep_tags = tags.select { |t| t =~ DependencyPrefix }
+    return dep_tags.map { |t| t.sub(DependencyPrefix, '') }
+  end
+  
+  # Return true iff the identifier of the feature is nil.
+  def anonymous?()
+    return identifier.nil?
+  end
+
+end # class
+
+end # module
+
+# End of file

data/lib/cukedep/gherkin-listener.rb

@@ -0,0 +1,98 @@
+# File: gherkin-listener.rb
+
+require_relative 'feature-rep'
+
+
+module Cukedep # This module is used as a namespace
+
+
+class FeatureFileRep 
+  attr_reader(:filepath)
+  attr(:feature, true)
+  
+  def initialize(aFilepath)
+    @filepath = aFilepath
+  end
+  
+  def basename()
+    File.basename(filepath)
+  end
+end
+
+# A ParserListener listens to all the formatting events
+# emitted by the Gherkin parser.
+# It converts the received the feature file elements and builds
+# a representation of the feature files that is appropriate
+# for the Cukedep application.
+class GherkinListener
+  # The list of feature files encountered so far
+  attr_reader(:feature_files)
+
+  # Internal representation of the feature being parsed
+  attr(:current_feature, true)
+  
+  def initialize()
+    @feature_files = []
+  end
+  
+  ######################################
+  # Event listening methods
+  ######################################
+
+  # Called when beginning the parsing of a feature file.
+  # featureURI: path + filename of feature file.
+  def uri(featureURI)
+    new_file = FeatureFileRep.new(featureURI)
+    feature_files << new_file
+  end
+
+  # aFeature is a Gherkin::Formatter::Model::Feature instance
+  def feature(aFeature)
+    tag_names = aFeature.tags.map(&:name)
+    @current_feature = feature_files.last.feature = FeatureRep.new(tag_names)
+  end
+
+  # aBackground is a Gherkin::Formatter::Model::Background instance
+  def background(aBackground)
+    ; # Do nothing
+  end
+  
+  # aScenario is a Gherkin::Formatter::Model::Scenario instance
+  def scenario(aScenario)
+    ; # Do nothing
+  end
+  
+  # aScenarioOutline is a Gherkin::Formatter::Model::ScenarioOutline instance
+  def scenario_outline(aScenarioOutline)
+    ; # Do nothing  
+  end
+  
+  # theExamples is a Gherkin::Formatter::Model::Examples instance
+  def examples(theExamples)
+    ; # Do nothing 
+  end
+
+  # aStep is a Gherkin::Formatter::Model::Step instance
+  def step(aStep)
+    ; # Do nothing
+  end
+  
+  # End of feature file notification.
+  def eof()
+    ; # Do nothing
+  end
+
+
+  # Catch all method
+  def method_missing(message, *args)
+    puts "Method #{message} is not implemented (yet)."
+  end
+
+end # class
+
+end # module
+
+
+
+
+# End of file