@cardenelabs/cdl 0.5.0

package/src/compile.ts

@@ -0,0 +1,12 @@
+import { layout } from "./layout";
+import { validate } from "./validate";
+import type { CdlDiagram, LaidDiagram } from "./types";
+
+/**
+ * compile = validate → layout で LaidDiagram を返す。
+ * render は別 file (render.tsx) が LaidDiagram を消費。
+ */
+export function compile(diag: CdlDiagram): LaidDiagram {
+  validate(diag);
+  return layout(diag);
+}

package/src/dom-verify-core.ts

@@ -0,0 +1,121 @@
+/**
+ * dom-verify core (library 化前段 = adapter pattern の足場)。
+ *
+ * cdl-specific 型 (CdlDiagram / LaidDiagram) に依存しない、 任意の SVG diagram tool に
+ * attach 可能な generic 検証 core。 将来 @cardenelabs/diagram-verifier として独立化する際の
+ * 「枝葉に依存しない API 設計」 を確立する。
+ *
+ * 利用側 (cdl adapter / Mermaid adapter / D2 adapter 等) は GenericDiagramSpec を満たす
+ * object を構築し、 verifyGenericDom(page, spec) で検証を回す。
+ *
+ * 既存 dom-verify.ts は本 file の上に cdl adapter として乗る (cdl の CdlDiagram → GenericDiagramSpec に変換)。
+ */
+
+import type { PageLike } from "./dom-verify-types";
+
+/**
+ * 任意 diagram tool が「目」 で検証されるために提供すべき構造的 spec。
+ * cdl-specific な型を排し、 generic な primitive (id / cx / cy / w / h / path d / activate set 等) のみ。
+ */
+export interface GenericDiagramSpec {
+  /** diagram の一意 id ([data-cdl-diagram="..."] でも別 attr でも良い、 adapter で selector を構築) */
+  id: string;
+  /** root selector の DOM attribute (default "data-cdl-diagram") */
+  rootAttribute?: string;
+  /** node selector の DOM attribute (default "data-cdl-node") */
+  nodeAttribute?: string;
+  /** edge selector の DOM attribute (default "data-cdl-edge") */
+  edgeAttribute?: string;
+  /** particle selector の DOM attribute (default "data-cdl-particle") */
+  particleAttribute?: string;
+  /** node 一覧 (id / cx / cy / w / h) */
+  nodes: Array<{
+    id: string;
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+  }>;
+  /** edge 一覧 (id / from / to / d / labelX / labelY / style) */
+  edges: Array<{
+    id: string;
+    from: string;
+    to: string;
+    d: string;
+    labelX: number;
+    labelY: number;
+    /** "dotted-flow" 相当のスタイル (particle 検証対象判定用) */
+    hasParticle: boolean;
+  }>;
+  /** phase 一覧 (id / activate set) */
+  phases: Array<{
+    id: string;
+    activate: string[];
+  }>;
+}
+
+/**
+ * 検証種別。
+ */
+export type GenericDiscrepancyKind =
+  | "missing-node-element"
+  | "missing-edge-element"
+  | "node-position-mismatch"
+  | "node-size-mismatch"
+  | "edge-path-endpoint-mismatch"
+  | "edge-label-position-mismatch"
+  | "particle-out-of-path"
+  | "activation-mismatch"
+  | "phase-transition-failure";
+
+export interface GenericDiscrepancy {
+  kind: GenericDiscrepancyKind;
+  diagramId: string;
+  elementId: string;
+  expected: unknown;
+  actual: unknown;
+  detail: string;
+}
+
+export interface GenericVerifyOptions {
+  positionTolerance?: number;
+  edgeEndpointTolerance?: number;
+  particleTolerance?: number;
+  particleFrameCount?: number;
+  particleConsecutiveFailThreshold?: number;
+  bboxTolerance?: number;
+  skipBbox?: boolean;
+  skipParticle?: boolean;
+  skipPhase?: boolean;
+}
+
+/**
+ * 任意 diagram の核心検証 5 種類。
+ *
+ * 本関数自体は cdl 依存ゼロ。 adapter (cdl-adapter / mermaid-adapter 等) が
+ * GenericDiagramSpec を構築して渡す。
+ */
+export async function verifyGenericDom(
+  _page: PageLike,
+  _spec: GenericDiagramSpec,
+  _options: GenericVerifyOptions = {},
+): Promise<GenericDiscrepancy[]> {
+  // implementation 詳細は dom-verify.ts の関数群を移植する形で次フェーズ実装。
+  // 本 PR では adapter pattern の枠組みのみ確立し、 cdl-specific dom-verify.ts は維持する。
+  // 将来 publish 時に dom-verify.ts は cdl-adapter として generic core を呼ぶ薄い wrapper になる。
+  throw new Error("verifyGenericDom: not yet implemented. Use cdl-specific verifyDiagramDom for now.");
+}
+
+/**
+ * 任意 diagram tool の adapter が満たすべき contract。
+ *
+ * cdl の場合 ... CdlDiagram → GenericDiagramSpec を返す純関数。
+ * Mermaid の場合 ... mermaid.parse() で AST 取得 → GenericDiagramSpec に変換。
+ * D2 の場合 ... d2 CLI で JSON dump → GenericDiagramSpec に変換。
+ */
+export interface DiagramAdapter<DiagramType> {
+  /** diagram type 名 (例 "cdl" / "mermaid" / "d2") */
+  readonly name: string;
+  /** diagram 型から GenericDiagramSpec への変換 */
+  toSpec(diagram: DiagramType): GenericDiagramSpec;
+}

package/src/dom-verify-types.ts

@@ -0,0 +1,21 @@
+/**
+ * dom-verify-core / dom-verify (cdl adapter) 両方で共有する types。
+ *
+ * PageLike を独立 file に切り出すことで、 core / adapter の循環 import を避ける。
+ */
+
+/**
+ * Playwright Page-like 抽象。 packages/cdl は Playwright を直接 import せず、
+ * 利用側で Page を渡す。 これで cdl が browser dependency 持たない。
+ */
+export interface PageLike {
+  /** querySelector の thin wrapper */
+  $$eval<T>(selector: string, fn: (els: Element[]) => T): Promise<T>;
+  $eval<T>(selector: string, fn: (el: Element) => T): Promise<T>;
+  /** 任意 JS を browser context で evaluate */
+  evaluate<T, A>(fn: (arg: A) => T, arg: A): Promise<T>;
+  /** sleep (ms) */
+  waitForTimeout(ms: number): Promise<void>;
+  /** click selector */
+  click(selector: string): Promise<void>;
+}