jekyll-sheafy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3388e74b27cfab3e3fbdd846805e3c03c5326a7e91a30e6d1eb807f9d5619212
-  data.tar.gz: 0c9299c8e5cf165f0b8c84a66b5f7d9b51680c4b00453d999367aa5ea4d914b5
+  metadata.gz: 8ec5d4f41ee3fca018fca579929acf04ad876ff525de337d6e385e8949226f62
+  data.tar.gz: 3e3feffb64ce77917d63fc53506bed3310b1dc3d4f52f0dd7dd66ba615f14e74
 SHA512:
-  metadata.gz: b1b71ad0af49028612d9e60fe0544e13d941dfae46e81e135023da8f7004baeceff1b7d32571ffe05e0008a1d026446d2bc036ec653fc7b703ad432751e05322
-  data.tar.gz: 7b42013f49e76759e2fb80e5477bb562c28d9ebc88815afca2afe4c72968050c28163f2f9abe5b9002ac74d8a14e97947f455200cb350789816a79a45e553637
+  metadata.gz: 25b689459a2f27e2399463f31a24220b76875ea97e0f37c533ae975ed1c43f0b6369618c959bcb6502062565c61bf9b1b1ddb5b803bc2207ad08251ade16126f
+  data.tar.gz: 1d0d6d01edf37590ec5b41529eddca5778743cbe3c899bd44ca6630ebe15b7fdf5a1f4b082caa534e1b64e733fb343721fc14093572092dfe7a490768c5e3983

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2022-02-01
+
+### Added
+
+- `inheritable` config key (array of strings, validated) to define attributes which are inherited from parent node.
+- `referents` variable containing list of referents (i.e. the targets of all references in the current node).
+- `root` variable containing the root node of the tree the current node belongs to.
+- `predecessors`/`successors` variables containing the siblings preceeding/following the current node.
+
+### Changed
+
+- Error message are a bit more rational.
+- `taxa` configuration key is now validated; it must be an hash valued in hashes.
+- `references.matchers` configuration key is now validated; it must be an array of regexps containing a single named capture "slug".
+
 ## [0.2.0] - 2022-01-29
 
 ### Added
@@ -20,5 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Structure to represent directed graphs.
 - Topological checks for rooted forests.
 
-[unreleased]: https://github.com/paolobrasolin/jekyll-sheafy/compare/0.1.0...HEAD
+[unreleased]: https://github.com/paolobrasolin/jekyll-sheafy/compare/0.3.0...HEAD
+[0.3.0]: https://github.com/paolobrasolin/jekyll-sheafy/compare/0.2.0...0.3.0
+[0.2.0]: https://github.com/paolobrasolin/jekyll-sheafy/compare/0.1.0...0.2.0
 [0.1.0]: https://github.com/paolobrasolin/jekyll-sheafy/releases/tag/0.1.0

data/README.md

@@ -40,6 +40,7 @@ sheafy:
   references:
     matchers: [] # ...
   taxa: {} # ...
