query-stream 1.2.2

data/lib/query_stream/query_stream_parser.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+# ================================================================
+# File: lib/query_stream/query_stream_parser.rb
+# ================================================================
+# 責務:
+#   QueryStream 記法（= books | tags=ruby | -title | 5 | :full）を
+#   パースし、構造化されたクエリハッシュを返す。
+#
+# パイプライン:
+#   1. Source  - データ名（必須）
+#   2. Filter  - 抽出条件（field=value, 比較演算子, 範囲指定）
+#   3. Sort    - ソート条件（-field / +field）
+#   4. Limit   - 件数制限（正の整数）
+#   5. Style   - スタイル名（:stylename または :stylename.ext）
+#
+# トークンの自動判別:
+#   各トークンは形式で一意に判別される（省略・順序入れ替えに対応）
+# ================================================================
+
+module QueryStream
+  # QueryStream 記法のパーサー
+  module QueryStreamParser
+    # 主キー候補フィールド（優先順位順）
+    PRIMARY_KEY_FIELDS = %i[id no code slug name title].freeze
+
+    # AND 条件の区切りパターン
+    AND_PATTERN = /\s+(?:AND|and|&&)\s+/
+
+    module_function
+
+    # QueryStream 記法をパースして構造化ハッシュを返す
+    #
+    # @param line [String] QueryStream 行（例: "= books | tags=ruby | :full"）
+    # @return [Hash] パース結果
+    #   - :source [String] データ名（複数形のまま）
+    #   - :filters [Array<Hash>] フィルタ条件
+    #   - :sort [Hash, nil] ソート条件 { field:, direction: }
+    #   - :limit [Integer, nil] 件数制限
+    #   - :style [String, nil] スタイル名
+    #   - :format [String, nil] 出力形式（スタイルに拡張子がある場合）
+    #   - :single_lookup [Boolean] 主キーによる一件検索か
+    def parse(line)
+      # "= books | tags=ruby | :full" → ["books", "tags=ruby", ":full"]
+      # "=books | :table" も許容
+      raw = line.sub(/\A=\s*/, '').strip
+      segments = raw.split('|').map { it.strip }
+
+      source = segments.shift
+      return build_result(source:) if segments.empty?
+
+      # 源泉名が単数形かどうかを判定
+      # 単数形の場合、最初の非修飾セグメントは主キー検索として解釈する
+      singular_source = (Singularize.call(source) == source)
+
+      filters = []
+      sort = nil
+      limit = nil
+      style = nil
+      format = nil
+      single_lookup = false
+
+      segments.each_with_index do |segment, idx|
+        next if segment.empty?
+
+        classified = classify_tokens(segment, primary_context: singular_source && idx == 0)
+        classified.each do |token|
+          case token
+          in { type: :style, value:, format: fmt }
+            style = value
+            format = fmt
+          in { type: :style, value: }
+            style = value
+          in { type: :limit, value: }
+            limit = value
+          in { type: :sort, value: }
+            sort = value
+          in { type: :filter, value: }
+            filters.concat(value)
+          in { type: :primary_lookup, value: }
+            filters.concat(value)
+            single_lookup = true
+          end
+        end
+      end
+
+      build_result(source:, filters:, sort:, limit:, style:, format:, single_lookup:)
+    end
+
+    # セグメント内のトークンを分類する
+    # AND で分割された複合条件、スタイル、ソート、件数を判別
+    # @param segment [String] パイプで区切られた1セグメント
+    # @param primary_context [Boolean] 主キー検索コンテキスト（単数形源泉の最初のセグメント）
+    # @return [Array<Hash>] 分類済みトークン
+    def classify_tokens(segment, primary_context: false)
+      tokens = []
+
+      # スタイル（:stylename または :stylename.ext）
+      if segment.match?(/\A:[a-zA-Z0-9_.-]+\z/)
+        style_str = segment.delete_prefix(':')
+        # 拡張子の検出（:table.html → style=table, format=html）
+        if style_str.match(/\A([a-zA-Z0-9_-]+)\.([a-zA-Z0-9]+)\z/)
+          tokens << { type: :style, value: $1, format: $2 }
+        else
+          tokens << { type: :style, value: style_str }
+        end
+        return tokens
+      end
+
+      # ソート（-field / +field）
+      if segment.match?(/\A[+-][a-zA-Z_]/)
+        tokens << { type: :sort, value: parse_sort(segment) }
+        return tokens
+      end
+
+      # フィルタ条件（field=value, 比較演算子, AND/OR 複合条件）
+      if segment.match?(/[=!<>]/) || segment.match?(AND_PATTERN)
+        tokens << { type: :filter, value: parse_filter_expression(segment) }
+        return tokens
+      end
+
+      # 主キー検索コンテキスト（単数形源泉の最初のセグメント）では
+      # 数値も主キー検索値として扱う（code=13 のような検索に対応）
+      if primary_context
+        tokens << { type: :primary_lookup, value: build_primary_lookup(segment) }
+        return tokens
+      end
+
+      # 件数（正の整数のみ）
+      if segment.match?(/\A\d+\z/)
+        tokens << { type: :limit, value: segment.to_i }
+        return tokens
+      end
+
+      # 上記いずれにも該当しない場合は主キー検索
+      tokens << { type: :primary_lookup, value: build_primary_lookup(segment) }
+      tokens
+    end
+
+    # ソート指定をパースする
+    # @param token [String] "-title" / "+title" / "title"
+    # @return [Hash] { field:, direction: }
+    def parse_sort(token)
+      case token
+      in /\A-(.+)\z/
+        { field: $1.to_sym, direction: :desc }
+      in /\A\+?(.+)\z/
+        { field: $1.to_sym, direction: :asc }
+      end
+    end
+
+    # 直前フィールドを引き継いで値のみの条件をパースする
+    # @param field [Symbol, String] 直前フィールド
+    # @param value_str [String] "ruby" / "ruby, beginner"
+    # @return [Array<Hash>] フィルタ条件
+    def parse_value_only_condition(field, value_str)
+      parse_eq_condition(field, value_str)
+    end
+
+    # AND で接続されたフィルタ式をパースする
+    # @param expression [String] "tags=ruby && category=web"
+    # @return [Array<Hash>] フィルタ条件のリスト
+    def parse_filter_expression(expression)
+      # AND で分割
+      clauses = expression.split(AND_PATTERN)
+      previous_field = nil
+      previous_filter = nil
+
+      clauses.flat_map do |clause|
+        clause = clause.strip
+        next [] if clause.empty?
+
+        parsed = parse_single_condition(clause)
+
+        if parsed.empty? && previous_field
+          if previous_filter && previous_filter[:field] == previous_field && previous_filter[:op] == :eq
+            additional = parse_values(clause)
+            previous_filter[:value] = Array(previous_filter[:value]) + additional
+            next []
+          else
+            parsed = parse_value_only_condition(previous_field, clause)
+          end
+        end
+
+        last_filter = parsed.last
+        previous_field = last_filter&.[](:field)
+        previous_filter = last_filter if last_filter&.[](:op) == :eq
+
+        parsed
+      end
+    end
+
+    # 単一条件をパースする（OR はカンマ区切りで表現）
+    # @param condition [String] "tags=ruby, javascript" / "temp>=20"
+    # @return [Array<Hash>] フィルタ条件（1つまたは複数）
+    def parse_single_condition(condition)
+      # 比較演算子の検出（!=, >=, <=, >, <, ==, = の順で試行）
+      case condition.strip
+      in /\A([a-zA-Z_]+)\s*!=\s*(.+)\z/
+        [{ field: $1.to_sym, op: :neq, value: parse_values($2) }]
+      in /\A([a-zA-Z_]+)\s*>=\s*(.+)\z/
+        [{ field: $1.to_sym, op: :gte, value: parse_numeric($2.strip) }]
+      in /\A([a-zA-Z_]+)\s*<=\s*(.+)\z/
+        [{ field: $1.to_sym, op: :lte, value: parse_numeric($2.strip) }]
+      in /\A([a-zA-Z_]+)\s*>\s*(.+)\z/
+        [{ field: $1.to_sym, op: :gt, value: parse_numeric($2.strip) }]
+      in /\A([a-zA-Z_]+)\s*<\s*(.+)\z/
+        [{ field: $1.to_sym, op: :lt, value: parse_numeric($2.strip) }]
+      in /\A([a-zA-Z_]+)\s*={1,2}\s*(.+)\z/
+        parse_eq_condition($1.strip, $2.strip)
+      else
+        # パースできない場合は空で返す
+        []
+      end
+    end
+
+    # 等値/範囲条件をパースする
+    # @param field [String] フィールド名
+    # @param value_str [String] "ruby, javascript" / "20..25" / "20...25"
+    # @return [Array<Hash>] フィルタ条件
+    def parse_eq_condition(field, value_str)
+      field_sym = field.to_sym
+
+      # 範囲指定の検出
+      # 開始なし（...N / ..N）を先にチェックし、次に両端あり（N...M / N..M）をチェック
+      if (m = value_str.match(/\A\.\.\.(\S+)\z/))
+        # 上限のみ・排他的（field=...25 → 25未満）
+        [{ field: field_sym, op: :lt, value: parse_numeric(m[1]) }]
+      elsif (m = value_str.match(/\A\.\.(\S+)\z/))
+        # 上限のみ（field=..25）
+        [{ field: field_sym, op: :lte, value: parse_numeric(m[1]) }]
+      elsif (m = value_str.match(/\A([^.]\S*)\.\.\.(\S+)\z/))
+        # 排他的範囲（終端除く）: 20...25
+        [{ field: field_sym, op: :range, value: parse_numeric(m[1])...parse_numeric(m[2]) }]
+      elsif (m = value_str.match(/\A([^.]\S*)\.\.(\S+)\z/))
+        # 包括的範囲: 20..25
+        [{ field: field_sym, op: :range, value: parse_numeric(m[1])..parse_numeric(m[2]) }]
+      elsif (m = value_str.match(/\A([^.]\S*)\.\.\z/))
+        # 下限のみ（field=20..）
+        [{ field: field_sym, op: :gte, value: parse_numeric(m[1]) }]
+      else
+        # 通常の等値条件（カンマ区切りでOR）
+        [{ field: field_sym, op: :eq, value: parse_values(value_str) }]
+      end
+    end
+
+    # カンマ区切りの値をリストとしてパースする
+    # @param str [String] "ruby, javascript"
+    # @return [Array<String>] ["ruby", "javascript"]
+    def parse_values(str)
+      str.split(',').map { it.strip }
+    end
+
+    # 数値文字列を適切な型に変換する
+    # @param str [String] "20" / "3.14" / "東京"
+    # @return [Integer, Float, String] 変換後の値
+    def parse_numeric(str)
+      s = str.strip
+      case s
+      when /\A-?\d+\z/    then s.to_i
+      when /\A-?\d+\.\d+\z/ then s.to_f
+      else s
+      end
+    end
+
+    # 主キー候補フィールドによる一件検索フィルタを構築する
+    # すべての主キー候補に対して OR 的に検索する
+    # @param value [String] 検索値
+    # @return [Array<Hash>] フィルタ条件（特殊な primary_key_lookup）
+    def build_primary_lookup(value)
+      parsed = parse_numeric(value)
+      [{ field: :_primary_key, op: :eq, value: parsed }]
+    end
+
+    # パース結果のハッシュを構築する
+    def build_result(source:, filters: [], sort: nil, limit: nil, style: nil, format: nil, single_lookup: false)
+      { source:, filters:, sort:, limit:, style:, format:, single_lookup: }
+    end
+  end
+end

