@cardenelabs/dragon 0.28.0 → 0.32.0

package/src/compile/actor-option-notice.ts

@@ -0,0 +1,379 @@
+/**
+ * 箱に書いた指定が効かない時の、伝える欄の割り出しと呼び名 (#2368 で 1 箇所にまとめた)。
+ *
+ * 同じ判定を図種の族ごとの経路が使う (経路の数は下の表ではなく実装が SSOT)。
+ *
+ * | 経路 | 図種 | 起点 |
+ * |---|---|---|
+ * | 板の面 | `sequence` / `solidity` | #2358 |
+ * | 木の図 | `tree` | #2360 |
+ * | 値の図とじょうご | `pie` ほか 9 図種 + `funnel` | #2368 |
+ * | ガントチャートと体験の地図と四象限 | `gantt` / `journey` / `quadrant` | #2370 |
+ * | 骨組みの図 | `flow` / `flowchart` / `swimlane` / `topology` / `c4` / `record` | #2376 / #2382 / #2782 |
+ *
+ * 矢印の側は `edge-option-notice.ts` が同じ形を持つ (#2366)。
+ */
+import type { DslActor } from "../types";
+import type { DslDiagramShape } from "../keywords";
+
+/**
+ * 効かない箱の欄の呼び名 (#2358)。 **並べた順に知らせへ出す**。
+ *
+ * 呼び名を持たない欄は名前をそのまま出すので、ここに足し忘れても知らせは消えない。
+ * 複数の欄が 1 つの呼び名を持つ形 (位置が 4 欄) は、1 度だけ出す。
+ *
+ * **図種をまたいで 1 つの表にする** (#2360)。 同じ欄を図種ごとに別の文言で呼ぶと、
+ * 図種を変えた読み手が同じ指定だと気付けない。 どの欄を伝えるかは図種ごとの除外が決める。
+ *
+ * **箱に無い欄名を書けないようにする** (#2384)。 表と除外は箱の欄と文字で突き合わせるので、
+ * 綴りが箱と違う行は静かに何とも一致しない。 実測 = 記法の `色:` に引きずられて書いた
+ * `color` が、箱に生まれない欄名のまま残っていた (箱に入るのは `colorHex` か `tone`)。
+ */
+export const 効かない箱の欄の呼び名 = [
+  ["kind", "種類"],
+  // 呼び名 (#2390)。 板 / 木 / 骨組みの図は箱に描くので、伝えるのは値として読む図だけ
+  ["subtitle", "呼び名"],
+  ["posW", "大きさ"],
+  ["posH", "大きさ"],
+  ["posX", "位置"],
+  ["posY", "位置"],
+  ["posRel", "位置"],
+  // 位置のずらし (#1971)。 板は面ごとの箱を持たないので動かす相手が無い
+  ["layoutPos", "位置"],
+  ["rows", "行"],
+  ["tone", "色"],
+  ["colorHex", "色"],
+  ["eyebrow", "小見出し"],
+  ["value", "値"],
+  ["shape", "図形"],
+  ["previous", "前の値"],
+  ["marks", "印"],
+  ["stack", "段"],
+  ["initial", "始まりの印"],
+  ["final", "終わりの印"],
+  ["visibleIf", "出す条件"],
+  ["opacity", "透け具合"],
+  ["wBind", "値への追随"],
+  ["hBind", "値への追随"],
+  ["renderOffsetX", "値への追随"],
+  ["renderOffsetY", "値への追随"],
+  ["owner", "担当"],
+  ["stage", "段階"],
+  ["end", "終わる時期"],
+  ["startLabel", "始まりの札"],
+  ["milestone", "節目"],
+  ["emphasis", "主役"],
+  ["at", "点の位置"],
+  ["atPos", "点の位置"],
+  ["touchpoint", "接点"],
+  ["opportunity", "伸びしろ"],
+  ["opportunityPosition", "伸びしろの位置"],
+] as const satisfies readonly (readonly [keyof DslActor, string])[];
+
+/**
+ * 体験と工程の欄 (#2380)。 **どの族の除外にも入る**。
+ *
+ * 担当 (`owner`) と終わる時期 (`end`) はガントチャートが、接点 (`touchpoint`) と伸びしろ
+ * (`opportunity`) と伸びしろの位置 (`opportunityPosition`) は体験の地図が描く。 描けない図種で書いた時は
+ * `reportChartFieldsNotHonored` が図種ごとの行き先を添えて伝える。
+ *
+ * 箱の知らせが同じ欄を重ねて伝えると、1 つの欄が 2 つの名前で呼ばれる (「担当」 と `owner`)
+ * うえ、案内が食い違う = 箱の知らせは「箱を持つ図種へ」 と言うが、担当は箱を持つ図種でも
+ * 効かない。
+ *
+ * **1 か所に置いて各族が読む**。 欄を族ごとに書き並べると、新しい欄を足した日に
+ * 直し忘れた族だけが 2 件並べるようになる (実測 = 板の族だけが 4 欄を持たず、
+ * `sequence` / `solidity` の 8 通りで知らせが 2 件並んでいた)。
+ */
+export const 体験と工程の欄: ReadonlySet<string> = new Set([
+  "owner",
+  "end",
+  "startLabel",
+  "milestone",
+  "emphasis",
+  "touchpoint",
+  "opportunity",
+  "opportunityPosition",
+]);
+
+/**
+ * 板の面で、効かないと伝えない箱の欄 (#2358)。
+ *
+ * **除外側を書く**。 効かない欄を並べる形にすると、箱に欄を足した日にその欄だけが
+ * 一覧から漏れ、書いた人には「書いたのに何も起きない」 としか見えない。
+ *
+ * | 区分 | 欄 |
+ * |---|---|
+ * | 板が描く | 名前 / 題 / 呼び名 と、書いた場所と種類を書いたかの印 |
+ * | 別の知らせが受け持つ | 縦列 (`reportLaneNotHonored`) / 体験と工程の 4 欄 (#2380) |
+ *
+ * 種類 (`kind`) は図種で分かれるので、判定の側で足す。
+ */
+export const 板が伝えない箱の欄: ReadonlySet<string> = new Set([
+  "name",
+  "title",
+  "subtitle",
+  "pos",
+  "kindWritten",
+  "lane",
+  ...体験と工程の欄,
+]);
+
+/**
+ * 木の図で、効かないと伝えない箱の欄 (#2360)。
+ *
+ * | 区分 | 欄 |
+ * |---|---|
+ * | 木の図が描く | 名前 / 題 / 呼び名 / 値 と、書いた場所と種類を書いたかの印 |
+ * | 別の知らせが受け持つ | 縦列 / 位置のずらし / 体験と工程の 4 欄 |
+ *
+ * 別の知らせは順に `lane-not-honored` / `position-offset-ignored` / `chart-value-unreadable`。
+ * 除かないと同じ箱に 2 件並ぶ。 体験と工程の 4 欄は `体験と工程の欄` から読む (#2380)。
+ */
+export const 木の図が伝えない箱の欄: ReadonlySet<string> = new Set([
+  "name",
+  "title",
+  "subtitle",
+  "value",
+  "pos",
+  "kindWritten",
+  "lane",
+  "layoutPos",
+  ...体験と工程の欄,
+]);
+
+/**
+ * 箱を名前と値の組として読む図で、どの図種でも効かないと伝えない箱の欄 (#2368 / #2370)。
+ *
+ * | 区分 | 欄 |
+ * |---|---|
+ * | どの図種も読む | 名前 / 題 / 値 と、書いた場所と種類を書いたかの印 |
+ * | 別の知らせが受け持つ | 縦列 / 位置のずらし / 体験と工程の 4 欄 |
+ *
+ * 呼び名 (`subtitle`) は除かない (#2390)。 値を書いていない箱で **値として読まれる**
+ * (`a.value ?? a.subtitle`) ので除いていたが、**値を書いた箱では読む先が無い**。
+ * 除いた結果、値と呼び名を両方書いた箱では誰も伝えず、13 図種で黙って消えていた。
+ * 値を書いていない箱で鳴らさない判定は呼び元が持つ = 箱 1 つごとに決まる条件なので、
+ * 図種ごとの除外では表せない (#2384 の色番号と同じ形)。
+ *
+ * 位置 (`posX` / `posY`) は除かない = この図種では両方書いても効かないため、
+ * 片方だけの知らせ (#2362) ではなくこちらが伝える。
+ *
+ * 記法の `offsetX` / `offsetY` は `layoutPos` に入る (`position-offset-ignored` が受け持つ)。
+ * 欄の名前で判定するので、記法の項目名ではなく入った先の欄を書く。
+ *
+ * 体験と工程の欄 (`体験と工程の欄`) は、読む図種と別の知らせが受け持つ図種に分かれる。
+ * どちらも伝えないので 1 つにまとめて除く。
+ */
+const 値として読む図に共通の除外: ReadonlySet<string> = new Set([
+  "name",
+  "title",
+  "value",
+  "pos",
+  "kindWritten",
+  "lane",
+  "layoutPos",
+  ...体験と工程の欄,
+]);
+
+/**
+ * 箱を名前と値の組として読む図種と、共通に加えて読む欄 (#2368 / #2370)。
+ *
+ * **表で持つ**。 図種ごとに除外の集合を丸ごと書くと、共通部分が図種の数だけ写され、
+ * 1 つ直した日に他が古いまま残る (実測 = 値の図とじょうごで 2 つに分かれていた)。
+ *
+ * | 図種 | 共通に加えて読む欄 |
+ * |---|---|
+ * | 数を描く図 (`chart`) | 色味 (`tone`) / 前の値 (`previous`) |
+ * | じょうご | 色味 (`tone`) |
+ * | 体験の地図 / 四象限 | 無し (名前と値だけを読む) |
+ * | ガントチャート | 色味 (`tone`)。 担当と終わる時期は共通の除外に入っている |
+ */
+export const 値として読む図種: ReadonlyMap<string, readonly string[]> = new Map([
+  ["chart", ["tone", "previous"]],
+  ["funnel", ["tone"]],
+  ["gantt", ["tone"]],
+  ["journey", []],
+  ["quadrant", ["at", "atPos"]],
+]);
+
+/**
+ * 件ごとの主役 (`emphasis`) を実際に描く値の図。
+ *
+ * `chart` という node の種類だけでは円・折れ線なども混ざるため、`chart/stacked` まで
+ * 形を含めて区別する。じょうごは形を持たず、段の `emphasis` を読む。
+ */
+const 主役を読む値の図: ReadonlySet<string> = new Set(["chart/stacked", "funnel"]);
+
+/** 件ごとの `emphasis` がその図で描かれるか */
+export function 値として読む図が主役を読む(図種: string, 形?: DslDiagramShape): boolean {
+  return 主役を読む値の図.has(形 === undefined ? 図種 : `${図種}/${形}`);
+}
+
+/**
+ * その図種で、効かないと伝えない箱の欄を返す (#2370)。
+ *
+ * @param 図種 `値として読む図種` に載っている図種
+ * @returns 共通の除外に、その図種が読む欄を足した集合
+ */
+export function 値として読む図が伝えない箱の欄(図種: string): ReadonlySet<string> {
+  const 読む欄 = 値として読む図種.get(図種) ?? [];
+  if (読む欄.length === 0) return 値として読む図に共通の除外;
+  return new Set([...値として読む図に共通の除外, ...読む欄]);
+}
+
+/**
+ * 箱を並べて線で繋ぐ図 (骨組みの図) で、どの図種でも効かないと伝えない箱の欄 (#2376)。
+ *
+ * | 区分 | 欄 |
+ * |---|---|
+ * | 骨組みの図が描く | 名前 / 題 / 呼び名 / 小見出し / 値 / 行 / 色味 / 図形 / 種類 / 段 / 透け具合 / 出す条件 |
+ * | 位置と大きさ | `posX` / `posY` / `posW` / `posH` / `posRel` / `layoutPos` |
+ * | 値への追随 | `wBind` / `hBind` / `renderOffsetX` / `renderOffsetY` |
+ * | 別の知らせが受け持つ | 縦列 / 体験と工程の 4 欄 |
+ *
+ * 色番号 (`colorHex`) は除かない (#2384)。 部品を置いた箱でだけ効く欄なので
+ * 「部品の側が伝えるから重ねない」 として除いていたが、**呼び元が部品を置いた箱を
+ * 判定の入口で飛ばす** (`a.partId !== undefined`) ため重なりようがなかった。
+ * 除いた結果、部品でない箱では誰も伝えず、7 図種で黙って消えていた。
+ *
+ * 記法の `色:` は 16 進数なら `colorHex` に、色の名前なら `tone` に入る。
+ * 名前で書いた形は箱の色として効くので、伝えるのは 16 進数で書いた形だけになる。
+ *
+ * 印 (`marks`) は除かない (#2377)。 行頭の記号に読み替えるのは ER 図と状態遷移図だけ
+ * (`行頭の印にする`) で、骨組みの残りの図種では行と組にしても効かない。
+ * 効く図種で鳴らさない判定は呼び元が持つ = 図種の一覧をここに写すと、印を読む図種を
+ * 足した日に古くなる。
+ *
+ * 残るのは始まりの印 / 終わりの印 / 印 / 前の値の 4 つ。
+ * 実測 = フロー 447 枚 ・ 泳路の図 35 枚 ・ 配置の図 8 枚の見本すべてで、この 4 件が
+ * 図も変えず知らせも出さなかった。
+ *
+ * **図種ごとの違いは `骨組みの図種` が持つ** (#2382)。 状態遷移図は始まりの印と終わりの印を
+ * 読むので、その 2 欄だけ除外に足す。
+ */
+const 骨組みの図に共通の除外: ReadonlySet<string> = new Set([
+  "name",
+  "title",
+  "subtitle",
+  "pos",
+  "kindWritten",
+  "value",
+  "eyebrow",
+  "tone",
+  "rows",
+  // cdl 0.129.0-0.136.0 の表箱・部品箱の欄。 applyV05Extensions が node へ渡し、
+  // 描き手が箱の種類に応じて題・罫線・印・入れ子・線画・足として読む (#2854)。
+  "kindForm",
+  "icon",
+  "emptyRowsNote",
+  "titleAlign",
+  "rowRules",
+  "rowStripe",
+  "rowLayout",
+  "rowDividerForm",
+  "rowWell",
+  "rowMarkForm",
+  "nestIn",
+  "figureCard",
+  "shape",
+  "kind",
+  "stack",
+  "opacity",
+  "visibleIf",
+  "posX",
+  "posY",
+  "posW",
+  "posH",
+  "posRel",
+  "layoutPos",
+  "wBind",
+  "hBind",
+  "renderOffsetX",
+  "renderOffsetY",
+  "lane",
+  ...体験と工程の欄,
+]);
+
+/**
+ * 図種ごとの、共通の除外との違い (#2382)。
+ *
+ * **両方向に持つ**。 共通の除外は「どの骨組みの図も読む欄」 を集めたものなので、
+ * 図種ごとの違いは 2 通り出る。 外す側だけだと、1 つの図種だけが読む欄を持つ図種を
+ * 族に入れられない (実測 = 状態遷移図が始まりの印を読むため、族の外に置かれていた)。
+ */
+export type 骨組みの図の違い = {
+  /** その図種だけが読まない欄。 共通の除外から外して、伝える側へ回す */
+  readonly 読まない?: readonly string[];
+  /** その図種だけが読む欄。 共通の除外に足して、伝えない側へ回す */
+  readonly 読む?: readonly string[];
+};
+
+/**
+ * 箱を並べて線で繋ぐ図種と、共通の除外との違い (#2376 / #2382)。
+ *
+ * | 図種 | 違い | 理由 |
+ * |---|---|---|
+ * | フロー / 泳路の図 / 配置の図 | 無し | `compile/generic.ts` が共通の経路で箱を作る |
+ * | 分かれ道の図 (`flowchart`) | 無し | 種類は専用の形または箱の見た目として読む |
+ * | 構成の図 (`c4`) | 段 (`stack`) を読まない | `compile/c4.ts` が `a.stack` を読まない |
+ * | 行を持つ図 (`record`) | 始まりの印と終わりの印を読む | `compile/generic.ts` の札がこの図種でだけ出る |
+ */
+export const 骨組みの図種: ReadonlyMap<string, 骨組みの図の違い> = new Map([
+  ["flow", {}],
+  ["flowchart", {}],
+  ["swimlane", {}],
+  ["topology", {}],
+  ["c4", { 読まない: ["stack"] }],
+  ["record", { 読む: ["initial", "final"] }],
+]);
+
+/**
+ * その図種で、効かないと伝えない箱の欄を返す (#2376 / #2382)。
+ *
+ * @param 図種 `骨組みの図種` に載っている図種
+ * @returns 共通の除外から読まない欄を抜き、読む欄を足した集合
+ */
+export function 骨組みの図が伝えない箱の欄(図種: string): ReadonlySet<string> {
+  const 違い = 骨組みの図種.get(図種) ?? {};
+  const 読まない欄 = 違い.読まない ?? [];
+  const 読む欄 = 違い.読む ?? [];
+  if (読まない欄.length === 0 && 読む欄.length === 0) return 骨組みの図に共通の除外;
+  const 残り = new Set(骨組みの図に共通の除外);
+  for (const 欄 of 読まない欄) 残り.delete(欄);
+  for (const 欄 of 読む欄) 残り.add(欄);
+  return 残り;
+}
+
+/**
+ * 箱に書いた欄のうち、効かないものの呼び名を並べる (#2368)。
+ *
+ * **伝える欄を並べず、読む欄を除いた残り全部を返す**。 効かない欄を並べる形にすると、
+ * 箱に欄を足した日にその欄だけが一覧から漏れ、書いた人には「書いたのに何も起きない」
+ * としか見えない。 除外側を書けば、足し忘れは「余計に知らせる」 側へ倒れる。
+ *
+ * @param 箱 記法から読んだ箱 1 つ
+ * @param 伝えない欄 その図種が読む欄と、別の知らせが受け持つ欄
+ * @param 判定で外す欄 図種の中でさらに外す欄 (種類が図種で分かれる形、#2358)
+ * @returns 知らせに出す呼び名。 空なら伝えるものが無い
+ */
+export function 効かない箱の欄を並べる(
+  箱: object,
+  伝えない欄: ReadonlySet<string>,
+  判定で外す欄: readonly string[] = [],
+): string[] {
+  const 残り = new Set(
+    Object.entries(箱 as Record<string, unknown>)
+      .filter(([欄, 値]) => 値 !== undefined && !伝えない欄.has(欄))
+      .map(([欄]) => 欄),
+  );
+  for (const 欄 of 判定で外す欄) 残り.delete(欄);
+  const 効かない: string[] = [];
+  for (const [欄, 呼び名] of 効かない箱の欄の呼び名) {
+    if (!残り.delete(欄)) continue;
+    if (!効かない.includes(呼び名)) 効かない.push(呼び名);
+  }
+  // 呼び名を持たない欄は名前をそのまま出す = 読みにくい名前でも、黙って落とすよりは伝わる
+  効かない.push(...[...残り].sort());
+  return 効かない;
+}

