@cardenelabs/cdl 0.5.0

package/src/layout.ts

@@ -0,0 +1,381 @@
+import type { CdlDiagram, LaidDiagram } from "./types";
+import {
+  CLEARANCE_LABEL_LABEL,
+  CLEARANCE_NODE_LABEL,
+} from "./layout/clearance-constants";
+import {
+  collectBBoxes,
+  detectCollisions,
+  detectNearCollisions,
+  resolveEdgeLabelOverlapsWithChainAndPropagate,
+  resolveOverlaps,
+} from "./layout/collisions";
+import { bowSharedStraightPaths, layoutEdges, repositionParallelLabels } from "./layout/edges";
+import {
+  expandLaneGapsForEdgeLabels,
+  expandLanesForNodes,
+  layoutLanes,
+  recomputeContainedLanes,
+} from "./layout/lanes";
+import { layoutNodes } from "./layout/nodes";
+import { computeViewBox } from "./layout/viewbox";
+
+/**
+ * chain 伝搬 shift の escape hatch (CAR-428 で導入、 CAR-430 で label-shift.ts 削除後も残置)。
+ *
+ * default = ON、 env `CDL_DISABLE_CHAIN_EDGE_LABEL=1` で OFF (chain 伝搬 shift を bypass)。
+ * CAR-430 で `label-shift.ts` の shift 探索は削除済のため、 OFF 時は
+ * `edges.ts routePath()` が返す init 位置がそのまま最終 label 位置になる。
+ * snapshot / preset regression 発生時の切戻し用として維持する。
+ */
+function isChainEdgeLabelDisabled(): boolean {
+  if (typeof process === "undefined") return false;
+  return process.env?.CDL_DISABLE_CHAIN_EDGE_LABEL === "1";
+}
+
+/**
+ * 同じ集合に属する node の shift を 1 つに集約する (Issue #202 の共通 logic)。
+ *
+ * 絶対値が最大のものを採用する。 最も強く押されている node が収まる位置まで集合全体を動かせば、
+ * 同じ向きに押されている他の node も干渉から外れる。
+ *
+ * ただし集合内で正負が混在する場合、 どちらを採用しても反対側の node の干渉が残る。
+ * この場合は集合を動かさない。 整列を壊してまで片側だけを救うことはせず、
+ * 残った干渉は visualValidate が検出する。
+ */
+function aggregateByGroup<K>(entries: readonly (readonly [K, number])[]): Map<K, number> {
+  const byGroup = new Map<K, number[]>();
+  for (const [key, delta] of entries) {
+    if (delta === 0) continue;
+    byGroup.set(key, [...(byGroup.get(key) ?? []), delta]);
+  }
+
+  const out = new Map<K, number>();
+  for (const [key, deltas] of byGroup) {
+    const hasNeg = deltas.some((d) => d < 0);
+    const hasPos = deltas.some((d) => d > 0);
+    if (hasNeg && hasPos) continue;
+    let strongest = 0;
+    for (const d of deltas) {
+      if (Math.abs(d) > Math.abs(strongest)) strongest = d;
+    }
+    out.set(key, strongest);
+  }
+  return out;
+}
+
+/**
+ * chain 伝搬の縦 shift を row (stack) 単位に集約する (Issue #202)。
+ *
+ * layout/nodes.ts は「同 stack 番号の node は全 lane で同じ cy になり、 lane 間 edge が
+ * 水平で揃う」 を不変条件として保証する。 chain 伝搬が node を 1 件ずつ縦に動かすと
+ * この不変条件が壊れ、 visualValidate の row-alignment が発火する。
+ *
+ * @param nodes 集約対象の node (id と stack のみ参照)
+ * @param nodeShifts chain 伝搬が返した node 別 shift
+ * @returns stack → 適用する dy。 shift 不要な stack と符号混在の stack は含まない
+ */
+export function aggregateRowDy(
+  nodes: readonly { id: string; stack: number }[],
+  nodeShifts: ReadonlyMap<string, { dx: number; dy: number }>,
+): Map<number, number> {
+  return aggregateByGroup(nodes.map((n) => [n.stack, nodeShifts.get(n.id)?.dy ?? 0] as const));
+}
+
+/**
+ * chain 伝搬の横 shift を lane 単位に集約する (Issue #202)。
+ *
+ * layout/nodes.ts は node の cx を所属 lane の中心に固定する。 chain 伝搬が node を
+ * 1 件ずつ横に動かすと同 lane 内の cx が揃わなくなり、 visualValidate の alignment /
+ * column-alignment が発火する (row 方向で cy が揃わなくなるのと同じ構造)。
+ *
+ * 実測 (dragon golden の T06 microservice mesh)。 label 回避のため svc1 だけが 100 world 左へ
+ * 押され、 同 lane の gw / svc2 / svc3 と cx がずれていた。 lane 単位に集約すると 4 node が
+ * 揃って動き、 整列を保ったまま label 回避が効く。
+ *
+ * @param nodes 集約対象の node (id と lane のみ参照)
+ * @param nodeShifts chain 伝搬が返した node 別 shift
+ * @returns lane → 適用する dx。 shift 不要な lane と符号混在の lane は含まない
+ */
+export function aggregateLaneDx(
+  nodes: readonly { id: string; lane: string }[],
+  nodeShifts: ReadonlyMap<string, { dx: number; dy: number }>,
+): Map<string, number> {
+  return aggregateByGroup(nodes.map((n) => [n.lane, nodeShifts.get(n.id)?.dx ?? 0] as const));
+}
+
+/**
+ * lane pitch の均一性を壊す横 shift を捨てる (Issue #202)。
+ *
+ * lane 中心間距離 (pitch) は `expandLaneGapsForEdgeLabels` が全対で均一に揃えている (PR #206)。
+ * visualValidate の row-gap-uniform は「同 stack の node の cx 差が揃うか」 を見るが、
+ * これは 3 node 以上が同 stack に載る時にしか判定されない。
+ *
+ * lane を 1 本だけ横に動かすと、 その lane の node が属する stack の cx 差が変わる。
+ * その stack に 3 node 以上あれば pitch のばらつきとして検出される
+ * (Codex review 実測 = 3 lane / 1 row で variance 200 > spec 40)。
+ *
+ * よって「動かす lane の node が属する stack のどれかに 3 node 以上ある」 lane の dx は捨てる。
+ * それ以外 (T 字型の疎な図など) では横 shift を効かせたまま label 回避ができる。
+ *
+ * @param dxByLane lane 単位に集約した dx
+ * @param nodes 全 node (lane / stack のみ参照)
+ * @returns 安全な dx だけを残した map
+ */
+function dropUnsafeLaneDx(
+  dxByLane: Map<string, number>,
+  nodes: readonly { lane: string; stack: number }[],
+): Map<string, number> {
+  if (dxByLane.size === 0) return dxByLane;
+
+  const nodeCountByStack = new Map<number, number>();
+  for (const n of nodes) nodeCountByStack.set(n.stack, (nodeCountByStack.get(n.stack) ?? 0) + 1);
+
+  const crowdedLanes = new Set<string>();
+  for (const n of nodes) {
+    if ((nodeCountByStack.get(n.stack) ?? 0) >= 3) crowdedLanes.add(n.lane);
+  }
+
+  const out = new Map<string, number>();
+  for (const [lane, dx] of dxByLane) {
+    if (crowdedLanes.has(lane)) continue;
+    out.set(lane, dx);
+  }
+  return out;
+}
+
+/**
+ * chain 伝搬の shift を row / lane 単位に集約して node と lane に適用する (Issue #202)。
+ *
+ * 縦は `aggregateRowDy` (同 stack で共通)、 横は `aggregateLaneDx` (同 lane で共通)。
+ * layoutNodes が保証する 2 つの不変条件 (同 stack は同 cy / 同 lane は同 cx) を保ったまま、
+ * label 回避の押し出しを効かせる。
+ *
+ * lane 単位の dx は lane 矩形にも同じ量を適用する。 node の cx は lane 中心に固定される
+ * 前提なので、 node だけ動かすと lane からはみ出し `node-inside-lane` /
+ * `lane-cx-consistency` が発火する (Codex review 指摘)。
+ *
+ * **node も lane も 1 件も動かない場合は null を返す。** 呼び元はこの時 node 配列を差し替えず、
+ * 元の参照を保つ必要がある。 参照が変わると layout.ts が「node が動いた」 と判定して
+ * `layoutEdges` を再実行し、 chain 伝搬が確定させた label 位置 (labelX / labelY) を
+ * 捨ててしまう。 符号混在で集合を動かさない場合がまさにこの経路に該当する。
+ *
+ * @param nodes 適用対象の node
+ * @param lanes 適用対象の lane
+ * @param nodeShifts chain 伝搬が返した node 別 shift
+ * @returns 座標が変わった node / lane。 1 件も動かないなら null
+ */
+export function applyRowLevelNodeShifts<
+  N extends { id: string; stack: number; lane: string; cx: number; cy: number },
+  L extends { id: string; x: number },
+>(
+  nodes: readonly N[],
+  lanes: readonly L[],
+  nodeShifts: ReadonlyMap<string, { dx: number; dy: number }>,
+): { nodes: N[]; lanes: L[] } | null {
+  const dyByStack = aggregateRowDy(nodes, nodeShifts);
+  const dxByLane = dropUnsafeLaneDx(aggregateLaneDx(nodes, nodeShifts), nodes);
+  let moved = false;
+  const outNodes = nodes.map((n) => {
+    const dx = dxByLane.get(n.lane) ?? 0;
+    const dy = dyByStack.get(n.stack) ?? 0;
+    if (dx === 0 && dy === 0) return n;
+    moved = true;
+    return { ...n, cx: n.cx + dx, cy: n.cy + dy };
+  });
+  const outLanes = lanes.map((l) => {
+    const dx = dxByLane.get(l.id) ?? 0;
+    if (dx === 0) return l;
+    moved = true;
+    return { ...l, x: l.x + dx };
+  });
+  return moved ? { nodes: outNodes, lanes: outLanes } : null;
+}
+
+/**
+ * Layout engine
+ *
+ * 規約 (SPEC.md §Layout engine 規約 と一致)。
+ * - lane が x 軸 column を決める
+ * - node は lane 内 stack 順で縦並び、 各 stack 間 gap 80px、 上端 80px
+ * - lane label は lane 上部 30px 高
+ * - contain: true の lane は内部 node 全部を 24px padding で囲む boundary
+ * - edge routing は orthogonal L 字 (起点 side → 中継 → 終点 side)、 左右 lane 跨ぎは S 字 bezier
+ * - edge label は path 中点から path 進行方向の垂直方向に 50-80px、 node bbox を避ける
+ * - viewBox は cdl が auto 計算 (右端 +80 / 下端 +80)
+ */
+export function layout(diag: CdlDiagram): LaidDiagram {
+  const lanes = layoutLanes(diag);
+  const rawNodes = layoutNodes(diag, lanes);
+  const expandedLanes = expandLanesForNodes(lanes, rawNodes);
+  // CAR-470 SSOT ... 隣接 lane 対を跨ぐ edge label の収納幅を engine 側で先手確保。
+  // 拡張後、 後続 lane は cumulative shift で連鎖 shift される。 lane.width は
+  // `expandLanesForNodes` 後の値のまま (node 収納 phase と gap 拡張 phase を分離)。
+  const gapExpandedLanes = expandLaneGapsForEdgeLabels(expandedLanes, rawNodes, diag.edges);
+  const nodes = rawNodes.map((n) => {
+    // posX / posY を明示した node は「user が固定した絶対座標」 なので lane 中心に引き戻さない。
+    //
+    // 本 map は gap 拡張で lane が動いた分を node に反映するためのものだが、 無条件に
+    // `lane.x + lane.width / 2` を代入していたため、 `layoutNodes` が尊重した posX が
+    // ここで捨てられていた。 結果 **全 diagram type で node の横位置を指定できず**、
+    // 「lane = actor」 の type (sequence / solidity / swimlane) 以外は自由配置が不可能だった。
+    //
+    // 実測 (修正前) = flow / state / topology のいずれも posX: 500 を書いて cx が変わらない。
+    if (n.posX !== undefined && n.posY !== undefined) return n;
+    const oldLane = lanes.find((l) => l.id === n.lane);
+    const newLane = gapExpandedLanes.find((l) => l.id === n.lane);
+    if (!oldLane || !newLane) return n;
+    return { ...n, cx: newLane.x + newLane.width / 2 };
+  });
+  const containedLanesPre = recomputeContainedLanes(gapExpandedLanes, nodes);
+  const edgesPre = layoutEdges(diag, nodes, containedLanesPre);
+
+  // 衝突 → 自動再配置 (同 kind=node 同士のみ、 sequence preset の lifeline 等は据え置き)。
+  // node の cy を shift した後は lane の contain bbox と edge routing も再計算が必要。
+  const bboxesPre = collectBBoxes(containedLanesPre, nodes, edgesPre);
+  const collisionsPre = detectCollisions(bboxesPre, edgesPre);
+  const nodesResolved = resolveOverlaps(nodes, collisionsPre);
+  const moved = nodesResolved !== nodes;
+  const containedLanes = moved ? recomputeContainedLanes(gapExpandedLanes, nodesResolved) : containedLanesPre;
+  const edgesAfterMove = moved ? layoutEdges(diag, nodesResolved, containedLanes) : edgesPre;
+
+  // post-pass (CAR-430 = SSOT 一本化) ... edges.ts routePath() が返す init 位置を SSOT とし、
+  // label 重複が生じた場合のみ chain 伝搬 shift (resolveEdgeLabelOverlapsWithChain) で解消。
+  //
+  // 旧実装 (CAR-430 以前) は post-pass 1 = shiftLabelsAwayFromNodes (16 方向 × 26 段階全探索) +
+  // post-pass 2 = resolveEdgeLabelOverlapsWithChain の 2 段構成で label 位置を再計算していた。
+  // 二重権限による予測困難な label 配置を解消するため、 CAR-430 で post-pass 1 を削除、
+  // chain 伝搬 shift を label 重複解消の単一 SSOT にした。
+  //
+  // fixedObstacles = node + lane-label bbox のみ (edge-path は resolveEdgeLabelOverlapsWithChain
+  // の設計 SSOT に従い chain shift 対象外)。 escape hatch = env `CDL_DISABLE_CHAIN_EDGE_LABEL=1` で
+  // OFF にすると edges.ts init 位置がそのまま最終 label 位置になる。
+  //
+  // minClearance = SSOT clearance の max (CLEARANCE_LABEL_LABEL=36 と CLEARANCE_NODE_LABEL=32)。
+  // 旧 default 16 では chain shift 後に near collision (32/36 base の閾値) が残る問題を
+  // 解消するため、 pair 別 clearance の worst case で shift 量を決める。
+  const chainShiftClearance = Math.max(CLEARANCE_LABEL_LABEL, CLEARANCE_NODE_LABEL);
+  // CAR-482 = chain 伝搬拡張版 (resolveEdgeLabelOverlapsWithChainAndPropagate) を採用、 label 移動先方向
+  // の node / lane-label も同方向同量 shift 連鎖。 既存 preset で label overlap 未発火なら shift 0 で
+  // 素通し (snapshot 100% 保持)。 escape hatch (CDL_DISABLE_CHAIN_EDGE_LABEL=1) は edges.ts init 位置維持。
+  //
+  // CAR-485 拡張 = label ↔ edge-path (別 edge) near-collision も検出、 label + 別 edge の path.d を
+  // 同方向連鎖 shift。 propagateResult.edges は label shift (labelX/labelY) + path shift (d 平行移動)
+  // 両方 apply 済 (applyEdgeLabelAndPathShifts helper) のため、 layout.ts 側追加処理は不要。
+  // path shift 情報は propagateResult.edgePathShifts で参照可能 (debug / test / future 用途)。
+  let edges: typeof edgesAfterMove;
+  let nodesFinal = nodesResolved;
+  let containedLanesFinal = containedLanes;
+  // lane 単位 dx を適用した後の lane 群。 chain 伝搬が lane を動かさなければ元のまま。
+  let laneShiftedBase: typeof gapExpandedLanes = gapExpandedLanes;
+  if (isChainEdgeLabelDisabled()) {
+    edges = edgesAfterMove;
+  } else {
+    const propagateResult = resolveEdgeLabelOverlapsWithChainAndPropagate(
+      edgesAfterMove,
+      collectBBoxes(containedLanes, nodesResolved, []).filter(
+        (b) => b.kind === "node" || b.kind === "lane-label",
+      ),
+      chainShiftClearance,
+    );
+    edges = propagateResult.edges;
+    // node / lane-label chain 伝搬 shift を反映 (CAR-482)。
+    //
+    // 縦方向は row (stack) 単位で動かす (Issue #202、 集約規則は aggregateRowDy SSOT)。
+    //
+    // 縦 shift を撤去すると label から退いていた node が戻って clearance が悪化する
+    // (catalog 実測 = clearance 17 → 25 件)。 label 回避の効果は残したいので、
+    // 同 stack の node を同じ dy で一括移動して整列を保つ。
+    // 実測 = 全 axis 合計 39 → 26 件、 row-alignment は 6 → 0 件。
+    //
+    // 横方向 (dx) は lane 中心に紐づくため node ごとの値をそのまま使う。
+    if (propagateResult.nodeShifts.size > 0) {
+      // 1 件も動かない場合は null が返る。 その時 nodesFinal は nodesResolved の参照のままとなり、
+      // 下の `nodesFinal !== nodesResolved` 判定が false になって layoutEdges 再実行を回避する。
+      // これにより chain 伝搬が確定させた label 位置が捨てられない。
+      const shifted = applyRowLevelNodeShifts(nodesResolved, gapExpandedLanes, propagateResult.nodeShifts);
+      if (shifted) {
+        nodesFinal = shifted.nodes;
+        laneShiftedBase = shifted.lanes;
+      }
+    }
+    // lane-label は独立 bbox として collect されるが、 現状 lane 自体の Y には影響しない
+    // (lane-label は render 時 lane.y + 8 offset で描画、 chain shift は future work)。
+    // node shift 発生時は contain lane bbox 再計算が必要。
+    if (nodesFinal !== nodesResolved) {
+      containedLanesFinal = recomputeContainedLanes(laneShiftedBase, nodesFinal);
+      // CAR-491 SSOT ... node が chain shift で移動した後 layoutEdges を再実行、 edge の起点/終点
+      // が shift 後 node 位置に追従するようにする。 旧実装は propagateResult.edges (shift 前 node
+      // 座標基準の path) をそのまま最終 edge として返却していたため、 topology ecs→rds のように
+      // rds を +108 world Y shift した後 vertical straight path の終点 Y=688 が rds top Y=796 に
+      // 到達せず 108 world gap の arrow marker 浮き症状が発生していた。
+      //
+      // 再実行後の chain 伝搬 label shift は失われるため trade-off がある ... 現状の SSOT は
+      // 「endpoint 追従 > label shift 保持」 = endpoint 切断は視覚的に致命 (arrow marker が空中
+      // 浮遊)、 label overlap は engine が最終段階で警告可能。 今後 label shift を再度保存する
+      // 必要が生じたら labelX/labelY を propagateResult 側から edgePathShifts と同 map に保存し、
+      // 再実行後の edges に merge する二段階 approach を検討する。
+      edges = layoutEdges(diag, nodesFinal, containedLanesFinal);
+    }
+  }
+
+  // 同じ 2 点を結ぶ複数の線を弓なりに分ける (dragon #941)。 label と path が確定した後に動かす =
+  // 確定前に判定すると、 後から動く label の位置を見て分離を諦める。 座標を明示した edge
+  // (canvas pivot) は「指定した直線が最終 path」 が公開契約なので対象から外す。
+  const positionedEdgeIds = new Set(
+    diag.edges
+      .filter((e) => e.posX1 !== undefined && e.posY1 !== undefined && e.posX2 !== undefined && e.posY2 !== undefined)
+      .map((e) => e.id),
+  );
+  bowSharedStraightPaths(edges, nodesFinal, positionedEdgeIds);
+  // 弧が確定してから、 同じ節の組を結ぶ辺の label を「兄弟の線を跨がない位置」 へ置き直す (#376)。
+  // 順序が逆だと、 直線を前提に置いた label を弧が貫く。 label を先に線から離すと、 今度は弧を
+  // 膨らませる判定が label を障害物と見なして弧が消える。
+  repositionParallelLabels(edges, nodesFinal);
+
+  const bboxes = collectBBoxes(containedLanesFinal, nodesFinal, edges);
+  const collisions = detectCollisions(bboxes, edges);
+  const nearCollisions = detectNearCollisions(bboxes, edges);
+
+  if (collisions.length > 0) {
+    for (const c of collisions) {
+      console.warn(
+        `[cdl layout] overlap: ${c.a.kind}#${c.a.id} ∩ ${c.b.kind}#${c.b.id} = ${Math.round(c.overlap_area)}px²`,
+      );
+    }
+  }
+  if (nearCollisions.length > 0) {
+    for (const c of nearCollisions) {
+      console.warn(
+        `[cdl layout] near: ${c.a.kind}#${c.a.id} ↔ ${c.b.kind}#${c.b.id} = ${Math.round(c.gap)}px (need ${c.required}px)`,
+      );
+    }
+  }
+
+  const viewBox = computeViewBox(containedLanesFinal, nodesFinal, edges, bboxes, diag.viewport);
+
+  return {
+    id: diag.id,
+    topic: diag.topic,
+    viewBox,
+    lanes: containedLanesFinal,
+    nodes: nodesFinal,
+    edges,
+    states: diag.states,
+    phases: diag.phases,
+    bboxes,
+    collisions,
+    nearCollisions,
+    // 図全体の倍率は座標に掛けず、 描画側 (stage.tsx) に委ねる。
+    // 座標に掛けると衝突検出 / validation の閾値 (等倍前提) と基準がずれる。
+    diagramScale: normalizeDiagramScale(diag.viewport?.scale),
+  };
+}
+
+/** 図全体の倍率を実用範囲に丸める。 1 / 未指定 / 不正値は undefined (= 倍率なしと同じ扱い)。 */
+function normalizeDiagramScale(scale: number | undefined): number | undefined {
+  if (scale === undefined) return undefined;
+  if (!Number.isFinite(scale) || scale <= 0) return undefined;
+  const clamped = Math.min(8, Math.max(0.125, scale));
+  return Math.abs(clamped - 1) < 1e-6 ? undefined : clamped;
+}