query-stream 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 399e9fb8aea90ac45fa0d7837c9891c7db5785b2bd81f6976c697eaa1d92f35c
-  data.tar.gz: 6587887f665b0a6ffde78dc029e2988bd647debcd92f0740766805b273f2ea61
+  metadata.gz: '0386ceba9bb9c31fb12bc7d02a7ef3ab23e1df189738e496e6bca25dd14b1cc9'
+  data.tar.gz: 1bc4884b4426a0bd2bd76ffa5c1f865742857905f7ba2c4dd2a85e57c1b5aaab
 SHA512:
-  metadata.gz: 47693f041e99aa59784a2d50a55fca8d1aa50c18798a16862a946a5c6ed1faedeafbc89a4fa2113d80fb793d2ef97d031a2e578ba64ab695f42e2ae3c946013a
-  data.tar.gz: '095ed49dca369ea7420c037ddf95d77bbf2833b85d5b9a312393f31694632ee9744b6bfc319dfdabd55b5025fcd82f9921d0d2e80b3d988a407145e2902b3132'
+  metadata.gz: 9157468004852779de4ceb88f3ee7cf248ab2c88da7a97b6a2126831f9eaf2e24016909cea8283ac11bbdcbd909da15d576fd121cfea08403f832e4d996afb48
+  data.tar.gz: 1a92018c0677b067a487d07a51c6f337daa7bdb66ec3282aa0e75fec2e2f402ba090c23d02a0ec1f5746ecd4b5fb17c74137a4114793fea626dc251dd55c6481

data/CHANGELOG.md

@@ -10,6 +10,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - パフォーマンス最適化
 - 追加のテンプレートスタイル
 
+## [Unreleased]
+
+## [1.5.0] - 2026-11-01
+
+### Added
+- **値の無い項目の部分だけを消せるようにした** (`template_compiler.rb`): 変数が 2 つ以上ある行は、区切り（`／`・`・`・`、`・`，`・`,` と、前後に空白のある ` / `）と、変数を含む括弧（`（…）`・`(…)`）で部品に分け、値の無い変数を含む部品だけを、区切りを詰めて消す。`= author.name 著／= publisher／= year 年` は、発行年の分からない本でも `高橋征義 著／SBクリエイティブ` と出る（これまでは著者まで行ごと消えていた）。`= author.name 著（= year年）` も、発行年が無ければ `高橋征義 著` になる。部品が 1 つも残らなければ、今までどおり行ごと消す。すべての値がそろった行の出力は変わらない。
+  - 変数が 1 つだけの行と、表の行（`|` で始まる行）は今までどおり行ごと消す（セルを消すと列がずれる）。
+  - 行頭の Markdown の目印（`- `・`1. `・`> `・`# `）は、先頭の部品が消えても残す。
+  - 空白なしの半角の `/` は区切りにせず（URL を割らない）、`]` の直後の括弧（リンク先）も部品にしない。
+- **抽出条件の数を、アンダースコアで桁区切りして書けるようにした** (`query_stream_parser.rb` / `filter_engine.rb`): `population>=9_000_000` や `population=900_0000..` のように書ける。Ruby の数値リテラルと同じく区切りは数字と数字のあいだにだけ置け、区切る位置は問わない（万の位で区切る `900_0000` も書ける）。比較（`>=` など）・範囲（`..`）・主キー検索に加え、等値（`=`）でも区切りを外して比べる。等値ではデータ側の値からも区切りを外すので、データに `"2024_01"` のような文字列があっても同じ綴りの条件で一致する。`snake_case` のような数でない値のアンダースコアはそのまま残す。
+- **日付を和暦（`R06-01-01`）でも書けるようにした** (`filter_engine.rb`): データでも抽出条件でも、西暦の `2024-01-01` と同じ日付として比べ、並べ替える。元号は頭文字（M・T・S・H・R）で書き、年は 1 桁でもよい（`R6-01-01`）。等値（`=`）でも和暦と西暦を同じ日として扱う。変換は `Date.jisx0301` に任せた——`Date.parse` は `"R06-01-01"` を 2006-01-01 と読み違えるため使えない。元号の境目は検査しない（`H31-05-01` も 2019-05-01 として読む）。存在しない日（`R06-02-30`）は、西暦と同じく `InvalidDateError` になる。
+
+- **抽出条件に `OR` / `or` を足した** (`query_stream_parser.rb` / `filter_engine.rb`): `tags=ruby OR year>=2020` のように、別の項目の条件もつなげる。AND は OR より強く結び付き、`a=1 AND b=2 OR c=3` は「a かつ b」または「c」になる。2 件目以降の項目名は省ける（`tags=ruby OR go`）。`||` は記法の区切りの `|` と衝突するので扱わない。前後に空白のある `OR` / `or` は区切りになるので、抽出条件の値に書けなくなった（`title=Rock or Pop`）。値だけの主キー検索（`= book | Rock or Pop`）は今までどおり 1 つの検索語として扱う。
+
+### Fixed
+- **項目名を省いた AND が OR として動いていた** (`query_stream_parser.rb`): `tags=ruby AND beginner` は、`ruby` と `beginner` の両方を含むレコードを選ぶ仕様だが、値を前の条件の値リストへ足していたため、どちらかを含むレコードを選んでいた。別の条件として組み立てる。誤った動きを期待していたテストも直した。
+- **比較とソートの対象の項目に値が無いレコードや比較できない値があると、`ArgumentError` が `render` の外へ出ていた** (`filter_engine.rb`): `on_error` にも渡らず、展開全体が止まった。比較では該当のレコードを除き、ソートでは最も多い種類の値を比べ、それ以外の値と値が無いレコードを昇順でも降順でも末尾に置く。
+- **両端を比較できない範囲で `ArgumentError` が出ていた** (`query_stream_parser.rb` / `filter_engine.rb`): `year=2020..abc` は `Range` を作れない。文字列の値として扱い、どのレコードにも一致しない。
+- **省ける項目が最初の 1 件に無いと、打ち間違いとして止まっていた** (`template_compiler.rb`): テンプレートのキーを確かめるとき、最初の 1 件のキーしか見ていなかった。1 冊目に `year` が無いだけで `UnknownKeyError` になり、値の無い項目を消す仕組みが働く前に止まった。どれか 1 件にあるキーは正しいキーとみなす。どの件にも無いキーは、今までどおり打ち間違いとして知らせる。
+- **日付の範囲指定が 1 件も返さなかった** (`filter_engine.rb`): `date=2024-06-01..2024-06-30` のような範囲は、両端が文字列のまま比べられ、日付に直したデータの値を含まなかった。両端も比較用にそろえてから判定する。数の範囲は両端が最初から数なので影響を受けていなかった。
+- **昇順ソートの書き方が README に無かった** (`README.md`): 例に並ぶのは降順（`-title`）だけで、昇順の `+title` はどこにも出てこない。実装は昇順を持っている——出口が塞がっていただけである。
+
+  自然に思いつくのは符号を付けない `= books | title` のほうだが、これは**主キー検索**として解釈され、該当なしの警告とともに何も展開されない（`= book | 楽しいRuby` と綴りが同じで、符号の有無だけが見分ける手掛かりになっている）。警告は出るので黙って壊れはしないが、書いた本人は「ソートしたつもり」なので、読んで気づける場所に書いておく必要があった。例へ `+title` / `-year` を足し、符号が必須である理由も添えた。
+
+- **一度も実行されない分岐が残っていた** (`query_stream_parser.rb`): `parse_sort` は符号を省いた `title` を昇順として扱う分岐（`/\A?(.+)\z/`）を持ち、コメントも受け付ける綴りとして `"title"` を挙げていた。しかし振り分け側（`parse_segment`）は `/\A[+-][a-zA-Z_]/` に一致した綴りしか渡さないため、**符号なしはここへ届かない**。
+
+  素の名前を昇順にすると主キー検索と区別が付かなくなるので、**いまの仕様のほうが正しい**。分岐とコメントが古かったので、符号が必須であることを前提に書き直した。挙動は変えていない（`+` / `-` の両方を実測で確認）。
+
+### Changed
+- **対応 Ruby を 3.4.10 / 4.0.9 にした**。4.0.9 は 2026-10-23 公開。
+- **依存を最新へ上げた**: Minitest → 6.0.6、samovar 2.4.1 → 2.5.1、rake 13.3.1 → 13.4.2。gemspec の minitest は `~> 5.22` から `>= 5.22` へ緩めた——5 系に固定する理由が無く、6 でも 158 件すべて通る（`stub` / `mock` を使っていないため、6 での `minitest/mock` 分離の影響も受けない）。
+- **rubocop を入れた**（`.rubocop.yml`・`rake rubocop`・CI）。見るのは `Lint` と `Security` だけで、引用符や行数は見ない。他の 2 つの gem と同じ構えである。現状 0 件。
+- **README と CHANGELOG の「vivlio-style」を「Vivlio Starter」にした**。製品名を崩した綴りだった。
+
 ## [1.4.0] - 2026-08-07
 
 ### Removed
