query-stream 1.2.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3f3bc788221f5c37fb1327f132501ec5fe4607e97f3e673ddbc2a32dfeeb188
-  data.tar.gz: 9111b6651c0596097399b9ffb46f8acea17928dd572f3a7af38ef167ddd6a037
+  metadata.gz: 399e9fb8aea90ac45fa0d7837c9891c7db5785b2bd81f6976c697eaa1d92f35c
+  data.tar.gz: 6587887f665b0a6ffde78dc029e2988bd647debcd92f0740766805b273f2ea61
 SHA512:
-  metadata.gz: 792bbe4684efb730c7d1f122ecdf6cff9dfbaa484254f7bf9830b47790978cba0a5150939845975e07fdd2ac9d24e464a66b2f17ee7085e4e8097f041fecb105
-  data.tar.gz: e3de3485e7fdb0f5bdb9d8f728ee2742387540c342f82a27765b80282d9dff1b337a680f419467440fdfbf9b201dfc27414d43110f0f37864e097de36d4f1c04
+  metadata.gz: 47693f041e99aa59784a2d50a55fca8d1aa50c18798a16862a946a5c6ed1faedeafbc89a4fa2113d80fb793d2ef97d031a2e578ba64ab695f42e2ae3c946013a
+  data.tar.gz: '095ed49dca369ea7420c037ddf95d77bbf2833b85d5b9a312393f31694632ee9744b6bfc319dfdabd55b5025fcd82f9921d0d2e80b3d988a407145e2902b3132'

data/CHANGELOG.md

