@tyroneross/navgator 0.2.0 → 0.2.1

package/web/.next/standalone/web/app/api/connections/route.ts

@@ -0,0 +1,319 @@
+/**
+ * API Route: /api/connections
+ *
+ * Returns architecture connection data from NavGator scans.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import * as fs from "fs/promises";
+import * as path from "path";
+import type { Connection, ConnectionsApiResponse, ConnectionsSummary } from "@/lib/types";
+
+// Cache for connection data (keyed by project path)
+const connectionsCache = new Map<string, { data: ConnectionsApiResponse["data"]; timestamp: number }>();
+const CACHE_TTL = 60000; // 1 minute cache
+
+/**
+ * GET /api/connections
+ */
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const demoMode = searchParams.get("demo") === "true";
+  const refresh = searchParams.get("refresh") === "true";
+  const projectPath = searchParams.get("path");
+
+  // Demo mode
+  if (demoMode) {
+    return NextResponse.json<ConnectionsApiResponse>({
+      success: true,
+      data: generateDemoConnections(),
+      source: "mock",
+    });
+  }
+
+  const cacheKey = projectPath || "__default__";
+  const cached = connectionsCache.get(cacheKey);
+
+  // Check cache
+  if (!refresh && cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return NextResponse.json<ConnectionsApiResponse>({
+      success: true,
+      data: cached.data,
+      source: "cache",
+    });
+  }
+
+  try {
+    const data = await loadConnectionData(projectPath);
+
+    if (data) {
+      connectionsCache.set(cacheKey, { data, timestamp: Date.now() });
+
+      return NextResponse.json<ConnectionsApiResponse>({
+        success: true,
+        data,
+        source: "scan",
+      });
+    }
+
+    // No scan data - check if user explicitly wants demo
+    if (demoMode) {
+      return NextResponse.json<ConnectionsApiResponse>({
+        success: true,
+        data: generateDemoConnections(),
+        source: "mock",
+      });
+    }
+
+    // Return empty state - prompt user to run setup
+    return NextResponse.json<ConnectionsApiResponse>({
+      success: true,
+      data: {
+        connections: [],
+        summary: {
+          totalConnections: 0,
+          byType: {},
+        },
+      },
+      source: "scan",
+      error: "No scan data found. Run `navgator setup` to scan your project.",
+    });
+  } catch (error) {
+    console.error("Error loading connection data:", error);
+    return NextResponse.json<ConnectionsApiResponse>({
+      success: false,
+      data: {
+        connections: [],
+        summary: {
+          totalConnections: 0,
+          byType: {},
+        },
+      },
+      source: "scan",
+      error: error instanceof Error ? error.message : "Unknown error",
+    });
+  }
+}
+
+// =============================================================================
+// DATA LOADING
+// =============================================================================
+
+async function loadConnectionData(
+  projectPath?: string | null
+): Promise<ConnectionsApiResponse["data"] | null> {
+  // Priority: query param > env var > NavGator directory
+  const root = projectPath ||
+    process.env.NAVGATOR_PROJECT_PATH ||
+    process.cwd().replace(/\/web$/, "");
+
+  // Try to load from NavGator storage
+  const connectionsDir = path.join(root, ".claude", "architecture", "connections");
+
+  try {
+    const files = await fs.readdir(connectionsDir);
+    const connectionFiles = files.filter((f) => f.endsWith(".json"));
+
+    if (connectionFiles.length === 0) return null;
+
+    const connections: Connection[] = [];
+
+    for (const file of connectionFiles) {
+      try {
+        const content = await fs.readFile(path.join(connectionsDir, file), "utf-8");
+        const raw = JSON.parse(content);
+        connections.push(transformConnection(raw));
+      } catch {
+        // Skip invalid files
+      }
+    }
+
+    if (connections.length === 0) return null;
+
+    return {
+      connections,
+      summary: buildSummary(connections),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function transformConnection(raw: Record<string, unknown>): Connection {
+  const from = raw.from as Record<string, unknown> | undefined;
+  const to = raw.to as Record<string, unknown> | undefined;
+  const codeRef = raw.code_reference as Record<string, unknown> | undefined;
+
+  return {
+    id: String(raw.connection_id || raw.id || ""),
+    from: codeRef?.file ? String(codeRef.file) : String(from?.component_id || ""),
+    fromComponent: String(from?.component_id || ""),
+    to: String(to?.component_id || ""),
+    toComponent: String(to?.component_id || ""),
+    type: mapConnectionType(String(raw.connection_type || "")),
+    symbol: String(codeRef?.symbol || codeRef?.function_name || ""),
+    line: Number(codeRef?.line_start || 0),
+    code: String(codeRef?.code_snippet || ""),
+    confidence: Number(raw.confidence || 0.8),
+  };
+}
+
+function mapConnectionType(type: string): Connection["type"] {
+  const typeMap: Record<string, Connection["type"]> = {
+    "service-call": "service-call",
+    "api-calls-db": "api-calls-db",
+    "frontend-calls-api": "frontend-calls-api",
+    "queue-triggers": "queue-triggers",
+    "imports": "imports",
+    "prompt-usage": "prompt-usage",
+    "prompt-location": "prompt-usage",
+    "deploys-to": "deploys-to",
+    "observes": "observes",
+    "conforms-to": "conforms-to",
+    "notifies": "notifies",
+    "stores": "stores",
+    "navigates-to": "navigates-to",
+    "requires-entitlement": "requires-entitlement",
+    "target-contains": "target-contains",
+    "generates": "generates",
+    "uses-package": "uses-package",
+    "other": "other",
+  };
+  return typeMap[type] || "other";
+}
+
+function buildSummary(connections: Connection[]): ConnectionsSummary {
+  const byType: Record<string, number> = {};
+
+  for (const c of connections) {
+    byType[c.type] = (byType[c.type] || 0) + 1;
+  }
+
+  return {
+    totalConnections: connections.length,
+    byType,
+    lastScanned: new Date().toISOString(),
+  };
+}
+
+// =============================================================================
+// DEMO DATA
+// =============================================================================
+
+function generateDemoConnections(): ConnectionsApiResponse["data"] {
+  const connections: Connection[] = [
+    {
+      id: "conn-1",
+      from: "src/api/payments.ts",
+      to: "Stripe",
+      type: "service-call",
+      symbol: "createPaymentIntent",
+      line: 45,
+      code: "await stripe.paymentIntents.create({...})",
+    },
+    {
+      id: "conn-2",
+      from: "src/api/subscriptions.ts",
+      to: "Stripe",
+      type: "service-call",
+      symbol: "createSubscription",
+      line: 23,
+      code: "await stripe.subscriptions.create({...})",
+    },
+    {
+      id: "conn-3",
+      from: "src/webhooks/stripe.ts",
+      to: "Stripe",
+      type: "service-call",
+      symbol: "handleWebhook",
+      line: 12,
+      code: "stripe.webhooks.constructEvent(...)",
+    },
+    {
+      id: "conn-4",
+      from: "src/api/users.ts",
+      to: "PostgreSQL",
+      type: "api-calls-db",
+      symbol: "getUser",
+      line: 15,
+      code: "prisma.user.findUnique({...})",
+    },
+    {
+      id: "conn-5",
+      from: "src/api/users.ts",
+      to: "PostgreSQL",
+      type: "api-calls-db",
+      symbol: "createUser",
+      line: 32,
+      code: "prisma.user.create({...})",
+    },
+    {
+      id: "conn-6",
+      from: "src/api/posts.ts",
+      to: "PostgreSQL",
+      type: "api-calls-db",
+      symbol: "getPosts",
+      line: 8,
+      code: "prisma.post.findMany({...})",
+    },
+    {
+      id: "conn-7",
+      from: "src/components/PaymentForm.tsx",
+      to: "src/api/payments.ts",
+      type: "frontend-calls-api",
+      symbol: "submitPayment",
+      line: 28,
+      code: "fetch('/api/payments', {...})",
+    },
+    {
+      id: "conn-8",
+      from: "src/components/Dashboard.tsx",
+      to: "src/api/users.ts",
+      type: "frontend-calls-api",
+      symbol: "loadUserData",
+      line: 15,
+      code: "useSWR('/api/users/me')",
+    },
+    {
+      id: "conn-9",
+      from: "src/jobs/emailJob.ts",
+      to: "SendGrid",
+      type: "service-call",
+      symbol: "sendEmail",
+      line: 22,
+      code: "sgMail.send({...})",
+    },
+    {
+      id: "conn-10",
+      from: "src/api/ai.ts",
+      to: "OpenAI",
+      type: "service-call",
+      symbol: "generateCompletion",
+      line: 18,
+      code: "openai.chat.completions.create({...})",
+    },
+    {
+      id: "conn-11",
+      from: "src/api/chat.ts",
+      to: "Anthropic",
+      type: "service-call",
+      symbol: "sendMessage",
+      line: 25,
+      code: "anthropic.messages.create({...})",
+    },
+    {
+      id: "conn-12",
+      from: "src/workers/summarize.ts",
+      to: "SUMMARIZE_PROMPT",
+      type: "prompt-usage",
+      symbol: "processSummarizeJob",
+      line: 34,
+      code: "claude.messages.create({ messages: [SYSTEM_PROMPT, ...] })",
+    },
+  ];
+
+  return {
+    connections,
+    summary: buildSummary(connections),
+  };
+}

package/web/.next/standalone/web/app/api/graph/route.ts

@@ -0,0 +1,235 @@
+/**
+ * API Route: /api/graph
+ *
+ * Returns architecture graph data (nodes + edges) from graph.json
+ * Enriches nodes with component details when available.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import * as fs from "fs/promises";
+import * as path from "path";
+
+const graphCache = new Map<string, { data: unknown; timestamp: number }>();
+const CACHE_TTL = 60000;
+
+interface GraphNode {
+  id: string;
+  name: string;
+  type: string;
+  layer: string;
+  version?: string;
+  purpose?: string;
+  configFiles?: string[];
+  tags?: string[];
+  connectsTo?: string[];
+  connectedFrom?: string[];
+  hostedBy?: string;
+  hosts?: string[];
+}
+
+interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  type: string;
+  label?: string;
+}
+
+// Derive inter-node flow edges from connection files
+// The raw graph.json edges use FILE:... sources that don't match node IDs.
+// This reads CONN_service-call_*.json files and maps FILE: sources to
+// their closest parent component node using path heuristics.
+async function deriveFlowEdges(
+  connectionsDir: string,
+  nodes: GraphNode[],
+): Promise<GraphEdge[]> {
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  // Path-to-layer heuristic
+  function fileToLayer(filePath: string): string {
+    const p = filePath.toLowerCase();
+    if (p.startsWith("app/") || p.startsWith("pages/") || p.startsWith("src/app/")) return "frontend";
+    if (p.includes("worker") || p.includes("queue") || p.includes("job")) return "queue";
+    return "backend";
+  }
+
+  // Pick representative nodes per layer — only use framework, service, database, queue, llm, infra types
+  // Never use generic npm packages as representatives
+  const meaningfulTypes = new Set(["framework", "service", "database", "queue", "llm", "infra"]);
+  const layerReps = new Map<string, string>();
+  for (const node of nodes) {
+    if (!meaningfulTypes.has(node.type)) continue;
+    const layer = node.layer || "backend";
+    if (!layerReps.has(layer)) {
+      layerReps.set(layer, node.id);
+    }
+    // Prefer framework nodes as the layer representative
+    if (node.type === "framework") {
+      layerReps.set(layer, node.id);
+    }
+  }
+
+  try {
+    const files = await fs.readdir(connectionsDir);
+    const connFiles = files.filter((f) => f.startsWith("CONN_") && f.endsWith(".json"));
+
+    // Aggregate: deduplicate by (sourceNodeId, targetNodeId)
+    const edgeSet = new Map<string, { source: string; target: string; type: string; count: number }>();
+
+    for (const file of connFiles) {
+      try {
+        const content = await fs.readFile(path.join(connectionsDir, file), "utf-8");
+        const conn = JSON.parse(content);
+        const targetId = conn.to?.component_id;
+        if (!targetId || !nodeById.has(targetId)) continue;
+
+        // Map FILE: source to a layer representative node
+        const srcFile = (conn.from?.component_id || "").replace("FILE:", "");
+        const layer = fileToLayer(srcFile);
+        const sourceId = layerReps.get(layer) || null;
+
+        if (sourceId && sourceId !== targetId && nodeById.has(sourceId)) {
+          const connType = conn.connection_type || "service-call";
+          const key = `${sourceId}->${targetId}`;
+          const existing = edgeSet.get(key);
+          if (existing) {
+            existing.count++;
+          } else {
+            edgeSet.set(key, { source: sourceId, target: targetId, type: connType, count: 1 });
+          }
+        }
+      } catch {
+        // Skip invalid connection files
+      }
+    }
+
+    // Convert to GraphEdge array
+    const edges: GraphEdge[] = [];
+    edgeSet.forEach((e, _key) => {
+      edges.push({
+        id: `flow-${edges.length}`,
+        source: e.source,
+        target: e.target,
+        type: e.type,
+        label: e.count > 1 ? `${e.count} calls` : undefined,
+      });
+    });
+    return edges;
+  } catch {
+    return [];
+  }
+}
+
+// Infer hosting relationships between infra and services
+function inferHosting(nodes: GraphNode[], edges: GraphEdge[]): void {
+  const infraNodes = nodes.filter((n) => n.layer === "infra");
+  const serviceTypes = new Set(["queue", "database", "backend"]);
+
+  // Build a map of edges for lookup
+  const edgeMap = new Map<string, Set<string>>();
+  for (const edge of edges) {
+    if (!edgeMap.has(edge.source)) edgeMap.set(edge.source, new Set());
+    edgeMap.get(edge.source)!.add(edge.target);
+  }
+
+  // Known hosting patterns — only match core services, not npm client libraries
+  // Use exact name matches or type-restricted patterns to avoid over-matching
+  const hostingPatterns: Record<string, { names: string[]; types: Set<string> }> = {
+    railway: { names: ["bullmq", "redis", "pg", "postgres"], types: new Set(["database", "queue", "service"]) },
+    vercel: { names: ["next", "next.js", "nextjs"], types: new Set(["framework", "service"]) },
+    heroku: { names: ["redis", "pg", "postgres"], types: new Set(["database", "queue", "service"]) },
+    render: { names: ["redis", "pg", "postgres"], types: new Set(["database", "queue", "service"]) },
+  };
+
+  for (const infra of infraNodes) {
+    const infraKey = infra.name.toLowerCase();
+    const pattern = hostingPatterns[infraKey];
+    if (!pattern) continue;
+
+    for (const node of nodes) {
+      if (node.id === infra.id) continue;
+      if (!serviceTypes.has(node.layer) && node.layer !== "frontend") continue;
+      // Only match if node type is in the allowed set
+      if (!pattern.types.has(node.type)) continue;
+
+      const nameKey = node.name.toLowerCase();
+      const matches = pattern.names.some((p) => nameKey === p || nameKey.includes(p));
+
+      if (matches) {
+        node.hostedBy = infra.id;
+        if (!infra.hosts) infra.hosts = [];
+        infra.hosts.push(node.id);
+      }
+    }
+  }
+}
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const refresh = searchParams.get("refresh") === "true";
+  const projectPath = searchParams.get("path");
+  const cacheKey = projectPath || "__default__";
+  const cached = graphCache.get(cacheKey);
+
+  if (!refresh && cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return NextResponse.json({ success: true, data: cached.data, source: "cache" });
+  }
+
+  try {
+    const basePath = projectPath
+      || process.env.NAVGATOR_PROJECT_PATH
+      || process.cwd();
+    const graphPath = path.join(basePath, ".claude", "architecture", "graph.json");
+    const componentsDir = path.join(basePath, ".claude", "architecture", "components");
+
+    const content = await fs.readFile(graphPath, "utf-8");
+    const graph = JSON.parse(content);
+
+    // Enrich nodes with component details
+    const enrichedNodes: GraphNode[] = await Promise.all(
+      (graph.nodes as GraphNode[]).map(async (node) => {
+        try {
+          const files = await fs.readdir(componentsDir);
+          const compFile = files.find((f) => f.startsWith(node.id) && f.endsWith(".json"));
+          if (compFile) {
+            const compContent = await fs.readFile(path.join(componentsDir, compFile), "utf-8");
+            const comp = JSON.parse(compContent);
+            return {
+              ...node,
+              version: comp.version || undefined,
+              purpose: comp.role?.purpose || undefined,
+              configFiles: comp.source?.config_files || undefined,
+              tags: comp.tags || undefined,
+              connectsTo: comp.connects_to || undefined,
+              connectedFrom: comp.connected_from || undefined,
+            };
+          }
+        } catch {
+          // Component file not found, use base node
+        }
+        return node;
+      })
+    );
+
+    // Infer hosting relationships
+    inferHosting(enrichedNodes, graph.edges);
+
+    // Derive inter-node flow edges from connection files
+    const connectionsDir = path.join(basePath, ".claude", "architecture", "connections");
+    const flowEdges = await deriveFlowEdges(connectionsDir, enrichedNodes);
+
+    const data = {
+      nodes: enrichedNodes,
+      edges: [...graph.edges, ...flowEdges],
+      metadata: graph.metadata,
+    };
+
+    graphCache.set(cacheKey, { data, timestamp: Date.now() });
+
+    return NextResponse.json({ success: true, data, source: "scan" });
+  } catch {
+    return NextResponse.json(
+      { success: false, error: "No graph data found. Run a scan first.", data: null },
+      { status: 200 }
+    );
+  }
+}