query-stream 1.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3f3bc788221f5c37fb1327f132501ec5fe4607e97f3e673ddbc2a32dfeeb188
+  data.tar.gz: 9111b6651c0596097399b9ffb46f8acea17928dd572f3a7af38ef167ddd6a037
+SHA512:
+  metadata.gz: 792bbe4684efb730c7d1f122ecdf6cff9dfbaa484254f7bf9830b47790978cba0a5150939845975e07fdd2ac9d24e464a66b2f17ee7085e4e8097f041fecb105
+  data.tar.gz: e3de3485e7fdb0f5bdb9d8f728ee2742387540c342f82a27765b80282d9dff1b337a680f419467440fdfbf9b201dfc27414d43110f0f37864e097de36d4f1c04

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+Copyright (c) 2025 Atelier Mirai
+
+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 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.
+
+---
+
+# 日本語訳（参考）
+
+MIT ライセンス
+
+Copyright (c) 2025 Atelier Mirai
+
+本ソフトウェアおよび関連ドキュメントファイル（以下「ソフトウェア」）の複製を取得したすべての人に対して、
+ソフトウェアを制限なく扱うことを無償で許可します。これには、ソフトウェアの複製を使用、複製、変更、
+結合、公表、頒布、サブライセンス、および/または販売する権利、およびソフトウェアを提供された人が
+そうすることを許可する権利も含まれますが、それらに限定されません。
+
+上記の著作権表示およびこの許可表示を、ソフトウェアのすべての複製または重要な部分に含めるものとします。
+
+本ソフトウェアは「現状のまま」提供され、明示または黙示を問わず、商品性、特定目的への適合性、
+および権利の非侵害を含むがそれらに限定されないいかなる保証もありません。
+著作権者または権利者は、ソフトウェアに関して、契約、不法行為、またはその他の方法で
+発生するいかなる請求、損害、責任についても責任を負いません。

data/README.md

@@ -0,0 +1,115 @@
+# QueryStream
+
+YAML/JSON データファイルとテンプレートファイルを組み合わせて、テキストコンテンツ内の QueryStream 記法を展開する汎用 Ruby ライブラリ。
+
+## インストール
+
+```ruby
+# Gemfile
+gem 'query-stream'
+```
+
+```bash
+bundle install
+```
+
+## 基本的な使い方
+
+```ruby
+require 'query_stream'
+
+# テキスト内の QueryStream 記法を展開
+source = File.read('contents/05-references.md')
+result = QueryStream.render(source)
+```
+
+## QueryStream 記法
+
+```
+= [源泉] | [抽出条件] | [ソート] | [件数] | [スタイル]
+```
+
+### 例
+
+```
+= books                           # 全件展開
+= books | tags=ruby               # タグで絞り込み
+= books | tags=ruby | -title | 5  # 絞り込み＋降順ソート＋5件
+= book | 楽しいRuby               # 主キーで一件検索
+= books | :full                   # fullスタイルで展開
+```
+
+### 具体例：vivlio-style での書籍データ展開
+
+#### データファイル例 (`data/books.yml`)
+
+```yaml
+- title: 楽しいRuby
+  author: 
+    name: 高橋征義
+  desc: Rubyを楽しく学べる入門書。
+  cover: ruby.webp
+
+- title: はじめてのC
+  author: 
+    name: 柴田望洋
+  desc: C言語の定番入門書。
+  cover: c.webp
+```
+
+#### テンプレートファイル例 (`templates/_book.md`)
+
+```markdown
+:::{.book-card}
+![](cover)
+**=title**
+=desc
+:::
+```
+
+#### Markdown記述
+
+```markdown
+## 参考書籍
+
+= books
+
+---
+```
+
+#### 展開結果
+
+```markdown
+## 参考書籍
+
+:::{.book-card}
+![](ruby.webp)
+**楽しいRuby**
+Rubyを楽しく学べる入門書。
+:::
+
+:::{.book-card}
+![](c.webp)
+**はじめてのC**
+C言語の定番入門書。
+:::
+
+---
+```
+
+VFMフェンス記法（`:::{.book-card}`）にも対応しており、各レコードが個別のフェンスで囲まれて展開されます。
+
+## 設定
+
+```ruby
+QueryStream.configure do |config|
+  config.data_dir       = 'data'
+  config.templates_dir  = 'templates'
+  config.default_format = :md
+  config.logger         = Logger.new($stdout)
+end
+```
+
+## ライセンス
+
+MIT License

data/bin/query-stream

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'query_stream'
+require 'query_stream/command'
+
+QueryStream::Command::Top.call(ARGV)