@@ -0,0 +1,181 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+### Planned
+- パフォーマンス最適化
+- 追加のテンプレートスタイル
+
+## [1.4.0] - 2026-08-07
+
+### Removed
+- **`QueryStream.logger` と `Configuration#logger` を削除した** (`query_stream.rb`, `configuration.rb`, `query-stream.gemspec`): 下記の `logger.error` 撤去により、gem 内でロガーを読む箇所がゼロになった。設定できるのに何も起きない項目は、利用者に「ログ出力を制御できる」という誤った期待を持たせるだけなので残さない。`logger` gem への依存も外した。
+  - **破壊的変更**: `config.logger = ...` を書いているコードは削除が必要（設定しても何も起きないため、消すだけでよい）。
+  - 唯一の利用者である vivlio-starter は `QueryStream.configure` 自体を使っておらず、影響は無い。
+
+### Changed
+- **`UnknownKeyError` を構造化例外にし、gem 内に最後まで残っていた `logger.error` を撤去した** (`errors.rb`, `template_compiler.rb`): 1.1.0 で `logger.error`、1.2.0 で `logger.warn` を廃したが、`TemplateCompiler` がテンプレートのキーを検証する 2 箇所にだけ `logger.error` が残っており、「gem 内のログ出力を全廃した」という設計が最後まで通っていなかった。`UnknownKeyError` は属性を 1 つも持たなかったため、**呼び出し元は「利用できるキーの一覧」を受け取れず**、gem が直接吐くログに頼るしかなかったのが原因である。`key_path` / `available_keys` / `template_path` / `location` を持たせ、ログ出力を削除した。これで呼び出し元は「もしかして `=title`?」のような案内を自前で組み立てられる。
+  - `location`（記法が書かれた原稿の位置）と `template_path`（打ち間違いがある雛形の位置）は別物として持つ。**直すのは雛形**なので、記法の位置だけでは著者はファイルを開けない。
+  - `TemplateCompiler.render` に `template_path:` キーワードを追加した（任意・既定 `nil`）。
+- **必要な Ruby を 4.0 以上から 3.4 以上へ緩めた** (`query-stream.gemspec`): Ruby 4.0 固有の機能は使っていない。Prism のバージョン指定パースで全 14 ファイルを解析したところ 4.0.0 / 3.4.0 / 3.3.0 いずれも構文エラー 0 件で、実際の下限を決めていたのは `it`（暗黙ブロック引数・16 箇所）**単独**だった。`it` は 3.3 でも構文エラーにならず「`it` というメソッドの呼び出し」として通り、実行時に `NameError` になる——静的解析では見つからないので、Ruby 3.4.10 で実走して全テスト通過を確認している。コード変更はゼロ（gemspec 1 行のみ）。
+
+### Fixed
+- **壊れた入力で生の例外が外へ漏れていたのを直した**: いずれも「著者が用意した原稿・データが壊れている」という正当に起こりうる状況で、`QueryStream::Error` 系ではない例外が呼び出し元へ届いていた。呼び出し元は例外型で扱いを分けるため、生の `ArgumentError` / `NoMethodError` が出ると「どのファイルのどこが悪いか」を著者へ案内できない。
+  - **空のデータファイルで `NoMethodError`** (`data_resolver.rb`): YAML が `nil` を返すのを素通ししており、`TemplateCompiler` が `undefined method 'any?' for nil` で落ちていた。`load_records` は**常に配列を返す**契約に正規化した（`@return [Array<Hash>]` という既存の記述に実装を合わせた形）。レコードの配列でもハッシュでもない中身（スカラーだけの YAML）は、何が入っていたかを添えて `DataLoadError` にする。
+  - **不正な UTF-8 を含む原稿で `ArgumentError`** (`query_stream.rb`): `String#match?` も `lstrip` も不正バイト列に対して `invalid byte sequence in UTF-8` を投げるため、原稿に 1 バイトの壊れが混ざっただけで展開が丸ごと止まっていた。読めない行は**本文としてそのまま返す**。scrub して通す設計は採らない——gem が黙ってバイト列を書き換えると、著者が気付けない形で本文が変わる。
+  - **`scan` に本文を渡すと `ArgumentError` / `Errno::EISDIR`** (`query_stream.rb`): `scan` はパスと本文の両方を受け取る API なのに、引数を無条件で `File.exist?` へ渡していた。NUL バイトを含む本文で `path name contains null byte`、ディレクトリ名で `File.exist?` が true を返し `File.read` が `Errno::EISDIR` になっていた。パスとして成立しうる形（NUL・改行を含まず `MAX_PATH_BYTES` 以下で、かつ `File.file?`）だけを読み、判定自体の失敗も本文扱いに倒す。
+
+### Added
+- **堅牢性テストを整備した** (`test/robustness/`): 「正しく使ったとき正しく動くか」を見る既存のユニットテストとは別に、**想定外の入力・環境に対する振る舞い**を固定する 27 件を追加。守る不変条件は「gem の外へ出てよい例外は `QueryStream::Error` の系統だけ」。上記 3 件の修正はいずれもこのテストを書く過程で見つかったもの。
+  - `data_file_safety_test.rb` — `!ruby/object` 等の危険なタグ・壊れた YAML/JSON・空ファイル・レコードでない中身
+  - `broken_encoding_test.rb` — 不正な UTF-8 を含む原稿。**バイト列を書き換えずに返す**ことまで固定
+  - `scan_input_test.rb` — `scan` のパス／本文判定（NUL・改行・超長入力・ディレクトリ）
+  - `missing_source_test.rb` — データ／テンプレート不在時の例外属性と、1 行の失敗で全体を止めないこと。**当てずっぽうの hint を返さない**ことも固定
+  - `unreadable_file_test.rb` — 権限エラーは `DataLoadError` へ包まず `Errno::EACCES` のまま伝える（環境の問題とデータの問題は直し方が違うため）
+
+## [1.3.0] - 2026-07-12
+
+### Added
+- **`post_render` 後段フィルタコールバックを追加** (`lib/query_stream.rb`, `lib/query_stream/configuration.rb`): 1 記法の展開結果を、コンテキスト付きで呼び出し元へ通す汎用フックを新設。`QueryStream.render` / `render_query` に `post_render:` キーワードを追加し、`Configuration#post_render` からも指定できる。コールバックは `(text, context)` を受け取り、`context` は `source`（記法の論理名）・`data_file`（単複解決後の実パス）・`data_dir`・`template_path`・`query`・`location` を含む。戻り値が String ならそれを、String 以外（nil 含む）なら元の展開結果を採用する。gem 自身は用途を規定せず、画像パス解決などの呼び出し元固有の後処理を委譲できる。コールバック内の例外は握り潰さず伝播する（`render` の既存 rescue は `QueryStream::Error` のみ捕捉するため、それ以外の後処理例外の扱いは呼び出し元の責務）。
+
+## [1.2.2] - 2026-04-26
+
+### Fixed
+- **アンダースコア付き複合名の単数形変換が誤る問題を修正** (`lib/query_stream/singularize.rb`): `physics_books` が `physic_books` に変換されていた問題を修正。アンダースコアで分割し、末尾から複数形セグメントを探して単数化するよう変更。`people` は不規則変化として優先処理。`physics_books` → `physics_book`、`books_nested` → `book_nested` が正しく変換されるようになった。
+
+## [1.2.1] - 2026-04-20
+
+### Security
+- **`DataResolver.load_records` を `YAML.safe_load_file` に移行** (`lib/query_stream/data_resolver.rb`):
+  従来は `YAML.load_file(file_path, symbolize_names: true)` を使用しており、Psych のバージョンや将来のアップデートで `!ruby/object` などの Ruby オブジェクトタグが受理されてしまう可能性があった。
+  `permitted_classes: [Symbol, Time, Date, DateTime]` と `aliases: true` を明示的に指定する `YAML.safe_load_file` に置き換え、安全性を Psych バージョン非依存にした。
+  これにより悪意のあるデータファイル（`!ruby/object:Kernel {}` 等）を読み込ませて任意コード実行を試みる攻撃ベクトルを明示的に塞いだ。
+  なお Symbol が許可されているため `symbolize_names: true` の挙動は従来どおり維持される。
+
+### Added
+- **`QueryStream::DataLoadError` 新規例外クラス** (`lib/query_stream/errors.rb`):
+  `Psych::DisallowedClass` / `Psych::SyntaxError` / `JSON::ParserError` を呼び出し元に優しいメッセージ付きの `DataLoadError` に変換する。
+  `file_path` と `cause_error` 属性を持ち、呼び出し元で詳細なログ出力や i18n が可能。
+
+### Tests
+- **セキュリティテスト 7 件を追加** (`test/query_stream_test.rb`):
+  - `!ruby/object:Object {}` を含む YAML は `DataLoadError` で拒否
+  - `!ruby/struct:Point` / `!ruby/hash:MyCustomHash` も同様に拒否
+  - Symbol / Time / Date / DateTime は正常に読み込める
+  - YAML / JSON 構文エラーは `DataLoadError` に変換される
+  - 通常の YAML anchor / alias は正常に展開される（DoS 耐性の副次確認）
+
+## [1.2.0] - 2026-04-19
+
+### Fixed
+- **`NoResultWarning` / `AmbiguousQueryWarning` を構造化例外に変更し、gem 内の `logger.warn` 呼び出しを全廃** (`lib/query_stream.rb`, `lib/query_stream/errors.rb`): 1.1.0 で `logger.error` は廃止されていたが、`render_query` の一件検索分岐に `logger.warn("一件検索で該当なし(…): …")` / `logger.warn("一件検索で複数件ヒット(…): …")` が残存しており、呼び出し元（vivlio-starter 等）が `⚠️` プレフィックスや i18n を付与できない問題があった。`NoResultWarning` / `AmbiguousQueryWarning` に `query` / `location` （ambiguous は `count` も）属性を追加し、`logger.warn` 呼び出しを削除。新たに `QueryStream.render` / `render_query` に `on_warning:` コールバックを追加し、警告情報を構造化例外として呼び出し元へ委譲する。これにより gem 内のログ出力が完全になくなり、メッセージ構成・ログ出力・i18n はすべて呼び出し元の責務となった。
+
+## [1.1.0] - 2026-04-13
+
+### Fixed
+
+- **`TemplateNotFoundError` / `DataNotFoundError` を構造化例外に変更** (`lib/query_stream.rb`, `lib/query_stream/errors.rb`):
+  従来は `render_query` 内で `logger.error` によるログ出力を行ってから例外を raise していた。
+  これでは呼び出し元がメッセージフォーマットや言語（i18n）を制御できないため、
+  gem 内のログ出力を廃止し、例外クラスに `template_path`, `query`, `location`, `hint`
+  （`DataNotFoundError` は `expected_path`, `query`, `location`）の属性を追加。
+  メッセージ構成・ログ出力・i18n はすべて呼び出し元の責務とした。
+
+- **`render` 内で展開エラーをキャッチして後続の記法を継続展開するよう変更** (`lib/query_stream.rb`):
+  従来は1行の展開失敗で `render` 全体が中断されていた。
+  `render_query` の呼び出しを `rescue Error` で囲み、失敗した行は元の記法のまま残して
+  後続の QueryStream 記法の展開を継続するよう修正。
+  `on_error` コールバックを追加し、エラー情報を呼び出し元に通知できるようにした。
+
+- **`Singularize` で `People`（大文字）が `person` に変換されない問題を修正** (`lib/query_stream/singularize.rb`):
+  `people` パターンの正規表現に `/i` フラグを追加し、大文字小文字を問わず変換できるようにした。
+
+## [1.0.0] - 2026-03-21
+
+### 🎉 最初のメジャーリリース
+
+QueryStream 1.0.0 としてリリース！YAML/JSON データファイルとテンプレートファイルを組み合わせて、テキストコンテンツ内の QueryStream 記法を展開する汎用 Ruby ライブラリが完成しました。
+
+### ✅ 実績と品質保証
+- **vivlio-starter** プロジェクトで実稼働実績
+- **109 テストケース**、**395 アサーション**で網羅的品質保証
+- **VFM フェンス記法** 完全対応と実用性検証
+
+### 🚀 主要機能
+- QueryStream 記法の完全実装（源泉・抽出・ソート・件数・スタイル）
+- VFM フェンス記法対応（`:::{.class-name}` 〜 `:::`）
+- テンプレートコンパイラ（変数展開、画像記法、ネスト値アクセス）
+- 高度なデータ処理（フィルタリング、ソート、単数形化）
+- 柔軟な設定システム
+
+### 📚 ドキュメント整備
+- 詳細な README と具体例
+- 完全な CHANGELOG
+- vivlio-style での実装例
+
+### 🔧 技術的特徴
+- **Ruby 4.0+** モダン開発標準準拠
+- **Semantic Versioning** 準拠
+- 後方互換性保証
+
+## [0.3.0] - 2026-03-21
+
+### Added
+- VFM フェンス記法対応 (`:::{.class-name}` 〜 `:::`)
+- フェンス行が動的行を囲んでいる場合、フェンス行も repeating 範囲に含めて各レコードごとに反復出力
+- `{.book-card}`, `{.person-card}` 等の任意 VFM クラス名に汎用的に対応
+- フェンス記法関連のテストケースを追加 (12件)
+- ファイルドキュメントに VFM フェンス記法対応の説明を追加
+
+### Changed
+- `TemplateCompiler` に `FENCE_OPEN_PATTERN` / `FENCE_CLOSE_PATTERN` 定数を追加
+- `classify_lines` で `:fence_open` / `:fence_close` タイプを認識
+- `expand_fence_range` メソッドを新設し、repeating 範囲の拡張ロジックを実装
+
+### Fixed
+- QueryStream と vivlio-starter の VFM フェンス記法の相性問題を解決
+- フェンス行が一度しか出力されず、全レコードが1つのフェンスに押し込まれる問題を修正
+
+## [0.2.0] - Previous Release
+
+### Added
+- 複数スタイル対応 (`:full`, `:table` 等)
+- 高度なフィルタリング機能（範囲指定、不等値比較）
+- パフォーマンス最適化
+- エラーハンドリングの改善
+
+## [0.1.0] - Initial Release
+
+### Added
+- 基本的な QueryStream 記法の実装
+  - 源泉指定 (`= books`)
+  - フィルタリング (`tags=ruby`, `condition=晴`)
+  - ソート (`-title`, `+date`)
+  - 件数制限 (`5`)
+  - スタイル指定 (`:full`)
+- テンプレートコンパイラ機能
+  - 変数展開 (`= title`, `= author`)
+  - 画像記法の展開 (`![](cover)`)
+  - ネストされた値へのアクセス (`= author.name`)
+  - テーブル記法対応
+- データフィルタリングとソート機能
+  - 等値フィルタ (`tags=ruby`)
+  - AND/OR 条件 (`tags=ruby && beginner`, `tags=ruby, javascript`)
+  - 比較演算子 (`>=`, `<=`, `>`, `<`, `!=`)
+- データリゾルバー
+  - YAML/JSON ファイルの自動探索
+  - 複数形→単数形の自動テンプレート解決
+- 単数形化ユーティリティ (Singularize)
+  - 英語の複数形パターン対応
+  - 不規則名詞 (people → person)
+- 設定システム
+  - データディレクトリ、テンプレートディレクトリの設定
+  - ロガー設定
+- エラー処理
+  - データファイル不在エラー
+  - テンプレートファイル不在エラー
+  - 不明キーエラー

