ワークフローを図にする

dandori doc は、.flow をレビューする人のために図にします。図には流れの呼び出し・match・待ち・ループがすべて載り、その横に、検査が知っていて本文には書かれていないことが並びます。各呼び出しが何を呼び、どうリトライし、エラーがそれぞれどこへ行くか。呼び出しのあと各案件がどの状態になりうるか。ワークフローがどう終わりうるか、そのとき各案件がどの状態で残るか、です。

dandori doc hotel.flow > hotel.md
dandori doc hotel.flow --format html > hotel.html

図はプラットフォームによって変わりません。ビルドが書いたものではなく、検査を通った .flow から描くので、何も走らせる前に手に入ります。Temporal にはワークフローのコードを図にする画面がありません。Step Functions や Argo Workflows が描くグラフには、結果を確かめるステートやループを回すステートなど、ビルドが足したものもすべて入ります。

Markdown で、プルリクエストに

Markdown では、flow と on failure・on cancel を Mermaid のフローチャートで描きます。GitHub は、プルリクエストや issue や README の中でそのまま図にします。図の下には、すべての呼び出しの表と、すべての終わり方の表が付きます。サービスを実装するワークフローでは、その前に、サービスのメソッドと、それぞれが実行に対して何をするかの表が入ります（サービスを実装する）。Jev が申込を採点し、人の承認に回すかを規則が決める、審査の例の日本語版（examples/review/temporal/review.ja.flow）です。

flowchart TD
    start(["審査 v1"])
    s1["結果 = 採点する(…)<br>jev · jev-1.13.0<br>retry 2 times every 10 seconds on 混雑, 過負荷 · timeout 10 seconds"]
    s2(["fail 採点不能<br>#quot;申込 {申込.id} を採点できませんでした#quot;"])
    s3[["判定 = 方針(…)<br>rule 審査の方針.rule"]]
    s4{{"match 判定.決定"}}
    s6[/"返事 = 承認を求める(…)<br>自分で書くタスク（応答はコールバック）<br>timeout 3 days"/]
    s7(["fail 承認なし<br>#quot;三日たっても承認がありません#quot;"])
    s8["知らせる(…)<br>自分で書くタスク"]
    s9(["succeed 判断 = 承認"])
    s10["知らせる(…)<br>自分で書くタスク"]
    s11(["succeed 判断 = 結果.判断"])
    start --> s1
    s1 -.->|"on failure"| s2
    s1 --> s3
    s3 --> s4
    s4 -->|"人に回す"| s6
    s6 -.->|"on timeout"| s7
    s6 --> s8
    s8 --> s9
    s4 -->|"承認, 却下"| s10
    s10 --> s11
    classDef ok stroke:#2da44e,stroke-width:2px
    classDef bad stroke:#cf222e,stroke-width:2px
    class s9,s11 ok
    class s2,s7 bad

四角はタスク、両脇に線のある四角は規則、斜めの四角は外から値が届くタスク（イベントやコールバックの応答）、六角形は match、角の丸い四角は待ち、ステップを囲む枠はループです。破線の矢印は、呼び出しがその場で処理するエラーです。呼び出しの二行目は呼び方で、三行目は、流れには書かれていない宣言の中身（案件に何をするか、リトライ、タイムアウト）です。

一枚のページで、実行を光らせる

--format html は、ほかに何も要らないページを一枚書きます。図は dandori が自分で描くので、ネットワークがなくても見られます。日本語で書いた例（Temporal 版）のページは、ホテルの予約、注文、引当と発送、問い合わせ、審査 です。どのプラットフォーム向けにも一つだけ書いた請求と支払いのページもあります。日付は、規則と同じ形に、どの日付のファイルのものかを添えて描きます。

• ステップを選ぶ。 右側に、そのステップの .flow の行、そこに来たとき各案件がとりうる状態、呼ぶもの、リトライとタイムアウト、エラーがそれぞれどこへ行くか、呼び出しのあとの案件、タスクや規則の宣言が出ます。
• シナリオを選ぶ。 左には dandori scenarios が作るシナリオが、終わり方ごとに並びます。すべての分岐、エラーを処理するすべての箇所、案件の状態の移り方のすべてを通るシナリオです。選ぶと、その実行が通るところが光り、ステップの横に通った回数が出て、右側に各呼び出しの結果が並びます。
• 両方を選ぶ。 ステップを選んでいると、そこを通るシナリオが目立ち、右側にその本数が出ます。

! の付いた呼び出しには、その場で処理しないエラーがあります。そのエラーは on failure へ行くか、ワークフローを失敗させます。実行でそうなると、印が光ります。選んだものはアドレスに残る（hotel.html#run=40&node=s23）ので、リンク一つで一本の実行を見せられます。

呼び出す規則

図の上では規則の呼び出しは四角一つですが、何を決めるかは規則の中にあります。そこで doc は、ワークフローが使う規則を rulec が描いたとおりに見せます。rulec doc が描く、人が読むページを、手を加えずに、ページの言葉で入れています。

• Markdown では、最後に規則の節があり、規則ごとに <details> で畳んであります。プルリクエストの上で開けば読めます。
• ページ では、左に規則の一覧があり、規則を呼ぶステップを選ぶと、右側にボタンが出ます。どちらからも、rulec doc --format html が描くページがこのページの上に開き、ケースを打って試せます。リンクでも開け（hotel.html#rule=与信）、Esc で閉じます。

rulec が描いたものには、描いた rulec の版が入ります。

検査でエラーが見つかるワークフロー

名前と型が解決していれば、検査でエラーが見つかるワークフローも図にします。そのときの終了コードは 1 です。ページにはシナリオの代わりに診断が並び、選ぶと、そうなる例が図の上で光ります。E020 なら、案件を片付けないまま終わる実行が、図の上の一本の線になります。Markdown では、診断を dandori check の出力のまま最後に載せます。

何がどう描かれるか