marquery 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0dc9fe8c874e5943dc0e56c9f986e6352e33630d067727df43ce36d3c2677886
+  data.tar.gz: 1f6791ac261d546ee5361c81f1c447f693983785450ce897660f4dca337ffe19
+SHA512:
+  metadata.gz: 96e7b6bbc81e5965232c8e0de1dacfd2caa16bd9ba0afdb7c9a1f648cdc42636fb73ff4d38f831369788e19e6e519a3cb28806ca87117a8b3380a5a4588272b9
+  data.tar.gz: a5f1b3ad546b38860ec3a287e7436fd4cb35d30fdb3c43df5d9e89b113bc1f1d934cf373d8f91e8c5b6f0ed5a367974796ab1d7bd7d5b039e216f033f37d0000

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffolding inspired by the
+  [Crystal marquery shard](https://codeberg.org/fluck/marquery.cr).
+- `Marquery::Model` with standard fields (`slug`, `title`, `description`,
+  `content`, `date`, `active?`, `source`, `assets`) and an `attribute` DSL
+  for declaring frontmatter-backed fields with optional type coercion.
+- `Marquery::Entry` as the default model.
+- `Marquery::Collection` and `Marquery::Index` for `_index.md` metadata,
+  including the same `attribute` DSL for custom index types.
+- `Marquery::Renderable` with `assets`, `asset`, `asset?`, `rewrite_assets`,
+  `process_content`, `to_html`, and a per-class `renderer` DSL.
+- `Marquery::Renderer` defaulting to Commonmarker (GitHub Flavored Markdown).
+- `Marquery::MarkdownToHtml` interface for plugging in alternative
+  markdown libraries.
+- `Marquery::Query` with class-level DSL (`model`, `index`, `order_by`,
+  `dir`, `assets_dir`) and a chainable, immutable instance API
+  (`all`, `find`, `find_by_slug`, `filter`, `reject`, `sort_by`, `reverse`,
+  `shuffle`, `previous`, `next`, `first`, `last`, `size`). Queries include
+  `Enumerable`.
+- `Marquery::Parser` for loading entries and `_index.md` at runtime with
+  YAML frontmatter and asset directories (per-entry plus `_shared` and
+  dated directories under a shared `assets_dir`).
+- `Marquery::Registry` and `Marquery.eager_load!` for opt-in warmup at
+  boot.
+- `Marquery::Configuration` accessed via `Marquery.configure` block, with
+  `data_dir` and `preprocessor` keys.
+- `Marquery::Helpers` module exposing `markdown(content)` for use from
+  view helpers in Hanami, Rails, or any Ruby class.
+- `Marquery::AssetHandler` Rack middleware with multi-root support and
+  path-traversal protection (opt-in via `require "marquery/asset_handler"`).
+- `to_h` on `Marquery::Model` and `Marquery::Collection` returning the
+  full attribute hash.
+- `Marquery::Error`, `Marquery::EntryNotFound`, `Marquery::AssetNotFound`,
+  and `Marquery::ParseError` exception types.
+- Codeberg / Forgejo CI workflow running rspec and rubocop on Ruby 3.4
+  and 4.0.
+- README covering quickstart, queries, error handling, configuration,
+  custom index models, custom rendering, preprocessing, shared and
+  multi-language assets, framework integration for Hanami / any Ruby app
+  / Rails, pagination, and entry serialization.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wout <hi@wout.codes>
+
+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,473 @@
+# Marquery
+
+[![CI](https://codeberg.org/fluck/marquery/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/fluck/marquery/actions?workflow=ci.yml)
+[![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcodeberg.org%2Fapi%2Fv1%2Frepos%2Ffluck%2Fmarquery%2Ftags&query=%24%5B0%5D.name&label=version)](https://codeberg.org/fluck/marquery/tags)
+
+A markdown query engine for Ruby. Load markdown files with YAML frontmatter
+from a conventional directory layout, query them through a chainable API,
+resolve associated assets, and render content to HTML.
+
+This is a Ruby companion to the [Crystal marquery
+shard](https://codeberg.org/fluck/marquery.cr). The Crystal version embeds
+everything at compile time via macros; the Ruby version does the equivalent
+work at runtime with memoization and an opt-in eager-load hook for production
+boot.
+
+> [!Note]
+> The original repository is hosted at
+> [Codeberg](https://codeberg.org/fluck/marquery). The [GitHub
+> repo](https://github.com/flucksite/marquery) is just a mirror.
+
+## Installation
+
+Add this to your Gemfile:
+
+```ruby
+gem "marquery"
+```
+
+Then run `bundle install`. Ruby 3.2 or newer is required.
+
+## Quickstart
+
+### 1. Lay out your content
+
+```
+marquery/
+  blog_post/
+    _index.md
+    20260320_first_post.md
+    20260320_first_post/
+      hero.png
+    20260325_second_post.md
+```
+
+The directory name (`blog_post`) is derived from your query class name.
+Filenames must start with a `YYYYMMDD_` date prefix.
+
+### 2. Define a model (optional)
+
+```ruby
+class Post
+  include Marquery::Model
+
+  attribute :tags, type: :array, default: []
+  attribute :author
+  attribute :featured, type: :bool, default: false
+end
+```
+
+If you do not declare a model, `Marquery::Entry` is used as a default. Standard
+fields are always available: `slug`, `title`, `description`, `content`, `date`,
+`active?`, `source`, `assets`.
+
+### 3. Define a query
+
+```ruby
+class PostQuery
+  include Marquery::Query
+
+  model Post
+  order_by :date, :desc
+end
+```
+
+### 4. Query and render
+
+```ruby
+PostQuery.new.all
+PostQuery.new.find("first-post")
+PostQuery.new.filter(&:active?).sort_by(&:title).first
+PostQuery.index_entry            # _index.md as a Marquery::Index
+
+post = PostQuery.new.find("first-post")
+post.to_html
+post.asset("hero.png")
+```
+
+Chainable methods return new query instances, so chains are safe to reuse:
+
+```ruby
+recent = PostQuery.new.filter(&:active?)
+recent.size                      # unaffected by later chaining
+recent.sort_by(&:title).first    # returns the first by title
+```
+
+## Queries
+
+Every filter or sort method returns a new query, so chains never mutate the
+original.
+
+```ruby
+query = PostQuery.new
+
+query.all                        # Array of entries
+query.first                      # nil if empty
+query.last                       # nil if empty
+query.size                       # entry count
+
+query.find("first-post")         # raises Marquery::EntryNotFound when missing
+query.find_by_slug("first-post") # returns nil when missing
+
+query.previous(post)             # previous entry, or nil at the start
+query.next(post)                 # next entry, or nil at the end
+```
+
+Chainable methods, all returning a new query:
+
+```ruby
+query.filter(&:active?)
+query.reject(&:active?)
+query.sort_by(&:title)
+query.reverse
+query.shuffle
+query.shuffle(random: Random.new(42))
+```
+
+`Marquery::Query` includes `Enumerable`, so `each`, `map`, `count`, `any?`,
+`take`, and friends are available. Those return plain Arrays, matching
+`Enumerable` conventions. Use the chainable methods above when you want to
+keep working with a query.
+
+### Error handling
+
+Marquery raises typed exceptions that all inherit from `Marquery::Error`:
+
+```ruby
+begin
+  PostQuery.new.find("nonexistent")
+rescue Marquery::EntryNotFound => exception
+  exception.message # => "Entry not found: nonexistent"
+end
+
+begin
+  post.asset("missing.png")
+rescue Marquery::AssetNotFound => exception
+  exception.message # => "Asset not found: missing.png"
+end
+```
+
+`Marquery::ParseError` is raised at load time when frontmatter or filenames
+cannot be parsed. Catching `Marquery::Error` picks up all three.
+
+## Configuration
+
+```ruby
+Marquery.configure do |c|
+  c.data_dir = "content"
+  c.preprocessor = ->(raw, entry) do
+    Liquid::Template.parse(raw).render("entry" => entry)
+  end
+end
+```
+
+### Eager loading in production
+
+```ruby
+# config/initializers/marquery.rb (Rails)
+Marquery.eager_load!
+```
+
+This walks every registered query class and parses files upfront so the first
+request does not pay the loading cost.
+
+## Custom index model
+
+By default the `_index.md` file is parsed into a `Marquery::Index` with
+the standard `title`, `description`, and `content` fields. For extra
+metadata on the index page, define your own type that includes
+`Marquery::Collection` and declare attributes the same way as on a model:
+
+```ruby
+class PostIndex
+  include Marquery::Collection
+
+  attribute :subtitle
+  attribute :featured_slugs, type: :array, default: []
+end
+
+class PostQuery
+  include Marquery::Query
+
+  index PostIndex
+end
+```
+
+```markdown
+---
+title: Blog
+subtitle: Thoughts on Ruby and Hanami
+featured_slugs:
+  - first-post
+  - third-post
+---
+
+Welcome to the blog.
+```
+
+```ruby
+PostQuery.index_entry.subtitle        # => "Thoughts on Ruby and Hanami"
+PostQuery.index_entry.featured_slugs  # => ["first-post", "third-post"]
+PostQuery.index_entry.to_html         # => "<p>Welcome to the blog.</p>\n"
+```
+
+If no `_index.md` exists, `index_entry` returns an empty `Marquery::Index`
+(or your custom collection) with default field values.
+
+## Custom rendering
+
+The default renderer uses
+[commonmarker](https://github.com/gjtorikian/commonmarker) for GitHub-flavored
+markdown. Swap it out per model:
+
+```ruby
+class MyRenderer
+  include Marquery::MarkdownToHtml
+
+  def markdown_to_html(content)
+    Kramdown::Document.new(content).to_html
+  end
+end
+
+class Post
+  include Marquery::Model
+  renderer MyRenderer
+end
+```
+
+## Preprocessing
+
+Two hooks, with per-model winning over global:
+
+```ruby
+# Global default.
+Marquery.configure do |c|
+  c.preprocessor = ->(raw, entry) { ... }
+end
+
+# Per-model override.
+class Post
+  include Marquery::Model
+
+  def process_content(raw)
+    rendered = Liquid::Template.parse(raw).render("entry" => self)
+    rewrite_assets(rendered)
+  end
+end
+```
+
+If you override `process_content`, you are in charge of asset rewriting. Call
+`rewrite_assets(content)` to opt back in.
+
+## Shared and multi-language assets
+
+For multilingual sites, point several query classes at a shared assets
+directory. Each language gets its own content tree; assets live once.
+
+```ruby
+class Blog::EnQuery
+  include Marquery::Query
+  dir "blog_en"
+  assets_dir "blog_assets"
+end
+
+class Blog::NlQuery
+  include Marquery::Query
+  dir "blog_nl"
+  assets_dir "blog_assets"
+end
+```
+
+Both `dir` and `assets_dir` resolve under `Marquery.config.data_dir` (default
+`marquery/`). The example above looks at:
+
+```
+marquery/blog_en/         # English entries
+marquery/blog_nl/         # Dutch entries
+marquery/blog_assets/     # shared assets
+├── _shared/
+│   └── logo.svg          # available on every entry
+├── 20260320/
+│   └── hero.png          # available on entries dated 20260320
+└── 20260325/
+    └── diagram.svg
+```
+
+Assets merge in three layers, each overriding the previous one when keys
+collide:
+
+1. `_shared/` (available to every entry)
+2. `<YYYYMMDD>/` (available to entries with that date prefix)
+3. The per-entry sibling directory next to the markdown file
+
+So a per-entry `banner.png` wins over a date-scoped `banner.png`, which in
+turn wins over a `_shared/banner.png`. This lets you provide sensible
+defaults and override per-entry when needed.
+
+## Framework integration
+
+Marquery ships two opt-in pieces for integrating with web frameworks:
+
+- `Marquery::Helpers` exposes a `markdown(content)` method that accepts a
+  String or any `Marquery::Renderable` (model or collection instance).
+- `Marquery::AssetHandler` is Rack middleware that serves files from one or
+  more marquery data directories with path-traversal protection.
+
+The two snippets below are everything you need. The framework-specific sections
+after them only differ in where you wire them up.
+
+```ruby
+# Renders a String or a Marquery::Renderable instance to HTML.
+Marquery::Helpers.markdown(post)             # => "<h1>...</h1>"
+Marquery::Helpers.markdown("# Hello")        # => "<h1>...</h1>"
+Marquery::Helpers.markdown(post, renderer: MyRenderer)
+```
+
+```ruby
+require "marquery/asset_handler"
+
+# Rack middleware. Pass one or more directories to serve files from.
+# `data_path` and `assets_path` are computed under Marquery.config.data_dir,
+# so they stay in sync if you change the global root.
+use Marquery::AssetHandler, PostQuery.data_path, PostQuery.assets_path
+```
+
+### Hanami
+
+Include `Marquery::Helpers` in your slice's view helpers and mount the asset
+handler as middleware. Both Hanami's app config and route-scoped middleware
+work; pick whichever fits your slice layout.
+
+```ruby
+# app/views/helpers.rb
+module MyApp
+  module Views
+    module Helpers
+      include Marquery::Helpers
+    end
+  end
+end
+```
+
+```ruby
+# config/app.rb
+require "marquery/asset_handler"
+require_relative "../app/queries/post_query"
+
+module MyApp
+  class App < Hanami::App
+    config.middleware.use Marquery::AssetHandler, PostQuery.data_path
+  end
+end
+```
+
+In templates, mark the output as safe HTML with Hanami's `raw` helper:
+
+```erb
+<%= raw markdown(post) %>
+```
+
+### Any Ruby app
+
+`Marquery::Helpers` is a plain module. `extend` it on the object that needs
+the helper, or include it in a class.
+
+```ruby
+class PostPresenter
+  include Marquery::Helpers
+
+  def initialize(post)
+    @post = post
+  end
+
+  def html
+    markdown(@post)
+  end
+end
+```
+
+If you serve HTTP through Rack (Sinatra, Roda, plain Rack), mount the asset
+handler in `config.ru`:
+
+```ruby
+require "marquery/asset_handler"
+require_relative "post_query"
+
+use Marquery::AssetHandler, PostQuery.data_path
+run MyApp
+```
+
+### Rails
+
+Mix `Marquery::Helpers` into `ApplicationHelper` so `markdown` is available
+across views.
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  include Marquery::Helpers
+end
+```
+
+```erb
+<%= raw markdown(@post) %>
+```
+
+For serving assets, either copy `marquery/` under `public/`, point Propshaft
+at it, or add the Rack middleware:
+
+```ruby
+# config/application.rb
+require "marquery/asset_handler"
+
+config.middleware.use Marquery::AssetHandler, PostQuery.data_path
+```
+
+### Pagination
+
+`query.all` returns a plain Array, so any pagination library that takes an
+Array works.
+
+[Pagy](https://github.com/ddnexus/pagy) is the lightest option and works in
+Hanami, Rails, Sinatra, Roda, and plain Rack:
+
+```ruby
+@pagy, @posts = pagy_array(PostQuery.new.all, items: 10)
+```
+
+For Rails, [Kaminari](https://github.com/kaminari/kaminari) also paginates
+arrays:
+
+```ruby
+@posts = Kaminari.paginate_array(PostQuery.new.all)
+                 .page(params[:page]).per(10)
+```
+
+For plain Ruby, slice it yourself:
+
+```ruby
+pages = PostQuery.new.all.each_slice(10).to_a
+```
+
+### Serializing entries
+
+Both `Marquery::Model` and `Marquery::Collection` expose `to_h`, returning a
+plain Hash of standard plus declared attributes. Pipe it through any JSON
+library you like:
+
+```ruby
+require "json"
+JSON.generate(post.to_h)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/marquery/asset_handler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/mime"
+
+module Marquery
+  class AssetHandler
+    def initialize(app, *directories)
+      @app = app
+      @roots = directories.flatten.compact.map { resolve_root(_1) }.compact
+    end
+
+    def call(env)
+      path = env["PATH_INFO"].to_s
+      if (resolved = serveable_path(path))
+        serve_file(resolved)
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def resolve_root(dir)
+      expanded = File.expand_path(dir.to_s)
+      return nil unless File.directory?(expanded)
+
+      File.realpath(expanded)
+    end
+
+    def serveable_path(request_path)
+      return nil if request_path.nil? || request_path.empty?
+
+      stripped = request_path.sub(%r{\A/}, "")
+      return nil if stripped.empty?
+      return nil unless File.file?(stripped)
+
+      real = File.realpath(stripped)
+      contained?(real) ? real : nil
+    rescue Errno::ENOENT, Errno::ENAMETOOLONG, Errno::EACCES
+      nil
+    end
+
+    def contained?(real_path)
+      @roots.any? do |root|
+        real_path == root || real_path.start_with?(root + File::SEPARATOR)
+      end
+    end
+
+    def serve_file(path)
+      mime = Rack::Mime.mime_type(File.extname(path), "application/octet-stream")
+      body = File.binread(path)
+      headers = {
+        "content-type" => mime,
+        "content-length" => body.bytesize.to_s
+      }
+      [200, headers, [body]]
+    end
+  end
+end

data/lib/marquery/attributable.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Marquery
+  module Attributable
+    VALID_TYPES = %i[string int float bool date time array].freeze
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def attribute(name, type: nil, default: nil)
+        validate_type!(type) if type
+
+        name = name.to_sym
+        attributes[name] = {type: type, default: deep_freeze(default)}
+        attr_reader name
+
+        alias_method("#{name}?", name) if type == :bool
+      end
+
+      def attributes
+        @attributes ||= {}
+      end
+
+      private
+
+      def validate_type!(type)
+        return if VALID_TYPES.include?(type)
+
+        raise ArgumentError,
+              "Unknown attribute type: #{type.inspect} (expected one of #{VALID_TYPES.inspect})"
+      end
+
+      def deep_freeze(value)
+        case value
+        when Array then value.map { deep_freeze(_1) }.freeze
+        when Hash then value.transform_values { deep_freeze(_1) }.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        else value
+        end
+      end
+    end
+
+    private
+
+    def assign_declared_attributes(attrs)
+      self.class.attributes.each do |name, config|
+        raw = attrs.key?(name) ? attrs[name] : config[:default]
+        value = config[:type] && !raw.nil? ? coerce_attribute(raw, config[:type]) : raw
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
+
+    def coerce_attribute(value, type)
+      case type
+      when :string then value.to_s
+      when :int then Integer(value)
+      when :float then Float(value)
+      when :bool then value == true || value == "true"
+      when :date then value.is_a?(Date) ? value : Date.parse(value.to_s)
+      when :time then value.is_a?(Time) ? value : Time.parse(value.to_s)
+      when :array then Array(value)
+      end
+    end
+  end
+end