metasploit-yard 1.0.0

data/lib/metasploit/yard/aruba/rvm_env/export.rb

@@ -0,0 +1,87 @@
+#
+# Gems
+#
+
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+require 'metasploit/yard/aruba/rvm_env/variable'
+
+# Recognizes `export`s of a variable
+class Metasploit::Yard::Aruba::RvmEnv::Export < Metasploit::Yard::Aruba::RvmEnv::Variable
+  #
+  # CONSTANTS
+  #
+
+  # Matches line with format `export <name>=<quote><value><quote>`
+  REGEXP = /\Aexport (?<name>.*?)=(?<quote>"|')(?<value>.*?)\k<quote>\Z/
+
+  #
+  # Attributes
+  #
+
+  # @!attribute value
+  #   The value to which {Metasploit::Yard::Aruba::RvmEnv::Variable#name} should be set
+  #
+  #   @return [String]
+  attr_accessor :value
+
+  #
+  # Class Methods
+  #
+
+  # Parses line of `rvm env` output into an {Export} if it matches {REGEXP}.
+  #
+  # @param line [String] a line of `rvm env` output
+  # @return [Export] if line contains `export`.
+  # @return [nil] otherwise
+  def self.parse(line)
+    # use self:: so subclasses can override
+    match = self::REGEXP.match(line)
+
+    if match
+      new(
+          name: match[:name],
+          value: match[:value]
+      )
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # @param attributes [Hash{Symbol=>String}]
+  # @option attributes [String] :name (see Metasploit::Yard::Aruba::RvmEnv::Variable#name})
+  # @option attributes [String] :value (see #value)
+  def initialize(attributes={})
+    attributes.assert_valid_keys(:name, :value)
+
+    super(name: attributes[:name])
+    @value = attributes[:value]
+  end
+
+  # Whether this export is the same class and has the same {#value} as `other`.
+  #
+  # @return [true] if `other.class` is `Metasploit::Yard::Aruba::RvmEnv::Export` and `other.value` is {#value}.
+  # @return [false] otherwise
+  def ==(other)
+    super(other) && other.value == self.value
+  end
+
+  # Set {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to {#value}.
+  #
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Metasploit::Yard::Aruba::RvmEnv::Unset] :from the old state of this variable
+  # @option options [Object] :world the cucumber world instance for the current scenario
+  def change(options={})
+    options.assert_valid_keys(:from, :world)
+
+    world = options.fetch(:world)
+
+    world.set_env(name, value)
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env/prepend.rb

@@ -0,0 +1,47 @@
+#
+# Gems
+#
+
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+require 'metasploit/yard/aruba/rvm_env'
+
+# Recognizes `export`s that are actually prepending values to the pre-existing value as is the case with `PATH`.
+class Metasploit::Yard::Aruba::RvmEnv::Prepend < Metasploit::Yard::Aruba::RvmEnv::Export
+  #
+  # CONSTANTS
+  #
+
+  # Matches line with format `export <name>=<quote><value>$<name><quote>`.  `<value>` will contain trailing
+  # `File::PATH_SEPARATOR`, so it can be directly prepended to the current value of `<name>` to get the value to set
+  # the environment variable.
+  REGEXP = /\Aexport (?<name>.*?)=(?<quote>"|')(?<value>.*?#{File::PATH_SEPARATOR})\$\k<name>\k<quote>\Z/
+
+  # Replaces {Metasploit::Yard::Aruba::RvmEnv::Export#value `:from` value} with
+  # {Metasploit::Yard::Aruba::RvmEnv::Export#value this variable's value}.
+  #
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Metasploit::Yard::Aruba::RvmEnv::Unset] :from the old state of this variable.
+  # @option options [Object] :world the cucumber world instance for the current scenario
+  def change(options={})
+    options.assert_valid_keys(:from, :world)
+
+    from = options.fetch(:from)
+    world = options.fetch(:world)
+
+    from_directories = from.value.split(File::PATH_SEPARATOR)
+    to_directories = value.split(File::PATH_SEPARATOR)
+
+    path = ENV[name]
+
+    to_directories.zip(from_directories) do |to_directory, from_directory|
+      path = path.gsub(from_directory, to_directory)
+    end
+
+    world.set_env(name, path)
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env/unset.rb

