ruby_tfs 0.0.1

data/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2013 Luke van der Hoeven
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

data/README.md

@@ -0,0 +1,55 @@
+# ruby_tfs
+TFS.rb is a wapper around the odata API for TFS
+
+- [The project](http://www.microsoft.com/en-us/download/details.aspx?id=36230)
+- [The specification][1]
+
+## Disclaimer
+This wrapper is mostly a shell around the `ruby_odata` gem to provide a "kinder"api specific to TFS and the capabilities within. If you want to get access beyond what this api provides, you can simply access the `TFS::Client.connection` object and run direct queries against odata, though if you want that kind of flexibility, it's probably better just got straight to the `ruby_odata` gem and skip this wrapper.
+
+## API
+
+The [TFS OData api][1] supports the following object types:
+
+- Builds
+- Build Definitions
+- Changesets
+- Changes
+- Branches
+- WorkItems
+- Attachments
+- Links
+- Projects
+- Queries
+- AreaPaths
+- IterationPaths
+
+Currently, we support the following (due to my own purposes) with plans to further support the rest as well:
+
+- Builds
+- Changesets
+- WorkItems
+- Projects
+- WorkItems
+
+### Querying
+
+All queries require a call to `#run` to finalize the query. This also makes it possible in most cases where you are defining a query to instead use `#to_query` to see the actual url-based query that will be run.
+
+## Notes
+While the api for `ruby_tfs` looks similar to Rails' `ActiveRecord` api, it is not meant to be an exact translation. The base type objects (`TFS::Builds`, `TFS::Projects`, etc) are setup to follow more of the [Repository pattern](http://martinfowler.com/eaaCatalog/repository.html) rather than an ORM-like pattern. The objects returned from the repository are actually from the [`ruby_odata`][2] library, which is a core dependency of this project. The odata lib does a great job of representing the OData… data, so I felt no need to re-wrap in a secondary set of layers. This opionon may change depending on the direction of the [`ruby_data`][2] project.
+
+## Plans
+The query engine currently works against the actual [OData api](http://www.odata.org/documentation/uri-conventions#QueryStringOptions). Eventually it'd be great to have a more "Ruby Way™" of doing this by doing some sort of query compilation between a Ruby DSL and the OData api. That will come in time.
+
+## Credits
+- Thanks to Damien White ([visoft](https://github.com/visoft)) for his [`ruby_odata`][2] wrapper. It made this project very painless to write.
+- Thanks to Microsoft for allowing an OData wrapper to exist for TFS. It makes writing third-party, non .NET apps much more fun. Go open source!
+
+## License
+Apache v2
+
+See the LICENSE.md file for more details.
+
+[1]: https://tfsodata.visualstudio.com/
+[2]: https://github.com/visoft/ruby_odata

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec

data/lib/tfs/builds.rb

@@ -0,0 +1,29 @@
+require 'tfs/work_items'
+require 'tfs/changesets'
+
+module TFS
+  class Builds < Queryable
+    add_child TFS::WorkItems
+    add_child TFS::Changesets
+
+    STATES = %w(All
+                Failed
+                InProgress
+                None
+                NotStarted
+                PartiallySucceeded
+                Stopped
+                Succeeded)
+
+    class << self
+      # To do an explicit build find, the API requires the definiton the build is from,
+      # the project it exists within, and the build number.
+      #
+      #     TFS::Builds.find("DevBuild", "My New Project", 'DevBuild.3')
+      #
+      def find(definition, project, number)
+        TFS.builds("Definition='#{definition}',Project='#{project}',Number='#{number}'").run.first
+      end
+    end
+  end
+end

data/lib/tfs/changesets.rb

@@ -0,0 +1,13 @@
+module TFS
+  class Changesets < Queryable
+    class << self
+      # Changeset can be found by id alone
+      #
+      #     TFS::Changeset.find(123)
+      #
+      def find(id)
+        TFS.changesets(id).run.first
+      end
+    end
+  end
+end

data/lib/tfs/class_helpers.rb

@@ -0,0 +1,19 @@
+module TFS
+  module ClassHelpers
+    def base_class(for_class=self)
+      name = (Class === for_class) ? for_class.name : for_class
+      name.split("::").last
+    end
+
+    def method_name_from_class(name=self.name)
+      base_class(name).downcase
+    end
+
+    SPECIAL_CASES = { workitems: "WorkItems" }
+
+    def odata_class_from_method_name(method_name)
+      return SPECIAL_CASES[method_name] if SPECIAL_CASES.has_key? method_name
+      method_name.to_s.capitalize
+    end
+  end
+end

data/lib/tfs/client.rb

@@ -0,0 +1,53 @@
+require 'ruby_odata'
+require 'tfs/configuration'
+
+require 'tfs/class_helpers'
+require 'tfs/query_engine'
+
+module TFS
+  class Client
+    include TFS::Configuration
+    extend TFS::ClassHelpers
+
+    # Options specific to the provider (odata in this case)
+    PROVIDER_OPTIONS = [:username, :password, :verify_ssl]
+
+    attr_reader :connection, :endpoint
+
+    # Creates an instance of the client
+    def initialize(options={})
+      TFS::Configuration.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || TFS.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+    # Creates the connection to the data provider source
+    def connect
+      @connection = @provider.new endpoint, opts_for_connection
+    end
+
+    [TFS::Builds, TFS::Changesets, TFS::Projects, TFS::WorkItems].each do |klass|
+      define_method(base_class(klass).downcase) do |*params|
+        TFS::QueryEngine.new(klass, @connection, params)
+      end
+    end
+
+    def run
+      @connection.execute
+    end
+
+    def method_missing(method_name, *args, &block)
+      return super unless @connection.respond_to? method_name
+      @connection.send(method_name, *args, &block)
+    end
+
+    private
+
+    def opts_for_connection
+      {
+        username: @username,
+        password: @password
+      }.merge connection_options
+    end
+  end
+end

data/lib/tfs/configuration.rb

@@ -0,0 +1,78 @@
+# Lots of these ideas were stolen from the spectacular
+# [sferik/twitter gem](https://github.com/sferik/twitter) gem
+module TFS
+  module Configuration
+    extend Forwardable
+
+    attr_writer :username, :password
+    attr_accessor :endpoint, :connection_options, :provider
+
+    def_delegator :options, :hash
+
+    CONNECTION_OPTIONS = {
+      :headers => {
+        :accept => 'application/json',
+        :user_agent => "TFS Ruby Gem",
+      },
+      :request => {
+        :open_timeout => 5,
+        :timeout => 10,
+      },
+      :verify_ssl => false
+    } unless defined? TFS::Configuration::CONNECTION_OPTIONS
+
+    class << self
+      def keys
+        @keys ||= [
+          :username,
+          :password,
+          :endpoint,
+          :connection_options,
+          :provider
+        ]
+      end
+
+      def connection_options
+        CONNECTION_OPTIONS
+      end
+
+      def username
+        ENV['TFS_USERNAME']
+      end
+
+      def password
+        ENV['TFS_PASSWORD']
+      end
+
+      def endpoint
+        ENV['TFS_ENDPOINT']
+      end
+
+      def provider
+        OData::Service
+      end
+
+      def options
+        Hash[Configuration.keys.map{|key| [key, send(key)]}]
+      end
+    end
+
+    def configure
+      yield self
+      self
+    end
+
+    def reset!
+      TFS::Configuration.keys.each do |key|
+        instance_variable_set(:"@#{key}", Configuration.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    private
+    def options
+      Hash[TFS::Configuration.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
+  end
+end

data/lib/tfs/projects.rb

@@ -0,0 +1,19 @@
+require 'tfs/work_items'
+
+module TFS
+  class Projects < Queryable
+    add_child TFS::WorkItems
+    add_child TFS::Builds
+    add_child TFS::Changesets
+
+    class << self
+      # Projects can be found by name alone
+      #
+      #     TFS::Projects.find("BFG")
+      #
+      def find(name)
+        TFS.projects(name).run.first
+      end
+    end
+  end
+end

data/lib/tfs/query_engine.rb

@@ -0,0 +1,103 @@
+require 'tfs/queryable'
+require 'tfs/builds'
+require 'tfs/changesets'
+require 'tfs/projects'
+
+require 'tfs/work_items'
+
+module TFS
+  class QueryEngine
+    extend Forwardable
+    include TFS::ClassHelpers
+
+    attr_reader :type
+
+    VALID_CLASSES = [
+      TFS::Builds,
+      TFS::Changesets,
+      TFS::Projects,
+      TFS::WorkItems
+    ]
+
+    DEFAULT_LIMIT = 50
+
+    def initialize(for_class, connection, params="")
+      check_type(for_class)
+      @type, @connection = for_class, connection
+
+      @native_query = @connection.send(base_class(for_class), normalize(params))
+    end
+
+    def raw
+      @native_query
+    end
+
+    def limit(count)
+      @native_query = @native_query.top(count)
+      self
+    end
+
+    def order_by(query)
+      @native_query = @native_query.order_by(query)
+      self
+    end
+
+    def where(filter)
+      @native_query = @native_query.filter(filter)
+      self
+    end
+
+    def count
+      @native_query = @native_query.count
+      self
+    end
+
+    def include(klass)
+      check_type(klass)
+      @native_query.expand(base_class(klass))
+      self
+    end
+
+    def page(start)
+      @native_query = @native_query.skip(start)
+      self
+    end
+
+    def run
+      @connection.execute
+    end
+
+    def to_query
+      @native_query.query
+    end
+
+    def method_missing(method_name, *args, &block)
+      return super unless @type.send "#{method_name}?".to_sym
+      @native_query.navigate(odata_class_from_method_name(method_name))
+      self
+    end
+
+    private
+    def check_type(for_class)
+      raise TypeError, "#{for_class.to_s} is not a valid query type." unless VALID_CLASSES.include? for_class
+    end
+
+    def normalize(params)
+      args = params.first
+      case args
+      when String
+        format_parameter(args)
+      when Array
+        args.map {|item| format_parameter(item) }.join(",")
+      when Hash
+        args.map {|k,v| "#{k.to_s.capitalize}=#{format_parameter(v)}"}.join(',')
+      else
+        args
+      end
+    end
+
+    def format_parameter(param)
+      "'#{param}'"
+    end
+  end
+end

data/lib/tfs/queryable.rb

@@ -0,0 +1,42 @@
+module TFS
+  class Queryable
+    class << self
+      include TFS::ClassHelpers
+      # Always limit to the default limit of 50 so as not to overwhelm the service
+      # If more are required, set `#limit` explicitly.
+      def all
+        get_query.limit(QueryEngine::DEFAULT_LIMIT).run
+      end
+
+      def inherited(klass)
+        klass.instance_eval do
+          @children = []
+
+          def add_child(child_class)
+
+            base = method_name_from_class(child_class).to_sym
+            self.send(:define_singleton_method, "#{base}?") { true }
+          end
+        end
+      end
+
+      # #odata_query allows you to access the raw query sytax provide by the OData api
+      #
+      #     TFS::Builds.odata_query('Status eq "Succeeded"')
+      #
+      def odata_query(raw_query)
+        get_query.where(raw_query)
+      end
+      alias :where :odata_query
+
+      private
+      def get_query
+        TFS.send(method_name_from_class)
+      end
+    end
+  end
+end
+
+# Eventually I'd like to see a query compiler that makes more
+# "ruby like" queries possible, instead of forcing users to use the OData
+# query api. For now, this is good enough.

data/lib/tfs/work_items.rb

@@ -0,0 +1,42 @@
+module TFS
+  class WorkItems < Queryable
+    InvalidRecord = Class.new(StandardError)
+
+    REQUIRED_PARAMS = [
+      "Title",
+      "Type",
+      "Project",
+      "Description"
+    ]
+
+    class << self
+      # Changeset can be found by id alone
+      #
+      #     TFS::Changeset.find(123)
+      #
+      def find(id)
+        TFS.workitems(id).run.first
+      end
+
+      def save(item)
+        REQUIRED_PARAMS.each do |param|
+          raise InvalidRecord, "Missing required parameter '#{param}'" if item.send(param).nil?
+        end
+
+        client.AddToWorkItems(item)
+        item = client.save_changes
+        item.first
+      end
+
+      def update(item)
+        client.update_object(item)
+        client.save_changes
+      end
+
+      private
+      def client
+        @client ||= TFS.client
+      end
+    end
+  end
+end

data/lib/tfs.rb

@@ -0,0 +1,30 @@
+require 'tfs/client'
+
+module TFS
+  # Wrapper for TFS::Client.new
+  class << self
+    include Configuration
+
+    # Shortcut to create and connect a client
+    def client
+      @client = begin
+        client = Client.new(options)
+        client.connect
+        client
+      end unless defined?(@client) && @client.hash == options.hash
+
+      @client
+    end
+
+    def respond_to_missing?(method_name, include_private=false); client.respond_to?(method_name, include_private); end if RUBY_VERSION >= "1.9"
+    def respond_to?(method_name, include_private=false); client.respond_to?(method_name, include_private) || super; end if RUBY_VERSION < "1.9"
+
+    private
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+  end
+end
+
+TFS.setup

data/ruby_tfs.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.add_dependency 'ruby_odata'
+
+  spec.add_development_dependency 'bundler', '~> 1.0'
+
+  spec.authors = ["Luke van der Hoeven"]
+  spec.description = %q{A Ruby interface to the TFS OData API.}
+  spec.email = ['hungerandthirst@gmail.com']
+  spec.files = %w(Rakefile LICENSE.md README.md ruby_tfs.gemspec)
+  spec.files += Dir.glob("lib/**/*.rb")
+  spec.homepage = 'https://github.com/BFGCOMMUNICATIONS/ruby_tfs'
+  spec.licenses = ['APLv2']
+  spec.name = 'ruby_tfs'
+  spec.require_paths = ['lib']
+  spec.required_rubygems_version = '>= 1.3.6'
+  spec.summary = spec.description
+  spec.test_files = Dir.glob("spec/**/*")
+  spec.version = "0.0.1"
+end