@cardenelabs/cdl 0.5.0

package/src/validate.ts

@@ -0,0 +1,268 @@
+import type { CdlDiagram } from "./types";
+import { TONES as TONE_NAMES, NODE_KINDS } from "./types";
+
+const TONES = new Set<string>(TONE_NAMES);
+const KINDS = new Set<string>(NODE_KINDS);
+const ENG_BANNED = /\b(FUNCTION|STORAGE|EVENT LOG|BALANCES MAPPING|READ|WRITE|EMIT|CALL)\b/;
+
+/**
+ * cdl が compile される前に通る validator。
+ * 構造的破綻 (重複 id / 不存在 id 参照 / 必須要素 0 件 等) は throw、
+ * 文体警告 (japanese-only 違反) は console.warn で build を止めない。
+ *
+ * error 統一 format ... `[cdl] {category}: {detail}` で grep / 著者の locate が楽に。
+ */
+export function validate(diag: CdlDiagram): void {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // ───────────────────────────────────────────────────────────
+  // 1. 必須要素の存在
+  // ───────────────────────────────────────────────────────────
+  if (diag.lanes.length === 0) {
+    errors.push(
+      `[cdl] empty: lane が 0 件です\n  → 修正例: diagram("${diag.id}", { topic }).lane("col1", { x: 0, width: 400 }).node(...).build()`,
+    );
+  }
+  if (diag.nodes.length === 0) {
+    errors.push(
+      `[cdl] empty: node が 0 件です\n  → 修正例: .node("a", { lane: "col1", stack: 0, kind: "actor", title: "Client" })`,
+    );
+  }
+  if (diag.phases.length === 0) {
+    errors.push(
+      `[cdl] empty: phase が 0 件です (animation を駆動するための最低 1 phase が必要)\n  → 修正例: .phase("p1", { duration: 1800, title: "step 1", body: "..." }, p => p.activate("a"))`,
+    );
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 2. 重複 id 検出 (lane / node / edge / state / phase)
+  // ───────────────────────────────────────────────────────────
+  const checkDup = (kind: string, items: Array<{ id: string }>) => {
+    const seen = new Map<string, number>();
+    items.forEach((item, idx) => {
+      const prev = seen.get(item.id);
+      if (prev !== undefined) {
+        errors.push(`[cdl] duplicate-id: ${kind} "${item.id}" が ${prev} 件目 + ${idx} 件目で重複`);
+      } else {
+        seen.set(item.id, idx);
+      }
+    });
+  };
+  checkDup("lane", diag.lanes);
+  checkDup("node", diag.nodes);
+  checkDup("edge", diag.edges);
+  checkDup("state", diag.states);
+  checkDup("phase", diag.phases);
+
+  // ───────────────────────────────────────────────────────────
+  // 3. tone / kind 妥当性
+  // ───────────────────────────────────────────────────────────
+  for (const e of diag.edges) {
+    if (!TONES.has(e.tone)) {
+      errors.push(`[cdl] unknown-tone: edge "${e.id}" tone "${e.tone}" は未対応 (${[...TONES].join(" / ")} のいずれか)`);
+    }
+  }
+  for (const n of diag.nodes) {
+    if (!KINDS.has(n.kind)) {
+      errors.push(`[cdl] unknown-kind: node "${n.id}" kind "${n.kind}" は未対応 (${[...KINDS].join(" / ")} のいずれか)`);
+    }
+    // 未知の tone は描画側が無言で既定色に落とすので、 typo が気付かれずに残る。
+    if (n.tone !== undefined && !TONES.has(n.tone)) {
+      errors.push(`[cdl] unknown-tone: node "${n.id}" tone "${n.tone}" は未対応 (${[...TONES].join(" / ")} のいずれか)`);
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 4. 不存在 id 参照 (lane / node / edge / state)
+  // ───────────────────────────────────────────────────────────
+  const laneIds = new Set(diag.lanes.map((l) => l.id));
+  const nodeIds = new Set(diag.nodes.map((n) => n.id));
+  const edgeIds = new Set(diag.edges.map((e) => e.id));
+  const stateIds = new Set(diag.states.map((s) => s.id));
+
+  // 「もしかして」 サジェスト (typo 検出): edit distance 1 で最も近い候補 1 件
+  const suggest = (target: string, candidates: Set<string>): string => {
+    const list = [...candidates];
+    if (list.length === 0) return "";
+    let best = "";
+    let bestD = Infinity;
+    for (const c of list) {
+      const d = levenshtein(target, c);
+      if (d < bestD) {
+        bestD = d;
+        best = c;
+      }
+    }
+    return bestD <= 2 ? ` (もしかして "${best}"?)` : ` (定義済 lane: ${list.slice(0, 5).join(", ")}${list.length > 5 ? "..." : ""})`;
+  };
+  for (const n of diag.nodes) {
+    if (!laneIds.has(n.lane)) {
+      errors.push(
+        `[cdl] unknown-ref: node "${n.id}" の lane "${n.lane}" が未定義です${suggest(n.lane, laneIds)}\n  → 修正例: .lane("${n.lane}", { x: 0, width: 400 }) を node 宣言前に追加`,
+      );
+    }
+  }
+  for (const e of diag.edges) {
+    if (!nodeIds.has(e.from)) {
+      errors.push(
+        `[cdl] unknown-ref: edge "${e.id}" の from "${e.from}" が node に存在しません${suggest(e.from, nodeIds)}\n  → 修正例: .node("${e.from}", { lane: "...", stack: 0, kind: "actor", title: "..." }) を edge 宣言前に追加`,
+      );
+    }
+    if (!nodeIds.has(e.to)) {
+      errors.push(
+        `[cdl] unknown-ref: edge "${e.id}" の to "${e.to}" が node に存在しません${suggest(e.to, nodeIds)}\n  → 修正例: .node("${e.to}", { lane: "...", stack: 0, kind: "...", title: "..." }) を edge 宣言前に追加`,
+      );
+    }
+    if (e.from === e.to) {
+      errors.push(
+        `[cdl] self-loop: edge "${e.id}" の from と to が同じ node "${e.from}" です (self-loop は現状未対応)\n  → 別 node を作って 2 段に分けるか、 後続 PR の self-loop support を待ってください`,
+      );
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 5. phase activate / tween の id 参照 (error 昇格)
+  // ───────────────────────────────────────────────────────────
+  for (const p of diag.phases) {
+    for (const id of p.activate) {
+      if (!nodeIds.has(id) && !edgeIds.has(id)) {
+        errors.push(`[cdl] unknown-ref: phase "${p.id}" の activate "${id}" は node でも edge でもない (typo の可能性)`);
+      }
+    }
+    for (const t of p.tweens) {
+      if (!stateIds.has(t.stateId)) {
+        errors.push(`[cdl] unknown-ref: phase "${p.id}" tween 対象 state "${t.stateId}" 未定義`);
+      }
+      if (typeof t.from === "number" && typeof t.to === "number" && t.from === t.to) {
+        warnings.push(`phase "${p.id}" tween state "${t.stateId}" の from === to (${t.from})、 動きなし`);
+      }
+    }
+    for (const s of p.sets) {
+      if (!stateIds.has(s.stateId)) {
+        errors.push(`[cdl] unknown-ref: phase "${p.id}" set 対象 state "${s.stateId}" 未定義`);
+      }
+    }
+    if (p.duration <= 0) {
+      errors.push(`[cdl] invalid-duration: phase "${p.id}" duration "${p.duration}" は正値必須`);
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 6. state 参照 (node.value / node.rows の {stateId}) → 未定義は warning
+  // ───────────────────────────────────────────────────────────
+  const refRe = /\{(\w+)\}/g;
+  for (const n of diag.nodes) {
+    const checks: string[] = [];
+    if (n.value) checks.push(n.value);
+    if (n.rows) checks.push(...n.rows);
+    for (const text of checks) {
+      let m: RegExpExecArray | null;
+      while ((m = refRe.exec(text))) {
+        const id = m[1];
+        if (id && !stateIds.has(id)) {
+          warnings.push(`node "${n.id}" が未定義 state "${id}" を参照`);
+        }
+      }
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 6.5. unused detection (warn のみ、 build を止めない)
+  // ───────────────────────────────────────────────────────────
+  // どの phase でも activate されない node / edge は warn (catalog で OK だが本番では typo の可能性)
+  const allActivated = new Set<string>();
+  for (const p of diag.phases) {
+    for (const id of p.activate) allActivated.add(id);
+  }
+  for (const n of diag.nodes) {
+    if (!allActivated.has(n.id)) {
+      warnings.push(`node "${n.id}" がどの phase でも activate されていない (unused、 typo の可能性)`);
+    }
+  }
+  for (const e of diag.edges) {
+    if (!allActivated.has(e.id)) {
+      warnings.push(`edge "${e.id}" がどの phase でも activate されていない (unused、 typo の可能性)`);
+    }
+  }
+  // 使われない state も warn (tween / set / node.value / node.rows のいずれにも参照されない)
+  const stateUsed = new Set<string>();
+  for (const p of diag.phases) {
+    for (const t of p.tweens) stateUsed.add(t.stateId);
+    for (const s of p.sets) stateUsed.add(s.stateId);
+  }
+  for (const n of diag.nodes) {
+    const texts = [n.value, ...(n.rows ?? [])].filter(Boolean) as string[];
+    for (const text of texts) {
+      let m: RegExpExecArray | null;
+      const re = /\{(\w+)\}/g;
+      while ((m = re.exec(text))) {
+        if (m[1]) stateUsed.add(m[1]);
+      }
+    }
+  }
+  for (const s of diag.states) {
+    if (!stateUsed.has(s.id)) {
+      warnings.push(`state "${s.id}" がどこでも参照されていない (unused)`);
+    }
+  }
+  // 使われない lane も warn (どの node も配置されない)
+  const laneUsed = new Set<string>();
+  for (const n of diag.nodes) laneUsed.add(n.lane);
+  for (const l of diag.lanes) {
+    if (!laneUsed.has(l.id)) {
+      warnings.push(`lane "${l.id}" にどの node も配置されていない (unused)`);
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 7. japanese-only (uppercase 英単語ラベル禁止) → warning
+  // ───────────────────────────────────────────────────────────
+  const texts: Array<{ where: string; text: string }> = [];
+  for (const l of diag.lanes) if (l.label) texts.push({ where: `lane "${l.id}".label`, text: l.label });
+  for (const n of diag.nodes) {
+    texts.push({ where: `node "${n.id}".title`, text: n.title });
+    if (n.eyebrow) texts.push({ where: `node "${n.id}".eyebrow`, text: n.eyebrow });
+    if (n.subtitle) texts.push({ where: `node "${n.id}".subtitle`, text: n.subtitle });
+  }
+  for (const e of diag.edges) {
+    texts.push({ where: `edge "${e.id}".label`, text: e.label });
+    if (e.sub) texts.push({ where: `edge "${e.id}".sub`, text: e.sub });
+  }
+  for (const { where, text } of texts) {
+    if (ENG_BANNED.test(text)) {
+      warnings.push(`${where} に uppercase 英単語が検出: "${text}"`);
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────
+  // 出力
+  // ───────────────────────────────────────────────────────────
+  if (warnings.length > 0) {
+    for (const w of warnings) console.warn(`[cdl validate] warn: ${w}`);
+  }
+  if (errors.length > 0) {
+    throw new Error(`cdl validate failed:\n  - ${errors.join("\n  - ")}`);
+  }
+}
+
+/**
+ * Levenshtein distance (typo サジェスト用)。
+ * 規模が小さい (各 string 数十文字程度) のため素朴な DP で十分。
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i]![0] = i;
+  for (let j = 0; j <= n; j++) dp[0]![j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(dp[i - 1]![j]! + 1, dp[i]![j - 1]! + 1, dp[i - 1]![j - 1]! + cost);
+    }
+  }
+  return dp[m]![n]!;
+}