go_script 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a33d0f56a637c8da9a53652adc002a7a9f1b58a
+  data.tar.gz: c696612e2b13fd0188cdfdd4262aaf46ebd35f58
+SHA512:
+  metadata.gz: 256d24a8a8c2a325dda36883717296185664c91e9d4a619bb56504f54467ddae3906db7e8303881f9fd6d95cd6273e73b1e6d830717221d1df47cf26e09b870e
+  data.tar.gz: 136735601a89dd6c735a0393663f505f46a004f3ab4383ea5409eb58273653ae168b5cafd13b722b0dffd33f6510191fa3102bfdfc0b1e953ce0c522cef9c9a8

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+## Welcome!
+
+We're so glad you're thinking about contributing to an 18F open source project! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions.
+
+We want to ensure a welcoming environment for all of our projects. Our staff follow the [18F Code of Conduct](https://github.com/18F/code-of-conduct/blob/master/code-of-conduct.md) and all contributors should do the same.
+
+We encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md).
+
+If you have any questions or want to read more, check out the [18F Open Source Policy GitHub repository]( https://github.com/18f/open-source-policy), or just [shoot us an email](mailto:18f@gsa.gov).
+
+## Public domain
+
+This project is in the public domain within the United States, and
+copyright and related rights in the work worldwide are waived through
+the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+
+All contributions to this project will be released under the CC0
+dedication. By submitting a pull request, you are agreeing to comply
+with this waiver of copyright interest.

data/LICENSE.md

@@ -0,0 +1,31 @@
+As a work of the United States Government, this project is in the
+public domain within the United States.
+
+Additionally, we waive copyright and related rights in the work
+worldwide through the CC0 1.0 Universal public domain dedication.
+
+## CC0 1.0 Universal Summary
+
+This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+### No Copyright
+
+The person who associated a work with this deed has dedicated the work to
+the public domain by waiving all of his or her rights to the work worldwide
+under copyright law, including all related and neighboring rights, to the
+extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+
+### Other Information
+
+In no way are the patent or trademark rights of any person affected by CC0,
+nor are the rights that other persons may have in the work or in how the
+work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with
+this deed makes no warranties about the work, and disclaims liability for
+all uses of the work, to the fullest extent permitted by applicable law.
+When using or citing the work, you should not imply endorsement by the
+author or the affirmer.

data/README.md

@@ -0,0 +1,149 @@
+## The `./go` script: a unified development environment interface.
+
+A `./go` script aims to abstract away all of the steps needed to develop (and
+sometimes deploy) a software project. It is a replacement for READMEs and
+other documents that may become out-of-date, and when maintained properly,
+should provide a cohesive and discoverable interface for common project tasks.
+
+This gem abstracts common functionality used in the Ruby-based `./go` scripts
+of several 18F projects, and provides a `./go` script generator for new
+projects.
+
+This gem was inspired by the blog articles [In Praise of the ./go Script -
+Part I](http://www.thoughtworks.com/insights/blog/praise-go-script-part-i) and
+[In Praise of the ./go Script - Part
+II](http://www.thoughtworks.com/insights/blog/praise-go-script-part-ii) by
+Pete Hodgson.
+
+**Note:** Not to be confused with the [Go programming
+language](https://golang.org). This convention is completely unrelated,
+though it does bear a great deal of resemblance to the Go language's `go`
+command.
+
+### Installation
+
+Install [the Ruby programming language](https://www.ruby-lang.org/) if it
+isn't already present on your system. We recommend using a Ruby version
+manager such as [rbenv](https://github.com/sstephenson/rbenv) or
+[rvm](https://rvm.io/) to do this.
+
+Install [Bundler](http://bundler.io/) via `gem install bundler`.
+
+Finally, install the `go_script` gem via `gem install go_script`. You may also
+wish to add it to the [`Gemfile`](http://bundler.io/gemfile.html) of your
+project to ensure version consistency.
+
+### Creating a `./go` script
+
+To create a fresh new `./go` script for your project, run:
+
+```shell
+$ cd path/to/the/project/repository
+
+$ go-script-template > ./go
+
+# Alternately, if you installed go_script using Bundler:
+$ bundle exec go-script-template > ./go
+
+# Make the script executable:
+$ chmod 700 ./go
+```
+
+### Listing commands
+
+To see the list of available commands for a script: run `./go help` (or one of
+the common variations thereon, such as `./go -h` or `./go --help`). For
+example, the output of `./go help` for this repository's `./go` script is:
+
+```
+Usage: ./go [option|command] [optional command arguments...]
+
+options:
+  -h,--help     Show this help
+  -v,--version  Show the version of the go_script gem
+
+Development commands
+  init         Set up the development environment
+  update_gems  Update Ruby gems
+  update_js    Update JavaScript components
+  test         Execute automated tests
+  lint         Run style-checking tools
+  ci_build     Execute continuous integration build
+  release      Test, build, and release a new gem
+```
+
+### Defining commands
+
+The `def_command` directive defines the individual `./go` commands that
+comprise the `./go` script interface. Its arguments are:
+
+- *id*: A [Ruby symbol](http://ruby-doc.org/core-2.2.3/Symbol.html)
+  (basically, a string starting with `:` with no quotes around it) defining
+  the name of the command.
+- *command_group*: A `CommandGroup` instance associated with the command.
+- *description*: A very brief description of the command that appears in the
+  usage text.
+
+These `def_command` definitions often use the `exec_cmd` directive
+that runs a shell command and exits on error. There are also additional
+directives from [`lib/go_script/go.rb`](lib/go_script/go.rb) that may be used
+to define commands, and commands may be built up from other commands defined
+in the `./go` script itself.
+
+#### Command groups
+
+A `CommandGroup` instance clusters a set of commands together.
+`go-script-template` generates a default `CommandGroup` instance called
+`dev_commands`; you are free to edit this definition, or to add additional
+`CommandGroup` instances to organize your individual command definitions and
+affect how they are displayed in the help/usage message.
+
+#### Command arguments
+
+Commands may take command-line arguments, which are passed in as block
+variables. In the following example, the `./go init` command takes no
+arguments, and the `./go test` command takes an argument list that is appended
+as additional command line arguments to `rake test`. For example, `./go test`
+runs `bundle exec rate test` without any further arguments, while running
+`./go test TEST=_test/go_test.rb` ultimately runs `bundle exec rake test
+TEST=_test/go_test.rb`.
+
+```ruby
+dev_commands = GoScript::CommandGroup.add_group 'Development commands'
+
+def_command :init, dev_commands, 'Set up the development environment' do
+  install_bundle
+end
+
+def_command :test, dev_commands, 'Execute automated tests' do |args|
+  exec_cmd "bundle exec rake test #{args.join ' '}"
+end
+```
+
+Command blocks may take more than one parameter, corresponding to a specific
+number of additional command line arguments for a specific command.
+
+### Contributing
+
+1. Fork the repo (or just clone it if you're an 18F team member)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Feel free to ping [@mbland](https://github.com/mbland) with any questions you
+may have, especially if the current documentation should've addressed your
+needs, but didn't.
+
+### Public domain
+
+This project is in the worldwide [public domain](LICENSE.md). As stated in
+[CONTRIBUTING](CONTRIBUTING.md):
+
+> This project is in the public domain within the United States, and copyright
+> and related rights in the work worldwide are waived through the
+> [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+>
+> All contributions to this project will be released under the CC0 dedication.
+> By submitting a pull request, you are agreeing to comply with this waiver of
+> copyright interest.

data/bin/go-script-template

@@ -0,0 +1,48 @@
+#! /usr/bin/env ruby
+# Author: Mike Bland <michael.bland@gsa.gov>
+
+require_relative '../lib/go_script'
+
+puts <<END_OF_TEMPLATE
+#! /usr/bin/env ruby
+
+require 'English'
+
+begin
+  require 'go_script'
+rescue LoadError
+  puts 'Installing go_script gem...'
+  exit $CHILD_STATUS.exitstatus unless system 'gem install go_script'
+end
+
+GoScript::Version.check_ruby_version '#{RUBY_VERSION}'
+
+extend GoScript
+
+BASEDIR = File.dirname(__FILE__)
+dev_commands = GoScript::CommandGroup.add_group 'Development commands'
+
+def_command :init, dev_commands, 'Set up the development environment' do
+  install_bundle
+end
+
+def_command :update_gems, dev_commands, 'Update Ruby gems' do |gems|
+  update_gems gems
+end
+
+def_command :update_js, dev_commands, 'Update JavaScript components' do
+  update_node_modules
+end
+
+def_command :test, dev_commands, 'Execute automated tests' do |args|
+  exec_cmd "bundle exec rake test \#{args.join ' '}"
+end
+
+def_command :lint, dev_commands, 'Run style-checking tools' do |files|
+  files = files.group_by { |f| File.extname f }
+  lint_ruby files['.rb']
+  lint_javascript BASEDIR, files['.js']
+end
+
+execute_command ARGV
+END_OF_TEMPLATE

data/lib/go_script.rb

@@ -0,0 +1,5 @@
+# @author Mike Bland (michael.bland@gsa.gov)
+
+require_relative './go_script/go'
+require_relative './go_script/command_group'
+require_relative './go_script/version'

data/lib/go_script/command_group.rb

@@ -0,0 +1,51 @@
+# Author: Mike Bland <michael.bland@gsa.gov>
+
+module GoScript
+  # Groups a set of commands by common function.
+  class CommandGroup
+    attr_accessor :description, :commands
+    private_class_method :new
+
+    # @param description [String] short description of the group
+    def initialize(description)
+      @description = description
+      @commands = {}
+    end
+
+    def to_s
+      padding = (commands.keys.max_by(&:size) || '').size + 2
+      command_descriptions = commands.map do |name, desc|
+        format "  %-#{padding}s#{desc}", name
+      end
+      ["\n#{@description}"].concat(command_descriptions).join("\n")
+    end
+
+    class <<self
+      attr_reader :groups
+      def add_group(description)
+        (@groups ||= []).push(new(description)).last
+      end
+
+      def command(command_sym)
+        if (groups || []).flat_map { |g| g.commands.keys }.include? command_sym
+          return command_sym
+        end
+        puts "Unknown option or command: #{command_sym}"
+        usage exitstatus: 1
+      end
+
+      def usage(exitstatus: 0)
+        output_stream = exitstatus == 0 ? $stdout : $stderr
+        output_stream.puts <<END_OF_USAGE
+Usage: #{$PROGRAM_NAME} [option|command] [optional command arguments...]
+
+options:
+  -h,--help     Show this help
+  -v,--version  Show the version of the go_script gem
+END_OF_USAGE
+        (groups || []).each { |group| output_stream.puts group }
+        exit exitstatus
+      end
+    end
+  end
+end

data/lib/go_script/go.rb

@@ -0,0 +1,81 @@
+# Author: Mike Bland <michael.bland@gsa.gov>
+
+require_relative './command_group'
+require_relative './version'
+require 'English'
+
+module GoScript
+  def def_command(id, command_group, description, &command_block)
+    abort "Command ID must be a symbol: #{id}" unless id.instance_of? Symbol
+    self.class.send :define_method, id, ->(argv) { command_block.call argv }
+    command_group.commands[id] = description
+  end
+
+  def execute_command(argv)
+    command = argv.shift
+    CommandGroup.usage exitstatus: 1 if command.nil?
+    CommandGroup.usage if ['-h', '--help', '-help', 'help'].include? command
+    send version if ['-v', '--version', 'version'].include? command
+    send CommandGroup.command(command.to_sym), argv
+  end
+
+  def version
+    puts "go_script version #{VERSION}"
+    exit 0
+  end
+
+  def exec_cmd(cmd)
+    exit $CHILD_STATUS.exitstatus unless system cmd
+  end
+
+  def install_bundle
+    begin
+      require 'bundler'
+    rescue LoadError
+      puts 'Installing Bundler gem...'
+      exec_cmd 'gem install bundler'
+      puts 'Bundler installed; installing gems'
+    end
+    exec_cmd 'bundle install'
+  end
+
+  def update_gems(gems)
+    exec_cmd "bundle update #{gems}"
+    exec_cmd 'git add Gemfile.lock'
+  end
+
+  def update_node_modules
+    abort 'Install npm to update JavaScript components: ' \
+      'http://nodejs.org/download/' unless system 'which npm > /dev/null'
+
+    exec_cmd 'npm update'
+    exec_cmd 'npm install'
+  end
+
+  JEKYLL_BUILD_CMD = 'bundle exec jekyll build --trace'
+  JEKYLL_SERVE_CMD = 'bundle exec jekyll serve -w --trace'
+
+  def serve_jekyll(extra_args)
+    exec "#{JEKYLL_SERVE_CMD} #{extra_args}"
+  end
+
+  def build_jekyll(extra_args)
+    exec_cmd "#{JEKYLL_BUILD_CMD} #{extra_args}"
+  end
+
+  def git_sync_and_deploy(commands)
+    exec_cmd 'git stash'
+    exec_cmd 'git pull'
+    commands.each { |command| exec_cmd command }
+  end
+
+  def lint_ruby(files)
+    files ||= []
+    exec_cmd "bundle exec rubocop #{files.join ' '}"
+  end
+
+  def lint_javascript(basedir, files)
+    files ||= []
+    exec_cmd "#{basedir}/node_modules/jshint/bin/jshint #{files.join ' '}"
+  end
+end

data/lib/go_script/version.rb

@@ -0,0 +1,22 @@
+# @author Mike Bland (michael.bland@gsa.gov)
+
+module GoScript
+  VERSION = '0.0.0'
+
+  class Version
+    def self.check_ruby_version(min_version)
+      unless RUBY_VERSION >= min_version
+        abort <<END_OF_ABORT_MESSAGE
+
+*** ABORTING: Unsupported Ruby version ***
+
+Ruby version #{min_version} or greater is required, but this Ruby is version
+#{RUBY_VERSION}. Consider using a version manager such as rbenv
+(https://github.com/sstephenson/rbenv) or rvm (https://rvm.io/) to install a
+Ruby version specifically for development.
+
+END_OF_ABORT_MESSAGE
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: go_script
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Mike Bland
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: safe_yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Abstracts common functionality used in the `./go` scripts of several
+  18F projects, and provides a `./go` script generator for new projects.
+email:
+- michael.bland@gsa.gov
+executables:
+- go-script-template
+extensions: []
+extra_rdoc_files: []
+files:
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- bin/go-script-template
+- lib/go_script.rb
+- lib/go_script/command_group.rb
+- lib/go_script/go.rb
+- lib/go_script/version.rb
+homepage: https://github.com/18F/go_script
+licenses:
+- CC0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: "./go script: a unified development environment interface"
+test_files: []