yarrow 0.9.2 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee0d0048f5ad41b5bd0d8c0cb49059728e2920217876618294cc08997e450914
-  data.tar.gz: e12fc19f4d9e973e522ae20e995bddf81c1e21861cfa26136cc3f03acf7f20b0
+  metadata.gz: 9312b361a125e332c4283433f1b26d29eda2a66c19b08023778eb77ea4b7e297
+  data.tar.gz: 04d6809bb61575cb508b0abb87de095e5bc8c861261177558eb602c95f6913a1
 SHA512:
-  metadata.gz: 81d64f248a17176116104d16f3d1e1a718aa5aa68eced9cc5eefa5ae8fb2d050bf43532c378a131010eab80125cb63360704790d62687287669f1a8c96bf91e3
-  data.tar.gz: 1f3e90865e4a947a1615eb0ea190a35f7cf4b8d3b51de6a1e1d9b78391f7e47d7a480153aacdef51028debca6d6eeb58222017c480cb1c66b143e361fa762bb6
+  metadata.gz: 2c9869456f8255277347e442693d68e894b4af657f82ecba0024a9b3d624cfd4393e83f30f4e98f8cb3897bbbc36c15fcd564060fc940a0de727c193f38ceb3b
+  data.tar.gz: 6ed205652f8a844e87d6c9c5c447d34a65e7e26bfcdc661b742ff26079796082b8b1fcf7fd7d521d37885f79ea83342dcf07e605e64ee5d84d1a8a447d556266

data/.github/workflows/ruby.yml

