trajectory 0.1.0

data/lib/trajectory/domain/project.rb

@@ -0,0 +1,168 @@
+module Trajectory
+  class Project
+    include Virtus
+
+    NUMBER_OF_WORKING_DAYS_BY_WEEK = 5.0
+
+    attr_writer :stories, :users_collection
+
+    # @return [Integer] the unique identifier of the project.
+    # @raise [MissingAttributeError] if id is nil
+    attribute :id, Integer, default: lambda { |project, attribute| raise MissingAttributeError.new(project, :id) }
+
+    # @return [String] the project name
+    attribute :name, String
+    # @!method archived?
+    # @return [true, false] true if the project has been archived, false otherwise
+    attribute :archived, Boolean
+    # @return [DateTime] creation date of the project
+    attribute :created_at, DateTime
+    # @return [Integer] the current velocity of the project
+    attribute :estimated_velocity, Integer
+    # @return [Array<Integer>] the velocities of past iterations
+    attribute :historic_velocity, Array[Integer]
+    # @return [String] project keyword identifier
+    attribute :keyword, String
+    # @return [DateTime] last modification date of the project
+    attribute :updated_at, DateTime
+    # @return [Integer] number of completed iterations in the project
+    attribute :completed_iterations_count, Integer
+    # @return [Integer] number of completed stories in the project
+    attribute :completed_stories_count, Integer
+
+    # Returns true if two projects are the sames i.e they share the same id
+    # attribute
+    #
+    # @param other [Project] the other object to compare
+    # @return [true, false]
+    def ==(other)
+      id == other.id
+    end
+
+    # Fetch all stories that belongs to the project
+    #
+    # @return [Stories] the stories collection
+    def stories
+      @stories ||= DataStore.stories_for_project(self)
+    end
+
+    # Fetch all iterations that belongs to the project
+    #
+    # @return [Iterations] the iterations collection
+    def iterations
+      @iterations ||= DataStore.iterations_for_project(self)
+    end
+
+    # Fetch all ideas that belongs to the project
+    #
+    # @return [Ideas] the ideas collection
+    def ideas
+      @ideas ||= DataStore.ideas_for_project(self)
+    end
+
+    # Fetch all users that belongs to the project
+    #
+    # @return [Users] the users collection
+    def users
+      @users_collection ||= DataStore.users_for_project(self)
+    end
+
+    # Fetch updates that belongs to the project since a given date
+    #
+    # @param since [DateTime] the date
+    # @return [Updates] the updates collection
+    def updates(since = DateTime.now)
+      DataStore.updates_for_project(self, since)
+    end
+
+    # Fetch a user from the project given its id or false if it does not exist
+    #
+    # @return [User, false] the user or false
+    def find_user_by_id(id)
+      users.find_by_id(id)
+    end
+
+    # Fetch the stories in a given iteration of a project
+    #
+    # @param iteration [Iteration] the iteration
+    # @return [Stories] the user
+    def stories_in_iteration(iteration)
+      stories.in_iteration(iteration)
+    end
+
+    # Returns the sum of all points of each story of the project
+    #
+    # @return [Integer] the points accumulation
+    def total_points
+      stories.inject(0) do |accumulator, story|
+        accumulator += story.points
+      end
+    end
+
+    # Returns estimated end date of the project with the actual estimated velocity
+    #
+    # @return [Date] the estimated date
+    def estimated_end_date
+      Date.today + remaining_days
+    end
+
+    # Returns the estimated number of days (weekend included) remaining before the end of the project.
+    #
+    # This is usefull to estimate the project end date.
+    #
+    # @return [Integer] the number of days
+    # @raise [VelocityEqualToZeroError] if estimated velocity is equal to zero (i.e the project can't be finished because no one actually works on it)
+    def remaining_days
+      raise VelocityEqualToZeroError.new(self) if estimated_velocity_per_day == 0
+      (remaining_points / estimated_velocity_per_day).ceil
+    end
+
+    # Returns sum of points of not completed stories
+    #
+    # @return [Integer] the number of points
+    def remaining_points
+      stories.not_completed.inject(0) do |accumulator, story|
+        accumulator += story.points
+      end
+    end
+
+    # Returns the estimated velocity by day over a week
+    #
+    # @return [Integer] the estimated velocity
+    def estimated_velocity_per_day
+      estimated_velocity / 7.0
+    end
+
+    # Returns the estimated number of working days (weekend excluded) remaining before the end of the project.
+    #
+    # This is usefull to be able to evaluate project budget as not all days are billable.
+    #
+    # @return [Integer] the number of days
+    # @raise [VelocityEqualToZeroError] if estimated velocity is equal to zero (i.e the project can't be finished because no one actually works on it)
+    def remaining_working_days
+      raise VelocityEqualToZeroError.new(self) if estimated_velocity_per_working_day == 0
+      (remaining_points / estimated_velocity_per_working_day).ceil
+    end
+
+    # Returns the estimated velocity by day over billable days (actually 5 days)
+    #
+    # @return [Integer] the estimated velocity
+    def estimated_velocity_per_working_day
+      estimated_velocity / NUMBER_OF_WORKING_DAYS_BY_WEEK
+    end
+
+    # Returns the completion percentage of the project
+    #
+    # @return [Float] the percentage
+    def percent_complete
+      (accepted_points.to_f / total_points * 100.0).round(1)
+    end
+
+    # Returns the sum of accepted story points
+    #
+    # @return [Integer] the number of points
+    def accepted_points
+      total_points - remaining_points
+    end
+  end
+end

