WarningShot Dependency Resolution Framework
 * Additional documentation @ http://github.com/coryodaniel/warningshot/wikis/

==== Note on RSpecs
  Currently the PermissionResolver RSpecs will probably fail that is because
  I am not sure what the best way is to write them in regards to users & groups
  that may or may not be on a remote machine.  I wrote the specs, and they work on
  my laptop (given that I have the groups/users) mentioned in the tests.
  See: ./test/spec/unit/resolvers/permission_resolver_spec.rb

==== Installing WarningShot
  WarningShot installs a little differently than most gems.  WarningShot itself has NO gem dependencies.  Gems become
  a dependency based on what Plugins/Resolvers you have installed.  By default WarningShot will not install any 
  additional gems.
  When using WarningShot if a gem is missing that is needed for a feature you are using you will receive a warning that 
  the gem
  is missing.  Optionally you can list and build all of warningshots dependencies from the command line.
  
  sudo gem install warningshot
  warningshot --list-deps (list all resolvers and their dependencies)
  warningshot --build-deps (install all gems that resolvers are dependent on)
  
  This method provides a minimalist WarningShot.  WarningShot's dependencies essentially change depending on what you 
  use
  it for.  Thats neat, not a lot of extra gems that you don't need installed being installed.
  

==== Terminology
  * Resolver
    A class that includes WarningShot::Resolver.  It should have the ability to test and resolve a type
    of dependency
      
  * Configuration
    The current configuration the WarningShot instance is running under.
    Configurations can be created with WarningShot::Config
    
  * Dependency
    A dependency is an entry in a recipe.  A dependency should consist of some means of identifying the
    dependency and optionally (but suggested) have some way of describing how it should be resolved.
      Ex: File Dependencies specify where the file should be located, and where WarningShot can download it if it
          does not exist
  
  * Test
    Tests are blocks that are registered in resolver.  They are a means of determining if a dependency is met.  Multiple 
    tests
    can be written, and may also have conditions as to whether they should run or not (a test could be environment
    specific for instance).  WarningShot will run the first test that it can based on any conditions provided.  
    Tests should always return a Boolean value
  
  * Resolution
    Resolutions are like tests in every way except instead of determine if a dependency has been met, they actually
    repair or resolve the dependency.  The gem resolver can install missing gems and the file resolver can download
    missing files
  
  * Recipes / Application Recipes
    A recipe is one or more dependency branches, the default file type is YAML, but that is configurable
    within warningshot.  A recipe can consist of one or more dependency branches.

    Example:  warningshot --templates will create a separate recipe for each branch supported.
    In the wiki 
    (http://github.com/coryodaniel/warningshot/wikis/example-merbnginx-app-recipe-once-aptquality-dependencies-are-suppo
    rted)
    is an example of a recipe that specifies dependencies of files, gems, apt binaries, etc.  Essentially all the 
    dependencies needed for
    the web server role.
    
  * DependencyTree
    After WarningShot locates all of the Machine Recipes they are parsed into the dependency tree.  The dependency
    tree is a large hash of branch names to raw hashes parsed from the Machine Recipes (YAML).
    
  * DependencyBranch
    A specific type of dependency within the dependency tree.  Examples include, :file, :gem, :directory
  
==== How it works
  * WarningShot - Factory class that creates and runs DependencyResolver
  * DependencyResolver - Locates Resolver classes, creates a dependency tree, and matches resolvers to resolution 
  branches
  * Resolver - Class that can be included to create plugins.  Composed of tests and resolutions that can determine if a 
  dependency was met, and if not, how to fix it
  
==== Command Line Examples
For a list of all flags do: warningshot --help

  - Details on Resolvers
    warningshot --version
    
  - Loading specific resolvers
    warningshot --oload=gem,file                         # => Only gem and file resolvers will be run
    warningshot --pload=directory,file                   # => Only loads specified gems and loads in specified order
    warningshot --resolvers=/path/to/my/resolvers/*.rb   # => Glob to find additional resolvers

  - Creating Recipe templates
    warningshot --templates=./path/to/where/you/want/templates
    
  - Warningshot's Dependencies
    warningshot --list-deps                              # => Depedencies per Resolver
    warningshot --build-deps                            # => Installs everything a full fledged warningshot needs


==== Ruby API

  - Configuring WarningShot
  config = WarningShot::Config.create do |c|
    c[:environment]  = 'development'
    c[:resolve]      = false
    c[:config_paths] = ['.'  / 'config' / 'warningshot']
    c[:application]  = '.'
    c[:log_path]     = '.' / 'log' / 'warningshot.log'
    c[:log_level]    = :debug
    c[:growl]        = false
    c[:verbose]      = true
    c[:]
  end
  
  - Interfacing with a DependencyResolver
  dependency_resolver = WarningShot.fire!(config)
  dependency_resolver.stats                       # => Hash of statistics
  
  dependency_resolver.resolvers                   # => Array of all executed resolvers
  
  dependency_resolver.resolvers.first.dependencies #=> Set of all loaded dependencies
  
  dependency_resolver.resolver.first.passed     # => Array of passed dependencies
  dependency_resolver.resolver.first.failed     # => Array of failed dependencies
  dependency_resolver.resolver.first.unresolved # => Array of unresolved dependencies
  dependency_resolver.resolver.first.resolved   # => Array of resolved dependencies
  
  - Callbacks
  WarningShot.before do 
    puts 'this would run before the DepenencyResolver was created in #fire!'
  end
  
  WarningShot.after do
    puts 'this would run after the DepenencyResolver was processed in #fire!'
  end
  
  WarningShot::AnyResolverYouWant.before :test do
    puts 'this would run before the #test! method on the chosen resolver'
  end
  
  WarningShot::AnotherFunResolver.after :test do
    puts 'this would run after the #test! method'
  end
  
  WarningShot::AnotherResolver.before :resolution do
    puts 'this would run before the #resolve! method'
  end
  
  WarningShot::AnotherResolver.after :resolution do
    puts 'this would run after the #resolve! method'
  end
  
==== Components
 * Ruby API
 * Resolvers
 * Config Files
 
 
==== Using Machine Recipes
 * Coming Soon

 
==== How the dependency tree works
 * Coming Soon


==== Extending WarningShot
 * Writing a Resolver (Coming Soon)
    * Kernel#require vs Resolver#add_dependency
 * Modifying Resolvers at run-time (Coming Soon)


==== Contributing
 * Source available @: 
    https://github.com/coryodaniel/warningshot/tree
 
 * Bug reports / feature requests @:
    http://warningshot.lighthouseapp.com/projects/17241-warningshot/overview
 
 * Online Documentation available @:
    http://github.com/coryodaniel/warningshot/wikis
    
 * RubyForge Project @:
    http://rubyforge.org/projects/warning-shot/
 
 * All modifications should also have applicable rpsecs
    http://rspec.info/
    
 * A dummy gem has been created for testing the GemResolver
    https://rubyforge.org/projects/ws-dummy/
    http://github.com/coryodaniel/ws-dummy/tree/master
    gem install ws-dummy
 
 * All code should be documented using YARD
    http://yard.rubyforge.org/
    A template is available file://./yardoc_template.txt
    Generate Yardoc with: yardoc --output-dir ./doc/yard --private --protected --readme README