data/lib/query_stream/command.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'samovar'
+
+# ================================================================
+# File: lib/query_stream/command.rb
+# ================================================================
+# 責務:
+#   QueryStream の CLI コマンド。--version のみ提供する。
+# ================================================================
+
+module QueryStream
+  module Command
+    # トップレベルコマンド
+    class Top < Samovar::Command
+      self.description = 'QueryStream - YAML/JSON data renderer'
+
+      options do
+        option '--version', 'Print version and exit'
+      end
+
+      # コマンド実行
+      def call
+        if @options[:version]
+          puts "query-stream #{QueryStream::VERSION}"
+        else
+          print_usage
+        end
+      end
+
+      private
+
+      def print_usage
+        puts self.class.description
+        puts "Usage: query-stream [options]"
+        puts "  --version  Print version and exit"
+      end
+    end
+  end
+end

data/lib/query_stream/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# ================================================================
+# File: lib/query_stream/configuration.rb
+# ================================================================
+# 責務:
+#   QueryStream のグローバル設定を管理する。
+#   data_dir, templates_dir, default_format, logger の4項目。
+# ================================================================
+
+module QueryStream
+  # グローバル設定クラス
+  class Configuration
+    # @return [String] データファイルのディレクトリ
+    attr_accessor :data_dir
+
+    # @return [String] テンプレートファイルのディレクトリ
+    attr_accessor :templates_dir
+
+    # @return [Symbol] スタイル省略時のデフォルト出力形式（:md / :html / :json）
+    attr_accessor :default_format
+
+    # @return [Logger] ログ出力先
+    attr_accessor :logger
+
+    def initialize
+      @data_dir       = 'data'
+      @templates_dir  = 'templates'
+      @default_format = :md
+      @logger         = Logger.new($stdout)
+    end
+  end
+end

data/lib/query_stream/data_resolver.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+# ================================================================
+# File: lib/query_stream/data_resolver.rb
+# ================================================================
+# 責務:
+#   データファイルの探索・単数形/複数形の自動解決を行う。
+#   YAML (.yml, .yaml) と JSON (.json) をサポートする。
+#
+# セキュリティ設計:
+#   YAML データファイルは `YAML.safe_load_file` で読み込む。
+#   `permitted_classes` は Symbol / Time / Date / DateTime に限定し、
+#   `!ruby/object` 等の Ruby オブジェクトタグは `Psych::DisallowedClass`
+#   として検出し、`QueryStream::DataLoadError` に変換する。
+#   `aliases: true` は DRY な YAML 記述のために許可するが、
+#   Psych 5.x の Billion Laughs 対策により DoS 耐性がある。
+# ================================================================
+
+require_relative 'errors'
+
+module QueryStream
+  # データファイル探索・読み込みモジュール
+  module DataResolver
+    # サポートする拡張子（優先順位順）
+    EXTENSIONS = %w[.yml .yaml .json].freeze
+
+    # YAML.safe_load_file で許可するクラス
+    # Symbol: symbolize_names: true のために必要
+    # Time/Date/DateTime: 日付/時刻を含む実用データに対応
+    YAML_PERMITTED_CLASSES = [Symbol, Time, Date, DateTime].freeze
+
+    module_function
+
+    # データファイルのパスを解決する
+    # 指定名そのまま → 複数形（末尾に s を付与）→ 単数形の順で探索する
+    # @param source_name [String] データ名（単数形または複数形）
+    # @param data_dir [String] データディレクトリ
+    # @return [String, nil] 見つかったファイルパス、または nil
+    def resolve(source_name, data_dir)
+      # そのまま試行
+      found = find_with_extensions(source_name, data_dir)
+      return found if found
+
+      # 複数形を試行（単数形→複数形: book → books）
+      found = find_with_extensions("#{source_name}s", data_dir)
+      return found if found
+
+      # 単数形を試行（複数形→単数形: books → book）
+      singular = Singularize.call(source_name)
+      if singular != source_name
+        found = find_with_extensions(singular, data_dir)
+        return found if found
+      end
+
+      nil
+    end
+
+    # レコード群をファイルから読み込む
+    #
+    # YAML は `safe_load_file` で読み込み、`!ruby/object` 等の危険なタグを
+    # `QueryStream::DataLoadError` に変換して呼び出し元に通知する。
+    #
+    # @param file_path [String] データファイルパス
+    # @return [Array<Hash>] レコード群（シンボルキー）
+    # @raise [DataLoadError] YAML/JSON の構文エラー、許可されていないクラス等
+    def load_records(file_path)
+      records = case File.extname(file_path).downcase
+                when '.json'
+                  JSON.parse(File.read(file_path, encoding: 'utf-8'), symbolize_names: true)
+                else
+                  YAML.safe_load_file(file_path,
+                                      permitted_classes: YAML_PERMITTED_CLASSES,
+                                      aliases: true,
+                                      symbolize_names: true)
+                end
+
+      records = [records] if records.is_a?(Hash)
+      records
+    rescue Psych::DisallowedClass => e
+      raise DataLoadError.new(
+        "データファイルに許可されていないクラス/タグが含まれています: #{e.message} (#{file_path})",
+        file_path: file_path, cause_error: e
+      )
+    rescue Psych::SyntaxError => e
+      raise DataLoadError.new(
+        "データファイルの YAML 構文エラー: #{e.message} (#{file_path})",
+        file_path: file_path, cause_error: e
+      )
+    rescue JSON::ParserError => e
+      raise DataLoadError.new(
+        "データファイルの JSON 構文エラー: #{e.message} (#{file_path})",
+        file_path: file_path, cause_error: e
+      )
+    end
+
+    # 指定名ですべての拡張子を試行する
+    # @param base_name [String] 拡張子なしファイル名
+    # @param data_dir [String] データディレクトリ
+    # @return [String, nil] 見つかったファイルパス、または nil
+    def find_with_extensions(base_name, data_dir)
+      EXTENSIONS.each do |ext|
+        path = File.join(data_dir, "#{base_name}#{ext}")
+        return path if File.exist?(path)
+      end
+      nil
+    end
+  end
+end