package/src/compile/actors.ts

@@ -0,0 +1,103 @@
+import type { DslActor, DslDocument } from "../types";
+import { slugify } from "./slug";
+/**
+ * 登場人物の参照表と、並びの整え (#2030 で `compile.ts` から移した)。
+ */
+
+/**
+ * 矢印の指す先を `actors` に書いた **正規の名前** へ解決する表 (#1209)。
+ *
+ * 名前そのものに加えて **一意な slug も受ける**。 動きを書いた図の組み立ては `slugify` に
+ * 落として引くため、 `API Gateway` を `api-gateway` と書いた形が届く。 2 つ以上の名前が
+ * 同じ slug になる時は受けない = どちらを指したか決められない。
+ *
+ * **返すのは正規の名前で、 slug ではない**。 slug を返すと、 動きを書いていない図の組み立て
+ * (名前の完全一致で引く) と食い違う = 知らせは出ないのに label が消える / 題が slug に化ける /
+ * 依存が切れる、 という形になる (Round 1 で実測)。 中央で名前へ揃えれば全経路が同じ相手を指す。
+ */
+export function actorRefTable(doc: DslDocument): Map<string, string> {
+  const 表 = new Map<string, string>();
+  const slug数 = new Map<string, number>();
+  for (const a of doc.actors) {
+    const sl = slugify(a.name);
+    slug数.set(sl, (slug数.get(sl) ?? 0) + 1);
+  }
+  for (const a of doc.actors) {
+    表.set(a.name, a.name);
+    const sl = slugify(a.name);
+    if ((slug数.get(sl) ?? 0) === 1) 表.set(sl, a.name);
+  }
+  return 表;
+}
+
+/**
+ * 矢印の指す先を正規の名前へ揃えた `flow` を返す (#1209)。
+ *
+ * 解決できない矢印はそのまま残す = 図種ごとに扱いが違う (木は独自の知らせを出し、 値で描く図は
+ * 落とす)。 中央で消すとその扱いが効かなくなる。 残した分は `reportMissingFlowActors` が
+ * 知らせ、 動きを書いた図の組み立てが落とす。
+ */
+export function canonicalizeFlowActors(doc: DslDocument): DslDocument {
+  const 表 = actorRefTable(doc);
+  let 変えた = false;
+  const flow = doc.flow.map((s) => {
+    const from = 表.get(s.from) ?? s.from;
+    const to = 表.get(s.to) ?? s.to;
+    if (from === s.from && to === s.to) return s;
+    変えた = true;
+    return { ...s, from, to };
+  });
+  return 変えた ? { ...doc, flow } : doc;
+}
+
+/**
+ * 状態遷移図で、どの箱を始まり / 終わりとみなすか (#1275)。
+ *
+ * **書いた値が勝つ**。 `initial:` / `final:` は記法で書けるのに 1 度も読まれておらず、
+ * 位置だけで決まっていた (実測 = 中央の箱に `final: true` を書いても、最後に書いた箱が
+ * 「最終」 になった)。
+ *
+ * 1 つも書いていなければ従来どおり位置で決める = 書かない記法の図は変わらない。
+ * 片方だけ書いた形も、書いた側だけが切り替わる。
+ *
+ * ## 打ち消し (`initial: false`) は書いた箱にだけ効く (#2418)
+ *
+ * 書いたかどうかを `true` だけで数えていた間、`false` しか書かれていない図は
+ * 「1 つも書いていない」 扱いになって位置で決める既定へ落ちていた。 その既定は
+ * 「1 番目の箱が始まり」 なので、**打ち消しを書いた当の箱に札が出ていた** (知らせも 0 件)。
+ *
+ * 位置で決める既定から、打ち消しを書いた箱だけを外す。
+ *
+ * **「どれか 1 つでも書いたら既定を捨てる」 形にはしない** = 途中の箱に書いた
+ * `initial: false` が 1 番目の箱の札まで消す。 書き手は途中の箱のことしか言っていない。
+ */
+export function 始まりと終わりの決め方(
+  doc: DslDocument,
+  /**
+   * 並びで決める既定を使うか (#2349)。
+   *
+   * **格子に置く形では並びが始まりと終わりを意味しない**。 縦列と段を書いた図は
+   * 書いた順に左から並ぶわけではないので、「最初に書いた箱」 を初期とみなす既定は
+   * 図の見た目と合わない (実測 = 印の箱を持つ見本で、既に形が始点を示している箱へ
+   * 「初期」 の字が重ねて出た)。 書いた値はどの並べ方でも効く。
+   */
+  opts: { 並びで決める?: boolean } = {},
+): {
+  始まり: (a: DslActor, idx: number) => boolean;
+  終わり: (a: DslActor, idx: number) => boolean;
+} {
+  const 並びで決める = opts.並びで決める ?? true;
+  const 書いた始まり = doc.actors.some((a) => a.initial === true);
+  const 書いた終わり = doc.actors.some((a) => a.final === true);
+  return {
+    始まり: (a, idx) =>
+      書いた始まり ? a.initial === true : 並びで決める && idx === 0 && a.initial !== false,
+    終わり: (a, idx) =>
+      書いた終わり
+        ? a.final === true
+        : 並びで決める &&
+          idx === doc.actors.length - 1 &&
+          doc.actors.length > 1 &&
+          a.final !== false,
+  };
+}

