@cardenelabs/cdl 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "CDL (Chainome Diagram Language). Mermaid-like declarative DSL that compiles to animated SVG diagrams. Built for blockchain / Solidity flows, generic enough for sequence / flow / state / ER / topology diagrams.",
   "license": "MIT",
   "author": "cardene777",

package/src/index.ts

@@ -76,6 +76,7 @@ export type {
   SweepReport,
   ValidateOptions,
   ValidationProfile,
+  ReferenceContainer,
 } from "./visual-validate";
 // edge label の文字仕様。 下流が主題で色を上書きする時、 「その文字に何 :1 が要るか」 は
 // 大きさと太さで決まる。 下流が 22 / 19 / 700 を書き写すと、 engine 側を変えた時に下流の

package/src/visual-validate.ts

@@ -412,10 +412,65 @@ const SKIPPED_AXES: Readonly<Record<ValidationProfile, ReadonlySet<VisualAxis>>>
   catalog: new Set<VisualAxis>(["seo-metadata-quality", "structured-data-extraction"]),
 };
 
+/**
+ * 図を描く器 (px)。 軸 23 `responsive-viewport` が画面上の字の大きさを出す時に使う。
+ *
+ * **高さは省ける**。 幅にだけ合わせて縦は巻き取る器があるため = 0 や無限大で表すと
+ * 「上限が無い」 と「潰れている」 が同じ値になる (`rules/quality.md § 判定できなかったことを
+ * 値に潰さない` と同じ形)。
+ */
+export interface ReferenceContainer {
+  /** 器の幅 (px)。 正の有限値。 */
+  readonly width: number;
+  /** 器の高さ (px)。 正の有限値。 **上限が無い器では省く**。 */
+  readonly height?: number;
+}
+
 /** 検査の設定。 */
 export interface ValidateOptions {
   /** 検査の用途。 既定は `production` (全ての軸を見る)。 */
   profile?: ValidationProfile;
+  /**
+   * 軸 23 `responsive-viewport` が基準にする器。
+   *
+   * 既定は下流の見本帳の拡大表示を画面で測った値 (1150 × 630px)。
+   * 実際の器は呼び出し側が決めるものなので、別の見せ方を測る時はここで渡す。
+   */
+  container?: ReferenceContainer;
+}
+
+/** 既定の器。 下流の見本帳の拡大表示を画面で測った値から導く (`#793` / `#797`)。 */
+const 既定の器: Required<Pick<ReferenceContainer, "width">> & { height: number } = {
+  /**
+   * 拡大表示の枠は `min(1200px, 94vw)` で、中身は 1px の縁と 24px の余白の内側に描かれる。
+   * 画面が 1280px 以上なら 1200 が効くので、そこから縁 2 枚と余白 2 枚を引く。
+   */
+  width: 1200 - 1 * 2 - 24 * 2,
+  /** 同じ拡大表示の高さの頭打ち (`90vh − 180px`) を、基準の画面の高さ 900px で評価した値。 */
+  height: 900 * 0.9 - 180,
+};
+
+/**
+ * 渡された器を検査して確定させる。 **入口で 1 度だけ呼ぶ** = 軸 23 の中で投げると
+ * 図ごとに投げることになり、どの呼び出しが誤っていたかが読みにくい。
+ *
+ * 壊れた寸法は既定に落とさず投げる。 落とすと、誤った値を渡した呼び出し側が
+ * 「効いている」 と読める。
+ */
+function 器を確かめる(c: ReferenceContainer | undefined): {
+  幅: number;
+  高さ: number | undefined;
+} {
+  if (c === undefined) return { 幅: 既定の器.width, 高さ: 既定の器.height };
+  if (!(c.width > 0) || !Number.isFinite(c.width)) {
+    throw new Error(`container.width が描画不能 (正の有限値である必要がある): ${c.width}`);
+  }
+  if (c.height !== undefined && (!(c.height > 0) || !Number.isFinite(c.height))) {
+    throw new Error(
+      `container.height が描画不能 (正の有限値で渡すか、上限が無いなら省く): ${c.height}`,
+    );
+  }
+  return { 幅: c.width, 高さ: c.height };
 }
 
 export interface VisualValidationReport {
@@ -1401,7 +1456,16 @@ export function visualValidateLaid(
     counts[axis]++;
   };
 
-  return visualValidateInner(laid, diag, violations, counts, push, profile, [...skipped]);
+  return visualValidateInner(
+    laid,
+    diag,
+    violations,
+    counts,
+    push,
+    profile,
+    [...skipped],
+    器を確かめる(opts?.container),
+  );
 }
 
 /**
@@ -1456,7 +1520,16 @@ export function visualValidate(diag: CdlDiagram, opts?: ValidateOptions): Visual
     console.warn = origWarn;
   }
 
-  return visualValidateInner(laid, safeDiag, violations, counts, push, profile, [...skipped]);
+  return visualValidateInner(
+    laid,
+    safeDiag,
+    violations,
+    counts,
+    push,
+    profile,
+    [...skipped],
+    器を確かめる(opts?.container),
+  );
 }
 
 /**
@@ -1782,6 +1855,8 @@ function visualValidateInner(
   push: (axis: VisualAxis, detail: string, severity?: "error" | "warn") => void,
   profile: ValidationProfile,
   skippedAxes: VisualAxis[],
+  /** 軸 23 が基準にする器。 入口で確かめ済 (`器を確かめる`)。 高さ `undefined` は上限なし。 */
+  器: { 幅: number; 高さ: number | undefined },
 ): VisualValidationReport {
   // 層 1 = 入口の検査 (top-level の配列 13 個と `viewBox`)。 壊れている箇所を報告してから、
   // 検査が反復できる形に差し替える。
@@ -1801,7 +1876,7 @@ function visualValidateInner(
   // 途中までに見つけた違反は `violations` に積まれているので保持される。 例外を投げた軸より
   // 後ろの軸は走らない = 「検査できなかった」 ことを報告に出す。
   try {
-    return runAxes(laid, diag, violations, counts, push, profile, skippedAxes);
+    return runAxes(laid, diag, violations, counts, push, profile, skippedAxes, 器);
   } catch (err) {
     // 入口が既に破綻を見つけていたなら入力側、 何も見つけていなければ検査側の欠陥。
     // 直す先が違うので軸を分ける。 まとめると「入力が悪い」 と誤読して本 file の bug を
@@ -1837,6 +1912,8 @@ function runAxes(
   push: (axis: VisualAxis, detail: string, severity?: "error" | "warn") => void,
   profile: ValidationProfile,
   skippedAxes: VisualAxis[],
+  /** 軸 23 が基準にする器。 入口で確かめ済 (`器を確かめる`)。 高さ `undefined` は上限なし。 */
+  器: { 幅: number; 高さ: number | undefined },
 ): VisualValidationReport {
   // ───────────────────────────────────────────────────────────
   // Axis 1: node-visibility (bbox 面積 / 最小寸法)
@@ -3079,33 +3156,18 @@ function runAxes(
   // ───────────────────────────────────────────────────────────
   //
   /**
-   * 判定に使う器の幅 (px)。 下流の見本帳の拡大表示を画面で測った値から導く。
+   * 判定に使う器 (px)。 **呼び出し側が `ValidateOptions.container` で渡す** (`#797`)。
    *
-   * 拡大表示の枠は `min(1200px, 94vw)` で、 中身は 1px の縁と 24px の余白の内側に描かれる。
-   * 画面が 1280px 以上なら 1200 が効くので、 そこから縁 2 枚と余白 2 枚を引く。
-   * 得られる 1150px は画面での実測と一致する。
-   *
-   * **実際の器は呼び出し側が決める**。 engine はそれを知らないので、 判定の基準として
-   * 1 つ選ぶ。 選んだ値そのものが閾値の意味を決めるため、 定数として出す。
-   */
-  const RESPONSIVE_REF_FRAME_W_PX = 1200;
-  const RESPONSIVE_REF_FRAME_BORDER_PX = 1;
-  const RESPONSIVE_REF_FRAME_PAD_PX = 24;
-  const RESPONSIVE_REF_CONTAINER_W_PX =
-    RESPONSIVE_REF_FRAME_W_PX - RESPONSIVE_REF_FRAME_BORDER_PX * 2 - RESPONSIVE_REF_FRAME_PAD_PX * 2;
-  /**
-   * 判定に使う器の高さ (px)。 同じ拡大表示の高さの頭打ち (`90vh − 180px`) を、
-   * 基準の画面の高さ 900px で評価した値。
+   * 実際の器は見せ方ごとに違う (拡大表示は 1150 × 630px、 一覧に並べた時の枠は
+   * 幅 874px で高さの頭打ちが無い)。 engine はどちらで見られるかを知らないので、
+   * 渡されなければ拡大表示の値を既定にする (`既定の器`)。
    *
-   * **高さを見ないと判定にならない** (`#793`)。 図は `preserveAspectRatio="xMidYMid meet"` で
-   * 器に収まるよう中で縮むため、 横が余っていても縦が足りなければ縦が倍率を決める。
-   * 画面での実測 28 回のうち 27 回は縦が効いていた。
+   * **高さは省ける**。 図は `preserveAspectRatio="xMidYMid meet"` で器に収まるよう中で縮むため、
+   * 高さの上限がある器では縦が倍率を決めうる (画面での実測 28 回のうち 27 回は縦が効いていた、
+   * `#793`)。 縦に巻き取る器ではその制約が無いので、 高さを見ない。
    */
-  const RESPONSIVE_REF_VIEWPORT_H_PX = 900;
-  const RESPONSIVE_REF_FRAME_H_RATIO = 0.9;
-  const RESPONSIVE_REF_CHROME_H_PX = 180;
-  const RESPONSIVE_REF_CONTAINER_H_PX =
-    RESPONSIVE_REF_VIEWPORT_H_PX * RESPONSIVE_REF_FRAME_H_RATIO - RESPONSIVE_REF_CHROME_H_PX;
+  const RESPONSIVE_REF_CONTAINER_W_PX = 器.幅;
+  const RESPONSIVE_REF_CONTAINER_H_PX = 器.高さ;
   /**
    * 画面上で読めると見なす文字の下限 (px)。
    *
@@ -3136,7 +3198,12 @@ function runAxes(
   } else {
     // 器に収めた時に効く倍率。 `xMidYMid meet` は縦横の小さい方に合わせる。
     const 横の倍率 = RESPONSIVE_REF_CONTAINER_W_PX / vbResp.w;
-    const 縦の倍率 = RESPONSIVE_REF_CONTAINER_H_PX / vbResp.h;
+    // **高さの上限が無い器では縦を見ない**。 0 や巨大な数で表すと「上限なし」 と
+    // 「潰れている」 が同じ値になるため、 `undefined` のまま `Infinity` に落とす。
+    const 縦の倍率 =
+      RESPONSIVE_REF_CONTAINER_H_PX === undefined
+        ? Number.POSITIVE_INFINITY
+        : RESPONSIVE_REF_CONTAINER_H_PX / vbResp.h;
     const 倍率 = Math.min(横の倍率, 縦の倍率);
     const 画面上の字 = RESPONSIVE_BASE_FONT_WORLD * 倍率;
     if (画面上の字 < RESPONSIVE_MIN_ON_SCREEN_FONT_PX) {
@@ -3144,12 +3211,16 @@ function runAxes(
       // (実測 = 1255×1700 の図は幅を半分にしても縦が効いたまま)。
       const 効く辺 = 横の倍率 <= 縦の倍率 ? "横" : "縦";
       const 収まる寸法 =
-        効く辺 === "横"
+        効く辺 === "横" || RESPONSIVE_REF_CONTAINER_H_PX === undefined
           ? `幅 ${((RESPONSIVE_REF_CONTAINER_W_PX * RESPONSIVE_BASE_FONT_WORLD) / RESPONSIVE_MIN_ON_SCREEN_FONT_PX).toFixed(0)} 以下`
           : `高さ ${((RESPONSIVE_REF_CONTAINER_H_PX * RESPONSIVE_BASE_FONT_WORLD) / RESPONSIVE_MIN_ON_SCREEN_FONT_PX).toFixed(0)} 以下`;
+      const 器の書き方 =
+        RESPONSIVE_REF_CONTAINER_H_PX === undefined
+          ? `器 幅 ${RESPONSIVE_REF_CONTAINER_W_PX}px (高さの上限なし)`
+          : `器 ${RESPONSIVE_REF_CONTAINER_W_PX}×${RESPONSIVE_REF_CONTAINER_H_PX}px`;
       push(
         "responsive-viewport",
-        `viewBox ${vbResp.w}×${vbResp.h} は器 ${RESPONSIVE_REF_CONTAINER_W_PX}×${RESPONSIVE_REF_CONTAINER_H_PX}px で ` +
+        `viewBox ${vbResp.w}×${vbResp.h} は${器の書き方} で ` +
           `${倍率.toFixed(3)} 倍に縮み、 箱の題が ${画面上の字.toFixed(1)}px になる ` +
           `(下限 ${RESPONSIVE_MIN_ON_SCREEN_FONT_PX}px、 倍率を決めたのは ${効く辺}、 ${収まる寸法}にすると届く)`,
         "warn",
@@ -4305,6 +4376,9 @@ export interface SweepReport {
 }
 
 export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions): SweepReport {
+  // **図を 1 枚も持たない呼び出しでも器を確かめる**。 各図の `visualValidate` に任せると、
+  // 図が 0 枚の掃き出しでは壊れた器が黙って通る (`#797`)。
+  器を確かめる(opts?.container);
   // Axis 52 用 = 各 diagram の validate 実行時間 (ms) を計測。 performance budget 超過検知。
   const durations: number[] = [];
   const reports = diagrams.map((d) => {