@reftrixmcp/mcp-server 0.1.7

package/src/services/responsive/types.ts

@@ -0,0 +1,387 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Responsive Analysis Types
+ * レスポンシブ解析関連の型定義
+ *
+ * @module services/responsive/types
+ */
+
+/**
+ * 名前付きビューポート設定
+ */
+export interface ResponsiveViewport {
+  name: string;
+  width: number;
+  height: number;
+}
+
+/**
+ * ナビゲーションタイプ
+ */
+export type NavigationType =
+  | "horizontal-menu"
+  | "hamburger-menu"
+  | "drawer"
+  | "bottom-nav"
+  | "tab-bar"
+  | "hidden"
+  | "other";
+
+/**
+ * 差異カテゴリ
+ */
+export type DifferenceCategory =
+  | "visibility"
+  | "layout"
+  | "navigation"
+  | "typography"
+  | "spacing"
+  | "order"
+  | "other";
+
+/**
+ * 要素の可視性情報
+ */
+export interface ElementVisibility {
+  visible: boolean;
+  type?: NavigationType;
+  displayMode?: string;
+  reason?: string;
+}
+
+/**
+ * セマンティック要素のcomputedStyle情報（Phase 2: computedStyleベース検出）
+ */
+export interface SemanticElementInfo {
+  /** 要素のCSSセレクタ（例: "header", "aside#sidebar"） */
+  selector: string;
+  /** タグ名 */
+  tagName: string;
+  /** display値 */
+  display: string;
+  /** visibility値 */
+  visibility: string;
+  /** opacity値 */
+  opacity: number;
+  /** グリッドカラム数（display: grid/inline-gridの場合） */
+  gridColumns?: number;
+  /** フレックス方向（display: flex/inline-flexの場合） */
+  flexDirection?: string;
+  /** BoundingRect */
+  boundingRect?: { x: number; y: number; width: number; height: number };
+}
+
+/**
+ * ブレークポイント解像度モード
+ */
+export type BreakpointResolution = "range" | "precise";
+
+/**
+ * レスポンシブ差異アイテム
+ */
+export interface ResponsiveDifference {
+  element: string;
+  description?: string;
+  category: DifferenceCategory;
+  desktop?: Record<string, unknown>;
+  tablet?: Record<string, unknown>;
+  mobile?: Record<string, unknown>;
+}
+
+/**
+ * ビューポート別スクリーンショット
+ */
+export interface ViewportScreenshot {
+  name: string;
+  width: number;
+  height: number;
+  screenshot?: {
+    base64: string;
+    format: "png" | "jpeg";
+    width: number;
+    height: number;
+  };
+}
+
+/**
+ * ビューポートキャプチャ結果
+ */
+export interface ViewportCaptureResult {
+  viewport: ResponsiveViewport;
+  html: string;
+  screenshot?: ViewportScreenshot;
+  layoutInfo: ViewportLayoutInfo;
+  navigationInfo: NavigationInfo;
+  error?: string;
+}
+
+/**
+ * ビューポートごとのレイアウト情報
+ */
+export interface ViewportLayoutInfo {
+  /** ドキュメント幅 */
+  documentWidth: number;
+  /** ドキュメント高さ */
+  documentHeight: number;
+  /** ビューポート幅 */
+  viewportWidth: number;
+  /** ビューポート高さ */
+  viewportHeight: number;
+  /** スクロール高さ */
+  scrollHeight: number;
+  /** 検出されたブレークポイント（CSSから抽出） */
+  breakpoints: string[];
+  /** グリッドカラム数 */
+  gridColumns?: number;
+  /** フレックス方向 */
+  flexDirection?: string;
+  /** タイポグラフィ情報 */
+  typography?: {
+    h1FontSize: number;
+    bodyFontSize: number;
+    bodyLineHeight: number;
+  };
+  /** スペーシング情報 */
+  spacing?: {
+    bodyPadding: { top: number; right: number; bottom: number; left: number };
+    mainContainerPadding?: { top: number; right: number; bottom: number; left: number };
+  };
+  /** セマンティック要素のcomputedStyle情報（Phase 2） */
+  semanticElements?: SemanticElementInfo[];
+  /** 拡張タイポグラフィ情報（h1-h6, p:first-of-type）（Phase 4） */
+  extendedTypography?: {
+    headings: Array<{ tag: string; fontSize: number }>;
+    pFirstOfType?: number;
+  };
+  /** セクション間スペーシング（Phase 4） */
+  sectionSpacing?: Array<{ selector: string; marginTop: number; marginBottom: number }>;
+}
+
+/**
+ * ナビゲーション情報
+ */
+export interface NavigationInfo {
+  /** ナビゲーションタイプ */
+  type: NavigationType;
+  /** ハンバーガーメニューが存在するか */
+  hasHamburgerMenu: boolean;
+  /** 水平メニューが存在するか */
+  hasHorizontalMenu: boolean;
+  /** ボトムナビゲーションが存在するか */
+  hasBottomNav: boolean;
+  /** ナビゲーション要素のセレクタ */
+  selector?: string;
+}
+
+/**
+ * レスポンシブ解析結果
+ */
+export interface ResponsiveAnalysisResult {
+  viewportsAnalyzed: ResponsiveViewport[];
+  differences: ResponsiveDifference[];
+  breakpoints: string[];
+  screenshots?: ViewportScreenshot[];
+  /** ビューポート間の視覚的差分（スクリーンショット有効時のみ） */
+  viewportDiffs?: ViewportDiffResult[];
+  analysisTimeMs: number;
+}
+
+/**
+ * レスポンシブ解析オプション
+ */
+export interface ResponsiveAnalysisOptions {
+  enabled: boolean;
+  viewports?: ResponsiveViewport[];
+  include_screenshots?: boolean;
+  /** ビューポート差分画像を結果に含めるか */
+  include_diff_images?: boolean;
+  /** ビューポート差分の閾値（0-1、デフォルト0.1） */
+  diff_threshold?: number;
+  detect_navigation?: boolean;
+  detect_visibility?: boolean;
+  detect_layout?: boolean;
+  /** ブレークポイント解像度（'range': CSSメディアクエリ + VP差分推定, 'precise': 二分探索で±8px特定） */
+  breakpoint_resolution?: BreakpointResolution;
+  /** robots.txt の crawl-delay（ミリ秒）。指定時はビューポートキャプチャ間に遅延を挿入 */
+  crawlDelayMs?: number;
+}
+
+/**
+ * マルチビューポートキャプチャオプション
+ */
+export interface MultiViewportCaptureOptions {
+  /** キャプチャ対象のビューポート配列 */
+  viewports: ResponsiveViewport[];
+  /** スクリーンショットを含めるか */
+  includeScreenshots: boolean;
+  /** タイムアウト（ms） */
+  timeout: number;
+  /** フルページスクリーンショット */
+  fullPage?: boolean;
+  /** ページ読み込み完了判定 */
+  waitUntil?: "load" | "domcontentloaded" | "networkidle";
+  /** DOM安定化待機 */
+  waitForDomStable?: boolean;
+  /** DOM安定化タイムアウト */
+  domStableTimeout?: number;
+  /** robots.txt の crawl-delay（ミリ秒）。2回目以降のキャプチャ前に遅延を挿入 */
+  crawlDelayMs?: number;
+}
+
+/**
+ * ナビゲーション検出オプション
+ */
+export interface NavigationDetectionOptions {
+  /** ナビゲーション要素のセレクタ候補 */
+  navSelectors?: string[];
+  /** ハンバーガーメニューのセレクタ候補 */
+  hamburgerSelectors?: string[];
+}
+
+/**
+ * 可視性検出オプション
+ */
+export interface VisibilityDetectionOptions {
+  /** 監視対象の要素セレクタ */
+  targetSelectors?: string[];
+  /** 特定の要素クラスを除外 */
+  excludeClasses?: string[];
+}
+
+/**
+ * レイアウト検出オプション
+ */
+export interface LayoutDetectionOptions {
+  /** グリッドコンテナのセレクタ候補 */
+  gridSelectors?: string[];
+  /** フレックスコンテナのセレクタ候補 */
+  flexSelectors?: string[];
+}
+
+/**
+ * タッチターゲット違反要素
+ */
+export interface TouchTargetFailedElement {
+  /** 要素のCSSセレクタ */
+  selector: string;
+  /** 要素の幅 (px) */
+  width: number;
+  /** 要素の高さ (px) */
+  height: number;
+}
+
+/**
+ * タッチターゲット検出結果
+ */
+export interface TouchTargetResult {
+  /** 基準を満たした要素数 */
+  passed: number;
+  /** 基準を満たさなかった要素数 */
+  failed: number;
+  /** 基準を満たさなかった要素の詳細 */
+  failedElements: TouchTargetFailedElement[];
+}
+
+/**
+ * モバイル読みやすさ評価結果
+ */
+export interface ReadabilityResult {
+  /** フォントサイズが基準以上か (>= 16px) */
+  fontSizeOk: boolean;
+  /** 行長が基準以下か (<= 80文字) */
+  lineLengthOk: boolean;
+  /** 行高さが基準以上か (>= 1.5) */
+  lineHeightOk: boolean;
+  /** 計測値の詳細 */
+  details: {
+    minFontSize: number;
+    avgLineLength: number;
+    avgLineHeight: number;
+    sampleCount: number;
+  };
+}
+
+/**
+ * コンテンツオーバーフロー検出結果
+ */
+export interface OverflowResult {
+  /** 水平スクロールが発生しているか */
+  horizontalScroll: boolean;
+  /** オーバーフローしている要素のセレクタ */
+  overflowElements: string[];
+}
+
+/**
+ * レスポンシブ画像チェック結果
+ */
+export interface ResponsiveImageResult {
+  /** srcset属性を持つ画像数 */
+  srcsetCount: number;
+  /** picture要素数 */
+  pictureCount: number;
+  /** レスポンシブ対応していない画像数 */
+  missingResponsive: number;
+}
+
+/**
+ * ビューポートごとの品質評価結果
+ */
+export interface ViewportQualityResult {
+  viewport: ResponsiveViewport;
+  touchTargets: TouchTargetResult;
+  readability: ReadabilityResult;
+  overflow: OverflowResult;
+  images: ResponsiveImageResult;
+}
+
+/**
+ * レスポンシブ品質評価結果
+ */
+export interface ResponsiveQualityResult {
+  viewportResults: ViewportQualityResult[];
+  /** 総合スコア (0-100) */
+  overallScore: number;
+  /** 評価時間 (ms) */
+  evaluationTimeMs: number;
+}
+
+/**
+ * レスポンシブ品質評価オプション
+ */
+export interface ResponsiveQualityEvaluationOptions {
+  /** 評価対象のビューポート */
+  viewports?: ResponsiveViewport[];
+  /** 実行するチェック項目の選択 */
+  checks?: {
+    touchTargets?: boolean;
+    readability?: boolean;
+    overflow?: boolean;
+    images?: boolean;
+  };
+  /** タイムアウト (ms) */
+  timeout?: number;
+}
+
+/**
+ * ビューポート間の視覚的差分結果
+ */
+export interface ViewportDiffResult {
+  /** 比較元ビューポート名 */
+  viewport1: string;
+  /** 比較先ビューポート名 */
+  viewport2: string;
+  /** 差分率 (0-100) */
+  diffPercentage: number;
+  /** 差分ピクセル数 */
+  diffPixelCount: number;
+  /** 総ピクセル数 */
+  totalPixels: number;
+  /** 比較時の幅 */
+  comparedWidth: number;
+  /** 比較時の高さ */
+  comparedHeight: number;
+  /** 差分画像バッファ（include_diff_images: true の場合のみ） */
+  diffImageBuffer?: Buffer;
+}

