gran 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 565f612153803ad8451b299b172a4880bd9f98149c279773344a5e56043ea3ec
+  data.tar.gz: 027ff3712bde1dae0fa350fb2842efba6a4e120194d29823345629109b7fb9bb
+SHA512:
+  metadata.gz: 813be36fdbb481c4d18ef6c9677865ae15d9c8c17296a841ccbda231ee293c99ac2115b7637900cd55f9244db01b479ded46b405461e0f4d78d7b29e9b7594bd
+  data.tar.gz: 732312e0d45347ecb4bd9893a84f67d50be0a39567607b6176ed4cf337204430bc0a0dd184d7efb4789fdfe8bc49a183ee16a54abdbb4b9f1dfef3e210312557

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-09-29
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at anders.rillbert@kutso.se. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,18 @@
+source "https://rubygems.org"
+
+# Use the gemspec for all runtime dependencies and other
+# metadata on the gem
+gemspec
+
+group :development, :test do
+  gem "logging", "~> 2.4"
+  gem "yard", "~> 0.9"
+  gem "ruby-lsp", "~> 0.18"
+  gem "standard", "~> 1.0"
+  gem "rake", "~> 13.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "minitest-hooks", "~> 1.5"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Anders Rillbert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,37 @@
+# Gran
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/gran`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add gran
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install gran
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/gran. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/gran/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Gran project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/gran/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+# Bundler.require(:test, :development)
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/gran/loggable.rb

@@ -0,0 +1,25 @@
+module Gran
+  module Loggable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def logger
+        @logger ||= Gran.logger
+      end
+
+      def logger=(logger)
+        @logger = logger
+      end
+    end
+
+    def logger
+      @logger ||= self.class.logger
+    end
+
+    def logger=(logger)
+      @logger = logger
+    end
+  end
+end

data/lib/gran/pathtree.rb

@@ -0,0 +1,556 @@
+require "pathname"
+require "set"
+require_relative "loggable"
+
+module Gran
+  #
+  # Provides a tree structure where each node is the basename of either
+  # a directory or a file. The pathname of a node is the concatenation of
+  # all basenames from the root node to the node in question, given as a
+  # Pathname object.
+  #
+  # Each node must have a unique pathname within the tree it is part of.
+  #
+  # A node can contain an associated 'data' object.
+  #
+  # The following paths:
+  # basedir/file_1
+  # basedir/file_2
+  # basedir/dir1/file_3
+  # basedir/dir1/file_4
+  # basedir/dir2/dir3/file_5
+  #
+  # are thus represented by the following path tree:
+  #
+  # basedir
+  #   file_1
+  #   file_2
+  #   dir1
+  #     file_3
+  #     file_4
+  #   dir2
+  #     dir3
+  #       file_5
+  #
+  # == Tree info
+  # see https://www.geeksforgeeks.org/tree-traversals-inorder-preorder-and-postorder/
+  #
+  class PathTree
+    include Loggable
+
+    attr_reader :data, :name, :children, :parent, :abs_root
+    attr_writer :parent, :data
+
+    def initialize(path, data = nil, parent = nil)
+      p = clean(path)
+      raise ArgumentError, "Can not instantiate node with path == '.'" if p.to_s == "."
+      raise ArgumentError, "Trying to create a non-root node using an absolute path" if p.absolute? && !parent.nil?
+
+      head = p.descend.first
+
+      @name = head
+      @children = []
+      @data = nil
+      @parent = parent
+
+      tail = p.relative_path_from(head)
+      if tail.to_s == "."
+        @data = data
+        return
+      end
+
+      add_descendants(tail, data)
+    end
+
+    # duplicate this node and all its children but keep the same data references
+    # as the originial nodes.
+    #
+    # parent:: the parent node of the copy, default = nil (the copy
+    # is a root node)
+    # returns:: a copy of this node and all its descendents. The copy will
+    # share any 'data' references with the original.
+    def dup(parent: nil)
+      d = PathTree.new(@name.dup, @data, parent)
+
+      @children.each { |c| d.children << c.dup(parent: d) }
+      d
+    end
+
+    def name=(name)
+      name = Pathname.new(name)
+
+      if !parent.nil? && @parent.children.any? { |c| c.name == name }
+        raise ArgumentError, "Can not rename to #{name}. An existing node already use that name"
+      end
+
+      @name = name
+    end
+
+    # return:: a String with the path segment for this node
+    def segment
+      @name.to_s
+    end
+
+    # return:: a Pathname with the complete path from the root of the
+    # tree where this node is a member to this node (inclusive).
+    def pathname
+      return @name if @parent.nil?
+
+      (@parent.pathname / @name).cleanpath
+    end
+
+    # create a subtree from the given path and add it to this node
+    #
+    # return:: the leaf node for the added subtree
+    def add_descendants(path, data = nil)
+      p = clean(path)
+      raise ArgumentError, "Can not add absolute path as descendant!!" if p.absolute?
+
+      # invoked with 'current' name, ignore
+      return self if p.to_s == "."
+
+      head = p.descend.first
+      tail = p.relative_path_from(head)
+      last_segment = tail.to_s == "."
+
+      ch = get_child(head)
+      if ch.nil?
+        @children << PathTree.new(head, last_segment ? data : nil, self)
+        ch = @children.last
+      end
+
+      last_segment ? @children.last : ch.add_descendants(tail, data)
+    end
+
+    # adds a new path to the root of the tree where this node is a member
+    # and associates the given data to the leaf of that path.
+    def add_path(path, data = nil)
+      p = clean(path)
+      raise ArgumentError, "Trying to add already existing path: #{path}" unless node(p, from_root: true).nil?
+
+      # prune any part of the given path that already exists in this
+      # tree
+      p.ascend do |q|
+        n = node(q, from_root: true)
+        next if n.nil?
+
+        t = PathTree.new(p.relative_path_from(q).to_s, data)
+        n.append_tree(t)
+        return self
+      end
+
+      # no part of the given path existed within the tree
+      raise ArgumentError, "Trying to add path with other root is not supported"
+    end
+
+    # Visits depth-first by root -> left -> right
+    #
+    # level:: the number of hops from the root node
+    # block:: the user supplied block that is executed for every visited node
+    #
+    # the level and node are given as block parameters
+    #
+    # === Returns
+    # A new array containing the values returned by the block
+    #
+    # === Examples
+    # Get an array with name of each node together with the level of the node
+    #    traverse_preorder{ |level, n| "#{level} #{n.segment}" }
+    #
+    def traverse_preorder(level = 0, &block)
+      result = [yield(level, self)]
+      @children.each do |c|
+        result.append(*c.traverse_preorder(level + 1, &block))
+      end
+      result
+    end
+
+    # Visits depth-first by left -> right -> root
+    #
+    # level:: the number of hops from the root node
+    # block:: the user supplied block that is executed for every visited node
+    #
+    # the level and node are given as block parameters
+    #
+    # === Returns
+    # A new array containing the values returned by the block
+    #
+    # === Examples
+    #
+    # Get an array of each node together with the level of the node
+    #    traverse_postorder{ |level, n| "#{level} #{n.segment}" }
+    def traverse_postorder(level = 0, &block)
+      result = []
+      @children.each do |c|
+        result.concat(c.traverse_postorder(level + 1, &block))
+      end
+      result << yield(level, self)
+    end
+
+    # Visits bredth-first left -> right for each level top-down
+    #
+    # level:: the number of hops from the root node
+    # block:: the user supplied block that is executed for every visited node
+    #
+    # the level and node are given as block parameters
+    #
+    # === Returns
+    # A new array containing the values returned by the block
+    #
+    # === Examples
+    # Get an array with the name of each node together with the level of the node
+    #    traverse_levelorder { |level, n| "#{level} #{n.segment}" }
+    def traverse_levelorder(level = 0, &block)
+      result = []
+      # the node of the original call
+      result << yield(level, self) if level == 0
+
+      # this level
+      @children.each do |c|
+        result << yield(level + 1, c)
+      end
+
+      # next level
+      @children.each do |c|
+        result.concat(c.traverse_levelorder(level + 1, &block))
+      end
+
+      result
+    end
+
+    # Sort the nodes on each level in the tree in lexical order but put
+    # leafs before non-leafs.
+    def sort_leaf_first!
+      @children.sort! { |a, b| leaf_first(a, b) }
+      @children.each(&:sort_leaf_first!)
+      self
+    end
+
+    # returns:: the number of nodes in the subtree with this node as
+    # root
+    def count
+      result = 0
+      traverse_preorder do |level, node|
+        result += 1
+      end
+      result
+    end
+
+    # return:: true if the node is a leaf, false otherwise
+    def leaf?
+      @children.length.zero?
+    end
+
+    # return:: an array with Pathnames of each full
+    # path for the leaves in this tree
+    def leave_pathnames(prune: false)
+      paths = []
+      traverse_postorder do |l, n|
+        next unless n.leaf?
+
+        paths << (prune ? n.pathname.relative_path_from(pathname) : n.pathname)
+      end
+      paths
+    end
+
+    # return:: true if this node does not have a parent node
+    def root?
+      @parent.nil?
+    end
+
+    # return:: the root node of the tree where this node is a member
+    def root
+      return self if root?
+
+      @parent.root
+    end
+
+    # Check if a given path exists in the tree as a directory (non-leaf node)
+    #
+    # path:: a String or Pathname with the path to check
+    # from_root:: if true, start the search from the root of the tree
+    #
+    # return:: true if the path exists and is a directory, false otherwise
+    def dir?(path, from_root: true)
+      n = node(path, from_root: from_root)
+      !n.nil? && !n.leaf?
+    end
+
+    # Finds the node corresponding to the given path.
+    #
+    # path:: a String or Pathname with the path to search for
+    # from_root:: if true start the search from the root of the tree where
+    # this node is a member. If false, start the search from this node's
+    # children.
+    #
+    # return:: the node with the given path or nil if the path
+    # does not exist within this pathtree
+    def node(path, from_root: false)
+      p = clean(path)
+      root = nil
+
+      traverse_preorder do |level, node|
+        q = from_root ? node.pathname : node.pathname.relative_path_from(pathname)
+        if q == p
+          root = node
+          break
+        end
+      end
+      root
+    end
+
+    # adds a copy of the given Pathtree as a subtree to this node. the subtree can not
+    # contain nodes that will end up having the same pathname as any existing
+    # node in the target tree. Note that 'data' attributes will not be copied. The copied
+    # Pathtree nodes will thus point to the same data attributes as the original.
+    #
+    # == Example
+    #
+    # 1. Add my/new/tree to /1/2 -> /1/2/my/new/tree
+    # 2. Add /my/new/tree to /1/2 -> ArgumentError - can not add root as subtree
+    # 3. Trying to add 'new/tree' to '/my' node in a tree with '/my/new/tree' raises
+    # ArgumentError since the pathname that would result already exists within the
+    # target tree.
+    def append_tree(root_node)
+      raise ArgumentError, "Trying to append a root node as subtree!" if root_node.pathname.root?
+
+      # make a copy to make sure it is a self-sustaining PathTree
+      c = root_node.dup
+
+      # get all leaf paths prepended with this node's name to check for
+      # previous existance in this tree.
+      p = c.leave_pathnames.collect { |p| Pathname.new(@name) / p }
+
+      # duplicate ourselves to compare paths
+      t = dup
+
+      # check that no path in c would collide with existing paths
+      common = Set.new(t.leave_pathnames) & Set.new(p)
+      unless common.empty?
+        str = common.collect { |p| p.to_s }.join(",")
+        raise ArgumentError, "Can not append tree due to conflicting paths: #{str}"
+      end
+
+      # hook the subtree into this tree
+      @children << c
+      c.parent = self
+    end
+
+    # Splits the node's path into
+    # - a 'stem', the common path to all nodes in this tree that are on the
+    # same level as this node or closer to the root.
+    # - a 'crown', the remaining path when the stem has been removed from this
+    # node's pathname
+    #
+    # === Example
+    # n.split_stem for the following tree:
+    #
+    #   base
+    #     |- dir
+    #         |- leaf_1
+    #         |- branch
+    #               |- leaf_2
+    #
+    # yields
+    #        ["base/dir", "leaf_1"] when n == leaf_1
+    #        ["base/dir", "branch/leaf_2"] when n == leaf_2
+    #        ["base", "dir"] when n == "dir"
+    #        [nil, "base"] when n == "base"
+    #
+    # return:: [stem, crown]
+    def split_stem
+      r = root
+      s = pathname.descend do |stem|
+        n = r.node(stem, from_root: true)
+        break n if n.children.count != 1 || n == self
+      end
+
+      if s == self
+        [root? ? nil : s.parent.pathname, @name]
+      else
+        [s.pathname, pathname.relative_path_from(s.pathname)]
+      end
+    end
+
+    # return:: a Pathname containing the relative path to this node as seen from the
+    # given node
+    def relative_path_from(node)
+      pathname.relative_path_from(node.pathname)
+    end
+
+    # Builds a PathTree with its root as the given file system dir or file
+    #
+    # fs_point:: an absolute or relative path to a file or directory that
+    # already exists in the file system.
+    # prune:: if false, add the entire, absolute, path to the fs_point to
+    # the PathTree. If true, use only the basename of the fs_point as the
+    # root of the PathTree
+    #
+    # You can submit a filter predicate that determine if a specific path
+    # shall be part of the PathTree or not ->(Pathname) { return true/false}
+    #
+    # return:: the node corresponding to the given fs_point in the resulting
+    # pathtree or nil if no nodes matched the given predicate filter
+    #
+    # === Example
+    #
+    # Build a pathtree containing all files under the "mydir" directory that
+    # ends with '.jpg'. The resulting tree will contain the absolute path
+    # to 'mydir' as nodes (eg '/home/gunnar/mydir')
+    #
+    # t = PathTree.build_from_fs("./mydir",true ) { |p| p.extname == ".jpg" }
+    def self.build_from_fs(fs_point, prune: false)
+      top_node = Pathname.new(fs_point).cleanpath
+      raise ArgumentError, "The path '#{fs_point}' does not exist in the file system!" unless top_node.exist?
+
+      t = nil
+      top_node.find do |path|
+        p = Pathname.new(path)
+
+        if (block_given? && yield(p)) || !block_given?
+          t.nil? ? t = PathTree.new(p) : t.add_path(p)
+        end
+      end
+      return nil if t.nil?
+
+      # always return the entry node but prune the parents if
+      # users wishes
+      entry_node = t.node(top_node, from_root: true)
+      (prune ? entry_node.dup : entry_node)
+    end
+
+    # delegate method calls not implemented by PathTree to the associated 'data'
+    # object
+    def method_missing(m, ...)
+      return super if data.nil?
+
+      data.send(m, ...)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      return super if data.nil?
+
+      data.respond_to?(method_name)
+    end
+
+    def to_s
+      traverse_preorder do |level, n|
+        str = " " * 4 * level + "|-- " + n.segment.to_s
+        str += " <#{n.data}>" unless n.data.nil?
+        str
+      end.join("\n")
+    end
+
+    #
+    # Return a list of nodes whose path match the given substring.
+    #
+    # @param [String] sub_str
+    #           a string to search for in the pathnames of the nodes
+    # @param [boolean] (false) from_root
+    #           True  - start search from the root.
+    #           False - start search from the current node.
+    #
+    # @return [<Type>] <description>
+    #
+    def find(sub_str, from_root: false)
+      result = []
+
+      traverse_preorder do |level, node|
+        q = from_root ? node.pathname : Pathname(segment) +
+          node.pathname.relative_path_from(pathname)
+        result << node if q.to_s.include?(sub_str)
+      end
+      result
+    end
+
+    # Return a new PathTree with the nodes whith pathname matching the
+    # given regex.
+    #
+    # The copy will point to the same node data as the original.
+    #
+    # regex:: a Regex matching the pathname of the nodes to be included in
+    # the copy
+    # prune:: remove all parents to this node in the returned copy
+    #
+    # === Returns
+    # the entry node in a new PathTree with the nodes with pathnames matching the given regex
+    # or nil if no nodes match
+    def match(regex, prune: false)
+      copy = nil
+
+      traverse_preorder do |level, n|
+        p = n.pathname
+        next unless regex&.match?(p.to_s)
+
+        copy.nil? ? copy = PathTree.new(p, n.data) : copy.add_path(p, n.data)
+      end
+      return nil if copy.nil?
+
+      # always return the entry node but return a pruned version if
+      # the user wishes
+      entry_node = copy.node(pathname, from_root: true)
+      (prune ? entry_node.dup : entry_node)
+    end
+
+    # Return a new PathTree with the nodes matching the given block
+    #
+    # The copy will point to the same node data as the original.
+    #
+    # prune:: prune all parents to this node from the returned copy
+    #
+    # === Block
+    #
+    # The given block will receive the level (from the entry node) and
+    # the node itself for each node.
+    #
+    # === Returns
+    # the entry node to the new Pathtree or nil if no nodes matched the
+    # given block.
+    #
+    # === Example
+    #
+    #   copy = original.filter { |l, n| n.data == "smurf" }
+    #
+    # The above will return a tree with nodes whose data is equal to 'smurf'
+    def filter(prune: false)
+      raise InvalidArgument, "No block given!" unless block_given?
+
+      # build the filtered copy
+      copy = nil
+      traverse_preorder do |level, n|
+        if yield(level, n)
+          p = n.pathname
+          copy.nil? ? copy = PathTree.new(p, n.data) : copy.add_path(p, n.data)
+        end
+      end
+
+      return nil if copy.nil?
+
+      # always return the entry node but return a pruned version if
+      # the user wishes
+      entry_node = copy.node(pathname, from_root: true)
+      (prune ? entry_node.dup : entry_node)
+    end
+
+    private
+
+    def clean(path)
+      Pathname.new(path).cleanpath
+    end
+
+    def leaf_first(left, right)
+      if left.leaf? != right.leaf?
+        # always return leaf before non-leaf
+        return left.leaf? ? -1 : 1
+      end
+
+      # for two non-leafs, return lexical order
+      left.segment <=> right.segment
+    end
+
+    def get_child(segment_name)
+      ch = @children.select { |c| c.segment == segment_name.to_s }
+      ch.length.zero? ? nil : ch[0]
+    end
+  end
+end

data/lib/gran/tree_transformer.rb

@@ -0,0 +1,215 @@
+require "pathname"
+require "fileutils"
+require_relative "loggable"
+require_relative "pathtree"
+
+module Gran
+  #
+  # A framework for transforming source file trees into destination trees
+  # through three distinct phases:
+  #
+  # 1. SCAN - Examine source tree, collect metadata (read-only)
+  # 2. TRANSFORM - Convert source nodes to destination nodes (core work)
+  # 3. FINALIZE - Generate derived outputs, aggregations (post-processing)
+  #
+  # == Usage
+  #
+  #   transformer = Gran::TreeTransformer.new(
+  #     src: "/path/to/source",
+  #     dst: "/path/to/destination",
+  #     transformer: MyTransformer.new,
+  #     traversal: :preorder  # optional, default :preorder
+  #   )
+  #
+  #   # Register scanners and finalizers
+  #   transformer.add_scanner(MyScanner.new)
+  #   transformer.add_finalizer(MyFinalizer.new)
+  #
+  #   # Run all phases
+  #   transformer.run(abort_on_exc: true)
+  #
+  # == Transformer Interface
+  #
+  # Transformers must implement:
+  #
+  #   def transform(src_node, dst_tree, context)
+  #     # Required: perform transformation, mutate dst_tree
+  #   end
+  #
+  #   def should_transform?(src_node, context)
+  #     # Optional: return true/false to filter nodes
+  #     # Default: true (process all nodes)
+  #   end
+  #
+  # == Scanner Interface
+  #
+  # Scanners must implement:
+  #
+  #   def scan(src_tree, context)
+  #     # Examine source tree, collect metadata
+  #     # Mutate context to share data with transform/finalize phases
+  #   end
+  #
+  # == Finalizer Interface
+  #
+  # Finalizers must implement:
+  #
+  #   def finalize(src_tree, dst_tree, transformer, context)
+  #     # Generate derived outputs, copy assets, etc.
+  #   end
+  #
+  class TreeTransformer
+    include Loggable
+
+    attr_reader :src_tree, :dst_tree, :context, :transformer
+
+    # Create a new TreeTransformer
+    #
+    # @param [Pathname, String, PathTree] src
+    #   Source tree - can be a filesystem path or an existing PathTree
+    # @param [Pathname, String] dst
+    #   Destination path where transformed output will be created
+    # @param [Object] transformer
+    #   Object implementing the transformer interface
+    # @param [Symbol] traversal
+    #   Tree traversal order: :preorder (default), :postorder, or :levelorder
+    # @param [Hash] context
+    #   Initial context hash for sharing data between phases
+    #
+    def initialize(src:, dst:, transformer:, traversal: :preorder, context: {})
+      @transformer = transformer
+      @traversal = traversal
+      @context = context
+
+      # Build or accept source tree
+      @src_tree = if src.is_a?(PathTree)
+        src
+      else
+        src_path = Pathname.new(src).cleanpath
+        raise ArgumentError, "Source path does not exist: #{src_path}" unless src_path.exist?
+
+        PathTree.build_from_fs(src_path, prune: false)
+      end
+
+      # Create destination tree
+      dst_path = Pathname.new(dst).cleanpath
+      @dst_tree = PathTree.new(dst_path)
+
+      # Store root references in context for convenience
+      @context[:src_root] = @src_tree
+      @context[:dst_root] = @dst_tree
+
+      # Phase handlers
+      @scanners = []
+      @finalizers = []
+
+      # Validate traversal method
+      unless @src_tree.respond_to?(:"traverse_#{@traversal}")
+        raise ArgumentError, "Invalid traversal order: #{@traversal}"
+      end
+    end
+
+    # Add a scanner to be run during the scan phase
+    #
+    # @param [Object] scanner
+    #   Object implementing the scanner interface (must respond to #scan)
+    #
+    def add_scanner(scanner)
+      raise ArgumentError, "Scanner must respond to #scan" unless scanner.respond_to?(:scan)
+
+      @scanners << scanner
+    end
+
+    # Add a finalizer to be run during the finalize phase
+    #
+    # @param [Object] finalizer
+    #   Object implementing the finalizer interface (must respond to #finalize)
+    #
+    def add_finalizer(finalizer)
+      raise ArgumentError, "Finalizer must respond to #finalize" unless finalizer.respond_to?(:finalize)
+
+      @finalizers << finalizer
+    end
+
+    # Run all three transformation phases
+    #
+    # @param [Boolean] abort_on_exc
+    #   If true, abort on first exception. If false, log errors and continue.
+    #
+    def run(abort_on_exc: true)
+      logger.info { "Starting tree transformation: #{@src_tree.pathname} -> #{@dst_tree.pathname}" }
+
+      run_scan_phase
+      run_transform_phase(abort_on_exc: abort_on_exc)
+      run_finalize_phase(abort_on_exc: abort_on_exc)
+
+      logger.info { "Tree transformation complete" }
+    end
+
+    private
+
+    # Phase 1: Scan
+    # Examine source tree and collect metadata (read-only)
+    def run_scan_phase
+      return if @scanners.empty?
+
+      logger.debug { "Running scan phase with #{@scanners.length} scanner(s)" }
+
+      @scanners.each do |scanner|
+        logger.debug { "Running scanner: #{scanner.class.name}" }
+        scanner.scan(@src_tree, @context)
+      end
+    end
+
+    # Phase 2: Transform
+    # Convert source nodes to destination nodes
+    def run_transform_phase(abort_on_exc:)
+      logger.debug { "Running transform phase (#{@traversal} traversal)" }
+
+      processed = 0
+      errors = 0
+
+      @src_tree.send(:"traverse_#{@traversal}") do |level, src_node|
+        # Check if this node should be transformed
+        should_process = if @transformer.respond_to?(:should_transform?)
+          @transformer.should_transform?(src_node, @context)
+        else
+          true
+        end
+
+        next unless should_process
+
+        # Perform transformation
+        @transformer.transform(src_node, @dst_tree, @context)
+        processed += 1
+      rescue => exc
+        errors += 1
+        logger.error { "Transform failed for #{src_node.pathname}: #{exc.message}" }
+        logger.debug { exc.backtrace.join("\n") }
+
+        raise exc if abort_on_exc
+      end
+
+      logger.info { "Transformed #{processed} node(s)" }
+      logger.warn { "Encountered #{errors} error(s)" } if errors > 0
+    end
+
+    # Phase 3: Finalize
+    # Generate derived outputs and finalize the destination tree
+    def run_finalize_phase(abort_on_exc:)
+      return if @finalizers.empty?
+
+      logger.debug { "Running finalize phase with #{@finalizers.length} finalizer(s)" }
+
+      @finalizers.each do |finalizer|
+        logger.debug { "Running finalizer: #{finalizer.class.name}" }
+        finalizer.finalize(@src_tree, @dst_tree, @transformer, @context)
+      rescue => exc
+        logger.error { "Finalizer failed: #{exc.message}" }
+        logger.debug { exc.backtrace.join("\n") }
+
+        raise exc if abort_on_exc
+      end
+    end
+  end
+end

data/lib/gran/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Gran
+  VERSION = "0.1.0"
+end

data/lib/gran.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "gran/version"
+require_relative "gran/loggable"
+require_relative "gran/pathtree"
+require_relative "gran/tree_transformer"
+
+module Gran
+  class Error < StandardError; end
+
+  #
+  # Setup the logger object for the module.
+  #
+  # Users of the module can assign a logger object to the module.
+  # If no logger object is assigned, a default logger object
+  # based on the Ruby Logger class is created.
+  #
+  class << self
+    # @return [logger] set the logger object for the module
+    attr_writer :logger
+
+    #
+    # Used to access the logger for the module.
+    #
+    # @return [logger] the logger object for the module
+    #
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    #
+    # Implement a default logger for the module.
+    #
+    # @return [logger] the default logger object for the module
+    #
+    def default_logger
+      require "logger"
+      Logger.new($stdout).tap do |log|
+        log.progname = name
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: gran
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Anders Rillbert
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-10-17 00:00:00.000000000 Z
+dependencies: []
+description: Provides classes for creatting and transforming trees of PathName nodes
+email:
+- anders.rillbert@kutso.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/gran.rb
+- lib/gran/loggable.rb
+- lib/gran/pathtree.rb
+- lib/gran/tree_transformer.rb
+- lib/gran/version.rb
+homepage: https://github.com/rillbert/giblish/tree/main/gran
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rillbert/giblish/tree/main/gran
+  bug_tracker_uri: https://github.com/rillbert/giblish/issues
+  source_code_uri: https://github.com/rillbert/giblish
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Provides utility classes for working with trees of file paths
+test_files: []