@@ -115,7 +149,7 @@ QueryStream 1.0.0 としてリリース！YAML/JSON データファイルとテ
 ### 📚 ドキュメント整備
 - 詳細な README と具体例
 - 完全な CHANGELOG
-- vivlio-style での実装例
+- Vivlio Starter での実装例
 
 ### 🔧 技術的特徴
 - **Ruby 4.0+** モダン開発標準準拠

data/README.md

@@ -38,12 +38,118 @@ result = QueryStream.render(source, data_dir: 'data', templates_dir: 'templates'
 ```
 = books                           # 全件展開
 = books | tags=ruby               # タグで絞り込み
+= books | +title                  # タイトルの昇順
+= books | -year                   # 発行年の降順
 = books | tags=ruby | -title | 5  # 絞り込み＋降順ソート＋5件
+= prefectures | population>=9_000_000  # 数は _ で桁を区切れる（900_0000 も可）
+= weather_reports | date>=R06-01-01    # 日付は西暦（2024-01-01）でも和暦でも書ける
 = book | 楽しいRuby               # 主キーで一件検索
 = books | :full                   # fullスタイルで展開
 ```
 
-### 具体例：vivlio-style での書籍データ展開
+**ソートには符号を必ず付けてください**（`+` が昇順、`-` が降順）。符号を省いた
+`= books | title` はソートではなく**主キー検索**として扱われ、該当なしの警告とともに
+何も展開されません。`= book | 楽しいRuby` のような一件検索と綴りが同じになるため、
+符号の有無で見分けています。
+
+ソートでは、最も多い種類の値（数・日付・文字列）を比べます。値が無いレコードと、それ以外の
+種類の値のレコードは、昇順でも降順でも末尾に置きます。
+
+日付は、データでも抽出条件でも `2024-01-01`（西暦）か `R06-01-01`（和暦）で書きます。
+和暦の元号は頭文字で書き（`M` 明治・`T` 大正・`S` 昭和・`H` 平成・`R` 令和）、年は 1 桁でも
+構いません（`R6-01-01`）。どちらで書いても同じ日付として比べ、並べ替えます。
+
+### 指定の順序
+
+`|` で区切った指定は、省略しても、順序を入れ替えても構いません。形で種類を判別します。
+
+| 形 | 種類 |
+|---|---|
+| `:full`・`:card.html` | スタイル |
+| `+title`・`-title` | ソート |
+| `tags=ruby`・`year>=2020` のように演算子を含むもの | 抽出条件 |
+| 正の整数 | 件数 |
+| それ以外の値 | 主キー検索 |
+
+単数形のデータ名に続く最初の指定は、数でも主キー検索として扱います（`= prefecture | 13`）。
+
+### 抽出条件
+
+| 書き方 | 意味 |
+|---|---|
+| `tags=ruby`・`tags==ruby` | 等しい |
+| `tags=ruby, go` | どちらかに等しい（OR） |
+| `tags!=ruby` | 等しくない |
+| `tags!=ruby, go` | どちらにも等しくない |
+| `year>2020`・`year>=2020` | より大きい・以上 |
+| `year<2020`・`year<=2020` | より小さい・以下 |
+| `year=2020..2024` | 2020 以上 2024 以下 |
+| `year=2020...2024` | 2020 以上 2024 未満 |
+| `year=2020..` | 2020 以上 |
+| `year=..2024` | 2024 以下 |
+| `year=...2024` | 2024 未満 |
+| `tags=ruby AND year>=2020` | 両方を満たす（`and`・`&&` も同じ） |
+| `tags=ruby AND beginner` | `ruby` と `beginner` の両方を含む（2 件目以降の項目名は省ける） |
+| `tags=ruby OR year>=2020` | どちらかを満たす（`or` も同じ） |
+| `tags=ruby OR go` | どちらかを含む（2 件目以降の項目名は省ける） |
+
+等しいかどうかを調べるとき、データの値が配列やカンマ区切りの文字列なら、要素のどれかが一致すれば条件を満たします。`tags: [ruby, web]` は `tags=ruby` に一致します。
+
+AND は OR より強く結び付きます。`tags=ruby AND year>=2020 OR tags=go` は、「`ruby` で 2020 年以降」または「`go`」を選びます。
+
+前後に空白のある `AND`・`and`・`OR`・`or`・`&&` は区切りとして扱うので、値には書けません。`||` は記法の区切りの `|` と重なるので使えません。
+
+比較（`>`・`>=`・`<`・`<=`）と範囲では、値が無いレコードと、比較できない値のレコード（数と比べるときの `不明` など）を除きます。
+
+### 一件検索
+
+値だけを書くと、主キーで検索します。主キーとして調べるのは `id`・`no`・`code`・`slug`・`name`・`title` です。
+
+```
+= book | 楽しいRuby    # title が一致するレコード
+= post | hello-world   # slug が一致するレコード
+```
+
+一致するレコードが無ければ `NoResultWarning` を通知し、何も展開しません。複数あれば `AmbiguousQueryWarning` を通知し、一致したレコードをすべて展開します。
+
+### ファイルの探し方
+
+データファイルは `data_dir` から次の順に探します。拡張子は `.yml`・`.yaml`・`.json` の順に試します。
+
+1. 書いたままの名前（`books`）
+2. 末尾に `s` を付けた名前（`book` → `books`）
+3. 単数形にした名前（`books` → `book`）
+
+テンプレートは `templates_dir` にある、単数形の名前のファイルを使います。
+
+| 記法 | テンプレート |
+|---|---|
+| `= books` | `_book.md` |
+| `= books \| :full` | `_book.full.md` |
+| `= books \| :card.html` | `_book.card.html` |
+
+拡張子を書かないときの形式は、`config.default_format` で変更できます。
+
+### テンプレートの書き方
+
+| 書き方 | 意味 |
+|---|---|
+| `= key`・`=key` | キーの値を展開する |
+| `= author.name` | ネストした値を展開する |
+| `![](cover)`・`![](= cover)` | 画像のパスをキーの値で展開する |
+| `![](logo.png)` | 拡張子のあるパスはそのまま出力する |
+
+変数を含む行はレコードごとに繰り返し、含まない行は 1 回だけ出力します。表は次のように書くと、見出しが 1 回だけ出力されます。
+
+```markdown
+| 書名 | 著者 |
+|---|---|
+| = title | = author.name |
+```
+
+コードブロック（` ``` `）の中の記法は展開しません。
+
+### 具体例：Vivlio Starter での書籍データ展開
 
 #### データファイル例 (`data/books.yml`)
 
@@ -98,11 +204,55 @@ Rubyを楽しく学べる入門書。
 C言語の定番入門書。
 :::
 
+
 ---
 ```
 
 VFMフェンス記法（`:::{.book-card}`）にも対応しており、各レコードが個別のフェンスで囲まれて展開されます。
 
+### 値の無い項目
+
+値が無い（キーが無い・空の）項目を含む行は、行ごと出力しません。項目によって情報量の
+違うデータにも、同じテンプレートが使えます。
+
+1 行に変数が 2 つ以上ある行では、**値の無い項目の部分だけ**を消します。行は区切り
+（`／`・`・`・`、`・`，`・`,` と、前後に空白のある ` / `）と、変数を含む括弧（`（…）`・`(…)`）で
+部品に分かれ、値の無い変数を含む部品だけが、区切りを詰めて消えます。変数に付いた言葉
+（`著`・`年`）は、変数と一緒に残るか、一緒に消えます。
+
+```markdown
+= author.name 著／= publisher／= year 年
+= author.name 著（= year年）
+```
+
+| データ | 1 行目 | 2 行目 |
+|---|---|---|
+| 全部ある | 高橋征義 著／SBクリエイティブ／2019 年 | 高橋征義 著（2019年） |
+| 発行年が無い | 高橋征義 著／SBクリエイティブ | 高橋征義 著 |
+| 全部無い | （行ごと消える） | （行ごと消える） |
+
+- 行頭の箇条書きの `- ` や見出しの `# ` は、先頭の部品が消えても残ります。
+- 表の行（`|` で始まる行）は部品に分けず、値の無い項目があれば行ごと消えます（セルを消すと列がずれるため）。
+- 空白なしの半角の `/` と、リンク先の括弧（`[= title](= url)`）は区切りになりません。
+- テンプレートのキーは、どれか 1 件のデータにあれば正しいキーとみなします。どの件にも無いキーは打ち間違いとして `UnknownKeyError` になります。
+
+## メソッド
+
+| メソッド | 役割 |
+|---|---|
+| `QueryStream.render(text, **options)` | テキスト内の記法をすべて展開し、結果を返す |
+| `QueryStream.render_query(query, **options)` | 1 つの記法を展開し、結果を返す |
+| `QueryStream.scan(path_or_text)` | ファイルパスまたはテキストから記法を探し、一覧を返す |
+
+```ruby
+QueryStream.render_query('= books | tags=ruby | :full', data_dir: 'data', templates_dir: 'templates')
+
+QueryStream.scan('contents/05-references.md')
+# => ["= books", "= books | :full"]
+```
+
+`render_query` は `on_error` を受け取りません。展開に失敗すると、例外をそのまま投げます。`scan` はコードブロックの中の記法を含めません。
+
 ## 設定
 
 ```ruby
@@ -116,7 +266,7 @@ end
 
 ## エラー・警告の扱い
 
-**この gem はメッセージを組み立てません。** どう表示するか、どの言語で出すか、そもそもログに残すかは、すべて呼び出し元が決めます。そのため展開時の出来事は、構造化された例外としてコールバックへ渡されます。
+**この gem はログを出力しません。** どう表示するか、どの言語で出すか、ログに残すかは、呼び出し元が決めます。そのため展開時の出来事は、構造化された例外としてコールバックへ渡されます。例外の `message` には日本語の既定の文が入っています。
 
 ```ruby
 QueryStream.render(
@@ -138,12 +288,13 @@ QueryStream.render(
 | `DataNotFoundError` | `expected_path`, `query`, `location` |
 | `DataLoadError` | `file_path`, `cause_error` |
 | `UnknownKeyError` | `key_path`, `available_keys`, `template_path`, `location` |
+| `InvalidDateError` | なし（`message` に日付を含みます） |
 | `NoResultWarning` | `query`, `location` |
 | `AmbiguousQueryWarning` | `query`, `location`, `count` |
 
-前 4 つは `QueryStream::Error`、後 2 つは `QueryStream::Warning` を継承します。**gem の外へ出る例外はこの 2 系統だけ**です。壊れた YAML も、不正な UTF-8 を含む原稿も、生の `ArgumentError` や `NoMethodError` にはなりません。
+前 5 つは `QueryStream::Error`、後 2 つは `QueryStream::Warning` を継承します。**gem の外へ出る例外はこの 2 系統だけ**です。壊れた YAML も、不正な UTF-8 を含む原稿も、生の `ArgumentError` や `NoMethodError` にはなりません。
 
-たとえば `UnknownKeyError` は「使えるキーの一覧」と「直すべき雛形のパス」まで持って届くので、呼び出し元で打ち間違いの案内を組み立てられます。`location` は記法が書かれた原稿の位置、`template_path` は直す雛形の位置で、**直すのは雛形のほう**です。
+たとえば `UnknownKeyError` は「使えるキーの一覧」と「直すべき雛形のパス」を属性に持つので、呼び出し元で打ち間違いの案内を組み立てられます。`location` は記法が書かれた原稿の位置、`template_path` は直す雛形の位置で、**直すのは雛形のほう**です。
 
 ```ruby
 on_error: lambda do |e|

data/RELEASE_NOTE.md

@@ -6,6 +6,45 @@ YAML / JSON のデータファイルとテンプレートを組み合わせて
 
 ---
 
+## 1.5.0 — 2026-11-01
+
+**値の無い項目があっても、行ごと消さずに、その部分だけを消すようになりました。** 書誌のように一行へ複数の値を並べるテンプレートで、どれか一つが欠けると、これまでは行ごと消えていました。
+
+```
+= author.name 著／= publisher／= year 年
+```
+
+発行年の分からない本でも、`高橋征義 著／SBクリエイティブ` と出ます（1.4 では著者と出版社まで消えていました）。区切り（`／`・`・`・`、` など）と、変数を含む括弧（`（= year 年）`）で行を部品に分け、値の無い部品だけを、区切りを詰めて消します。すべての値がそろった行の出力は変わりません。変数が一つだけの行と表の行は、これまでどおり行ごと消します（表のセルを消すと列がずれるためです）。
+
+**抽出条件の書き方を三つ足しました。**
+
+- **`OR` で条件をつなげます。** `tags=ruby OR year>=2020` のように、別の項目の条件も書けます。AND は OR より強く結び付きます。前後に空白のある `OR` / `or` は区切りになるので、`title=Rock or Pop` のような値は抽出条件に書けなくなりました
+- **数をアンダースコアで桁区切りして書けます。** `population>=9_000_000` や、万の位で区切る `900_0000` も書けます。比較・範囲・主キー検索・等値のどれでも使えます
+- **日付を和暦（`R06-01-01`）でも書けます。** データでも抽出条件でも、西暦の `2024-01-01` と同じ日として比べ、並べ替えます。元号は頭文字（M・T・S・H・R）で書き、年は 1 桁でも構いません
+
+**昇順の並べ替えの書き方を README に追加しました。** 機能は最初からありましたが、README の例は降順（`-title`）だけでした。
+
+```
+= books | +title    # タイトルの昇順
+= books | -year     # 発行年の降順
+```
+
+**符号は必ず付けてください。** 符号を省いた `= books | title` は、並べ替えではなく**一件検索**として解釈され、「該当なし」の警告を出して何も展開しません。`= book | 楽しいRuby` と同じ形なので、パーサーは符号の有無だけで両者を区別します。README にも理由を記載しました。
+
+あわせて、内部に一度も実行されない分岐が残っていたのを整理しました。動きは変わりません。
+
+- **対応 Ruby を 3.4.10 / 4.0.9 に更新しました**（4.0.9 は 2026 年 10 月 23 日公開）
+- **Minitest を 6 系へ、samovar を 2.5.1 へ更新しました**
+- **コード検査（rubocop）を導入しました。** 有効にしているのは `Lint` と `Security` の規則だけで、引用符の種類などの様式は検査しません
+- README と CHANGELOG にあった「vivlio-style」という綴りを「Vivlio Starter」に直しました
+
+### 不具合の修正
+
+- **項目名を省いた AND が OR として動いていたのを直しました。** `tags=ruby AND beginner` は、`ruby` と `beginner` の両方を含むレコードを選ぶ記法ですが、どちらかを含むレコードを選んでいました。この書き方を使っている場合は、結果の件数が変わります
+- **比較とソートで `ArgumentError` が発生していたのを直しました。** 対象の項目に値が無いレコードや比較できない値のレコードが 1 件でもあると、例外が `render` の外へ出ていました。比較では該当のレコードを除き、ソートでは昇順でも降順でも末尾に置きます。`year=2020..abc` のように両端を比較できない範囲も、例外にならなくなりました
+- **省ける項目が最初の 1 件に無いと、`UnknownKeyError` が発生していたのを直しました。** テンプレートのキーを最初の 1 件だけで確認していました。修正後は、どれか 1 件にあるキーを正しいキーとして扱い、どの件にも無いキーだけを `UnknownKeyError` にします
+- **日付の範囲指定が 1 件も返さなかったのを直しました。** `date=2024-06-01..2024-06-30` のような範囲は、両端が文字列のまま比較され、どのデータにも一致しませんでした。数の範囲は影響を受けていません
+
 ## 1.4.0 — 2026-08-07
 
 **細かな不具合修正が中心のリリースです。** いずれも「著者が用意した原稿やデータが壊れている」という、実際に起こりうる場面で想定外の例外が漏れていた問題です。

data/lib/query_stream/command.rb

@@ -2,8 +2,6 @@
 
 require 'samovar'
 
-# ================================================================
-# File: lib/query_stream/command.rb
 # ================================================================
 # 責務:
 #   QueryStream の CLI コマンド。--version のみ提供する。
@@ -31,11 +29,8 @@ module QueryStream
 
       # 使い方を表示する。
       #
-      # public かつ `output:` を受ける形でなければならない。Samovar は引数の解析に
-      # 失敗すると、外から `error.command.print_usage(output: output)` を呼んで
-      # 使い方を出そうとする。private に置いていた頃は、そこで
-      # `private method 'print_usage' called` の NoMethodError になり、
-      # **`--help` と未知の引数がスタックトレースで落ちていた**。
+      # public かつ `output:` を受ける形にする。Samovar は引数の解析に失敗すると、外から
+      # `error.command.print_usage(output: output)` を呼ぶ。
       # @param output [IO] 出力先（Samovar からはエラー出力が渡される）
       def print_usage(output: $stdout)
         output.puts self.class.description

data/lib/query_stream/configuration.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/configuration.rb
 # ================================================================
 # 責務:
 #   QueryStream のグローバル設定を管理する。

data/lib/query_stream/data_resolver.rb

@@ -3,8 +3,6 @@
 require 'yaml'
 require 'json'
 
-# ================================================================
-# File: lib/query_stream/data_resolver.rb
 # ================================================================
 # 責務:
 #   データファイルの探索・単数形/複数形の自動解決を行う。
@@ -97,10 +95,8 @@ module QueryStream
 
     # 読み込み結果をレコード配列へ正規化する。
     #
-    # **常に配列を返すのが本メソッドの契約である。** 空のデータファイルは YAML が
-    # `nil` を返すため、素通しすると呼び出し先（TemplateCompiler）が
-    # `undefined method 'any?' for nil` で落ちる——データを空にしただけの著者に
-    # NoMethodError を見せることになる。
+    # **常に配列を返す。** 空のデータファイルは YAML が `nil` を返すので、空配列に変換する
+    # （呼び出し先の TemplateCompiler は配列を前提にしている）。
     #
     # 配列でもハッシュでもない中身（先頭が文字列や数値だけの YAML）は、
     # レコード群として解釈しようがないので DataLoadError で理由を伝える。

data/lib/query_stream/errors.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/errors.rb
 # ================================================================
 # 責務:
 #   QueryStream の例外クラス体系を定義する。
@@ -55,8 +53,6 @@ module QueryStream
   #
   # 「どのキーが無いか」だけでなく「代わりに何が使えるか」「どのファイルを直すか」まで
   # 属性で渡す。呼び出し元はこれを使って「もしかして =author?」のような案内を組み立てられる。
-  # 属性が無かった頃はこのクラスだけが gem 内で logger.error を呼んでおり、
-  # 利用できるキーの一覧を呼び出し元が受け取れなかった。
   #
   # location（記法の位置）と template_path（雛形の位置）は別物である。
   # 直すのは雛形なので、記法の位置だけでは著者はファイルを開けない。

data/lib/query_stream/filter_engine.rb

@@ -2,8 +2,6 @@
 
 require 'date'
 
-# ================================================================
-# File: lib/query_stream/filter_engine.rb
 # ================================================================
 # 責務:
 #   AND/OR/比較/Range によるフィルタリングとソート処理を行う。
@@ -13,6 +11,21 @@ require 'date'
 module QueryStream
   # フィルタリング＆ソートエンジンモジュール
   module FilterEngine
+    # 西暦の日付（2024-01-01）
+    SEIREKI_DATE = /\A\d{4}-\d{2}-\d{2}\z/
+
+    # 和暦の日付（R06-01-01）。元号は頭文字で書く（M 明治・T 大正・S 昭和・H 平成・R 令和）。
+    # 年は 1 桁でもよい（R6-01-01）。
+    WAREKI_DATE = /\A(?<era>[MTSHR])(?<year>\d{1,2})-(?<month>\d{2})-(?<day>\d{2})\z/
+
+    # 大小の条件と、<=> の結果の判定
+    ORDER_TESTS = {
+      gt:  ->(order) { order.positive? },
+      gte: ->(order) { order >= 0 },
+      lt:  ->(order) { order.negative? },
+      lte: ->(order) { order <= 0 }
+    }.freeze
+
     module_function
 
     # フィルタ条件をレコード群に適用する
@@ -27,13 +40,21 @@ module QueryStream
       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
+      keyed = records.map do |record|
+        value = record[sort[:field]]
+        [record, missing_value?(value) ? nil : to_comparable(value)]
+      end
+      kind = keyed.filter_map { |_, key| sort_kind(key) }.tally.max_by { |_, count| count }&.first
+
+      sortable, others = keyed.partition { |_, key| sort_kind(key) == kind }
+      sorted = sortable.sort_by(&:last).map(&:first)
+      (sort[:direction] == :desc ? sorted.reverse : sorted) + others.map(&:first)
     end
 
     # 単一フィルタ条件をレコードに対して評価する
@@ -53,22 +74,55 @@ module QueryStream
         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 :gt, :gte, :lt, :lte
+        satisfies_order?(field_value, filter)
       when :range
-        range = filter[:value]
-        range.cover?(to_comparable(field_value))
+        within_range?(field_value, filter[:value])
+      when :or
+        filter[:branches].any? { |branch| branch.all? { evaluate_filter(record, it) } }
       else
         false
       end
     end
 
+    # 大小の条件を満たすか。値が無いレコードと、比較できない値のレコードは満たさない
+    # @param field_value [Object] レコードの値
+    # @param filter [Hash] フィルタ条件 { op:, value: }
+    # @return [Boolean]
+    def satisfies_order?(field_value, filter)
+      return false if missing_value?(field_value)
+
+      order = to_comparable(field_value) <=> to_comparable(filter[:value])
+      !order.nil? && ORDER_TESTS.fetch(filter[:op]).call(order)
+    end
+
+    # 範囲に含まれるか。両端も比較用にそろえる。パーサーは "2024-06-01".."2024-06-30" のような
+    # 文字列の範囲を返すので、そのままでは Date の値を含まない。
+    # @param field_value [Object] レコードの値
+    # @param range [Range] 範囲
+    # @return [Boolean]
+    def within_range?(field_value, range)
+      Range.new(to_comparable(range.begin), to_comparable(range.end), range.exclude_end?)
+           .cover?(to_comparable(field_value))
+    rescue ArgumentError
+      # 両端を比較できない範囲（Range.new が受け付けない）
+      false
+    end
+
+    # 値が無いか（キーが無い・nil・空文字列）
+    def missing_value?(value) = value.nil? || value == ''
+
+    # ソートで比べられる値の種類。値が無いときは nil
+    def sort_kind(key)
+      case key
+      when nil then nil
+      when Numeric then :number
+      when Date then :date
+      when Time then :time
+      else :string
+      end
+    end
+
     # 主キー候補フィールドを順番に走査して一致するものを探す
     # @param record [Hash] 単一レコード
     # @param query_value [Object] 検索値
@@ -82,13 +136,25 @@ module QueryStream
     # 等値比較（配列・カンマ区切り文字列を透過的に扱う）
     # データ側が配列/カンマ区切りの場合、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 }
+      # 綴りの揺れは両側でそろえる。条件側だけそろえると、データに "2024_01" や
+      # "R06-01-01" のような文字列があるとき、同じ綴りの条件で一致しなくなる。
+      field_list = normalize_to_list(field_value).map { canonical_token(it) }
+      value_list = Array(filter_values).map { canonical_token(it.to_s.strip) }
 
       # フィールド側の値リストと条件値リストに交差があれば一致
       (field_list & value_list).any?
     end
 
+    # 等値比較のため、値を綴りの揺れのない形へそろえる。
+    # 数は桁区切りを外し（9_000_000 → 9000000）、日付は西暦にする（R06-01-01 → 2024-01-01）。
+    # 存在しない日付は、等値比較では文字列のまま比べる。
+    def canonical_token(str)
+      date = parse_date(str)
+      date ? date.iso8601 : QueryStreamParser.strip_digit_separators(str)
+    rescue InvalidDateError
+      str
+    end
+
     # フィールド値をリスト化する（配列/カンマ区切り/単値を統一）
     def normalize_to_list(value)
       case value
@@ -103,20 +169,31 @@ module QueryStream
       end
     end
 
+    # 西暦・和暦の日付を Date に直す。日付の形でなければ nil を返す。
+    # 和暦は Date.jisx0301 に任せる。Date.parse は "R06-01-01" を 2006-01-01 と
+    # 読み違えるので使えない。jisx0301 の区切りはドットで、年は 2 桁が要る。
+    # 元号の境目は検査しない（H31-05-01 も 2019-05-01 として読む）。
+    # @raise [InvalidDateError] 日付の形だが存在しない日（2024-02-30 など）
+    def parse_date(value)
+      if value.match?(SEIREKI_DATE)
+        Date.parse(value)
+      elsif (m = value.match(WAREKI_DATE))
+        Date.jisx0301("#{m[:era]}#{m[:year].rjust(2, '0')}.#{m[:month]}.#{m[:day]}")
+      end
+    rescue Date::Error
+      raise InvalidDateError, "無効な日付: #{value}"
+    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
+        # 日付形式（西暦・和暦）を検出して Date に変換
+        date = parse_date(value)
+        return date if date
+
         # 数値変換を試みる
         case value
         when /\A-?\d+\z/

data/lib/query_stream/query_stream_parser.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/query_stream_parser.rb
 # ================================================================
 # 責務:
 #   QueryStream 記法（= books | tags=ruby | -title | 5 | :full）を
@@ -27,6 +25,14 @@ module QueryStream
     # AND 条件の区切りパターン
     AND_PATTERN = /\s+(?:AND|and|&&)\s+/
 
+    # OR 条件の区切りパターン。`||` は記法の区切りの `|` と衝突するので使わない
+    OR_PATTERN = /\s+(?:OR|or)\s+/
+
+    # 桁をアンダースコアで区切った数（9_000_000 / 900_0000 / 1_234.5）。
+    # Ruby の数値リテラルと同じく、区切りは数字と数字のあいだにだけ置ける。
+    # 区切り方は問わないので、万の位で区切る 900_0000 も書ける。
+    NUMBER_WITH_SEPARATORS = /\A-?\d+(?:_\d+)*(?:\.\d+(?:_\d+)*)?\z/
+
     module_function
 
     # QueryStream 記法をパースして構造化ハッシュを返す
@@ -137,16 +143,15 @@ module QueryStream
       tokens
     end
 
-    # ソート指定をパースする
-    # @param token [String] "-title" / "+title" / "title"
+    # ソート指定をパースする。
+    #
+    # **符号は必須である。** 呼び出し側（parse_segment）が `+` か `-` で始まることを確かめてから渡す。
+    # 符号なしの `title` は、`= book | 楽しいRuby` と区別できないので主キー検索として扱う。
+    #
+    # @param token [String] "-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
+      { field: token[1..].to_sym, direction: token.start_with?('-') ? :desc : :asc }
     end
 
     # 直前フィールドを引き継いで値のみの条件をパースする
@@ -157,37 +162,35 @@ module QueryStream
       parse_eq_condition(field, value_str)
     end
 
-    # AND で接続されたフィルタ式をパースする
-    # @param expression [String] "tags=ruby && category=web"
-    # @return [Array<Hash>] フィルタ条件のリスト
+    # AND / OR で接続されたフィルタ式をパースする。AND は OR より強く結び付く。
+    # 項目名を省いた値は、直前の条件の項目を引き継ぐ（tags=ruby AND beginner）。
+    # @param expression [String] "tags=ruby && category=web" / "tags=ruby OR tags=go"
+    # @return [Array<Hash>] すべて満たすフィルタ条件のリスト。OR は { op: :or, branches: } の 1 条件にまとめる
     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?
+      branches = expression.split(OR_PATTERN).map do |branch|
+        branch.split(AND_PATTERN).flat_map do |clause|
+          parsed = parse_clause(clause.strip, previous_field)
+          previous_field = parsed.last&.[](:field) || previous_field
+          parsed
+        end
+      end.reject(&:empty?)
 
-        parsed = parse_single_condition(clause)
+      branches.size > 1 ? [{ op: :or, branches: }] : branches.flatten
+    end
 
-        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
+    # AND / OR で区切られた 1 節をパースする
+    # @param clause [String] "tags=ruby" / "beginner"
+    # @param previous_field [Symbol, nil] 項目名を省いたときに引き継ぐ項目
+    # @return [Array<Hash>] フィルタ条件
+    def parse_clause(clause, previous_field)
+      return [] if clause.empty?
 
-        last_filter = parsed.last
-        previous_field = last_filter&.[](:field)
-        previous_filter = last_filter if last_filter&.[](:op) == :eq
+      parsed = parse_single_condition(clause)
+      return parsed unless parsed.empty? && previous_field
 
-        parsed
-      end
+      parse_value_only_condition(previous_field, clause)
     end
 
     # 単一条件をパースする（OR はカンマ区切りで表現）
@@ -242,6 +245,9 @@ module QueryStream
         # 通常の等値条件（カンマ区切りでOR）
         [{ field: field_sym, op: :eq, value: parse_values(value_str) }]
       end
+    rescue ArgumentError
+      # 両端を比較できない範囲（2020..abc）は Range を作れないので、文字列の値として扱う
+      [{ field: field_sym, op: :eq, value: parse_values(value_str) }]
     end
 
     # カンマ区切りの値をリストとしてパースする
@@ -255,7 +261,7 @@ module QueryStream
     # @param str [String] "20" / "3.14" / "東京"
     # @return [Integer, Float, String] 変換後の値
     def parse_numeric(str)
-      s = str.strip
+      s = strip_digit_separators(str.strip)
       case s
       when /\A-?\d+\z/    then s.to_i
       when /\A-?\d+\.\d+\z/ then s.to_f
@@ -263,6 +269,13 @@ module QueryStream
       end
     end
 
+    # 数の桁区切り（アンダースコア）を外す。数でない値（tag_name など）はそのまま返す。
+    # @param str [String] "9_000_000" / "ruby"
+    # @return [String] "9000000" / "ruby"
+    def strip_digit_separators(str)
+      str.match?(NUMBER_WITH_SEPARATORS) ? str.delete('_') : str
+    end
+
     # 主キー候補フィールドによる一件検索フィルタを構築する
     # すべての主キー候補に対して OR 的に検索する
     # @param value [String] 検索値

data/lib/query_stream/singularize.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/singularize.rb
 # ================================================================
 # 責務:
 #   英単語の複数形を単数形に変換する軽量ヘルパー。

data/lib/query_stream/template_compiler.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/template_compiler.rb
 # ================================================================
 # 責務:
 #   テンプレートファイル（_book.md 等）にデータを流し込み、
@@ -9,6 +7,8 @@
 #
 # 変換ルール:
 #   - `= key` のみの行 → key の値を展開（nil/空文字なら行スキップ）
+#   - `= key` が 2 つ以上ある行 → 区切り（／・、，,）と括弧で部品に分け、
+#     空のキーを含む部品だけを消す（部品が全部消えたら行スキップ。表の行は対象外）
 #   - `prefix = key` → prefix を残してkey の値を展開
 #   - `![](key)` → 変数展開（拡張子なし → 変数、拡張子あり → リテラル）
 #   - `= key` を含まない行 → リテラル出力（ヘッダー等は一度だけ出力）
@@ -44,6 +44,21 @@ module QueryStream
     # VFM フェンス終了行: 単独の :::
     FENCE_CLOSE_PATTERN = /\A:::\s*\z/
 
+    # 部品の区切り: 全角の斜線・中黒・読点・コンマと半角のコンマ（前後の空白ごと）、
+    # 前後に空白のある半角の斜線。空白なしの半角の斜線を区切りにしないのは、
+    # URL（https://example.com/books/= id）を割らないため。
+    PART_SEPARATOR = %r{\s*[／・、，,]\s*|\s+/\s+}
+
+    # 変数を含みうる括弧（全角・半角）。中身ごと 1 つの部品として扱う（直前の空白も含める）。
+    # `]` の直後の括弧は Markdown のリンク先（`[= title](= url)`）なので含めない。
+    OPTIONAL_GROUP = /\s*(?<!\])[（(][^（）()]*[）)]/
+
+    # 行頭の Markdown の目印（箇条書き・番号・引用・見出し）。部品が消えても残す。
+    LINE_MARKER = /\A\s*(?:(?:[-*+]|\d+\.)\s+|>\s?|\#{1,6}\s+)*/
+
+    # 括弧を部品として退避するときの目印（テンプレートに現れない制御文字で挟む）
+    GROUP_PLACEHOLDER = /\u0000(\d+)\u0000/
+
     module_function
 
     # テンプレートにレコード群を流し込んでテキストを生成する
@@ -55,7 +70,7 @@ module QueryStream
     # @return [String] 展開後のテキスト
     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:, template_path:) if records.any?
+      validate_template_keys!(lines, records, source_filename:, line_number:, template_path:) if records.any?
 
       parts = classify_lines(lines)
       return '' if records.empty?
@@ -219,7 +234,7 @@ module QueryStream
     end
 
     # テンプレート行をレコードデータで展開する
-    # nil/空文字のキーがあれば行ごとスキップ（nil を返す）
+    # 行ごと消すときは nil を返す
     # @param line [String] テンプレート行
     # @param record [Hash] データレコード
     # @return [String, nil] 展開後の行、またはスキップ時 nil
@@ -270,10 +285,72 @@ module QueryStream
     end
 
     # = key パターンの変数を展開する（ドット記法対応）
+    #
+    # 変数が 2 つ以上ある行は、空のキーを含む部品だけを消す（expand_parts）。
+    # `= author.name 著／= publisher／= year 年` で発行年だけが無い本でも、著者と出版社は出る。
+    # 変数が 1 つの行と表の行（セルを消すと列がずれる）は、空なら行ごと消す。
     # @param line [String] テンプレート行
     # @param record [Hash] データレコード
     # @return [String, nil] 展開後の行、またはスキップ時 nil
     def expand_variables(line, record)
+      return expand_parts(line, record) if partial_line?(line)
+
+      expand_whole(line, record)
+    end
+
+    # 部品ごとに消せる行か。変数が 2 つ以上あり、表の行でないもの。
+    def partial_line?(line)
+      !line.lstrip.start_with?('|') && line.scan(VARIABLE_PATTERN).size >= 2
+    end
+
+    # 区切りと括弧で行を部品に分け、空のキーを含む部品だけを消す。
+    #
+    # - 変数を含む括弧（`（= year 年）`）は 1 つの部品。空なら直前の空白ごと消す。
+    # - 括弧の外は PART_SEPARATOR で分ける。残った部品は、前の部品の後ろにあった区切りでつなぐ。
+    # - 行頭の Markdown の目印（`- ` など）と行末の改行は、部品が消えても残す。
+    # - 変数を含む部品が 1 つも残らなければ nil（行ごと消す）。
+    # キーがすべて埋まっていれば、区切りも括弧も元のまま戻るので、出力は expand_whole と同じになる。
+    # @param line [String] テンプレート行
+    # @param record [Hash] データレコード
+    # @return [String, nil] 展開後の行、またはスキップ時 nil
+    def expand_parts(line, record)
+      newline = line[/\R\z/].to_s
+      body = line.chomp
+      marker = body[LINE_MARKER]
+      body = body.delete_prefix(marker)
+
+      groups = []
+      masked = body.gsub(OPTIONAL_GROUP) do |group|
+        next group unless group.match?(VARIABLE_PATTERN)
+
+        groups << group
+        "\u0000#{groups.size - 1}\u0000"
+      end
+
+      kept = masked.split(/(#{PART_SEPARATOR})/).each_slice(2).filter_map do |part, separator|
+        text = expand_part(part, groups, record)
+        text && [text, separator.to_s, variable_part?(part)]
+      end
+      return nil unless kept.any? { |_, _, variable| variable }
+
+      joined = kept.each_with_index.map { |(text, separator, _), i| i == kept.size - 1 ? text : text + separator }.join
+      "#{marker}#{joined}#{newline}"
+    end
+
+    # 部品 1 つを展開する。空のキーを含めば nil。括弧は中のキーが空ならそこだけ消す。
+    # 括弧の外を先に展開するのは、値の中の `= …` をもう一度展開しないため（括弧は退避中）。
+    def expand_part(part, groups, record)
+      outer = expand_whole(part, record)
+      return nil unless outer
+
+      text = outer.gsub(GROUP_PLACEHOLDER) { expand_whole(groups[::Regexp.last_match(1).to_i], record).to_s }
+      text.strip.empty? ? nil : text
+    end
+
+    def variable_part?(part) = part.match?(VARIABLE_PATTERN) || part.match?(GROUP_PLACEHOLDER)
+
+    # 行の変数をすべて展開する。空のキーが 1 つでもあれば nil（行ごと消す）。
+    def expand_whole(line, record)
       result = line.dup
 
       result.gsub!(VARIABLE_PATTERN) do |_match|
@@ -303,16 +380,19 @@ module QueryStream
     end
 
     # テンプレート内のキーがデータに存在するかを検証する
+    #
+    # どれか 1 件にでもあるキーは正しいキーとみなす。省ける項目（発行年など）が最初の 1 件に
+    # 無いだけで、打ち間違いとして止めないため。値の無い件では、その行・部品を消す（expand_variables）。
     # @param lines [Array<String>] テンプレートの行リスト
-    # @param sample_record [Hash] サンプルレコード（最初の1件）
+    # @param records [Array<Hash>] レコード群
     # @param source_filename [String, nil] エラー報告用ファイル名
     # @param line_number [Integer, 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
+    def validate_template_keys!(lines, records, source_filename: nil, line_number: nil, template_path: nil)
+      available_keys = records.flat_map(&:keys).uniq
+      return if available_keys.empty?
 
       location = source_filename ? "#{source_filename}:#{line_number}" : ''
-      available_keys = sample_record.keys
       in_code_block = false
 
       lines.each do |line|

data/lib/query_stream/version.rb

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

data/lib/query_stream.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream.rb
 # ================================================================
 # 責務:
 #   QueryStream gem のエントリポイント。
@@ -120,8 +118,6 @@ module QueryStream
       parsed = QueryStreamParser.parse(query)
 
       # --- Phase: Load Data ---
-      # gem 内でログ出力せず、構造化された属性を持つ例外を raise する。
-      # メッセージの構成・ログ出力・i18n は呼び出し元の責務とする。
       data_file = DataResolver.resolve(parsed[:source], data_dir)
       unless data_file
         expected = File.join(data_dir, "#{parsed[:source]}.yml")
@@ -147,13 +143,11 @@ module QueryStream
       if parsed[:single_lookup]
         case records.size
         when 0
-          # gem 内でログ出力せず、構造化された属性を持つ警告を呼び出し元に委ねる。
           on_warning&.call(NoResultWarning.new(query: query, location: location))
           return ''
         when 1
           # 正常
         else
-          # gem 内でログ出力せず、構造化された属性を持つ警告を呼び出し元に委ねる。
           on_warning&.call(
             AmbiguousQueryWarning.new(query: query, location: location, count: records.size)
           )
@@ -168,8 +162,6 @@ module QueryStream
 
       unless File.exist?(template_path)
         hint = build_template_hint(singular, style, format, templates_dir)
-        # gem 内でログ出力せず、構造化された属性を持つ例外を raise する。
-        # メッセージの構成・ログ出力・i18n は呼び出し元の責務とする。
         raise TemplateNotFoundError.new(
           template_path: template_path,
           query:         query,
@@ -185,7 +177,7 @@ module QueryStream
 
       # --- Phase: Post-render filter ---
       # 展開結果を呼び出し元の後段フィルタへ通す（画像パス解決など gem 外の後処理）。
-      # コールバックが String 以外を返した場合は安全側に倒して元の展開結果を採用する。
+      # コールバックが String 以外を返した場合は、元の展開結果を採用する。
       return rendered unless post_render
 
       context = {
@@ -226,16 +218,12 @@ module QueryStream
 
     # その行を QueryStream 記法として扱うか。
     #
-    # **不正な UTF-8 を含む行は記法として解釈しない。** `match?` はそういう行に
-    # `ArgumentError: invalid byte sequence in UTF-8` を投げるので、素通しにすると
-    # 原稿に 1 バイトの壊れが混ざっただけで展開が丸ごと止まる。
-    # ここでバイト列を書き換えて（scrub して）通す手もあるが採らない——gem が黙って
-    # 原稿のバイト列を変えると、著者が気付けない形で本文が変わる。
-    # 記法として読めない行は本文として、そのまま返すのが正しい。
+    # 不正な UTF-8 を含む行は記法として解釈せず、本文としてそのまま返す。`match?` はそういう行に
+    # `ArgumentError` を投げるので、捕まえないと展開全体が止まる。scrub しないのは、原稿のバイト列を
+    # 変えないため。
     #
-    # EncodingError と ArgumentError の両方を捕まえるのは意図的である。壊れたバイト列に
-    # Ruby がどちらを投げるかはメソッド次第で（match? / 先頭破損の lstrip は ArgumentError、
-    # strip は Encoding::CompatibilityError）、その差で展開が止まってはならない。
+    # EncodingError と ArgumentError の両方を捕まえる。壊れたバイト列に Ruby が投げる例外はメソッドで
+    # 異なる（match? / 先頭破損の lstrip は ArgumentError、strip は Encoding::CompatibilityError）。
     def query_line?(line)
       line.match?(QUERY_STREAM_PATTERN)
     rescue EncodingError, ArgumentError
@@ -243,9 +231,7 @@ module QueryStream
     end
 
     # コードフェンスの開始/終了行か。
-    # `lstrip` も不正な UTF-8 で ArgumentError を投げるので、query_line? と同じく
-    # 「読めない行は本文」へ倒す。ここを素通しにすると、記法判定だけ守っても
-    # 手前のフェンス判定で落ちる。
+    # `lstrip` も不正な UTF-8 で ArgumentError を投げるので、query_line? と同じく本文として扱う。
     def code_fence?(line)
       line.lstrip.start_with?('```')
     rescue EncodingError, ArgumentError
@@ -254,10 +240,9 @@ module QueryStream
 
     # 引数をファイルパスとして読むべきか。
     #
-    # `scan` はパスと本文のどちらも受け取る API なので、本文をそのまま
-    # `File.exist?` へ渡すと壊れる——NUL バイトを含めば `ArgumentError`、
-    # ディレクトリなら「存在する」と判定されて `File.read` が `Errno::EISDIR` を出す。
-    # パスとして成立しうる形だけを先に選別し、判定自体の失敗も本文扱いに倒す。
+    # `scan` はパスと本文のどちらも受け取る。本文を `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")

data/query-stream.gemspec

@@ -8,9 +8,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Atelier Mirai']
   spec.email         = ['contact@atelier-mirai.net']
 
-  spec.summary       = 'QueryStream - YAML/JSON data renderer with template expansion'
-  spec.description   = 'A generic Ruby library that expands QueryStream notation in text content ' \
-                        'by combining YAML/JSON data files with template files.'
+  spec.summary       = 'YAML / JSON のデータとテンプレートから、文章中の 1 行の記法を展開する Ruby ライブラリ'
+  spec.description   = 'QueryStream は、文章中に書いた `= books | tags=ruby | -year | 5` のような 1 行の記法を、' \
+                       'YAML / JSON のデータファイルとテンプレートを組み合わせて展開する汎用の Ruby ライブラリです。' \
+                       '抽出条件、並べ替え、件数、スタイルを指定できます。'
   spec.homepage      = 'https://github.com/Atelier-Mirai/query-stream'
   spec.license       = 'MIT'
 
@@ -20,18 +21,16 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.4'
 
   spec.files = Dir.glob('{lib,bin}/**/*') +
-               %w[README.md CHANGELOG.md RELEASE_NOTE.md LICENSE Gemfile query-stream.gemspec]
+               %w[README.md CHANGELOG.md RELEASE_NOTE.md LICENSE query-stream.gemspec]
   spec.bindir        = 'bin'
   spec.executables   = ['query-stream']
   spec.require_paths = ['lib']
 
-  # Runtime dependencies
-  # logger への依存は 1.4.0 で外した。gem 自身はログを出さず、失敗は構造化例外で伝える。
   spec.add_dependency 'samovar', '~> 2.1'
 
-  # Development dependencies
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake', '~> 13.2'
-  spec.add_development_dependency 'minitest', '~> 5.22'
+  spec.add_development_dependency 'minitest', '>= 5.22'
+  spec.add_development_dependency 'rubocop', '~> 1.81'
   spec.metadata['rubygems_mfa_required'] = 'false'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query-stream
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Atelier Mirai
@@ -55,18 +55,32 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.22'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.22'
-description: A generic Ruby library that expands QueryStream notation in text content
-  by combining YAML/JSON data files with template files.
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+description: QueryStream は、文章中に書いた `= books | tags=ruby | -year | 5` のような 1 行の記法を、YAML
+  / JSON のデータファイルとテンプレートを組み合わせて展開する汎用の Ruby ライブラリです。抽出条件、並べ替え、件数、スタイルを指定できます。
 email:
 - contact@atelier-mirai.net
 executables:
@@ -75,7 +89,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- Gemfile
 - LICENSE
 - README.md
 - RELEASE_NOTE.md
@@ -112,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
-summary: QueryStream - YAML/JSON data renderer with template expansion
+summary: YAML / JSON のデータとテンプレートから、文章中の 1 行の記法を展開する Ruby ライブラリ
 test_files: []

data/Gemfile

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