data/lib/trajectory/domain/projects.rb

@@ -0,0 +1,55 @@
+require 'delegate'
+
+module Trajectory
+  class Projects < SimpleDelegator
+    alias :projects :__getobj__
+
+    # Creates a new collection of {Projects}
+    #
+    # @param projects [Array<Project>] a arbitrary lenght list of {Project} objects
+    def initialize(*projects)
+      super(projects)
+    end
+
+    # Create a new collection of {Project} from a JSON array of attributes from trajectory API
+    #
+    # @param json_attributes [Hash] the hash of attributes of each project of the collection
+    def self.from_json(json_attributes)
+      new(*json_attributes.map do |attributes|
+        Project.new(attributes.symbolize_keys!)
+      end)
+    end
+
+    # Fetch the project with the given id in the collection. If it is not found,
+    # it returns false
+    #
+    # @param id [Integer] the project id
+    # @return [Project, false] the found project or false
+    def find_by_id(id)
+      projects.find { |project| project.id == id } || false
+    end
+
+    # Fetch the project with the given keyword in the collection. If it is not found,
+    # it returns false
+    #
+    # @param keyword [String] the project keyword
+    # @return [Project, false] the found project or false
+    def find_by_keyword(keyword)
+      projects.find { |project| project.keyword == keyword } || false
+    end
+
+    # Returns the archived projects of the collection
+    #
+    # @return [Projects] the filtered collection
+    def archived
+      projects.select { |project| project.archived? }
+    end
+
+    # Returns the active projects of the collection
+    #
+    # @return [Projects] the filtered collection
+    def active
+      projects.select { |project| !project.archived? }
+    end
+  end
+end

data/lib/trajectory/domain/stories.rb

