loom-core 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11bd9487c4e4752e294000493fe1fe04537f97bfcea9385b1cf16e90c2c79a71
-  data.tar.gz: 926227cb27d65b64103dd0f541acb1f523afdfac2df832180450f1aaaff4397f
+  metadata.gz: 8c95f594a71ab9a9a776b8f83cceb04224d17d7527546237f019f018971be6ad
+  data.tar.gz: d105521e8666b8bc50b7fd504e13534c02d3c216f1d99bdf72ef484602a54efb
 SHA512:
-  metadata.gz: 687255010d7a4c709cb95b2022151a95175ae88decb368cfac503dd3bfdb24c677abdbd2ef055f16a80a783bad2d24762ab856bf20c085ec08d1f51734c78c01
-  data.tar.gz: b789683f5aefd5a1997536e3f930f143bb7c12fc24be4e40d10fb0147e0c997c5af84798fad9e2da79d3cdbb7f5fe4a854d3f981f6deabe43ff08ab0092e3c68
+  metadata.gz: 71bce721c3d6168173522d90e56988cf415daef5bf6dcb97033a4fac8d9fa9f7ae9ae422c27b2dcd31027de60f3935c02f8cd12926dffd251272698ffbfa5314
+  data.tar.gz: 3196d487c91a75cb327b4b2050fbdbce95c5c1e1ea0f8890429999e16baf6a5349f127b0579eea362395ffeda7a19ebac5bb03fe05d5fab08e332c29576161ab

data/.rubocop.yml

@@ -0,0 +1,31 @@
+# https://rubocop.readthedocs.io/en/latest/cops_layout/
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+Layout/MultilineMethodCallBrace:
+  Enabled: false
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Lint/BooleanSymbol:
+  Enabled: false
+
+# https://rubocop.readthedocs.io/en/latest/cops_metrics/
+Metrics/LineLength:
+  Max: 100
+
+Naming/HeredocDelimiterNaming:
+  Enable: false
+
+# https://rubocop.readthedocs.io/en/latest/cops_style/
+Style/Alias:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Enabled: false
+Style/Encoding:
+  Enabled: false
+Sylte/IfUnlessModifier:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    loom-core (0.0.6)
+    loom-core (0.0.7)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       commander (~> 4.4)
       ed25519 (>= 1.0, < 2.0)
@@ -12,6 +12,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.0)
     bcrypt_pbkdf (1.0.0)
     byebug (9.0.6)
     coderay (1.1.1)
@@ -36,6 +37,7 @@ GEM
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
     highline (1.7.10)
+    jaro_winkler (1.5.1)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
@@ -49,6 +51,10 @@ GEM
     notiffany (0.1.1)
       nenv (~> 0.1)
       shellany (~> 0.0)
+    parallel (1.12.1)
+    parser (2.5.1.2)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
     pry (0.10.4)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -56,6 +62,7 @@ GEM
     pry-byebug (3.4.0)
       byebug (~> 9.0)
       pry (~> 0.10)
+    rainbow (3.0.0)
     rake (11.3.0)
     rb-fsevent (0.9.8)
     rb-inotify (0.9.7)
