microservice-kg 0.1.0

package/src/cli.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import process from "node:process";
+import { analyzeWorkspace, writeGraphArtifacts } from "./analyzer.mjs";
+
+function printUsage() {
+  console.log(`Usage:
+  microservice-kg analyze <input-directory> [--output <output-directory>]
+
+Examples:
+  microservice-kg analyze /Users/me/workspace/services
+  microservice-kg analyze /Users/me/workspace/services --output /tmp/service-kg
+`);
+}
+
+function parseArgs(argv) {
+  const [, , command, maybeInput, ...rest] = argv;
+  if (!command || command === "--help" || command === "-h") {
+    return { help: true };
+  }
+
+  const options = {
+    command,
+    inputDir: maybeInput,
+    outputDir: null,
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (token === "--output" || token === "-o") {
+      options.outputDir = rest[index + 1];
+      index += 1;
+    }
+  }
+
+  return options;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help || !args.command) {
+    printUsage();
+    process.exit(args.help ? 0 : 1);
+  }
+
+  if (args.command !== "analyze" || !args.inputDir) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const inputDir = path.resolve(args.inputDir);
+  const outputDir = args.outputDir
+    ? path.resolve(args.outputDir)
+    : path.join(inputDir, ".microservice-kg");
+
+  const graph = await analyzeWorkspace(inputDir);
+  await writeGraphArtifacts(graph, outputDir);
+
+  console.log(`Analyzed workspace: ${inputDir}`);
+  console.log(`Discovered services: ${graph.serviceCount}`);
+  console.log(`Discovered service edges: ${graph.serviceEdges.length}`);
+  console.log(`Wrote graph to: ${path.join(outputDir, "service-graph.json")}`);
+  console.log(`Wrote summary to: ${path.join(outputDir, "summary.md")}`);
+}
+
+main().catch((error) => {
+  console.error(error?.stack || error?.message || String(error));
+  process.exit(1);
+});