data/lib/query_stream/errors.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# ================================================================
+# File: lib/query_stream/errors.rb
+# ================================================================
+# 責務:
+#   QueryStream の例外クラス体系を定義する。
+#   ERROR系は処理を中断し、WARNING系は処理を続行する。
+# ================================================================
+
+module QueryStream
+  # 基底クラス
+  class Error   < StandardError; end
+  class Warning < StandardError; end
+
+  # ERROR系（処理を中断）
+  #
+  # 各エラークラスは構造化された属性を持つ。
+  # gem 内ではログ出力を行わず、呼び出し元が属性を使って
+  # 独自のメッセージ・i18n・フォーマットを構成する。
+
+  # テンプレートファイルが存在しない
+  # @attr_reader template_path [String] 期待されたテンプレートパス
+  # @attr_reader query [String] 元の QueryStream 記法
+  # @attr_reader location [String] ソースファイル名と行番号
+  # @attr_reader hint [String, nil] 修正ヒント
+  class TemplateNotFoundError < Error
+    attr_reader :template_path, :query, :location, :hint
+
+    def initialize(msg = nil, template_path: nil, query: nil, location: nil, hint: nil)
+      super(msg || "テンプレートファイルが見つかりません: #{template_path}")
+      @template_path = template_path
+      @query         = query
+      @location      = location
+      @hint          = hint
+    end
+  end
+
+  # データファイルが存在しない
+  # @attr_reader expected_path [String] 期待されたデータファイルパス
+  # @attr_reader query [String] 元の QueryStream 記法
+  # @attr_reader location [String] ソースファイル名と行番号
+  class DataNotFoundError < Error
+    attr_reader :expected_path, :query, :location
+
+    def initialize(msg = nil, expected_path: nil, query: nil, location: nil)
+      super(msg || "データファイルが見つかりません: #{expected_path}")
+      @expected_path = expected_path
+      @query         = query
+      @location      = location
+    end
+  end
+
+  class UnknownKeyError  < Error; end    # テンプレート内に存在しないキー
+  class InvalidDateError < Error; end    # 無効な日付
+
+  # データファイルの読み込みに失敗した
+  # （YAML/JSON 構文エラー、YAML で許可されていないクラス/タグ等）
+  #
+  # セキュリティ設計:
+  #   YAML データファイルは `YAML.safe_load_file` で読み込まれ、
+  #   `!ruby/object` など危険な Ruby オブジェクトタグは
+  #   `Psych::DisallowedClass` として検出され、本例外に変換される。
+  #
+  # @attr_reader file_path [String] 読み込みに失敗したファイルパス
+  # @attr_reader cause_error [StandardError, nil] 元の例外（Psych::DisallowedClass 等）
+  class DataLoadError < Error
+    attr_reader :file_path, :cause_error
+
+    def initialize(msg = nil, file_path: nil, cause_error: nil)
+      super(msg || "データファイルの読み込みに失敗しました: #{file_path}")
+      @file_path = file_path
+      @cause_error = cause_error
+    end
+  end
+
+  # WARNING系（処理を続行）
+  #
+  # ERROR と同様に構造化された属性を持ち、gem 内ではログ出力を行わず、
+  # 呼び出し元が on_warning コールバックで独自メッセージを構成する。
+
+  # 一件検索で0件ヒット
+  # @attr_reader query [String] 元の QueryStream 記法
+  # @attr_reader location [String] ソースファイル名と行番号
+  class NoResultWarning < Warning
+    attr_reader :query, :location
+
+    def initialize(msg = nil, query: nil, location: nil)
+      super(msg || "一件検索で該当なし: #{query}")
+      @query    = query
+      @location = location
+    end
+  end
+
+  # 一件検索で複数件ヒット
+  # @attr_reader query [String] 元の QueryStream 記法
+  # @attr_reader location [String] ソースファイル名と行番号
+  # @attr_reader count [Integer] ヒット件数
+  class AmbiguousQueryWarning < Warning
+    attr_reader :query, :location, :count
+
+    def initialize(msg = nil, query: nil, location: nil, count: nil)
+      super(msg || "一件検索で複数件ヒット(#{count}件): #{query}")
+      @query    = query
+      @location = location
+      @count    = count
+    end
+  end
+end

