@cardenelabs/dragon 0.28.0 → 0.30.0

package/src/near-name.ts

@@ -0,0 +1,42 @@
+/**
+ * 書き間違えた名前に綴りの近い候補を探す (#1295 で JSON の項目名に作り、#2113 で部品の名前と共有した)。
+ *
+ * 「知らない名前です」 だけだと、書いた人は正しい綴りを探しに行く必要がある。
+ * 2 文字の違い (足りない / 多い / 別の字) までを候補とする。 隣どうしの入れ替わりは 2 文字の違いに数える。
+ *
+ * 遠い名前は勧めない。 無関係な名前を勧めると、書いた人がそちらへ直して二度手間になる。
+ * 大文字と小文字は区別しない。
+ */
+export function 近い名前(語: string, 候補: Iterable<string>): string | undefined {
+  const 小文字 = 語.toLowerCase();
+  let 最短: { 名: string; 距離: number } | undefined;
+  for (const c of 候補) {
+    const d = 編集距離(小文字, c.toLowerCase(), 2);
+    if (d <= 2 && (最短 === undefined || d < 最短.距離)) 最短 = { 名: c, 距離: d };
+  }
+  return 最短?.名;
+}
+
+/**
+ * 2 つの語の編集距離 (上限付き)。
+ *
+ * 上限を持つのは、長い語どうしで表を全部埋めないため。 上限を超えた時点で打ち切る。
+ */
+function 編集距離(a: string, b: string, 上限: number): number {
+  if (Math.abs(a.length - b.length) > 上限) return 上限 + 1;
+  let 前 = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const 今: number[] = [i];
+    let 行の最小 = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const 費用 = a[i - 1] === b[j - 1] ? 0 : 1;
+      const v = Math.min(今[j - 1]! + 1, 前[j]! + 1, 前[j - 1]! + 費用);
+      今.push(v);
+      if (v < 行の最小) 行の最小 = v;
+    }
+    // その行の最小が上限を超えたら、以降どう進んでも上限以下にはならない
+    if (行の最小 > 上限) return 上限 + 1;
+    前 = 今;
+  }
+  return 前[b.length]!;
+}

package/src/relative-pos.ts

@@ -12,8 +12,20 @@
  * 直らない事故を、 規則を共有することで構造的に防ぐ。
  */
 
-/** 基準からどちら側に置くか。 */
-export type RelativeDirection = "right" | "left" | "above" | "below";
+/**
+ * 基準からどちら側に置くか。
+ *
+ * 語の一覧は下の `RELATIVE_DIRECTIONS` が持つ。 型を並べ直さず、一覧から導く。
+ */
+export type RelativeDirection = (typeof RELATIVE_DIRECTIONS)[number];
+
+/**
+ * 向きとして受ける語の一覧。
+ *
+ * 読み取りの入口が 2 つある (本文の `位置: Web の右 200` と JSON の `posRel.dir`) ため、
+ * 一覧を 1 箇所に置いて両方から引く。 2 度書くと、向きを足した時に片方だけが取り残される。
+ */
+export const RELATIVE_DIRECTIONS = ["right", "left", "above", "below"] as const;
 
 /** 相対で書かれた位置の指定。 */
 export type RelativePos = {
@@ -180,3 +192,60 @@ export function orderByDependency(
   }
   return { order, cyclic: [...cyclic] };
 }
