red_quilt 0.6.1

data/docs/architecture.md

@@ -0,0 +1,81 @@
+# RedQuilt Architecture Overview
+
+RedQuiltの構成を概観する。
+
+## パイプライン
+
+```
+Source (Markdown String)
+   │
+   ▼RedQuilt.normalize_input         (lib/red_quilt.rb)
+   │
+   ▼BlockParser                      (lib/red_quilt/block_parser.rb)
+   │dispatch / container parsers / build_lines
+   │     (list.rb, blockquote.rb, reference_definition.rb)
+   │
+   ▼Arena (raw inline spans)
+   │paragraph / heading / table cellの本文はbyte spanのみで保持
+   │
+   ▼InlinePass                       (lib/red_quilt/inline_pass.rb)
+   │     ├─Inline::Lexer              (lib/red_quilt/inline/lexer.rb)
+   │     │byte scan→Tokens (parallel array)
+   │     └─Inline::Builder            (lib/red_quilt/inline/builder.rb)
+   │linear pass→process_emphasis (CommonMark§6.2)
+   │
+   ▼Arena (inline解決済み)
+   │
+   ▼  (option) FootnotePass             (footnotes: true)
+   ▼  (option) ExtendedAutolinkPass    (extended_autolinks: true)
+   ▼  (option) LintPass                (lint: true)
+   │
+   ▼Renderer::HTML                   (lib/red_quilt/renderer/html.rb)
+         arenaをwalkしてmutable Stringにappend
+```
+
+## 各ステージの責務
+
+### `RedQuilt.normalize_input`
+CommonMark§2.3/2.4の最小前処理。`\r\n`/`\r`→`\n`の行末正規化と、NUL→U+FFFDの置換だけを行う。
+
+### BlockParser
+- 行分割: sourceを`Line` Struct配列へ。各行はbyte spanで保持する。
+- dispatch: 行頭バイトでblock kindを判定(`paragraph_only_line?`が非ブロック行を早期に振り分け)。
+- container委譲: list / blockquoteは`List::Parser` / `Blockquote::Parser`へ委譲し、内部で`parse_lines`を再帰。
+- 定義の収集と除外: link reference定義(参照テーブル)と、opt-inのfootnote定義(`FootnoteRegistry`)を本文フローから抜き、専用collectorへ集約。
+- 桁計算: タブ展開を含むインデント計算は`Indentation`に委譲。
+- 出力: inline未解決のblockノードをArenaに構築する。
+
+### InlinePass / Lexer / Builder
+- 対象選定: paragraph / heading / table cellの各inline targetを走査して処理。
+- Lexer: targetのbyte spanをスキャンしTokens(parallel array)へ。
+- Builder①linear pass: code span / link / image / autolink / 簡易inlineを解決。
+- Builder②process_emphasis: delimiter stackを畳んでemphasis / strongを確定(CommonMark§6.2)。
+- footnote参照: `[^label]`を`FootnoteRegistry`で解決し、初回参照順に採番して`FOOTNOTE_REFERENCE`を生成。
+
+### FootnotePass (`footnotes: true`)
+- 並べ替え: `FOOTNOTES_SECTION`(root末尾)配下の定義を初回参照順へ。
+- 刈り取り: 未参照の定義をdetach。
+- section削除: 参照ゼロならsection自体を除去。
+
+### Renderer::HTML
+- walk: arenaを再帰walkし、`+""`で開いたmutable Stringへ直接`<<`。
+- raw HTML: `allow_html`で素通し / エスケープを切替、`disallow_raw_html`でGFM Disallowed Raw HTMLをfilter。
+- footnote: `FOOTNOTE_REFERENCE`をsupリンクに、末尾`FOOTNOTES_SECTION`を`<section class="footnotes">`＋backrefとして出力。
+
+## 主なサブシステム位置
+
+| 領域 | ファイル |
+|---|---|
+| エントリ / 入力正規化 | `lib/red_quilt.rb` |
+| 公開API | `lib/red_quilt/document.rb`、`node_ref.rb` |
+| Arena | `lib/red_quilt/arena.rb` |
+| Block解析 | `block_parser.rb`、`list.rb`、`blockquote.rb`、`indentation.rb` |
+| Reference definition | `reference_definition.rb` |
+| Footnotes (opt-in) | `footnote_definition.rb`、`footnote_registry.rb`、`footnote_pass.rb` |
+| Inline解析 | `inline.rb`、`inline/lexer.rb`、`inline/tokens.rb`、`inline/flanking.rb`、`inline/builder.rb`、`inline/link_scanner.rb` |
+| Inlineエンティティ | `inline/html_entities.rb` |
+| HTML / MDAST出力 | `renderer/html.rb`、`renderer/mdast.rb` |
+| 拡張パス | `inline_pass.rb`、`footnote_pass.rb`、`extended_autolink_pass.rb`、`lint_pass.rb` |
+| Source位置 | `source_span.rb`、`source_map.rb` |
+| Diagnostics | `diagnostic.rb` |
+| CLI | `cli.rb`、`exe/redquilt` |

