omnitest-psychic 0.0.9

data/docs/code_samples.md

@@ -0,0 +1,92 @@
+# Running Code Samples
+
+Psychic can be used to run code samples as well as tasks. It's designed so that if two (or more) projects have a similar set of samples than the same psychic commands should find and run the samples, even if the commands required to run them are drastically different. Psychic does this by:
+- Searching for sample code by name rather than path
+- Finding a task runner that is capable of running hte sample
+- Adjusting how to pass input to the code sample, if necessary
+
+## Showing Samples
+
+You can check that psychic is finding the correct code sample before you attempt to run it. If you run:
+
+```
+$ psychic show sample "upload file"
+```
+
+This will show the information about the sample:
+
+```
+Sample Name:                          upload file
+Tokens:
+- authUrl
+- username
+- apiKey
+- region
+- containerName
+- localFilePath
+- remoteObjectName
+Source File:                          ObjectStore/upload-object.php
+```
+
+If you pass the `--verbose` flag then Psychic will also display the code for the code sample, with syntax highlighting (if your terminal suports color).
+
+The Tokens section shows what the tokens Psychic has detected that can be used for passing input to the code sample. See the documentation on [Tokens](tokens) for more details.
+
+### Automatic detection
+
+The default behavior is for psychic to search for with file with a name that is similar to the name of the sample. It will basically do a case-insensitive search for a file with a name that contains "upload file", ignoring whitespace. It will then display info about the sample it found:
+
+```
+$ bundle exec psychic show sample "upload file"
+Sample Name:                          upload file
+Tokens:                               (None)
+Source File:                          storage/upload_file.rb
+```
+
+### Custom Map
+
+You can tell Psychic exactly where to find a sample if it cannot be auto-detected. This is useful [omnitest](https://github.com/omnitest/omnitest) or any other situation where you want the same sample name to work across multiple projects even though the file names of the sample code have very different names.
+
+You can do this by mapping sample names to files in your `psychic.yaml`. So you could add this:
+
+```yaml
+samples:
+  upload file: ObjectStore/upload-object.php
+```
+
+Now `psychic show sample "upload file"` will find the correct sample, even though it has "object" rather than "file" in the name.
+
+### Listing Samples
+
+There is also a command for listing all known samples. See the [skeptic](https://github.com/omnitest/psychic-skeptic) project if you want to make ensure a project has a required set of samples.
+
+```
+$ bundle exec psychic list samples
+upload file              ObjectStore/upload-object.php
+change metadata          ObjectStore/update-object-metadata.php
+get file                 ObjectStore/get-object.php
+create networked server  Compute/create_server_with_network.php
+create keypair           Compute/create_new_keypair.php
+create load balancer     LoadBalancer/create-lb.php
+secure load balancer     LoadBalancer/blacklist-ip-range.php
+setup ssl                LoadBalancer/ssl-termination.php
+delete load balancer     LoadBalancer/delete-lb.php
+```
+
+### Running a sample
+
+Once you've checked that Psychic is detecting the correct sample, you can easily tell Psychic to run it with hte `psychic sample` command.
+
+If you want to see how psychic would run the sample first, you can use the `--print` flag:
+
+```
+psychic sample "upload object" --print
+```
+
+### Dealing with Input
+
+Psychic is able to run some code samples that require input. See the [Input documentation](input) for more details.
+
+### Testing code samples
+
+You can use Psychic's companion project, [Skeptic](https://github.com/omnitest/psychic-skeptic) to test code samples.

data/docs/index.md

@@ -0,0 +1,128 @@
+# Psychic::Runner
+
+Psychic runs anything.
+
+## What is Psychic
+
+Psychic is a project to help developers that work on many different projects. It
+provides a unified interface for running tasks so you don't need to remember a
+bunch of project specific commands.
+
+Psychic provides command aliases so that a command like `psychic bootstrap`
+will invoke a similiar task in any project, but the actual command invoked will vary.
+It might end up calling `bundle install`, `npm install` `./scripts/boostrap.sh` or some
+other command.
+
+Psychic provides a common set of alises for common tasks but also allows you to define
+custom tasks across different projects, so you could have cross-project commands like
+`metrics` or `documentation`.
+
+## Why?
+
+Psychic exists to provide a common interface for tasks to build, test, and analyze projects while still allowing (or even encouraging) projects to use idiomatic patterns for their particular language. This makes it easy for new contributors to join a project because it follows the "principal of least astonishment", while also providing a consistent interface for tools to build, test or analyze any project.
+
+The [bootstrap consistency pattern](http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency) is an example of that. It aims to provide "a consistent user experience to get from zero to productive on any new project". Similarly, Travis-CI gives you a consistent interface to test any software project. The command `travis run` will always build and test a project.
+
+Omnitest is an attempt to make a more generic framework for creating consistent user experiences across projects. That experienec can be "getting from zero to productive" like the bootstrap consistency pattern, "testing a change" like Travis-CI, or even something like "generating end of sprint reports" or "generating and previewing documentation".
+
+In fact, the reason the project is called "psychic" is because it's supposed to seem like it's reading your mind. When you ask it to do something, like "bootstrap" a project, it should seem like it just magically picks the correct command to run. The project is actually more of a fraud than a clairvoyant - it just uses "[hot](http://en.wikipedia.org/wiki/Hot_reading)" and "[cold](http://en.wikipedia.org/wiki/Cold_reading)" reading tricks to pick the correct command.
+
+### Psychic vs scripts/*
+
+ThoughtBot, GitHub and others use a [bootstrap consistency pattern](http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency) to provide "a consistent user experience to get from zero to productive on any new project". The scripts used vary but common examples are:
+- Bootstrapping via `bin/setup` or `script/bootstrap`
+- Running tests via `script/test` and/or `script/cibuild`
+
+Psychic's goals are similar but it's scope is broader, as explained above. Psychic will detect the scripts/* pattern and delegate task commands to it, so `psychic task bootstrap` will run `scripts/bootstrap.sh` if it exists. If you have both `bootstrap.sh` and `boostrap.ps1` (for Windows) psychic will choose the appropriate script for your platform.
+
+The difference is that if you try to run a task for psychic that doesn't have a script Psychic will continue looking for other ways to run that task. For example, if you have a `scripts/bootstrap.sh` and `Rakefile` that defines `lint` task, then `psychic bootstrap` will run `scripts/bootstrap.sh`, while `psychic lint` will run `rake lint`.
+
+### Psychic vs Travis-Build
+
+The goals of psychic are also similar to travis-build, and psychic will delegate supported tasks to travis-build if it is installed. Even if it isn't installed, Psychic aims to be as compatible as possible with travis-build, so a command like `psychic task install` behave a lot like `travis run install`.
+
+Note that travis-build is not installed as a normal gem or Psychic would just depend on it. If you want psychic to delegate to travis-build you need to [install it as a CLI extension](https://github.com/travis-ci/travis-build#use-as-addon-for-cli).
+
+#### Scope
+Psychic's scope is broader, so there are things you could do with psychic that wouldn't make sense to run on Travis-CI. For example, you could setup a command like `psychic wip`, that would show your work in progress for any given project. The behavior would be project specific, but could include things like:
+- Listing your local branches that haven't been merged
+- Listing pull requests that are assigned to you
+- Issues that are assigned to you
+- Display `what_im_working_on.txt`
+
+The command could be setup so it would display a WIP report for any project, even if some projects are getting info from your local git branches, other from GitHub, and others from issue trackers like JIRA, Launchpad, or Mingle. This command obviously doesn't make sense on Travis-CI, especially if it's only showing the work in progress for a current developer, but could be very useful if you want to quickly review your WIP across several projects. That's what the [omnitest](https://github.com/omnitest/omnitest) tool's [crosstasking](https://github.com/omnitest/omnitest#crosstasking-via-psychic) feature is designed to do.
+
+#### Features
+
+This is one of the reasons why psychic was created as a new project rather than as enhancements to travis-build. In general, Psychic aims to provide a simpler API that is less coupled with Travis. The major differences between Psychic and travis-build are:
+- Psychic is distributed as a gem that can be used as a library or a standalone CLI. Travis-build is a
+travis CLI extension that is not distributed as a gem.
+- Psychic as a simple API for running tasks by alias. The travis-build API is tightly coupled with a travis-configuration object.
+- Psychic just provides task aliases and inference. It does not provide environment setup, like fetching projects from version control or driving environment managers like rvm or virtualenv. Those actions should be done before invoking psychic.
+- Psychic does not contain travis-specific features like integration with travis's caching system.
+
+## Psychic Commands
+
+### Tasks
+
+Psychic supports both built-in and custom tasks. You should be able to use built-in tasks in virtually any project, even projects that weren't setup for psychic, because these tasks are mapped to common actions of commonly used tools.
+
+#### Built-in Tasks
+
+The `bootstrap` task is an example of a built-in task. If you run `psychic bootstrap` it will setup your project. It detects tools or patterns that are commonly used to setup projects and will choose an appropriate command for that tool. So it may run something like `bundle install`, `npm install`, or `scripts/bootstrap.sh`, depending on your project.
+
+The built-in tasks are all mapped to top-level commands, so you can see them by running `psychic help`.
+
+#### Custom Tasks
+
+Psychic can also run custom tasks. You can list all known tasks, including custom tasks, with the command `psychic list tasks`. If you run with the `--verbose` flag it will show the command that would be run.
+
+This list will include any custom tasks mapped to a command in `psychic.yaml`. Psychic will also try to detect known tasks from any tool that can print out a list of documented tasks, like Rake (via `rake --tasks` ), Grunt (via `grunt --help`) or NPM (via `npm run`). This is only partially supported, because not all tools support listing tasks, and even the ones that do rarely have an option for machine-readable output or an option like git's `--porcelain` (to "give the output in an easy-to-parse format for scripts", which will "remain stable across versions regardless of user configuration").
+
+You can run a custom task via `psychic task <task_name>`. So if you have defined a `lint` task in a tool that supports autodetection, or defined the task in `psychic.yaml`, then you can run it with `psychic task lint`.
+
+```sh
+ bundle exec psychic task lint
+I, [2015-01-15T13:01:09.752242 #59850]  INFO -- : Executing bundle exec rubocop -D
+I, [2015-01-15T13:01:10.595926 #59850]  INFO -- : warning: parser/current is loading parser/ruby21, which recognizes
+I, [2015-01-15T13:01:10.596019 #59850]  INFO -- : warning: 2.1.5-compliant syntax, but you are running 2.1.4.
+I, [2015-01-15T13:01:11.142419 #59850]  INFO -- : Inspecting 2 files
+I, [2015-01-15T13:01:11.142526 #59850]  INFO -- : ..
+I, [2015-01-15T13:01:11.142553 #59850]  INFO -- :
+I, [2015-01-15T13:01:11.142576 #59850]  INFO -- : 2 files inspected, no offenses detected
+```
+
+You can also pass additional arguments to the command after the end of options delimiter (`--`). This is useful for passing flags like `--debug`, `--verbose` or `--help`, though there is no guarantee that any of these flags will work (even `--help`) will work for a task.
+
+```sh
+$ bundle exec psychic task lint -- --debug
+I, [2015-01-15T13:06:11.456547 #60908]  INFO -- : Executing bundle exec rubocop -D --debug
+I, [2015-01-15T13:06:12.288424 #60908]  INFO -- : warning: parser/current is loading parser/ruby21, which recognizes
+I, [2015-01-15T13:06:12.289181 #60908]  INFO -- : warning: 2.1.5-compliant syntax, but you are running 2.1.4.
+I, [2015-01-15T13:06:12.689274 #60908]  INFO -- : For /Users/Thoughtworker/repos/rackspace/polytrix/samples/sdks/ruby: configuration from /Users/Thoughtworker/repos/rackspace/polytrix/.rubocop.yml
+I, [2015-01-15T13:06:12.689343 #60908]  INFO -- : Inheriting configuration from /Users/Thoughtworker/repos/rackspace/polytrix/.rubocop_todo.yml
+I, [2015-01-15T13:06:12.689372 #60908]  INFO -- : Default configuration from /opt/boxen/rbenv/versions/2.1.4/lib/ruby/gems/2.1.0/gems/rubocop-0.28.0/config/default.yml
+I, [2015-01-15T13:06:12.689396 #60908]  INFO -- : Inheriting configuration from /opt/boxen/rbenv/versions/2.1.4/lib/ruby/gems/2.1.0/gems/rubocop-0.28.0/config/enabled.yml
+I, [2015-01-15T13:06:12.689421 #60908]  INFO -- : Inheriting configuration from /opt/boxen/rbenv/versions/2.1.4/lib/ruby/gems/2.1.0/gems/rubocop-0.28.0/config/disabled.yml
+I, [2015-01-15T13:06:12.689447 #60908]  INFO -- : Inspecting 2 files
+I, [2015-01-15T13:06:12.689487 #60908]  INFO -- : Scanning /Users/Thoughtworker/repos/rackspace/polytrix/samples/sdks/ruby/Gemfile
+I, [2015-01-15T13:06:12.689514 #60908]  INFO -- : .Scanning /Users/Thoughtworker/repos/rackspace/polytrix/samples/sdks/ruby/katas/hello_world.rb
+I, [2015-01-15T13:06:12.689534 #60908]  INFO -- : .
+I, [2015-01-15T13:06:12.689553 #60908]  INFO -- :
+I, [2015-01-15T13:06:12.689574 #60908]  INFO -- : 2 files inspected, no offenses detected
+I, [2015-01-15T13:06:12.689595 #60908]  INFO -- : Finished in 0.04216 seconds
+```
+
+### Code Samples
+
+Psychic also has features to detect and run a code sample by alias, just like it runs tasks by an alias. This gets more complicated and might be split into a separate gem in the future, so we'll leave that for a separate doc.
+
+## Related projects
+
+### Skeptic
+
+The [Skeptic](https://github.com/omnitest/skeptic) project is a companion to Psychic that tests the results code samples via Psychic. It captures and validates the output the exit code and output of the process, but can also capture additional data through "spies" like looking for HTTP calls it expects to see or files that should be created. So it let's you write assertions and reports on the behavior of code that's executed via Psychic.
+
+### Omnitest
+
+The [omnitest](https://github.com/omnitest/omnitest) project is for running tasks or tests across multiple projects. It uses Psychic (and Skeptic) in order to run the task in teach project, and then consolidates all of the results and produces reports.

data/lib/omnitest/output_helper.rb

@@ -0,0 +1,84 @@
+module Omnitest
+  module OutputHelper
+    class StringShell < Thor::Base.shell
+      attr_reader :io
+
+      def initialize(*args)
+        @io = StringIO.new
+        super
+      end
+
+      alias_method :stdout, :io
+      alias_method :stderr, :io
+
+      def string
+        @io.string
+      end
+
+      def can_display_colors?
+        # Still capture colors if they can eventually be displayed.
+        $stdout.tty?
+      end
+    end
+
+    def cli
+      @cli ||= Thor::Base.shell.new
+    end
+
+    def build_string
+      old_cli = @cli
+      new_cli = @cli = StringShell.new
+      yield
+      @cli = old_cli
+      new_cli.string
+    end
+
+    def reformat(string)
+      return if string.nil? || string.empty?
+
+      indent do
+        string.gsub(/^/, indent)
+      end
+    end
+
+    def indent
+      @indent_level ||= 0
+      if block_given?
+        @indent_level += 2
+        result = yield
+        @indent_level -= 2
+        result
+      else
+        ' ' * @indent_level
+      end
+    end
+
+    def say(msg)
+      cli.say msg if msg
+    end
+
+    def status(status, msg = nil, color = :cyan, colwidth = 50)
+      msg = yield if block_given?
+      cli.say(indent) if indent.length > 0
+      status = cli.set_color("#{status}:", color, true)
+      # The built-in say_status is right-aligned, we want left-aligned
+      cli.say format("%-#{colwidth}s %s", status, msg).rstrip
+    end
+
+    # TODO: Reporters for different formats
+    def print_table(*args)
+      # @reporter.print_table(*args)
+      cli.print_table(*args)
+    end
+
+    def colorize(string, *args)
+      return string unless @reporter.respond_to? :set_color
+      # @reporter.set_color(string, *args)
+      cli.set_color(string, *args)
+    end
+
+    def color_pad(string)
+      string + colorize('', :white)
+    end
+  end
+end

data/lib/omnitest/psychic.rb

@@ -0,0 +1,191 @@
+require 'omnitest/core'
+require 'omnitest/psychic/version'
+require 'omnitest/psychic/error'
+require 'omnitest/psychic/code2doc'
+require 'yaml'
+
+autoload :Thor, 'thor'
+
+module Omnitest
+  autoload :Shell,  'omnitest/shell'
+  autoload :OutputHelper, 'omnitest/output_helper'
+
+  # The primary interface for using Psychic as an API.
+  #
+  # Detects scripts and tools that can run tasks in the instance's working directory,
+  # so that Psychic can act as a universal task/script selection and execution system.
+  class Psychic # rubocop:disable Metrics/ClassLength
+    autoload :Tokens,   'omnitest/psychic/tokens'
+    module Tokens
+      autoload :RegexpTokenHandler,   'omnitest/psychic/tokens'
+      autoload :MustacheTokenHandler,   'omnitest/psychic/tokens'
+    end
+    module Execution
+      autoload :DefaultStrategy, 'omnitest/psychic/execution/default_strategy'
+      autoload :TokenStrategy, 'omnitest/psychic/execution/token_strategy'
+      autoload :EnvStrategy, 'omnitest/psychic/execution/env_strategy'
+      autoload :FlagStrategy, 'omnitest/psychic/execution/flag_strategy'
+    end
+    autoload :Hints, 'omnitest/psychic/hints'
+    autoload :FileFinder, 'omnitest/psychic/file_finder'
+    autoload :FactoryManager, 'omnitest/psychic/factory_manager'
+    autoload :ScriptFactoryManager, 'omnitest/psychic/script_factory_manager'
+    autoload :ScriptFactoryManager, 'omnitest/psychic/script_factory_manager'
+    autoload :TaskFactoryManager, 'omnitest/psychic/task_factory_manager'
+    autoload :MagicTaskFactory, 'omnitest/psychic/magic_task_factory'
+    autoload :ScriptFactory, 'omnitest/psychic/script_factory'
+    autoload :CommandTemplate, 'omnitest/psychic/command_template'
+    autoload :Task, 'omnitest/psychic/task'
+    autoload :Script, 'omnitest/psychic/script'
+    autoload :Workflow, 'omnitest/psychic/workflow'
+    autoload :TaskRunner, 'omnitest/psychic/task_runner'
+    autoload :ScriptRunner, 'omnitest/psychic/script_runner'
+
+    FactoryManager.autoload_factories!
+
+    include Core::Logger
+    include Shell
+    include TaskRunner
+    include ScriptRunner
+
+    # @return [String] A name for logging and reporting.
+    # The default value is the name of the current working directory.
+    attr_reader :name
+    # @return [Dir] Current working directory for running commands.
+    attr_reader :cwd
+    alias_method :basedir, :cwd
+    # @return [Hash] Environment variables to use when executing commands.
+    #   The default is to pass all environment variables to the command.
+    attr_reader :env
+    # @return [String] The Operating System to target. Autodetected if unset.
+    attr_reader :os
+    # @return [Hints] Psychic "hints" that are used to help Psychic locate tasks or scripts.
+    attr_reader :hints
+    # @return [Hash] Parameters to use as input for scripts.
+    attr_reader :parameters
+    # @return [Hash] Additional options
+    attr_reader :opts
+
+    DEFAULT_PARAMS_FILE = 'psychic-parameters.yaml'
+
+    # Creates a new Psychic instance that can be used to execute tasks and scripts.
+    # All options are
+    # @params [Hash] opts
+    # @option opts [Dir] :cwd sets the current working directory
+    # @option opts [Logger] :logger assigns a logger
+    # @option opts [Hash] :env sets environment variables
+    # @option opts [String] :name a name for logging and reporting
+    # @option opts [String] :os the target operating system
+    # @option opts [String] :interactive run psychic in interactive mode, where it will prompt for input
+    def initialize(opts = { cwd: Dir.pwd  }) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      opts[:cwd] ||= Dir.pwd
+      # must be a string on windows...
+      @cwd = opts[:cwd] = Pathname(opts[:cwd]).to_s
+      @opts = opts
+      init_attr(:name) { File.basename cwd }
+      init_hints
+      init_attr(:logger) { new_logger }
+      init_attr(:env) { ENV.to_hash }
+      init_attr(:os) { RbConfig::CONFIG['host_os'] }
+      init_attrs :cli, :interactive, :parameter_mode, :restore_mode, :print
+      @shell_opts = select_shell_opts
+      @parameters = load_parameters(opts[:parameters])
+    end
+
+    # Executes a command using the options set on this Psychic instance.
+    #   @param [String] command the command to execute
+    #   @param [*args] *args additional arguments to join to the command
+    #   @return [ExecutionResult] the result of running the command
+    #   @raises [ExecutionError] if the command
+    #
+    # @example
+    #   psychic.execute('echo', 'hello', 'world')
+    #   #<Omnitest::Shell::ExecutionResult:0x007fdfe15208f0 @command="echo hello world",
+    #     @exitstatus=0, @stderr="", @stdout="hello world\n">
+    #
+    # @example
+    #   psychic.execute('foo')
+    #   # Omnitest::Shell::ExecutionError: No such file or directory - foo
+    def execute(command, *args)
+      shell_opts = @shell_opts.dup
+      shell_opts.merge!(args.shift) if args.first.is_a? Hash
+      full_cmd = [command, *args].join(' ')
+      logger.banner("Executing: #{full_cmd}")
+      shell.execute(full_cmd, shell_opts)
+    end
+
+    def workflow(name = 'workflow', options = {}, &block)
+      Workflow.new(self, name, options, &block)
+    end
+
+    # Detects the Operating System family for the selected Operating System.
+    # @return [Symbol] The operating system family for {#os}.
+    def os_family
+      case os
+      when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+        :windows
+      when /darwin|mac os/
+        :macosx
+      when /linux/
+        :linux
+      when /solaris|bsd/
+        :unix
+      else
+        :unknown
+      end
+    end
+
+    # @return [Boolean] true if Psychic is in interactive mode and will prompt for decisions
+    def interactive?
+      @opts[:interactive]
+    end
+
+    private
+
+    def init_attr(var)
+      var_name = "@#{var}"
+      var_value = @opts[var]
+      var_value = yield if var_value.nil? && block_given?
+      instance_variable_set(var_name, var_value)
+    end
+
+    def init_attrs(*vars)
+      vars.each do | var |
+        init_attr var
+      end
+    end
+
+    def init_hints
+      hint_data = Omnitest::Core::Util.symbolized_hash(@opts[:hints] || load_hints || {})
+      @hints = Hints.new hint_data
+      @opts.merge! Omnitest::Core::Util.symbolized_hash(@hints.options)
+    end
+
+    def select_shell_opts
+      # Make sure to delete any option that isn't a MixLib::ShellOut option
+      @opts.select { |key, _| Omnitest::Shell::AVAILABLE_OPTIONS.include? key }
+    end
+
+    def load_hints
+      hints_file = Dir.glob("#{@cwd}/psychic.{yaml,yml}", File::FNM_CASEFOLD).first
+      YAML.load(File.read(hints_file)) unless hints_file.nil?
+    end
+
+    def load_parameters(parameters)
+      if parameters.nil? || parameters.is_a?(String)
+        load_parameters_file(parameters)
+      else
+        parameters
+      end
+    end
+
+    def load_parameters_file(file = nil)
+      if file.nil?
+        file ||= File.expand_path(DEFAULT_PARAMS_FILE, cwd)
+        return {} unless File.exist? file
+      end
+      # Just return it as a template, not as YAML
+      File.read(file)
+    end
+  end
+end