data/README.md

@@ -13,6 +13,8 @@ gem 'query-stream'
 bundle install
 ```
 
+Ruby 3.4 以上が必要です。
+
 ## 基本的な使い方
 
 ```ruby
@@ -20,9 +22,11 @@ require 'query_stream'
 
 # テキスト内の QueryStream 記法を展開
 source = File.read('contents/05-references.md')
-result = QueryStream.render(source)
+result = QueryStream.render(source, data_dir: 'data', templates_dir: 'templates')
 ```
 
+`data_dir` / `templates_dir` は後述の `configure` で既定値を決めておけば省略できます。
+
 ## QueryStream 記法
 
 ```
@@ -106,10 +110,66 @@ QueryStream.configure do |config|
   config.data_dir       = 'data'
   config.templates_dir  = 'templates'
   config.default_format = :md
-  config.logger         = Logger.new($stdout)
+  config.post_render    = ->(text, context) { text }
+end
+```
+
+## エラー・警告の扱い
+
+**この gem はメッセージを組み立てません。** どう表示するか、どの言語で出すか、そもそもログに残すかは、すべて呼び出し元が決めます。そのため展開時の出来事は、構造化された例外としてコールバックへ渡されます。
+
+```ruby
+QueryStream.render(
+  content,
+  data_dir:        'data',
+  templates_dir:   'templates',
+  source_filename: 'chapter.md',      # 位置情報（location）の表示に使います
+  on_error:        ->(e) { },         # 展開失敗。その行は元の記法のまま残ります
+  on_warning:      ->(w) { },         # 一件検索の該当なし／複数ヒット
+  post_render:     ->(text, ctx) { }  # 展開結果の後処理
+)
+```
+
+**1 行の失敗で全体は止まりません。** 失敗した行は元の記法のまま残り、後続の記法は展開され続けます。
+
+| 例外クラス | 属性 |
+|:---|:---|
+| `TemplateNotFoundError` | `template_path`, `query`, `location`, `hint` |
+| `DataNotFoundError` | `expected_path`, `query`, `location` |
+| `DataLoadError` | `file_path`, `cause_error` |
+| `UnknownKeyError` | `key_path`, `available_keys`, `template_path`, `location` |
+| `NoResultWarning` | `query`, `location` |
+| `AmbiguousQueryWarning` | `query`, `location`, `count` |
+
+前 4 つは `QueryStream::Error`、後 2 つは `QueryStream::Warning` を継承します。**gem の外へ出る例外はこの 2 系統だけ**です。壊れた YAML も、不正な UTF-8 を含む原稿も、生の `ArgumentError` や `NoMethodError` にはなりません。
+
+たとえば `UnknownKeyError` は「使えるキーの一覧」と「直すべき雛形のパス」まで持って届くので、呼び出し元で打ち間違いの案内を組み立てられます。`location` は記法が書かれた原稿の位置、`template_path` は直す雛形の位置で、**直すのは雛形のほう**です。
+
+```ruby
+on_error: lambda do |e|
+  next unless e.is_a?(QueryStream::UnknownKeyError)
+
+  keys = e.available_keys.map(&:to_s)
+  near = DidYouMean::SpellChecker.new(dictionary: keys).correct(e.key_path.split('.').first).first
+  puts "#{e.location} もしかして =#{near}?（#{e.template_path} / 使えるキー: #{keys.join(', ')}）"
+end
+```
+
+例外はファイル権限のみ扱いが異なり、`Errno::EACCES` のまま伝わります。環境の問題（`chmod` で直る）とデータの問題（中身を直す）は、対処が違うためです。
+
+### `post_render`
+
+展開結果を、その出どころの情報つきで受け取れます。gem 側は用途を規定しないので、画像パスの解決など固有の後処理を差し込めます。
+
+```ruby
+post_render: lambda do |text, context|
+  # context: source, data_file, data_dir, template_path, query, location
+  MyImageResolver.rewrite(text, context)
 end
 ```
 
+戻り値が `String` ならそれを、そうでなければ元の展開結果を採用します。
+
 ## ライセンス
 
 MIT License

data/RELEASE_NOTE.md

@@ -0,0 +1,61 @@
+# QueryStream リリースノート
+
+YAML / JSON のデータファイルとテンプレートを組み合わせて、文章中の 1 行記法を展開する Ruby ライブラリです。使い方は [README](README.md)、網羅的な変更履歴は [CHANGELOG](CHANGELOG.md) をご覧ください。
+
+新しい版から順に並べています。
+
+---
+
+## 1.4.0 — 2026-08-07
+
+**細かな不具合修正が中心のリリースです。** いずれも「著者が用意した原稿やデータが壊れている」という、実際に起こりうる場面で想定外の例外が漏れていた問題です。
+
+- **空のデータファイルで落ちなくなりました。** 空 YAML は例外ではなく空配列として扱います。レコードでない中身（スカラーだけの YAML など）は、何が入っていたかを添えて `DataLoadError` で知らせます
+- **壊れた文字が 1 バイト混ざっただけで展開が止まらなくなりました。** 読めない行は本文としてそのまま返します。gem が黙ってバイト列を書き換える（scrub する）設計は採っていません
+- **`scan` に本文を渡しても落ちなくなりました。** パスと本文の両方を受け取る API なのに、引数を無条件でファイルとして開こうとしていました
+- **`UnknownKeyError` が「使えるキーの一覧」と「直すべき雛形のパス」を持って届くようになりました。** これまでこの例外だけ属性が無く、キーの候補は gem が直接吐くログにしか出ていませんでした。`key_path` / `available_keys` / `template_path` / `location` を持たせ、**gem 内に最後まで残っていた `logger.error` を撤去**しています。呼び出し元は「もしかして `=title`?」のような案内を自前で組み立てられます
+- **必要な Ruby を 4.0 以上から 3.4 以上へ緩めました**（コード変更はゼロ、gemspec 1 行のみ）
+
+**破壊的変更が 1 つあります。** `QueryStream.logger` と `config.logger` を削除しました。上記の撤去で gem 内にロガーを読む箇所が無くなり、設定できるのに何も起きない項目になったためです。`config.logger = ...` と書いている箇所があれば、消してください（設定しても何も起きないので、消すだけで済みます）。`logger` gem への依存も外しました。
+
+あわせて、これらを二度と起こさないための**堅牢性テスト 27 件**を `test/robustness/` に追加しました。守る約束は 1 つ、**gem の外へ出てよい例外は `QueryStream::Error` の系統だけ**です。呼び出し元は例外の型で扱いを分けるため、生の `ArgumentError` が出ると「どのファイルのどこが悪いか」を著者へ案内できません。上の 3 件は、このテストを書く過程で見つかりました。
+
+ただし権限エラーだけは `Errno::EACCES` のまま伝えます。**環境の問題（`chmod` で直る）とデータの問題（中身を直す）は対処が違う**ためです。
+
+## 1.3.0 — 2026-07-12
+
+- **`post_render` 後段フィルタを追加しました。** 1 記法の展開結果を、コンテキスト付きで呼び出し元へ渡す汎用フックです。`context` には `source` / `data_file` / `data_dir` / `template_path` / `query` / `location` が入ります
+- gem 自身は用途を規定しません。画像パス解決などの呼び出し元固有の後処理を、gem に固有知識を持ち込まずに差し込めます
+
+## 1.2.2 — 2026-04-26
+
+- **`physics_books` が `physic_books` になる単数形変換の誤りを修正しました。** アンダースコアで分割し、末尾から複数形セグメントを探して単数化します（`physics_books` → `physics_book`、`books_nested` → `book_nested`）
+
+## 1.2.1 — 2026-04-20
+
+- **データファイルの読み込みを `YAML.safe_load_file` へ移行しました（セキュリティ）。** `permitted_classes: [Symbol, Time, Date, DateTime]` を明示し、`!ruby/object:Kernel {}` のような Ruby オブジェクトタグを読ませて任意コード実行を狙う経路を塞いでいます。安全性が Psych のバージョンに依存しなくなりました
+- **`DataLoadError` を追加しました。** `Psych::DisallowedClass` / `Psych::SyntaxError` / `JSON::ParserError` を、`file_path` と `cause_error` を持つ例外に変換します
+
+## 1.2.0 — 2026-04-19
+
+- **警告の `logger.warn` を全廃し、`on_warning:` コールバックで呼び出し元へ委譲しました。** `NoResultWarning` / `AmbiguousQueryWarning` に `query` / `location`（後者は `count` も）を持たせています
+- これにより、`⚠️` の付け方も i18n も呼び出し元で決められるようになりました
+
+> **補足**: このとき `TemplateCompiler` が `UnknownKeyError` を投げる経路にだけ `logger.error` が残っていました。1.4.0 で撤去し、**gem 内のログ出力はここで本当にゼロになりました**（設定項目 `config.logger` も同時に削除）。
+
+## 1.1.0 — 2026-04-13
+
+- **エラーを構造化例外へ移行しました。** `TemplateNotFoundError` に `template_path` / `query` / `location` / `hint`、`DataNotFoundError` に `expected_path` / `query` / `location` を持たせ、gem 内の `logger.error` を廃止しました
+- **1 行の展開失敗で全体が止まる問題を修正しました。** 失敗した行は元の記法のまま残し、後続の展開を続けます。`on_error:` コールバックで通知します
+- **`People`（大文字）が `person` に変換されない問題を修正しました**
+
+## 1.0.0 — 2026-03-21
+
+最初のメジャーリリースです。
+
+- QueryStream 記法の完全実装（源泉・抽出条件・ソート・件数・スタイル）
+- VFM フェンス記法対応（`:::{.book-card}` 〜 `:::`）。各レコードが個別のフェンスで囲まれて展開されます
+- テンプレートコンパイラ（変数展開・画像記法・ネスト値アクセス・表記法）
+- データリゾルバ（YAML / JSON の自動探索、複数形→単数形のテンプレート解決）
+- フィルタリング（等値・AND / OR・比較演算子）とソート
+- 設定システム（`data_dir` / `templates_dir` / `default_format` / `logger`）

data/lib/query_stream/command.rb

@@ -17,6 +17,7 @@ module QueryStream
 
       options do
         option '--version', 'Print version and exit'
+        option '--help', 'Print this message and exit'
       end
 
       # コマンド実行
@@ -28,12 +29,19 @@ module QueryStream
         end
       end
 
-      private
-
-      def print_usage
-        puts self.class.description
-        puts "Usage: query-stream [options]"
-        puts "  --version  Print version and exit"
+      # 使い方を表示する。
+      #
+      # public かつ `output:` を受ける形でなければならない。Samovar は引数の解析に
+      # 失敗すると、外から `error.command.print_usage(output: output)` を呼んで
+      # 使い方を出そうとする。private に置いていた頃は、そこで
+      # `private method 'print_usage' called` の NoMethodError になり、
+      # **`--help` と未知の引数がスタックトレースで落ちていた**。
+      # @param output [IO] 出力先（Samovar からはエラー出力が渡される）
+      def print_usage(output: $stdout)
+        output.puts self.class.description
+        output.puts 'Usage: query-stream [options]'
+        output.puts '  --version  Print version and exit'
+        output.puts '  --help     Print this message and exit'
       end
     end
   end

data/lib/query_stream/configuration.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
-require 'logger'
-
 # ================================================================
 # File: lib/query_stream/configuration.rb
 # ================================================================
 # 責務:
 #   QueryStream のグローバル設定を管理する。
-#   data_dir, templates_dir, default_format, logger の4項目。
+#   data_dir, templates_dir, default_format, post_render の4項目。
+#
+# ログ出力の設定は持たない。gem 自身がログを出さないためである
+# （失敗はすべて構造化例外として on_error / on_warning へ渡す）。
 # ================================================================
 
 module QueryStream
@@ -22,14 +23,16 @@ module QueryStream
     # @return [Symbol] スタイル省略時のデフォルト出力形式（:md / :html / :json）
     attr_accessor :default_format
 
-    # @return [Logger] ログ出力先
-    attr_accessor :logger
+    # 1 記法の展開結果を、コンテキスト付きで呼び出し元へ通す後段フィルタ。
+    # gem 自身は用途を規定しない（画像パス解決など呼び出し元固有の後処理を担わせる）。
+    # @return [Proc, nil] (text, context) -> String。String 以外を返した場合は元の展開結果を採用する
+    attr_accessor :post_render
 
     def initialize
       @data_dir       = 'data'
       @templates_dir  = 'templates'
       @default_format = :md
-      @logger         = Logger.new($stdout)
+      @post_render    = nil
     end
   end
 end

data/lib/query_stream/data_resolver.rb

@@ -77,8 +77,7 @@ module QueryStream
                                       symbolize_names: true)
                 end
 
-      records = [records] if records.is_a?(Hash)
-      records
+      normalize_records(records, file_path)
     rescue Psych::DisallowedClass => e
       raise DataLoadError.new(
         "データファイルに許可されていないクラス/タグが含まれています: #{e.message} (#{file_path})",
@@ -96,6 +95,30 @@ module QueryStream
       )
     end
 
+    # 読み込み結果をレコード配列へ正規化する。
+    #
+    # **常に配列を返すのが本メソッドの契約である。** 空のデータファイルは YAML が
+    # `nil` を返すため、素通しすると呼び出し先（TemplateCompiler）が
+    # `undefined method 'any?' for nil` で落ちる——データを空にしただけの著者に
+    # NoMethodError を見せることになる。
+    #
+    # 配列でもハッシュでもない中身（先頭が文字列や数値だけの YAML）は、
+    # レコード群として解釈しようがないので DataLoadError で理由を伝える。
+    # @return [Array<Hash>]
+    def normalize_records(records, file_path)
+      case records
+      when nil then []
+      when Hash then [records]
+      when Array then records
+      else
+        raise DataLoadError.new(
+          "データファイルはレコードの配列（またはハッシュ 1 件）である必要があります" \
+          "（#{records.class} が入っています）: #{file_path}",
+          file_path: file_path
+        )
+      end
+    end
+
     # 指定名ですべての拡張子を試行する
     # @param base_name [String] 拡張子なしファイル名
     # @param data_dir [String] データディレクトリ

data/lib/query_stream/errors.rb

@@ -51,7 +51,32 @@ module QueryStream
     end
   end
 
-  class UnknownKeyError  < Error; end    # テンプレート内に存在しないキー
+  # テンプレートに、データレコードが持たないキーが書かれている
+  #
+  # 「どのキーが無いか」だけでなく「代わりに何が使えるか」「どのファイルを直すか」まで
+  # 属性で渡す。呼び出し元はこれを使って「もしかして =author?」のような案内を組み立てられる。
+  # 属性が無かった頃はこのクラスだけが gem 内で logger.error を呼んでおり、
+  # 利用できるキーの一覧を呼び出し元が受け取れなかった。
+  #
+  # location（記法の位置）と template_path（雛形の位置）は別物である。
+  # 直すのは雛形なので、記法の位置だけでは著者はファイルを開けない。
+  #
+  # @attr_reader key_path [String] テンプレートに書かれていたキー（"author.name" 等）
+  # @attr_reader available_keys [Array<Symbol>] レコードが実際に持つキー
+  # @attr_reader template_path [String, nil] 打ち間違いがあるテンプレートのパス
+  # @attr_reader location [String] 記法が書かれていたソースファイル名と行番号
+  class UnknownKeyError < Error
+    attr_reader :key_path, :available_keys, :template_path, :location
+
+    def initialize(msg = nil, key_path: nil, available_keys: [], template_path: nil, location: nil)
+      super(msg || "テンプレートに存在しないキーが記述されています: #{key_path}")
+      @key_path       = key_path
+      @available_keys = Array(available_keys)
+      @template_path  = template_path
+      @location       = location
+    end
+  end
+
   class InvalidDateError < Error; end    # 無効な日付
 
   # データファイルの読み込みに失敗した

data/lib/query_stream/template_compiler.rb

@@ -51,10 +51,11 @@ module QueryStream
     # @param records [Array<Hash>] データレコード群
     # @param source_filename [String, nil] エラー報告用ファイル名
     # @param line_number [Integer, nil] エラー報告用行番号
+    # @param template_path [String, nil] エラー報告用テンプレートパス（キーの打ち間違いはここを直す）
     # @return [String] 展開後のテキスト
-    def render(template, records, source_filename: nil, line_number: nil)
+    def render(template, records, source_filename: nil, line_number: nil, template_path: nil)
       lines = template.lines
-      validate_template_keys!(lines, records.first, source_filename:, line_number:) if records.any?
+      validate_template_keys!(lines, records.first, source_filename:, line_number:, template_path:) if records.any?
 
       parts = classify_lines(lines)
       return '' if records.empty?
@@ -306,7 +307,8 @@ module QueryStream
     # @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)
+    # @param template_path [String, nil] エラー報告用テンプレートパス
+    def validate_template_keys!(lines, sample_record, source_filename: nil, line_number: nil, template_path: nil)
       return unless sample_record
 
       location = source_filename ? "#{source_filename}:#{line_number}" : ''
@@ -327,10 +329,7 @@ module QueryStream
         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
+            raise UnknownKeyError.new(key_path:, available_keys:, template_path:, location:)
           end
         end
 
@@ -341,10 +340,7 @@ module QueryStream
 
           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
+            raise UnknownKeyError.new(key_path: src, available_keys:, template_path:, location:)
           end
         end
       end

data/lib/query_stream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QueryStream
-  VERSION = '1.2.2'
+  VERSION = '1.4.0'
 end

data/lib/query_stream.rb

@@ -29,6 +29,10 @@ module QueryStream
   # 行頭 = の直後に英数字/ハイフン/アンダースコアのデータ名（スペースは任意）
   QUERY_STREAM_PATTERN = /^=\s*([a-zA-Z][a-zA-Z0-9_-]*)(?:\s*\|.*)?$/
 
+  # これを超える長さの引数はパスとみなさず本文として扱う（scan の path/content 判定）。
+  # 主要な OS の PATH_MAX は 4096 前後で、それより長い「パス」は実在しない。
+  MAX_PATH_BYTES = 4096
+
   class << self
     # グローバル設定を返す
     # @return [Configuration]
@@ -42,12 +46,6 @@ module QueryStream
       yield(configuration)
     end
 
-    # ロガーへのショートカット
-    # @return [Logger]
-    def logger
-      configuration.logger
-    end
-
     # テキストコンテンツ内の QueryStream 記法をすべて展開する
     # 1行の展開に失敗しても残りの行の処理を継続する。
     # エラー情報は例外の属性として呼び出し元に委ねる（gem 内ではログ出力しない）。
@@ -57,10 +55,13 @@ module QueryStream
     # @param templates_dir [String, nil] テンプレートディレクトリ（nil時はconfigを使用）
     # @param on_error [Proc, nil] エラー時コールバック。|exception| を受け取る。省略時は何もしない。
     # @param on_warning [Proc, nil] 警告時コールバック。|warning| を受け取る。省略時は何もしない。
+    # @param post_render [Proc, nil] 展開結果の後段フィルタ。(text, context) -> String。省略時は configuration.post_render を使う。
     # @return [String] 展開後のテキストコンテンツ
-    def render(content, source_filename: nil, data_dir: nil, templates_dir: nil, on_error: nil, on_warning: nil)
+    def render(content, source_filename: nil, data_dir: nil, templates_dir: nil, on_error: nil, on_warning: nil,
+               post_render: nil)
       data_dir      ||= configuration.data_dir
       templates_dir ||= configuration.templates_dir
+      post_render   ||= configuration.post_render
 
       lines = content.lines
       result = []
@@ -70,7 +71,7 @@ module QueryStream
         line_number = idx + 1
 
         # コードブロック内はスキップ
-        if line.lstrip.start_with?('```')
+        if code_fence?(line)
           in_code_block = !in_code_block
           result << line
           next