@@ -0,0 +1,56 @@
+#
+# Gems
+#
+
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+require 'metasploit/yard/aruba/rvm_env/variable'
+
+# Recognizes `unset`s of environment variables.
+class Metasploit::Yard::Aruba::RvmEnv::Unset < Metasploit::Yard::Aruba::RvmEnv::Variable
+  #
+  # CONSTANTS
+  #
+
+  # Matches line with format `unset <name>`
+  REGEXP = /\Aunset (?<name>.*?)\Z/
+
+  #
+  # Class Methods
+  #
+
+  # Parses lines of `rvm env` output into a {Prepend} if it matches {REGEXP}
+  #
+  # @param line [String] a line of `rvm env` output.
+  # @return [Unset] if line contains `unset`.
+  # @return [nil] otherwise
+  def self.parse(line)
+    match = REGEXP.match(line)
+
+    if match
+      new(
+          name: match[:name]
+      )
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # Unsets {Metasploit::Yard::Aruba::RvmEnv::Variable#name}.
+  #
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Metasploit::Yard::Aruba::RvmEnv::Unset] :from the old state of this variable
+  # @option options [Object] :world the cucumber world instance for the current scenario
+  def change(options={})
+    options.assert_valid_keys(:from , :world)
+
+    world = options.fetch(:world)
+    world.unset_env(name)
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env/variable.rb

@@ -0,0 +1,44 @@
+#
+# Gems
+#
+
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+require 'metasploit/yard/aruba/rvm_env'
+
+# An environment variable in `rvm env`.
+class Metasploit::Yard::Aruba::RvmEnv::Variable
+  #
+  # Attributes
+  #
+
+  # @!attribute name
+  #   The name of variable being manipulated in `rvm env`
+  #
+  #   @return [String]
+  attr_accessor :name
+
+  #
+  # Instance Methods
+  #
+
+  # @param attributes [Hash{Symbol=>String}]
+  # @option attributes [String] :name (see #name)
+  def initialize(attributes={})
+    attributes.assert_valid_keys(:name)
+
+    @name = attributes[:name]
+  end
+
+  # This variable is the same class and has the same {#name} as `other`.
+  #
+  # @return [true] if `other.class` is `Metasploit::Yard::Aruba::RvmEnv::Variable` and `other.name` is {#name}.
+  # @return [false] otherwise
+  def ==(other)
+    other.class == self.class && other.name == self.name
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env.rb

