vibepro 0.1.0-alpha.0

package/src/gesture-interaction-scanner.js

@@ -0,0 +1,330 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const IGNORED_DIRS = new Set([
+  '.git',
+  '.next',
+  '.turbo',
+  '.vibepro',
+  'coverage',
+  'dist',
+  'node_modules',
+  'graphify-out'
+]);
+const TEXT_EXTENSIONS = new Set(['.css', '.htm', '.html', '.js', '.jsx', '.mjs', '.ts', '.tsx']);
+const UI_ROOT_PATTERN = /^(app|components|pages|public|src|styles)\//;
+const GESTURE_SURFACE_PATTERN = /\b(carousel|slider|swiper|snap|scroll-x|horizontal|map|mapbox|google-map|leaflet|drag|draggable|swipe|touch)\b/i;
+const MAP_SURFACE_PATTERN = /\b(map|mapbox|google-map|leaflet|marker|pin|overlay)\b/i;
+const CAROUSEL_SURFACE_PATTERN = /\b(carousel|slider|swiper|slide|snap|scroll-x|horizontal)\b/i;
+const TOUCH_TARGET_PATTERN = /\b(card|marker|pin|carousel|slide|item|thumb|button|btn)\b/i;
+const TOUCH_ACTION_PATTERN = /touch-action\s*:\s*([^;]+)/i;
+const POSITIONED_OVERLAY_PATTERN = /position\s*:\s*(absolute|fixed|sticky)\b/i;
+const POINTER_EVENTS_NONE_PATTERN = /pointer-events\s*:\s*none\b/i;
+const OVERFLOW_X_PATTERN = /overflow-x\s*:\s*(auto|scroll)\b/i;
+const SCROLL_SNAP_PATTERN = /scroll-snap-type\s*:/i;
+const MARKER_CODE_PATTERN = /\b(AdvancedMarkerElement|google\.maps\.Marker|MarkerF|MapMarker|<Marker\b|<AdvancedMarker\b|mapbox|leaflet|L\.marker)\b/;
+const DRAG_HANDLER_PATTERN = /\b(onPointerDown|onPointerMove|onPointerUp|onTouchStart|onTouchMove|onTouchEnd|onMouseDown|onMouseMove|onMouseUp|onDragStart|draggable)\b/;
+const CLICK_NAV_PATTERN = /\b(onClick|router\.push|navigate\s*\(|window\.location|href=)\b/;
+const DRAG_STATE_PATTERN = /\b(isDragging|dragging|dragStart|touchStart|pointerStart|swipeStart|isSwiping|hasDragged|dragDistance|touchMoved)\b/g;
+const CLICK_SUPPRESSION_PATTERN = /\b(preventClick|ignoreClick|suppressClick|cancelClick|hasDragged|touchMoved)\b|Math\.abs\s*\(|event\.preventDefault\s*\(|e\.preventDefault\s*\(/i;
+const DRAG_THRESHOLD_PATTERN = /\b(threshold|delta|dragDistance|swipeDistance|minDrag|movementX|movementY|clientX|clientY|pageX|pageY|Math\.abs)\b/i;
+const MARKER_LAYERING_PATTERN = /\b(collisionBehavior|zIndex|z-index|aria-label|selected|active|contrast|outline|box-shadow)\b/i;
+
+export async function scanGestureInteraction(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const files = await collectFiles(root);
+  const result = {
+    schema_version: '0.1.0',
+    status: 'pass',
+    scanned_files: files.length,
+    touch_action_hits: [],
+    overlay_pointer_hits: [],
+    drag_tap_hits: [],
+    carousel_hits: [],
+    map_marker_hits: [],
+    risk_summary: {
+      touch_action_hits: { block: 0, review: 0, info: 0 },
+      overlay_pointer_hits: { block: 0, review: 0, info: 0 },
+      drag_tap_hits: { block: 0, review: 0, info: 0 },
+      carousel_hits: { block: 0, review: 0, info: 0 },
+      map_marker_hits: { block: 0, review: 0, info: 0 }
+    },
+    summary: {
+      total_hits: 0,
+      scanned_files: files.length
+    }
+  };
+
+  for (const file of files) {
+    const content = await readFile(file.absolutePath, 'utf8');
+    const ext = path.extname(file.relativePath).toLowerCase();
+    if (['.css', '.html', '.htm'].includes(ext)) {
+      collectCssGestureHits(result, file.relativePath, content);
+    }
+    if (['.js', '.jsx', '.mjs', '.ts', '.tsx', '.html', '.htm'].includes(ext)) {
+      collectCodeGestureHits(result, file.relativePath, content);
+    }
+  }
+
+  for (const key of Object.keys(result.risk_summary)) {
+    result.risk_summary[key] = summarizeGateEffects(result[key]);
+  }
+  result.summary.total_hits = [
+    result.touch_action_hits,
+    result.overlay_pointer_hits,
+    result.drag_tap_hits,
+    result.carousel_hits,
+    result.map_marker_hits
+  ].reduce((total, hits) => total + hits.length, 0);
+  result.status = result.summary.total_hits > 0 ? 'needs_review' : 'pass';
+  return result;
+}
+
+function collectCssGestureHits(result, file, content) {
+  const rulePattern = /([^{}]+)\{([^{}]*)\}/gm;
+  let match;
+  while ((match = rulePattern.exec(content)) !== null) {
+    const selector = cleanup(match[1]);
+    const body = match[2];
+    const selectorAndBody = `${selector} ${body}`;
+    const line = lineNumberAt(content, match.index);
+    const excerpt = `${selector} { ${cleanup(body).slice(0, 160)} }`;
+    const touchAction = TOUCH_ACTION_PATTERN.exec(body)?.[1]?.trim();
+
+    if (touchAction && GESTURE_SURFACE_PATTERN.test(selectorAndBody) && isAmbiguousTouchAction(touchAction)) {
+      result.touch_action_hits.push({
+        file,
+        line,
+        kind: 'ambiguous_touch_action_on_gesture_surface',
+        selector,
+        touch_action: touchAction,
+        excerpt,
+        confidence: /pan-x.*pan-y|pan-y.*pan-x/.test(touchAction) ? 'high' : 'medium',
+        gate_effect: 'review',
+        recommendation: 'carousel、map、drag surfaceでは縦横panやpinch-zoomを同時に許可する前に、スワイプ、地図移動、ページスクロールの優先順位をStory/E2Eで明示する。'
+      });
+    }
+
+    if (MAP_SURFACE_PATTERN.test(selectorAndBody)
+      && POSITIONED_OVERLAY_PATTERN.test(body)
+      && !POINTER_EVENTS_NONE_PATTERN.test(body)
+      && /z-index\s*:|inset\s*:|top\s*:|bottom\s*:|left\s*:|right\s*:/.test(body)) {
+      result.overlay_pointer_hits.push({
+        file,
+        line,
+        kind: 'map_overlay_may_capture_touch',
+        selector,
+        excerpt,
+        confidence: 'medium',
+        gate_effect: 'review',
+        recommendation: 'map上のoverlayは操作を奪う必要がある領域だけpointer-events:autoにし、装飾や表示だけのlayerはpointer-events:noneにする。'
+      });
+    }
+
+    if (CAROUSEL_SURFACE_PATTERN.test(selectorAndBody) && OVERFLOW_X_PATTERN.test(body) && !SCROLL_SNAP_PATTERN.test(body)) {
+      result.carousel_hits.push({
+        file,
+        line,
+        kind: 'carousel_missing_scroll_snap_contract',
+        selector,
+        excerpt,
+        confidence: 'medium',
+        gate_effect: 'review',
+        recommendation: 'carouselはscroll-snap、active item更新、drag threshold、または代替の明示制御を持つことを確認する。'
+      });
+    }
+
+    const size = extractStaticSize(body);
+    if (size && TOUCH_TARGET_PATTERN.test(selector) && (size.width < 44 || size.height < 44)) {
+      result.carousel_hits.push({
+        file,
+        line,
+        kind: 'small_gesture_hit_area',
+        selector,
+        width_px: size.width,
+        height_px: size.height,
+        excerpt,
+        confidence: 'medium',
+        gate_effect: 'review',
+        recommendation: 'mobile touch targetやmap markerの実hit areaは44px程度を基準に、visual sizeだけでなくpaddingや透明hit areaで補強する。'
+      });
+    }
+  }
+}
+
+function collectCodeGestureHits(result, file, content) {
+  const code = stripComments(content);
+  if (DRAG_HANDLER_PATTERN.test(code) && CLICK_NAV_PATTERN.test(code)) {
+    const states = [...new Set([...code.matchAll(DRAG_STATE_PATTERN)].map((match) => match[1]))];
+    if (states.length > 0 && !CLICK_SUPPRESSION_PATTERN.test(code)) {
+      result.drag_tap_hits.push({
+        file,
+        line: lineNumberAt(content, code.indexOf(states[0])),
+        kind: 'drag_state_not_connected_to_click_suppression',
+        state_candidates: states.slice(0, 5),
+        excerpt: excerptAround(content, states[0]),
+        confidence: 'medium',
+        gate_effect: 'review',
+        recommendation: 'drag/swipe stateを取得している場合は、移動量が閾値を超えたclickやnavigationを抑止し、Playwrightでdrag後にURLが変わらないことを確認する。'
+      });
+    }
+  }
+
+  if (CAROUSEL_SURFACE_PATTERN.test(code)
+    && DRAG_HANDLER_PATTERN.test(code)
+    && !DRAG_THRESHOLD_PATTERN.test(code)) {
+    result.carousel_hits.push({
+      file,
+      line: firstPatternLine(content, DRAG_HANDLER_PATTERN),
+      kind: 'carousel_drag_threshold_not_detected',
+      excerpt: excerptAround(content, 'onPointer'),
+      confidence: 'medium',
+      gate_effect: 'review',
+      recommendation: 'carouselのdrag/tap判定は開始座標、移動量、閾値、active card更新、scrollLeft変化を明示する。'
+    });
+  }
+
+  if (MARKER_CODE_PATTERN.test(code) && !MARKER_LAYERING_PATTERN.test(code)) {
+    result.map_marker_hits.push({
+      file,
+      line: firstPatternLine(content, MARKER_CODE_PATTERN),
+      kind: 'map_marker_layering_contract_missing',
+      excerpt: excerptAround(content, 'Marker'),
+      confidence: 'medium',
+      gate_effect: 'review',
+      recommendation: 'map markerはcollisionBehavior、zIndex、選択状態、contrast、hit areaの少なくとも一部を明示し、重なり時の操作優先度を確認する。'
+    });
+  }
+}
+
+async function collectFiles(root, current = root) {
+  const entries = await readdir(current, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && IGNORED_DIRS.has(entry.name)) continue;
+    const absolutePath = path.join(current, entry.name);
+    const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
+
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(root, absolutePath));
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+    if (!shouldScanFile(relativePath)) continue;
+    const fileStat = await stat(absolutePath);
+    if (fileStat.size > 1024 * 1024) continue;
+    files.push({ absolutePath, relativePath });
+  }
+
+  return files;
+}
+
+function shouldScanFile(relativePath) {
+  const ext = path.extname(relativePath).toLowerCase();
+  if (!TEXT_EXTENSIONS.has(ext)) return false;
+  if (!UI_ROOT_PATTERN.test(relativePath) && relativePath.includes('/')) return false;
+  return !relativePath.endsWith('.test.js')
+    && !relativePath.endsWith('.test.jsx')
+    && !relativePath.endsWith('.test.ts')
+    && !relativePath.endsWith('.test.tsx');
+}
+
+function isAmbiguousTouchAction(value) {
+  const normalized = value.toLowerCase();
+  if (normalized === 'auto' || normalized === 'manipulation') return true;
+  if (normalized.includes('pinch-zoom') && (normalized.includes('pan-x') || normalized.includes('pan-y'))) return true;
+  return normalized.includes('pan-x') && normalized.includes('pan-y');
+}
+
+function extractStaticSize(body) {
+  const width = extractPxValue(body, 'width') ?? extractPxValue(body, 'min-width');
+  const height = extractPxValue(body, 'height') ?? extractPxValue(body, 'min-height');
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  return { width, height };
+}
+
+function extractPxValue(body, property) {
+  const pattern = new RegExp(`${property}\\s*:\\s*(\\d+(?:\\.\\d+)?)px`, 'i');
+  const match = pattern.exec(body);
+  if (!match) return null;
+  return Number(match[1]);
+}
+
+function stripComments(content) {
+  return content
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+function firstPatternLine(content, pattern) {
+  const match = pattern.exec(content);
+  return lineNumberAt(content, match?.index ?? 0);
+}
+
+function excerptAround(content, token) {
+  const index = token ? content.indexOf(token) : -1;
+  const start = Math.max(0, index < 0 ? 0 : index - 80);
+  return cleanup(content.slice(start, start + 180));
+}
+
+function lineNumberAt(content, index) {
+  return content.slice(0, index).split(/\r?\n/).length;
+}
+
+function cleanup(value) {
+  return String(value).trim().replace(/\s+/g, ' ');
+}
+
+function summarizeGateEffects(hits) {
+  const summary = { block: 0, review: 0, info: 0 };
+  for (const hit of hits) {
+    const effect = ['block', 'review', 'info'].includes(hit.gate_effect) ? hit.gate_effect : 'info';
+    summary[effect] += 1;
+  }
+  return summary;
+}
+
+export function renderGestureInteractionReport({ runId, gestureInteraction }) {
+  if (!gestureInteraction) {
+    return `# ジェスチャー操作診断結果
+
+| 項目 | 内容 |
+|------|------|
+| Run ID | ${runId} |
+| 状態 | gesture-interaction は適用されていない |
+`;
+  }
+  const groups = [
+    ['touch_action_hits', 'touch-action候補'],
+    ['overlay_pointer_hits', 'overlay pointer候補'],
+    ['drag_tap_hits', 'drag/tap候補'],
+    ['carousel_hits', 'carousel/hit area候補'],
+    ['map_marker_hits', 'map marker候補']
+  ];
+  return `# ジェスチャー操作診断結果
+
+| 項目 | 内容 |
+|------|------|
+| Run ID | ${runId} |
+| Status | ${gestureInteraction.status} |
+| 走査ファイル | ${gestureInteraction.scanned_files}件 |
+| 検出候補 | ${gestureInteraction.summary?.total_hits ?? 0}件 |
+${groups.map(([key, label]) => `| ${label} | ${formatRiskCount(gestureInteraction[key] ?? [], gestureInteraction.risk_summary?.[key])} |`).join('\n')}
+
+${groups.map(([key, label]) => `## ${label}
+
+${renderHits(gestureInteraction[key] ?? [])}`).join('\n\n')}
+`;
+}
+
+function renderHits(hits) {
+  if (hits.length === 0) return '- なし';
+  return hits.map((hit) => `- ${hit.file}:${hit.line} ${hit.kind} confidence=${hit.confidence ?? '-'} gate_effect=${hit.gate_effect ?? '-'} ${hit.selector ? `selector=${hit.selector} ` : ''}\`${hit.excerpt ?? ''}\``).join('\n');
+}
+
+function formatRiskCount(hits = [], summary = null) {
+  const gateSummary = summary ?? summarizeGateEffects(hits);
+  return `${hits.length}件 (block=${gateSummary.block ?? 0}, review=${gateSummary.review ?? 0}, info=${gateSummary.info ?? 0})`;
+}

package/src/graph-context.js

@@ -0,0 +1,263 @@
+export function normalizeGraphEdges(graph) {
+  if (Array.isArray(graph?.edges)) return { edges: graph.edges, sourceKey: 'edges' };
+  if (Array.isArray(graph?.links)) return { edges: graph.links, sourceKey: 'links' };
+  return { edges: [], sourceKey: null };
+}
+
+export function buildGraphIndex({ nodes = [], edges = [] } = {}) {
+  const nodesById = new Map();
+  const nodesBySourceFile = new Map();
+  const degreeByNodeId = new Map();
+  const edgesByNodeId = new Map();
+
+  for (const node of nodes) {
+    if (!node || typeof node !== 'object' || typeof node.id !== 'string') continue;
+    nodesById.set(node.id, node);
+    const sourceFile = extractGraphNodeSourceFile(node);
+    if (sourceFile) {
+      const key = normalizeGraphPath(sourceFile);
+      if (!nodesBySourceFile.has(key)) nodesBySourceFile.set(key, []);
+      nodesBySourceFile.get(key).push(node);
+    }
+  }
+
+  for (const edge of edges) {
+    const source = getEdgeEndpoint(edge, 'source');
+    const target = getEdgeEndpoint(edge, 'target');
+    if (!source || !target) continue;
+    degreeByNodeId.set(source, (degreeByNodeId.get(source) ?? 0) + 1);
+    degreeByNodeId.set(target, (degreeByNodeId.get(target) ?? 0) + 1);
+    if (!edgesByNodeId.has(source)) edgesByNodeId.set(source, []);
+    if (!edgesByNodeId.has(target)) edgesByNodeId.set(target, []);
+    edgesByNodeId.get(source).push(edge);
+    edgesByNodeId.get(target).push(edge);
+  }
+
+  return {
+    nodesById,
+    nodesBySourceFile,
+    degreeByNodeId,
+    edgesByNodeId,
+    edgeCount: edges.length
+  };
+}
+
+export function buildGraphContextForRoutes(routes, graphIndex) {
+  const context = buildGraphContextForFiles(routes.map((route) => route.file), graphIndex);
+  return {
+    ...context,
+    matched_route_count: context.matched_file_count,
+    affected_communities: context.affected_communities.map((community) => ({
+      ...community,
+      route_count: community.file_count ?? community.route_count ?? 0
+    }))
+  };
+}
+
+export function buildGraphContextForFiles(files, graphIndex) {
+  const normalizedFiles = uniqueNormalizedGraphFiles(files);
+  const empty = {
+    ...emptyGraphContext(),
+    target_file_count: normalizedFiles.length,
+    matched_file_count: 0,
+    matched_files: [],
+    unmatched_files: normalizedFiles,
+    related_files: [],
+    community_span: 0,
+    cross_community: false
+  };
+  if (!graphIndex || normalizedFiles.length === 0) return empty;
+
+  const targetFiles = new Set(normalizedFiles);
+  const matchedFiles = new Set();
+  const matchedNodesById = new Map();
+  const relatedEdges = new Set();
+
+  for (const file of normalizedFiles) {
+    const matchedNodes = graphIndex.nodesBySourceFile.get(file) ?? [];
+    if (matchedNodes.length === 0) continue;
+    matchedFiles.add(file);
+    for (const node of matchedNodes) {
+      matchedNodesById.set(node.id, node);
+      for (const edge of graphIndex.edgesByNodeId.get(node.id) ?? []) {
+        relatedEdges.add(edge);
+      }
+    }
+  }
+
+  if (matchedNodesById.size === 0) return empty;
+
+  const touchedNodeIds = new Set(matchedNodesById.keys());
+  for (const edge of relatedEdges) {
+    const source = getEdgeEndpoint(edge, 'source');
+    const target = getEdgeEndpoint(edge, 'target');
+    if (source) touchedNodeIds.add(source);
+    if (target) touchedNodeIds.add(target);
+  }
+
+  const affectedCommunities = buildAffectedCommunities({
+    matchedNodes: [...matchedNodesById.values()],
+    matchedRouteFiles: new Set(),
+    matchedFiles,
+    relatedEdges: [...relatedEdges],
+    graphIndex
+  });
+  const affectedCommunityIds = new Set(affectedCommunities.map((community) => community.id));
+
+  return {
+    matched_route_count: 0,
+    target_file_count: normalizedFiles.length,
+    matched_file_count: matchedFiles.size,
+    matched_files: [...matchedFiles].sort(),
+    unmatched_files: normalizedFiles.filter((file) => !matchedFiles.has(file)),
+    matched_node_count: matchedNodesById.size,
+    affected_communities: affectedCommunities,
+    hub_nodes: buildHubNodes({
+      touchedNodeIds,
+      matchedNodeIds: new Set(matchedNodesById.keys()),
+      affectedCommunityIds,
+      graphIndex
+    }),
+    related_files: buildRelatedGraphFiles({ touchedNodeIds, targetFiles, graphIndex }),
+    related_edge_count: relatedEdges.size,
+    impact_score: calculateImpactScore(relatedEdges.size, graphIndex.edgeCount),
+    community_span: affectedCommunities.length,
+    cross_community: affectedCommunities.length > 1
+  };
+}
+
+export function emptyGraphContext() {
+  return {
+    matched_route_count: 0,
+    target_file_count: 0,
+    matched_file_count: 0,
+    matched_files: [],
+    unmatched_files: [],
+    matched_node_count: 0,
+    affected_communities: [],
+    hub_nodes: [],
+    related_files: [],
+    related_edge_count: 0,
+    impact_score: 0,
+    community_span: 0,
+    cross_community: false
+  };
+}
+
+export function normalizeGraphPath(filePath) {
+  return String(filePath).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function uniqueNormalizedGraphFiles(files) {
+  return [...new Set((files ?? [])
+    .map((file) => normalizeGraphPath(file ?? ''))
+    .filter(Boolean))]
+    .sort();
+}
+
+function buildAffectedCommunities({ matchedNodes, matchedRouteFiles, matchedFiles = matchedRouteFiles, relatedEdges, graphIndex }) {
+  const communities = new Map();
+  for (const node of matchedNodes) {
+    const id = node.community ?? 'unknown';
+    if (!communities.has(id)) {
+      communities.set(id, {
+        id,
+        routeFiles: new Set(),
+        files: new Set(),
+        nodeIds: new Set(),
+        edgeCount: 0
+      });
+    }
+    const item = communities.get(id);
+    const sourceFile = extractGraphNodeSourceFile(node);
+    const normalizedSourceFile = sourceFile ? normalizeGraphPath(sourceFile) : null;
+    if (normalizedSourceFile && matchedRouteFiles.has(normalizedSourceFile)) {
+      item.routeFiles.add(normalizedSourceFile);
+    }
+    if (normalizedSourceFile && matchedFiles.has(normalizedSourceFile)) {
+      item.files.add(normalizedSourceFile);
+    }
+    item.nodeIds.add(node.id);
+  }
+
+  for (const edge of relatedEdges) {
+    const communityIds = new Set([
+      graphIndex.nodesById.get(getEdgeEndpoint(edge, 'source'))?.community ?? null,
+      graphIndex.nodesById.get(getEdgeEndpoint(edge, 'target'))?.community ?? null
+    ].filter((id) => id !== null));
+    for (const id of communityIds) {
+      if (communities.has(id)) communities.get(id).edgeCount += 1;
+    }
+  }
+
+  return [...communities.values()]
+    .map((item) => ({
+      id: item.id,
+      route_count: item.routeFiles.size,
+      file_count: item.files.size,
+      node_count: item.nodeIds.size,
+      edge_count: item.edgeCount
+    }))
+    .sort((a, b) => b.route_count - a.route_count || b.file_count - a.file_count || b.node_count - a.node_count || String(a.id).localeCompare(String(b.id)));
+}
+
+function buildHubNodes({ touchedNodeIds, matchedNodeIds, affectedCommunityIds, graphIndex }) {
+  return [...touchedNodeIds]
+    .map((id) => graphIndex.nodesById.get(id))
+    .filter(Boolean)
+    .filter((node) => isRelevantHubNode({ node, matchedNodeIds, affectedCommunityIds }))
+    .map((node) => ({
+      id: node.id,
+      label: node.label ?? node.name ?? node.id,
+      source_file: extractGraphNodeSourceFile(node) ?? null,
+      community: node.community ?? null,
+      degree: graphIndex.degreeByNodeId.get(node.id) ?? 0
+    }))
+    .sort((a, b) => b.degree - a.degree || a.id.localeCompare(b.id))
+    .slice(0, 5);
+}
+
+function isRelevantHubNode({ node, matchedNodeIds, affectedCommunityIds }) {
+  if (matchedNodeIds.has(node.id)) return true;
+  if (!affectedCommunityIds.has(node.community ?? 'unknown')) return false;
+  const sourceFile = extractGraphNodeSourceFile(node);
+  if (!sourceFile) return false;
+  return normalizeGraphPath(sourceFile).startsWith('src/');
+}
+
+function buildRelatedGraphFiles({ touchedNodeIds, targetFiles, graphIndex }) {
+  const related = new Map();
+  for (const nodeId of touchedNodeIds) {
+    const node = graphIndex.nodesById.get(nodeId);
+    const sourceFile = node ? extractGraphNodeSourceFile(node) : null;
+    const file = sourceFile ? normalizeGraphPath(sourceFile) : null;
+    if (!file || targetFiles.has(file)) continue;
+    const degree = graphIndex.degreeByNodeId.get(nodeId) ?? 0;
+    related.set(file, Math.max(related.get(file) ?? 0, degree));
+  }
+  return [...related.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 8)
+    .map(([file]) => file);
+}
+
+function calculateImpactScore(relatedEdgeCount, totalEdgeCount) {
+  if (!totalEdgeCount) return 0;
+  return Number(Math.min(1, relatedEdgeCount / totalEdgeCount).toFixed(4));
+}
+
+export function extractGraphNodeSourceFile(node) {
+  return node.source_file
+    ?? node.sourceFile
+    ?? node.file
+    ?? node.path
+    ?? node.payload?.source_file
+    ?? node.payload?.sourceFile
+    ?? null;
+}
+
+export function getEdgeEndpoint(edge, endpoint) {
+  if (!edge || typeof edge !== 'object') return null;
+  if (endpoint === 'source') return edge.source ?? edge.from ?? edge._src ?? edge.source_id ?? edge.sourceId ?? null;
+  return edge.target ?? edge.to ?? edge._dst ?? edge._tgt ?? edge.target_id ?? edge.targetId ?? null;
+}