package/src/services/responsive/viewport-diff.service.ts

@@ -0,0 +1,236 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Viewport Diff Service
+ * 異なるビューポートのスクリーンショットを比較し、視覚的差分を検出するサービス
+ *
+ * @module services/responsive/viewport-diff.service
+ */
+
+import pixelmatch from "pixelmatch";
+import sharp from "sharp";
+import { logger, isDevelopment } from "../../utils/logger";
+import type { ViewportDiffResult } from "./types";
+
+/**
+ * ViewportDiff オプション
+ */
+export interface ViewportDiffOptions {
+  /** Pixelmatch の差分閾値 (0-1, デフォルト: 0.1) */
+  threshold?: number;
+  /** 差分画像を結果に含めるか */
+  includeDiffImage?: boolean;
+}
+
+/**
+ * 画像のRGBAデータ
+ */
+interface ImageData {
+  data: Buffer;
+  width: number;
+  height: number;
+}
+
+/**
+ * Viewport Diff Service
+ * 異なるビューポートのスクリーンショットを比較するサービス
+ */
+export class ViewportDiffService {
+  /**
+   * 2つのスクリーンショットバッファを比較
+   *
+   * @param screenshot1 - 比較元スクリーンショット（PNGバッファ）
+   * @param screenshot2 - 比較先スクリーンショット（PNGバッファ）
+   * @param viewport1Name - 比較元ビューポート名
+   * @param viewport2Name - 比較先ビューポート名
+   * @param options - 差分検出オプション
+   * @returns 差分結果
+   */
+  async comparePair(
+    screenshot1: Buffer,
+    screenshot2: Buffer,
+    viewport1Name: string,
+    viewport2Name: string,
+    options?: ViewportDiffOptions
+  ): Promise<ViewportDiffResult> {
+    const threshold = options?.threshold ?? 0.1;
+    const includeDiffImage = options?.includeDiffImage ?? false;
+
+    if (isDevelopment()) {
+      logger.debug("[ViewportDiff] Comparing pair", {
+        viewport1: viewport1Name,
+        viewport2: viewport2Name,
+        threshold,
+      });
+    }
+
+    // 画像データをRGBA形式で取得
+    const [img1, img2] = await Promise.all([
+      this.getImageData(screenshot1),
+      this.getImageData(screenshot2),
+    ]);
+
+    // 小さい方の解像度に合わせてリサイズ（アスペクト比維持）
+    const targetWidth = Math.min(img1.width, img2.width);
+    const targetHeight = Math.min(img1.height, img2.height);
+
+    const [resized1, resized2] = await Promise.all([
+      this.resizeToMatch(screenshot1, targetWidth, targetHeight),
+      this.resizeToMatch(screenshot2, targetWidth, targetHeight),
+    ]);
+
+    const totalPixels = resized1.width * resized1.height;
+
+    // 差分画像バッファを準備
+    const diffBuffer = Buffer.alloc(resized1.width * resized1.height * 4);
+
+    // Pixelmatchで差分検出
+    const diffPixelCount = pixelmatch(
+      resized1.data,
+      resized2.data,
+      diffBuffer,
+      resized1.width,
+      resized1.height,
+      { threshold }
+    );
+
+    const diffPercentage = totalPixels > 0 ? (diffPixelCount / totalPixels) * 100 : 0;
+
+    if (isDevelopment()) {
+      logger.debug("[ViewportDiff] Comparison completed", {
+        viewport1: viewport1Name,
+        viewport2: viewport2Name,
+        diffPercentage: diffPercentage.toFixed(2),
+        diffPixelCount,
+        totalPixels,
+      });
+    }
+
+    // exactOptionalPropertyTypes対応: 条件付きで返す
+    if (includeDiffImage) {
+      const diffImageBuffer = await this.bufferToPng(diffBuffer, resized1.width, resized1.height);
+      return {
+        viewport1: viewport1Name,
+        viewport2: viewport2Name,
+        diffPercentage,
+        diffPixelCount,
+        totalPixels,
+        comparedWidth: resized1.width,
+        comparedHeight: resized1.height,
+        diffImageBuffer,
+      };
+    }
+
+    return {
+      viewport1: viewport1Name,
+      viewport2: viewport2Name,
+      diffPercentage,
+      diffPixelCount,
+      totalPixels,
+      comparedWidth: resized1.width,
+      comparedHeight: resized1.height,
+    };
+  }
+
+  /**
+   * 複数のスクリーンショットを全ペアで比較
+   *
+   * @param screenshots - ビューポート名 → スクリーンショットバッファのマップ
+   * @param options - 差分検出オプション
+   * @returns 全ペアの差分結果配列
+   */
+  async compareAll(
+    screenshots: Map<string, Buffer>,
+    options?: ViewportDiffOptions
+  ): Promise<ViewportDiffResult[]> {
+    const entries = Array.from(screenshots.entries());
+    const results: ViewportDiffResult[] = [];
+
+    if (entries.length < 2) {
+      if (isDevelopment()) {
+        logger.debug("[ViewportDiff] Not enough screenshots for comparison", {
+          count: entries.length,
+        });
+      }
+      return results;
+    }
+
+    // 全ペアを比較
+    for (let i = 0; i < entries.length; i++) {
+      for (let j = i + 1; j < entries.length; j++) {
+        const [name1, buffer1] = entries[i]!;
+        const [name2, buffer2] = entries[j]!;
+        const result = await this.comparePair(buffer1, buffer2, name1, name2, options);
+        results.push(result);
+      }
+    }
+
+    if (isDevelopment()) {
+      logger.info("[ViewportDiff] All comparisons completed", {
+        pairCount: results.length,
+        avgDiffPercentage:
+          results.length > 0
+            ? (results.reduce((sum, r) => sum + r.diffPercentage, 0) / results.length).toFixed(2)
+            : "0",
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * 画像データをRGBA形式で取得
+   */
+  private async getImageData(buffer: Buffer): Promise<ImageData> {
+    const result = await sharp(buffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    return {
+      data: result.data,
+      width: result.info.width,
+      height: result.info.height,
+    };
+  }
+
+  /**
+   * 指定サイズにリサイズしてRGBAデータを返す（アスペクト比維持、パディングなし）
+   */
+  private async resizeToMatch(
+    buffer: Buffer,
+    targetWidth: number,
+    targetHeight: number
+  ): Promise<ImageData> {
+    const result = await sharp(buffer)
+      .resize(targetWidth, targetHeight, {
+        fit: "cover",
+        position: "top",
+      })
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+
+    return {
+      data: result.data,
+      width: result.info.width,
+      height: result.info.height,
+    };
+  }
+
+  /**
+   * RGBAバッファをPNG画像に変換
+   */
+  private async bufferToPng(buffer: Buffer, width: number, height: number): Promise<Buffer> {
+    return sharp(buffer, {
+      raw: {
+        width,
+        height,
+        channels: 4,
+      },
+    })
+      .png()
+      .toBuffer();
+  }
+}
+
+// シングルトンインスタンス
+export const viewportDiffService = new ViewportDiffService();