@cardenelabs/dragon 0.28.0 → 0.32.0

package/src/compile/gantt.ts

@@ -0,0 +1,337 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+
+import { actorRefTable } from "./actors";
+import { 効かない矢印の欄を並べる, 向きだけを使う図が伝えない矢印の欄 } from "./edge-option-notice";
+import type { CompileNotice } from "./notice";
+import { slugify } from "./slug";
+import { 箱の題 } from "./node-title";
+import { truncateForMessage, 図の小見出し } from "./subtitle";
+import { 図表の大きさを読む } from "./chart-fields";
+/**
+ * ガントチャート (`type: gantt`) の組み立て (#2030 で `compile.ts` から移した)。
+ */
+
+export function compileGantt(doc: DslDocument, onNotice?: (n: CompileNotice) => void): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "gantt" });
+  const 既定W = 720;
+
+  /**
+   * 書いたのに効かない形を伝える。 **`console.warn` だけにしない** (#2111) = 編集画面は知らせだけを
+   * 画面に出すため、log だけだと書いている人に理由が見えない。 値の図 (`value-chart.ts`) と同じ形
+   */
+  const 伝える = (種類: CompileNotice["kind"], 名前: string, message: string, line = 0): void => {
+    onNotice?.({ kind: 種類, actor: 名前, line, message });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${message}`);
+  };
+
+  // 目盛りは **書かれた順** に並べる。 以前は `Q1=200 / Q2=600 / ...` の決め打ちで、 Q1-Q4 以外は
+  // 全て同じ位置に落ちていた。 順に並べれば月名でも週番号でも同じ規則で置ける
+  const 明示した目盛り = doc.ticks !== undefined;
+  const 目盛り: string[] = doc.ticks === undefined ? [] : [...doc.ticks];
+  const 目盛りなし: string[] = [];
+  // 最初に時期を読めなかった項目の行。 画面が案内できるようにする (値の図と同じ)
+  let 目盛りなし行 = 0;
+  const タスク: {
+    name: string;
+    title: string;
+    label: string;
+    line: number;
+    tone?: DslDocument["actors"][number]["tone"];
+    owner?: string;
+    end?: string;
+    startLabel?: string;
+    milestone?: boolean;
+    emphasis?: "primary";
+    startFraction: number;
+    precise: boolean;
+  }[] = [];
+  for (const a of doc.actors) {
+    const label = (a.value ?? a.subtitle ?? "").trim();
+    if (label === "") {
+      if (目盛りなし.length === 0) 目盛りなし行 = a.pos?.line ?? 0;
+      目盛りなし.push(a.name);
+      continue;
+    }
+    const 始まり = 時期を読む(label);
+    if (始まり === null) {
+      伝える(
+        "chart-value-unreadable",
+        a.name,
+        `type: gantt で ${truncateForMessage(a.name)} の始まり (${truncateForMessage(label)}) が読めません (帯に載せません)。 月の中の位置は \`6月+0.55\` の形で 0..1 を書いてください`,
+        a.pos?.line ?? 0,
+      );
+      continue;
+    }
+    if (!明示した目盛り && !目盛り.includes(始まり.label)) 目盛り.push(始まり.label);
+    if (明示した目盛り && !目盛り.includes(始まり.label)) {
+      伝える(
+        "chart-value-unreadable",
+        a.name,
+        `type: gantt で ${truncateForMessage(a.name)} の始まり (${truncateForMessage(始まり.label)}) は ticks にありません (帯に載せません)。 ticks = ${目盛り.map(truncateForMessage).join(" / ")}`,
+        a.pos?.line ?? 0,
+      );
+      continue;
+    }
+    // 色は帯にそのまま渡す。 箱が 1 つになっても、 書いた色が消えないようにする
+    タスク.push({
+      name: a.name,
+      title: 箱の題(a),
+      label,
+      startFraction: 始まり.fraction,
+      precise: 明示した目盛り || 始まり.written || (a.end?.includes("+") ?? false),
+      line: a.pos?.line ?? 0,
+      ...(a.tone !== undefined ? { tone: a.tone } : {}),
+      ...(a.owner !== undefined ? { owner: a.owner } : {}),
+      ...(a.end !== undefined ? { end: a.end } : {}),
+      ...(a.startLabel !== undefined ? { startLabel: a.startLabel } : {}),
+      ...(a.milestone !== undefined ? { milestone: a.milestone } : {}),
+      ...(a.emphasis !== undefined ? { emphasis: a.emphasis } : {}),
+    });
+  }
+  if (目盛りなし.length > 0) {
+    伝える(
+      "chart-value-unreadable",
+      目盛りなし[0]!,
+      `type: gantt で時期を読めない項目があります (帯に載せません): ${目盛りなし.join(", ")}。` +
+        ` \`- 設計: "Q1"\` の形で書いてください`,
+      目盛りなし行,
+    );
+  }
+
+  // 矢印は依存として読む (`- 設計 -> 実装` = 実装は設計の後)。 帯どうしを結ぶ線は描画側が
+  // 依存として描くので、 書いた矢印を捨てずに使う
+  const タスク名 = new Set(タスク.map((t) => t.name));
+  // 矢印の端の名前を引く表。 全ての図種に共通の「居ない名前」 の知らせと同じ表を使う
+  const 名前の表 = actorRefTable(doc);
+  const 依存元 = new Map<string, string[]>();
+  for (const s of doc.flow) {
+    const line = s.pos?.line ?? 0;
+    const 矢印 = `${truncateForMessage(s.from)} -> ${truncateForMessage(s.to)}`;
+    if (!タスク名.has(s.from) || !タスク名.has(s.to)) {
+      // `actors` に居ない名前を指す矢印は、全ての図種に共通の知らせ (`flow-actor-missing`) が
+      // 書いた行で伝えている。 ここでも伝えると同じ行に 2 件並ぶ (#2111)
+      if (!名前の表.has(s.from) || !名前の表.has(s.to)) continue;
+      const 時期なし = [s.from, s.to].filter((n) => !タスク名.has(n)).map(truncateForMessage);
+      伝える(
+        "chart-edge-dropped",
+        s.from,
+        `type: gantt で ${矢印} の依存を結べません (${時期なし.join(" / ")} に時期がありません)`,
+        line,
+      );
+      continue;
+    }
+    const 前工程 = 依存元.get(s.to) ?? [];
+    if (!前工程.includes(s.from)) {
+      前工程.push(s.from);
+      依存元.set(s.to, 前工程);
+    }
+    /*
+     * 帯の依存は「どちらが先か」 だけを持つ。 矢印に書いた飾りは描けないので伝える。
+     *
+     * **伝える欄を並べない** (#2366)。 以前は 文字 / 色 / 線種 / 多重度 の 4 種を手で並べて
+     * いたため、後から足した項目がどこにも入らなかった (実測 = 矢印に書ける 21 項目のうち
+     * 17 件が、図も変わらず知らせも出ないまま落ちていた)。 矢印が使う欄を除いた残り全部を伝える。
+     *
+     * 多重度もここに含める = 多重度の知らせ (#2107) と同じ行に 2 件並べない。
+     */
+    const 効かない = 効かない矢印の欄を並べる(s, 向きだけを使う図が伝えない矢印の欄);
+    if (効かない.length > 0) {
+      伝える(
+        "edge-option-not-honored",
+        s.from,
+        `type: gantt で ${矢印} に書いた ${効かない.join(" / ")} は描けません (ガントチャートの矢印は前後の関係だけを使います)`,
+        line,
+      );
+    }
+  }
+
+  // 高さは件数から決める。 描画側は 1 行 28 以上 + 行間 20 で積み、 上下に 32 / 44 の余白を取る
+  // (`kinds/gantt.tsx`)。 360 の固定だと 8 件目から最後の帯が枠の外に出る (実測 = 8 件で 56 はみ出す)
+  const 既定H = Math.max(360, 48 * タスク.length + 96);
+  const { w: CHART_W, h: CHART_H } = 図表の大きさを読む(doc, { w: 既定W, h: 既定H });
+  b.lane("gantt", { width: CHART_W });
+
+  b.node(`${slugify(doc.title) || "gantt"}-chart`, {
+    lane: "gantt",
+    stack: 0,
+    kind: "gantt-timeline",
+    title: doc.title,
+    ...図の小見出し(doc),
+    w: CHART_W,
+    h: CHART_H,
+    ganttData: タスク.map((t) => {
+      const startName = 時期を読む(t.label)?.label ?? t.label;
+      const idx = 目盛り.indexOf(startName);
+      const startIdx = idx + t.startFraction;
+      const dependencies = (依存元.get(t.name) ?? []).map((from) => slugify(from) || from);
+      const [firstDependency] = dependencies;
+      const dependsOn = firstDependency === undefined
+        ? undefined
+        : dependencies.length === 1 ? firstDependency : dependencies;
+      // 帯の誤りは、その項目を書いた行で伝える。 知らせの種類は呼ばれる側が決める (#2392)
+      const 帯を伝える = (種類: CompileNotice["kind"], 名: string, message: string): void =>
+        伝える(種類, 名, message, t.line);
+      const 終わり = 終わる位置(
+        t.end,
+        startIdx,
+        目盛り,
+        t.name,
+        帯を伝える,
+        doc,
+        t.precise,
+      );
+      const startLabel = t.startLabel ?? (t.precise ? 位置の目盛り(startIdx, 目盛り) : t.label);
+      return {
+        id: slugify(t.name) || t.name,
+        title: t.title,
+        startIdx,
+        endIdx: 終わり.idx,
+        startLabel,
+        endLabel: 終わり.label ?? startLabel,
+        ...(t.owner !== undefined ? { owner: t.owner } : {}),
+        ...(dependsOn !== undefined ? { dependsOn } : {}),
+        ...(t.tone !== undefined ? { tone: t.tone } : {}),
+        ...(t.emphasis !== undefined ? { emphasis: t.emphasis } : {}),
+        ...(t.milestone === true ? { milestone: true as const } : {}),
+      };
+    }),
+    ...(明示した目盛り ? { ganttAxisMax: 目盛り.length } : {}),
+    ...(doc.ganttToday !== undefined ? { ganttToday: doc.ganttToday } : {}),
+    ...(doc.ganttTickLabels !== undefined ? { ganttTickLabels: doc.ganttTickLabels } : {}),
+    ...(doc.ganttBarEnd !== undefined ? { ganttBarEnd: doc.ganttBarEnd } : {}),
+    ...(doc.ganttBarThickness !== undefined ? { ganttBarThickness: doc.ganttBarThickness } : {}),
+    ...(doc.ganttSize !== undefined ? { ganttSize: doc.ganttSize } : {}),
+  });
+
+  return b.build();
+}
+
+/**
+ * `{名前}` が指す状態が取りうる値を、記法に書かれた範囲で集める (#1251)。
+ *
+ * 初期値と、段が動かす先 (`tween:` の両端と `set:` の値) を見る。 数として読めない値は
+ * 落とす = 位置として使われないため、下限の判定には関係しない。
+ */
+function 状態が取る値(参照: string, doc: DslDocument): number[] {
+  const 名 = 参照.slice(1, -1);
+  const out: number[] = [];
+  const 数にする = (v: unknown): void => {
+    if (typeof v === "number") {
+      if (Number.isFinite(v)) out.push(v);
+      return;
+    }
+    // **空文字と空白だけの値を数にしない**。 `Number("")` は 0 を返すため、そのままだと
+    // 位置 0 として扱われ、始まりが 1 以降の帯に誤った知らせが出る。 描画側はこの値を
+    // 解けず始まりへ倒すので、警告する相手ではない
+    const 文字 = String(v).trim();
+    if (文字 === "") return;
+    const n = Number(文字);
+    if (Number.isFinite(n)) out.push(n);
+  };
+  for (const st of doc.animate?.states ?? []) if (st.name === 名) 数にする(st.initial);
+  for (const p of doc.animate?.phases ?? []) {
+    for (const t of p.tweens ?? []) {
+      if (t.state !== 名) continue;
+      数にする(t.from);
+      数にする(t.to);
+    }
+    for (const v of p.sets ?? []) if (v.state === 名) 数にする(v.value);
+  }
+  return out;
+}
+
+/**
+ * 工程が終わる位置を決める (#1251)。
+ *
+ * 書かなければ始まりと同じ = 帯が 1 コマ (従来の挙動)。
+ *
+ * `{名前}` を書いたらそのまま渡す。 描画側が状態を解いて位置に直すため、段で帯が伸び縮みする。
+ * その場合 **時期の名前は始まりのものを使う** = 状態が指すのは位置であって時期の名前ではなく、
+ * 帯の端に出す字が段ごとに変わるわけではない。
+ *
+ * 時期の名前を書いたら、その名前の位置に終わる。 書いた名前が目盛りに無い形は始まりと同じに
+ * 倒し、**読めないことを伝える** (#2392) = 目盛りは書かれた順に作るため載っていない名前は
+ * 位置を持たないが、黙って倒すと「書いたのに 1 コマのまま」 になる。
+ * 始まりより前を書いた時 (下の分岐) と同じ扱いにする。
+ */
+function 終わる位置(
+  end: string | undefined,
+  始まり: number,
+  目盛り: readonly string[],
+  名前: string,
+  伝える: (種類: CompileNotice["kind"], 名: string, message: string) => void,
+  doc: DslDocument,
+  precise = false,
+): { idx: number | string; label?: string } {
+  if (end === undefined) return { idx: 始まり };
+  if (/^\{\w+\}$/.test(end)) {
+    // **状態が取る値は記法に全部書いてある**。 初期値と、段が動かす先 (`tween:` の両端と
+    // `set:` の値) を集めれば、始まりより前に落ちる値をここで見つけられる。
+    //
+    // 覆えないのは `values:` の式から決まる値だけ = 他の状態から計算されるため、
+    // 段ごとの結果を組み立ての時点では出せない
+    const 低い = 状態が取る値(end, doc).filter((v) => v < 始まり);
+    if (低い.length > 0) {
+      伝える(
+        "gantt-end-before-start",
+        名前,
+        `type: gantt で ${truncateForMessage(名前)} の終わり (${truncateForMessage(end)}) が始まりより前になる値を取ります (${[...new Set(低い)].join(", ")})。 始まりは ${始まり} 番目です`,
+      );
+    }
+    return {
+      idx: end,
+      ...(precise ? { label: 状態の目盛り(end, doc, 目盛り) ?? 位置の目盛り(始まり, 目盛り) } : {}),
+    };
+  }
+  const 時点 = 時期を読む(end);
+  const i = 時点 === null ? -1 : 目盛り.indexOf(時点.label);
+  // 目盛りは箱に書いた時期から作るので、どの箱も書いていない時期は位置を持たない。
+  // 読めた時期を並べて伝える = 目盛りは図ごとに変わるため、固定の一覧を文に書けない
+  if (i < 0 || 時点 === null) {
+    伝える(
+      "chart-value-unreadable",
+      名前,
+      `type: gantt で ${truncateForMessage(名前)} の終わり (${truncateForMessage(end)}) は目盛りにありません (帯を伸ばしません)。` +
+        ` 目盛りは箱に書いた時期から作ります = ${目盛り.map((x) => truncateForMessage(x)).join(" / ")} のどれかを書いてください`,
+    );
+    return { idx: 始まり };
+  }
+  // 始まりより前に終わる帯は描けない。 そのまま渡すと横幅が負になり、帯が始まりの位置から
+  // 左へはみ出す。 始まりと同じに倒して伝える (黙って倒すと「書いたのに 1 コマのまま」 になる)
+  const endIdx = precise ? i + (時点.written ? 時点.fraction : 1) - 1 : i;
+  if (endIdx < 始まり) {
+    伝える(
+      "gantt-end-before-start",
+      名前,
+      `type: gantt で ${truncateForMessage(名前)} の終わり (${truncateForMessage(end)}) が始まりより前です (始まりと同じに倒しました)`,
+    );
+    return { idx: 始まり, ...(precise ? { label: 位置の目盛り(始まり, 目盛り) } : {}) };
+  }
+  return { idx: endIdx, label: precise ? 位置の目盛り(endIdx, 目盛り) : end };
+}
+
+/** `6月+0.55` を目盛り名と、その目盛り内の位置に分ける。 */
+function 時期を読む(raw: string): { label: string; fraction: number; written: boolean } | null {
+  const m = raw.trim().match(/^(.+?)(?:\+([+-]?(?:\d+(?:\.\d+)?|\.\d+)))?$/);
+  if (m === null) return null;
+  const fraction = m[2] === undefined ? 0 : Number(m[2]);
+  if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) return null;
+  return { label: m[1]!.trim(), fraction, written: m[2] !== undefined };
+}
+
+function 位置の目盛り(idx: number, 目盛り: readonly string[]): string {
+  const rounded = Math.max(0, Math.min(目盛り.length - 1, Math.round(idx)));
+  return 目盛り[rounded] ?? "";
+}
+
+function 状態の目盛り(
+  ref: string,
+  doc: DslDocument,
+  目盛り: readonly string[],
+): string | undefined {
+  const values = 状態が取る値(ref, doc);
+  if (values.length === 0) return undefined;
+  return 位置の目盛り(Math.max(...values), 目盛り);
+}