@@ -0,0 +1,56 @@
+require 'delegate'
+
+module Trajectory
+  class Stories < SimpleDelegator
+    alias :stories :__getobj__
+
+    # Creates a new collection of {Story}
+    #
+    # @param stories [Array<Story>] a arbitrary lenght list of {Story} objects
+    def initialize(*stories)
+      super(stories)
+    end
+
+    # Create a new collection of {Story} from a JSON array of attributes from trajectory API
+    #
+    # @param project [Project] the project the stories belongs to
+    # @param json_attributes [Hash] the hash of attributes of each story of the collection
+    def self.from_json(project, json_attributes)
+      new(*json_attributes.map do |attributes|
+        attributes = attributes.symbolize_keys!.merge({project_id: project.id})
+        Story.new(attributes)
+      end)
+    end
+
+    # Returns started stories of the collection
+    #
+    # @return [Stories] started stories collection
+    def started
+      stories.select(&:started?)
+    end
+
+    # Returns unstarted stories of the collection
+    #
+    # @return [Stories] unstarted stories collection
+    def unstarted
+      stories.select(&:unstarted?)
+    end
+
+    # Returns not completed stories of the collection
+    #
+    # @return [Stories] not completed stories collection
+    def not_completed
+      stories.reject(&:completed?)
+    end
+
+    # Returns stories of the collection that are in the given iteration
+    #
+    # @param iteration [Iteration] an iteration
+    # @return [Stories] stories collection in iteration
+    def in_iteration(iteration)
+      stories.select do |story|
+        story.in_iteration?(iteration)
+      end
+    end
+  end
+end

data/lib/trajectory/domain/story.rb

@@ -0,0 +1,119 @@
+module Trajectory
+  class Story
+    include Virtus
+
+    # @return [Integer] the unique identifier of the story
+    # @raise [MissingAttributeError] if id is nil
+    attribute :id, Integer, default: lambda { |project, attribute| raise MissingAttributeError.new(project, :id) }
+    # @return [String] the name of the user assigned to the story
+    attribute :assignee_name, String
+    # @return [String] the type of story as "Feature", "Bug", "Todo" or "Milestone"
+    attribute :task_type, String
+    # The Integer position of the story in the backlog.
+    # Lower is higher.
+    # @return [Integer] the position of the story
+    attribute :position, Integer
+    # @return [DateTime] the creation date of the story
+    attribute :created_at, DateTime
+    # @return [Array<String>] the valid states the story can transition to
+    # @todo Replace String by Symbol
+    attribute :state_events, Array[String]
+    # @return [String] the title of the story
+    attribute :title, String
+    # @return [true, false] true if design is needed for the story, false otherwise
+    attribute :design_needed, Boolean
+    # @return [DateTime] the last modification date of the story
+    attribute :updated_at, DateTime
+    # @return [String] the subject of the idea the story is attached to
+    attribute :idea_subject, String
+    # @!method archived?
+    # @return [true, false] true if the story has been archived, false otherwise
+    attribute :archived, Boolean
+    # @return [Integer] estimation in points of the story complexity
+    attribute :points, Integer
+    # @!method development_needed?
+    # @return [true, false] true if development is needed for the story, false otherwise
+    attribute :development_needed, Boolean
+    # @!method deleted?
+    # @return [ture, false] true if the story has been deleted, false otherwise
+    attribute :deleted, Boolean
+    # @return [String] name of the user that created the story
+    attribute :user_name, String
+    # @return [Integer] id of the user that created the story
+    # @see #user
+    attribute :user_id, Integer
+    # @return [Integer] number of comments of the story
+    attribute :comments_count, Integer
+    # @return [Symbol] state of the story in [:started, :unstarted, :delivered, :accepted, :rejected]
+    attribute :state, Symbol
+    # @return [Integer] project id the story belongs to
+    # @see #project
+    attribute :project_id, Integer
+    # @return [Integer] iteration id the story belongs to
+    # @see #iteration
+    attribute :iteration_id, Integer
+
+    # Returns true if two stories are the sames i.e they share the same id
+    # attribute
+    #
+    # @param other [Story] the other object to compare
+    # @return [true, false]
+    def ==(other)
+      id == other.id
+    end
+
+    # Fetch the project the story belongs to
+    #
+    # @return [Project]
+    def project
+      @project ||= DataStore.find_project_by_id(project_id)
+    end
+
+    # Returns true if the story is started i.e in :started state
+    #
+    # @return [true, false]
+    def started?
+      state == :started
+    end
+
+    # Returns true if the story is not started i.e in :unstarted state
+    #
+    # @return [true, false]
+    def unstarted?
+      state == :unstarted
+    end
+
+    # Returns true if the story is not completed i.e not in :accepted state
+    #
+    # @return [true, false]
+    def not_completed?
+      !completed?
+    end
+
+    # Returns true if the story is completed i.e in :accepted state
+    #
+    # @return [true, false]
+    def completed?
+      state == :accepted
+    end
+
+    # Fetch the user that created the story
+    #
+    # @return [User]
+    def user
+      @user ||= DataStore.find_user_of_project_with_id(project, user_id)
+    end
+
+    # Returns true if the story belongs to the given iteration, false otherwise
+    #
+    # @param iteration [Iteration] an iteration
+    # @return [true, false]
+    def in_iteration?(iteration)
+      iteration_id == iteration.id
+    end
+
+    # @todo Not Yet Implemented
+    def iteration
+    end
+  end
+end