@@ -0,0 +1,103 @@
+#
+# Gems
+#
+
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+require 'metasploit/yard/aruba'
+
+# Helpers for parsing `rvm env` output
+module Metasploit::Yard::Aruba::RvmEnv
+  require 'metasploit/yard/aruba/rvm_env/export'
+  require 'metasploit/yard/aruba/rvm_env/prepend'
+  require 'metasploit/yard/aruba/rvm_env/unset'
+
+  #
+  # CONSTANTS
+  #
+
+  # Class for parsing lines for `rvm env` in order of precedence
+  LINE_PARSER_PRECEDENCE = [
+      # must be before `Metasploit::Yard::Aruba::RvmEnv::Export` because
+      # `Metasploit::Yard::Aruba::RvmEnv::Export::REGEXP` matches a superset of
+      # `Metasploit::Yard::Aruba::RvmEnv::Prepend::REGEXP`
+      Metasploit::Yard::Aruba::RvmEnv::Prepend,
+      Metasploit::Yard::Aruba::RvmEnv::Export,
+      Metasploit::Yard::Aruba::RvmEnv::Unset
+  ]
+
+  # Changes from one `rvm env [@<gemset>]` to another.
+  #
+  # @param options [Hash{Symbol => Array<Metasploit::Yard::Aruba::RvmEnv::Variable>}]
+  # @option options :from [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] the current rvm env; usually the output of
+  #   parsing `rvm env`.
+  # @option options :to [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] the new rvm env; usualy the output of parsing
+  #   `rvm env @<gemset>`
+  # @option options [Object] :world the cucumber World instance for the current scenario.
+  def self.change(options={})
+    options.assert_valid_keys(:from, :to, :world)
+
+    from_by_name = parsed_to_hash(options.fetch(:from))
+    to_by_name = parsed_to_hash(options.fetch(:to))
+    world = options.fetch(:world)
+
+    to_by_name.each do |name, to_variable|
+      from_variable = from_by_name[name]
+
+      # ignore variables that didn't change
+      unless to_variable == from_variable
+        to_variable.change(
+            from: from_variable,
+            world: world
+        )
+      end
+    end
+  end
+
+  # Parses the output of `rvm env`.
+  #
+  # @return [Array<Metasploit::Yard::Aruba::RvmEnv::Variable, #apply>]
+  def self.parse(rvm_env)
+    rvm_env.each_line.map { |line|
+      parse_line(line)
+    }
+  end
+
+  # Parses an individual line of `rvm env`
+  #
+  # @return [Metasploit::Yard::Aruba::RvmEnv::Variable, #apply]
+  # @raise [ArgumentError] if no `Class` in {LINE_PARSER_PRECEDENCE} returns a parsed instance.
+  def self.parse_line(line)
+    parsed = nil
+
+    LINE_PARSER_PRECEDENCE.each do |line_parser|
+      parsed = line_parser.parse(line)
+
+      if parsed
+        break
+      end
+    end
+
+    unless parsed
+      raise ArgumentError, "No line parser could parse #{line.inspect}"
+    end
+
+    parsed
+  end
+
+  # Converts output of {parse} into Hash that maps {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to the
+  # {Metasploit::Yard::Aruba::RvmEnv::Variable}.
+  #
+  # @param parsed [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] output of {parse}.
+  # @return [Hash{String => Metasploit::Yard::Aruba::RvmEnv::Variable}] Map of
+  #   {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to the {Metasploit::Yard::Aruba::RvmEnv::Variable}.
+  def self.parsed_to_hash(parsed)
+    parsed.each_with_object({}) { |variable, variable_by_name|
+      variable_by_name[variable.name] = variable
+    }
+  end
+end

data/lib/metasploit/yard/aruba.rb

@@ -0,0 +1,6 @@
+require 'metasploit/yard'
+
+# Helpers for aruba step definitions for testing `rake yard`
+module Metasploit::Yard::Aruba
+
+end

data/lib/metasploit/yard/railtie.rb

@@ -0,0 +1,12 @@
+require 'rails/railtie'
+
+module Metasploit
+  module Yard
+    # Automatically loads `yard.rake` for any Rails project.
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load 'tasks/yard.rake'
+      end
+    end
+  end
+end

data/lib/metasploit/yard/version.rb

@@ -0,0 +1,43 @@
+module Metasploit
+  module Yard
+    # Holds components of {VERSION} as defined by {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0}.
+    module Version
+      # The major version number.
+      MAJOR = 1
+      # The minor version number, scoped to the {MAJOR} version number.
+      MINOR = 0
+      # The patch number, scoped to the {MINOR} version number.
+      PATCH = 0
+
+      # The full version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the {PRERELEASE} in the
+      # {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0} format.
+      #
+      # @return [String] '{MAJOR}.{MINOR}.{PATCH}' on master.  '{MAJOR}.{MINOR}.{PATCH}-{PRERELEASE}' on any branch
+      #   other than master.
+      def self.full
+        version = "#{MAJOR}.#{MINOR}.#{PATCH}"
+
+        if defined? PRERELEASE
+          version = "#{version}-#{PRERELEASE}"
+        end
+
+        version
+      end
+
+      # The full gem version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the {PRERELEASE} in the
+      # {http://guides.rubygems.org/specification-reference/#version RubyGems versioning} format.
+      #
+      # @return [String] '{MAJOR}.{MINOR}.{PATCH}' on master.  '{MAJOR}.{MINOR}.{PATCH}.{PRERELEASE}' on any branch
+      #   other than master.
+      def self.gem
+        full.gsub('-', '.pre.')
+      end
+    end
+
+    # @see Version.gem
+    GEM_VERSION = Version.gem
+
+    # @see Version.full
+    VERSION = Version.full
+  end
+end