+
+/** 解けない書き方の種類。 誤りの文は入口ごとに作るので、ここでは種類だけを返す */
+export type RelativeProblemKind = "self" | "missing-anchor" | "cyclic";
+
+/** 解けない書き方 1 件。 `anchor` は相手が居ない時だけ持つ */
+export type RelativeProblem = {
+  name: string;
+  kind: RelativeProblemKind;
+  anchor?: string;
+};
+
+/**
+ * 解けない相対の指定を挙げる (#2039)。
+ *
+ * 解けない書き方は 3 通りある。 相手が居ない / 自分を基準にした / 基準が輪になっている。
+ * どれも「書いたのに図が変わらない」 形で表に出るため、図を出す前に知らせる。
+ *
+ * **判定は本 file に 1 つだけ置く**。 読み取りの入口が 2 つある (本文と JSON) ため、
+ * 片方だけに判定を持つと、同じ書き方が入口によって通ったり通らなかったりする。
+ * 実際 JSON 側には判定が無く、相対で置く欄そのものが無かった。
+ *
+ * 誤りの文は返さない。 本文側は行番号を、JSON 側は欄の場所を添えるため、文の組み立ては
+ * 入口に任せる。 ここが返すのは「誰の」「どの種類の」 解けなさか だけ。
+ *
+ * 呼ぶ側は、挙がった名前から相対の指定を外す。 残したままだと、誤りを無視して読み込んだ
+ * 経路で解決できない指定が組み立てまで届く。
+ */
+export function findRelativeProblems(
+  items: ReadonlyArray<{ name: string; rel?: RelativePos }>,
+): RelativeProblem[] {
+  const named = new Set(items.map((i) => i.name));
+  const broken = new Set<string>();
+  const out: RelativeProblem[] = [];
+
+  for (const it of items) {
+    const rel = it.rel;
+    if (!rel) continue;
+    if (rel.anchor === it.name) {
+      out.push({ name: it.name, kind: "self" });
+      broken.add(it.name);
+      continue;
+    }
+    if (!named.has(rel.anchor)) {
+      out.push({ name: it.name, kind: "missing-anchor", anchor: rel.anchor });
+      broken.add(it.name);
+    }
+  }
+
+  // 輪は、既に解けないと判った分を外してから探す。 外さないと「相手が居ない」 1 件が
+  // 「輪になっている」 としても挙がり、同じ 1 つの誤りが 2 通りの直し方で出る
+  const { cyclic } = orderByDependency(
+    items.map((i) => ({ name: i.name, rel: broken.has(i.name) ? undefined : i.rel })),
+  );
+  for (const name of cyclic) out.push({ name, kind: "cyclic" });
+
+  return out;
+}

package/src/schema.ts

@@ -13,7 +13,7 @@
  *   });
  *   const diagram = jsonToDiagram(res.content[0].input);
  *
- * schema JSON は `packages/dragon/schemas/diagram.json` が SSOT、 本 file は import して再 export するだけ。
+ * schema JSON は `packages/dragon/src/schemas/diagram.json` が SSOT、 本 file は import して再 export するだけ。
  */
 
 import schemaJson from "./schemas/diagram.json" with { type: "json" };

package/src/schemas/diagram.json

@@ -106,7 +106,7 @@
               },
               "kind": {
                 "type": "string",
-                "description": "node kind。 shape-* を指定して 49 shape 中から選ぶ。 例: 'shape-wallet' / 'shape-smart-contract' / 'shape-cloud' / 'shape-file' / 'actor' (default) / 'function' / 'storage' / 'event' 等"
+                "description": "node kind。 shape-* を指定して 49 shape 中から選ぶ。 例: 'shape-wallet' / 'shape-smart-contract' / 'shape-cloud' / 'shape-file' / 'actor' (default) / 'function' / 'storage' / 'event' 等。 種別に無い名前は部品の名前として部品の一覧 (partsCatalog) から引き、一覧にも無ければ種別を書かなかった箱になる。 部品を持つ一覧を渡した時は知らせを出し、綴りの近い名前を案内する。"
               },
               "subtitle": {
                 "type": "string",
@@ -215,7 +215,7 @@
               },
               "end": {
                 "type": "string",
-                "description": "gantt の工程が終わる時期。"
+                "description": "gantt の工程が終わる時期。 始まりより前の時期は始まりと同じに倒し、知らせを出す。"
               },
               "touchpoint": {
                 "type": "string",
@@ -245,6 +245,10 @@
                 "type": "number",
                 "description": "parts の描画倍率。 kind に parts identifier を指定した時だけ使える。"
               },