data/lib/trajectory/domain/update.rb

@@ -0,0 +1,17 @@
+module Trajectory
+  class Update
+    # @attr_reader stories [Stories] the updated stories by the update
+    # @attr_reader iterations [iterations] the updated iterations by the update
+    attr_reader :stories, :iterations
+
+    # Creates a new update with given updated stories and iterations
+    #
+    # @param stories [Stories] collection of updated stories
+    # @param iterations [Iterations] collection of updated iterations
+    # :nocov:
+    def initialize(stories, iterations)
+      @stories = stories
+      @iterations = iterations
+    end
+  end
+end

data/lib/trajectory/domain/user.rb

@@ -0,0 +1,28 @@
+module Trajectory
+  class User
+    include Virtus
+
+    # @return [Integer] the unique identifier of the User
+    # @raise [MissingAttributeError] if id is nil
+    attribute :id, Integer, default: lambda { |project, attribute| raise MissingAttributeError.new(project, :id) }
+    # @return [String] the full name of the user
+    attribute :name, String
+    # @return [DateTime] the creation date of the user account
+    attribute :created_at, DateTime
+    # @return [DateTime] the last modification date of the user account
+    attribute :updated_at, DateTime
+    # @return [String] the url to the avatar image of the user (uses gravatar)
+    attribute :gravatar_url, String
+    # @return [String] the email of the user
+    attribute :email, String
+
+    # Returns true if two users are the sames i.e they share the same id
+    # attribute
+    #
+    # @param other [User] the other object to compare
+    # @return [true, false]
+    def ==(other)
+      id == other.id
+    end
+  end
+end

data/lib/trajectory/domain/users.rb

@@ -0,0 +1,30 @@
+module Trajectory
+  class Users < SimpleDelegator
+    alias :users :__getobj__
+
+    # Creates a new collection of {User}
+    #
+    # @param users [Array<User>] a arbitrary lenght list of {User} objects
+    def initialize(*users)
+      super(users)
+    end
+
+    # Create a new collection of {User} from a JSON array of attributes from trajectory API
+    #
+    # @param json_attributes [Hash] the hash of attributes of each user of the collection
+    def self.from_json(json_attributes)
+      new(*json_attributes.map do |attributes|
+        User.new(attributes.symbolize_keys!)
+      end)
+    end
+
+    # Returns the the first user with the given id in the collection or false if
+    # no user can be found with the id
+    #
+    # @param id [Integer] the id of the user to find
+    # @return [User, false] the user with the given id
+    def find_by_id(id)
+      users.find { |user| user.id == id } || false
+    end
+  end
+end

data/lib/trajectory/domain.rb