package/src/compile/c4.ts

@@ -0,0 +1,74 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { 描ける種別 } from "./kinds";
+import { 段を読み取る } from "./rows";
+import { slugify } from "./slug";
+/**
+ * C4 preset (C4 model 階層 system context 専用 layout)
+ *
+ * 設計 ... actor.subtitle の先頭に "L1" / "L2" / "L3" を置き、 階層 lane を生成。
+ * - L1 = 全体の見取り図 (C4 model の System Context)
+ * - L2 = 動かす単位 (同 Container = 単体で動かす application や保管庫)
+ * - L3 = 部品 (同 Component)
+ *
+ * 実装 ... **中身のある段だけ** lane を作り、 使う段を左から順に詰めて横並び (contain: true で
+ * 囲む) 配置する。 3 lane を常に作ると中身のない枠が画面に残り、 描かれ損ねたように見える (#1078)。
+ * 同 lane 内の actor は内部 stack で縦並びになる (横並びは layout 制約上不可、
+ * 段の区別が視覚的に最重要)。 subtitle marker 未指定なら L1 fallback。
+ *
+ * flow ... actor 間の関係を edge で表現。
+ */
+export function compileC4(doc: DslDocument): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "infrastructure" });
+  const LANE_W = 400;
+  const LANE_GAP = 80;
+  // 段の名前は **枠に描く字** で、記法に打ち込む識別子ではない (#1886)。 打ち込む字は目印
+  // (`L1` / `L2` / `L3`) の側で、そちらは綴りを変えない
+  const 段の名前: Record<number, string> = { 1: "全体の見取り図", 2: "動かす単位", 3: "部品" };
+
+  // 段は **先頭一致** で読み、 読んだ目印は説明から落とす (`段を読み取る` の説明を参照)
+  const 割当 = doc.actors.map((a, idx) => {
+    const { 段, 説明 } = 段を読み取る(a.subtitle);
+    return { 段, 説明, id: slugify(a.name) || `n${idx}`, actor: a };
+  });
+
+  // **中身のある段だけ枠を作る**。 3 段を必ず作ると、 書いていない段が空の点線枠として残り、
+  // 見た人には「何かが描かれ損ねた」 ようにしか見えない
+  const 使う段 = [1, 2, 3].filter((lv) => 割当.some((x) => x.段 === lv));
+  使う段.forEach((lv, i) => {
+    b.lane(`c4-l${lv}`, {
+      // 空の段を飛ばした分だけ左に詰める。 飛ばした位置に隙間を残すと、 やはり
+      // 「何かが抜けている」 ように見える
+      x: i * (LANE_W + LANE_GAP),
+      width: LANE_W,
+      label: 段の名前[lv]!,
+      contain: true,
+    });
+  });
+
+  const stackPerLane: Record<string, number> = { "c4-l1": 0, "c4-l2": 0, "c4-l3": 0 };
+  for (const x of 割当) {
+    const lid = `c4-l${x.段}`;
+    const stack = stackPerLane[lid]!;
+    stackPerLane[lid] = stack + 1;
+    b.node(x.id, {
+      lane: lid,
+      stack,
+      kind: 描ける種別(x.actor.kind),
+      title: x.actor.name,
+    });
+  }
+
+  for (const s of doc.flow) {
+    const fromId = slugify(s.from);
+    const toId = slugify(s.to);
+    b.edge(fromId, toId, {
+      label: s.label,
+      ...(s.sub ? { sub: s.sub } : {}),
+      ...(s.side ? { side: s.side } : {}),
+    });
+  }
+
+  return b.build();
+}