data/lib/query_stream/filter_engine.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'date'
+
+# ================================================================
+# File: lib/query_stream/filter_engine.rb
+# ================================================================
+# 責務:
+#   AND/OR/比較/Range によるフィルタリングとソート処理を行う。
+#   日付の自動正規化にも対応する。
+# ================================================================
+
+module QueryStream
+  # フィルタリング＆ソートエンジンモジュール
+  module FilterEngine
+    module_function
+
+    # フィルタ条件をレコード群に適用する
+    # @param records [Array<Hash>] レコード群
+    # @param filters [Array<Hash>] フィルタ条件の配列
+    # @return [Array<Hash>] フィルタ後のレコード群
+    def apply_filters(records, filters)
+      return records if filters.nil? || filters.empty?
+
+      records.select do |record|
+        filters.all? { evaluate_filter(record, it) }
+      end
+    end
+
+    # ソート条件を適用する
+    # @param records [Array<Hash>] レコード群
+    # @param sort [Hash] ソート条件 { field:, direction: }
+    # @return [Array<Hash>] ソート後のレコード群
+    def apply_sort(records, sort)
+      sorted = records.sort_by { to_comparable(it[sort[:field]]) }
+      sort[:direction] == :desc ? sorted.reverse : sorted
+    end
+
+    # 単一フィルタ条件をレコードに対して評価する
+    # @param record [Hash] 単一レコード
+    # @param filter [Hash] フィルタ条件 { field:, op:, value: }
+    # @return [Boolean] 条件に合致するか
+    def evaluate_filter(record, filter)
+      # 主キー検索（_primary_key）の特別処理
+      if filter[:field] == :_primary_key
+        return evaluate_primary_key_lookup(record, filter[:value])
+      end
+
+      field_value = record[filter[:field]]
+
+      case filter[:op]
+      when :eq
+        match_eq(field_value, filter[:value])
+      when :neq
+        !match_eq(field_value, filter[:value])
+      when :gt
+        to_comparable(field_value) > to_comparable(filter[:value])
+      when :gte
+        to_comparable(field_value) >= to_comparable(filter[:value])
+      when :lt
+        to_comparable(field_value) < to_comparable(filter[:value])
+      when :lte
+        to_comparable(field_value) <= to_comparable(filter[:value])
+      when :range
+        range = filter[:value]
+        range.cover?(to_comparable(field_value))
+      else
+        false
+      end
+    end
+
+    # 主キー候補フィールドを順番に走査して一致するものを探す
+    # @param record [Hash] 単一レコード
+    # @param query_value [Object] 検索値
+    # @return [Boolean] いずれかの主キー候補と一致するか
+    def evaluate_primary_key_lookup(record, query_value)
+      QueryStreamParser::PRIMARY_KEY_FIELDS.any? do |key|
+        record[key]&.to_s == query_value.to_s
+      end
+    end
+
+    # 等値比較（配列・カンマ区切り文字列を透過的に扱う）
+    # データ側が配列/カンマ区切りの場合、ORの値リストと交差判定する
+    def match_eq(field_value, filter_values)
+      field_list = normalize_to_list(field_value)
+      value_list = Array(filter_values).map { it.to_s.strip }
+
+      # フィールド側の値リストと条件値リストに交差があれば一致
+      (field_list & value_list).any?
+    end
+
+    # フィールド値をリスト化する（配列/カンマ区切り/単値を統一）
+    def normalize_to_list(value)
+      case value
+      when Array
+        value.map { it.to_s.strip }
+      when String
+        value.split(',').map { it.strip }
+      when nil
+        []
+      else
+        [value.to_s.strip]
+      end
+    end
+
+    # 比較用に値を正規化する（数値変換・日付変換を試みる）
+    def to_comparable(value)
+      case value
+      when Date, Time
+        value
+      when String
+        # 日付形式（YYYY-MM-DD）を検出して Date に変換
+        if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          begin
+            return Date.parse(value)
+          rescue Date::Error
+            raise InvalidDateError, "無効な日付: #{value}"
+          end
+        end
+        # 数値変換を試みる
+        case value
+        when /\A-?\d+\z/
+          value.to_i
+        when /\A-?\d+\.\d+\z/
+          value.to_f
+        else
+          value
+        end
+      when Integer, Float
+        value
+      else
+        value.to_s
+      end
+    end
+  end
+end