@@ -0,0 +1,11 @@
+require 'trajectory/domain/story'
+require 'trajectory/domain/stories'
+require 'trajectory/domain/project'
+require 'trajectory/domain/projects'
+require 'trajectory/domain/iteration'
+require 'trajectory/domain/iterations'
+require 'trajectory/domain/idea'
+require 'trajectory/domain/ideas'
+require 'trajectory/domain/user'
+require 'trajectory/domain/users'
+require 'trajectory/domain/update'

data/lib/trajectory/exceptions/bad_environment_error.rb

@@ -0,0 +1,7 @@
+module Trajectory
+  class BadEvnrionmentError < RuntimeError
+    def to_s
+      "Specify trajectory API environment variables : TRAJECTORY_API_KEY and TRAJECTORY_ACCOUNT_KEYWORD"
+    end
+  end
+end

data/lib/trajectory/exceptions/missing_attribute_error.rb

@@ -0,0 +1,12 @@
+module Trajectory
+  class MissingAttributeError < RuntimeError
+    def initialize(object, attribute)
+      @object = object
+      @attribute = attribute.to_sym
+    end
+
+    def to_s
+      "Attribute #{@attribute} of #{@object.inspect} is nil."
+    end
+  end
+end

data/lib/trajectory/exceptions/velocity_equal_to_zero_error.rb

@@ -0,0 +1,11 @@
+module Trajectory
+  class VelocityEqualToZeroError < RuntimeError
+    def initialize(project)
+      @project = project
+    end
+
+    def to_s
+      "Estimated velocity of #{@project.inspect} is equal to 0."
+    end
+  end
+end

data/lib/trajectory/exceptions.rb

@@ -0,0 +1,3 @@
+require 'trajectory/exceptions/missing_attribute_error'
+require 'trajectory/exceptions/velocity_equal_to_zero_error'
+require 'trajectory/exceptions/bad_environment_error'

data/lib/trajectory/version.rb

@@ -0,0 +1,3 @@
+module Trajectory
+  VERSION = "0.1.0"
+end

data/lib/trajectory.rb

@@ -0,0 +1,15 @@
+require 'virtus'
+require 'httparty'
+require 'json'
+
+require "trajectory/version"
+
+require 'trajectory/core_ext'
+require 'trajectory/exceptions'
+require 'trajectory/domain'
+require 'trajectory/data_access'
+
+require 'trajectory/client'
+
+module Trajectory
+end

data/spec/fabricators/iteration_fabricator.rb

@@ -0,0 +1,18 @@
+Fabricator(:iteration, class_name: Trajectory::Iteration) do
+  id { sequence }
+  percent_complete 90.0
+  started_stories_count 4
+  created_at DateTime.now
+  estimated_velocity 12
+  delivered_stories_count 28
+  updated_at DateTime.now
+  unstarted_stories_count 31
+  starts_on DateTime.now
+  current false
+  stories_count 59
+  complete false
+  accepted_points 51
+  estimated_points 72
+  comments_count 8
+  accepted_stories_count 24
+end

data/spec/fabricators/project_fabricator.rb

@@ -0,0 +1,11 @@
+Fabricator(:project, class_name: Trajectory::Project) do
+  archived false
+  created_at DateTime.now
+  estimated_velocity 20
+  historic_velocity [10, 9, 12, 13, 18]
+  id { sequence(:id, 1) }
+  keyword 'keyword'
+  updated_at DateTime.now
+  completed_iterations_count 10
+  completed_stories_count 42
+end

data/spec/fabricators/story_fabricator.rb

@@ -0,0 +1,18 @@
+Fabricator(:story, class_name: Trajectory::Story) do
+  assignee_name 'An asignee'
+  task_type 'Feature'
+  position { sequence }
+  created_at DateTime.now
+  state_events []
+  title 'A story title'
+  design_needed true
+  updated_at DateTime.now
+  idea_subject 'the related idea subject'
+  archived false
+  points 1
+  id { sequence }
+  development_needed true
+  deleted false
+  user_name 'A user'
+  comments_count 24
+end