package/src/export-obsidian.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function main() {
+  const [, , inputGraphPath, outputVaultPath] = process.argv;
+  if (!inputGraphPath || !outputVaultPath) {
+    console.error("Usage: node export-obsidian.mjs <service-graph.json> <output-vault>");
+    process.exit(1);
+  }
+
+  const graph = JSON.parse(await fs.readFile(path.resolve(inputGraphPath), "utf8"));
+  const vaultPath = path.resolve(outputVaultPath);
+  const servicesDir = path.join(vaultPath, "services");
+  const obsidianDir = path.join(vaultPath, ".obsidian");
+
+  await fs.rm(vaultPath, { recursive: true, force: true });
+  await fs.mkdir(servicesDir, { recursive: true });
+  await fs.mkdir(obsidianDir, { recursive: true });
+
+  const serviceMap = new Map();
+  for (const service of graph.services) {
+    if (!serviceMap.has(service.id)) {
+      serviceMap.set(service.id, {
+        id: service.id,
+        roots: new Set(),
+        endpointCount: 0,
+        clientCount: 0,
+        methodInteractionCount: 0,
+      });
+    }
+    const entry = serviceMap.get(service.id);
+    entry.roots.add(service.relativeRootDir || service.rootDir || service.id);
+    entry.endpointCount += service.endpoints?.length || 0;
+    entry.clientCount += service.clients?.length || 0;
+    entry.methodInteractionCount += service.methodInteractions?.length || 0;
+  }
+
+  const outgoingMap = new Map();
+  const incomingMap = new Map();
+  for (const edge of graph.serviceEdges) {
+    if (!outgoingMap.has(edge.sourceServiceId)) {
+      outgoingMap.set(edge.sourceServiceId, []);
+    }
+    outgoingMap.get(edge.sourceServiceId).push(edge);
+
+    if (!incomingMap.has(edge.targetServiceId)) {
+      incomingMap.set(edge.targetServiceId, []);
+    }
+    incomingMap.get(edge.targetServiceId).push(edge);
+  }
+
+  const notePathByServiceId = new Map();
+  for (const serviceId of Array.from(serviceMap.keys()).sort((a, b) => a.localeCompare(b))) {
+    notePathByServiceId.set(serviceId, `services/${serviceId}.md`);
+  }
+
+  const serviceIds = Array.from(serviceMap.keys()).sort((a, b) => a.localeCompare(b));
+  for (const serviceId of serviceIds) {
+    const entry = serviceMap.get(serviceId);
+    const outgoing = (outgoingMap.get(serviceId) || []).sort((a, b) => a.targetServiceId.localeCompare(b.targetServiceId));
+    const incoming = (incomingMap.get(serviceId) || []).sort((a, b) => a.sourceServiceId.localeCompare(b.sourceServiceId));
+    const lines = [
+      `# ${serviceId}`,
+      "",
+      "## Service",
+      "",
+      `- Logical service id: \`${serviceId}\``,
+      `- Roots: ${Array.from(entry.roots).sort((a, b) => a.localeCompare(b)).map((root) => `\`${root}\``).join(", ")}`,
+      `- Endpoints discovered: ${entry.endpointCount}`,
+      `- Clients discovered: ${entry.clientCount}`,
+      `- Method interactions discovered: ${entry.methodInteractionCount}`,
+      "",
+      "## Outgoing",
+      "",
+    ];
+
+    if (outgoing.length === 0) {
+      lines.push("- None", "");
+    } else {
+      for (const edge of outgoing) {
+        const targetLink = linkToService(edge.targetServiceId, notePathByServiceId);
+        lines.push(`- ${targetLink}`);
+        for (const call of edge.calls.slice(0, 8)) {
+          lines.push(`  - \`${call.httpMethod}\` \`${call.path}\``);
+          lines.push(`  - client: \`${call.sourceClassName}.${call.sourceMethodName}\``);
+          if (call.provider) {
+            lines.push(`  - provider: \`${call.provider.targetClassName}.${call.provider.targetMethodName}\``);
+          }
+        }
+      }
+      lines.push("");
+    }
+
+    lines.push("## Incoming", "");
+    if (incoming.length === 0) {
+      lines.push("- None", "");
+    } else {
+      for (const edge of incoming) {
+        lines.push(`- ${linkToService(edge.sourceServiceId, notePathByServiceId)}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("## Notes", "", "- Graph view shows logical service-to-service links from these markdown references.");
+
+    await fs.writeFile(
+      path.join(vaultPath, notePathByServiceId.get(serviceId)),
+      `${lines.join("\n")}\n`,
+      "utf8",
+    );
+  }
+
+  const indexLines = [
+    "# Microservice KG",
+    "",
+    `- Generated at: ${graph.generatedAt}`,
+    `- Input directory: \`${graph.inputDir}\``,
+    `- Logical services: ${serviceIds.length}`,
+    `- Service edges: ${graph.serviceEdges.length}`,
+    "",
+    "## Services",
+    "",
+    ...serviceIds.map((serviceId) => `- ${linkToService(serviceId, notePathByServiceId)}`),
+  ];
+
+  await fs.writeFile(path.join(vaultPath, "INDEX.md"), `${indexLines.join("\n")}\n`, "utf8");
+
+  const corePlugins = [
+    "file-explorer",
+    "graph",
+    "markdown-importer",
+    "outline",
+    "search",
+    "switcher",
+  ];
+
+  await fs.writeFile(
+    path.join(obsidianDir, "core-plugins.json"),
+    `${JSON.stringify(corePlugins, null, 2)}\n`,
+    "utf8",
+  );
+
+  await fs.writeFile(
+    path.join(obsidianDir, "graph.json"),
+    `${JSON.stringify({
+      "collapse-filter": false,
+      search: "",
+      showTags: false,
+      showAttachments: false,
+      showExistingOnly: true,
+      localJumps: false,
+      colorGroups: [],
+    }, null, 2)}\n`,
+    "utf8",
+  );
+
+  await fs.writeFile(
+    path.join(obsidianDir, "workspace.json"),
+    `${JSON.stringify({
+      main: {
+        id: "main",
+        type: "split",
+        children: [
+          {
+            id: "graph-leaf",
+            type: "leaf",
+            state: {
+              type: "graph",
+              state: {},
+            },
+          },
+        ],
+        direction: "vertical",
+      },
+      left: {
+        id: "left",
+        type: "split",
+        children: [
+          {
+            id: "left-tabs",
+            type: "tabs",
+            children: [
+              {
+                id: "file-explorer",
+                type: "leaf",
+                state: {
+                  type: "file-explorer",
+                  state: {},
+                },
+              },
+            ],
+          },
+        ],
+        direction: "horizontal",
+        width: 300,
+      },
+      right: {
+        id: "right",
+        type: "split",
+        children: [],
+        direction: "horizontal",
+        width: 300,
+      },
+      active: "graph-leaf",
+      lastOpenFiles: ["INDEX.md"],
+    }, null, 2)}\n`,
+    "utf8",
+  );
+
+  console.log(`Created Obsidian vault at ${vaultPath}`);
+  console.log(`Logical services: ${serviceIds.length}`);
+  console.log(`Service edges: ${graph.serviceEdges.length}`);
+}
+
+function linkToService(serviceId, notePathByServiceId) {
+  const notePath = notePathByServiceId.get(serviceId);
+  const basename = path.basename(notePath, ".md");
+  return `[[${basename}]]`;
+}
+
+main().catch((error) => {
+  console.error(error?.stack || error?.message || String(error));
+  process.exit(1);
+});

package/src/graph-query.mjs

@@ -0,0 +1,292 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { analyzeWorkspace, writeGraphArtifacts } from "./analyzer.mjs";
+
+export class GraphStore {
+  constructor(options = {}) {
+    this.defaultGraphPath = options.defaultGraphPath || null;
+    this.graph = null;
+    this.graphPath = null;
+  }
+
+  async loadGraph(graphPath = this.defaultGraphPath) {
+    if (!graphPath) {
+      throw new Error("No graph path configured");
+    }
+    const resolvedPath = path.resolve(graphPath);
+    const graph = JSON.parse(await fs.readFile(resolvedPath, "utf8"));
+    this.graph = graph;
+    this.graphPath = resolvedPath;
+    return graph;
+  }
+
+  async ensureGraph() {
+    if (this.graph) {
+      return this.graph;
+    }
+    return this.loadGraph();
+  }
+
+  async analyzeAndLoad({ inputDir, outputDir }) {
+    const resolvedInput = path.resolve(inputDir);
+    const resolvedOutput = outputDir
+      ? path.resolve(outputDir)
+      : path.join(resolvedInput, ".microservice-kg");
+    const graph = await analyzeWorkspace(resolvedInput);
+    await writeGraphArtifacts(graph, resolvedOutput);
+    const graphPath = path.join(resolvedOutput, "service-graph.json");
+    this.graph = graph;
+    this.graphPath = graphPath;
+    return {
+      inputDir: resolvedInput,
+      outputDir: resolvedOutput,
+      graphPath,
+      serviceCount: graph.serviceCount,
+      edgeCount: graph.serviceEdges.length,
+    };
+  }
+}
+
+export async function listServices(store, { includeStats = true } = {}) {
+  const graph = await store.ensureGraph();
+  const grouped = groupServices(graph);
+  const results = Object.values(grouped)
+    .sort((left, right) => left.id.localeCompare(right.id))
+    .map((service) => {
+      const base = {
+        id: service.id,
+        name: service.id,
+        roots: service.roots.sort((a, b) => a.localeCompare(b)),
+      };
+      if (!includeStats) {
+        return base;
+      }
+      return {
+        ...base,
+        endpointCount: service.endpointCount,
+        clientCount: service.clientCount,
+        methodInteractionCount: service.methodInteractionCount,
+        outgoingServices: uniqueSorted(
+          graph.serviceEdges
+            .filter((edge) => edge.sourceServiceId === service.id)
+            .map((edge) => edge.targetServiceId),
+        ),
+        incomingServices: uniqueSorted(
+          graph.serviceEdges
+            .filter((edge) => edge.targetServiceId === service.id)
+            .map((edge) => edge.sourceServiceId),
+        ),
+      };
+    });
+
+  return {
+    graphPath: store.graphPath,
+    serviceCount: results.length,
+    services: results,
+  };
+}
+
+export async function getServiceContext(store, { serviceId }) {
+  const graph = await store.ensureGraph();
+  const grouped = groupServices(graph);
+  const service = grouped[serviceId];
+  if (!service) {
+    throw new Error(`Unknown service: ${serviceId}`);
+  }
+
+  const outgoing = graph.serviceEdges
+    .filter((edge) => edge.sourceServiceId === serviceId)
+    .map(summarizeEdge);
+  const incoming = graph.serviceEdges
+    .filter((edge) => edge.targetServiceId === serviceId)
+    .map(summarizeEdge);
+
+  return {
+    service: {
+      id: service.id,
+      roots: service.roots.sort((a, b) => a.localeCompare(b)),
+      endpointCount: service.endpointCount,
+      clientCount: service.clientCount,
+      methodInteractionCount: service.methodInteractionCount,
+    },
+    outgoing,
+    incoming,
+  };
+}
+
+export async function getEdgeDetails(store, { sourceServiceId, targetServiceId }) {
+  const graph = await store.ensureGraph();
+  const edge = graph.serviceEdges.find(
+    (candidate) =>
+      candidate.sourceServiceId === sourceServiceId
+      && candidate.targetServiceId === targetServiceId,
+  );
+  if (!edge) {
+    throw new Error(`Unknown edge: ${sourceServiceId} -> ${targetServiceId}`);
+  }
+
+  return {
+    id: edge.id,
+    sourceServiceId: edge.sourceServiceId,
+    targetServiceId: edge.targetServiceId,
+    protocol: edge.protocol,
+    reasons: edge.reasons,
+    calls: edge.calls,
+  };
+}
+
+export async function getDependencyPath(
+  store,
+  { sourceServiceId, targetServiceId, maxDepth, direction = "downstream" },
+) {
+  const graph = await store.ensureGraph();
+  const effectiveMaxDepth = normalizeMaxDepth(maxDepth, graph);
+  const adjacency = buildAdjacency(graph, direction);
+  const queue = [{ node: sourceServiceId, path: [sourceServiceId] }];
+  const visited = new Set([sourceServiceId]);
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current.node === targetServiceId) {
+      return {
+        found: true,
+        direction,
+        path: current.path,
+        depth: current.path.length - 1,
+        maxDepth: effectiveMaxDepth,
+      };
+    }
+
+    if (current.path.length - 1 >= effectiveMaxDepth) {
+      continue;
+    }
+
+    for (const neighbor of adjacency.get(current.node) || []) {
+      if (visited.has(neighbor)) {
+        continue;
+      }
+      visited.add(neighbor);
+      queue.push({
+        node: neighbor,
+        path: [...current.path, neighbor],
+      });
+    }
+  }
+
+  return {
+    found: false,
+    direction,
+    path: [],
+    depth: null,
+    maxDepth: effectiveMaxDepth,
+  };
+}
+
+export async function getServiceImpact(
+  store,
+  { serviceId, direction = "downstream", maxDepth },
+) {
+  const graph = await store.ensureGraph();
+  const effectiveMaxDepth = normalizeMaxDepth(maxDepth, graph);
+  const adjacency = buildAdjacency(graph, direction);
+  const queue = [{ node: serviceId, depth: 0 }];
+  const visited = new Set([serviceId]);
+  const results = [];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current.depth >= effectiveMaxDepth) {
+      continue;
+    }
+
+    for (const neighbor of adjacency.get(current.node) || []) {
+      if (visited.has(neighbor)) {
+        continue;
+      }
+      visited.add(neighbor);
+      const nextDepth = current.depth + 1;
+      results.push({
+        serviceId: neighbor,
+        depth: nextDepth,
+      });
+      queue.push({
+        node: neighbor,
+        depth: nextDepth,
+      });
+    }
+  }
+
+  return {
+    serviceId,
+    direction,
+    maxDepth: effectiveMaxDepth,
+    impactedServices: results.sort(
+      (left, right) => left.depth - right.depth || left.serviceId.localeCompare(right.serviceId),
+    ),
+  };
+}
+
+function summarizeEdge(edge) {
+  return {
+    id: edge.id,
+    sourceServiceId: edge.sourceServiceId,
+    targetServiceId: edge.targetServiceId,
+    protocol: edge.protocol,
+    clientClasses: uniqueSorted(edge.reasons.map((reason) => reason.clientClassName)),
+    callCount: edge.calls.length,
+  };
+}
+
+function buildAdjacency(graph, direction) {
+  const adjacency = new Map();
+  const ids = uniqueSorted(graph.services.map((service) => service.id));
+  for (const id of ids) {
+    adjacency.set(id, new Set());
+  }
+
+  for (const edge of graph.serviceEdges) {
+    if (direction === "upstream") {
+      adjacency.get(edge.targetServiceId)?.add(edge.sourceServiceId);
+    } else {
+      adjacency.get(edge.sourceServiceId)?.add(edge.targetServiceId);
+    }
+  }
+
+  return adjacency;
+}
+
+function groupServices(graph) {
+  const grouped = {};
+  for (const service of graph.services) {
+    if (!grouped[service.id]) {
+      grouped[service.id] = {
+        id: service.id,
+        roots: [],
+        endpointCount: 0,
+        clientCount: 0,
+        methodInteractionCount: 0,
+      };
+    }
+    grouped[service.id].roots.push(service.relativeRootDir || service.rootDir || service.id);
+    grouped[service.id].endpointCount += service.endpoints?.length || 0;
+    grouped[service.id].clientCount += service.clients?.length || 0;
+    grouped[service.id].methodInteractionCount += service.methodInteractions?.length || 0;
+  }
+  return grouped;
+}
+
+function uniqueSorted(values) {
+  return Array.from(new Set(values.filter(Boolean))).sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeMaxDepth(value, graph) {
+  const graphWideDepth = Math.max(1, uniqueSorted(graph.services.map((service) => service.id)).length);
+  if (value === undefined || value === null || value === "") {
+    return graphWideDepth;
+  }
+  const numericValue = Number(value);
+  if (!Number.isFinite(numericValue) || numericValue < 1) {
+    return graphWideDepth;
+  }
+  return Math.floor(numericValue);
+}