library_tree 1.0.0

data/lib/library_tree/node.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module LibraryTree
+  # Represents a tracked module and its relationships
+  # Parents are modules that include this module
+  # Children are modules that this module is included into.
+  # In Ruby, when A includes B, A depends on B.
+  # We will model edges parent -> child as: including_module -> included_module
+  class Node
+    # @return [String] the name of the underlying Ruby module being tracked
+    # @return [Array<LibraryTree::Node>] parents of this node (including modules)
+    # @return [Array<LibraryTree::Node>] children of this node (included modules)
+    attr_reader :name, :parents, :children
+
+    # Create a node for a Ruby module
+    # @param mod [Module] the module to track
+    def initialize(mod)
+      @name = mod.name || mod.inspect
+      @parents = [] # Array<Node>
+      @children = [] # Array<Node>
+    end
+
+    # Add a child node (an included module)
+    # @param child [LibraryTree::Node]
+    # @return [void]
+    def add_child(child)
+      return if @children.include?(child)
+      @children << child
+    end
+
+    # Add a parent node (a module that includes this module)
+    # @param parent [LibraryTree::Node]
+    # @return [void]
+    def add_parent(parent)
+      return if @parents.include?(parent)
+      @parents << parent
+    end
+
+    # Whether this node has no parents (it is a root)
+    # @return [Boolean]
+    def root?
+      @parents.empty?
+    end
+
+    # Return a Hash representation of this node and its children
+    # @param seen [Hash{Integer=>true}] a map of visited node object_ids to avoid cycles
+    # @return [Hash{Symbol=>Object}] a tree structure with :name and :children
+    def to_h(seen = {})
+      return {name: name} if seen[object_id]
+      seen[object_id] = true
+      {
+        name: name,
+        children: children.map { |c| c.to_h(seen) },
+      }
+    end
+
+    # Render a tree view starting from this node.
+    # @param indent [Integer] number of levels to indent (default: 0)
+    # @param seen [Hash{Integer=>true}] a map of visited node object_ids to avoid cycles
+    # @return [String] a multi-line string representing the subtree
+    def render(indent = 0, seen = {})
+      return "#{"  " * indent}* #{name} (…cycle…)\n" if seen[object_id]
+      seen[object_id] = true
+      out = "#{"  " * indent}* #{name}\n"
+      children.each do |child|
+        out += child.render(indent + 1, seen.dup)
+      end
+      out
+    end
+  end
+end

data/lib/library_tree/registry.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module LibraryTree
+  # Thread-safe registry of tracked modules and their relationships
+  module Registry
+    # Return the registry mutex
+    # @return [Mutex]
+    def mutex
+      @mutex ||= Mutex.new # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+    module_function :mutex
+
+    # Internal storage of nodes keyed by Module
+    # @return [Hash{Module=>LibraryTree::Node}]
+    def nodes
+      @nodes ||= {} # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+    module_function :nodes
+
+    # Check if a module is being tracked
+    # @param mod [Module]
+    # @return [Boolean]
+    def tracked?(mod)
+      nodes.key?(mod)
+    end
+    module_function :tracked?
+
+    # Ensure a Node exists for the given module, creating it if needed
+    # @param mod [Module]
+    # @return [LibraryTree::Node]
+    def ensure_node(mod)
+      nodes[mod] ||= Node.new(mod)
+    end
+    module_function :ensure_node
+
+    # Mark a module as tracked
+    # @param mod [Module]
+    # @return [void]
+    def mark_tracked(mod)
+      mutex.synchronize do
+        ensure_node(mod)
+      end
+    end
+    module_function :mark_tracked
+
+    # Create a link parent -> child (including_module -> included_module)
+    # Ruby 1.9.2+ compatible: use positional parameters instead of keyword arguments
+    # @param parent [Module] including module
+    # @param child [Module] included module
+    # @return [void]
+    def link(parent, child)
+      mutex.synchronize do
+        pnode = ensure_node(parent)
+        cnode = ensure_node(child)
+        pnode.add_child(cnode)
+        cnode.add_parent(pnode)
+      end
+    end
+    module_function :link
+
+    # Return all root nodes
+    # @return [Array<LibraryTree::Node>]
+    def roots
+      mutex.synchronize do
+        nodes.values.select(&:root?)
+      end
+    end
+    module_function :roots
+
+    # Return all known nodes
+    # @return [Array<LibraryTree::Node>]
+    def all
+      mutex.synchronize do
+        nodes.values
+      end
+    end
+    module_function :all
+
+    # Reset the registry to an empty state
+    # @return [void]
+    def reset!
+      mutex.synchronize do
+        @nodes = {}
+      end
+    end
+    module_function :reset!
+  end
+end

data/lib/library_tree/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module LibraryTree
+  # Contains version information for LibraryTree
+  module Version
+    # The current version of the LibraryTree gem
+    VERSION = "1.0.0"
+  end
+end

