syntropy 0.14 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc595fea6260cf92c377aeb6931cd1f62ce02fd2e05ca2436fb8b49ac57e4b49
-  data.tar.gz: 9c38f08bf13033aabc5bcf4df9b96e05e238461a43513167b6aeca21fb55c388
+  metadata.gz: ef2840797122cef8e0f7f7675c10665c35f60915e091043416ffd0ed70e1cb5c
+  data.tar.gz: 0d929bfbe0d629879b05c57b7c01c1e8c0ee1af148dc23570c30233f19e81156
 SHA512:
-  metadata.gz: 23d2888d82b16a4f848523193478d7e2813398cf07b32a5ef009c2ce24d76b150579228b32abf6179176075e882e6c68119002819e945984207f611c68726a43
-  data.tar.gz: 13416d8be55de9b6fc454c7c99e25ad65093be329de19b9e4c561ab28e1436f412d8e42838ec14ad3ab039b79b0d57c3b0ea157c5fbb2795d97d605dc2f34b63
+  metadata.gz: 6375f3fb5cbab65d6b710b613c32d0eb9ebb714880f0eb3921fd0b07da9219e0ab94faec2398ae2f33a21fa4f21a8135416faf5b6f2ad0721a99afa067b854f7
+  data.tar.gz: 715274f642dc3b0db72b0ec37526f26221b56930e19eb324f804408b18552a5c465d59f313cd8329a24a9caa0aa05abaa6907d523f15e1e7061e3e9e1bf1762c

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.15 2025-08-31
+
+- Implement invalidation of reverse dependencies on module file change
+
 # 0.14 2025-08-30
 
 - Tweak "boot" sequence

data/TODO.md

@@ -1,5 +1,7 @@
+## Immediate
+
 - [ ] Collection - treat directories and files as collections of data.
-      
+
   Kind of similar to the routing tree, but instead of routes it just takes a
   bunch of files and turns it into a dataset. Each directory is a "table" and is
   composed of zero or more files that form rows in the table. Supported file
@@ -15,9 +17,9 @@
   Articles = @app.collection('_articles/*.md')
   article = Articles.last_by(&:date)
 
-  article.title #=> 
+  article.title #=>
   article.date #=>
-  article.layout #=> 
+  article.layout #=>
   article.render_proc #=> (load layout, apply article)
   article.render #=> (render to HTML)
   ...

data/bin/syntropy

@@ -69,5 +69,8 @@ env[:banner] = false
 env[:machine] = Syntropy.machine = UM.new
 env[:logger] = env[:logger] && TP2::Logger.new(env[:machine], **env)
 
+require 'syntropy/version'
+
+env[:logger]&.info(message: "Running Syntropy version #{Syntropy::VERSION}")
 app = Syntropy::App.load(env)
 TP2.run(env) { app.call(it) }

data/lib/syntropy/app.rb

@@ -37,7 +37,7 @@ module Syntropy
     end
 
     attr_reader :module_loader, :routing_tree, :root_dir, :mount_path, :env
-    
+
     def initialize(**env)
       @machine = env[:machine]
       @root_dir = File.expand_path(env[:root_dir])
@@ -302,7 +302,8 @@ module Syntropy
       wf = @env[:watch_files]
       period = wf.is_a?(Numeric) ? wf : 0.1
       Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
-        @module_loader.invalidate(fn)
+        @env[:logger]&.info(message: "File change detected", fn: fn)
+        @module_loader.invalidate_fn(fn)
         debounce_file_change
       end
     rescue Exception => e

data/lib/syntropy/module.rb

@@ -3,39 +3,118 @@
 require 'p2'
 
 module Syntropy
+  # The ModuleLoader class implemenets a module loader. It handles loading of
+  # modules, tracking of dependencies between modules, and invalidation of
+  # loaded modules (following a change to the module file).
+  # 
+  # A module may implement a route endpoint, a layout template, utility methods,
+  # classes, or any other functionality needed by the web app.
+  # 
+  # Modules are Ruby files that can import other modules as dependencies. A
+  # module must export a single value, which can be a class, a template, a proc,
+  # or any other Ruby object. A module can also export itself by calling `export
+  # self`.
+  # 
+  # Modules are referenced relative to the web app's root directory, without the
+  # `.rb` extension. For example, for a site residing in `/my_site`, the
+  # reference `_lib/foo` will point to a module residing in
+  # `/my_site/_lib/foo.rb`.
   class ModuleLoader