@@ -82,10 +83,10 @@ module QueryStream
         end
 
         # QueryStream 記法の検出
-        if line.match?(QUERY_STREAM_PATTERN)
+        if query_line?(line)
           begin
             expanded = render_query(
-              line.chomp, line_number:, source_filename:, data_dir:, templates_dir:, on_warning:
+              line.chomp, line_number:, source_filename:, data_dir:, templates_dir:, on_warning:, post_render:
             )
             result << expanded << "\n"
           rescue Error => e
@@ -107,8 +108,10 @@ module QueryStream
     # @param source_filename [String, nil] ソースファイル名
     # @param data_dir [String, nil] データディレクトリ
     # @param templates_dir [String, nil] テンプレートディレクトリ
+    # @param post_render [Proc, nil] 展開結果の後段フィルタ。(text, context) -> String
     # @return [String] 展開後のテキスト
-    def render_query(query, line_number: nil, source_filename: nil, data_dir: nil, templates_dir: nil, on_warning: nil)
+    def render_query(query, line_number: nil, source_filename: nil, data_dir: nil, templates_dir: nil, on_warning: nil,
+                     post_render: nil)
       data_dir      ||= configuration.data_dir
       templates_dir ||= configuration.templates_dir
       location = source_filename ? "#{source_filename}:#{line_number}" : "行#{line_number}"