data/docs/arena-usage.md

@@ -0,0 +1,363 @@
+# Arenaクラスの使い方
+
+`RedQuilt::Arena`はRedQuiltのAST本体を保持する低レベルストレージクラスです。
+本稿はArenaを直接触る人(block parser/ inline builder / renderer /カスタムtransformerなど、`lib/red_quilt`配下のコードを使う人)向けに、そのAPIと前提条件を整理したものです。
+
+>外部APIとしてASTを扱うだけなら`RedQuilt::Document`と`RedQuilt::NodeRef`を経由するのが標準です。Arenaは内部寄りのレイヤーで、`NodeRef`の実装が依存しているデータ構造そのものです。
+
+---
+
+## 0. 簡単な使い方
+
+下のコードはそのままコピー＆ペーストすれば動きます。
+Arenaが「source文字列をベースに各種IDでツリーを組み立てる」ものだという雰囲気が伝わるかと思います。
+
+```ruby
+require "red_quilt"
+
+source = "Hello *world*"
+arena = RedQuilt::Arena.new(source)
+
+# (a)ノードを作る。戻り値はnode id (Integer)
+para_id  = arena.add_node(RedQuilt::NodeType::PARAGRAPH,
+                          source_start: 0, source_len: source.bytesize)
+text_id  = arena.add_node(RedQuilt::NodeType::TEXT,
+                          source_start: 0, source_len: 6)   # "Hello "
+em_id    = arena.add_node(RedQuilt::NodeType::EMPHASIS,
+                          source_start: 6, source_len: 7)   # "*world*"
+inner_id = arena.add_node(RedQuilt::NodeType::TEXT,
+                          source_start: 7, source_len: 5)   # "world"
+
+# (b)親子関係を組む
+arena.append_child(para_id, text_id)
+arena.append_child(para_id, em_id)
+arena.append_child(em_id,   inner_id)
+
+# (c)内容を取り出す
+puts "type:    #{arena.type_name(para_id)}"
+puts "text:    #{arena.text(text_id).inspect}"
+puts "inner:   #{arena.text(inner_id).inspect}"
+puts "span:    #{arena.source_span(em_id).inspect}"
+
+# (d)子を走査する(ブロック形式・Enumeratorなし)
+puts "children of paragraph:"
+arena.each_child(para_id) do |child_id|
+  puts "  #{arena.type_name(child_id)}: #{arena.text(child_id).inspect}"
+end
+```
+
+出力結果は以下のようになります。
+
+```
+type:    paragraph
+text:    "Hello "
+inner:   "world"
+span:    #<RedQuilt::SourceSpan:0x... @start_byte=6, @end_byte=13>
+children of paragraph:
+  text: "Hello "
+  emphasis: "*world*"
+```
+
+このサンプルが作るASTは次のようになります。
+
+```
+PARAGRAPH    [0, 13)   "Hello *world*"
+├─TEXT      [0, 6)    "Hello "
+└─EMPHASIS  [6, 13)   "*world*"
+└─TEXT   [7, 12)   "world"
+```
+
+Arenaの扱いのポイントは以下になります。
+
+- `add_node`はNode ID(Integer)を返す。以降のAPIは全部このIDをキーにする。
+- `source_start` / `source_len`は元のsource文字列に対し、文字単位ではなくバイト単位で範囲を指定する。文字列そのもののコピーは持たない。
+- `text(id)`はstr1があればそれを返し、なければ`source`をbytesliceする。
+- `each_child(id)`を基本の走査APIとしてホットパスで使用する。
+
+これらを頭に入れておくと、後の章は「実際にこのAPIは何を保証しているのか/どう使うべきか」として読めるはずです。
+
+---
+
+## 1.設計の要点
+
+ArenaはASTを「オブジェクトのツリー」ではなく[parallel array](https://en.wikipedia.org/wiki/Parallel_array)として表現します。
+
+-ノードは整数ID(`node_id`)で識別されます
+-各IDに対応する属性(parent / source span / payload)はそれぞれ異なるArrayに列として保持します
+-ノードの追加は各Arrayの末尾への代入操作だけで完結し、新しいRubyオブジェクトは一切生成しません
+
+結果として、Arenaは以下のような性質を持ちます。
+
+-ホットパスではIDというIntegerだけを取り回せる
+-メモリ局所性が良く、GC圧が小さい
+-ノードを「軽い」値として扱えるのでRenderer / Builderをinline化しやすい
+
+###列(column)一覧
+
+|列名|用途|
+|------|------|
+| `@type` | NodeType (Integer定数) |
+| `@parent` / `@first_child` / `@last_child` / `@next_sibling` / `@prev_sibling` |親・子・兄弟リンク。値はnode id (`NO_NODE`で「なし」) |
+| `@source_start` / `@source_len` | document source内のバイト範囲。`source_start < 0`は「spanなし、内容はstr1に持つ」を意味する|
+| `@int1` / `@int2` / `@int3` | NodeTypeごとに用途が決まる整数スロット(default `0`) |
+| `@str1` / `@str2` | NodeTypeごとに用途が決まる文字列スロット(default `nil`) |
+
+---
+
+## 2.不変条件
+
+Arenaを扱う上で常に成り立つ前提です。
+
+1. Node IDは単調増加する
+   `add_node`で払い出されるIDは`@type.length`から始まり、追加するたびに1ずつ増えます。IDが再利用されることはありません。
+2. detachされたノードも列に残る
+   `detach`は親・兄弟リンクを`NO_NODE`にリセットするだけで、列のレコード自体はarena内に残り続けます。後続の`add_node`がそのスロットを再利用することもありません。これはallocationを単純化するための意図的な選択です。
+3. `@source`はimmutableとして扱う
+   Arena構築後にsourceを書き換えてはいけません。`source_start` / `source_len`は直接バイト範囲を指しているため、sourceが変わると`text` / `source_span`の戻り値が壊れます。
+4. `NO_NODE` = -1
+親や兄弟が存在しないことを示すsentinelです。`Arena::NO_NODE`定数で参照できます。
+5. `source_start < 0`は「spanなし」
+この場合、ノードの内容は`@str1`にliteralとして持たれていることが期待されます(例: blockquoteを解除したparagraph、entityデコード後のTEXT)。
+
+---
+
+## 3. APIのレイヤー
+
+Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図が掴みやすくなります。
+
+### 3.1構造の操作(mutators)
+
+ツリーを組み立て・編集するためのAPIです。`validなid`を渡す前提で、安全性チェックは最小限です。
+
+|メソッド|概要|
+|----------|------|
+| `add_node(type, **fields)` |新規ノードを末尾に追加。IDを返す。初期状態はdetached |
+| `append_child(parent_id, child_id)` |親の子リスト末尾に追加|
+| `insert_before(parent_id, ref_id, new_id)` | `ref_id`の直前に挿入|
+| `detach(child_id)` |親から切り離す。ノード自体は残る|
+| `reparent(new_parent_id, first_id, last_id)` | `first_id..last_id`の兄弟範囲を新しい親へ移動|
+| `update_span(id, start_byte, end_byte)` | source spanを再設定|
+| `update_str1(id, value)` / `update_int3(id, value)` |個別slotの書き換え|
+
+### 3.2構造の参照(raw id accessors)
+
+`NO_NODE`を返しうる、生のcolumn値を取り出します。命名規則`raw_X_id`は「戻り値がnode idで、-1 (`NO_NODE`)になる可能性がある」ことを示します。
+
+|メソッド|戻り値|
+|----------|--------|
+| `raw_parent_id(id)` |親idか`NO_NODE` |
+| `raw_first_child_id(id)` / `raw_last_child_id(id)` |子idか`NO_NODE` |
+| `raw_next_sibling_id(id)` / `raw_prev_sibling_id(id)` |兄弟idか`NO_NODE` |
+
+### 3.3ペイロードの参照(column accessors)
+
+各columnを生のまま返します。「sentinelが返り得る」ことは戻り値の型から読み取ってください。
+
+|メソッド|戻り値|
+|----------|--------|
+| `type(id)` | NodeType定数(Integer) |
+| `type_name(id)` | Symbol (例: `:paragraph`) |
+| `source_start(id)` / `source_len(id)` | byte offset / byte長。`source_start < 0`はspanなし|
+| `int1(id)` / `int2(id)` / `int3(id)` | Integer (default 0) |
+| `str1(id)` / `str2(id)` | String or `nil` |
+
+### 3.4セマンティックaccessor
+
+低レベル列を解釈して「使いやすい値」を返します。`nil`を返しうるのは明示的に「無い」ことを表現するためです。
+
+|メソッド|戻り値|
+|----------|--------|
+| `source_span(id)` | `SourceSpan`か`nil` (spanなしの場合) |
+| `text(id)` | `str1`があればそれ、なければ`source.byteslice(...)`。どちらもなければ`nil` |
+
+### 3.5走査
+
+|メソッド|用途|
+|----------|------|
+| `each_child(id) { |child_id| ... }` |ブロック形式。ホットパス推奨(Enumerator不要) |
+| `child_ids(id)` | `Enumerator`を返す。`map` / `select`などのチェイン用|
+
+---
+
+## 4. NodeTypeごとのslot用法
+
+各NodeTypeがどのint / strスロットを使うかは規約で決まっています。以下が現在の規約です。
+
+### Blockノード
+
+| NodeType | int1 | int2 | int3 | str1 | str2 |
+|----------|------|------|------|------|------|
+| `DOCUMENT` | - | - | - | - | - |
+| `PARAGRAPH` | - | - | - | (transformed時のみ)結合済みliteral | - |
+| `HEADING` | level (1-6) | - | - | (transformed時のみ) inline literal | - |
+| `THEMATIC_BREAK` | - | - | - | - | - |
+| `BLOCKQUOTE` | - | - | - | - | - |
+| `LIST` | ordered? (0/1) | start_number | tight? (1=tight) | marker (`-`/`*`/`+`/`.`/`)`) | - |
+| `LIST_ITEM` | - | - | - | - | - |
+| `CODE_BLOCK` | - | - | - | code内容(literal) | info string (fencedのみ) |
+| `HTML_BLOCK` | - | - | - | HTML内容(literal) | - |
+| `TABLE` | - | - | - | - | - |
+| `TABLE_ROW` | header? (1/0) | - | - | - | - |
+| `TABLE_CELL` | header? (1/0) | - | - | strippedセルtext | - |
+| `FOOTNOTE_DEFINITION` | - | - | - | 正規化済みlabel | - |
+| `FOOTNOTES_SECTION` | - | - | - | - | - |
+
+### Inlineノード
+
+| NodeType | int1 | int2 | int3 | str1 | str2 |
+|----------|------|------|------|------|------|
+| `TEXT` | - | - | - | literal (entity decode後など)または`nil` (spanベース) | - |
+| `SOFTBREAK` / `HARDBREAK` | - | - | - | `"\n"` | - |
+| `EMPHASIS` / `STRONG` / `STRIKETHROUGH` | - | - | - | - | - |
+| `CODE_SPAN` | - | - | - | normalized content (literal) | - |
+| `LINK` | - | - | - | sanitized destination | title (or `nil`) |
+| `IMAGE` | - | - | - | sanitized destination | title (or `nil`) |
+| `HTML_INLINE` | - | - | - | matched HTML literal | - |
+| `FOOTNOTE_REFERENCE` | footnote番号 | 出現回数(同一labelのN個目) | - | 正規化済みlabel | - |
+
+> `-`は「使わない」を意味します(default値`0` / `nil`のまま)。
+
+> footnoteは`footnotes: true`時のみ生成されます。`FOOTNOTES_SECTION`はroot直下の最後の子として置かれ(span-less、`source_start: -1`)、参照された`FOOTNOTE_DEFINITION`を初回参照順に保持します。backrefの個数はfootnote番号とlabelからrender時に算出します。
+
+### Source spanの慣習
+
+- `source_start` / `source_len`: 元documentのbytes (絶対byte offset)
+- `source_start < 0`: spanなし。内容は`str1`にliteralとして持たれる(transformed paragraphやLexerのliteralモードで生じる)
+- blockノードは「自分のtext範囲」をspanとして持つ(`#`や`>`のprefixを除いた、内側のみ)
+
+---
+
+## 5.典型的な使い方
+
+### 5.1 Arenaを作って小さなASTを組み立てる
+
+```ruby
+source = "Hello *world*"
+arena = RedQuilt::Arena.new(source)
+
+doc_id = arena.add_node(RedQuilt::NodeType::DOCUMENT,
+                        source_start: 0, source_len: source.bytesize)
+
+para_id = arena.add_node(RedQuilt::NodeType::PARAGRAPH,
+                         source_start: 0, source_len: source.bytesize)
+arena.append_child(doc_id, para_id)
+
+text_id = arena.add_node(RedQuilt::NodeType::TEXT,
+                         source_start: 0, source_len: 6) # "Hello "
+arena.append_child(para_id, text_id)
+
+em_id = arena.add_node(RedQuilt::NodeType::EMPHASIS,
+                       source_start: 6, source_len: 7) # "*world*"
+arena.append_child(para_id, em_id)
+
+inner_id = arena.add_node(RedQuilt::NodeType::TEXT,
+                          source_start: 7, source_len: 5) # "world"
+arena.append_child(em_id, inner_id)
+
+arena.text(text_id)        # => "Hello "
+arena.text(inner_id)       # => "world"
+arena.source_span(em_id)   # => #<SourceSpan @start_byte=6 @end_byte=13>
+```
+
+### 5.2兄弟をループする(ホットパス)
+
+```ruby
+arena.each_child(para_id) do |child_id|
+  case arena.type(child_id)
+  when RedQuilt::NodeType::TEXT
+    output << arena.text(child_id)
+  when RedQuilt::NodeType::EMPHASIS
+    output << "<em>"
+    render_children(child_id)
+    output << "</em>"
+  end
+end
+```
+
+`Enumerator`チェインしたい場合(NodeRefなど)は以下のようにします。
+
+```ruby
+arena.child_ids(para_id).map { |id| arena.type_name(id) }
+# => [:text, :emphasis]
+```
+
+### 5.3ノードを別の親に移動する
+
+```ruby
+# `em_id`の子を全部`para_id`直下に移す
+first = arena.raw_first_child_id(em_id)
+last  = arena.raw_last_child_id(em_id)
+arena.reparent(para_id, first, last) if first != RedQuilt::Arena::NO_NODE
+
+# em_idを空のまま切り離す
+arena.detach(em_id)
+```
+
+### 5.4ノードを差し替える
+
+```ruby
+# em_idをstrong_idに置換(中身はそのまま)
+strong_id = arena.add_node(RedQuilt::NodeType::STRONG,
+                            source_start: arena.source_start(em_id),
+                            source_len: arena.source_len(em_id))
+arena.insert_before(arena.raw_parent_id(em_id), em_id, strong_id)
+
+first = arena.raw_first_child_id(em_id)
+last  = arena.raw_last_child_id(em_id)
+arena.reparent(strong_id, first, last) if first != RedQuilt::Arena::NO_NODE
+
+arena.detach(em_id)
+```
+
+### 5.5列の値を直接更新する
+
+```ruby
+# headingのレベルはint1に入っているが、書き換え専用setterは無いので
+#必要なら追加する。現在はstr1 / int3 / spanのみpublic setterあり:
+arena.update_str1(text_id, "Hello, world!")
+arena.update_int3(list_id, 1) # tightに
+arena.update_span(text_id, 0, 12)
+```
+
+なおint1 / int2 / str2のsetterは現状ありません。必要が出た時点で`update_int1`などを追加する想定です。
+
+---
+
+## 6.パフォーマンス上の注意
+
+####ホットパスでは`each_child`を使う
+
+ブロック直yieldでEnumerator allocationを避ける。`child_ids`は外部API用
+
+#### `text(id)`はstr1を優先する
+
+余計な`byteslice`を起こさないため、可能な限り`str1`にliteralを持たせない(`nil`のまま)のが基本
+
+#### `source_span(id)`は`SourceSpan`を毎回allocateする
+
+ホットパスで使うなら`source_start` / `source_len`を直接読む方が良い
+
+#### `detach`したnodeは捨て切れない
+
+大量にdetachする処理を繰り返すとarenaの列が膨らみ続ける。1つのdocumentのparse内では問題ない規模だが、長寿命のarenaには向かない
+
+---
+
+## 7.落とし穴
+
+#### `raw_*_id`の戻り値を生でforeign key参照する場合
+
+`NO_NODE` (-1)チェックを忘れない。Array#[-1]にすると配列末尾を読んでしまい、treeが壊れる
+
+#### `reparent`の前提
+
+`first_id`から`next_sibling`を辿って`last_id`に到達する必要がある。違う親のノードや、`first_id`の後ろにある到達不能な`last_id`を渡すと無限ループする可能性がある(実際builderで過去にハマった)
+
+#### `source_start < 0`の意味
+
+「位置情報を捨てたliteralモード」。ユーザーAPI (`SourceMap`, `node.source_location`等)はspanなし扱いになる。これを忘れてdebuggerで「位置情報がない」と困惑しないこと
+
+#### `@source`を後から変えない
+
+仮にやると`text` / `source_span`の戻り値が静かに壊れる
+

data/docs/commonmark-conformance.md

@@ -0,0 +1,241 @@
+# RedQuilt CommonMark Conformance
+
+## 1. 本書の位置付け
+
+本稿はRedQuiltとCommonMark / GFM specとの差分について解説する。
+spec通りに動く挙動は仕様書(<https://spec.commonmark.org/0.31.2/>、<https://github.github.com/gfm/>)を直接参照する想定で、本書では繰り返さない。
+
+#### 書く対象
+
+- specが許す範囲を実装が 狭めた 箇所(曖昧な箇所の解釈・厳格化)
+- specの範囲外の機能(セキュリティ・診断・オプションフラグ)
+- 有効化している 拡張(GFM等)とそのオプトイン条件
+- 未対応・既知の制限
+
+#### 書かない対象
+
+- specと一致する標準挙動の説明
+- 設計の経緯やデータ構造の選択
+
+### 1.1 対象バージョン
+
+- CommonMark: 0.31.2
+- GitHub Flavored Markdown: 0.29-gfm
+
+### 1.2 実装上の前提
+
+- 入力はUTF-8文字列。`force_encoding(Encoding::UTF_8)` 等の前処理は呼び出し側の責任。
+- spec§2.3 / §2.4が要求する正規化(NUL→U+FFFD、`\r\n` / `\r` → `\n`、blank lineのspace/tab限定)はいずれも実装している。
+  これはspec通りなので本書では個別項目化しない。
+
+### 1.3 各項目のフォーマット
+
+```
+### N.N <タイトル>
+
+**Spec**: 該当節とspecの規定(または曖昧さ)
+**RedQuiltの挙動**: 実装がどう振る舞うか / どこを狭めたか・拡張したか
+**実装**: ファイル:行 / 主要シンボル
+**テスト**: specファイル / example番号
+```
+
+## 2. specを厳格化している点
+
+specの文言が複数解釈を許す箇所、あるいは "must" が曖昧なまま放置されている箇所で、実装はより厳しい側を選んでいる。
+
+### 2.1 URI autolinkがU+007F (DEL) を拒否
+
+**Spec**: §6.5—URI autolinkは "ASCII control characters, space, `<`, `>`" を含まない。
+"ASCII control characters" の範囲がU+0000–U+001FのみかU+007Fも含むかは明示されていない。
+
+**RedQuiltの挙動**: U+007Fを含めて拒否。
+
+**実装**: `lib/red_quilt/inline/lexer.rb` — `URI_AUTOLINK_RE`
+**テスト**: `spec/whitespace_strictness_spec.rb` — "URI autolink (CommonMark 6.5)"
+
+### 2.2 Raw HTML tagのseparatorをspace/tab/CR/LFに限定
+
+**Spec**: §6.6— 属性間や `=` 周りのseparatorを "whitespace" と定義。
+"whitespace" の集合はspecの用語定義(§2.1)ではspace / tab / newline / line tabulation (U+000B) / form feed (U+000C) / carriage returnを含む広い集合。
+
+**RedQuiltの挙動**: tag grammarの中では `[ \t\r\n]` のみをseparatorとして許可。
+FF (U+000C) / VT (U+000B) は含めない。インラインのraw HTML、HTML blockのtype 1 / 6 / 7すべてに同じ制約を適用。
+
+**実装**:
+- インライン: `lib/red_quilt/inline/lexer.rb` — `HTML_OPEN_TAG_RE` / `HTML_CLOSING_TAG_RE`
+- ブロック: `lib/red_quilt/block_parser.rb` — `HTML_TYPE_7_OPEN_TAG_RE` /
+  `HTML_TYPE_7_CLOSING_TAG_RE` / `HTML_BLOCK_TYPE_6_RE` / type 1 regex
+
+**テスト**: `spec/whitespace_strictness_spec.rb` — "raw HTML tag whitespace (CommonMark 6.6)"
+
+### 2.3 Inline link tail separatorをspace/tab/最大1 LFに限定
+
+**Spec**: §6.3—linkのtail (`(dest "title")` 内部)は "spaces, tabs, and up to one line ending" で区切る。FF / VTへの言及は無い。
+
+**RedQuiltの挙動**: link tail内ではspace / tabのみをseparatorとし、line endingは別途1回までカウント。
+FF / VTが現れた場合はlinkとしては成立しない(段落の通常テキストとして扱う)。
+
+**実装**: `lib/red_quilt/inline/builder.rb` — `link_tail_whitespace_byte?`、
+`skip_link_whitespace`、`parse_link_tail`
+
+**テスト**: `spec/whitespace_strictness_spec.rb` — "inline link tail whitespace (CommonMark 6.3)"
+
+### 2.4 Reference definitionのraw destination検証をinline linkと同等に
+
+**Spec**: §6.3—link destinationのraw形式は "a nonempty sequence of
+characters that does not start with `<`, does not include ASCII control
+characters or space character, and includes parentheses only if (a) they are
+backslash-escaped or (b) they are part of a balanced pair of unescaped
+parentheses".
+
+**RedQuiltの挙動**: reference definitionのraw destinationでも上記すべてを検証する。
+具体的にはASCII control (U+0000–U+001F) / U+007F (DEL) / spaceを拒否、unescaped parenのdepthを追跡しアンバランスなら定義無効。
+
+**過去の挙動**: 単純な `/\A(\S+)(.*)\z/` で受けていたため、`[x]: foo(bar` や`[x]: foobar` でもdefinitionとして成立してしまっていた。
+
+**実装**: `lib/red_quilt/reference_definition.rb` — `parse_raw_destination`、`RAW_DEST_FORBIDDEN_RE`
+
+**テスト**: `spec/link_validation_spec.rb` — "reference definition raw destination validation"
+
+### 2.5 Link labelの999文字上限を全経路で適用
+
+**Spec**: §6.3— "A link label can have at most 999 characters inside the square brackets."
+
+**RedQuiltの挙動**: reference definition側とreference link使用側(shortcut / collapsed / fullすべて)で999文字超を拒否。
+
+**実装**:
+- 定数: `lib/red_quilt/reference_definition.rb` — `LABEL_MAX_LENGTH = 999`、`label_too_long?` ヘルパ
+- 定義側: `match_label`(単一行・複数行のどちらでも判定)
+- 使用側: `lib/red_quilt/inline/builder.rb` — `try_reference_link` / `read_reference_label`
+
+**テスト**: `spec/link_validation_spec.rb` — "link label length limit (999 characters)"
+
+### 2.6 NCRの桁上限と無効codepointのU+FFFD置換
+
+**Spec**: §6.4—decimal NCRは1–7桁、hex NCRは1–6桁。
+decode結果がU+0000、surrogate (U+D800–U+DFFF)、またはUnicode範囲外 (>U+10FFFF) になる場合はU+FFFDに置き換える。
+
+**RedQuiltの挙動**: 上記すべてを実装。
+
+**過去の挙動**: `CGI.unescapeHTML` に委譲していたため、`&#00000065;` のような8桁decimalや `&#xD800;` のようなsurrogateがそれぞれ "A" としてdecodeされたり、`RangeError` を発生させていた。
+
+**実装**: `lib/red_quilt/inline/html_entities.rb` — `Inline.decode_entity`、
+`Inline::ENTITY_RE`、`decode_numeric_codepoint`。`SURROGATE_RANGE`、
+`MAX_UNICODE_CODEPOINT` 定数。
+
+**テスト**: `spec/numeric_character_reference_spec.rb`
+
+### 2.7 GFM tableのheader / delimiter列数一致要件
+
+**Spec (GFM§4.10)**: "The header row must match the delimiter row in the number of cells. If not, a table will not be recognized."
+
+**RedQuiltの挙動**: headerとdelimiterでcell数が一致しない場合、tableとして認識せずparagraphとして扱う。
+
+**実装**: `lib/red_quilt/block_parser.rb` — `table_start?`
+
+**テスト**: `spec/red_quilt_spec.rb` — "table separator validation (GFM spec)"
+
+### 2.8 GFM extended autolinkのdomain underscore制約
+
+**Spec (GFM§6.9)**: "If the domain name contains an underscore (`_`) in its last two segments, it is invalid."
+
+**RedQuiltの挙動**: extended autolinkを有効化した場合、URL / emailのdomain末尾2セグメントに `_` を含むものはlinkifyしない。
+
+**実装**: `lib/red_quilt/extended_autolink_pass.rb` — `valid_domain?` / `extract_domain`
+
+**テスト**: `spec/extended_autolink_spec.rb` — "domain validation (GFM spec)"
+
+## 3. specの範囲外の機能
+
+specには規定が無いが、RedQuilt側で安全性・利便性のために提供している機能。
+
+### 3.1 unsafe URL schemeのサニタイズ
+
+**RedQuiltの挙動**: link / imageのdestinationのschemeが以下の安全リストに含まれない場合、`href` を空文字列にして出力する。
+同時に `:unsafe_url` のdiagnosticをwarningとして発行する。
+
+**安全スキーム**: `http`、`https`、`mailto`、`ftp`、`tel`、`ssh`
+
+**ブロックされる代表例**: `javascript:`、`vbscript:`、`data:`
+
+**実装**: `lib/red_quilt/inline/builder.rb` — `SAFE_SCHEMES`、sanitize_destination`
+
+**テスト**: `spec/red_quilt_spec.rb` — "sanitizes unsafe URL schemes"
+
+### 3.2 Diagnostics
+
+**RedQuiltの挙動**: parse / render中に検出した不審な構文・参照漏れ・潜在的なセキュリティ事象を `RedQuilt::Diagnostic` として `Document#diagnostics` に
+蓄積する。
+処理は中断しない(常にtreeとHTMLが返る)。
+
+**現状で発行されるrule**:
+
+| Rule | Severity | 内容 |
+|---|---|---|
+| `:missing_reference` | warning | full reference link `[text][ref]` の定義が無い |
+| `:duplicate_reference` | warning | 同じlabelのreference definitionが複数あった(最初の定義を採用) |
+| `:unsafe_url` | warning | safe schemeリストに無いURLを空hrefに置換した |
+
+**実装**: `lib/red_quilt/diagnostic.rb`(値オブジェクト)、`lib/red_quilt/block_parser.rb`(duplicate)、`lib/red_quilt/inline/builder.rb`(missing / unsafe)
+
+### 3.3 `allow_html` / `disallow_raw_html` フラグ
+
+**RedQuiltの挙動**:
+
+| Flag | Default | 効果 |
+|---|---|---|
+| `allow_html` | `false` | 偽の場合、raw HTMLは全エスケープ(`&lt;` 化)で出力。真にするとHTML block / inline raw HTMLが原文のまま出力される |
+| `disallow_raw_html` | `false` | `allow_html: true` 下で有効化するGFM "Disallowed Raw HTML" 拡張。指定タグ群の `<` を `&lt;` に書き換える |
+
+GFMが定めるdisallowedタグ群: `title`, `textarea`, `style`, `xmp`, `iframe`, `noembed`, `noframes`, `script`, `plaintext`
+
+**実装**: `lib/red_quilt/document.rb` — `allow_html?` / `disallow_raw_html?`
+**実装(filter)**: `lib/red_quilt/renderer/html.rb` — `DISALLOWED_RAW_TAGS` /
+`DISALLOWED_RAW_TAG_RE` / `filter_disallowed_raw`
+
+## 4. 有効化している拡張
+
+### 4.1 GFM Table
+
+常時有効。specの仕様に加えて2.7のcolumn count一致要件を適用。
+
+**実装**: `lib/red_quilt/block_parser.rb` — `table_start?` / `parse_table`
+
+### 4.2 GFM Strikethrough
+
+常時有効。`~~text~~` の2連tildeのみ対応(GFMの挙動と一致)。単一tilde`~text~` は通常テキストとして扱う。
+
+**実装**: `lib/red_quilt/inline/builder.rb`(`scan_delim_run` 内の `~` 取扱)、`lib/red_quilt/inline/lexer.rb`(`SPECIAL_BYTES` に `0x7E`)
+
+### 4.3 GFM Disallowed Raw HTML
+
+オプトイン。`allow_html: true, disallow_raw_html: true` を併用したときのみ動作する(`allow_html: false` 下では全HTMLがエスケープされるため意味がない)。
+詳細は3.3参照。
+
+### 4.4 GFM Extended Autolink
+
+オプトイン。`extended_autolinks: true` を指定すると `ExtendedAutolinkPass` がパスとして走り、`<...>` で囲まれていない裸のURL / email / `www.` 始まり等をリンク化する。
+
+**追加制約**: 2.8のdomain underscoreチェックを実装。
+
+**実装**: `lib/red_quilt/extended_autolink_pass.rb`
+
+## 5. 未対応 / 既知の制限
+
+- GFM Task List Items (`- [ ]` / `- [x]`) は未対応。通常のlist itemとしてパースされる。
+
+## 6. テストとの対応関係
+
+差分項目を検証するspecファイルを集約する。
+
+| 観点 | specファイル |
+|---|---|
+| 公式CommonMark exampleの通過 | `spec/commonmark_compat_spec.rb` |
+| 入力正規化(行終端 / NUL / blank line) | `spec/input_normalization_spec.rb` |
+| Whitespace厳格化(autolink / raw HTML / link tail) | `spec/whitespace_strictness_spec.rb` |
+| Link / reference検証(label cap / raw dest) | `spec/link_validation_spec.rb` |
+| NCR桁上限と無効codepoint | `spec/numeric_character_reference_spec.rb` |
+| GFM tableのcolumn count一致 | `spec/red_quilt_spec.rb` — "table separator validation" |
+| GFM extended autolinkのdomain検証 | `spec/extended_autolink_spec.rb` |
+| URL schemeサニタイズ | `spec/red_quilt_spec.rb` — "sanitizes unsafe URL schemes" |
+| Disallowed Raw HTML | `spec/red_quilt_spec.rb` —disallow_raw_html系 |