+    attr_reader :modules
+
+    # Instantiates a module loader
+    # 
+    # @param env [Hash] environment hash
+    # @return [void]
     def initialize(env)
       @root_dir = env[:root_dir]
       @env = env
-      @loaded = {} # maps ref to code
+      @modules = {} # maps ref to module entry
       @fn_map = {} # maps filename to ref
     end
 
+    # Loads a module (if not already loaded) and returns its export value.
+    # 
+    # @param ref [String] module reference
+    # @return [any] export value
     def load(ref)
-      @loaded[ref] ||= load_module(ref)
+      entry = (@modules[ref] ||= load_module(ref))
+      entry[:export_value]
     end
 
-    def invalidate(fn)
+    # Invalidates a module by its filename, normally following a change to the
+    # underlying file (in order to cause reloading of the module). The module
+    # will be removed from the modules map, as well as modules dependending on
+    # it.
+    # 
+    # @param fn [String] module filename
+    # @return [void]
+    def invalidate_fn(fn)
       ref = @fn_map[fn]
       return if !ref
 
-      @loaded.delete(ref)
-      @fn_map.delete(fn)
+      invalidate_ref(ref)
     end
 
     private
 
+    # Invalidates a module by its reference, normally following a change to the
+    # underlying file (in order to cause reloading of the module). The module
+    # will be removed from the modules map, as well as modules dependending on
+    # it.
+    # 
+    # @param ref [String] module reference
+    # @return [void]
+    def invalidate_ref(ref)
+      entry = @modules.delete(ref)
+      return if !entry
+
+      @fn_map.delete(entry[:fn])
+      entry[:reverse_deps].each { invalidate_ref(it) }
+    end
+
+    # Registers reverse dependencies for the given module reference.
+    # 
+    # @param ref [String] module reference
+    # @param deps [Array<String>] array of dependencies for the given module
+    # @return [void]
+    def add_dependencies(ref, deps)
+      deps.each do
+        entry = @modules[it]
+        next if !entry
+          
+        entry[:reverse_deps] << ref
+      end
+    end
+
+    # Loads a module and returns a module entry. Any dependencies (using
+    # `import`) are loaded as well.
+    # 
+    # @param ref [String] module reference
+    # @return [Hash] module entry
     def load_module(ref)
       fn = File.expand_path(File.join(@root_dir, "#{ref}.rb"))
-      @fn_map[fn] = ref
       raise Syntropy::Error, "File not found #{fn}" if !File.file?(fn)
 
+      @fn_map[fn] = ref
       code = IO.read(fn)
       env = @env.merge(module_loader: self, ref: ref)
-      export_value = Syntropy::Module.load(env, code, fn)
-      transform_module_export_value(export_value)
+      m = Syntropy::Module.load(env, code, fn)
+      add_dependencies(ref, m.__dependencies__)
+      export_value = transform_module_export_value(m.__export_value__)
+
+      {
+        fn: fn,
+        export_value: export_value,
+        reverse_deps: []
+      }
     end
 
+    # Transforms the given export value. If the value is nil, an exception is
+    # raised.
+    # 
+    # @param export_value [any] module's export value
+    # @return [any] transformed value
     def transform_module_export_value(export_value)
       case export_value
       when nil
@@ -50,13 +129,16 @@ module Syntropy
     end
   end
 
+  # The Syntropy::Module class implements a reloadable module. A module is a
+  # `.rb` source file that implements a route endpoint, a template, utility
+  # methods or any other functionality needed by the web app.
   class Module
+    # Loads a module, returning the module instance
     def self.load(env, code, fn)
       m = new(**env)
       m.instance_eval(code, fn)
-      export_value = m.__export_value__
       env[:logger]&.info(message: "Loaded module at #{fn}")
