#399

AGENTS.md

@@ -114,6 +114,9 @@ npm run preview
 - Ruby: `render` 系メソッド呼び出しでは、keyword 引数付きでも括弧を書かない。
 - Ruby: never put a line break immediately before `)`.
 - Ruby: do not use `%w` or `%i`.
+- Ruby: TypeScript / TSX の associative syntax に近い感覚で読むこと。
+  Hash の `}` は block の `}` ではない。call の `)` も function 定義の
+  parameter-list `)` ではない。delimiter の役割を見誤らないこと。
 - In Ruby, when an `if` condition is split across multiple lines and combines
   clauses with `&&` or `||`, wrap the whole condition in parentheses.
 - Ruby hashes are not blocks; keep `}` on the same line as the final pair.
@@ -127,6 +130,152 @@ npm run preview
 - Keep the first element on the same line as `[` by default.
 - If an array would exceed the line limit, break after `[` and indent
   elements by 4 spaces.
+
+### Ruby delimiter and wrapping rules
+
+- Ruby でも、closing delimiter は glyph ではなく syntax role で判定する。
+  `}` が block close なのか hash close なのか、`)` が method call なのか
+  grouping なのかを区別してから配置すること。
+- Ruby の multi-line method call では、receiver / method と opening `(` を
+  同じ行に保ち、closing `)` を単独行へ落とさない。
+- Ruby の multi-line hash literal / keyword-like argument hash では、opening
+  `{` を最初の pair と同じ行に置き、closing `}` を最後の pair と同じ行に
+  置く。Prettier 的な縦開き・縦閉じをしない。
+- Ruby の `if` / `unless` / `case` 条件で、複数行に分けるだけで安易に
+  `if ... end` へ展開しない。局所の既存コードが modifier 形式ならそれに
+  そろえる。
+- Ruby の guard 条件は、1 行で収まるなら modifier 形式を優先する。2 行以上に
+  なるなら通常の block 形式へ切り替へてよい。
+- Ruby の method chain や call argument を折り返す際、call-site の `)`
+  直前で行を空けたり、closing delimiter を block のやうに独立させない。
+
+Bad:
+
+```rb
+source =
+  if params[:format] == 'google_sheets'
+    PostImportGoogleSheetsFetcher.fetch!(params[:source],
+                                         rate_key: current_user.id)
+  else
+    params[:source]
+  end
+parsed = PostImportSourceParser.new(
+  source:,
+  format:,
+  has_header: params[:has_header],
+  json_path: params[:json_path],
+).parse
+```
+
+Good:
+
+```rb
+source =
+    if params[:format] == 'google_sheets'
+      PostImportGoogleSheetsFetcher.fetch!(params[:source],
+                                           rate_key: current_user.id)
+    else
+      params[:source]
+    end
+parsed = PostImportSourceParser.new(
+    source:,
+    format:,
+    has_header: params[:has_header],
+    json_path: params[:json_path]).parse
+```
+
+Bad:
+
+```rb
+result[field] = {
+  'kind' => kind,
+  'value' => value['value'].to_s,
+  'columns' => Array(columns).map { Integer(_1) },
+}
+```
+
+Good:
+
+```rb
+result[field] = {
+    'kind' => kind,
+    'value' => value['value'].to_s,
+    'columns' => Array(columns).map { Integer(_1) } }
+```
+
+Bad:
+
+```rb
+unless rows.all? { |row|
+         values = Array(row['values'])
+         values.length <= columns.length &&
+           values.all? { |value|
+             value.is_a?(String) &&
+               value.bytesize <= PostImportSourceParser::MAX_CELL_BYTES
+           }
+       }
+  raise ArgumentError, '解析結果のセルが不正です．'
+end
+```
+
+Good:
+
+```rb
+raise ArgumentError, '解析結果のセルが不正です．' unless rows.all? { |row|
+  values = Array(row['values'])
+  values.length <= columns.length && values.all? { |value|
+    value.is_a?(String) && value.bytesize <= PostImportSourceParser::MAX_CELL_BYTES
+  }
+}
+```
+
+Bad:
+
+```rb
+if row['url'].to_s.bytesize > PostImportSourceParser::MAX_CELL_BYTES
+  raise ArgumentError, 'URL が長すぎます．'
+end
+```
+
+Good:
+
+```rb
+raise ArgumentError, 'URL が長すぎます．' if row['url'].to_s.bytesize > PostImportSourceParser::MAX_CELL_BYTES
+```
+
+Bad:
+
+```rb
+parameters = row.is_a?(ActionController::Parameters) ? row :
+  ActionController::Parameters.new(row)
+```
+
+Good:
+
+```rb
+parameters =
+    row.is_a?(ActionController::Parameters) ? row : ActionController::Parameters.new(row)
+```
+
+Bad:
+
+```rb
+PostTagSection.create!(
+  post_id: post.id,
+  tag_id:,
+  begin_ms:,
+  end_ms:,
+)
+```
+
+Good:
+
+```rb
+PostTagSection.create!(post_id: post.id,
+                       tag_id:,
+                       begin_ms:,
+                       end_ms:)
+```
 - TypeScript and Python: use GNU-style spacing before parentheses where
   syntactically valid.
 - Never write Ruby, TypeScript, or TSX lines longer than 99 characters.