notation-render

notation-render — DSL → 図（決定的レンダリング）

役割

入力された notation の DSL テキストだけを読み、決定的に図へ変換する。受け付ける notation は repo-map v1 と document-map v1。先頭のバージョン行で対応を分岐し、未知バージョンは描かず拒否する。設計の土台は notation-core、文法・検証の正本は各 DSL の grammar.md（repo-map / document-map）。この Skill はそれらを再定義せず参照する。両 DSL は 1 本のパイプラインを共有し、版差（列挙・色・scope メタキー・depth×kind）は scripts/profiles.mjs のプロファイルで切り替える。

主経路は、LLM が HTML 本文を書き起こすのではなく、同梱の実行可能レンダラー scripts/render_repo_map.mjs を実行すること。 これにより parse → validate → layout → emit がコードで機械的に走り、同じ DSL からは毎回同じ HTML/JSON が出る（下記「スクリプト」）。

入力契約（最重要）

• 入力は DSL テキストのみ。 受け付けるのは先頭行 # repo-map v1 または # document-map v1 のテキスト。バージョン行で対応を分岐し、未知バージョン（v2 等）は描かず拒否する（E-BADVERSION/E-NOVERSION）。
• DSL 以外から描かない。 自然言語の要望、口頭・チャットでのレイアウト指示、リポジトリの再走査——いずれも描画の入力にしない。図に出す情報は、すべて DSL に書かれていなければならない。
• 不足は差し戻す。 DSL に必要な情報が足りない／矛盾するときは、自分で推測して埋めず、その DSL を出した生成 Skill（repo-map-notation / document-map-notation）に戻して DSL を直してもらう。
• 詳細は references/render-contract.md。

パイプライン

parse → validate → layout → emit

1. parse — DSL を内部モデル RepoMap にする（grammar.md §4）。
2. validate — 同じ検証規則を描画前ゲートとして走らせる（grammar.md §7）。エラーがあれば描かない（処方を報告して差し戻す）。警告は報告しつつ描く。
3. layout — @layout の rank/group を尊重し、無い／部分のところは決定的アルゴリズムで配置する（references/layout-algorithm.md）。
4. emit — 固定テーマで図を書き出す（references/output-formats.md）。

スクリプト（主経路：DSL → renderer → HTML/JSON）

このパイプラインは 実行可能なレンダラーとして scripts/ に実装されている。可能な場合は、LLM が HTML 本文を考えて書くのではなく、このスクリプトを実行する。

node skills/notation-render/scripts/render_repo_map.mjs input.repo-map --format html > out.html
cat input.repo-map | node skills/notation-render/scripts/render_repo_map.mjs - --format json

• --format html|json|mermaid（既定 html）。json は parse/validate/layout 後の内部モデル確認用。
• 入力はファイルパスまたは -（stdin）。出力は stdout、診断は stderr。終了コード: 0 正常 / 1 検証エラー（描画しない）/ 2 使用法エラー。
• Node.js 標準ライブラリのみ・外部依存ゼロ。 使い方の詳細とモジュール構成は scripts/README.md。テストは node --test skills/notation-render/tests/。
• スクリプトは references/*.md と grammar.md の実装であり、正本を新設しない。挙動と仕様が食い違ったら .md を正とし、スクリプトを直す。
• HTML 出力ではノードをドラッグで移動できる（接続線・ラベルが追従）。これは閲覧時の操作のみで、リロードすると決定的な初期レイアウトに戻る（出力ファイルの決定性は壊さない）。

入力例とスナップショットは examples/（example-a.dsl ＋ 期待 HTML/JSON、layout-demo.dsl、invalid.dsl）。

出力の優先順位

1. HTML（既定・インタラクティブ Viewer・決定的な正典）— 単一ファイル、まずこれを出す。レイアウト＋テーマから組んだインライン SVG の図＋凡例に、ノードクリックで質問できる固定 UI（data-* 属性＋質問パネル＋固定スクリプト）を載せる。決定的（同じ DSL → 同じ HTML）。data-* スキーマは repo-map-interactive-viewer/references/html-viewer-contract.md を参照。Claude Code CLI 呼び出し・Python ブリッジは repo-map-interactive-viewer の責務（ここでは出さない）。
2. Mermaid（任意）— graph TD への機械的変換。Mermaid は正本にしない（レイアウトは Mermaid 任せになり決定性の対象外）。

Figma API / Figma Skill は使わない。出力先として人が後から HTML を貼るのは自由だが、この Skill は Figma を描画経路にしない。詳細は references/output-formats.md。

レイアウト（要約）

• 意味は DSL の @layout（rank / group）を尊重する。
• @layout が無い／部分的なときの既定: ランク順のレイヤー配置（上から下）。階層系の関係（contains/deploys/owns）からランクを決め、同じ group は横にクラスタする。
• 色・フォントは固定テーマ定数（少数の hex）。ケースバイケースの美学議論はしない。
• 同じ DSL からは同じ座標・同じ色が出る（references/layout-algorithm.md §決定性）。

禁止事項（強調・再掲）

入力契約の裏返しとして、次をしてはならない。

• ❌ DSL なしで図を描く。 「だいたいこんな感じで」式の自然言語から直接図を起こさない。まず DSL を要求する（無ければ repo-map-notation へ）。
• ❌ 同じ DSL から毎回違うレイアウトを出す。 レイアウトに乱数・実行時刻・気分を持ち込まない。アルゴリズムは固定（同一 DSL → 同一 HTML）。
• ❌ リポジトリを再走査して DSL を勝手に補完する。 図に足りない情報は、描画側で埋めず repo-map-notation に差し戻す。描画側はリポジトリを読まない。

reference 地図

ファイル	中身	いつ読む
references/render-contract.md	受付 notation・バージョン分岐・パイプライン・検証ゲート	入力の扱いを決めるとき
references/layout-algorithm.md	決定的レイアウト（rank / group / 座標）	配置を出すとき
references/theme.md	テーマ定数（kind ごとの色・フォント・固定 hex）	色・文字体裁を出すとき
references/output-formats.md	HTML / Mermaid の出し方、Figma 不使用	形式を選ぶとき
scripts/README.md ＋ scripts/	実行可能レンダラー本体（parser/validator/layout/emitter/CLI）と使い方	図を実際に生成するとき（主経路）

関連スキル

• repo-map-notation — リポジトリ版 repo-map v1 DSL の供給元。不足は必ずここへ差し戻す。
• document-map-notation — ドキュメント版 document-map v1 DSL の供給元。不足は必ずここへ差し戻す。
• repo-map-interactive-viewer — 出力したインタラクティブ HTML を、ローカル Claude Code とつなぐ対話ビューア（CLI/ブリッジ側）。data-* の契約はここが正本。
• notation-core — 「レンダラーは DSL だけを読む」「決定的であれ」という原則の出どころ。
• 連携全体は SKILLS_MAP.md。