monstrare

monstrare

変更を主題に分け、主題ごとに「その変更の仕組みが一目で分かる図」を描いたページを作る。 読む人は全ての diff を読まなくても、何がどう繋がって動くようになったかを掴める。 全ての変更行を説明する検査は revidere の役目で、ここではしない。代わりに、変更したファイルが 1 つ残らずどれかの主題に入っていることだけをスクリプトが検査する。

$ARGUMENTS

引数にベース (origin/main など) があれば、手順 1 で --base に渡す。

手順

スクリプトは python3 "${CLAUDE_SKILL_DIR}/scripts/monstrare.py" で走らせる (以下 monstrare.py)。 同じプラグインの revidere のスクリプトを借りて動くので、revidere の dir も要る。 スクリプトは利用者の index や作業ツリーに何も書かない。自分で差分を読むときも git diff-index -p -M を使う。

1. 一覧を作る。 monstrare.py prepare [--base <ref>] をリポジトリの中で走らせる。 1 行目に作業 dir (毎回 $TMPDIR の下に新しく作られる) が、続いて範囲と変更ファイルの一覧が出る。 exit 2 はベースが決められない等の失敗、exit 3 は差分が無い。どちらも出た文をそのまま利用者に伝えて終える。
2. 読む。 今のブランチ以外を読むときは git worktree add で作業コピーを作らない。作業ツリーが clean なら git switch で切り替えて回し、終わったら戻す。出た範囲のとおり git diff-index -p -M <base> を走らせ、 変更されたファイルと、図にする流れの呼び出し元・呼び出し先まで読む。一覧にあって差分に出ないパスは 未追跡の新規ファイルなので中身を読む。図は「どこから呼ばれ、どこへ渡るか」まで読まないと描けない。
3. 書く。 下の「主題と図の規則」に従った JSON を <作業dir>/story.json に書く。
4. 検査する。 monstrare.py check <作業dir>。
   • exit 0 なら次へ。
   • exit 1 は、どの主題にも入っていないファイルがある。出たファイルを、扱っている主題の files に足すか、 新しい主題を作って story.json を直し、もう一度 check。2 回直しても残るなら次へ進む (ページに残りが出る)。
   • exit 2 は story.json が読めないか、欄が欠けているか、指したパスや行が差分に無い。名指しされた所を直して もう一度 check。2 回直しても通らなければ、出た文を利用者に伝えて終える。
5. ページにする。 monstrare.py render <作業dir> が <作業dir>/story.html を書いてパスを出す。 render も story.json を検査し直すので、手順 6 で直したあとも check を経ずに render してよい。
6. 見る。 ブラウザを操作できるツールがこのセッションにあれば、story.html を開いてページ全体を 1 枚だけ撮る (file: を開けないツールなら、作業 dir で python3 -m http.server --bind 127.0.0.1 を裏で起こして開き、撮ったら止める。 --bind を外すと、未コミットの変更を含む diff が LAN から読める)。 図の文字のはみ出し・重なり・消えた文字を 1 回だけ直して render し直す。撮り直しはしない。ツールが無ければ飛ばす。
7. 出す。 ページには変更したコードの抜粋がそのまま載る。そのことを利用者に 1 行で伝えてから、 Artifact ツールで story.html を publish し、リンクを返す。ツールが作業 dir のファイルを読めないと断ったら、 このセッションが読める場所 (scratchpad など) へコピーして、そちらを publish する。Artifact ツールが無いセッションなら、 使えないと伝えて story.html のパスを返す。

コードへのリンクは、origin が GitHub で、指す側のコミットが origin に push 済みのときだけ付く。