@@ -178,26 +181,42 @@ module QueryStream
       template_content = File.read(template_path, encoding: 'utf-8')
 
       # --- Phase: Render ---
-      TemplateCompiler.render(template_content, records, source_filename:, line_number:)
+      rendered = TemplateCompiler.render(template_content, records, source_filename:, line_number:, template_path:)
+
+      # --- Phase: Post-render filter ---
+      # 展開結果を呼び出し元の後段フィルタへ通す（画像パス解決など gem 外の後処理）。
+      # コールバックが String 以外を返した場合は安全側に倒して元の展開結果を採用する。
+      return rendered unless post_render
+
+      context = {
+        source:        parsed[:source],   # 記法に書かれた論理名（例: "physics_book"）
+        data_file:     data_file,          # 単複解決後の実パス（例: "data/physics_books.yml"）
+        data_dir:      data_dir,
+        template_path: template_path,
+        query:         query,
+        location:      location            # "filename:line" 形式
+      }
+      result = post_render.call(rendered, context)
+      result.is_a?(String) ? result : rendered
     end
 
     # テキスト内の QueryStream 記法を検出してリストを返す
     # @param path_or_content [String] ファイルパスまたはテキストコンテンツ
     # @return [Array<String>] 検出された QueryStream 記法のリスト
     def scan(path_or_content)