data/lib/query_stream/singularize.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# ================================================================
+# File: lib/query_stream/singularize.rb
+# ================================================================
+# 責務:
+#   英単語の複数形を単数形に変換する軽量ヘルパー。
+#   ActiveSupport::Inflector に依存せず、パターンマッチングで実装する。
+#
+# 例:
+#   books       → book
+#   categories  → category
+#   branches    → branch
+#   shelves     → shelf
+#   elements    → element
+#   data        → data（不変）
+# ================================================================
+
+module QueryStream
+  # 英単語の複数形→単数形変換モジュール
+  module Singularize
+    module_function
+
+    # 複数形の英単語を単数形に変換する
+    # @param word [String] 変換対象の単語
+    # @return [String] 単数形の単語
+    def call(word)
+      str = word.to_s
+
+      # アンダースコア付きの複合名は、末尾の s で終わるセグメントを単数化する
+      # physics_books → physics_book, books_nested → book_nested, books2 → book2
+      if str.include?('_')
+        segments = str.split('_')
+        # people は不規則変化なので優先的に単数化
+        people_idx = segments.index { it.match?(/\Apeople\z/i) }
+        if people_idx
+          segments[people_idx] = singularize_simple(segments[people_idx])
+          return segments.join('_')
+        end
+        # 末尾から探して最初に見つかった複数形セグメントを単数化
+        idx = segments.rindex { singularize_simple(it) != it }
+        if idx
+          segments[idx] = singularize_simple(segments[idx])
+          return segments.join('_')
+        end
+      end
+
+      singularize_simple(str)
+    end
+
+    # 単一単語の単数化
+    def singularize_simple(word)
+      case word.to_s
+      in /\Apeople(.*)\z/i             then "person#{$1}"
+      in /\A(.+)ies\z/                 then "#{$1}y"
+      in /\A(.+)([sxz]|ch|sh)es\z/    then "#{$1}#{$2}"
+      in /\A(.+)ves\z/                 then "#{$1}f"
+      in /\A(.+?)s([0-9].*)\z/         then "#{$1}#{$2}"
+      in /\A(.+)s\z/                   then $1
+      else word
+      end
+    end
+  end
+end