@@ -10,10 +10,10 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: [2.7, 3.1, 3.2]
+        ruby: [3.1, 3.2, "3.3.0-preview1"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/README.md

@@ -29,7 +29,7 @@ gem 'yarrow'
 Status
 ------
 
-Yarrow is an extraction from several existing private documentation projects. This repo is in alpha state, which means that many of the useful features are not yet folded into this codebase.
+Yarrow is an extraction from several existing private documentation projects. ~~This repo is in alpha state, which means that many of the useful features are not yet folded into this codebase.~~ This repo is in flux as it is being used on several live projects, but lacks documentation and a unified command line tool.
 
 Yarrow is being slowly developed as a part-time project to scratch a few itches. New features and bugfixes are pushed straight to `main`, and releases of the Gem are kept more or less in sync with the planned roadmap.
 
@@ -40,12 +40,15 @@ A rough sketch of the project direction.
 
 | Version | Features                                        |
 |---------|-------------------------------------------------|
-| `0.9`   | Support standard text formats and linked assets |
-| `0.10`  | Custom Markdown components                      |
-| `0.11`  | Publishing support for S3 and GitHub/Netlify    |
-| `0.12`  | Clean up local web server and watcher           |
-| `0.13`  | Content structure transformations               |
-| `1.0`   | Reintroduce generic command line runner         |
+| `0.10`  | Filename map expansion strategy                 |
+| `0.11`  | Directory merge expansion strategy              |
+| `0.12`  | Basename merge expansion strategy               |
+| `0.13`  | Resources and Assets vocabulary                 |
+| `0.14`  | Flatten namespaces and clean up modules         |
+| `0.15`  | Web template mapping and markup generators      |
+| `0.16`  | Document custom Markdown components             |
+| `0.17`  | Publishing support for S3 and GitHub/Netlify    |
+| `0.18`  | Clean up local web server and watcher           |
 
 License
 -------

data/lib/yarrow/config.rb

@@ -10,11 +10,11 @@ module Yarrow
     # For larger web publishing projects, this should be moved out into a
     # template context or language/translation files to make it editable
     # for a larger group of people.
-    Meta = Yarrow::Schema::Value.new(
-      :title,
-      :author
+    class Meta < Yarrow::Schema::Entity
+      attribute :title, :string
+      attribute :author, :string
       # :copyright TODO: what other basic details to include?
-    )
+    end
 
     # Dev server config. This is mainly useful if you want to set up a specific
     # chain of Rack middleware and handlers. If you don’t care about default
@@ -52,27 +52,90 @@ module Yarrow
     #   :__config_source_map,
     #   Yarrow::Schema::Types::Map.of(Symbol)
     # )
-
-    class Content < Yarrow::Schema::Entity[:__config_content]
+    class Content < Yarrow::Schema::Entity
       attribute :module, :string
       #attribute :source_map, :__config_source_map
       attribute :source_map, :hash
     end
+    
+    # Template engine and site generator configuration block
+    class OutputGenerator < Yarrow::Schema::Entity
+      attribute :engine, :string
+      attribute :template_dir, :string
+      attribute :options, :hash
+    end
+
+    # Document mapping configuration block
+    class OutputManifest < Yarrow::Schema::Entity
+      attribute :layout, :string
+      attribute :scheme, :string
+
+      DEFAULT_URL_SCHEME = "/{ancestors*}"
+
+      def self.from_spec(input, context)
+        attrs = {}
+
+        if input.is_a?(TrueClass)
+          attrs[:layout] = context[:key].to_s
+        elsif input.is_a?(FalseClass)
+          raise "Reconciliation for content type #{context[:key]} cannot be skipped (yet)"
+        elsif input.is_a?(Symbol)
+          attrs[:layout] = input.to_s
+        elsif input.is_a?(String)
+          attrs[:layout] = context[:key].to_s
+          attrs[:scheme] = input
+        elsif input.is_a?(Hash)
+          attrs = input
+        else
+          raise "Invalid data for output manifest: #{input.class}"
+        end
+
+        unless attrs.key?(:scheme)
+          attrs[:scheme] = DEFAULT_URL_SCHEME
+        end
+       
+        new(attrs)
+      end
+    end
+
+    # Define output document map type
+    Yarrow::Schema::Definitions.register(
+      :yarrow_config_output_manifest_spec,
+      Yarrow::Schema::Types::Map.of(Symbol => OutputManifest).accept_elements(Hash)
+                                                             .accept_elements(TrueClass, :from_spec)
+                                                             .accept_elements(FalseClass, :from_spec)
+                                                             .accept_elements(Symbol, :from_spec)
+                                                             .accept_elements(String, :from_spec)
+    )
+
+    # Manifest reconciliation configuration block
+    class OutputReconcile < Yarrow::Schema::Entity
+      attribute :match, :string
+      attribute :manifest, :yarrow_config_output_manifest_spec
+    end
 
-    class Output < Yarrow::Schema::Entity[:__config_output]
-      attribute :generator, :string
-      attribute :template_dir, :path
-      #attribute :scripts, :array
+    # Output configuration block
+    class Output < Yarrow::Schema::Entity
+      attribute :target, :string
+      attribute :generator, :yarrow_config_output_generator
+      attribute :reconcile, :yarrow_config_output_reconcile
     end
 
+    # Define output schema list type
+    Yarrow::Schema::Definitions.register(
+      :yarrow_config_output_list,
+      Yarrow::Schema::Types::List.of(Output).accept_elements(Hash)
+    )
+
     # Top level root config namespace.
     class Instance < Yarrow::Schema::Entity
       attribute :source_dir, :path
       attribute :output_dir, :path
-      attribute :meta, :any
+      attribute :meta, :yarrow_config_meta
       attribute :server, :any
-      attribute :content, :__config_content
-      attribute :output, :__config_output
+      attribute :content, :yarrow_config_content
+      attribute :output, :yarrow_config_output_list
+      #attribute :output, :any
     end
     #
     # `content_dir` and `output_dir` are placeholders and should be overriden

data/lib/yarrow/configuration.rb

@@ -1,21 +1,11 @@
 module Yarrow
   class Configuration
     class << self
-      # Merges the given configuration or hash-like object with the
-      # registered global configuration.
-      #
-      # @param [Hash, Hashie::Mash, Yarrow::Configuration]
-      #
-      def merge(config)
-        instance.deep_merge!(config)
-      end
-
       # Loads a configuration object from the given YAML file.
       #
       # @param [String] path to YAML file
       #
       # @return [Yarrow::Config]
-      #
       def load(file)
         coerce_config_struct(YAML.load(File.read(file), symbolize_names: true))
       end
@@ -34,12 +24,9 @@ module Yarrow
       # TODO: this should be folded into the schema machinery with type coercions
       def coerce_config_struct(config)
         meta_obj = if config.key?(:meta)
-          Yarrow::Config::Meta.new(
-            title: config[:meta][:title],
-            author: config[:meta][:author]
-          )
+          config[:meta]
         else
-          nil
+          raise "missing :meta key in config"
         end
 
         server_obj = if config.key?(:server)
@@ -49,7 +36,7 @@ module Yarrow
         end
 
         content_obj = if config.key?(:content)
-          Yarrow::Config::Content.new(config[:content])
+          config[:content]
         else
           Yarrow::Config::Content.new({
             module: "",
@@ -60,9 +47,9 @@ module Yarrow
         end
 
         output_obj = if config.key?(:output)
-          Yarrow::Config::Output.new(config[:output])
+          config[:output]
         else
-          Yarrow::Config::Output.new({ generator: "web", template_dir: "templates" })
+          raise "missing :output key in config"
         end
 
         # TODO: messy hack to get rid of Hashie::Mash, this should either be

data/lib/yarrow/content/collection.rb

@@ -0,0 +1,7 @@
+module Yarrow
+  module Content
+    class Collection < Yarrow::Schema::Entity
+      
+    end
+  end
+end

data/lib/yarrow/content/expansion/aggregator.rb

@@ -36,7 +36,7 @@ module Yarrow
             }
             collection_node.label = :collection
             collection_node.props[:type] = type
-            collection_node.props[:resource] = collection_const.new(attributes)
+            collection_node.props[:collection] = collection_const.new(attributes)
           end
 
           # Add this collection id to the lookup table for edge construction
@@ -52,7 +52,7 @@ module Yarrow
           end
         end
 
-        def create_entity(source_node, parent_path, type, entity_const)
+        def create_resource(source_node, parent_path, type, entity_const)
           contents = Yarrow::Format.read(source_node.props[:path])
 
           # Create an entity node with attached resource model
@@ -63,7 +63,7 @@ module Yarrow
               body: contents.document.to_s
             }.merge(contents.metadata)
             
-            entity_node.label = :entity
+            entity_node.label = :resource
             entity_node.props[:type] = type
             entity_node.props[:resource] = entity_const.new(attributes)
           end

data/lib/yarrow/content/expansion/filename_map.rb

@@ -15,7 +15,7 @@ module Yarrow
         def expand_file(entity, policy)
           if policy.match_by_extension(entity.props[:ext])
             parent_path = entity.incoming(:directory).first.props[:path]
-            create_entity(entity, parent_path, policy.entity, policy.entity_const)
+            create_resource(entity, parent_path, policy.entity, policy.entity_const)
           end
         end
       end

data/lib/yarrow/content/policy.rb

@@ -1,40 +1,53 @@
+Yarrow::Schema::Definitions.register(:extension_list, Yarrow::Schema::Types::List.of(String))
+
 module Yarrow
   module Content
-    class Policy
+    class Policy < Yarrow::Schema::Entity
+      # TODO: document meaning and purpose of each attribute
+      attribute :container, :symbol
+      attribute :collection, :symbol
+      attribute :entity, :symbol
+      attribute :expansion, :symbol
+      attribute :extensions, :extension_list
+      attribute :source_path, :string
+      attribute :module_prefix, :string
+
       DEFAULT_EXPANSION = :filename_map
 
       DEFAULT_EXTENSIONS = [".md", ".yml", ".htm"]
 
       DEFAULT_SOURCE_PATH = "."
 
+      DEFAULT_MODULE_PREFIX = ""
+
       MODULE_SEPARATOR = "::"
 
       # Construct a content policy from the given source specification.
-      def self.from_spec(policy_label, policy_props, module_prefix="")
+      def self.from_spec(policy_label, policy_props=DEFAULT_SOURCE_PATH, module_prefix=DEFAULT_MODULE_PREFIX)
         # TODO: validate length, structure etc
 
         # If the spec holds a symbol value then treat it as an entity mapping
         if policy_props.is_a?(Symbol)
-          new(
-            policy_label,
-            policy_label,
-            policy_props,
-            DEFAULT_EXPANSION,
-            DEFAULT_EXTENSIONS,
-            policy_label.to_s,
-            module_prefix
-          )
+          new({
+            container: policy_label,
+            collection: policy_label,
+            entity: policy_props,
+            expansion: DEFAULT_EXPANSION,
+            extensions: DEFAULT_EXTENSIONS,
+            source_path: policy_label.to_s,
+            module_prefix: module_prefix
+          })
 
         # If the spec holds a string value then treat it as a source path mapping
         elsif policy_props.is_a?(String)
           new(
-            policy_label,
-            policy_label,
-            Yarrow::Symbols.to_singular(policy_label),
-            DEFAULT_EXPANSION,
-            DEFAULT_EXTENSIONS,
-            policy_props,
-            module_prefix
+            container: policy_label,
+            collection: policy_label,
+            entity: Yarrow::Symbols.to_singular(policy_label),
+            expansion: DEFAULT_EXPANSION,
+            extensions: DEFAULT_EXTENSIONS,
+            source_path: policy_props,
+            module_prefix: module_prefix
           )
 
         # Otherwise scan through the spec and fill in any gaps
@@ -43,7 +56,8 @@ module Yarrow
           collection = if policy_props.key?(:collection)
             policy_props[:collection]
           else
-            # If an entity name is provided use its plural for the container name
+            # If an entity name is provided use its plural for the container name.
+            # Otherwise fall back to a container name or policy label. 
             if policy_props.key?(:entity)
               Yarrow::Symbols.to_plural(policy_props[:entity])
             else
@@ -51,7 +65,7 @@ module Yarrow
             end
           end
 
-          # Use explicit container name if provided
+          # Use explicit container name if provided. Otherwise fall back to the collection name.
           container = if policy_props.key?(:container)
             policy_props[:container]
           else
@@ -91,44 +105,36 @@ module Yarrow
           end
 
           # Construct the new policy
-          new(
-            container,
-            collection,
-            entity,
-            expansion,
-            extensions,
-            source_path,
-            module_prefix
-          )
+          new({
+            container: container,
+            collection: collection,
+            entity: entity,
+            expansion: expansion,
+            extensions: extensions,
+            source_path: source_path,
+            module_prefix: module_prefix
+          })
         end
       end
 
-      attr_reader :container, :collection, :entity, :expansion, :extensions, :source_path, :module_prefix
-
-      def initialize(container, collection, entity, expansion, extensions, source_path, module_prefix)
-        @container = container
-        @collection = collection
-        @entity = entity
-        @expansion = expansion.to_sym
-        @extensions = extensions
-        @source_path = source_path
-        @module_prefix = module_prefix.split(MODULE_SEPARATOR)
+      def module_prefix_parts
+        module_prefix.split(MODULE_SEPARATOR)
       end
 
       def container_const
-        @container_const ||= Yarrow::Symbols.to_module_const([*module_prefix, container])
+        @container_const ||= Yarrow::Symbols.to_module_const([*module_prefix_parts, container])
       end
 
       def collection_const
         begin
-          @collection_const ||= Yarrow::Symbols.to_module_const([*module_prefix, collection])
+          @collection_const ||= Yarrow::Symbols.to_module_const([*module_prefix_parts, collection])
         rescue NameError
           raise NameError, "cannot map undefined entity `#{collection}`"
         end
       end
 
       def entity_const
-        @entity_const ||= Yarrow::Symbols.to_module_const([*module_prefix, entity])
+        @entity_const ||= Yarrow::Symbols.to_module_const([*module_prefix_parts, entity])
       end
 
       def aggregator_const

data/lib/yarrow/defaults.yml

@@ -11,8 +11,21 @@ content:
     pages:
       expansion: tree
 output:
-  generator: web
-  template_dir: templates
+  - target: web
+    generator:
+      engine: __PENDING_LIBRARY_DECISION__
+      template_dir: templates
+      options:
+        error_mode: strict
+    reconcile:
+      match: collection
+      manifest:
+        collection:
+          layout: collection
+          scheme: /{ancestor_path}
+        resource:
+          layout: resource
+          scheme: /{ancestor_path}/{name}
 assets:
   input_dir: assets
   output_dir: public/assets

data/lib/yarrow/output/build.rb

@@ -0,0 +1,37 @@
+module Yarrow
+  module Output
+    class Build
+      attr_reader :graph, :output_config
+      
+      def initialize(graph, output_config)
+        @graph = graph
+        @output_config = output_config
+      end
+
+      def reconcile
+        case output_config.reconcile.match
+        when "collection/resource" then traverse_by_path(:collection, :resource)
+        when "collection" then traverse_by_label(:collection)
+        when "resource" then traverse_by_label(:resource)
+        end
+      end
+
+      private
+
+      def traverse_by_label(label)
+        graph.n(label).each do |node|
+          puts "§ #{label} node #{node.label} #{node.props}"
+        end
+      end
+
+      def traverse_by_path(parent_label, child_label)
+        graph.n(parent_label).each do |collection_node|
+          puts "§ #{parent_label} node #{collection_node.label} #{collection_node.props}"
+          collection_node.out(child_label).each do |resource_node|
+            puts "§ #{child_label} node #{resource_node.label} #{resource_node.props}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yarrow/schema/definitions.rb

@@ -7,7 +7,7 @@ module Yarrow
         symbol: Types::Instance.of(Symbol).accept(String, :to_sym),
         path: Types::Instance.of(Pathname).accept(String),
         any: Types::Any.new,
-        array: Types::List.of(Types::Any),
+        array: Types::List.any,
         hash: Types::Instance.of(Hash),
         markdown: Types::Instance.of(Kramdown::Document).accept(String)
       }