-      content = File.exist?(path_or_content) ? File.read(path_or_content, encoding: 'utf-8') : path_or_content
+      content = readable_file?(path_or_content) ? File.read(path_or_content, encoding: 'utf-8') : path_or_content
       lines = content.lines
       queries = []
       in_code_block = false
 
       lines.each do |line|
-        if line.lstrip.start_with?('```')
+        if code_fence?(line)
           in_code_block = !in_code_block
           next
         end
         next if in_code_block
 
-        queries << line.chomp if line.match?(QUERY_STREAM_PATTERN)
+        queries << line.chomp if query_line?(line)
       end
 
       queries
@@ -205,6 +224,50 @@ module QueryStream
 
     private
 
+    # その行を QueryStream 記法として扱うか。
+    #
+    # **不正な UTF-8 を含む行は記法として解釈しない。** `match?` はそういう行に
+    # `ArgumentError: invalid byte sequence in UTF-8` を投げるので、素通しにすると
+    # 原稿に 1 バイトの壊れが混ざっただけで展開が丸ごと止まる。
+    # ここでバイト列を書き換えて（scrub して）通す手もあるが採らない——gem が黙って
+    # 原稿のバイト列を変えると、著者が気付けない形で本文が変わる。
+    # 記法として読めない行は本文として、そのまま返すのが正しい。
+    #
+    # EncodingError と ArgumentError の両方を捕まえるのは意図的である。壊れたバイト列に
+    # Ruby がどちらを投げるかはメソッド次第で（match? / 先頭破損の lstrip は ArgumentError、
+    # strip は Encoding::CompatibilityError）、その差で展開が止まってはならない。
+    def query_line?(line)
+      line.match?(QUERY_STREAM_PATTERN)
+    rescue EncodingError, ArgumentError
+      false
+    end
+
+    # コードフェンスの開始/終了行か。
+    # `lstrip` も不正な UTF-8 で ArgumentError を投げるので、query_line? と同じく
+    # 「読めない行は本文」へ倒す。ここを素通しにすると、記法判定だけ守っても
+    # 手前のフェンス判定で落ちる。
+    def code_fence?(line)
+      line.lstrip.start_with?('```')
+    rescue EncodingError, ArgumentError
+      false
+    end
+
+    # 引数をファイルパスとして読むべきか。
+    #
+    # `scan` はパスと本文のどちらも受け取る API なので、本文をそのまま
+    # `File.exist?` へ渡すと壊れる——NUL バイトを含めば `ArgumentError`、
+    # ディレクトリなら「存在する」と判定されて `File.read` が `Errno::EISDIR` を出す。
+    # パスとして成立しうる形だけを先に選別し、判定自体の失敗も本文扱いに倒す。
+    def readable_file?(str)
+      s = str.to_s
+      return false if s.empty? || s.include?("\0") || s.include?("\n")
+      return false if s.bytesize > MAX_PATH_BYTES
+
+      File.file?(s)
+    rescue ArgumentError, SystemCallError
+      false
+    end
+
     # テンプレートファイルパスを解決する
     # @param singular_name [String] 単数形のデータ名
     # @param style [String, nil] スタイル名