package/src/compile/chain.ts

@@ -0,0 +1,93 @@
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslActor, DslDocument } from "../types";
+import { 書いた縦列に置く } from "./lanes";
+import { lookupPartRaw } from "./parts-lookup";
+/**
+ * 箱を鎖のように 1 本につなぐ形か (#2030 で `compile.ts` から移した)。
+ *
+ * 図種ごとの file と、`compile.ts` に残る部品の取り込みの両方が呼ぶ。
+ */
+
+/**
+ * 静止した `type: flow` かどうか。 この形だけ矢印を鎖状に作る (`compileFlow`)。
+ *
+ * 段を持つ形・縦列を書いた形・向きを書いた形は generic 経路へ回るため鎖にならない。
+ *
+ * **`compileFlow` の分岐もこの判定を使う**。 判定を 2 か所に書くと、組み立てだけが別経路へ回り、
+ * 行の対応と端の知らせが鎖のまま残る。 向きを書いた形 (#1494) は組み立てにだけ足され、`A -> C` に
+ * 書いた `head` が `C -> B` に載り、書いた端のとおりの矢印に「端は使われません」 が出ていた (#1986)。
+ */
+export function 鎖でつなぐ形か(doc: DslDocument): boolean {
+  if (doc.type !== "flow") return false;
+  return !鎖にしない書き方.some((x) => x.あてはまる(doc));
+}
+
+/**
+ * 鎖をやめて、書いた端どおりに繋ぐ書き方 (#2374)。
+ *
+ * **判定と案内を組にして持つ**。 以前は判定が 3 つの条件を見るのに、知らせの案内は
+ * 手で並べた 2 つだった (実測 = 動きを書く経路が案内に無く、読み手はその道を知れなかった)。
+ *
+ * 表から判定を導き、案内も同じ表から作る。 条件を足した日に案内が自動で追随する。
+ *
+ * どれも図の見た目を変えるので、**優先順位は付けない**。 向きを書けば並びが変わり、
+ * 縦列を書けば列ができ、動きを書けば段が付く。 どれを選ぶかは書き手が決める。
+ */
+export const 鎖にしない書き方: readonly {
+  /** 検査と読み手のための短い呼び名 */
+  名: string;
+  /** その書き方をしているか */
+  あてはまる: (doc: DslDocument) => boolean;
+  /** 知らせの案内に出す文 */
+  案内: string;
+}[] = [
+  {
+    名: "動き",
+    あてはまる: (doc) => doc.animate !== undefined && doc.animate.phases.length > 0,
+    案内: "動き (animation:) を書く",
+  },
+  {
+    名: "向き",
+    あてはまる: (doc) => doc.direction !== undefined,
+    案内: "向き (direction: 縦) を書く",
+  },
+  {
+    名: "縦列",
+    あてはまる: (doc) => 書いた縦列に置く("flow", doc),
+    案内: "箱に縦列 (lane:) を書く",
+  },
+];
+
+/** 知らせの案内に出す、鎖をやめる書き方の並び (#2374) */
+export function 鎖にしない書き方の案内(): string {
+  return 鎖にしない書き方.map((x) => x.案内).join(" / ");
+}
+
+/**
+ * 静止したフローの鎖に並べる登場人物 (#1987)。
+ *
+ * **どの行にも書かれていない部品は鎖に並べない**。 並べると、部品の前後の並び順の矢印は書き手が
+ * 部品へ引いたものではないため部品へ繋がずに外され (#1979)、部品を途中に置いた図から矢印が全て
+ * 消えていた (実測 = `受付 / 印 / 出荷` で矢印 0 本、知らせ 0 件)。 編集画面は部品を本文から抜いてから
+ * 鎖を作るので `受付 -> 出荷` を描き、カタログと絵が食い違っていた。 部品は図の下の格子に置くため、
+ * 鎖から外しても流れの列に空きは生まれない。
+ *
+ * - 部品の一覧に無い部品は仮の箱のまま描かれるので残す (一覧を渡さない組み立ても同じ)
+ * - 大きすぎて取り込まない部品は一覧にあるので外す (図に入らない場所へ鎖を通さない)
+ * - 行の端に書かれた部品は残し、#1979 の繋ぎ方に従う
+ *
+ * 鎖を作る `compileFlow`、行との対応 (`鎖のどの行から来たか`)、端の知らせ
+ * (`reportFlowEndpointNotHonored`) の 3 つがこの並びを使う。 1 つでも `doc.actors` を見ると、
+ * N 本目の矢印と行の対応がずれる。
+ */
+export function 鎖に並べる登場人物(
+  doc: DslDocument,
+  partsCatalog: Record<string, CdlDiagram> | undefined,
+): DslActor[] {
+  if (!partsCatalog) return doc.actors;
+  const 行に書かれた = new Set(doc.flow.flatMap((s) => [s.from, s.to]));
+  // 部品でない箱は `partId` を持たず一覧を引けないので、一覧に無い部品と同じく残る
+  return doc.actors.filter(
+    (a) => 行に書かれた.has(a.name) || lookupPartRaw(partsCatalog, a.partId) === undefined,
+  );
+}