特殊コメントで定義識別子・実装先を明示できるようにする

[TwoSquirrels]

動機

#20 の文書化 (#93) で「識別子近似の設計上の限界」として整理した 2 つのケースに、opt-in の脱出口を用意したい。

1. マクロで宣言の名前を生成するファイル (X-macro 等): 登録時の解析はプリプロセスをしないため、生成される名前が記録されない。前方宣言を併記する回避策を文書化したが、C++ には宣言だけを単独で書けない構文があり、これらが生成された場合は現状 --no-tree-shaking しか打つ手がない。
   • using エイリアス (前方宣言が存在しない)
   • concept (再宣言不可)
   • 無スコープ enum の列挙子
2. 実装先を静的に特定できない実装ファイル: 自由関数の演算子だけを定義するファイル等は、名前の付いた定義もクラス外実装も持たず、tree-shaking で消え得る。演算子定義を名前の付いた定義と同じファイルに置く構成変更でしか回避できない。

提案

ライブラリファイルに書ける特殊コメントを導入し、登録時の解析がコメントからも名前を拾えるようにする (記法は要検討):

// risundle-define Point
// risundle-implements FormalPowerSeries

• risundle-define <name>: このファイルが <name> を定義しているとみなし、tags.json の files (定義識別子) に合流させる。
• risundle-implements <type>: このファイルの実装先の型名として implements に合流させる。

設計上の筋

• 安全方針と整合: 注釈は「拾う名前を増やす」方向にしか働かないため、「過剰検出は無害」(architecture.md) の原則の範囲内。注釈の無いライブラリの挙動は一切変わらない opt-in。
• 実装が小さい: tree-sitter はコメントもノードとして返すため、identifiers.rs の走査でコメント内容をパターン照合して合流させるだけ。tags.json のスキーマ変更は不要 (既存の files/implements に混ざるだけ)。
• 前例のある文化: 競プロ界隈は verification-helper の特殊コメント等、ツール注釈に慣れている。

懸念と要検討事項

• 「注釈無しで普通のライブラリがそのまま動く」という売りに対し、ツール固有の記法をソースに書かせる入口を開く。opt-in の脱出口に留める限り売りは損なわれないと考えるが、乱用を招かない文書化 (「まず前方宣言、それが書けない構文だけ注釈」の順で案内する等) が要る。
• 記法の命名は要検討。risundle-define / risundle-implements は grep しやすい接頭辞形式の一案。行コメント限定か、ブロックコメントも許すか。大文字小文字、複数名の列挙 (risundle-define A B C) を許すか、なども未定。
• 実装されたら docs/compatibility.ja.md の該当節 (X-macro の回避策・「修正の予定はない」の記述) を書き換える。

関連: #20 (条件の文書化)、#93 (文書の PR)

🤖 Generated with Claude Code