data/query-stream.gemspec

@@ -17,15 +17,16 @@ Gem::Specification.new do |spec|
   spec.metadata['source_code_uri'] = 'https://github.com/Atelier-Mirai/query-stream'
   spec.metadata['changelog_uri']   = 'https://github.com/Atelier-Mirai/query-stream/blob/master/CHANGELOG.md'
 
-  spec.required_ruby_version = '>= 4.0'
+  spec.required_ruby_version = '>= 3.4'
 
-  spec.files = Dir.glob('{lib,bin}/**/*') + %w[README.md LICENSE Gemfile query-stream.gemspec]
+  spec.files = Dir.glob('{lib,bin}/**/*') +
+               %w[README.md CHANGELOG.md RELEASE_NOTE.md LICENSE Gemfile query-stream.gemspec]
   spec.bindir        = 'bin'
   spec.executables   = ['query-stream']
   spec.require_paths = ['lib']
 
   # Runtime dependencies
-  spec.add_dependency 'logger'
+  # logger への依存は 1.4.0 で外した。gem 自身はログを出さず、失敗は構造化例外で伝える。
   spec.add_dependency 'samovar', '~> 2.1'
 
   # Development dependencies

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query-stream
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Atelier Mirai
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: logger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: samovar
   requirement: !ruby/object:Gem::Requirement
@@ -88,9 +74,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
+- RELEASE_NOTE.md
 - bin/query-stream
 - lib/query_stream.rb
 - lib/query_stream/command.rb
@@ -117,14 +105,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: QueryStream - YAML/JSON data renderer with template expansion
 test_files: []