+  inheritable: [] # ...
 ```
 
 ### Node variables
@@ -57,14 +58,18 @@ sheafy:
 
 #### Dependencies
 
+- `root`
 - `ancestors`
 - `parent`
 - `subroot`
 - `children`
+- `predecessors`
+- `successors`
 
 #### References
 
 - `referrers`
+- `referents`
 
 #### Numbering
 
@@ -75,11 +80,6 @@ sheafy:
 
 These are the features you can expect in the future:
 
-- Enable `referents` variable w/ nodes references by the current one
-- `root` variable w/ root node of the tree
-- `siblings` variable or some variant of it to enable navigation between adjacent nodes at the same depth
-- Prev/next node navigation
-- Variable inheritance from parent/root node
 - Search feature
 
 Of course any feedback is welcome!

data/lib/jekyll/sheafy/dependencies.rb

@@ -4,9 +4,10 @@ module Jekyll
   module Sheafy
     module Dependencies
       RE_INCLUDE_TAG = /^@include{(?<slug>.+?)}$/
-      SUBLAYOUT_KEY = "sublayout"
-      SUBLAYOUT_DEFAULT_VALUE = "sheafy/node/default"
-      SUBROOT_KEY = "subroot"
+
+      class Error < TemplateError; end
+
+      InvalidConfig = Error.build("Invalid config: %s is not an %s.")
 
       def self.process(nodes)
         adjacency_list = build_adjacency_list(nodes)
@@ -26,6 +27,7 @@ module Jekyll
           attribute_ancestors!(node)
           attribute_depth!(node)
           attribute_clicks!(node)
+          attribute_inheritable!(node)
         end
 
         # NOTE: this pass is separate to have data available in layouts.
@@ -34,6 +36,8 @@ module Jekyll
         end
       end
 
+      #==[ Graph building ]=====================================================
+
       def self.scan_includes(node)
         node.content.scan(RE_INCLUDE_TAG).flatten
       end
@@ -42,16 +46,31 @@ module Jekyll
         nodes_index.transform_values(&method(:scan_includes))
       end
 
+      def self.build_rooted_forest!(adjacency_list)
+        Sheafy::DirectedGraph[adjacency_list].
+          tap(&:ensure_rooted_forest!)
+      rescue Jekyll::Sheafy::DirectedGraph::Error => error
+        raise StandardError.new(<<~MESSAGE)
+                Sheafy processing error! The nodes dependency graph MUST be a directed rooted forest. #{error.message}
+              MESSAGE
+      end
+
       def self.denormalize_adjacency_list!(list, index)
         # TODO: handle missing nodes
         list.transform_keys!(&index)
         list.values.each { |children| children.map!(&index) }
       end
 
+      #==[ Data generation ]====================================================
+
       def self.attribute_neighbors!(list)
         list.each do |parent, children|
           parent.data["children"] = children
-          children.each { |child| child.data["parent"] ||= parent }
+          children.each_with_index do |child, index|
+            child.data["parent"] ||= parent
+            child.data["predecessors"] = children.take(index)
+            child.data["successors"] = children.drop(index.succ)
+          end
         end
       end
 
@@ -62,6 +81,7 @@ module Jekyll
           ancestors = [*parent.data["ancestors"], parent]
           node.data["ancestors"] = ancestors
         end
+        node.data["root"] = parent&.data&.[]("root") || node
       end
 
       def self.attribute_depth!(node)
@@ -73,8 +93,8 @@ module Jekyll
         node.data["clicks"] ||= [
           { "clicker" => node.data["clicker"], "value" => 0 },
         ]
-        node.data["children"].
-          group_by { |child| child.data["clicker"] }.
+        node.data["children"]&.
+          group_by { |child| child.data["clicker"] }&.
           each do |clicker, children|
           children.each_with_index do |child, index|
             clicks = node.data["clicks"].dup
@@ -84,22 +104,22 @@ module Jekyll
         end
       end
 
-      def self.build_rooted_forest!(adjacency_list)
-        Sheafy::DirectedGraph[adjacency_list].
-          tap(&:ensure_rooted_forest!)
-      rescue Sheafy::DirectedGraph::PayloadError => error
-        message = case error
-          when Sheafy::DirectedGraph::MultipleEdgesError then "node reuse"
-          when Sheafy::DirectedGraph::LoopsError then "self reference"
-          when Sheafy::DirectedGraph::CyclesError then "cyclic reference"
-          when Sheafy::DirectedGraph::IndegreeError then "node reuse"
-          else raise StandardError.new("Malformed dependency graph!")
-          end
-        raise StandardError.new(<<~MESSAGE)
-                Error in dependency graph topology, #{message} detected: #{error.payload}
-              MESSAGE
+      INHERITABLE_PATH = ["sheafy", "inheritable"]
+
+      def self.attribute_inheritable!(node)
+        inheritable = node.site.config.dig(*INHERITABLE_PATH) || []
+        return unless (parent = node.data["parent"])
+        inherited = parent.data.slice(*inheritable)
+        # TODO: how/when do we need to clone/dup here?
+        node.data.merge!(**inherited) { |key, left, right| left }
       end
 
+      #==[ Layout flattening ]==================================================
+
+      SUBLAYOUT_KEY = "sublayout"
+      SUBLAYOUT_DEFAULT_VALUE = "sheafy/node/default"
+      SUBROOT_KEY = "subroot"
+
       def self.apply_sublayout(resource, content, subroot)
         sublayout = resource.data.fetch(SUBLAYOUT_KEY, SUBLAYOUT_DEFAULT_VALUE)
         # NOTE: all this mess is just to adhere to Jekyll's internals
@@ -133,6 +153,21 @@ module Jekyll
         end
         apply_sublayout(resource, content, subroot)
       end
+
+      #==[ Config validation ]==================================================
+
+      def self.validate_config!(config)
+        case (inheritables = config.dig(*INHERITABLE_PATH))
+        when nil
+        when Array
+          inheritables.each_with_index do |inheritable, index|
+            next if inheritable.is_a?(String)
+            raise InvalidConfig.new([*INHERITABLE_PATH, index].join("."), "string")
+          end
+        else
+          raise InvalidConfig.new(INHERITABLE_PATH.join("."), "array")
+        end
+      end
     end
   end
 end

data/lib/jekyll/sheafy/directed_graph.rb

@@ -1,23 +1,17 @@
 require "tsort"
+require "jekyll/sheafy/template_error"
 
 module Jekyll
   module Sheafy
     class DirectedGraph < Hash
-      class PayloadError < StandardError
-        attr_reader :payload
+      class Error < TemplateError; end
 
-        def initialize(payload)
-          @payload = payload
-          super
-        end
-      end
-
-      class MissingKeysError < PayloadError; end
-      class InvalidValuesError < PayloadError; end
-      class MultipleEdgesError < PayloadError; end
-      class LoopsError < PayloadError; end
-      class CyclesError < PayloadError; end
-      class IndegreeError < PayloadError; end
+      MissingKeysError = Error.build("Missing keys detected: %s.")
+      InvalidValuesError = Error.build("Invalid values detected: %s.")
+      MultipleEdgesError = Error.build("Parallel edges detected: %s.")
+      LoopsError = Error.build("Loops detected: %s.")
+      CyclesError = Error.build("Cycles detected: %s.")
+      IndegreeError = Error.build("Nodes with indegree > 1 detected: %s.")
 
       def ensure_rooted_forest!
         ensure_valid!

data/lib/jekyll/sheafy/references.rb

@@ -1,47 +1,37 @@
 require "safe_yaml"
+require "jekyll/sheafy/template_error"
+
 # NOTE: allows for rexexp entries in mathers array in config
 SafeYAML::OPTIONS[:whitelisted_tags].push("!ruby/regexp")
 
 module Jekyll
   module Sheafy
     module References
-      class Error < StandardError; end
-      class InvalidMatcher < Error; end
-
-      CONFIG_KEY = "references"
-      DEFAULT_CONFIG = {
-        "matchers" => [
-          /{%\s*ref (?<slug>.+?)\s*%}/,
-        ],
-      }
-      @@config = DEFAULT_CONFIG
+      MATCHERS_PATH = ["sheafy", "references", "matchers"]
+      DEFAULT_MATCHERS = [
+        /{%\s*ref (?<slug>.+?)\s*%}/,
+      ]
+      SLUG_CAPTURE_NAME = "slug"
       REFERRERS_KEY = "referrers"
+      REFERENTS_KEY = "referents"
 
-      def self.validate_matcher!(matcher)
-        return if matcher.names.include?("slug")
-        raise InvalidMatcher.new(<<~ERROR)
-                Sheafy configuration error: the matcher #{matcher} is missing a capturing group named "slug".
-              ERROR
-      end
+      class Error < TemplateError; end
 
-      def self.load_config(config)
-        overrides = config.fetch(CONFIG_KEY, {})
-        overrides["matchers"]&.each(&method(:validate_matcher!))
-        @@config = Jekyll::Utils.deep_merge_hashes(DEFAULT_CONFIG, overrides)
-      end
+      InvalidMatcher = Error.build("Invalid reference matcher: %s should have one capture group named '#{SLUG_CAPTURE_NAME}'.")
 
-      def self.process(nodes_index, config = {})
-        load_config(config)
+      def self.process(nodes_index)
         adjacency_list = build_adjacency_list(nodes_index)
         denormalize_adjacency_list!(adjacency_list, nodes_index)
-        # NOTE: topology is arbitrary so no single pass technique is possible.
-        nodes_index.values.each { |node| node.data[REFERRERS_KEY] = [] }
         attribute_neighbors!(adjacency_list)
       end
 
+      #==[ Graph building ]=====================================================
+
       def self.scan_references(node)
-        @@config["matchers"].flat_map do |matcher|
-          node.content.scan(matcher).flatten
+        matchers = node.site.config.dig(*MATCHERS_PATH) || DEFAULT_MATCHERS
+        matchers.flat_map do |matcher|
+          index = matcher.named_captures.fetch(SLUG_CAPTURE_NAME).fetch(0).pred
+          node.content.scan(matcher).map { |captures| captures.fetch(index) }
         end
       end
 
@@ -55,16 +45,31 @@ module Jekyll
         list.values.each { |children| children.map!(&index) }
       end
 
+      #==[ Data generation ]====================================================
+
       def self.attribute_neighbors!(list)
+        # NOTE: topology is arbitrary so no single pass technique is possible.
+        list.keys.each { |node| node.data[REFERRERS_KEY] = [] }
         list.each do |referrer, referents|
-          # TODO: can referents be useful?
-          # referrer.data["referents"] = referents.uniq
+          referrer.data[REFERENTS_KEY] = referents.uniq
           referents.each do |referent|
             next if referent.data[REFERRERS_KEY].include?(referrer)
             referent.data[REFERRERS_KEY] << referrer
           end
         end
       end
+
+      #==[ Config validation ]==================================================
+
+      def self.validate_config!(config)
+        config.dig(*MATCHERS_PATH)&.each(&method(:validate_matcher!))
+      end
+
+      def self.validate_matcher!(matcher)
+        valid = matcher.named_captures.key?(SLUG_CAPTURE_NAME)
+        valid &&= matcher.named_captures.fetch(SLUG_CAPTURE_NAME).one?
+        raise InvalidMatcher.new(matcher) unless valid
+      end
     end
   end
 end

data/lib/jekyll/sheafy/taxa.rb

@@ -1,18 +1,39 @@
+require "jekyll/sheafy/template_error"
+
 module Jekyll
   module Sheafy
     module Taxa
+      TAXA_PATH = ["sheafy", "taxa"]
       TAXON_KEY = "taxon"
 
+      class Error < TemplateError; end
+
+      InvalidTaxon = Error.build("Invalid taxon: %s should be an hash.")
+
       def self.process(nodes_index)
         nodes_index.values.each(&method(:apply_taxon!))
       end
 
+      #==[ Data generation ]====================================================
+
       def self.apply_taxon!(node)
         taxon_name = node.data[TAXON_KEY]
-        taxon_data = node.site.config.dig("sheafy", "taxa", taxon_name) || {}
+        taxon_data = node.site.config.dig(*TAXA_PATH, taxon_name) || {}
         # TODO: emit warning on undefined taxon
         node.data.merge!(taxon_data) { |key, left, right| left }
       end
+
+      #==[ Config validation ]==================================================
+
+      def self.validate_config!(config)
+        config.dig(*TAXA_PATH)&.each_pair do |taxon_key, taxon_value|
+          validate_taxon!(taxon_key, taxon_value)
+        end
+      end
+
+      def self.validate_taxon!(taxon_key, taxon_value)
+        raise InvalidTaxon.new(taxon_key) unless taxon_value.is_a?(Hash)
+      end
     end
   end
 end

data/lib/jekyll/sheafy/template_error.rb

@@ -0,0 +1,25 @@
+module Jekyll
+  module Sheafy
+    # NOTE: be careful in wielding magick!
+    class TemplateError < StandardError
+      attr_reader :payload
+
+      def initialize(*payload)
+        @payload = payload
+      end
+
+      def to_s
+        self.class.instance_variable_get(:@template) % payload
+      end
+
+      def self.build(template)
+        raise ArgumentError.new(<<~MESSAGE) unless template.is_a?(String)
+          wrong type of argument (given #{template.class}, expected String)
+        MESSAGE
+        Class.new(self) do
+          @template = template
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/sheafy/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module Sheafy
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/jekyll/sheafy.rb

@@ -2,17 +2,25 @@ require "jekyll"
 require "jekyll/sheafy/dependencies"
 require "jekyll/sheafy/references"
 require "jekyll/sheafy/taxa"
+require "jekyll/sheafy/template_error"
 require "jekyll/sheafy/version"
 
 module Jekyll
   module Sheafy
-    CONFIG_KEY = "sheafy"
+    def self.validate_config!(site)
+      Jekyll::Sheafy::Taxa.validate_config!(site.config)
+      Jekyll::Sheafy::References.validate_config!(site.config)
+      Jekyll::Sheafy::Dependencies.validate_config!(site.config)
+    rescue Jekyll::Sheafy::TemplateError => error
+      raise StandardError.new(<<~MESSAGE)
+              Sheafy configuration error! #{error.message}
+            MESSAGE
+    end
 
     def self.process(site)
-      config = site.config.fetch(CONFIG_KEY, {})
       nodes_index = build_nodes_index(site)
       Jekyll::Sheafy::Taxa.process(nodes_index)
-      Jekyll::Sheafy::References.process(nodes_index, config)
+      Jekyll::Sheafy::References.process(nodes_index)
       Jekyll::Sheafy::Dependencies.process(nodes_index)
     end
 
@@ -24,6 +32,10 @@ module Jekyll
   end
 end
 
+Jekyll::Hooks.register :site, :after_init do |site|
+  Jekyll::Sheafy::validate_config!(site)
+end
+
 Jekyll::Hooks.register :site, :post_read, priority: 30 do |site|
   Jekyll::Sheafy.process(site)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-sheafy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Paolo Brasolin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-29 00:00:00.000000000 Z
+date: 2022-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -44,6 +44,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.7.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.7.3
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.18.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.18.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -72,6 +100,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -103,6 +145,7 @@ files:
 - lib/jekyll/sheafy/directed_graph.rb
 - lib/jekyll/sheafy/references.rb
 - lib/jekyll/sheafy/taxa.rb
+- lib/jekyll/sheafy/template_error.rb
 - lib/jekyll/sheafy/version.rb
 homepage: https://github.com/paolobrasolin/jekyll-sheafy
 licenses:
@@ -128,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Brew your own Stacks Project with Jekyll!