-      export_value
+      m
     rescue StandardError => e
       env[:logger]&.error(
           message: "Error while loading module #{fn}",
@@ -65,7 +147,10 @@ module Syntropy
       raise
     end
 
-    attr_reader 
+    # Initializes a module with the given environment hash.
+    # 
+    # @param env [Hash] environment hash
+    # @return [void]
     def initialize(**env)
       @env = env
       @machine = env[:machine]
@@ -74,16 +159,42 @@ module Syntropy
       @ref = env[:ref]
       singleton_class.const_set(:MODULE, self)
     end
-      
+
     attr_reader :__export_value__
+
+    # Exports the given value. This value will be used as the module's
+    # entrypoint. It can be any Ruby value, but for a route module would
+    # normally be a proc.
+    # 
+    # @param v [any] export value
+    # @return [void]
     def export(v)
       @__export_value__ = v
     end
 
+    # Returns the list of module references imported by the module.
+    # 
+    # @return [Array] array of module references
+    def __dependencies__
+      @__dependencies__ ||= []
+    end
+
+    # Imports the module corresponding to the given reference. The return value
+    # is the module's export value.
+    # 
+    # @param ref [String] module reference
+    # @return [any] loaded dependency's export value
     def import(ref)
-      @module_loader.load(ref)
+      @module_loader.load(ref).tap {
+        __dependencies__ << ref
+      }
     end
 
+    # Creates and returns a P2 template created with the given block.
+    # 
+    # @param proc [Proc, nil] template proc or nil
+    # @param block [Proc] template block
+    # @return [P2::Template] template
     def template(proc = nil, &block)
       proc ||= block
       raise "No template block/proc given" if !proc
@@ -91,10 +202,17 @@ module Syntropy
       P2::Template.new(proc)
     end
 
+    # Returns a list of pages found at the given ref.
+    # 
+    # @param ref [String] directory reference
+    # @return [Array] array of pages found in directory
     def page_list(ref)
       Syntropy.page_list(@env, ref)
     end
 
+    # Creates and returns a Syntropy app for the given environment.
+    # 
+    # @param env [Hash] environment
     def app(**env)
       Syntropy::App.new(**(@env.merge(env)))
     end

data/lib/syntropy/routing_tree.rb

@@ -66,32 +66,6 @@ module Syntropy
       @router_proc ||= compile_router_proc
     end
 
-    # Returns the first error handler found for the entry. If no error handler
-    # exists for the entry itself, the search continues up the tree through the
-    # entry's ancestors.
-    #
-    # @param entry [Hash] route entry
-    # @return [String, nil] filename of error handler, or nil if not found
-    def route_error_handler(entry)
-      return entry[:error] if entry[:error]
-
-      entry[:parent] && route_error_handler(entry[:parent])
-    end
-
-    # Returns a list of all hooks found up the tree from the given entry. Hooks
-    # are returned ordered from the tree root down to the given entry.
-    #
-    # @param entry [Hash] route entry
-    # @return [Array<String>] list of hook entries
-    def route_hooks(entry)
-      hooks = []
-      while entry
-        hooks.unshift(entry[:hook]) if entry[:hook]
-        entry = entry[:parent]
-      end
-      hooks
-    end
-
     # Computes a "clean" URL path for the given path. Modules and markdown are
     # stripped of their extensions, and index file paths are also converted to the
     # containing directory path. For example, the clean URL path for `/foo/bar.rb`
@@ -233,7 +207,7 @@ module Syntropy
       case
       when (m = fn.match(/\/index(\+)?(\.(?:rb|md))$/))
         make_index_module_route(m:, parent:, path: abs_path, fn:)
-        
+
       # index.html
       when fn.match(/\/index\.html$/)
         set_index_route_target(parent:, path: abs_path, kind: :static, fn:)
@@ -256,7 +230,7 @@ module Syntropy
     # (modules or markdown) files) are applied as targets to the immediate
     # containing directory. A + suffix indicates this route handles requests to
     # its subtree
-    # 
+    #
     # @param m [MatchData] path match data
     # @param parent [Hash] parent route entry
     # @param path [String] route path

data/lib/syntropy/utils.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
- 
+
 module Syntropy
   # Utilities for use in modules
   module Utilities
-    # Returns a request handler that routes request according to 
+    # Returns a request handler that routes request according to
     def route_by_host(env, map = nil)
       root = env[:root_dir]
       sites = Dir[File.join(root, '*')]
@@ -17,7 +17,7 @@ module Syntropy
       # copy over map refs
       map&.each { |k, v| sites[k] = sites[v] }
 
-      # 
+      #
       lambda { |req|
         site = sites[req.host]
         site ? site.call(req) : req.respond(nil, ':status' => Status::BAD_REQUEST)
@@ -36,6 +36,6 @@ module Syntropy
 
     def app(**env)
       Syntropy::App.new(**env)
-    end    
+    end
   end
 end

data/lib/syntropy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Syntropy
-  VERSION = '0.14'
+  VERSION = '0.15.1'
 end

data/test/app/_lib/dep.rb

@@ -0,0 +1,7 @@
+Foo = import '_lib/self'
+
+def bar
+  Foo.foo
+end
+
+export self

data/test/test_module.rb

@@ -44,4 +44,14 @@ class ModuleTest < Minitest::Test
     assert_equal @loader, mod.module_loader
     assert_equal 42, mod.app
   end
+
+  def test_dependency_invalidation
+    mod = @loader.load('_lib/dep')
+    assert_equal ['_lib/self', '_lib/dep'], @loader.modules.keys
+
+    self_fn = @loader.modules['_lib/self'][:fn]
+    @loader.invalidate_fn(self_fn)
+
+    assert_equal [], @loader.modules.keys
+  end
 end

data/test/test_routing_tree.rb

@@ -288,58 +288,6 @@ class RoutingTreeTest < Minitest::Test
     assert_equal 'foo', params['id']
   end
 
-  def test_route_error_handler
-    e = @rt.dynamic_map['/docs/[org]']
-    target = @rt.route_error_handler(e)
-    assert_kind_of Hash, target
-    assert_equal :module, target[:kind]
-    assert_equal File.join(@rt.root_dir, '_error.rb'), target[:fn]
-
-    e = @rt.dynamic_map['/docs/api+']
-    target = @rt.route_error_handler(e)
-    assert_equal :module, target[:kind]
-    assert_equal File.join(@rt.root_dir, '_error.rb'), target[:fn]
-
-    e = @rt.dynamic_map['/docs/[org]/[repo]']
-    target = @rt.route_error_handler(e)
-    assert_equal :module, target[:kind]
-    assert_equal File.join(@rt.root_dir, '[org]/[repo]/_error.rb'), target[:fn]
-  end
-
-  def test_route_hooks
-    e = @rt.dynamic_map['/docs/[org]']
-    hooks = @rt.route_hooks(e)
-    assert_equal [
-      { kind: :module, fn: File.join(@rt.root_dir, '_hook.rb') }
-    ], hooks
-
-    e = @rt.dynamic_map['/docs/api+']
-    hooks = @rt.route_hooks(e)
-    assert_equal [
-      { kind: :module, fn: File.join(@rt.root_dir, '_hook.rb') }
-    ], hooks
-
-    e = @rt.dynamic_map['/docs/[org]/[repo]']
-    hooks = @rt.route_hooks(e)
-    assert_equal [
-      { kind: :module, fn: File.join(@rt.root_dir, '_hook.rb') }
-    ], hooks
-
-    e = @rt.dynamic_map['/docs/[org]/[repo]/issues']
-    hooks = @rt.route_hooks(e)
-    assert_equal [
-      { kind: :module, fn: File.join(@rt.root_dir, '_hook.rb') },
-      { kind: :module, fn: File.join(@rt.root_dir, '[org]/[repo]/issues/_hook.rb') }
-    ], hooks
-
-    e = @rt.dynamic_map['/docs/[org]/[repo]/issues/[id]']
-    hooks = @rt.route_hooks(e)
-    assert_equal [
-      { kind: :module, fn: File.join(@rt.root_dir, '_hook.rb') },
-      { kind: :module, fn: File.join(@rt.root_dir, '[org]/[repo]/issues/_hook.rb') }
-    ], hooks
-  end
-
   def test_routing_root_mounted
     rt = Syntropy::RoutingTree.new(root_dir: File.join(@root_dir, 'site'), mount_path: '/')
     router = rt.router_proc

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: syntropy
 version: !ruby/object:Gem::Version
-  version: '0.14'
+  version: 0.15.1
 platform: ruby
 authors:
 - Sharon Rosner
@@ -221,6 +221,7 @@ files:
 - test/app/_hook.rb
 - test/app/_layout/default.rb
 - test/app/_lib/callable.rb
+- test/app/_lib/dep.rb
 - test/app/_lib/env.rb
 - test/app/_lib/klass.rb
 - test/app/_lib/missing-export.rb