jiraby 0.0.1

data/.gitignore

@@ -0,0 +1,9 @@
+jira/*
+coverage/*
+.rvmrc
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+mockjira.pid
+doc/*
+.yardoc/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--pattern "spec/**/*_spec.rb"

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.3
+

data/.yardopts

@@ -0,0 +1,8 @@
+--readme README.md
+--markup markdown
+lib/**/*.rb
+-
+docs/index.md
+docs/usage.md
+docs/development.md
+docs/history.md

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem 'bundler'
+
+# Get all other dependencies from the gemspec
+gemspec
+

data/README.md

@@ -0,0 +1,132 @@
+Jiraby
+======
+
+Jiraby is a Ruby wrapper for the [JIRA](http://www.atlassian.com/JIRA)
+[REST API](https://docs.atlassian.com/jira/REST/latest/), supporting Jira
+versions 6.2 and up.
+
+[Full documentation is on rdoc.info](http://rubydoc.info/github/a-e/jiraby/master/frames).
+
+
+Connect to Jira
+---------------
+
+Assuming your JIRA site is at `http://jira.enterprise.com`, and you have
+an account `picard` with password `earlgrey`, you can connect like so:
+
+    require 'jiraby'
+
+    host = 'jira.enterprise.com:8080' # :PORT is optional
+    username = 'picard'
+    password = 'earlgrey'
+
+    jira = Jiraby::Jira.new(host, username, password)
+
+[HTTP basic](http://en.wikipedia.org/wiki/Basic_access_authentication)
+authentication is used for all requests.
+
+
+REST API
+--------
+
+Methods in the [JIRA REST API](https://docs.atlassian.com/jira/REST/6.2/) can be
+accessed directly using the `#get`, `#put`, `#post`, and `#delete` methods:
+
+    jira.get 'serverInfo'                         # info about Jira server
+    jira.get 'issue/TEST-1'                       # full details of TEST-1 issue
+    jira.get 'field'                              # all fields, both System and Custom
+    jira.get 'user/search', :username => 'bob'    # all users matching "bob"
+    jira.get 'user/search?username=bob'           # all users matching "bob"
+
+    jira.put 'issue/TEST-1', :fields => {         # set one or more fields
+      :summary => "Modified summary",
+      :description => "New description"
+    }
+
+    jira.delete 'issue/TEST-1'                    # delete issue TEST-1
+
+All REST methods return a `Jiraby::Entity` (a hash-like object built directly from
+the JSON response), or an `Array` of them (for those REST methods that return arrays).
+
+
+Wrappers
+--------
+
+You can look up a Jira issue using the `#issue` method:
+
+    issue = jira.issue('myproj-15')
+    issue = jira.issue('MYPROJ-15') # case-insensitive
+
+    issue.class
+    # => Jiraby::Issue
+
+If you're interested, view the raw data returned from Jira:
+
+    issue.data
+    # => {
+    #   'id' => '10024',
+    #   'key' => 'MYPROJ-15',
+    #   'self' => 'http://jira.enterprise.com:8080/rest/api/2/issue/10024',
+    #   'fields' => {
+    #     'summary' => 'Realign the dilithium stabilizer matrix.',
+    #     ...
+    #   }
+    # }
+
+Or use the higher-level methods provided by the `Issue` class:
+
+    issue['foo']              # Value of field 'foo'; same as `issue.data.fields.foo`
+    issue['foo'] = "Newval"   # Assign to field 'foo'
+    issue.subtasks            # Array of issue keys for this issue's subtasks
+    issue.is_subtask?         # True if issue is a sub-task of another issue
+    issue.parent              # For subtasks, issue key of parent issue
+    issue.is_assigned?        # True if issue is assigned
+
+When modifying fields, the changes will appear in the `Issue` instance immediately:
+
+    issue['summary'] = "Modified summary"
+
+    issue['summary']
+    # => "Modified summary"
+
+But these changes are not saved back to Jira until you call `#save!`. Before
+saving, you can check for pending changes:
+
+    issue.pending_changes?
+    # => true
+
+    issue.pending_changes
+    # => {"summary" => "Modified summary"}
+
+Then save the updates back to Jira:
+
+    issue.save!
+    # => true
+
+
+Copyright
+---------
+
+The MIT License
+
+Copyright (c) 2014 Eric Pierce
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rake'
+Dir.glob('tasks/*.rake').each { |r| import r }
+
+task :default => [:test]
+

data/docs/development.md

@@ -0,0 +1,20 @@
+Development
+===========
+
+Testing
+-------
+
+Jiraby is tested using a locally-installed instance of Jira. For licensing and
+size reasons that should be obvious, this local instance is not included in the
+Jiraby codebase itself. Here are the assumptions that the Jiraby test suite
+makes about your local Jira instance:
+
+- It's running at http://localhost:8080/
+- There is an administrator (in the 'jira-administrators' group):
+    - Username: admin
+    - Password: admin
+- There is a regular user (in the 'jira-users' group):
+    - Username: user
+    - Password: user
+- There is a project called 'TST'
+

data/docs/history.md

@@ -0,0 +1,5 @@
+Jiraby History
+==============
+
+TODO
+

data/docs/ideas.md

@@ -0,0 +1,54 @@
+Jiraby API ideas
+================
+
+- Implement an attribute wrapper for hashes, to allow stuff like:
+    issue.project.key
+    issue.project.owner
+    (See http://pullmonkey.com/2008/01/06/convert-a-ruby-hash-into-a-class-object/)
+
+Issue fields have different types. For example:
+
+    > iss.json['fields']['comment']
+     => {"comments"=>[], "startAt"=>0, "total"=>0, "maxResults"=>0}
+
+    > iss.json['fields']['environment']
+     => nil
+
+    > iss.json['fields']['summary']
+     => "It's broken"
+
+    > iss.json['fields']['subtasks']
+     => []
+
+Further, these are different in different versions of Jira. The above are from
+Jira 5.0, while Jira 4.4 produces:
+
+    > iss.json['fields']['comment']
+     => {"name"=>"comment", "value"=>[], "type"=>"com.atlassian.jira.issue.fields.CommentSystemField"}
+
+    > iss.json['fields']['environment']
+     => {"name"=>"environment", "type"=>"java.lang.String"}
+
+    > iss.json['fields']['summary']
+     => {"name"=>"summary", "value"=>"Cherwell incident #33170", "type"=>"java.lang.String"}
+
+    > iss.json['fields']['sub-tasks'] # NOTE: Different key
+     => {"name"=>"sub-tasks", "value"=>[], "type"=>"issuelinks"}
+
+Maintaining compatibility between both of these could be a royal pain. It's
+probably best to separate the REST / JSON stuff from the specific Jira/API
+version we're using.
+
+Consistency
+-----------
+
+The JIRA REST API is consistent in some things:
+
+  - It (almost) always returns JSON
+    Note: At least one method (PUT /issue/<key>) returns an empty string on success
+  - Use of `self` for each entity
+
+Challenges:
+
+  - How to remain authenticated (pass JSONResource around to each REST request)?
+

data/docs/index.md

@@ -0,0 +1,11 @@
+Jiraby
+======
+
+Jiraby is a Ruby interface to the [JIRA](http://www.atlassian.com/JIRA)
+[REST API](http://docs.atlassian.com/jira/REST/latest/).
+
+- [Usage](usage.md)
+- [Development](development.md)
+- [Ideas](ideas.md)
+- [History](history.md)
+

data/docs/usage.md

@@ -0,0 +1,64 @@
+Usage
+=====
+
+Assuming your JIRA site is at `http://jira.enterprise.com`, and you have
+an account `picard` with password `earlgrey`, you can connect like so:
+
+    require 'jiraby'
+
+    jira = Jiraby::Jira.new('http://jira.enterprise.com')
+    jira.login('picard', 'earlgrey')
+
+Using Jiraby from the Ruby console:
+
+    $ bundle console
+    > require 'lib/jiraby/jira'
+    > jira = Jiraby::Jira.new('http://localhost:8080')
+    > jira.login('username', 'password')
+    > jira.logout
+
+Methods in the [JIRA REST API](https://docs.atlassian.com/jira/REST/6.2/) can be
+accessed like so:
+
+    > jira.get('issue/TEST-1')
+    => {"id"=>"10000",
+     "self"=>"http://localhost:8080/rest/api/2/issue/10000",
+     "key"=>"TEST-1",
+     "fields"=>{ ... }
+     }
+
+    > jira.get('serverInfo')
+    => {"baseUrl"=>"http://localhost:8080",
+     "version"=>"6.2",
+     "versionNumbers"=>[6, 2, 0],
+     "buildNumber"=>6252,
+     "buildDate"=>"2014-02-19T00:00:00.000-0700",
+     "serverTime"=>"2014-03-06T08:27:04.116-0700",
+     "scmInfo"=>"aa343257d4ce030d9cb8c531be520be9fac1c996",
+     "serverTitle"=>"Jiraby Test"}
+
+    > jira.get('resolution/1')
+    => {"self"=>"http://localhost:8080/rest/api/2/resolution/1",
+     "id"=>"1",
+     "description"=>"A fix for this issue is checked into the tree and tested.",
+     "name"=>"Fixed"}
+
+Passing parameters to GET:
+
+    > jira.get('user/search?username=admin')
+    => [{"self"=>"http://localhost:8080/rest/api/2/user?username=admin",
+      "key"=>"admin",
+      "name"=>"admin",
+      "emailAddress"=>"epierce@automation-excellence.com",
+      "avatarUrls"=>
+       {"16x16"=>
+         "http://localhost:8080/secure/useravatar?size=xsmall&avatarId=10122",
+        "24x24"=>
+         "http://localhost:8080/secure/useravatar?size=small&avatarId=10122",
+        "32x32"=>
+         "http://localhost:8080/secure/useravatar?size=medium&avatarId=10122",
+        "48x48"=>"http://localhost:8080/secure/useravatar?avatarId=10122"},
+      "displayName"=>"Admin Istrator",
+      "active"=>true,
+      "timeZone"=>"America/Denver"}]
+

data/jiraby.gemspec

@@ -0,0 +1,31 @@
+Gem::Specification.new do |s|
+  s.name = "jiraby"
+  s.version = "0.0.1"
+  s.summary = "Jira-Ruby bridge"
+  s.description = <<-EOS
+    Jiraby is a Ruby wrapper for the JIRA REST API,
+    supporting Jira 6.x.
+  EOS
+  s.authors = ["Eric Pierce"]
+  s.email = "wapcaplet88@gmail.com"
+  s.homepage = "http://github.com/a-e/jiraby"
+  s.platform = Gem::Platform::RUBY
+
+  s.add_dependency 'rest-client'
+  s.add_dependency 'yajl-ruby'
+  s.add_dependency 'hashie'
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'sinatra'
+  s.add_development_dependency 'rakeup'
+  s.add_development_dependency 'thin'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
+
+  s.files = `git ls-files`.split("\n")
+  s.require_path = 'lib'
+end
+

data/lib/jiraby.rb

@@ -0,0 +1,8 @@
+require 'jiraby/exceptions'
+require 'jiraby/issue'
+require 'jiraby/jira'
+require 'jiraby/json_resource'
+require 'jiraby/project'
+
+module Jiraby
+end

data/lib/jiraby/entity.rb

@@ -0,0 +1,21 @@
+require 'hashie'
+
+module Jiraby
+  # Represents some data structure in Jira, as it would be returned by
+  # a REST API method.
+  class Entity < Hashie::Mash
+    # If no `args` are given, return the value in the `key` field (often used
+    # as an identifier in Jira). If `args` are given, pass-through to Hash's
+    # regular `key` method (returning the key for a given value).
+    def key(*args)
+      # Pass-through to Hash's `key` method
+      if args.length > 0
+        super(*args)
+      else
+        return self['key']
+      end
+    end
+
+  end # class Entity
+end # module Jiraby
+

data/lib/jiraby/exceptions.rb

@@ -0,0 +1,8 @@
+module Jiraby
+  class JirabyError < RuntimeError; end
+  class ProjectNotFound < JirabyError; end
+  class IssueNotFound < JirabyError; end
+  class RestCallFailed < JirabyError; end
+  class InvalidField < JirabyError; end
+end # module Jiraby
+

data/lib/jiraby/issue.rb

@@ -0,0 +1,109 @@
+require 'jiraby/exceptions'
+require 'jiraby/entity'
+
+module Jiraby
+  class Issue
+    def initialize(jira_instance, json_data={})
+      @jira = jira_instance
+      @data = Entity.new(json_data)
+      # Modifications are stored here until #save is called
+      @pending_changes = Entity.new
+    end
+
+    attr_reader :jira, :data, :pending_changes
+
+    # Return this issue's `key`
+    def key
+      return @data.key
+    end
+
+    # Set field `name_or_id` equal to `value`.
+    def []=(name_or_id, value)
+      @pending_changes[self.field_id(name_or_id)] = value
+    end
+
+    # Return the value in field `name_or_id`.
+    def [](name_or_id)
+      _id = self.field_id(name_or_id)
+      return @pending_changes[_id] || @data.fields[_id]
+    end
+
+    # Return a field ID, given a name or ID. `name_or_id` may be the field's ID
+    # (like "subtasks" or "customfield_10001"), or it may be the human-readable
+    # field name (like "Sub-Tasks" or "My Custom Field").
+    #
+    # TODO: Raise an exception on invalid name_or_id?
+    def field_id(name_or_id)
+      if @data.fields.include?(name_or_id)
+        return name_or_id
+      else
+        _id = @jira.field_mapping.key(name_or_id)
+        if _id.nil?
+          raise InvalidField.new("Invalid field name or ID: #{name_or_id}")
+        end
+        return _id
+      end
+    end
+
+    # Return true if this issue has a field with the given name or ID,
+    # false otherwise.
+    def has_field?(name_or_id)
+      begin
+        self.field_id(name_or_id)
+      rescue InvalidField
+        return false
+      else
+        return true
+      end
+    end
+
+    # Return true if this issue is a subtask, false otherwise.
+    def is_subtask?
+      return @data.fields.issuetype.subtask
+    end
+
+    # Return true if this issue is assigned to someone, false otherwise.
+    def is_assigned?
+      return !@data.fields.assignee.nil?
+    end
+
+    # Return this issue's parent key, or nil if this issue has no parent.
+    def parent
+      if is_subtask?
+        return @data.fields.parent.key
+      else
+        return nil
+      end
+    end
+
+    # Return this issue's subtask keys
+    def subtasks
+      return @data.fields.subtasks.collect { |st| st.key }
+    end
+
+    # Return a sorted list of valid field IDs for this issue.
+    def field_ids
+      return @data.fields.keys.sort
+    end
+
+    def editmeta
+      return @jira.get("issue/#{@data.key}/editmeta")
+    end
+
+    # Return true if this issue has been modified since saving.
+    def pending_changes?
+      return !@pending_changes.empty?
+    end
+
+    # Save this issue by sending a PUT request.
+    # Return true if save was successful.
+    def save!
+      json_data = {'fields' => @pending_changes}
+      # TODO: Handle failed save
+      @jira.put("issue/#{@data.key}", json_data)
+      @data.fields.merge!(@pending_changes)
+      @pending_changes = Entity.new
+      return true
+    end
+  end
+end