data/lib/metasploit/yard.rb

@@ -0,0 +1,18 @@
+
+#
+# Project
+#
+
+require 'metasploit/yard/version'
+
+# The namespace shared between all gems related to
+# [Metasploit Framework](https://github.com/rapid7/metasploit-framework) and
+# [Metasploit Commercial Editions](https://metasploit.com)
+module Metasploit
+  # Namespace for this gem.
+  module Yard
+    if defined?(Rails)
+      require 'metasploit/yard/railtie'
+    end
+  end
+end

data/lib/tasks/yard.rake

@@ -0,0 +1,58 @@
+# @note All options not specific to any given rake task should go in the .yardopts file so they are available to both
+#   the below rake tasks and when invoking `yard` from the command line
+
+#
+# Gems
+#
+# gems must load explicitly any gem declared in gemspec
+# @see https://github.com/bundler/bundler/issues/2018#issuecomment-6819359
+#
+#
+
+require 'yard'
+
+namespace :yard do
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    # --no-stats here as 'stats' task called after will print fuller stats
+    t.options = ['--no-stats']
+
+    t.after = Proc.new {
+      Rake::Task['yard:stats'].execute
+    }
+  end
+
+  desc "Shows stats for YARD Documentation including listing undocumented modules, classes, constants, and methods"
+  task :stats => :environment do
+    stats = YARD::CLI::Stats.new
+    stats.run('--compact', '--list-undoc')
+
+    threshold = 100.0
+    threshold_path = 'config/yard-stats-threshold'
+
+    if File.exist?(threshold_path)
+      threshold = File.read(threshold_path).to_f
+    end
+
+    # duplicates end of YARD::CLI::Stats#print_statistics
+    # @see https://github.com/lsegal/yard/blob/76c7525f46df38f7b24d4b3cb9daeef512fe58e8/lib/yard/cli/stats.rb#L63-L69
+    total = stats.instance_eval {
+      if @undocumented == 0
+        100
+      elsif @total == 0
+        0
+      else
+        (@total - @undocumented).to_f / @total.to_f * 100
+      end
+    }
+
+    if total < threshold
+      $stderr.puts "Documentation percentage (%<total>.2f%%) below threshold (%<threshold>.2f%%)" % { total: total, threshold: threshold}
+      exit 1
+    end
+  end
+end
+
+# @todo Figure out how to just clone description from yard:doc
+desc "Generate YARD documentation"
+# allow calling namespace to as a task that goes to default task for namespace
+task :yard => ['yard:doc']

data/metasploit-yard.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'metasploit/yard/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "metasploit-yard"
+  spec.version       = Metasploit::Yard::VERSION
+  spec.authors       = ["Luke Imhoff"]
+  spec.email         = ["luke_imhoff@rapid7.com"]
+  spec.summary       = "yard rake tasks"
+  spec.description   = "YARD rake tasks used through the metasploit-* gem namespace"
+  spec.homepage      = "https://github.com/rapid7/"
+  spec.license       = "BSD-3-Clause"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  # assert_valid_keys
+  spec.add_development_dependency 'activesupport'
+  spec.add_development_dependency 'aruba'
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'cucumber'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov'
+
+  spec.add_runtime_dependency 'rake'
+  spec.add_runtime_dependency 'yard'
+
+  # Ruby 1.9 JSON Hash syntax is used
+  spec.required_ruby_version = '>= 1.9'
+end

