power_stencil 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1387471841811025d2ebdc21c23aec26f9341193
-  data.tar.gz: ff9722780a689f245baa21c3dbf5b5bef0a1024d
+  metadata.gz: 9852320333b0476c1e74b31ea327946e3a6d94b9
+  data.tar.gz: 44de44adfb97d695d8f1e7311566cea9b4ae47a9
 SHA512:
-  metadata.gz: df95d43e7e99fd25fe57bbb3713fc5707b53a2f939c9734720cbcd9bca4f7d8dfaff61294db2e8e245b768ff93c737aa1b6e14da9f64cb7fe07f234f8061ec16
-  data.tar.gz: 24ba3ea0b87f0dd480250b5a4b32e6c8e1730396d6e0b43820f10d97bb1084f405df74a3fd9dcfec7aa96a813014427163aebbf1e15a112b9d72bf9f9188b45a
+  metadata.gz: d867a9e2efa622ecce40dac7446309a1164c1a8b2750855ef4217708e519984c31698a1c567090d5defe630045c056397f9083ebbdfd15b698acdf4a295063b5
+  data.tar.gz: fc06c6240c6d8f60a4eabe4f0c1a7fc3cb83a9d72c5e2ed7878296466637f8fa03519994f8ec66222f7a4d838e38081f15ab2a593d965be583900fed7a5f59aa

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

@@ -5,7 +5,7 @@ PowerStencil
 
 <!-- TOC -->
 