@@ -77,6 +84,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
+    rubocop (0.60.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
     ruby_dep (1.5.0)
     shellany (0.0.1)
     slop (3.6.0)
@@ -84,6 +100,7 @@ GEM
       net-scp (>= 1.1.2)
       net-ssh (>= 2.8.0)
     thor (0.19.1)
+    unicode-display_width (1.4.0)
 
 PLATFORMS
   ruby
@@ -96,6 +113,7 @@ DEPENDENCIES
   pry-byebug
   rake (~> 11.3)
   rspec (~> 3.5)
+  rubocop
 
 BUNDLED WITH
    1.16.2

data/Rakefile

@@ -1,3 +1,5 @@
+# TODO: I can replace this with Loom now.
+# TODO: Make a Loom mod that converts Rake Tasks into Loom Patterns.
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/bin/loom

@@ -158,6 +158,9 @@ EOS
           end
         end
       end
+      # TODO: p and patterns produce different output on failure, p is a
+      # truncated stack. Figure out why, and fix that. This is going to be
+      # somewhere in Commander.
       alias_command :"p", :"patterns"
 
       command :"config" do |c|

data/gentags.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+find lib -name \*.rb | etags -l ruby --output=loom.TAGS -

data/lib/loom/all.rb

@@ -9,12 +9,12 @@ require_relative "config"
 
 require_relative "shell"
 require_relative "host_spec"
-require_relative "dsl"
 
 require_relative "inventory"
 require_relative "facts"
 require_relative "pattern"
 require_relative "mods"
+require_relative "runner/all"
 require_relative "runner"
 
 require_relative "version"

data/lib/loom/config.rb

@@ -77,7 +77,7 @@ module Loom
     class FileManager
 
       def initialize(config)
-        @loom_search_paths = config.loom_search_paths
+        @loom_search_paths = [config.loom_search_paths].flatten
         @loom_files = config.loom_files
         @loom_file_patterns = config.loom_file_patterns
       end

data/lib/loom/mods/mod_loader.rb

@@ -10,7 +10,12 @@ module Loom::Mods
       @loom_config = loom_config
     end
 
-    def verify_shell_cmds(shell, mod_klass)
+    def load_mod_klass(mod_klass, shell)
+      verify_shell_cmds mod_klass, shell
+    end
+
+    private
+    def verify_shell_cmds(mod_klass, shell)
       Loom.log.debug2(self) { "verifying cmds for mod => #{mod_klass}" }
       mod_klass.required_commands.each do |cmd|
         begin
@@ -53,7 +58,7 @@ module Loom::Mods
           Loom.log.debug3(self) do
             "handling mod call => #{mod_klass}##{name} #{args} #{pattern_block}"
           end
-          verify_shell_cmds shell, mod_klass
+          load_mod_klass mod_klass, shell
 
           mod = mod_klass.new shell, @loom_config
           mod.execute *args, &pattern_block

data/lib/loom/pattern/all.rb

@@ -1,6 +1,7 @@
 require_relative "dsl"
 require_relative "hook"
 require_relative "definition_context"
+require_relative "pattern"
 require_relative "reference"
 require_relative "expanding_reference"
 require_relative "reference_set"

data/lib/loom/pattern/definition_context.rb

@@ -8,11 +8,11 @@ module Loom::Pattern
 
     NilLetValueError = Class.new Loom::LoomError
 
-    def initialize(pattern_module, parent_context=nil)
-      @fact_map = pattern_module.facts.dup
-      @let_map = pattern_module.let_map.dup
+    def initialize(dsl_builder, parent_context=nil)
+      @fact_map = dsl_builder.facts.dup
+      @let_map = dsl_builder.let_map.dup
 
-      @hooks = pattern_module.hooks.dup
+      @hooks = dsl_builder.hooks.dup
       @parent_context = parent_context
 
       @merged_fact_map = merged_fact_map

data/lib/loom/pattern/dsl.rb

@@ -1,13 +1,53 @@
+# IN Progress:
+# [wip-patternbuilder]
+# * Add a phase to the pattern execution sequence to collect calls to factset and loom
+#   objects. Results collected from this ""pre-execute"" can be analyzed for errors, optimization,
+#   success assertions, verification, etc. The loom file then executes in 2 passes, analyze &
+#   execute.
+#   -- pre-fact collection - inject the facts (or loom) object as a recorder
+#   -- (like a mock in record mode) # instead of the factual fact set. no need
+#   -- to change any loom files.
+#   -- only run fact providers which are accessed in the pattern set
+#   -- only load modules accessed in the pattern set
+#
+# * Replace Pattern "mods" and "mod specs" in 80 Loom::Pattern::ReferenceSet
+#   with usages of a builder instead. Currently the internal data model in
+#   ReferenceSet is confusing, but luckily it's the only client of pattern
+#   modules, that have used Loom::Pattern::DSL. Change calls to
+#   DSL#pattern/report/weave (anythin else that creates a pattern) to add a new
+#   PatternBuilder to the module. Use the builder to implement the TODO above
+#   ("Add a phase..."). Implement analysis on the builder.
+# [master]
+# * ... ongoing ... ways to test and +verify+ pattern execution
+
 # TODO: DSL extensions:
-# - a way to test and verify pattern execution.... I still don't trust this
-#   enough. this starts with fixing error reporting.
+# - More Mods! .... ondeck:
+#   * bkblz
+#   * cassandra
+#   * apache (nginx?)
+#   * digital ocean
+#   * systemd-nspawj
+
+# - Models Future:
+#   Notice each ondeck module above (bkblz, cassanadra, apache, digital ocean,
+#   system-nspawn): covers a unique infrastructure area, i.e.: bkblz:object and
+#   cold storage, cassandra:hyper-scale data storage, apache/nginx:content
+#   serving, digital-ocean/aws/gcp:remote virtual hosting, containers:local
+#   virtual hosting
+#   I could generalize each of the above infrastructure area into a high level
+#   mod. Should I? Maybe not.
+
+# - auto mod documentation in the CLI
+
 # - Pattern+non_idempotent+ marks a pattern as explicitly not idempotent, this
 #   let's additional warnings and checks to be added
+
 # - A history module, store a log of each executed command, a hash of the .loom
 #   file, and the requisite facts (the let declarations) for each executed pattern
 #   on the host it executes. /var/log/loom/history? Create this log on startup.
 #   -- add a new set of history commands through the CLI and a history
 #      FactProvider exposing host/loom/pattern_slug execution stats.
+
 # - Provide automatic command reversion support with a =Module= DSL that ties in
 #   with local revision history.
 #   -- allow Module actions/mods to define an "undo" command of itself given the
@@ -24,6 +64,7 @@
 #      accesses to fact_set be done in let expressions (enforce this maybe?)
 #   -- Later... before/after hooks can ensure the entire loom execution sequence
 #      was "revertable"
+
 # - A mechanism to allow mods to register CLI flags and actions. Using an action predicate
 #   mechanisms can add flags at the global or action levels. All CLI flags set config values.
 #   -- Mods can also register for action namespaces similar to git. This is consistent with mod
@@ -31,33 +72,20 @@
 #   -- Best way is to migrate loom/mods/module and loom/mods/action_proxy into base classes of
 #      themselves. The isolate the shell specific behavior into a subclass of each to preserve the
 #      current behavior. A new "cli" module and "cli" action proxy would enable the implementation.
-# - Add a phase to the pattern execution sequence to collect calls to factset and loom
-#   objects. Results collected from this ""pre-execute"" can be analyzed for errors, optimization,
-#   success assertions, verification, etc. The loom file then executes in 2 passes, analyze &
-#   execute.
-#   -- pre-fact collection - inject the facts (or loom) object as a recorder (like a mock in record mode)
-#      instead of the factual fact set. no need to change any loom files.
-#   -- only run fact providers which are accessed in the pattern set
-#   -- only load modules accessed in the pattern set
-# - Replace Pattern "mods" and "mod specs" in Loom::Pattern::ReferenceSet with usages of a builder
-#   instead. Currently the internal data model in ReferenceSet is confusing, but luckily it's the
-#   only client of pattern modules, that have used Loom::Pattern::DSL. Change calls to
-#   DSL#pattern/report/weave (anythin else that creates a pattern) to add a new PatternBuilder to
-#   the module. Use the builder to implement the TODO above ("Add a phase..."). Implement analysis
-#   on the builder.
 
 =begin
 
 ## .loom File DSL
 
 See:
-* spec/test.loom for a valid .loom file.
+* spec/.loom/*.loom for a lots of valid .loom files.
+  * run these specs with `rspec spec/test_loom_spec.rb`
 * spec/loom/pattern/dsl_spec.rb for other examples
 
 
-I've tried to take inspriation from several ruby DSLs, including (but not
-limited to) RSpec, Thor, Commander, Sinatra... so hopefully it feels
-comfortable.
+I've tried to take inspriation from several ruby DSLs, including RSpec, Thor,
+Commander, Sinatra... so hopefully it feels comfortable. Thank you to all of
+those projects.
 
 Loom::Pattern::DSL is the mixin that defines the declarative API for all .loom
 file defined modules. It is included into Loom::Pattern by default. The outer
@@ -83,15 +111,19 @@ end
 
 It declares a reference set with slugs:
 
-* top_level
+* cmd
 * outer:first
 * outer:inner:second
 
-Defining the same pattern slug twice raises a DuplicatPatternRef error.
+Defining the same pattern slug twice raises a `DuplicatePatternRef` error.
 
 #### Code Details
 
-To follow the code path for .loom file loading see:
+Loom::DSL is a facade available to all .loom file ::Modules that include
+Loom::Pattern. It provides Module singleton methods listed at
+Loom::DSL::DSL_METHODS.
+
+Code path for .loom file loading:
 
     Loom::Runner#load
       -> Loom::Pattern::Loader.load
@@ -103,12 +135,48 @@ file. A ReferenseSet being a collection of references with uniquely named
 slugs. The slug of a reference is computed from the module namespace and
 instance method name.
 
+### `weave`
+
+The `weave` creates a specialized pattern, that allows aliasing a sequence of
+pattern slugs as a single pattern name. Pattern execution will be flattened and
+run sequentially before or after any other patterns in the `$ loom` invocation.
+
+``` ~ruby
+pattern :step_1 { ... }
+pattern :step_2 { ... }
+
+module OtherTasks
+...
+end
+
+weave :do_it, [ :step_1, :step_2, :other_tasks:* ]
+```
+
+This creates pattern :do_it, which when run `$ loom do_it` will run :step_1,
+:step_2, and all slugs that match /other_tasks.*/. Recursive expansion is
+explicitly disallowed, only pattern names (not weaves), are allowed in the list
+of weave pattern slugs.
+
+#### Code Details
+
+Weave expansion to pattern slugs is accomplished by creating a
+Loom::Pattern::ExpandingReference via the Loom::Pattern::Loader+load+ path
+invoked via Loom::Runner+load+. Expansion happens on read via
+Loom::Pattern::Loader+patterns+, thus the list of patterns is constant
+throughout all phases of pattern execution.
+
 ### `report`
 
-Use `report` to create a pattern that outputs a fact, other value, or result of
-a block to yaml, json, or any other format.
+Use `report` to create another specialized pattern that prints a fact, value,
+or result of a block to yaml, json, or any other format to STDOUT.
 
-### `let`, `before`, and `after`
+### `let`, `before`, and `after`: for examples spec/.loom/parent_context.loom
+
+`let`, does the same as in RSpec (including the context details). It creates an
+alias for a value, available in all patterns.
+
+`before` and `after` are similar to the same in RSpec. Each before/after block
+is run before/after respectively to EACH pattern.
 
 Module::Inner, from above, inherits all +let+ declarations from its outer
 contexts, both :: (root) and ::Outer. +before+ hooks are run from a top-down
@@ -179,31 +247,6 @@ Loom::Facts::FactSet as parameters.
 See Loom::Pattern::DefinitionContext for evaluation of `let` blocks and
 before/after context ordering.
 
-### `weave`
-
-The `weave` keyword allows aliasing a sequence of patterns a single
-name. Pattern execution will be flattened and run sequentially before or after
-any other patterns in the `$ loom` invocation.
-
-``` ~ruby
-pattern :step_1 { ... }
-pattern :step_2 { ... }
-
-weave :do_it, [ :step_1, :step_2 ]
-```
-
-This creates pattern :do_it, which when run `$ loom do_it` will run :step_1,
-:step_2. Recursive expansion is explicitly disallowed, only pattern names (not
-weaves), are allowed in the 2nd param of `weave`.
-
-#### Code Details
-
-Weave expansion to pattern slugs is accomplished by creating a
-Loom::Pattern::ExpandingReference via the Loom::Pattern::Loader+load+ path
-invoked via Loom::Runner+load+. Expansion happens on read via
-Loom::Pattern::Loader+patterns+, thus the list of patterns is constant
-throughout all phases of pattern execution.
-
 #### Pattern Execution Sequence
 
 Once hosts and patterns are identified in earlier Loom::Runner phases,
@@ -250,14 +293,55 @@ module Loom::Pattern
 
   PatternDefinitionError = Class.new Loom::LoomError
 
-  # TODO: clarify this DSL to only export:
-  # - description
-  # - pattern
-  # - let
-  # - after/before
-  # other methods are utility methods used to process and run patterns.
+  DSL_METHODS = [
+    :desc,
+    :description,
+
+    :pattern,
+    :weave,
+    :report,
+
+    :with_facts,
+    :let,
+    :before,
+    :after,
+
+    :namespace
+  ]
+
+  ##
+  # The Loom DSL definition. See documentation above.
   module DSL
+    DSL_METHODS.each do |m|
+      define_method m do |*args, &block|
+        Loom.log.debug1(self) { "delegating Pattern::DSL call to DSLBuilder+#{m}+" }
+        @dsl_builder.send(m, *args, &block)
+      end
+    end
+
+    attr_reader :dsl_builder
+
+    class << self
+      def extended(receiving_mod)
+        # NB: Using Forwardable was awkward here due to the scope of extended, and
+        # the scope of where the fordwardable instance variable would live.
+        dsl_builder = PatternBuilder.new
+        receiving_mod.instance_variable_set :@dsl_builder, dsl_builder
+      end
+    end
+  end
+
+  class DSL::PatternBuilder
+
+    def initialize
+      @pattern_map = {}
+      @fact_map = {}
+      @let_map = {}
+      @hooks = []
+      @next_description = nil
+    end
 
+    # BEGIN DSL Implementation
     loom_accessor :namespace
 
     def description(description)
@@ -266,37 +350,33 @@ module Loom::Pattern
     alias_method :desc, :description
 
     def with_facts(**new_facts, &block)
-      @facts ||= {}
-      @facts.merge! new_facts
-      yield_result = yield @facts if block_given?
-      @facts = yield_result if yield_result.is_a? Hash
+      @fact_map.merge! new_facts
+      yield_result = yield @fact_map if block_given?
+      @fact_map = yield_result if yield_result.is_a? Hash
     end
 
     def let(name, default: nil, &block)
       raise "malformed let expression: missing block" unless block_given?
-
-      @let_map ||= {}
       @let_map[name.to_sym] = LetMapEntry.new default, &block
     end
 
     def pattern(name, &block)
-      Loom.log.debug1(self) { "defining pattern => #{name}" }
-      define_pattern_internal(name, &block)
+      define_pattern_internal(name, kind: :pattern, &block)
     end
 
     ##
     # @param format[:yaml|:json|:raw] default is :yaml
     def report(name, format: :yaml, &block)
-      Loom.log.debug1(self) { "defining reporting pattern => #{name}" }
-      define_pattern_internal(name) do |loom, facts|
-        # TODO: I don't like all of this logic in the dsl.
+      define_pattern_internal(name, kind: :report) do |loom, facts|
+        # TODO: I don't like all of this logic here. It feels like it belongs in
+        # a mod.
         result = if block_given?
                    Loom.log.debug(self) { "report[#{name}] from block" }
-                   self.instance_exec(loom, facts, &block)
+                   instance_exec(loom, facts, &block)
                  elsif !Loom::Facts.is_empty?(facts[name])
                    Loom.log.debug(self) { "report[#{name}] from facts[#{name}]" }
                    facts[name]
-                 elsif self.respond_to?(name) && !self.send(name).nil?
+                 elsif respond_to?(name) && !self.send(name).nil?
                    Loom.log.debug(self) { "report[#{name}] from let{#{name}}" }
                    self.send name
                  else
@@ -318,15 +398,10 @@ module Loom::Pattern
     end
 
     def weave(name, pattern_slugs)
-      Loom.log.debug1(self) { "defining weave => #{name}" }
-      @weave_slugs ||= {}
-      @weave_slugs[name.to_sym] = pattern_slugs.map { |s| s.to_s }
-
       unless @next_description
         @next_description = "Weave runs patterns: %s" % pattern_slugs.join(", ")
       end
-
-      define_pattern_internal(name) { |_, _| true }
+      define_pattern_internal(name, kind: :weave, expanded_slugs: pattern_slugs) { true }
     end
 
     def before(&block)
@@ -336,68 +411,50 @@ module Loom::Pattern
     def after(&block)
       hook :after, &block
     end
+    # END DSL Implementation
 
-    def weave_slugs
-      @weave_slugs || {}
-    end
-
-    def is_weave?(name)
-      !!weave_slugs[name]
-    end
-
-    def pattern_methods
-      @pattern_methods || []
-    end
-
-    def pattern_description(name)
-      @pattern_descriptions[name]
-    end
-
-    def pattern_method(name)
-      raise UnknownPatternMethod, name unless @pattern_method_map[name]
-      instance_method name
+    def patterns
+      @pattern_map.values
     end
 
     def hooks
-      @hooks || []
+      @hooks
     end
 
     def facts
-      @facts || {}
+      @fact_map
     end
 
     def let_map
-      @let_map || {}
+      @let_map
     end
 
     private
-    def define_pattern_internal(name, &loom_file_block)
-      @pattern_methods ||= []
-      @pattern_method_map ||= {}
-      @pattern_descriptions ||= {}
-
-      method_name = name.to_sym
+    # TODO: Let mods introduce new pattern handlers. A pattern is effectively a
+    # named wrapper around a pattern execution block. This would be an advanced
+    # usage when before and after blocks aren't scalable. It could also provided
+    # additional filtering for pattern selection at weave time.
+    def define_pattern_internal(name, kind: :pattern, **kwargs, &loom_file_block)
+      unless block_given?
+        raise PatternDefinitionError, "missing block for pattern[#{name}]"
+      end
+      unless Pattern::KINDS[kind]
+        raise "unknown pattern kind: #{kind}"
+      end
 
-      @pattern_methods << method_name
-      @pattern_method_map[method_name] = true
-      @pattern_descriptions[method_name] = @next_description
+      desc = @next_description
+      unless desc.is_a?(String) || desc.nil?
+        raise PatternDefinitionError, "description must be a string: #{desc.class}"
+      end
       @next_description = nil
+      name = name.intern
 
-      ##
-      # ```ruby
-      # pattern :xyz do |loom, facts|
-      #   loom.x :dostuff
-      # end
-      # ```
-      # Patterns declared in the .loom file are defined here:
-      define_method method_name do |loom, facts|
-        Loom.log.debug2(self) { "calling .loom file pattern: #{name}" }
-        self.instance_exec(loom, facts, &loom_file_block)
-      end
+      Loom.log.debug(self) { "defined .loom pattern[kind:#{kind}]: #{name}" }
+      @pattern_map[name] = Pattern.new(
+        name: name, description: desc, kind: kind, **kwargs, &loom_file_block)
     end
 
     def hook(scope, &block)
-      @hooks ||= []
       @hooks << Hook.new(scope, &block)
     end
   end # DSL