data/spec/metasploit/yard/version_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+
+RSpec.describe Metasploit::Yard::Version do
+  context 'CONSTANTS' do
+    context 'MAJOR' do
+      subject(:major) do
+        described_class::MAJOR
+      end
+
+      it { is_expected.to be_a Integer }
+    end
+
+    context 'MINOR' do
+      subject(:minor) do
+        described_class::MINOR
+      end
+
+      it { is_expected.to be_a Integer }
+    end
+
+    context 'PATCH' do
+      subject(:patch) do
+        described_class::PATCH
+      end
+
+      it { is_expected.to be_a Integer }
+    end
+
+    pull_request = ENV['TRAVIS_PULL_REQUEST']
+
+    # a pull request cannot check PRERELEASE because it will be tested in the target branch, but the source itself
+    # is from the source branch and so has the source branch PRERELEASE.
+    #
+    # PRERELEASE can only be set appropriately for a merge by merging to the target branch and then updating PRERELEASE
+    # on the target branch before committing and/or pushing to github and travis-ci.
+    if pull_request.nil? || pull_request == 'false'
+      context 'PREPRELEASE' do
+        subject(:prerelease) do
+          described_class::PRERELEASE
+        end
+
+        branch = ENV['TRAVIS_BRANCH']
+
+        if branch.nil? || branch.empty?
+          branch = `git rev-parse --abbrev-ref HEAD`.strip
+        end
+
+        if branch == 'master'
+          it 'does not have a PRERELEASE' do
+            expect(defined? described_class::PRERELEASE).to be_nil
+          end
+        else
+          branch_regex = %r{\A(?:refs/remotes/)?(?<type>bug|chore|feature|staging)(/(?<story>[^/]+))?/(?<prerelease>[^\/]+)\z}
+          match = branch.match(branch_regex)
+
+          if match
+            it 'matches the branch relative name' do
+              expected_prerelease = match[:prerelease]
+
+              expect(defined? described_class::PRERELEASE).not_to be_nil,
+                                                                  "PRERELEASE should be defined as #{expected_prerelease.inspect}"
+              expect(prerelease).to eq(expected_prerelease)
+            end
+          else
+            tag_regex = /\Av(?<major>\d+).(?<minor>\d+).(?<patch>\d+)(\.pre\.(?<prerelease>.*))?\z/
+            # travis-ci sets TRAVIS_BRANCH to the tag name for tag builds
+            match = branch.match(tag_regex)
+
+            if match
+              tag_prerelease = match[:prerelease]
+
+              if tag_prerelease
+                it 'matches the tag prerelease converted from a gem version to a VERSION' do
+                  expect(prerelease).to eq(tag_prerelease.gsub('.pre.', '-'))
+                end
+              else
+                it 'does not have a PRERELEASE' do
+                  expect(defined? described_class::PRERELEASE).to be_nil
+                end
+              end
+            else
+              it 'has a abbreviated reference that can be parsed for prerelease' do
+                fail "Do not know how to parse #{branch.inspect} for PRERELEASE"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  context 'full' do
+    subject(:full) do
+      described_class.full
+    end
+
+    #
+    # lets
+    #
+
+    let(:major) do
+      1
+    end
+
+    let(:minor) do
+      2
+    end
+
+    let(:patch) do
+      3
+    end
+
+    before(:each) do
+      stub_const("#{described_class}::MAJOR", major)
+      stub_const("#{described_class}::MINOR", minor)
+      stub_const("#{described_class}::PATCH", patch)
+    end
+
+    context 'with PRERELEASE' do
+      let(:prerelease) do
+        'prerelease'
+      end
+
+      before(:each) do
+        stub_const("#{described_class}::PRERELEASE", prerelease)
+      end
+
+      it 'is <major>.<minor>.<patch>-<prerelease>' do
+        expect(full).to eq("#{major}.#{minor}.#{patch}-#{prerelease}")
+      end
+    end
+
+    context 'without PRERELEASE' do
+      before(:each) do
+        hide_const("#{described_class}::PRERELEASE")
+      end
+
+      it 'is <major>.<minor>.<patch>' do
+        expect(full).to eq("#{major}.#{minor}.#{patch}")
+      end
+    end
+  end
+end

data/spec/metasploit/yard_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+RSpec.describe Metasploit::Yard do
+  context 'CONSTANTS' do
+    context 'VERSION' do
+      subject(:version) {
+        described_class::VERSION
+      }
+
+      it 'is Metasploit::Yard::Version.full' do
+        expect(version).to eq(Metasploit::Yard::Version.full)
+      end
+    end
+  end
+end