checklister 0.1.1 → 0.9.0

data/.travis.yml

@@ -1,6 +1,8 @@
 language: ruby
 cache: bundler
 rvm:
+  - 2.0.0
   - 2.1.4
+  - 2.2.2
 before_install: gem install bundler -v 1.10.5
 script: 'bundle exec rake'

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -3,12 +3,10 @@ All notable changes to this project will be documented in this file.
 
 NOTE: the project follows [Semantic Versioning](http://semver.org/).
 
-## 1.0.0 - YYYY-MM-DD
-
-### Dependencies
-
-- [Gli](https://github.com/davetron5000/gli)
+## 0.0.9 - 2015-09-22
 
 ### Added
 
-- #4 - Add a CHANGELOG
+- [feature] Create a new Issue based on a specific markdown file (local path)
+- [feature] Connect to gitlab account
+- [feature] Save your gitlab services settings to local file

data/README.md

@@ -5,10 +5,12 @@
 [![Build Status](https://travis-ci.org/benichu/checklister.svg)](https://travis-ci.org/benichu/checklister)
 [![Dependency Status](https://gemnasium.com/benichu/checklister.svg)](https://gemnasium.com/benichu/checklister)
 [![Gem Version](https://badge.fury.io/rb/checklister.svg)](http://badge.fury.io/rb/checklister)
+[![Code Climate](https://codeclimate.com/github/benichu/checklister/badges/gpa.svg)](https://codeclimate.com/github/benichu/checklister)
+[![Coverage Status](https://coveralls.io/repos/benichu/checklister/badge.svg?branch=master&service=github)](https://coveralls.io/github/benichu/checklister?branch=master)
 
 ## Description
 
-Checklister is a CLI packaged as a Ruby gem giving you the power to transform any markdown file or url checklist into an actionable gitlab (and soon github) issue.
+Checklister is a CLI packaged as a Ruby gem giving you the power to transform any markdown file or url checklist into an actionable gitlab or github issue.
 
 ### Why using checklists
 
@@ -33,33 +35,50 @@ Source: http://atulgawande.com/book/the-checklist-manifesto/
 
 ### Install/Update gem
 
-    TO RELEASE
+```bash
+$ gem install checklister
+```
 
 ### Setup Gitlab Authentication
 
 ```bash
-$ checklister setup gitlab
+$ checklister setup
 ```
 
-### Setup Github Authentication
+Answer the questions and the information will be saved for later use in a configuration json file.
+
+### Check your saved configuration
 
 ```bash
-$ checklister setup github
+$ checklister settings
 ```
 
 ### CLI
 
 ```bash
-$ checklister --file https://raw.githubusercontent.com/benichu/checklister/master/examples/simple-checklist.md \
-              --new_issue_url https://github.com/benichu/checklister/issues
+$ checklister new --checklist /path/to/simple-checklist.md
+```
+
+or for a remote path (NOT IMPLEMENTED YET)
+
+```bash
+$ checklister new --checklist https://raw.githubusercontent.com/benichu/checklister/master/examples/simple-checklist.md
 ```
 
+In this example, the initial markdown file at `https://raw.githubusercontent.com/benichu/checklister/master/examples/simple-checklist.md` is the following :
+
+![Simple Checklist](http://i.imgur.com/KUXThqu.png)
+
+Once the file is parsed, a Github issue will be created with its content. In this case, the issue would be :
+
+![Github Issue](http://i.imgur.com/1IwGKaS.png)
+
 ## Development Setup
 
 ### Dependencies
 
 * rbenv or rvm
-* Ruby 1.9+
+* Ruby 2.0+
 * RubyGems 1.9+ (`gem update --system `)
 * Bundler 1.10+
 
@@ -74,18 +93,55 @@ To install or update your development environment, run `script/bootstrap`.
 3. Run `script/test` to ensure your development setup is sane.
 5. Read `CONTRIBUTING.md` for contribution guidelines.
 6. Run `bundle exec guard`
-7. You can run a REPL: `bin/console`
+7. You can run a REPL: `script/console`
 
-## Testing
+### Testing
 
 You can write tests using `rspec v3+` syntax in the `spec` folder. To run the tests, run `script/test`.
 
-## Release
+### Documentation
+
+[Documenting your code from rubygems.org](http://guides.rubygems.org/make-your-own-gem/#documenting-your-code)
+
+This project is documented with the [YARD syntax](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md),
+every time the gem is published a documentation will automatically be generated at [rubydoc.info](http://www.rubydoc.info/gems/checklister).
 
-    Make sure you are all setup first: http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg
+You should always check how your documentation looks like from time to time.
+Here is a convenient way for you to run a yard server:
+
+```bash
+$ script/doc
+```
+
+You can now open your browser at [http://localhost:8808/](http://localhost:8808/)
+
+### Release
+
+    Make sure you are all set up first: http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg
 
 To prepare a release, run `script/release`. This will package a new version of the `checklister` gem and release it to [https://rubygems.org/gems/checklister](https://rubygems.org/gems/checklister).
 
+## Roadmap
+
+### Version 0.9
+
+- [x] [feature] Create a new Issue based on a specific markdown file (local path)
+- [x] [feature] Connect to gitlab account
+
+### Version 1.0
+
+- [ ] [improvements] CLI improvements based on first test run with real users
+- [ ] [documentation] Yard documentation updated
+- [ ] [feature] Create a new Issue based on a specific markdown file (remote path)
+- [ ] [feature] Connect to github account
+
+### Wishlist
+
+- [ ] [dev] Better step by step DSL for CLI interactions with user
+- [ ] [feature] Select a milestone from a list populated based on github/gitlab API
+- [ ] [feature] Select a checklist from an history list
+- [ ] [feature] Connect to a bitbucket account
+
 ## Authors
 
 Checklister is written and maintained by [Benjamin Thouret](https://github.com/benichu) and [Manon Deloupy](https://github.com/mdeloupy).

data/bin/checklister

@@ -0,0 +1,151 @@
+#!/usr/bin/env ruby
+require "gli"
+require "checklister"
+
+include GLI::App
+
+ISSUE_SERVICES = { "1" => "gitlab", "2" => "github" }.freeze
+
+program_desc "gives you the power to transform any markdown file or url checklist into an actionable gitlab and github issue."
+
+version Checklister::VERSION
+subcommand_option_handling :normal
+arguments :strict
+sort_help :manually
+
+# Flags
+flag [:c,:config], default_value: File.join(ENV["HOME"],".checklister.yml"),
+                   desc: "Set the saved configuration path"
+
+flag [:s,:service], must_match: ISSUE_SERVICES.values
+flag [:e,:endpoint], desc: "Set the issue service API endpoint"
+flag [:p,:private_token], desc: "Set your private token to access the issue API service"
+
+pre do |global_options,command,options,args|
+  unless command.name.to_s == "setup"
+    config_file = Checklister::ConfigurationFile.new(global_options["config"])
+    if global_options[:endpoint]
+      config_options = global_options
+    elsif config_file.exist?
+      saved_services = config_file.services
+      if saved_services.size > 1
+        puts "* Which Issue Service would you like to use?"
+        saved_services.each_with_index do |service, index|
+          line = []
+          line << "[#{index+1}] #{service[:endpoint]}"
+          line << "(#{service[:label]})" if service[:label]
+          puts line.join(" ")
+        end
+        choice = STDIN.gets.to_i
+        raise("You need to select a service.") if choice < 1
+      else
+        choice = 1
+      end
+      service_selected = saved_services[choice-1]
+      config_options = service_selected
+    else
+      config_options = {}
+    end
+    Checklister.configure(config_options)
+  else
+    true
+  end
+end
+
+desc "Show current configuration settings"
+command :settings do |c|
+  c.action do |global_options,options,args|
+    puts "---------------------"
+    Checklister.config.to_stdout
+    puts "---------------------"
+  end
+end
+
+desc "Save your gitlab or github settings for later"
+command :setup do |c|
+  c.action do |global_options,options,args|
+    data = {}
+    config_file = Checklister::ConfigurationFile.new(global_options["config"])
+
+    if global_options[:service]
+      service_selected = global_options[:service]
+    else
+      puts "* Which Issue Service would you like to setup?"
+      ISSUE_SERVICES.each do |index, service|
+        puts "[#{index}] #{service}"
+      end
+      choice = STDIN.gets.to_i
+      raise("You need to select a service.") if choice < 1
+      service_selected = ISSUE_SERVICES[choice.to_s]
+    end
+    data["kind"] = service_selected
+
+    puts ""
+    puts "* We are going to help you set up the #{service_selected} service"
+
+    if service_selected == "gitlab"
+      puts ""
+      puts "** What is your gitlab endpoint? (Ex: https://gitlab.com/api/v3)"
+      choice = STDIN.gets.chomp
+      raise("You need to type a endpoint.") if choice == ""
+      data["endpoint"] = choice
+    elsif service_selected == "github"
+      data["endpoint"] = "https://api.github.com"
+    end
+
+    puts ""
+    puts "** What is your private token with the #{service_selected} service?"
+    choice = STDIN.gets.chomp
+    raise("You need to type a private token.") if choice == ""
+    data["private_token"] = choice
+
+    puts ""
+    puts "** You can give a label to #{data["endpoint"]} (you can leave it blank too)"
+    choice = STDIN.gets.chomp
+    if choice != ""
+      data["label"] = choice
+    end
+
+    config_file.add_service data
+    config_file.persist
+    puts ""
+    puts "* Your configuration data has been saved at #{global_options[:config]}"
+  end
+end
+
+desc "Transform a markdown file or url checklist into an actionable issue"
+command :new do |c|
+  c.flag [:c,:checklist], desc: "Set the markdown checklist file path", required: true
+  c.action do |global_options,options,args|
+    client = Checklister::Client.new(Checklister.config.to_hash).get_api_client
+    gitlab_project = Checklister::Gitlab::Project.new(client)
+    checklist_path = options[:checklist]
+
+    puts "* Type some letters of your project's name..."
+    project_like = STDIN.gets.chomp
+    projects = gitlab_project.filtered_by_name(project_like)
+    default_project_id = projects.first[:id]
+    projects.each do |project|
+      puts "%-5s %-100s" % ["[#{project[:id]}]", project[:name]]
+    end
+    puts "* Pick your project Id, defaults to [#{default_project_id}]"
+    choice = STDIN.gets.chomp
+    project_id = choice == "" ? default_project_id : choice
+    project = gitlab_project.get(project_id)
+    puts "* Creating a checklist issue from #{checklist_path}"
+    puts "  to the project: #{project[:name]}"
+    parsed_checklist = Checklister::Parser.new(checklist_path)
+    issue = Checklister::Gitlab::Issue.new(client).create(project_id, parsed_checklist.to_params)
+    puts "------------->"
+    puts "| Check it out: #{Checklister.config.endpoint.gsub("/api/v3", "")}/#{project[:path_with_namespace]}/issues/#{issue.id}"
+    puts "------------->"
+  end
+end
+
+on_error do |exception|
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+exit run(ARGV)

data/checklister.gemspec

@@ -15,18 +15,23 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/benichu/checklister"
   spec.license       = "MIT"
 
-  spec.required_ruby_version = '>= 2.0'
+  spec.required_ruby_version     = '>= 2.0'
+  spec.required_rubygems_version = '>= 1.9'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = "bin"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "gli", "~> 2.13"
+  spec.add_dependency "gitlab"    , "~> 3.4.0"
+  spec.add_dependency "gli"       , "~> 2.13"
 
   spec.add_development_dependency "bundler"     , "~> 1.10"
+  spec.add_development_dependency "coveralls"   , "~> 0.8.2"
   spec.add_development_dependency "guard"       , "~> 2.13"
   spec.add_development_dependency "guard-rspec" , "~> 4.6"
   spec.add_development_dependency "rake"        , "~> 10.4"
   spec.add_development_dependency "rspec"       , "~> 3.3"
+  spec.add_development_dependency "yard"        , "~> 0.8"
+  spec.add_development_dependency "webmock"     , "~> 1.21"
 end

data/config/checklister.example.yml

@@ -0,0 +1,9 @@
+services:
+  - endpoint: "https://www.gitlab.com/api"
+    private_token: "supersecret"
+    label: "Gitlab"
+    kind: "gitlab"
+  - endpoint: "https://api.github.com"
+    private_token: "supersecret"
+    label: "Github"
+    kind: "github"

data/examples/basic-checklist.md

@@ -0,0 +1,5 @@
+## Checklist
+
+- [ ] Step 1
+- [ ] Step 2
+- [ ] Step 3

data/examples/simple-checklist.md

@@ -9,3 +9,7 @@ When you need to accomplish stuff, follow those steps.
 - [ ] Step 1
 - [ ] Step 2
 - [ ] Step 3
+
+## Checklist
+
+- [ ] Step 4

data/lib/checklister.rb

@@ -1,5 +1,31 @@
+require "checklister/configuration"
+require "checklister/configuration_file"
+require "checklister/issue"
+require "checklister/parser"
+require "checklister/sanitizer"
 require "checklister/version"
 
+# API Clients
+require "checklister/client"
+require "checklister/gitlab/project"
+require "checklister/gitlab/issue"
+
 module Checklister
-  # Your code goes here...
+  class << self
+    # Keep track of the configuration values set after a configuration
+    # has been applied
+    #
+    # @example Return a configuration value
+    #   Checklister.config.foo #=> "bar"
+    #
+    # @return [Object] the configuration object
+    #
+    def config
+      @config ||= Checklister::Configuration.new
+    end
+
+    def configure(attributes = {})
+      config.apply attributes
+    end
+  end
 end

data/lib/checklister/client.rb

@@ -0,0 +1,23 @@
+require "gitlab"
+
+module Checklister
+  class Client
+    IMPLEMENTED_BACKENDS = %w(gitlab)
+
+    def initialize(options = {})
+      @kind = options.fetch(:kind) { raise ArgumentError, "No API client can be initialized" }
+      raise(ArgumentError, "No #{@kind} API client has been implemented") unless IMPLEMENTED_BACKENDS.include?(@kind)
+      @options = options.reject { |k| [:kind].include? k }
+      default_options = { user_agent: "Checklister for #{@kind} #{Checklister::VERSION}" }
+      default_options.merge!(httparty: { verify: false }) # FIXME
+      @options.merge! default_options
+    end
+
+    def get_api_client
+      case @kind
+      when "gitlab"
+        ::Gitlab.client(@options)
+      end
+    end
+  end
+end

data/lib/checklister/configuration.rb

@@ -0,0 +1,155 @@
+require "uri"
+
+module Checklister
+  # This class maintains all system-wide configuration for *checklister*. It properly
+  # applies the correct source of configuration values based on the different contexts and
+  # also makes sure that compulsory data are not missing.
+  #
+  # Some values are dependent on a context, for example: `host` can have different values
+  # based on what service the user wants to connect to.
+  # Other values are shared by all those contexts, for example `log_file` is defined once and
+  # for all and the service selected by our user does not matter.
+  #
+  # *checklister* can work with several publishing destinations, for example:
+  #
+  # - [gitlab.com](https://gitlab.com/) (Official Hosted Service)
+  # - privately hosted _gitlab_ server
+  # - [github.com](https://github.com/)
+  #
+  # ## Setting/Selecting the configuration values
+  #
+  # When using the *checklister* binary, you can set one of the many publishing destinations
+  # you have access to, via two possible ways:
+  #
+  # ### 1. CLI Configuration Values
+  #
+  # No configuration file required, you can pass your service credentials directly inline as options.
+  #
+  # For example, you might do:
+  #
+  # ```bash
+  # $ checklister --endpoint=https://api.github.com --private_token==supersecret create ...
+  # ```
+  # NOTE: Every time you pass credentials via command line options, they will override any configuration
+  # file you have previously set .
+  #
+  # ### 2. Configuration File
+  #
+  # You can use the command line to add publishing destinations credentials and answer the questions:
+  #
+  # ```bash
+  # $ checklister setup
+  # ```
+  #
+  # By default, that configuration file will be saved at `/path/to/home/.checklister.json`.
+  # But you can easily use another one by using that option before any *checklister* commands:
+  #
+  # ```bash
+  # $ checklister --config=/another/path/to/my_checklister.json setup
+  # ```
+  # As soon as you have set up one or many publishing destinations, every time you will be using
+  # a *checklister* command you will be prompted to select which service to use, for example:
+  #
+  # ```bash
+  # $ checklister create ...
+  #
+  #   Select which service to use:
+  #   [1] https://github.com/benichu
+  #   [2] https://github.com/mdeloupy
+  #   [3] https://gitlab.intello.com
+  # ```
+  #
+  # ## DEVELOPMENT: Using the configuration values
+  #
+  # Any time you need to access the credentials, you just need to confidently query the value without
+  # worrying about the context selected by the user.
+  #
+  # For example:
+  #
+  # - The user selected the `https://github.com/benichu` service, querying `Checklister.config.username` will return the appropriate value `github_user`
+  # - But, if the user selects next the `https://gitlab.intello.com` service, querying `Checklister.config.username` will return the appropriate value `gitlab_user`
+  #
+  class Configuration
+    # List of all the configuration attributes stored for use within the gem
+    ATTRIBUTES = [:endpoint, :private_token, :label, :kind]
+
+    # List of accessor attributes
+    attr_accessor :endpoint, :private_token, :kind
+    # List of writer attributes (with a reader defined in the class definition)
+    attr_writer :label
+
+    # Apply a configuration hash to a configuration instance
+    #
+    # @example Override one of the configuration attributes
+    #   config = Checklister::Configuration.new
+    #   config.apply(private_token: 'supersecret')
+    #   config.private_token #=> "supersecret"
+    #
+    # @param attributes [Hash] list of key/values to apply to the configuration
+    # @return [Object] the configuration object
+    #
+    def apply(attributes = {})
+      prepared_attributes = prepare_attributes attributes
+      prepared_attributes.each_pair do |attribute, value|
+        send("#{attribute}=", value)
+      end
+      self
+    end
+
+    # The label value, if not specifically set, we infer it from the given
+    # endpoint url (we use the host)
+    #
+    # @return [String] the label string
+    #
+    def label
+      if instance_variable_get "@label"
+        @label
+      elsif instance_variable_get "@endpoint"
+        URI.parse(@endpoint).host
+      end
+    end
+
+    # The configuration instance formatted as a stringified hash
+    #
+    # @example Override one of the configuration attributes
+    #   config = Checklister::Configuration.new
+    #   config.to_hash #=> { "endpoint" => "https://gitlab.example.com/api/v3", ..., "private_token" => "supersecret" }
+    #
+    # @return [Hash] the configuration object as a Hash
+    #
+    def to_hash
+      config_hash = ATTRIBUTES.inject({}) do |hash, attr|
+        hash["#{attr}"] = instance_variable_get("@#{attr}")
+        hash
+      end
+      Checklister::Sanitizer.symbolize config_hash
+    end
+
+    # Write a configuration summary to STDOUT, useful for output in the CLI
+    #
+    def to_stdout
+      to_hash.each_pair do |attribute, value|
+        puts "%-20s %-50s" % ["#{attribute}:", value]
+      end
+      nil
+    end
+
+    private
+
+    # Symbolize keys and remove nil or duplicate attributes
+    # The attributes usually passed to our configuration class by the CLI
+    # are usually full of duplicates and unconsistant keys, we make sure
+    # to clean up that input, before doing any configuration work.
+    #
+    # @param attributes [Hash] list of key/values
+    # @return [Hash] a clean list of key/values
+    #
+    def prepare_attributes(attributes)
+      # Convert string keys to symbols
+      symboled_attributes = Checklister::Sanitizer.symbolize attributes
+      # Clean up user_attributes from unwanted, nil and duplicate options
+      symboled_attributes.select { |key, _| ATTRIBUTES.include? key }
+                         .delete_if { |_, v| v.nil? }
+    end
+  end
+end