data/lib/yarrow/schema/dictionary.rb

@@ -23,11 +23,12 @@ module Yarrow
         @attrs_spec.keys
       end
 
-      def cast(input)
+      def cast(input, context=nil)
         missing_attrs = @attrs_spec.keys.difference(input.keys)
 
         if missing_attrs.any?
           missing_attrs.each do |name|
+            # TODO: add optional check
             raise "#{missing_attrs} wrong number of attributes" unless @attrs_spec[name].is_a?(Types::Any)
           end
         end
@@ -37,7 +38,7 @@ module Yarrow
         raise "attribute #{mismatching_attrs} does not exist" if mismatching_attrs.any?
 
         input.reduce({}) do |converted, (name, value)|
-          converted[name] = @attrs_spec[name].cast(value)
+          converted[name] = @attrs_spec[name].cast(value, context)
           converted
         end
       end

data/lib/yarrow/schema/entity.rb

@@ -20,26 +20,24 @@ module Yarrow
         end
 
         def inherited(class_name)
+          class_type = Yarrow::Schema::Types::Instance.of(class_name).accept(Hash)
+          
           if @label
-            class_type = Yarrow::Schema::Types::Instance.of(class_name)
-            Yarrow::Schema::Definitions.register(@label, class_type)
+            label = @label
             @label = nil
+          else
+            label = Yarrow::Symbols.from_const(class_name)
           end
+
+          Yarrow::Schema::Definitions.register(label, class_type)
         end
       end
 
-      def initialize(config)
+      def initialize(config, context=nil)
         converted = dictionary.cast(config)
 
         converted.each_pair do |key, value|
-          # raise "#{key} not a declared attribute" unless dictionary.key?(key)
-          #
-          # defined_type = dictionary[key]
-          #
-          # unless value.is_a?(defined_type)
-          #   raise "#{key} accepts #{defined_type} but #{value.class} given"
-          # end
-
+          # TODO: should we represent this as an attribute set rather than instance vars?
           instance_variable_set("@#{key}", value)
         end
       end
@@ -48,7 +46,15 @@ module Yarrow
         dictionary.attr_names.reduce({}) do |attr_dict, name|
           value = instance_variable_get("@#{name}")
 
-          attr_dict[name] = if value.respond_to?(:to_h)
+          attr_dict[name] =if value.is_a?(Array)
+            value.map do |entry|
+              if entry.respond_to?(:to_h)
+                entry.to_h
+              else
+                entry
+              end
+            end
+          elsif value.respond_to?(:to_h)
             value.to_h
           else
             value