+              "phase": {
+                "type": "boolean",
+                "description": "parts が持つ段を使うか。 既定は書いた段と番号ごとに並べて再生する。 false を書くと parts の段の中身を空にし、値は animation に書いた段だけが動かす。 kind に parts identifier を指定した時だけ使える。"
+              },
               "pos": {
                 "type": "object",
                 "additionalProperties": false,
@@ -262,6 +266,36 @@
                   }
                 }
               },
+              "posRel": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "位置を他の要素からの相対で書く指定。 座標を知らなくても「誰の」「どちら側に」「どれだけ離して」 で置ける。 解決した後は posX / posY を書いた時と同じ経路を通る。",
+                "required": [
+                  "anchor",
+                  "dir"
+                ],
+                "properties": {
+                  "anchor": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "基準にする相手の名前。 actors に書かれた名前をそのまま書く。"
+                  },
+                  "dir": {
+                    "type": "string",
+                    "enum": [
+                      "right",
+                      "left",
+                      "above",
+                      "below"
+                    ],
+                    "description": "基準からどちら側に置くか。"
+                  },
+                  "gap": {
+                    "type": "number",
+                    "description": "相手の縁との間隔。 書かなければ 160 で置く。"
+                  }
+                }
+              },
               "visibleIf": {
                 "type": "string",
                 "description": "その箱を出すかどうかの条件。 状態を差し込める文字列で、\"0\" / \"false\" / 空文字が偽、それ以外は真。"
@@ -538,7 +572,7 @@
           },
           "cardinality": {
             "type": "string",
-            "description": "ER の多重度 (1..N 等、 kind: er 用)"
+            "description": "ER の多重度 (type: er 用)。 1:1 / 1:N / N:1 / N:M / 0..1 / 1..* のどれかを書くと、 両端の形がその語から決まり (tailHead / head を書けばそちらが勝つ)、 語は説明文の下の行に出る。 説明文に書いた同じ語は説明文から外す。 6 語以外を書くと説明文に (語) と添えるだけで、 端の形は決まらない (tailHead と head を両方書かなければ、 描かない端を知らせる)。 type: er 以外の図種では描かず、 そのことを知らせる"
           },
           "side": {
             "type": "string",
@@ -2321,7 +2355,7 @@
     },
     "events": {
       "type": "array",
-      "description": "押下などの出来事で動く仕掛け。 相手は名前で指す (box / lane / arrow / diagram のどれか 1 つ)。",
+      "description": "押下などの出来事で動く仕掛け。 相手は名前で指し、指し方の項目をちょうど 1 つだけ書く。",
       "items": {
         "type": "object",
         "required": [

package/src/types.ts

@@ -637,10 +637,10 @@ export type DslValue = {
     }
 );
 
-/** ステップ (phase) */
 /** 動いている間の帯 (#1466)。 順序図で、面がいつ動いているかを段の番号で持つ */
 export type DslBand = { actor: string; from: number; to: number };
 
+/** ステップ (phase) */
 export type DslPhase = {
   name: string;
   durationMs: number;

package/src/v05/parser.ts

@@ -47,7 +47,7 @@ import type { EdgeReveal, RelationFocus } from "@cardenelabs/cdl";
 import { TONE_ALIAS, NODE_KIND_ALIAS, DIRECTIONS, resolveDirection, PALETTES, resolvePalette } from "../keywords";
 import type { DslPalette } from "../keywords";
 import type { DslDirection } from "../keywords";
-import { parseRelativePos, orderByDependency } from "../relative-pos";
+import { parseRelativePos, findRelativeProblems, type RelativeProblem } from "../relative-pos";
 import {
   checkValueExpression,
   isTriggerBody,
@@ -383,14 +383,12 @@ const INFRA_KIND_ALIAS: Record<string, NodeKind> = {
 };
 
 /**
- * 受け付ける箱の種類。 描画できる種類 (cdl の `NODE_KINDS`) に、 記法だけが持つ種類を足す。
+ * 記法が受理する種類の全体。 これに載っていない種類は見本 (パーツ) の候補になる。
  *
- * 以前は手書きの 31 種だった。 描画できる 90 種のうち 78 種が記法から書けず、 部品名として
- * 扱われて「そんな部品は無い」 と警告が出るだけだった。 描画側を出所に加えることで
+ * 描画できる種類 (cdl の `NODE_KINDS`) に、 記法だけが持つ種類と基盤の別名を足す。
+ * 手書きの一覧だった頃は、 描画側に種類が増えても記法から書けず、 部品名として扱われて
+ * 「そんな部品は無い」 と警告が出るだけだった。 描画側を出所に加えることで
  * 「描画できるものは書ける」 が成立する。
- */
-/**
- * 記法が受理する種類の全体。 これに載っていない種類は見本 (パーツ) の候補になる。
  *
  * 画面側が「本文が見本を使っているか」 を判定するのに使う (#1022)。 手書きの一覧を
  * 別に持つと、種類が増えた時にそちらだけ取り残されて余分な読み込みが起きる。
@@ -1553,7 +1551,7 @@ export const AXIS_Y_KEYS = ["bottom", "top"] as const satisfies readonly (keyof
 // `parser.ts` に置いたままだと 生成した表 → parser → 生成した表 の輪ができる
 export type { 欄の形, 図形の定義 } from "./parser-types";
 
-/** 描ける図形と、その欄 (`CdlDynShape` の全 5 種を覆う) */
+/** 描ける図形と、その欄 (`CdlDynShape` の全種を覆う) */
 export const 図形の表: Record<string, 図形の定義> = {
   rect: {
     必須: ["source", "fillMax"],
@@ -1608,9 +1606,9 @@ export const 図形の表: Record<string, 図形の定義> = {
 /**
  * 記法が受ける部品と、その欄。
  *
- * **手で書かず、描画側の型定義から生成する** (#1385)。 描画側は 107 種を持ち欄は 510 個あり、
- * 手で写すと写し間違いと描画側の変更への drift が残る (`rules/quality.md § 導出可能記述は
- * 人手で書かない`)。
+ * **手で書かず、描画側の型定義から生成する** (#1385)。 描画側が持つ種類も、種類ごとの欄も
+ * 多く、手で写すと写し間違いと描画側の変更への drift が残る (`rules/quality.md § 導出可能記述は
+ * 人手で書かない`)。 いくつあるかは `readout-table.generated.ts` を数えれば出る。
  *
  * 作り直す = `node packages/dragon/scripts/gen-readout-table.mjs`
  * ずれの検知 = `packages/dragon/test/readout-table-generated.test.ts`
@@ -1621,8 +1619,9 @@ import { 部品の表, 部品の組の表 } from "./readout-table.generated";
 /**
  * 記法が受けるつまみと、その欄 (#1389)。
  *
- * **部品の表と同じく、描画側の型定義から生成する**。 14 種それぞれ欄が違い、手で写すと
+ * **部品の表と同じく、描画側の型定義から生成する**。 種類ごとに欄が違い、手で写すと
  * 描画側が種類を足した時に drift が残る (`rules/quality.md § 導出可能記述は人手で書かない`)。
+ * いくつあるかは `input-table.generated.ts` を数えれば出る。
  *
  * 作り直す = `node packages/dragon/scripts/gen-input-table.mjs`
  * ずれの検知 = `packages/dragon/test/input-table-generated.test.ts`
@@ -2081,8 +2080,26 @@ export const EVENT_KINDS = [
   "blur",
 ] as const;
 
-/** 出来事の相手を指す書き方。 ちょうど 1 つだけ書く */
-const EVENT_TARGET_KEYS = ["box", "lane", "arrow", "diagram"] as const;
+/**
+ * 出来事の相手を指す書き方。 ちょうど 1 つだけ書く。
+ *
+ * **ここが唯一の置き場所** (#2256)。 同じ 4 語が JSON の記法にも書かれていた間、
+ * 1:1 を名乗りながら受ける項目が両側で別々に決まっており、片方に 5 つ目を足すと
+ * 記法では通るのに JSON では弾かれる状態が黙って生まれる形だった。
+ * 公開 schema の項目の鍵とは `event-target-keys-parity.test.ts` が突き合わせる。
+ */
+export const EVENT_TARGET_KEYS = ["box", "lane", "arrow", "diagram"] as const;
+
+/** 出来事に必ず書く項目。 相手の指し方と合わせて schema の項目の鍵になる */
+export const EVENT_REQUIRED_KEYS = ["on", "handler"] as const;
+
+/**
+ * 出来事が受ける項目の全体 (#2258)。
+ *
+ * **判定と知らせが同じ集合を読む**。 知らせが先頭 2 語だけを手で並べていた間、
+ * 必ず書く項目を増やしても知らせは古い一覧を教え続ける形だった。
+ */
+const EVENT_ITEM_KEYS: readonly string[] = [...EVENT_REQUIRED_KEYS, ...EVENT_TARGET_KEYS];
 
 /**
  * 押下などの出来事で動く仕掛けを 1 件読む (#1393)。
@@ -2109,12 +2126,11 @@ function 出来事として読む(
   }
   const opts = parseInlineMapping(t.slice(1, -1));
   for (const k of Object.keys(opts)) {
-    if (k === "on" || k === "handler" || (EVENT_TARGET_KEYS as readonly string[]).includes(k))
-      continue;
+    if (EVENT_ITEM_KEYS.includes(k)) continue;
     errors.push({
       line,
       message: `出来事の項目名が読めません: "${k}"`,
-      hint: `使える項目 = on, handler, ${EVENT_TARGET_KEYS.join(", ")}`,
+      hint: `使える項目 = ${EVENT_ITEM_KEYS.join(", ")}`,
     });
     return undefined;
   }
@@ -2622,20 +2638,6 @@ function collectIndentedList(
   return { items, next: i };
 }
 
-/**
- * 登場人物を 1 件ずつ集める。 続く字下げ行は同じ 1 件にまとめる。
- *
- * 項目が少なければ 1 行で書け、 多ければ縦に並べられる。 縦に並べた方が、 何を指定できるかが
- * 見える。
- *
- * ```
- * - Client
- * - API: service
- * - Web:
- *     kind: service
- *     色: 失敗
- * ```
- */
 /**
  * 色の指定を振り分ける。
  *
@@ -3091,51 +3093,68 @@ export const ACTOR_ITEM_KEYS: ReadonlySet<string> = new Set([
  */
 function validateRelativePositions(actors: DslActor[], errors: DslError[]): void {
   const named = new Set(actors.map((a) => a.name));
-  const broken = new Set<string>();
+  // 解けない書き方の判定は `relative-pos.ts` が持つ。 JSON の入口も同じ判定を呼ぶ (#2039)
+  const problems = findRelativeProblems(actors.map((a) => ({ name: a.name, rel: a.posRel })));
 
-  for (const a of actors) {
-    const rel = a.posRel;
-    if (!rel) continue;
-    if (rel.anchor === a.name) {
-      errors.push({
-        line: a.pos.line,
-        message: `位置の基準が自分自身です: "${a.name}"`,
-        hint: "別の登場人物の名前を書く",
-      });
-      broken.add(a.name);
-      continue;
-    }
-    if (!named.has(rel.anchor)) {
-      errors.push({
-        line: a.pos.line,
-        message: `位置の基準が見つかりません: "${rel.anchor}"`,
-        hint:
-          named.size > 0
-            ? `actors: に書かれている名前 = ${[...named].join(", ")}`
-            : "actors: に基準にする登場人物を書く",
-      });
-      broken.add(a.name);
-    }
-  }
-
-  const { cyclic } = orderByDependency(
-    actors.map((a) => ({ name: a.name, rel: broken.has(a.name) ? undefined : a.posRel })),
-  );
-  for (const name of cyclic) {
-    const a = actors.find((x) => x.name === name);
+  for (const p of problems) {
+    const a = actors.find((x) => x.name === p.name);
     errors.push({
       line: a?.pos.line ?? 1,
-      message: `位置の基準が互いを指しています: "${name}"`,
-      hint: "どれか 1 つは座標 (`位置: 300,200`) か自動配置にする",
+      ...相対の誤り(p, named),
     });
-    broken.add(name);
   }
 
+  const broken = new Set(problems.map((p) => p.name));
   for (const a of actors) {
     if (broken.has(a.name)) a.posRel = undefined;
   }
 }
 
+/**
+ * 解けない相対の指定に対する、記法側の誤りの文 (#2039)。
+ *
+ * 判定は `relative-pos.ts` が持ち、文はここが持つ。 JSON 側は欄の場所を添えた別の文を作る。
+ */
+function 相対の誤り(
+  p: RelativeProblem,
+  named: ReadonlySet<string>,
+): { message: string; hint: string } {
+  switch (p.kind) {
+    case "self":
+      return {
+        message: `位置の基準が自分自身です: "${p.name}"`,
+        hint: "別の登場人物の名前を書く",
+      };
+    case "missing-anchor":
+      return {
+        message: `位置の基準が見つかりません: "${p.anchor ?? ""}"`,
+        hint:
+          named.size > 0
+            ? `actors: に書かれている名前 = ${[...named].join(", ")}`
+            : "actors: に基準にする登場人物を書く",
+      };
+    case "cyclic":
+      return {
+        message: `位置の基準が互いを指しています: "${p.name}"`,
+        hint: "どれか 1 つは座標 (`位置: 300,200`) か自動配置にする",
+      };
+  }
+}
+
+/**
+ * 登場人物を 1 件ずつ集める。 続く字下げ行は同じ 1 件にまとめる。
+ *
+ * 項目が少なければ 1 行で書け、 多ければ縦に並べられる。 縦に並べた方が、 何を指定できるかが
+ * 見える。
+ *
+ * ```
+ * - Client
+ * - API: service
+ * - Web:
+ *     kind: service
+ *     色: 失敗
+ * ```
+ */
 function collectActorEntries(
   lines: Line[],
   start: number,
@@ -3300,13 +3319,6 @@ function reportScaleOnNonPart(
   });
 }
 
-/**
- * 中括弧の形で読める項目名。
- *
- * ここに無い名前は、 パーツでない箱ではどこにも入らずに消える。 `ACTOR_ITEM_KEYS` (縦に
- * 並べた形) とは別に持つ = 中括弧の形は位置や大きさを未対応にしてあり、 同じ集合にすると
- * 「知らせない」 側がずれる。
- */
 /**
  * 中括弧の形で読める日本語と、その英語名 (#1301)。
  *
@@ -3340,6 +3352,13 @@ function 中括弧の別名を寄せる(opts: Record<string, string>): Record<st
   return 触った ? out : opts;
 }
 
+/**
+ * 中括弧の形で読める項目名。
+ *
+ * ここに無い名前は、 パーツでない箱ではどこにも入らずに消える。 `ACTOR_ITEM_KEYS` (縦に
+ * 並べた形) とは別に持つ = 中括弧の形は位置や大きさ (`pos` / `size` / `scale`) を未対応にしてあり、
+ * 同じ集合にすると「知らせない」 側がずれる。
+ */
 export const INLINE_ACTOR_KEYS: ReadonlySet<string> = new Set([
   "kind",
   "subtitle",