archgraph 0.1.0

package/packages/core/src/export.js

@@ -0,0 +1,77 @@
+import { writeFile } from 'node:fs/promises';
+
+function escapeCypher(value) {
+  return String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+
+function escapeMermaid(value) {
+  return String(value).replaceAll('"', '\\"');
+}
+
+function toCypher(graph) {
+  const lines = [];
+  lines.push('// backend-graphing cypher export');
+  lines.push('BEGIN;');
+
+  const nodes = [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id));
+  for (const node of nodes) {
+    const label = `n_${node.kind}`.replace(/[^A-Za-z0-9_]/g, '_');
+    lines.push(`MERGE (n:${label} {id: "${escapeCypher(node.id)}"})`);
+    lines.push(`SET n.label = "${escapeCypher(node.label)}", n.kind = "${escapeCypher(node.kind)}"`);
+    if (node.file) {
+      lines.push(`SET n.file = "${escapeCypher(node.file)}"`);
+    }
+    if (node.symbol) {
+      lines.push(`SET n.symbol = "${escapeCypher(node.symbol)}"`);
+    }
+    if (node.external) {
+      lines.push('SET n.external = true');
+    }
+  }
+
+  const edges = [...graph.edges].sort((a, b) => a.id.localeCompare(b.id));
+  for (const edge of edges) {
+    const rel = `E_${edge.kind.toUpperCase()}`.replace(/[^A-Z0-9_]/g, '_');
+    lines.push(`MATCH (a {id: "${escapeCypher(edge.from)}"}), (b {id: "${escapeCypher(edge.to)}"})`);
+    lines.push(`MERGE (a)-[:${rel}]->(b)`);
+  }
+
+  lines.push('COMMIT;');
+  return `${lines.join('\n')}\n`;
+}
+
+function toMermaid(graph) {
+  const lines = [];
+  lines.push('graph TD');
+
+  const nodes = [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id));
+  for (const node of nodes) {
+    lines.push(`  ${node.id}["${escapeMermaid(node.label)}"]`);
+  }
+
+  const edges = [...graph.edges].sort((a, b) => a.id.localeCompare(b.id));
+  for (const edge of edges) {
+    lines.push(`  ${edge.from} -- ${edge.kind} --> ${edge.to}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export async function exportGraph(graph, format, outPath) {
+  if (format === 'graph-json') {
+    await writeFile(outPath, `${JSON.stringify(graph, null, 2)}\n`, 'utf8');
+    return;
+  }
+
+  if (format === 'cypher') {
+    await writeFile(outPath, toCypher(graph), 'utf8');
+    return;
+  }
+
+  if (format === 'mermaid') {
+    await writeFile(outPath, toMermaid(graph), 'utf8');
+    return;
+  }
+
+  throw new Error(`Unsupported format: ${format}`);
+}

package/packages/core/src/index.js

@@ -0,0 +1,4 @@
+export { analyzeProject } from './analyze-project.js';
+export { buildView } from './view.js';
+export { exportGraph } from './export.js';
+export { SUPPORTED_NODE_KINDS, SUPPORTED_EDGE_KINDS } from './types.js';

package/packages/core/src/types.js

@@ -0,0 +1,37 @@
+/** @typedef {'endpoint'|'route_handler'|'function'|'method'|'class'|'object'|'agent'|'langgraph_node'|'mcp_tool'|'module'|'file'|'ui_route'|'ui_component'|'group'|'condition'} NodeKind */
+/** @typedef {'declares_endpoint'|'handles'|'calls'|'imports'|'invokes_agent'|'uses_mcp_tool'|'langgraph_edge'|'belongs_to_group'|'ui_calls_api'|'frontend_proxies_to_backend'|'evaluates_condition'|'condition_true'|'condition_false'|'condition_case'} EdgeKind */
+
+export const SUPPORTED_NODE_KINDS = [
+  'endpoint',
+  'route_handler',
+  'function',
+  'method',
+  'class',
+  'object',
+  'agent',
+  'langgraph_node',
+  'mcp_tool',
+  'module',
+  'file',
+  'ui_route',
+  'ui_component',
+  'group',
+  'condition',
+];
+
+export const SUPPORTED_EDGE_KINDS = [
+  'declares_endpoint',
+  'handles',
+  'calls',
+  'imports',
+  'invokes_agent',
+  'uses_mcp_tool',
+  'langgraph_edge',
+  'belongs_to_group',
+  'ui_calls_api',
+  'frontend_proxies_to_backend',
+  'evaluates_condition',
+  'condition_true',
+  'condition_false',
+  'condition_case',
+];

package/packages/core/src/view.js

@@ -0,0 +1,86 @@
+function buildAdjacency(edges) {
+  const out = new Map();
+  for (const edge of edges) {
+    if (!out.has(edge.from)) out.set(edge.from, []);
+    out.get(edge.from).push(edge.to);
+    if (!out.has(edge.to)) out.set(edge.to, []);
+  }
+  return out;
+}
+
+function bfs(startNodes, adjacency, depth) {
+  const visited = new Set();
+  const queue = startNodes.map((id) => ({ id, depth: 0 }));
+
+  while (queue.length) {
+    const current = queue.shift();
+    if (visited.has(current.id)) continue;
+    visited.add(current.id);
+    if (current.depth >= depth) continue;
+    for (const next of adjacency.get(current.id) ?? []) {
+      if (!visited.has(next)) {
+        queue.push({ id: next, depth: current.depth + 1 });
+      }
+    }
+  }
+
+  return visited;
+}
+
+export function buildView(graph, spec) {
+  const depth = Number.isFinite(spec.depth) ? Number(spec.depth) : 2;
+  const includeKinds = spec.includeNodeKinds?.length ? new Set(spec.includeNodeKinds) : null;
+  const excludeExternal = Boolean(spec.excludeExternal);
+
+  const adjacency = buildAdjacency(graph.edges);
+
+  let startNodes;
+  if (spec.focus) {
+    startNodes = [spec.focus];
+  } else {
+    startNodes = graph.nodes.filter((n) => n.kind === 'endpoint').map((n) => n.id);
+    if (!startNodes.length) {
+      startNodes = graph.nodes.slice(0, 1).map((n) => n.id);
+    }
+  }
+
+  const visible = bfs(startNodes, adjacency, Math.max(depth, 0));
+
+  let nodes = graph.nodes.filter((node) => visible.has(node.id));
+  if (includeKinds) {
+    nodes = nodes.filter((node) => includeKinds.has(node.kind));
+  }
+  if (excludeExternal) {
+    nodes = nodes.filter((node) => !node.external);
+  }
+
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges = graph.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+
+  let groups = graph.groups;
+  if (spec.groupBy) {
+    groups = groups.filter((group) => group.kind === spec.groupBy);
+  }
+  groups = groups
+    .map((group) => ({
+      ...group,
+      memberNodeIds: group.memberNodeIds.filter((id) => nodeIds.has(id)),
+    }))
+    .filter((group) => group.memberNodeIds.length > 0);
+
+  return {
+    spec: {
+      version: '1',
+      depth,
+      focus: spec.focus,
+      groupBy: spec.groupBy,
+      includeNodeKinds: spec.includeNodeKinds,
+      excludeExternal,
+      collapsePatterns: spec.collapsePatterns,
+      labelMode: spec.labelMode,
+    },
+    nodes,
+    edges,
+    groups,
+  };
+}

package/packages/viewer/public/app.js

@@ -0,0 +1,226 @@
+// app.js — BGX Viewer entry point
+
+import { initCanvas, canvasTransform, nodePositions, applyCanvasTransform } from './canvas.js';
+import { initMinimap, setMinimapView, updateMinimap } from './minimap.js';
+import { initTooltip } from './tooltip.js';
+import { initSidebar, openCodeSidebar } from './sidebar.js';
+import { initComments } from './comments.js';
+import {
+  initRender,
+  setRenderView,
+  setSelectedNode,
+  setCurrentTasks,
+  renderGraph,
+  renderCommentPins,
+  applyCollapse,
+} from './render.js';
+import { initTheme, toggleTheme } from './theme.js';
+
+// ─── Global state ─────────────────────────────────────────────────────────────
+let graph = null;
+let view = null;
+let descriptions = null;
+let selectedNodeId = null;
+let currentTasks = [];
+let currentNodes = [];
+let currentEdges = [];
+
+// ─── DOM refs ──────────────────────────────────────────────────────────────────
+const graphSvg       = document.getElementById('graphSvg');
+const canvasGroup    = document.getElementById('canvasGroup');
+const groupByInput   = document.getElementById('groupBy');
+const groupItemInput = document.getElementById('groupItem');
+const searchInput    = document.getElementById('search');
+const summaryBadge   = document.getElementById('summaryBadge');
+const projectNameEl  = document.getElementById('projectName');
+const resetViewBtn   = document.getElementById('resetViewBtn');
+const themeToggleBtn = document.getElementById('themeToggleBtn');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+// ─── Group/filter helpers ─────────────────────────────────────────────────────
+function listGroups(groupBy) {
+  const groups = view.groups.filter((g) => g.kind === groupBy);
+  const previous = groupItemInput.value;
+
+  groupItemInput.innerHTML = ['<option value="">All</option>']
+    .concat(
+      groups
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((g) => `<option value="${escapeHtml(g.id)}">${escapeHtml(g.name)}</option>`),
+    )
+    .join('');
+
+  if (previous && groups.some((g) => g.id === previous)) {
+    groupItemInput.value = previous;
+  }
+}
+
+function getVisibleGraph() {
+  const groupBy = groupByInput.value;
+  const search = searchInput.value.trim().toLowerCase();
+
+  const groups = view.groups.filter((g) => g.kind === groupBy);
+  const selectedGroup = groups.find((g) => g.id === groupItemInput.value) ?? null;
+
+  let visibleSet = null;
+  if (selectedGroup) {
+    visibleSet = new Set(selectedGroup.memberNodeIds);
+  }
+
+  let nodes = view.nodes.filter((node) => (visibleSet ? visibleSet.has(node.id) : true));
+
+  if (search) {
+    nodes = nodes.filter(
+      (node) =>
+        node.label.toLowerCase().includes(search) || node.kind.toLowerCase().includes(search),
+    );
+  }
+
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges = view.edges.filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to));
+
+  return applyCollapse(nodes, edges);
+}
+
+// ─── Node selection ───────────────────────────────────────────────────────────
+async function selectNode(nodeId) {
+  selectedNodeId = nodeId;
+  setSelectedNode(nodeId);
+
+  // Re-render to show selection highlight
+  renderGraph(currentNodes, currentEdges);
+  renderCommentPins(currentTasks);
+
+  try {
+    const response = await fetch(`/api/node/${encodeURIComponent(nodeId)}/code`);
+    const payload = await response.json();
+    openCodeSidebar(payload, descriptions);
+  } catch (error) {
+    console.error('Failed to load code for node:', error);
+  }
+}
+
+// ─── Task loading ─────────────────────────────────────────────────────────────
+async function loadTasks() {
+  try {
+    const response = await fetch('/api/tasks');
+    const payload = await response.json();
+    currentTasks = payload.tasks || [];
+    setCurrentTasks(currentTasks);
+    renderCommentPins(currentTasks);
+  } catch (error) {
+    console.error('Failed to load tasks:', error);
+  }
+}
+
+// ─── Main render ──────────────────────────────────────────────────────────────
+async function render() {
+  const { nodes, edges } = getVisibleGraph();
+  currentNodes = nodes;
+  currentEdges = edges;
+
+  summaryBadge.textContent = `${nodes.length} nodes · ${edges.length} edges`;
+
+  renderGraph(nodes, edges);
+  renderCommentPins(currentTasks);
+  updateMinimap(canvasTransform, nodePositions, graphSvg);
+}
+
+// ─── Data loading ─────────────────────────────────────────────────────────────
+async function loadData() {
+  const [graphRes, viewRes, descRes] = await Promise.all([
+    fetch('/api/graph'),
+    fetch('/api/view'),
+    fetch('/api/descriptions'),
+  ]);
+  graph = await graphRes.json();
+  view = await viewRes.json();
+  descriptions = await descRes.json();
+
+  projectNameEl.textContent = graph.project?.name ?? 'BGX Viewer';
+  document.title = `BGX — ${graph.project?.name ?? 'Viewer'}`;
+
+  setRenderView(view);
+  setMinimapView(view);
+
+  listGroups(groupByInput.value);
+  await render();
+  await loadTasks();
+}
+
+// ─── Reset view ───────────────────────────────────────────────────────────────
+function doResetView() {
+  nodePositions.clear();
+  canvasTransform.x = 60;
+  canvasTransform.y = 60;
+  canvasTransform.scale = 1.0;
+  applyCanvasTransform();
+  renderGraph(currentNodes, currentEdges);
+  renderCommentPins(currentTasks);
+}
+
+// ─── Global hooks (used by render.js and minimap.js to avoid circular deps) ───
+window.__bgxPanToWorld = (worldX, worldY) => {
+  const rect = graphSvg.getBoundingClientRect();
+  canvasTransform.x = rect.width / 2 - worldX * canvasTransform.scale;
+  canvasTransform.y = rect.height / 2 - worldY * canvasTransform.scale;
+  applyCanvasTransform();
+};
+
+window.__bgxRender = async () => {
+  await render();
+};
+
+// ─── Initialization ───────────────────────────────────────────────────────────
+initTheme();
+initTooltip();
+
+initCanvas(graphSvg, canvasGroup, {
+  onNodeClick: (nodeId) => selectNode(nodeId),
+  onResetView: doResetView,
+});
+
+initRender(graphSvg, canvasGroup, {
+  onSelect: (nodeId) => selectNode(nodeId),
+});
+
+initSidebar();
+
+initComments({
+  onReload: async () => {
+    await loadTasks();
+  },
+});
+
+initMinimap(null); // view passed after load via setMinimapView
+
+resetViewBtn.addEventListener('click', doResetView);
+themeToggleBtn.addEventListener('click', toggleTheme);
+
+groupByInput.addEventListener('change', async () => {
+  listGroups(groupByInput.value);
+  await render();
+});
+
+groupItemInput.addEventListener('change', async () => {
+  await render();
+});
+
+searchInput.addEventListener('input', async () => {
+  await render();
+});
+
+loadData().catch((error) => {
+  summaryBadge.textContent = `Failed to load: ${String(error)}`;
+  summaryBadge.style.color = '#b42318';
+});

package/packages/viewer/public/canvas.js

@@ -0,0 +1,181 @@
+// canvas.js — Pan, zoom, and node drag system
+
+import { updateMinimap } from './minimap.js';
+import { hideTooltip } from './tooltip.js';
+import { closeCommentOverlay } from './comments.js';
+
+export const canvasTransform = { x: 60, y: 60, scale: 1.0 };
+export const nodePositions = new Map(); // nodeId → {x, y}
+
+let graphSvg = null;
+let canvasGroup = null;
+let onNodeClick = null; // callback(nodeId)
+let onResetView = null; // callback()
+
+let isPanning = false;
+let panStart = { x: 0, y: 0, tx: 0, ty: 0 };
+
+let isDraggingNode = false;
+let draggingNodeId = null;
+let hasDragged = false;
+let dragStart = { mx: 0, my: 0, nx: 0, ny: 0 };
+let dragPointerId = null;
+
+export function initCanvas(svgEl, groupEl, { onNodeClick: clickCb, onResetView: resetCb }) {
+  graphSvg = svgEl;
+  canvasGroup = groupEl;
+  onNodeClick = clickCb;
+  onResetView = resetCb;
+
+  graphSvg.addEventListener('pointerdown', onCanvasPointerDown);
+  graphSvg.addEventListener('pointermove', onCanvasPointerMove);
+  graphSvg.addEventListener('pointerup', onCanvasPointerUp);
+  graphSvg.addEventListener('pointercancel', onCanvasPointerUp);
+
+  graphSvg.addEventListener('wheel', onCanvasWheel, { passive: false });
+
+  document.addEventListener('keydown', onKeyDown);
+
+  applyCanvasTransform();
+}
+
+export function applyCanvasTransform() {
+  const { x, y, scale } = canvasTransform;
+  canvasGroup.setAttribute('transform', `translate(${x},${y}) scale(${scale})`);
+  updateMinimap(canvasTransform, nodePositions, graphSvg);
+}
+
+export function resetView(nodes, edges, renderGraphFn) {
+  nodePositions.clear();
+  canvasTransform.x = 60;
+  canvasTransform.y = 60;
+  canvasTransform.scale = 1.0;
+  applyCanvasTransform();
+  renderGraphFn(nodes, edges);
+}
+
+function getSvgRect() {
+  return graphSvg.getBoundingClientRect();
+}
+
+function clientToWorld(clientX, clientY) {
+  const rect = getSvgRect();
+  return {
+    x: (clientX - rect.left - canvasTransform.x) / canvasTransform.scale,
+    y: (clientY - rect.top - canvasTransform.y) / canvasTransform.scale,
+  };
+}
+
+function onCanvasPointerDown(e) {
+  // Check if we're clicking on a node
+  const nodeGroup = e.target.closest('.node');
+  if (nodeGroup) {
+    // Node drag
+    e.stopPropagation();
+    const nodeId = nodeGroup.dataset.nodeId;
+    if (!nodeId) return;
+
+    isDraggingNode = true;
+    draggingNodeId = nodeId;
+    hasDragged = false;
+    dragPointerId = e.pointerId;
+
+    const world = clientToWorld(e.clientX, e.clientY);
+    const pos = nodePositions.get(nodeId) ?? { x: 0, y: 0 };
+    dragStart = { mx: world.x, my: world.y, nx: pos.x, ny: pos.y };
+
+    graphSvg.setPointerCapture(e.pointerId);
+    hideTooltip();
+    return;
+  }
+
+  // Check collapse toggle — handled by render.js
+  if (e.target.closest('.collapse-toggle')) return;
+  // Check comment pin — handled by render.js
+  if (e.target.closest('.comment-pin')) return;
+
+  // Canvas pan
+  isPanning = true;
+  panStart = { x: e.clientX, y: e.clientY, tx: canvasTransform.x, ty: canvasTransform.y };
+  graphSvg.setPointerCapture(e.pointerId);
+  graphSvg.style.cursor = 'grabbing';
+  closeCommentOverlay();
+}
+
+function onCanvasPointerMove(e) {
+  if (isDraggingNode && e.pointerId === dragPointerId) {
+    const world = clientToWorld(e.clientX, e.clientY);
+    const dx = world.x - dragStart.mx;
+    const dy = world.y - dragStart.my;
+
+    if (!hasDragged && (Math.abs(dx) > 4 || Math.abs(dy) > 4)) {
+      hasDragged = true;
+    }
+
+    if (hasDragged) {
+      nodePositions.set(draggingNodeId, {
+        x: dragStart.nx + dx,
+        y: dragStart.ny + dy,
+      });
+      // repositionNodeAndEdges is imported dynamically to avoid circular deps
+      if (window.__bgxRepositionNode) {
+        window.__bgxRepositionNode(draggingNodeId);
+      }
+    }
+    return;
+  }
+
+  if (isPanning) {
+    const dx = e.clientX - panStart.x;
+    const dy = e.clientY - panStart.y;
+    canvasTransform.x = panStart.tx + dx;
+    canvasTransform.y = panStart.ty + dy;
+    applyCanvasTransform();
+  }
+}
+
+function onCanvasPointerUp(e) {
+  if (isDraggingNode && e.pointerId === dragPointerId) {
+    if (!hasDragged && onNodeClick) {
+      onNodeClick(draggingNodeId);
+    }
+    isDraggingNode = false;
+    draggingNodeId = null;
+    hasDragged = false;
+    dragPointerId = null;
+    graphSvg.releasePointerCapture(e.pointerId);
+    return;
+  }
+
+  if (isPanning) {
+    isPanning = false;
+    graphSvg.style.cursor = '';
+    graphSvg.releasePointerCapture(e.pointerId);
+  }
+}
+
+function onCanvasWheel(e) {
+  e.preventDefault();
+
+  const factor = e.deltaY < 0 ? 1.1 : 0.9;
+  const rect = getSvgRect();
+  const mouseX = e.clientX - rect.left;
+  const mouseY = e.clientY - rect.top;
+
+  const newScale = Math.min(4.0, Math.max(0.1, canvasTransform.scale * factor));
+
+  canvasTransform.x = mouseX - (mouseX - canvasTransform.x) * (newScale / canvasTransform.scale);
+  canvasTransform.y = mouseY - (mouseY - canvasTransform.y) * (newScale / canvasTransform.scale);
+  canvasTransform.scale = newScale;
+
+  applyCanvasTransform();
+}
+
+function onKeyDown(e) {
+  if (['INPUT', 'TEXTAREA', 'SELECT'].includes(e.target.tagName)) return;
+
+  if (e.key === ' ') {
+    e.preventDefault();
+    if (onResetView) onResetView();
+  }
+}