data/lib/query_stream/template_compiler.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+# ================================================================
+# File: lib/query_stream/template_compiler.rb
+# ================================================================
+# 責務:
+#   テンプレートファイル（_book.md 等）にデータを流し込み、
+#   テキストを生成するコンパイラ。
+#
+# 変換ルール:
+#   - `= key` のみの行 → key の値を展開（nil/空文字なら行スキップ）
+#   - `prefix = key` → prefix を残してkey の値を展開
+#   - `![](key)` → 変数展開（拡張子なし → 変数、拡張子あり → リテラル）
+#   - `= key` を含まない行 → リテラル出力（ヘッダー等は一度だけ出力）
+#   - 空行 → 改行出力
+#
+# テーブル記法対応:
+#   `= key` を含む行のみ反復し、含まない行（ヘッダー・区切り行）は
+#   一度だけ出力する。
+#
+# VFM フェンス記法対応:
+#   :::{.book-card} 〜 ::: のようなフェンスが動的行を囲んでいる場合、
+#   フェンス行も repeating 範囲に含めて各レコードごとに反復出力する。
+#   {.person-card} 等の任意の VFM クラス名に汎用的に対応する。
+# ================================================================
+
+module QueryStream
+  # テンプレートコンパイラモジュール
+  module TemplateCompiler
+    # 変数展開パターン: = key または =key（行内に出現、ドット記法対応）
+    # (?<![=\w]) で width=40 や align=right 内の = を除外
+    VARIABLE_PATTERN = /(?<![=\w])=\s*([a-zA-Z_][a-zA-Z0-9_.]*)/
+
+    # 画像記法内の変数展開パターン: ![](key) / ![](= key)
+    # 名前付きキャプチャで gsub ブロック内の $N 上書き問題を回避
+    IMAGE_VAR_PATTERN = /!\[(?<alt>[^\]]*)\]\((?:=\s*)?(?<src>[^)]+)\)(?<attr>\{[^}]*\})?/
+
+    # 画像の拡張子（リテラル判定用）
+    IMAGE_EXTENSIONS = %w[png jpg jpeg webp gif svg].freeze
+
+    # VFM フェンス開始行: :::{.class-name} 形式
+    FENCE_OPEN_PATTERN = /\A:::\s*\{\.[\w-].*\}\s*\z/
+
+    # VFM フェンス終了行: 単独の :::
+    FENCE_CLOSE_PATTERN = /\A:::\s*\z/
+
+    module_function
+
+    # テンプレートにレコード群を流し込んでテキストを生成する
+    # @param template [String] テンプレートの内容
+    # @param records [Array<Hash>] データレコード群
+    # @param source_filename [String, nil] エラー報告用ファイル名
+    # @param line_number [Integer, nil] エラー報告用行番号
+    # @return [String] 展開後のテキスト
+    def render(template, records, source_filename: nil, line_number: nil)
+      lines = template.lines
+      validate_template_keys!(lines, records.first, source_filename:, line_number:) if records.any?
+
+      parts = classify_lines(lines)
+      return '' if records.empty?
+
+      # 最初と最後の動的行を特定し、leading / repeating / trailing に三分割する
+      first_dyn = parts.index { it[:type] == :dynamic }
+
+      # 動的行がないテンプレートは全行をそのまま一度だけ出力
+      unless first_dyn
+        return parts.map { |p|
+          p[:type] == :blank ? "\n" : p[:content]
+        }.compact.join
+      end
+
+      last_dyn = parts.rindex { it[:type] == :dynamic }
+
+      # --- Phase: フェンス行をrepeating範囲に取り込む ---
+      # 動的行の直前にフェンス開始行がある場合、repeating 範囲を前方に拡張する
+      # 動的行の直後にフェンス終了行がある場合、repeating 範囲を後方に拡張する
+      # これにより :::{.book-card} 〜 ::: が各レコードごとに反復される
+      first_dyn, last_dyn = expand_fence_range(parts, first_dyn, last_dyn)
+
+      leading   = parts[0...first_dyn]
+      repeating = parts[first_dyn..last_dyn]
+      trailing  = last_dyn + 1 < parts.size ? parts[(last_dyn + 1)..] : []
+
+      # テーブルテンプレート判定（区切り行 |---|…| の有無、またはデータ行が | で始まる）
+      table_mode = leading.any? { it[:type] == :static && it[:content]&.match?(/^\|[-|:\s]+\|/) } ||
+                   repeating.any? { it[:type] == :dynamic && it[:content]&.match?(/^\s*\|/) }
+
+      output = []
+
+      # leading: 静的ヘッダーを一度だけ出力
+      leading.each do |part|
+        case part
+        in { type: :static, content: } then output << content
+        in { type: :blank }            then output << "\n"
+        end
+      end
+
+      # repeating: レコードごとに動的行を展開
+      records.each_with_index do |record, idx|
+        output << "\n" if idx > 0 && !table_mode
+
+        repeating.each do |part|
+          case part
+          in { type: :dynamic, content: }
+            expanded = expand_line(content, record)
+            output << expanded if expanded
+          in { type: :fence_open, content: } then output << content
+          in { type: :fence_close, content: } then output << content
+          in { type: :static, content: }
+            output << content
+          in { type: :blank }
+            output << "\n" unless table_mode
+          end
+        end
+      end
+
+      # trailing: 末尾の静的行を一度だけ出力
+      trailing.each do |part|
+        case part
+        in { type: :static, content: } then output << content
+        in { type: :blank }            then output << "\n"
+        end
+      end
+
+      output.join
+    end
+
+    # テンプレート行を分類する
+    # @param lines [Array<String>] テンプレートの行リスト
+    # @return [Array<Hash>] 分類済み行リスト
+    def classify_lines(lines)
+      in_code_block = false
+      lines.map do |line|
+        stripped = line.strip
+
+        # コードブロックのフェンス行（``` で始まる行）を検出してトグル
+        if stripped.start_with?('```')
+          in_code_block = !in_code_block
+          next { type: :static, content: line }
+        end
+
+        # コードブロック内は変数展開せず static として扱う
+        if in_code_block
+          next { type: :static, content: line }
+        end
+
+        if stripped.empty?
+          { type: :blank }
+        elsif stripped.match?(FENCE_OPEN_PATTERN)
+          { type: :fence_open, content: line }
+        elsif stripped.match?(FENCE_CLOSE_PATTERN)
+          { type: :fence_close, content: line }
+        elsif contains_variable?(line)
+          { type: :dynamic, content: line }
+        else
+          { type: :static, content: line }
+        end
+      end
+    end
+
+    # VFM フェンス開始行かを判定する
+    # @param line [String] テンプレート行
+    # @return [Boolean]
+    def fence_open?(line) = line.strip.match?(FENCE_OPEN_PATTERN)
+
+    # VFM フェンス終了行かを判定する
+    # @param line [String] テンプレート行
+    # @return [Boolean]
+    def fence_close?(line) = line.strip.match?(FENCE_CLOSE_PATTERN)
+
+    # 動的行の前後にあるフェンス行を repeating 範囲に取り込む
+    # フェンス開始→（空行）→動的行 のパターンや
+    # 動的行→（空行）→フェンス終了 のパターンも考慮する
+    # @param parts [Array<Hash>] 分類済み行リスト
+    # @param first_dyn [Integer] 最初の動的行インデックス
+    # @param last_dyn [Integer] 最後の動的行インデックス
+    # @return [Array(Integer, Integer)] 拡張後の [first_dyn, last_dyn]
+    def expand_fence_range(parts, first_dyn, last_dyn)
+      # 前方拡張: フェンス開始行を取り込む（間に空行があっても可）
+      idx = first_dyn - 1
+      idx -= 1 if idx >= 0 && parts[idx][:type] == :blank
+      first_dyn = idx if idx >= 0 && parts[idx][:type] == :fence_open
+
+      # 後方拡張: フェンス終了行を取り込む（間に空行があっても可）
+      idx = last_dyn + 1
+      idx += 1 if idx < parts.size && parts[idx][:type] == :blank
+      last_dyn = idx if idx < parts.size && parts[idx][:type] == :fence_close
+
+      [first_dyn, last_dyn]
+    end
+
+    # 行に変数参照（= key）が含まれるかを判定する
+    # @param line [String] テンプレート行
+    # @return [Boolean]
+    def contains_variable?(line)
+      return true if line.match?(VARIABLE_PATTERN)
+      return true if line.match?(IMAGE_VAR_PATTERN) && image_has_variable?(line)
+
+      false
+    end
+
+    # 画像記法内に変数参照があるかを判定する
+    # @param line [String] テンプレート行
+    # @return [Boolean]
+    def image_has_variable?(line)
+      line.scan(IMAGE_VAR_PATTERN).any? do |(_, src, _)|
+        src = src.sub(/\A=\s*/, '').strip
+        !literal_image?(src)
+      end
+    end
+
+    # 画像パスがリテラル（拡張子あり）かを判定する
+    # @param src [String] 画像パス文字列
+    # @return [Boolean]
+    def literal_image?(src)
+      ext = File.extname(src).delete_prefix('.').downcase
+      IMAGE_EXTENSIONS.include?(ext)
+    end
+
+    # テンプレート行をレコードデータで展開する
+    # nil/空文字のキーがあれば行ごとスキップ（nil を返す）
+    # @param line [String] テンプレート行
+    # @param record [Hash] データレコード
+    # @return [String, nil] 展開後の行、またはスキップ時 nil
+    def expand_line(line, record)
+      result = line.dup
+
+      # 画像記法の展開（先に処理）
+      result = expand_images(result, record)
+      return nil unless result
+
+      # = key パターンの展開
+      result = expand_variables(result, record)
+      return nil unless result
+
+      result
+    end
+
+    # 画像記法内の変数を展開する
+    # @param line [String] テンプレート行
+    # @param record [Hash] データレコード
+    # @return [String, nil] 展開後の行、またはスキップ時 nil
+    def expand_images(line, record)
+      result = line.dup
+      skip = false
+
+      result.gsub!(IMAGE_VAR_PATTERN) do |match|
+        md   = Regexp.last_match
+        alt  = md[:alt]
+        src  = md[:src].sub(/\A=\s*/, '').strip
+        attr = md[:attr] || ''
+
+        if literal_image?(src)
+          # 拡張子ありはリテラルとしてそのまま出力
+          match
+        else
+          # 変数として展開（ドット記法対応）
+          value = resolve_nested_value(record, src)
+          if value.nil? || value.to_s.strip.empty?
+            skip = true
+            match # gsub のブロックからは文字列を返す必要がある
+          else
+            "![#{alt}](#{value})#{attr}"
+          end
+        end
+      end
+
+      skip ? nil : result
+    end
+
+    # = key パターンの変数を展開する（ドット記法対応）
+    # @param line [String] テンプレート行
+    # @param record [Hash] データレコード
+    # @return [String, nil] 展開後の行、またはスキップ時 nil
+    def expand_variables(line, record)
+      result = line.dup
+
+      result.gsub!(VARIABLE_PATTERN) do |_match|
+        key_path = $1
+        value = resolve_nested_value(record, key_path)
+        if value.nil? || value.to_s.strip.empty?
+          return nil # 行ごとスキップ
+        end
+        value.to_s
+      end
+
+      result
+    end
+
+    # ドット記法のキーパスをたどってネストされた値を取得する
+    # @param record [Hash] データレコード
+    # @param key_path [String] キーパス（例: "author.name"）
+    # @return [Object, nil] 値
+    def resolve_nested_value(record, key_path)
+      keys = key_path.split('.')
+      value = record
+      keys.each do |k|
+        return nil unless value.is_a?(Hash)
+        value = value[k.to_sym] || value[k.to_s]
+      end
+      value
+    end
+
+    # テンプレート内のキーがデータに存在するかを検証する
+    # @param lines [Array<String>] テンプレートの行リスト
+    # @param sample_record [Hash] サンプルレコード（最初の1件）
+    # @param source_filename [String, nil] エラー報告用ファイル名
+    # @param line_number [Integer, nil] エラー報告用行番号
+    def validate_template_keys!(lines, sample_record, source_filename: nil, line_number: nil)
+      return unless sample_record
+
+      location = source_filename ? "#{source_filename}:#{line_number}" : ''
+      available_keys = sample_record.keys
+      in_code_block = false
+
+      lines.each do |line|
+        stripped = line.strip
+
+        # コードブロック内はキー検証をスキップ
+        if stripped.start_with?('```')
+          in_code_block = !in_code_block
+          next
+        end
+        next if in_code_block
+
+        # = key パターン（ドット記法の場合はルートキーのみ検証）
+        line.scan(VARIABLE_PATTERN).each do |(key_path)|
+          root_key = key_path.split('.').first.to_sym
+          unless available_keys.include?(root_key)
+            msg = "テンプレートに存在しないキーが記述されています: #{key_path}"
+            QueryStream.logger.error("#{msg}(#{location})")
+            QueryStream.logger.error("  利用可能なキー: #{available_keys.join(', ')}")
+            raise UnknownKeyError, msg
+          end
+        end
+
+        # 画像記法内の変数
+        line.scan(IMAGE_VAR_PATTERN).each do |(_, src, _)|
+          src = src.sub(/\A=\s*/, '').strip
+          next if literal_image?(src)
+
+          root_key = src.split('.').first.to_sym
+          unless available_keys.include?(root_key)
+            msg = "テンプレートに存在しないキーが記述されています: #{src}"
+            QueryStream.logger.error("#{msg}(#{location})")
+            QueryStream.logger.error("  利用可能なキー: #{available_keys.join(', ')}")
+            raise UnknownKeyError, msg
+          end
+        end
+      end
+    end
+  end
+end