power_stencil 0.3.9 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 63b5292b83c11cf7fb867257189af4945225de5b
-  data.tar.gz: 104f23b19dfc0d0851e06bdb34f8e8ec5fe2c59e
+  metadata.gz: cfcce3efeec28087203d838f24ebef0e9353aaa0
+  data.tar.gz: 80e819c42c39ce84926cd38facd980038888300a
 SHA512:
-  metadata.gz: e6baf3d3caecbf9a102dbc42c272db77d7092dc77b97be2a87f98f6f1f807d3229c45fddcf36fc03bfbc678eb24aff074fdd9473652cc688e38a05e875aba76f
-  data.tar.gz: 41353ec4a84de5acabee14f9338ba9f311e9aed5c9a82588037cba254ad22c8bbc8d5a8ca82da0e940e5fd48183984832e0b9147dd4bb022821516d39b757886
+  metadata.gz: 60b1544795adc76d57b7749c14173708fc89bcbb265ee4ad044dd8c539a5d48884c7e38ad8bbbf0904f0a429ff1eb2a3bce0aff41782939b70d4f5f1c20e4682
+  data.tar.gz: afe028a613e6f4e4236fb019b501316202c95bb736a8e1e4090506b9d0feba3ed7b87add6795f38c4df1de8884b2bf166382df45d99dd3e9d1d828c339419102

data/.gitignore

@@ -10,4 +10,5 @@
 # rspec failure tracking
 .rspec_status
 /.idea/
+/.ruby-version
 /test/test_project/build/

data/Gemfile

@@ -1,4 +1,5 @@
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in power_stencil.gemspec
+
 gemspec

data/README.md

