houston-core 0.5.0.beta1

data/README.md

@@ -0,0 +1,133 @@
+# Houston [![Code Climate](https://codeclimate.com/github/houston/houston.png)](https://codeclimate.com/github/houston/houston)
+
+### Mission Control for your projects and teams.
+
+Houston interfaces with your version-control, ticket-tracking, continuous integration, and other systems to stitch together a picture of your projects and teams.
+ 
+<table>
+  <tr>
+    <td align="center" vertical-align="top">
+      <a href="http://houston.github.com/houston/images/screenshots/burndown-chart.png" target="_blank" title="Ticket Workflow">
+        <img src="http://houston.github.com/houston/images/screenshots/burndown-chart.png" width="180" alt="Ticket Workflow" />
+      </a>
+    </td>
+    <td align="center" vertical-align="top">
+      <a href="http://houston.github.com/houston/images/screenshots/testing-conversation-2.png" target="_blank" title="Testing Workflow">
+        <img src="http://houston.github.com/houston/images/screenshots/testing-conversation-2.png" width="180" alt="Testing Workflow" />
+      </a>
+    </td>
+    <td align="center" vertical-align="top">
+      <a href="http://houston.github.com/houston/images/screenshots/new-release-2.png" target="_blank" title="Automatic Release Notes">
+        <img src="http://houston.github.com/houston/images/screenshots/new-release-2.png" width="180" alt="Automatic Release Notes" />
+      </a>
+    </td>
+    <td align="center" vertical-align="top">
+      <a href="http://houston.github.com/houston/images/screenshots/timeline.png" target="_blank" title="Reports">
+        <img src="http://houston.github.com/houston/images/screenshots/timeline.png" width="180" alt="Reports" />
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <th>Ticket Workflow</th>
+    <th>Testing Workflow</th>
+    <th>Automatic Release Notes</th>
+    <th>Reports</th>
+  </tr>
+</table>
+
+
+
+## Getting Started
+
+#### Requirements
+
+  * Ruby 2.0+
+  * Postgres 9.2+
+
+
+#### Getting Houston Running
+
+ 1. Clone Houston:
+
+    git clone git@github.com:houston/houston.git
+
+ 2. Modify config/database.yml to connect to your database (See [the Rails Guide](http://guides.rubyonrails.org/configuring.html#configuring-a-database) for examples)
+
+ 3. Set up your database
+
+    cd houston
+    script/bootstrap
+    bundle exec rake db:seed
+
+ 4. Start Houston
+
+    bundle exec rails server
+
+
+#### Configuring Houston
+
+You can control Houston's feature, permissions, events, colors, and more in `config/config.rb`.
+
+
+#### Writing your own modules
+
+To create a new module for Houston, run:
+
+    gem install houston-cli
+    houston_new_module warpcore
+
+This will generate a gem for a Rails Engine named `houston-warpcore`.
+
+Then add something like the following to `config/config.rb`:
+
+    use :warpcore, github: "mscott/warpcore", branch: "master"
+
+(You can use the same options after `use :warpcore` that you'd use after `gem "houston-warpcore"` in a `Gemfile`.)
+
+
+
+## Vision
+
+Houston does not intend to become a ticket-tracking system or continuous integration server. It's goal is to glue those systems together and synthesize information from them. Houston has three parts:
+
+ 1. A model of your projects and teams
+ 2. Adapters for various version-control, ticket-tracking, and other systems
+ 3. Custom views that synthesize that information
+
+You should pick a ticket-tracking system or a continuous integration server based on your teams needs&mdash;or your company's needs&mdash;but then be able to extend it as you wish. Houston is a framework for just that!
+
+
+
+## Features
+
+The following are examples of how Houston can be used:
+
+ - **Kanban** allows you define stages for tickets and then depicts how all of your tickets, across projects, fall into those stages.
+ - **Testing Report** collects tickets awaiting QA from multiple projects, and shows the progress and evolution of testing
+ - **Release Notes** are generated automatically from your commit messages, and can be configured to automatically close tickets when released
+ - **Scheduler** shows you tickets that need effort and value estimates and generates to-do lists from them based on your queuing discipline
+ - **CI** can be configured to trigger CI jobs and publish the results upon version-control events
+
+
+
+## Architecture
+
+### Models
+
+Four models are central to Houston:
+
+ - **Project** which ties together a slug, color, and different adapters with a project
+ - **User** which has a role and is tied to different permissions and notifications
+ - **Ticket** a generic concept of a ticket
+ - **Commit** a generic concept of a commit
+
+### Adapters
+
+Houston uses adapters to support multiple systems. There are three right now:
+ - **TicketTracking**: `Unfuddle` and `None` supported
+ - **VersionControl**: `Git` and `None` supported
+ - **CI**: `Jenkins` and `None` supported
+
+### Configuration
+
+The specific details of Houston's operation are described in config/config.rb ([example](https://github.com/houston/houston/blob/master/config/config.sample.rb)).

data/Rakefile

@@ -0,0 +1,8 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path("../config/application", __FILE__)
+
+require "bundler/gem_tasks"
+
+Houston::Application.load_tasks

data/app/adapters/houston/adapters.rb

@@ -0,0 +1,51 @@
+module Houston
+  module Adapters
+    class << self
+      
+      def each
+        constants.each do |name|
+          yield name, name_to_path(name)
+        end
+      end
+      
+      alias :[] :const_get
+      
+      def define_adapter_namespace(name)
+        namespace = ::Module.new
+        const_set name, namespace
+        
+        pathname = name_to_path(name)
+        adapters_paths = File.join(File.dirname(__FILE__), "adapters/#{pathname}/*_adapter.rb")
+        Dir[adapters_paths].each(&method(:require))
+        
+        def namespace.adapters
+          constants
+            .select { |sym| sym =~ /Adapter$/ }
+            .map { |sym| sym[/^.*(?=Adapter)/] }
+            .sort_by { |name| name == "None" ? "" : name }
+        end
+        
+        def namespace.adapter(name)
+          const_get "#{name}Adapter"
+        end
+        
+        def namespace.adapter?(name)
+          adapters.map(&:downcase).member?(name.to_s.downcase)
+        end
+      end
+      
+    private
+      
+      def name_to_path(name)
+        # Copied and simplified from ActiveSupport::Inflector.underscore
+        name.to_s
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+          .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+          .downcase
+      end
+      
+    end
+  end
+end
+
+Dir[File.join(File.dirname(__FILE__), "adapters/*.rb")].each(&method(:require))

data/app/adapters/houston/adapters/ci_server.rb

@@ -0,0 +1,5 @@
+require File.dirname(__FILE__)
+
+Houston::Adapters.define_adapter_namespace "CIServer"
+
+require "houston/adapters/ci_server/errors"

data/app/adapters/houston/adapters/ci_server/errors.rb

@@ -0,0 +1,16 @@
+module Houston
+  module Adapters
+    module CIServer
+      
+      class Error < StandardError
+      end
+      
+      class NotConfiguredError < ::Houston::Adapters::CIServer::Error
+      end
+      
+      class NotFoundError < ::Houston::Adapters::CIServer::Error
+      end
+      
+    end
+  end
+end

data/app/adapters/houston/adapters/ci_server/jenkins_adapter.rb

@@ -0,0 +1,21 @@
+module Houston
+  module Adapters
+    module CIServer
+      class JenkinsAdapter
+        
+        def self.errors_with_parameters(project)
+          {}
+        end
+        
+        def self.build(project)
+          Job.new(project)
+        end
+        
+        def self.parameters
+          []
+        end
+        
+      end
+    end
+  end
+end

data/app/adapters/houston/adapters/ci_server/jenkins_adapter/job.rb

@@ -0,0 +1,245 @@
+module Houston
+  module Adapters
+    module CIServer
+      class JenkinsAdapter
+        class Job
+          
+          def initialize(project)
+            @project = project
+            
+            config = Houston.config.ci_server_configuration(:jenkins)
+            
+            protocol = "http"
+            protocol = "https" if config[:port] == 443
+            jenkins_url = "#{protocol}://#{config[:host]}"
+            jenkins_url << ":#{config[:port]}" unless [80, 443].member?(config[:port])
+            
+            @connection = Faraday.new(url: jenkins_url)
+            @connection.basic_auth config[:username], config[:password] if config[:username] && config[:password]
+          end
+          
+          attr_reader :project, :connection
+          
+          def job_url
+            "#{@connection.url_prefix}#{job_path}"
+          end
+          
+          def job_path
+            "/job/#{project.slug}"
+          end
+          
+          def build_path(commit)
+            "#{job_path}/buildWithParameters?COMMIT_SHA=#{commit}"
+          end
+          
+          def last_build_url
+            url = "#{job_path}/api/json?tree=lastBuild[url]"
+            response = connection.get(url)
+            last_build_url_error!(url) unless 200 == response.status
+            MultiJson.load(response.body).fetch("lastBuild").fetch("url")
+          end
+          
+          def last_build_progress_url
+            url = last_build_url
+            url + "/console" if url
+          end
+          
+          def build!(commit)
+            url = build_path(commit)
+            Houston.try({max_tries: 5}, Faraday::Error::ConnectionFailed) do
+              Rails.logger.info "[jenkins] POST #{url}"
+              response = connection.post(url)
+              build_error!(url) unless [200, 201, 302].member?(response.status)
+              response
+            end
+          end
+          
+          def fetch_results!(build_url)
+            build_url = build_url.chomp("/")
+            results = {}
+            results.merge! fetch_overall_report!(build_url)
+            results.merge! fetch_test_report!(build_url)
+            results.merge! fetch_coverage_report!(build_url)
+          end
+          
+          
+          
+        private
+          
+          
+          
+          def fetch_overall_report!(build_url)
+            response = fetch_json(
+              "#{build_url}/api/json?tree=result",
+              resource_name: "the result of the build")
+            
+            { result: translate_result(response["result"]) }
+          end
+          
+          def fetch_test_report!(build_url)
+            response = fetch_json(
+              "#{build_url}/testReport/api/json",
+              resource_name: "detailed test results",
+              additional_error_info: "Most likely the build failed before the tests could be run.")
+            
+            tests = translate_suites(response["suites"])
+            regression_count = tests.count { |hash| hash[:status] == :regression }
+            { duration: translate_duration(response["duration"]),
+              total_count: tests.count,
+              regression_count: regression_count,
+              fail_count: response["failCount"] - regression_count,
+              pass_count: response["passCount"],
+              skip_count: response["skipCount"],
+              tests: tests }
+          end
+          
+          def fetch_coverage_report!(build_url)
+            response = fetch_json(
+              "#{build_url}/artifact/coverage/coverage.json",
+              resource_name: "coverage report",
+              fallback_value: {})
+            
+            metrics = response["metrics"] || {}
+            covered_percent = metrics["covered_percent"] / 100.0 if metrics.key?("covered_percent")
+            covered_strength = metrics["covered_strength"] / 100.0 if metrics.key?("covered_strength")
+            { coverage: translate_file_coverage(response["files"]),
+              covered_percent: covered_percent || 0,
+              covered_strength: covered_strength || 0 }
+          end
+          
+          
+          
+          def translate_result(result)
+            RESULT_MAP.fetch(result) do
+              raise NotImplementedError.new("#{result} is not a mapped result from Jenkins")
+            end
+          end
+          
+          def translate_duration(seconds)
+            seconds * 1000 # milliseconds!
+          end
+          
+          def translate_suites(suites)
+            suites.each_with_object([]) do |suite, tests|
+              suite_name = suite["name"]
+              suite["cases"].each do |test_case|
+                tests << translate_test_case(test_case).merge(suite: suite_name)
+              end
+            end
+          end
+          
+          def translate_test_case(test_case)
+            test = { name:  translate_test_name(test_case["name"]) }
+            
+            if test_case["skipped"]
+              test[:status]   = :skip
+            else
+              test[:status]   = translate_status(test_case["status"])
+              test[:duration] = translate_duration(test_case["duration"])
+              test[:age]      = test_case["age"]
+              
+              error_message, error_backtrace = translate_stack_trace(test_case["errorStackTrace"])
+              if error_message
+                # test[:status] = :error # <-- until we can differentiate errors and fails, call them fails
+                test[:error_message] = error_message
+                test[:error_backtrace] = error_backtrace
+              end
+            end
+            
+            test
+          end
+          
+          def translate_test_name(name)
+            name.gsub(/^test_/, "").gsub("_", " ")
+          end
+          
+          def translate_status(status)
+            STATUS_MAP.fetch(status) do
+              raise NotImplementedError.new("#{status} is not a mapped status from Jenkins")
+            end
+          end
+          
+          def translate_stack_trace(stack_trace)
+            lines = stack_trace.to_s.split("\n").map(&:strip).reject(&:blank?)
+            message = lines[0]
+            backtrace = lines[1..-1]
+            [message, backtrace]
+          end
+          
+          def translate_file_coverage(files)
+            Array.wrap(files).map do |file|
+              { filename: get_relative_filename(file["filename"]),
+                coverage: file["coverage"] }
+            end
+          end
+          
+          # Gets the path of the file in question relative to the
+          # project's root directory.
+          #
+          # Works by assuming that the project has been checked out
+          # to a folder named "workspace" by Jenkins: a reasonable
+          # assumption, but not probably the most robust way of
+          # implementing this!
+          WORKSPACE_MATCHER = /(?<=\/workspace\/).*/.freeze
+          def get_relative_filename(filename)
+            filename[WORKSPACE_MATCHER] || filename
+          end
+          
+          
+          
+          def fetch_json(url, options)
+            Rails.logger.debug "[jenkins] GET #{url}"
+            
+            response = connection.get(url)
+            unless response.status == 200
+              return options[:fallback_value] if options.key?(:fallback_value)
+              network_error!(url, options)
+            end
+            
+            JSON.parse(response.body)
+          rescue JSON::ParserError
+            parser_error!(url, options)
+          end
+          
+          def network_error!(url, options)
+            resource = options.fetch(:resource_name, "the resource")
+            error_message = "Houston could not get #{resource} from the URL #{url.inspect}."
+            error_message << " " << options[:additional_error_info] if options.key?(:additional_error_info)
+            raise Houston::Adapters::CIServer::Error, error_message
+          end
+          
+          def parser_error!(url, options)
+            resource = options.fetch(:resource_name, "the resource")
+            error_message = "Houston could not parse #{resource} from the URL #{url.inspect}."
+            error_message << " [#{$!.message}]"
+            error_message << " " << options[:additional_error_info] if options.key?(:additional_error_info)
+            raise Houston::Adapters::CIServer::Error, error_message
+          end
+          
+          def build_error!(url)
+            raise Houston::Adapters::CIServer::Error.new("Houston was unable to trigger a build for #{project.name} with the URL #{url}.")
+          end
+          
+          def last_build_url_error!(url)
+            raise Houston::Adapters::CIServer::Error.new("Houston was unable to fetch the job's lastBuild URL using #{url}.")
+          end
+          
+          
+          
+          RESULT_MAP = {
+            "FAILURE" => "fail",
+            "UNSTABLE" => "fail",
+            "SUCCESS" => "pass",
+            "ABORTED" => "aborted" }.freeze
+          STATUS_MAP = {
+            "FAILED" => :fail,
+            "REGRESSION" => :fail,
+            "SKIPPED" => :skip,
+            "PASSED" => :pass,
+            "FIXED"  => :pass }.freeze
+          
+        end
+      end
+    end
+  end
+end