data/lib/library_tree/watcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module LibraryTree
+  # Public API module to enable watching on modules that include it.
+  # When a watched module is included into another watched module, a link is recorded.
+  module Watcher
+    module ClassMethods
+      # Called whenever the watched module (`self`) is included into another module (`base`).
+      # @param base [Module] the including module
+      # @return [void]
+      def included(base)
+        super
+        # Link whenever the included module (self) is tracked, regardless of whether the includer (base) is tracked.
+        if LibraryTree::Registry.tracked?(self)
+          LibraryTree::Registry.link(base, self)
+        end
+      end
+    end
+
+    class << self
+      # Mark the including module as tracked and extend it to observe future inclusions
+      # @param mod [Module]
+      # @return [void]
+      def included(mod)
+        # Mark the module itself as tracked
+        LibraryTree::Registry.mark_tracked(mod)
+        # Ensure we observe future inclusions of this module into other modules
+        mod.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/library_tree.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "library_tree/version"
+require_relative "library_tree/watcher"
+require_relative "library_tree/registry"
+
+module LibraryTree
+  # Main namespace for LibraryTree. Provides convenience accessors to the registry
+  # and a renderer for the forest of tracked modules.
+  # @see LibraryTree::Watcher
+  # @see LibraryTree::Registry
+  # @see LibraryTree::Node
+  # @see LibraryTree::Version
+  # Generic error class for LibraryTree
+  class Error < StandardError; end
+
+  class << self
+    # Return array of root nodes (modules without parents)
+    # @return [Array<LibraryTree::Node>] an array of nodes that have no parents
+    def roots
+      Registry.roots
+    end
+
+    # Return all nodes currently tracked in the registry
+    # @return [Array<LibraryTree::Node>] all known nodes
+    def nodes
+      Registry.all
+    end
+
+    # Render the forest as a string
+    # @return [String] a textual tree representation of all roots and their descendants
+    def render
+      roots.map { |r| r.render }.join
+    end
+
+    # Testing/utility: reset the registry
+    # @return [void]
+    def reset!
+      Registry.reset!
+    end
+  end
+end

metadata

@@ -0,0 +1,234 @@
+--- !ruby/object:Gem::Specification
+name: library_tree
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Peter H. Boling
+bindir: exe
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+  ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+  A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+  DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+  LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+  uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+  LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+  mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+  coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+  FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+  yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+  to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+  qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+  fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+  HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+  A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+  ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+  wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+  L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+  GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+  kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+  QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+  0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+  DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+  L9nRqA==
+  -----END CERTIFICATE-----
+date: 2025-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: stone_checksums
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-block_is_expected
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-stubbed_env
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: silent_stream
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.11
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Builds a tree of module inclusion of a target module into other modules
+email:
+- floss@galtzo.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- CITATION.cff
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- REEK
+- RUBOCOP.md
+- SECURITY.md
+files:
+- CHANGELOG.md
+- CITATION.cff
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- REEK
+- RUBOCOP.md
+- SECURITY.md
+- lib/library_tree.rb
+- lib/library_tree/node.rb
+- lib/library_tree/registry.rb
+- lib/library_tree/version.rb
+- lib/library_tree/watcher.rb
+homepage: https://github.com/galtzo-floss/library_tree
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://library-tree.galtzo.com/
+  source_code_uri: https://github.com/galtzo-floss/library_tree/tree/v1.0.0
+  changelog_uri: https://github.com/galtzo-floss/library_tree/blob/v1.0.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/galtzo-floss/library_tree/issues
+  documentation_uri: https://www.rubydoc.info/gems/library_tree/1.0.0
+  funding_uri: https://github.com/sponsors/pboling
+  wiki_uri: https://github.com/galtzo-floss/library_tree/wiki
+  news_uri: https://www.railsbling.com/tags/library_tree
+  discord_uri: https://discord.gg/3qme4XHNKN
+  rubygems_mfa_required: 'true'
+rdoc_options:
+- "--title"
+- library_tree - Six-degrees of (Kevin Bacon's?) Module
+- "--main"
+- CHANGELOG.md
+- CITATION.cff
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- REEK
+- RUBOCOP.md
+- SECURITY.md
+- "--line-numbers"
+- "--inline-source"
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Six-degrees of (Kevin Bacon's?) Module
+test_files: []

metadata.gz.sig

@@ -0,0 +1,2 @@
+��6���,�F�&_��F�a��|T}Soણ��� E7xj7��B_F
+S>��>ք��S�`#Ɠ��=IU$6����h��56�rT��r9	�r�oR��̜Yc��A��cm��2f�C.�����
�fH��@���l}~-wٖ䟌&�^����M�	�\H�����x�̠rD�������L�%�y