@@ -13,6 +13,7 @@ PowerStencil
     - [Creating a `PowerStencil` project](#creating-a-powerstencil-project)
     - [`PowerStencil` project structure](#powerstencil-project-structure)
     - [Getting started](#getting-started)
+- [Project status](#project-status)
 - [Contributing](#contributing)
     - [License](#license)
     - [Code of Conduct](#code-of-conduct)
@@ -23,7 +24,7 @@ PowerStencil
 
 `PowerStencil` proposes a radical approach on how to manage your shared configuration.
 
-Configuration is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, keep consistent and avoid duplication on the long run across the various projects that may share this configuration.
+**Configuration** is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, **keep consistent and avoid duplication** on the long run across the various projects that may share this configuration.
 
 From a very high level point of view, the workfow `PowerStencil` proposes looks like:
 
@@ -35,6 +36,8 @@ It is a common pattern to introduce a database to manage shared configuration fo
 
 A `PowerStencil` project is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization and **with `PowerStencil` everything is maintained in a git repository**: data, templates, specific code **without sacrificing on data integrity and relational features**. No more config loss, no more change applied without a full lineage.
 
+**:information_source: With `PowerStencil` data can either be managed as documents to edit (Yaml) or code !!**. Use the best method depending on what you are doing.
+
 The `PowerStencil` gem provides the `power_stencil` executable which is a pluggable CLI to:
 
 - Manage the project data
@@ -174,6 +177,9 @@ And course, you may:
 - Read the [F.A.Q.]
 - See some real world [example use cases].
 
+# Project status
+
+Check `PowerStencil` [status in the F.A.Q.].
 
 # Contributing
 
@@ -196,6 +202,7 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [plugins]: doc/plugins.md "Plugins in PowerStencil"
 [example use cases]: doc/example_use_cases.md "Example uses cases using PowerStencil"
 [F.A.Q.]: doc/faq.md "PowerStencil F.A.Q."
+[status in the F.A.Q.]: doc/faq.md#what-is-the-status-of-powerstencil- "PowerStencil project status"
 [code of conduct]: CODE_OF_CONDUCT.md
 
 <!-- Code links -->
@@ -208,4 +215,4 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [MIT License]: http://opensource.org/licenses/MIT "The MIT license"
 [ERB]: https://ruby-doc.org/stdlib-2.6.3/libdoc/erb/rdoc/ERB.html "Quick ERB description"
 [Haml]: http://haml.info/ "The templating engine for XML-like documents"
-[Ruby]: https://www.ruby-lang.org "The powerful Ruby language"
+[Ruby]: https://www.ruby-lang.org "The powerful Ruby language"

data/doc/entities.md

@@ -272,7 +272,12 @@ $ power_stencil get base_entity --names-only --regexp
 
 - my_1st_entity
 ```
-There are 2 other options (`--compiled` and `--scenario`) but they will be covered in the scope of [builds].
+There are 2 other interesting options (`--compiled` and `--scenario`) but they will be covered in the scope of [builds].
+
+:information_source: Another very interesting option is `--graph`. **It will generate a [Graphviz] graph of the relations of the entities within the repository.** This is actually provided by the [universe_compiler] Gem. The display of this graph can be completed customized at project level (the 2 versioned and unversioned config files), at entity level (by providing a `#graphviz_label` method in your entities. You'll see later in that document what it means in [creating custom entity types](#creating-custom-entity-types)), and even at plugin level.
+
+By default the graph is generated in a temporary folder, but of course you can specify the file name using the `--graph-file` options. The default is to generate an svg file (best viewed in a browser as it contains _hover_ over its nodes).
+
 
 ## Creating entities
 
@@ -664,6 +669,8 @@ So you see that if we try to set parent with something wrong, the accessor seems
 
 :information_source: The `name` property of the `has_one` directive is optional. If not present the field will be named from the entity_type referenced instead...
 
+**:warning: See more advanced features, like reverse methods in the [universe_compiler advanced relations documentation].**
+
 ### has_many
 
 Once you know the `has_one` directive, you should not be surprised by the `has_many` directive...
@@ -712,6 +719,8 @@ Which translates at persistence level as:
 ```
 Nice !
 
+**:warning: See more advanced features, like reverse methods in the [universe_compiler advanced relations documentation].**
+
 ### is_array
 
 You can define a field as being an array:
@@ -963,4 +972,6 @@ Now you know an entity type is just a regular Ruby class. As such you could add
 [Pry]: https://github.com/pry/pry "The awesome Pry console"
 [ActiveRecord]: https://guides.rubyonrails.org/active_record_basics.html "The ultimate ORM"
 [Ruby On Rails]: https://rubyonrails.org/ "One of the best Web framework"
-[universe_compiler]: https://gitlab.com/tools4devops/universe_compiler "The underlying engine to manage entities and compilation !"
+[universe_compiler]: https://gitlab.com/tools4devops/universe_compiler "The underlying engine to manage entities and compilation !"
+[universe_compiler advanced relations documentation]: https://gitlab.com/tools4devops/universe_compiler#advanced-relations "Advanced relational features"
+[Graphviz]: (https://www.graphviz.org/) "Graph Visualization Software"

data/etc/base_commands_definition.yml

@@ -148,6 +148,11 @@
         :summary: Displays the query result as a graph.
         :short_aliases:
           - g
+      graph-file:
+        :type: string
+        :summary: Displays the query result as a graph in the specified file.
+        :long_aliases:
+          - gf
   shell:
     :banner: |
       Opens a shell to interact with entities.

data/etc/meta_templates/plugin_seed/etc/plugin_config.yaml

@@ -1,4 +1,28 @@
 # This config file provided by the plugin '<%= main_entry_point %>' will be
 # automatically merged into the global project config
 
-# :<%= plugin_name %>.property1: value 1
+:<%= plugin_name %>.property1: value 1
+
+# Graphviz configuration
+#
+# If you are under Gnome, chances are that you have 'eog' installed
+# or put you own there. Unless in the path specify full path to it:
+# node defines the default graphviz node attributes. In customization
+# each key can be an entity type, that you can fully customize using the
+# same mechanism
+
+#:graphviz:
+#  :viewer: eog '%s'
+#  :label: < Repository Entities <br/> >
+#  :labelloc: :t
+#  :show_config: false
+#  :file_type: svg
+#  :graph_type: :digraph
+#  :node:
+#    :shape: box
+#    :style: filled
+#    :fillcolor: grey95
+#  :customizations:
+#    :my_custom_entity:
+#      :shape: circle
+#      :fillcolor: red

data/etc/meta_templates/plugin_seed/lib/{entity}/{entity}_processor.rb.erb

@@ -9,7 +9,6 @@ module <%= plugin_module_name %>
 
     def execute
       puts '<%= main_entry_point.upcase %> PLUGIN WAZ HERE'
-      puts_and_logs config[].to_yaml
     end
 
 

data/etc/power_stencil.yaml

@@ -82,7 +82,20 @@
 # are automatically discovered and loaded.
 :project_plugins: []
 
-
+# Graphviz
+
+# Customize graphviz properties
+:graphviz:
+  :label: < Repository Entities <br/> >
+  :labelloc: :t
+  :show_config: false
+  :file_type: :svg
+  :graph_type: :digraph
+  :node:
+    :shape: box
+    :style: filled
+    :fillcolor: grey95
+  :customizations: {}
 
 # MISC
 

data/etc/templates/plugin_definition/etc/plugin_config.yaml

@@ -1,4 +1,28 @@
 # This config file provided by the plugin '<%= main_entry_point %>' will be
 # automatically merged into the global project config
 
-# :<%= plugin_name %>.property1: value 1
+:<%= plugin_name %>.property1: value 1
+
+# Graphviz configuration
+#
+# If you are under Gnome, chances are that you have 'eog' installed
+# or put you own there. Unless in the path specify full path to it:
+# node defines the default graphviz node attributes. In customization
+# each key can be an entity type, that you can fully customize using the
+# same mechanism
+
+#:graphviz:
+#  :viewer: eog '%s'
+#  :label: < Repository Entities <br/> >
+#  :labelloc: :t
+#  :show_config: false
+#  :file_type: svg
+#  :graph_type: :digraph
+#  :node:
+#    :shape: box
+#    :style: filled
+#    :fillcolor: grey95
+#  :customizations:
+#    :my_custom_entity:
+#      :shape: circle
+#      :fillcolor: red

data/etc/templates/plugin_definition/lib/{entity}/{entity}_processor.rb.erb

@@ -9,7 +9,6 @@ module <%= plugin_module_name %>
 
     def execute
       puts '<%= main_entry_point.upcase %> PLUGIN WAZ HERE'
-      puts_and_logs config[].to_yaml
     end
 
 

data/etc/templates/project/.ps_project/personal-config.yaml

@@ -2,7 +2,32 @@
 # THIS FILE *IS NOT* MEANT TO BE VERSIONED (and is not by default)
 # You can use it for any configuration you want to keep local
 
+# Common configuration
+
 # :debug: true
-# :log-level: 2
+:log-level: 2
 # :debug-on-stderr: true
-# :verbose: true
+# :verbose: true
+
+# Graphviz configuration
+#
+# If you are under Gnome, chances are that you have 'eog' installed
+# or put you own there. Unless in the path specify full path to it:
+# node defines the default graphviz node attributes. In customization
+# each key can be an entity type, that you can fully customize using the
+# same mechanism
+
+#:graphviz:
+#  :viewer: eog '%s'
+#  :label: < Repository Entities <br/> >
+#  :labelloc: :t
+#  :show_config: false
+#  :file_type: svg
+#  :node:
+#    :shape: box
+#    :style: filled
+#    :fillcolor: grey95
+#  :customizations:
+#    :my_custom_entity:
+#      :shape: circle
+#      :fillcolor: red

data/etc/templates/project/.ps_project/versioned-config.yaml

@@ -3,4 +3,27 @@
 # You can use it for any configuration you want to keep at repository level
 
 # If you want to ensure a minimal version number of PowerStencil
-:min_power_stencil_version: <%= PowerStencil::VERSION %>
+:min_power_stencil_version: <%= PowerStencil::VERSION %>
+
+# Graphviz configuration
+#
+# If you are under Gnome, chances are that you have 'eog' installed
+# or put you own there. Unless in the path specify full path to it:
+# node defines the default graphviz node attributes. In customization
+# each key can be an entity type, that you can fully customize using the
+# same mechanism
+
+#:graphviz:
+#  :viewer: eog '%s'
+#  :label: < Repository Entities <br/> >
+#  :labelloc: :t
+#  :show_config: false
+#  :file_type: svg
+#  :node:
+#    :shape: box
+#    :style: filled
+#    :fillcolor: grey95
+#  :customizations:
+#    :my_custom_entity:
+#      :shape: circle
+#      :fillcolor: red

data/lib/power_stencil.rb

@@ -13,6 +13,7 @@ require 'power_stencil/utils/directory_processor'
 require 'power_stencil/utils/secure_require'
 require 'power_stencil/utils/gem_utils'
 require 'power_stencil/utils/file_edit'
+require 'power_stencil/utils/graphviz'
 
 require 'climatic/script/unimplemented_processor'
 require 'power_stencil/project/proxy'

data/lib/power_stencil/command_processors/get.rb

@@ -7,15 +7,25 @@ module PowerStencil
       include Climatic::Proxy
       include PowerStencil::Project::Proxy
       include PowerStencil::CommandProcessors::EntityHelper
+      include PowerStencil::Utils::Graphviz
 
       def execute
         targets = targets_from_criteria analyse_extra_params, project.engine.root_universe
-        targets.sort{|a, b| a.as_path <=> b.as_path}.each do |target|
-          display_entity target
+        if config[:graph] || config[:'graph-file']
+          filename = graph_entities targets, config[:'graph-file']
+          msg = "Graphviz graph saved into '#{filename}'."
+          logger.info msg
+          puts msg
+          if config[:graphviz][:viewer]
+            cmd = config[:graphviz][:viewer] % [filename]
+            `#{cmd}`
+          end
+        else
+          targets.sort{|a, b| a.as_path <=> b.as_path}.each {|target| display_entity target }
         end
       end
-
     end
 
   end
+
 end

data/lib/power_stencil/dsl/entities.rb

@@ -13,10 +13,36 @@ module PowerStencil
         e.nil? ? entity(type.to_sym, name) : e
       end
 
-      def entity(type, name)
+      def entity(type_or_path, name = nil)
+        type, name = if name.nil?
+                       md = type_or_path.match /^(?<type>[^\/]+)\/(?<name>.*)$/
+                       if md
+                         [md['type'].to_sym, md['name']]
+                       else
+                         raise PowerStencil::Error, "Invalid entity id: '#{type_or_path}'"
+                       end
+                     else
+                       [type_or_path, name]
+                     end
         PowerStencil.project.engine.entity type, name, @universe
       end
 
+      # Need to implement a `replace` method which would rename files before...
+      # def edit_entity(type, name)
+      #   tmp = Object.new
+      #   tmp.extend PowerStencil::Utils::FileEdit
+      #   org = entity(type, name)
+      #   unless org.nil?
+      #     mod = tmp.securely_edit_entity entity(type, name)
+      #     raise PowerStencil::Error "You cannot "
+      #
+      #
+      #     universe = org.universe
+      #     universe.delete org
+      #     universe.add mod
+      #   end
+      # end
+
       def entities(criterion: nil, value: nil, &filter_block)
         PowerStencil.project.engine.entities @universe, criterion: criterion, value: value, &filter_block
       end

data/lib/power_stencil/engine/entities_handling.rb

@@ -45,8 +45,10 @@ module PowerStencil
       def delete_entity(work_universe, type, name, delete_files: false)
         entity_to_delete = work_universe.get_entity type, name
         get_user_confirmation prompt: "Are you sure you want delete '#{[type, name].join '/'}' ?" do
+          work_universe.delete(entity_to_delete).each do |impacted_entity, _|
+            impacted_entity.save raise_error: false, force_save: true
+          end
           entity_to_delete.delete force_files_deletion: delete_files
-          entity_to_delete.universe = nil
           entity_to_delete
         end
       end

data/lib/power_stencil/system_entity_definitions/entity_project_common.rb

@@ -3,8 +3,8 @@ module PowerStencil
 
     module EntityProjectCommon
 
-      def save(uri = source_uri, force_files_generation: false)
-        super(uri)
+        def save(uri = source_uri, raise_error: true, force_save: false, force_files_generation: false )
+        super(source_uri, raise_error: raise_error, force_save: force_save)
         unless PowerStencil.project.entity_type_templates[type].nil?
           PowerStencil.project.generate_entity_dir_for_entity self, force: force_files_generation
         end

data/lib/power_stencil/system_entity_definitions/non_persistent.rb

@@ -3,7 +3,7 @@ module PowerStencil
 
     module NonPersistent
 
-      def save(uri = source_uri)
+      def save
         PowerStencil.logger.debug "Won't save '#{self.class.to_s}' because defined as non persistent"
         self
       end

data/lib/power_stencil/system_entity_definitions/simple_exec.rb

@@ -26,10 +26,10 @@ module PowerStencil
         super(raise_error: raise_error)
       end
 
-      def save(uri = source_uri, force_files_generation: false)
-        valid?
+      def save(uri = source_uri, raise_error: true, force_save: false, force_files_generation: false )
+        valid? raise_error: raise_error
         self.post_process.save
-        super(uri, force_files_generation: force_files_generation)
+        super
       end
 
       def delete(force_files_deletion: false)

data/lib/power_stencil/utils/file_edit.rb

@@ -25,7 +25,7 @@ module PowerStencil
       def securely_edit_entity(entity, &modifications_validation_block)
         initial_uri = entity.source_uri
         modified_entity = nil
-        Tempfile.create([entity.type.to_s, entity.name.to_s]) do |tmpfile|
+        Tempfile.create(["#{entity.type.to_s}_#{entity.name.to_s}", '.yaml']) do |tmpfile|
           tmpfile.puts entity.to_yaml
           tmpfile.flush
           securely_edit_file(tmpfile, &modifications_validation_block)

data/lib/power_stencil/utils/graphviz.rb

@@ -0,0 +1,61 @@
+module PowerStencil
+  module Utils
+
+    module Graphviz
+
+      include UniverseCompiler::Utils::Graphviz
+
+      def graph_entities(entities, filename = nil)
+        entities_to_process = unless config[:graphviz][:show_config]
+                                entities.reject {|e| e.type == :project_config}
+                              else
+                                entities
+                              end
+
+        graph_options = {
+            output_file_name: filename,
+            graph_type:       config[:graphviz][:graph_type],
+            file_type:        config[:graphviz][:file_type]
+        }
+
+        graph_entities_to_file entities_to_process, graph_options do |graph, cache|
+          graph[:label] = config[:graphviz][:label]
+          graph[:labelloc] = config[:graphviz][:labelloc]
+          graph.each_node do |node_name|
+            node = graph.get_node node_name
+            entity = cache[:by_node][node]
+
+            # Set default node attributes
+            config[:graphviz][:node].each do |k,v|
+              node[k] = v
+            end
+            fields_to_display = {}
+
+            # Define node tooltip
+            entity.fields.keys.each do |field_name|
+              constraints = entity.class.fields_constraints[field_name]
+              unless constraints.nil?
+                # Remove relations as they are represented as edges
+                next if constraints.keys.include? :has_one
+                next if constraints.keys.include? :has_many
+              end
+              fields_to_display[field_name] = entity[field_name]
+            end
+            node[:tooltip] = fields_to_display.to_yaml
+
+            # specific customizations
+            if config[:graphviz][:customizations][entity.type]
+              config[:graphviz][:customizations][entity.type].each do |k,v|
+                node[k] = v
+              end
+            end
+          end
+        end
+
+      end
+
+
+    end
+
+  end
+end

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.3.9'.freeze
+  VERSION = '0.4.4'.freeze
 end

data/power_stencil.gemspec

@@ -25,9 +25,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
-  spec.add_dependency 'climatic', '~> 0.2', '>= 0.2.28'
+  spec.add_dependency 'climatic', '~> 0.2.29'
   spec.add_dependency 'dir_glob_ignore', '~> 0.3'
-  spec.add_dependency 'universe_compiler', '~> 0.2', '>= 0.2.16'
+  spec.add_dependency 'universe_compiler', '~> 0.4.1'
   spec.add_dependency 'pry'
 
   spec.post_install_message = %Q{

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.4.4
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-13 00:00:00.000000000 Z
+date: 2019-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -58,20 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.28
+        version: 0.2.29
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.28
+        version: 0.2.29
 - !ruby/object:Gem::Dependency
   name: dir_glob_ignore
   requirement: !ruby/object:Gem::Requirement
@@ -92,20 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.16
+        version: 0.4.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.2.16
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -256,6 +244,7 @@ files:
 - lib/power_stencil/utils/file_edit.rb
 - lib/power_stencil/utils/file_helper.rb
 - lib/power_stencil/utils/gem_utils.rb
+- lib/power_stencil/utils/graphviz.rb
 - lib/power_stencil/utils/secure_require.rb
 - lib/power_stencil/utils/semantic_version.rb
 - lib/power_stencil/version.rb
@@ -264,7 +253,7 @@ homepage: https://gitlab.com/tools4devops/power_stencil
 licenses:
 - MIT
 metadata: {}
-post_install_message: "\nThank you for installing PowerStencil 0.3.9 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.4.4 !\nFrom the command
   line you can run `power_stencil --help`\nIf your shell is not completing the command:\n
   \ If you use rbenv: `rbenv rehash`\n  If you use zsh  : `rehash`\n\nFull documentation
   here   : https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel