@cardenelabs/cdl 0.80.0 → 0.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.80.0",
+  "version": "0.81.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/visual-validate.ts

@@ -4415,18 +4415,27 @@ export interface SweepReport {
   profile: ValidationProfile;
   /** 用途によって見なかった軸。 `totalCounts` はこれらも 0 を返す。 */
   skippedAxes: VisualAxis[];
+  /**
+   * 速さを何で測ったか (`#897`)。
+   *
+   * 超過した時だけ文面に出すと、超過していない周では測り方が分からない。 呼ぶ側が
+   * 「CPU 時間で測れているか」 を常に確かめられるように、超過の有無と切り離して返す。
+   */
+  perfClock: PerfClockKind;
 }
 
 export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions): SweepReport {
   // **図を 1 枚も持たない呼び出しでも器を確かめる**。 各図の `visualValidate` に任せると、
   // 図が 0 枚の掃き出しでは壊れた器が黙って通る (`#797`)。
   器を確かめる(opts?.container);
-  // Axis 52 用 = 各 diagram の validate 実行時間 (ms) を計測。 performance budget 超過検知。
+  // Axis 52 用 = 各 diagram の検査に掛かった時間 (ms) を計測。 performance budget 超過検知。
+  // 測るのは CPU 時間で、待たされた分は足さない (`perfClock` の doc comment が理由の SSOT)。
+  const 時計 = perfClock();
   const durations: number[] = [];
   const reports = diagrams.map((d) => {
-    const start = Date.now();
+    const 止める = 時計.測る();
     const r = visualValidate(d, opts);
-    durations.push(Date.now() - start);
+    durations.push(止める());
     return r;
   });
   const fail = reports.filter((r) => !r.ok).length;
@@ -4438,7 +4447,7 @@ export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions
   }
 
   // Axis 47/48/49/50/52 = engine meta 判定
-  const metaViolations = validateMetaAxes(totalCounts, diagrams, durations, reports);
+  const metaViolations = validateMetaAxes(totalCounts, diagrams, durations, reports, 時計.kind);
 
   return {
     total: reports.length,
@@ -4449,6 +4458,7 @@ export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions
     profile: opts?.profile ?? "production",
     skippedAxes: [...SKIPPED_AXES[opts?.profile ?? "production"]],
     metaViolations,
+    perfClock: 時計.kind,
   };
 }
 
@@ -4468,6 +4478,63 @@ export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions
 /** 全 diagram の検査に掛けてよい合計の時間 (ms)。 */
 export const PERF_BUDGET_TOTAL_MS = 5000;
 
+/** 時間を何で測ったか。 超過の文面に出して、黙って別の物を測らないようにする。 */
+export type PerfClockKind = "cpu" | "wall";
+
+/**
+ * 検査 1 回に掛かった時間を測る道具を作る (`#897`)。
+ *
+ * ## 壁時計は図の性質を測っていない
+ *
+ * 壁時計は **待たされた分も足す**。 使う側の図 599 枚を 3 周する形で測った実測。
+ *
+ * ```
+ * その検査だけを回す (5 回 × 3 周)    335..1739ms
+ * 検査を一式回す     (5 回 × 3 周)    806..2468ms
+ * ```
+ *
+ * 同じ入力で 7.4 倍ぶれる。 境の 5000ms に対して最悪 49% なので今は超えないが、図の枚数は
+ * 軸を作った時の 444 枚から 599 枚に増えており、余裕は枚数の増加だけで減る。
+ * 超えると使う側の「3 周とも同じ件数か」 を見る検査が周ごとに落ち、落ちた人が自分の変更を
+ * 疑うことになる (`cardene777/dragon#2526` 実測 = 無関係だと確かめるのに一式を 3 回)。
+ *
+ * ## CPU 時間なら待っている間は増えない
+ *
+ * `process.cpuUsage()` はこの process が使った CPU 時間をマイクロ秒で返す。 同時に他の検査が
+ * 走っていても、待っている間は増えない。 `Date.now()` の 1ms 刻みでは 1 枚あたりがほとんど
+ * 0ms に丸まるため、超過した時に出す「重い順」 の内訳も読めるようになる。
+ *
+ * ## 読めない環境では壁時計に落ちる
+ *
+ * `visualValidateAll` を呼ぶのは検査だけで Node で動くが、browser に持ち込まれた時は
+ * `process` が無い。 **落ちたことを文面に出す** = 測り方が変わったのに同じ顔で報告すると、
+ * 読み手は 2 つの値を同じものとして並べる (`rules/quality.md § 判定できなかったことを値に
+ * 潰さない` と同じ理由)。
+ */
+export function perfClock(): { kind: PerfClockKind; 測る: () => () => number } {
+  const cpu = (globalThis as { process?: { cpuUsage?: (v?: unknown) => { user: number; system: number } } })
+    .process?.cpuUsage;
+  if (typeof cpu === "function") {
+    return {
+      kind: "cpu",
+      測る: () => {
+        const 始め = cpu();
+        return () => {
+          const 差 = cpu(始め);
+          return (差.user + 差.system) / 1000;
+        };
+      },
+    };
+  }
+  return {
+    kind: "wall",
+    測る: () => {
+      const 始め = Date.now();
+      return () => Date.now() - 始め;
+    },
+  };
+}
+
 /** 合計が境を超えた時に、内訳として名前を出す図の数。 */
 export const PERF_SLOWEST_SAMPLE = 5;
 
@@ -4506,10 +4573,12 @@ export const PERF_SLOWEST_SAMPLE = 5;
  *
  * @param durations 図ごとの実行時間 (ms)。 `diagrams` と同じ並び
  * @param diagrams 図。 名前を内訳に出すためだけに使う
+ * @param clock 何で測ったか。 渡さない時は文面に出さない (合成した値を測り方つきで語らない)
  */
 export function perfBudgetViolations(
   durations: readonly number[],
   diagrams: readonly { id: string }[] = [],
+  clock?: PerfClockKind,
 ): Violation[] {
   const total = durations.reduce((s, d) => s + d, 0);
   if (total <= PERF_BUDGET_TOTAL_MS) return [];
@@ -4529,7 +4598,9 @@ export function perfBudgetViolations(
       diagramId: "__meta__",
       detail:
         `visualValidateAll 全 ${durations.length} 図の累計 ${total}ms > ` +
-        `${PERF_BUDGET_TOTAL_MS}ms budget (重い順 ${内訳})`,
+        `${PERF_BUDGET_TOTAL_MS}ms budget (重い順 ${内訳})` +
+        // 測り方が変わったのに同じ顔で報告すると、読み手が 2 つの値を同じものとして並べる
+        (clock === undefined ? "" : `、 測り方 ${clock === "cpu" ? "CPU 時間" : "壁時計 (CPU 時間が読めない)"}`),
       severity: "warn",
     },
   ];
@@ -4540,6 +4611,7 @@ function validateMetaAxes(
   diagrams: CdlDiagram[] = [],
   durations: number[] = [],
   reports: VisualValidationReport[] = [],
+  clock?: PerfClockKind,
 ): Violation[] {
   const out: Violation[] = [];
 
@@ -4566,7 +4638,7 @@ function validateMetaAxes(
   // 本 axis は 空 (engine 単体で判定材料なし)、 発火経路として先取り。
 
   // ─── Axis 52: validate-performance-budget (validate 実行時間) ───
-  out.push(...perfBudgetViolations(durations, diagrams));
+  out.push(...perfBudgetViolations(durations, diagrams, clock));
 
   // Axis 47: dead axis 検知
   // security / migration 系は自然発火なしを許容 (実データに XSS / migration 混入は稀)