-- [Core concepts](#core-concepts)
+- [Overview](#overview)
 - [Pfff, yet another templating engine...](#pfff-yet-another-templating-engine)
 - [Installation](#installation)
 - [Usage](#usage)
@@ -13,36 +13,37 @@ 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)
 
 <!-- /TOC -->
 
-# Core concepts
+# Overview
 
 `PowerStencil` proposes a radical approach on how to manage your shared configuration.
 
-Internally `PowerStencil` is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization:
+**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.
 
-![simple-flow-image]
+From a very high level point of view, the workfow `PowerStencil` proposes looks like:
 
-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.
+![simple-flow-image]
 
 `PowerStencil` provides **development and operations friendly workflows to fully manage the maintenance of a complex shared config** in order to generate anything you may want like _documentation_, _static sites_, _code_, _configuration_ for multiple tools..., while **avoiding duplication, and manage it like code** !
 
-It is a common pattern to introduce a database to manage this configuration, and it is a very bad idea because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will __integrate smoothly within your existing development and operations workflows__, builds, CI/CD, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
+It is a common pattern to introduce a database to manage shared configuration for CI/CD processes, and it is a very bad idea (see [F.A.Q.]) because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will integrate smoothly within your existing development and operations workflows, builds, CI/CD processes, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
 
-**With `PowerStencil` everything is maintained in a git repository**: data, templates, specific code. No more config loss, no more change applied without a full lineage.
+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.
 
-See some real world [example use cases].
+**: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:
 
-- CRUD [entities] using either an editor or a dedicated REPL
-- Manage [templates]
-- Manage [builds]
-- Create and manipulate [plugins]
+- Manage the project data
+- Manage templates
+- Manage builds
+- Create and manipulate plugins
 
 # Pfff, yet another templating engine...
 
@@ -110,17 +111,19 @@ The program uses the standard paradigm of sub-commands (à-la-git), and each can
 
 To create a new project, use the `init` sub-command. It works as you would expect. If you run it in an existing directory it will create the project here but you can specify the directory where you want the project to be created (the path will be created provided you have the rights on the filesystem):
 
-    $ power_stencil init --project-path /where/you/want
+    $ power_stencil init /where/you/want/your/project
 
-The `--project-path` option can be applied to any sub-command, but à-la-git, once the project created if you are anywhere within the project tree, you don't need to specify the project path.
+Once the project created, if you are anywhere within the project tree, you don't need to specify the project path anymore (if needed, any `power_stencil` sub-command supports a `--project-path` option). If you're used to the Git command line, it works the same way, and you should not feel in uncharted territory...
 
 :information_source: The rest of this documentation will assume you are at the root of this created project.
 
-:information_source: Of course, once you created a new project you should version it with Git:
+**:information_source: Of course, once you've been creating a new project, you should version it with Git:**
 
     $ git init
+    $ git add .
     $ git commit -a -m 'Initial commit'
 
+This will allow you to track any change resulting of your interactions with `power_stencil` command line.
 
 ## `PowerStencil` project structure
 
@@ -141,9 +144,9 @@ The structure of a brand new `PowerStencil` project is the following:
     │   └── README.md
     └── versioned-config.yaml
 ```
-New directories will appear once you start some [builds] or when you will define [templates].
+New directories will appear once you start some [builds] or when you will define [templates], but this is the initial state.
 
-Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project.
+Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project. It is prefilled so that unless you want to specifically avoid a file to be versioned, you don't need any action regarding `PowerStencil` project files.
 
 The project has two distinct config files. Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest will be versioned. But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml` which is not be versioned. The content defined in the latter overrides the content of the official one. This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.
 
@@ -155,19 +158,28 @@ The `plugins` directory can optionally contain project specific plugins. Plugins
 
 The core of the system is the `entity`, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
 
-:arrow_forward: [Entities]
+> :arrow_forward: [Entities]
 
 Then it is important to understand how to use entities within `templates`. Templates are the way to generate something (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
 
-:arrow_forward: [Templates]
+> :arrow_forward: [Templates]
 
 The mechanism that combines entities and templates is called a `build`. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
 
-:arrow_forward: [Builds]
+> :arrow_forward: [Builds]
 
 `PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. `Plugins` provide a way to completely extend `PowerStencil`, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
 
-:arrow_forward: [Plugins]
+> :arrow_forward: [Plugins]
+
+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
 
@@ -189,6 +201,8 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [builds]: doc/builds.md "Builds in PowerStencil"
 [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 -->
@@ -201,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/builds.md

@@ -255,7 +255,7 @@ If you want to do something more custom after the build process completed, this
 [entities]: entities.md "Entities in PowerStencil"
 [templates]: templates.md "Templates in PowerStencil"
 [plugins]: plugins.md "Plugins in PowerStencil"
-[buildable]: entities.md#buildable--buildable_by "How to make an entity buildable ?"
+[buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
 [local entities]: entities.md#local-unversioned-entities "Local unversioned entities"
 
 <!-- Code links -->

data/doc/entities.md

@@ -33,7 +33,7 @@ Entities
         - [not_empty](#not_empty)
         - [should_match](#should_match)
         - [class_name](#class_name)
-        - [buildable / buildable_by](#buildable--buildable_by)
+        - [buildable and buildable_by](#buildable-and-buildable_by)
     - [Module you could include in your entity types](#module-you-could-include-in-your-entity-types)
     - [Adding functional code](#adding-functional-code)
 
@@ -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
 
@@ -908,7 +913,7 @@ PowerStencil DSL> e.valid? raise_error: true
 
 :warning: Use this one with caution, as it does not test anything regarding inheritance...
 
-### buildable / buildable_by
+### buildable and buildable_by
 
 One of the most important directives !
 More information is provided in the [builds] documentation, but basically this defines an `entity_type` as a potential target for the build process.
@@ -963,4 +968,5 @@ 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 !"
+[Graphviz]: (https://www.graphviz.org/) "Graph Visualization Software"

data/doc/faq.md

@@ -0,0 +1,106 @@
+F.A.Q.
+======
+
+<!-- TOC -->
+
+- [How does `PowerStencil` compare with a CMDB ?](#how-does-powerstencil-compare-with-a-cmdb-)
+- [Why is a "real" database a bad idea as configuration store for CI/CD ?](#why-is-a-real-database-a-bad-idea-as-configuration-store-for-cicd-)
+- [How does `PowerStencil` compare to environment variables + subst ?](#how-does-powerstencil-compare-to-environment-variables--subst-)
+- [Why data persisted in YAML ?](#why-data-persisted-in-yaml-)
+- [What are the system requirements ?](#what-are-the-system-requirements-)
+- [What is the status of `PowerStencil` ?](#what-is-the-status-of-powerstencil-)
+
+<!-- /TOC -->
+[:back:][Documentation root]
+
+# How does `PowerStencil` compare with a CMDB ?
+
+It could sound like a strange question. `PowerStencil` is absolutelly not designed with ITIL in mind but in the end its true that its data management part looks a lot like a [CMDB].
+
+- [Entities][entities] (and more specifically entity types) can cover most aspects (I am not ITIL expert enough to say it covers all of them) of ITIL's _Configuration Items_. Default entities provided with `PowerStencil` do not contain all necessary attributes to do be really considered as _configuration items_, but it should be very easy to achieve with custom entities. In fact it could be a good idea of [plugin][plugins]...
+- Relation semantics in `PowerStencil` cover 1-1, 1-n and composition relation patterns.
+- Versioning is achieved through Git. Implying on top of versioning, branching, merging
+
+But `PowerStencil` cannot be simplified to it's "database" aspect. It goes well beyond, and is as well a pragmatic workflow for developers and operations to actually do something out of this data. A [CMDB] may be used by external processes in order to achieve what `PowerStencil` does out of the box.
+
+
+# Why is a "real" database a bad idea as configuration store for CI/CD ?
+
+There are some reasons why using a database in the scope of CI/CD is not a good idea.
+
+Basically the CI/CD infrastructure could be built around Jenkins, containerized tools (Drone for example), Travis, GitlabCI... The goal being to provide the **easiest possible way for the developer** to perform integration tests and eventually build and deploy software.
+
+But the easiest possible way for the developer doesn't mean that the underlying infrastructure is simple to put in place or maintain. In fact it is not !
+
+Anything you add to this carefully crafted mechanic could turn into an infrastructure management nightmare. And a database (and its availability, maintenance) is clearly not the simplest component to inject in your infrastructure...
+
+On top of this, a database does not not provide by default all the required features. Versioning is obviously one of them but of course not the only one (you may think about branching or others...). Meaning that **you need to have custom developments** on top of the chosen database in order to achieve all the required features. It immediately becomes a de-facto single point of failure in your CI/CD process...
+
+Relying on Git to achieve the storage, versioning, branching, decentralization is a much easier way to achieve the same. There is no need to have specific developments as any CI/CD mechanism knows how to deal with extra git repository.
+
+# How does `PowerStencil` compare to environment variables + subst ?
+
+If you have very few files/templates, you may consider this as a solution, but as soon as your templates will complexify or some data need to reference some other, you will enter a loop of death that will make you regret your initial choice.
+
+`PowerStencil` is not a templating engine, it is a framework! 
+
+Not only it [allows structured and relational data][entities], it structures your work as well, and provides mechanisms to allow developers to [easily perform tests without committing unwanted changes by mistake][overrides].
+
+Due on how it is easy to use `PowerStencil`, even for the simplest use cases, there is no real reason not to use it.
+
+
+# Why data persisted in YAML ?
+
+Assuming Git is used for storage and versioning **we need to have a data format that is git-friendly**.
+
+- So it discards local databases like SQLite, BerkeleyDB or others which are binary formats.
+- XML is **not** a human readable format and is a real pain to _diff_. It should have been kept for what it has been designed for, ie machine to machine protocols...
+
+So the two main remaining contenders are JSON and YAML. Although there is no real reason to take one more than the other, including the manipulating language, would I have written `PowerStencil` in JS or Go, I may probably have chosen JSON as storage format. But it is written in Ruby and therefore I went for YAML.
+
+
+# What are the system requirements ?
+
+`PowerStencil` has been developed under Linux, but it's only requiring a working Ruby installed on your machine. 
+
+As such, even if I never tested, I would expect it to probably work out of the box on MacOS, BSD or other Unices supporting Ruby 2.2+.
+
+Regarding Windows, I stopped using spywareOS years ago so I can't really tell you. Last time I tried using Ruby on Windows (maybe 10 years ago), I did face a lot of dependency issues. Maybe things are better now, but I have no idea. As far as I understood you can now have an Ubuntu running on top of Windows 10 as a kind of blessed VM. I would probably more go this way...
+
+
+# What is the status of `PowerStencil` ?
+
+Although `PowerStencil` is still under development, **it can already be safely used**.
+
+Regarding `PowerStencil` core:
+
+- The part that may evolve the most is the plugin part (including documentation which is not really in par with the rest...), but it should not break anything developed now.
+- New system entity types may appear. 
+
+Anyway `PowerStencil` follows the semantic versioning pattern and if incompatible changes arise it may be reflected in the version.
+
+There are already some plugins in the pipe, especially around contenerization topics.
+
+:information_source: Of course, `PowerStencil` is new software and it is expected to evolve with the needs of its users...
+
+
+
+
+[:back:][Documentation root]
+<!-- End of Document -->
+
+<!-- Pages -->
+[Documentation root]: ../README.md "Back to documentation root"
+[entities]: entities.md "Entities in PowerStencil"
+[plugins]: plugins.md "Plugins in PowerStencil"
+[overrides]: builds.md#overriding-entities-and-build-scenarii "Overriding data locally"
+
+
+<!-- Code links -->
+
+
+<!-- Illustrations -->
+
+
+<!-- External links -->
+[CMDB]: https://en.wikipedia.org/wiki/Configuration_management_database "Configuration Management Database"

data/doc/templates.md

@@ -317,7 +317,7 @@ Flawless victory !!
 [builds]: builds.md "Builds in PowerStencil"
 [plugins]: plugins.md "Plugins in PowerStencil"
 [example use cases]: example_use_cases.md "Example uses cases using PowerStencil"
-[buildable]: entities.md#buildable--buildable_by "How to make an entity buildable ?"
+[buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
 
 <!-- Code links -->
 

data/etc/base_commands_definition.yml

@@ -125,6 +125,13 @@
       names-only:
         :type: bool
         :summary: Only returns the name of the entities found.
+        :long_aliases:
+          - names
+          - name
+          - short
+        :short_aliases:
+          - n
+          - s
       compiled: &COMPILEDOPT
         :type: bool
         :summary: Entities as used by susbstitution engine.
@@ -141,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,27 @@
 # 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
+#  :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/meta_templates/plugin_seed/psplugin_{entity}.gemspec

@@ -29,8 +29,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'bundler', '~> 2.0.2'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'power_stencil', "~> #{<%= plugin_module_name %>::VERSION}"
+  spec.add_development_dependency 'power_stencil', "~> <%= PowerStencil::VERSION %>"
 end

data/etc/power_stencil.yaml

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

data/etc/templates/plugin_definition/.travis.yml

@@ -1,5 +1,7 @@
+---
 sudo: false
 language: ruby
+cache: bundler
 rvm:
   - 2.3.1
-before_install: gem install bundler -v 1.16.1
+before_install: gem install bundler -v 2.0.2

data/etc/templates/plugin_definition/Gemfile

@@ -1,6 +1,4 @@
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
 # Specify your gem's dependencies in <%= plugin_module_name %>.gemspec
 gemspec

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

@@ -1,4 +1,27 @@
 # 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
+#  :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/plugin_definition/psplugin_{entity}.gemspec

@@ -29,8 +29,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'bundler', '~> 2.0.2'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'power_stencil', "~> #{<%= plugin_module_name %>::VERSION}"
+  spec.add_development_dependency 'power_stencil', "~> <%= PowerStencil::VERSION %>"
 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
 
-# debug
-:debug: false
-# :log-level: 2
-# :debug-on-stderr: true
+# Common configuration
+
+# :debug: true
+:log-level: 2
+# :debug-on-stderr: 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/entity_helper.rb

@@ -12,13 +12,14 @@ module PowerStencil
       def display_entity(entity)
         puts_and_logs "# Entity '#{entity.name}' (#{entity.type})"
         if config[:'names-only']
-          puts "- #{entity.name}"
+          puts "- '#{entity.as_path}' ('#{entity.name}' of the type '#{entity.type}')"
         else
           if config[:raw]
             puts entity.to_yaml
           else
             puts entity.to_hash.to_yaml
           end
+          puts
         end
       end
 

data/lib/power_stencil/command_processors/get.rb

@@ -7,16 +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.each do |target|
-          display_entity target
-          puts
+        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/project/config.rb

@@ -5,9 +5,9 @@ module PowerStencil
 
       include PowerStencil::Project::Paths
 
-      PROJECT_CONFIG_PRIORITY = 2000
-      USER_CONFIG_PRIORITY = 2010
-      PLUGIN_CONFIG_PRIORITY_MIN = 1000
+      PROJECT_CONFIG_PRIORITY = 990
+      USER_CONFIG_PRIORITY = 995
+      PLUGIN_CONFIG_PRIORITY_MIN = 100
 
       attr_reader :plugin_priority_count
 
@@ -16,6 +16,8 @@ module PowerStencil
         # Optional config files should have less priority than the command line layer
         add_optional_config_layer project_versioned_config_file, 'versioned project config file', PROJECT_CONFIG_PRIORITY
         add_optional_config_layer project_personal_config_file, 'personal project config file', USER_CONFIG_PRIORITY
+        Climatic.send :setup_logger
+        logger.debug 'Project config files loaded'
       end
 
 

data/lib/power_stencil/system_entity_definitions/entity_project_common.rb

@@ -27,6 +27,20 @@ module PowerStencil
         self.class.buildable?
       end
 
+      protected
+
+      def project_engine
+        PowerStencil.project.engine
+      end
+
+      def create_universe_entity(type, fields = {})
+        project_engine.new_entity project_engine.root_universe, type, fields: fields
+      end
+
+      def remove_entity_from_universe(entity)
+        project_engine.root_universe.delete entity
+      end
+
     end
 
   end

data/lib/power_stencil/utils/graphviz.rb

@@ -0,0 +1,56 @@
+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_entities_to_file entities_to_process,
+                               output_file_name: filename,
+                               file_type: config[:graphviz][:file_type] 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.5'.freeze
+  VERSION = '0.4.0'.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.26'
+  spec.add_dependency 'climatic', '~> 0.2', '>= 0.2.29'
   spec.add_dependency 'dir_glob_ignore', '~> 0.3'
-  spec.add_dependency 'universe_compiler', '~> 0.2', '>= 0.2.11'
+  spec.add_dependency 'universe_compiler', '~> 0.3.0', '>= 0.3.2'
   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.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-31 00:00:00.000000000 Z
+date: 2019-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -61,7 +61,7 @@ dependencies:
         version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.26
+        version: 0.2.29
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -71,7 +71,7 @@ dependencies:
         version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.26
+        version: 0.2.29
 - !ruby/object:Gem::Dependency
   name: dir_glob_ignore
   requirement: !ruby/object:Gem::Requirement
@@ -92,20 +92,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 0.3.0
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.11
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 0.3.0
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.11
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +143,7 @@ files:
 - doc/builds.md
 - doc/entities.md
 - doc/example_use_cases.md
+- doc/faq.md
 - doc/images/power-stencil-entity-build.svg
 - doc/images/power-stencil-entity-creation.svg
 - doc/images/power-stencil-simple-flow.svg
@@ -255,6 +256,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
@@ -263,7 +265,7 @@ homepage: https://gitlab.com/tools4devops/power_stencil
 licenses:
 - MIT
 metadata: {}
-post_install_message: "\nThank you for installing PowerStencil 0.3.5 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.4.0 !\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