@lzehrung/codegraph 2.1.0

package/docs/graph-visualization/file-tree-filters.js

@@ -0,0 +1,50 @@
+/**
+ * Pure filter / presentation helpers for the file tree.
+ * No DOM dependency except `highlightMatch` which creates a DocumentFragment.
+ */
+
+export function kindAbbrev(kind) {
+  const map = { function: "fn", class: "cls", type: "ty", variable: "var", import: "imp" };
+  return map[kind] || (kind ? kind.slice(0, 3) : "?");
+}
+
+export function matchesFilter(name, filter) {
+  if (!filter) return true;
+  return name.toLowerCase().includes(filter.toLowerCase());
+}
+
+export function subtreeMatchesFilter(node, filter) {
+  if (!filter) return true;
+  if (matchesFilter(node.name, filter)) return true;
+  if (node.type === "directory" && node.children) {
+    return node.children.some((c) => subtreeMatchesFilter(c, filter));
+  }
+  if (node.type === "file" && node.symbols) {
+    return node.symbols.some((s) => matchesFilter(s.name, filter));
+  }
+  return false;
+}
+
+/**
+ * Create a DOM fragment that wraps the first occurrence of `filter` in a
+ * `<mark>` element.  Returns a plain TextNode when there is no match or no
+ * filter.
+ *
+ * NOTE: this is the only function in the module that touches the DOM.
+ */
+export function highlightMatch(text, filter) {
+  if (!filter) return document.createTextNode(text);
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(filter.toLowerCase());
+  if (idx < 0) return document.createTextNode(text);
+
+  const frag = document.createDocumentFragment();
+  if (idx > 0) frag.appendChild(document.createTextNode(text.slice(0, idx)));
+  const mark = document.createElement("mark");
+  mark.textContent = text.slice(idx, idx + filter.length);
+  frag.appendChild(mark);
+  if (idx + filter.length < text.length) {
+    frag.appendChild(document.createTextNode(text.slice(idx + filter.length)));
+  }
+  return frag;
+}

package/docs/graph-visualization/file-tree-model.js

@@ -0,0 +1,186 @@
+/**
+ * Pure data-structure functions for building and querying the file tree.
+ * No DOM dependency -- safe to import from tests or workers.
+ */
+
+export function findCommonPrefix(paths) {
+  if (!paths.length) return "";
+  const normalized = paths.map((p) => p.replace(/\\/g, "/"));
+  const first = normalized[0];
+  let prefixEnd = 0;
+  for (let i = 0; i < first.length; i++) {
+    if (normalized.every((p) => p[i] === first[i])) {
+      if (first[i] === "/") prefixEnd = i + 1;
+    } else {
+      break;
+    }
+  }
+  return first.slice(0, prefixEnd);
+}
+
+/**
+ * Build a hierarchical tree from a codegraph payload.
+ *
+ * Returns `{ root, itemsByKey }` where `itemsByKey` is a Map<string, TreeItem>
+ * for O(1) lookups by graphKey.
+ */
+export function buildFileTree(payload) {
+  const files = payload.files || payload.nodes || [];
+  const isCompact = Array.isArray(payload.files);
+  const stringFiles = files.filter((f) => typeof f === "string");
+  const prefix = findCommonPrefix(stringFiles);
+
+  const root = { name: "", type: "directory", children: [], expanded: true, parent: null };
+  const itemsByKey = new Map();
+
+  const symbolsByFile = new Map();
+  if (isCompact && Array.isArray(payload.symbols)) {
+    payload.symbols.forEach((s, idx) => {
+      if (!s) return;
+      let list = symbolsByFile.get(s.file);
+      if (!list) {
+        list = [];
+        symbolsByFile.set(s.file, list);
+      }
+      list.push({
+        name: s.name || payload.symbolIdIndex?.[idx] || `symbol_${idx}`,
+        type: "symbol",
+        kind: s.kind || "variable",
+        symbolIndex: idx,
+        graphKey: `s:${idx}`,
+        fullId: payload.symbolIdIndex?.[idx] || s.name,
+        parent: null,
+      });
+    });
+  }
+
+  for (let i = 0; i < files.length; i++) {
+    const filePath = files[i];
+    if (typeof filePath !== "string") continue;
+
+    const relative = filePath.replace(/\\/g, "/").slice(prefix.length);
+    const parts = relative.split("/").filter(Boolean);
+    let current = root;
+
+    for (let j = 0; j < parts.length - 1; j++) {
+      let dir = current.children.find((c) => c.type === "directory" && c.name === parts[j]);
+      if (!dir) {
+        dir = {
+          name: parts[j],
+          type: "directory",
+          children: [],
+          expanded: false,
+          parent: current,
+        };
+        current.children.push(dir);
+      }
+      current = dir;
+    }
+
+    const fileName = parts[parts.length - 1] || filePath;
+    const graphKey = isCompact ? `f:${i}` : filePath;
+
+    const symbols = symbolsByFile.get(i) || [];
+
+    const fileNode = {
+      name: fileName,
+      type: "file",
+      fileIndex: i,
+      graphKey,
+      fullPath: filePath,
+      symbols,
+      expanded: false,
+      parent: current,
+    };
+
+    symbols.forEach((s) => {
+      s.parent = fileNode;
+      itemsByKey.set(s.graphKey, s);
+    });
+    current.children.push(fileNode);
+    itemsByKey.set(graphKey, fileNode);
+  }
+
+  sortTree(root);
+  autoExpandSingleChildren(root);
+  return { root, itemsByKey };
+}
+
+export function sortTree(node) {
+  if (!node.children) return;
+  node.children.sort((a, b) => {
+    if (a.type === "directory" && b.type !== "directory") return -1;
+    if (a.type !== "directory" && b.type === "directory") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  node.children.forEach(sortTree);
+}
+
+export function autoExpandSingleChildren(node) {
+  if (node.type !== "directory") return;
+  const dirChildren = node.children.filter((c) => c.type === "directory");
+  if (node.children.length === 1 && dirChildren.length === 1) {
+    node.expanded = true;
+    autoExpandSingleChildren(node.children[0]);
+  }
+}
+
+/**
+ * Build index maps for O(1) edge lookups by source or target index.
+ *
+ * Returns `{ fileEdgesByFrom, fileEdgesByTo, symbolEdgesByFrom, symbolEdgesByTo }`
+ * where each value is a `Map<number, Edge[]>`.
+ */
+export function buildEdgeIndexes(payload) {
+  const fileEdgesByFrom = new Map();
+  const fileEdgesByTo = new Map();
+  const symbolEdgesByFrom = new Map();
+  const symbolEdgesByTo = new Map();
+
+  if (Array.isArray(payload.fileEdges)) {
+    for (const edge of payload.fileEdges) {
+      if (!edge || typeof edge !== "object") continue;
+      if (typeof edge.from === "number") {
+        let list = fileEdgesByFrom.get(edge.from);
+        if (!list) {
+          list = [];
+          fileEdgesByFrom.set(edge.from, list);
+        }
+        list.push(edge);
+      }
+      const to = edge.to;
+      if (to && typeof to === "object" && to.type === "file" && typeof to.path === "number") {
+        let list = fileEdgesByTo.get(to.path);
+        if (!list) {
+          list = [];
+          fileEdgesByTo.set(to.path, list);
+        }
+        list.push(edge);
+      }
+    }
+  }
+
+  if (Array.isArray(payload.symbolEdges)) {
+    for (const edge of payload.symbolEdges) {
+      if (!edge || typeof edge !== "object") continue;
+      if (typeof edge.from === "number") {
+        let list = symbolEdgesByFrom.get(edge.from);
+        if (!list) {
+          list = [];
+          symbolEdgesByFrom.set(edge.from, list);
+        }
+        list.push(edge);
+      }
+      if (typeof edge.to === "number") {
+        let list = symbolEdgesByTo.get(edge.to);
+        if (!list) {
+          list = [];
+          symbolEdgesByTo.set(edge.to, list);
+        }
+        list.push(edge);
+      }
+    }
+  }
+
+  return { fileEdgesByFrom, fileEdgesByTo, symbolEdgesByFrom, symbolEdgesByTo };
+}

package/docs/graph-visualization/graph-builder.js

@@ -0,0 +1,303 @@
+import Graph from "./vendor/graphology.js";
+import forceAtlas2 from "./vendor/graphology-layout-forceatlas2.js";
+
+export const FILE_NODE_COLOR = "#4da3ff";
+export const EXTERNAL_NODE_COLOR = "#f59e0b";
+export const SYMBOL_NODE_COLOR = "#6ee7b7";
+
+const MAX_LABEL_LENGTH = 28;
+
+export function shortLabel(pathOrName) {
+  if (typeof pathOrName !== "string") return "";
+  const s = pathOrName.replace(/^ext:/, "");
+  const slash = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  const basename = slash >= 0 ? s.slice(slash + 1) : s;
+  if (basename.length <= MAX_LABEL_LENGTH) return basename;
+  return basename.slice(0, MAX_LABEL_LENGTH - 1) + "\u2026";
+}
+
+export function normalizeToKey(target) {
+  if (typeof target === "string") {
+    return { key: target, type: "file" };
+  }
+
+  if (target && typeof target === "object" && target.type === "file" && typeof target.path === "string") {
+    return { key: target.path, type: "file" };
+  }
+
+  if (target && typeof target === "object" && target.type === "external" && typeof target.name === "string") {
+    return { key: `ext:${target.name}`, type: "external" };
+  }
+
+  return null;
+}
+
+export function edgeKey(from, to) {
+  return `${from}->${to}`;
+}
+
+function addNodeIfMissing(graph, key, attributes) {
+  if (!graph.hasNode(key)) {
+    graph.addNode(key, attributes);
+  }
+}
+
+function seedNodeCoordinates(graph) {
+  const order = graph.order;
+  if (order === 0) return;
+
+  const radius = Math.max(10, order / 2);
+  let index = 0;
+  graph.forEachNode((node) => {
+    const angle = (index / order) * Math.PI * 2;
+    graph.setNodeAttribute(node, "x", Math.cos(angle) * radius);
+    graph.setNodeAttribute(node, "y", Math.sin(angle) * radius);
+    index += 1;
+  });
+}
+
+function applyLayout(graph) {
+  if (graph.order === 0) return;
+  // Skip heavy layout in typical test environments to keep unit tests fast.
+  if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "test") {
+    return;
+  }
+  // Allow overriding or disabling layout via a global configuration.
+  let iterations = 500;
+  if (typeof globalThis !== "undefined" && globalThis.GRAPH_LAYOUT_ITERATIONS != null) {
+    const configured = Number(globalThis.GRAPH_LAYOUT_ITERATIONS);
+    if (Number.isFinite(configured)) {
+      iterations = configured;
+    }
+  }
+  if (iterations <= 0) {
+    // Non-positive iteration count disables layout.
+    return;
+  }
+  seedNodeCoordinates(graph);
+
+  forceAtlas2.assign(graph, {
+    iterations,
+    settings: {
+      gravity: 0.8,
+      scalingRatio: 25,
+      strongGravityMode: false,
+      barnesHutOptimize: true,
+      slowDown: 1,
+      linLogMode: true,
+      outboundAttractionDistribution: true,
+    },
+  });
+}
+
+function compactIndex(value, indexes, upperBound) {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value < upperBound) {
+    return value;
+  }
+  if (typeof value === "string") return indexes.get(value);
+  return undefined;
+}
+
+export function normalizeGraphPayload(payload) {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.files)) return payload;
+  const sourceFileEdges = Array.isArray(payload.fileEdges) ? payload.fileEdges : [];
+  const sourceSymbols = Array.isArray(payload.symbols) ? payload.symbols : [];
+  const sourceSymbolEdges = Array.isArray(payload.symbolEdges) ? payload.symbolEdges : [];
+  const portable =
+    payload.format === "codegraph.graph-json" ||
+    sourceFileEdges.some((edge) => typeof edge?.from === "string") ||
+    sourceSymbols.some((symbol) => typeof symbol?.file === "string");
+  if (!portable) return payload;
+
+  const fileIndexes = new Map();
+  payload.files.forEach((file, index) => {
+    if (typeof file === "string") fileIndexes.set(file, index);
+  });
+
+  const fileEdges = [];
+  for (const edge of sourceFileEdges) {
+    if (!edge || typeof edge !== "object") continue;
+    const from = compactIndex(edge.from, fileIndexes, payload.files.length);
+    if (from === undefined || !edge.to || typeof edge.to !== "object") continue;
+    if (edge.to.type === "file") {
+      const target = compactIndex(edge.to.path, fileIndexes, payload.files.length);
+      if (target !== undefined) fileEdges.push({ ...edge, from, to: { type: "file", path: target } });
+      continue;
+    }
+    if (edge.to.type === "external" && typeof edge.to.name === "string") {
+      fileEdges.push({ ...edge, from, to: { type: "external", name: edge.to.name } });
+    }
+  }
+
+  const symbols = [];
+  const symbolIdIndex = [];
+  const symbolIndexes = new Map();
+  for (let sourceIndex = 0; sourceIndex < sourceSymbols.length; sourceIndex += 1) {
+    const symbol = sourceSymbols[sourceIndex];
+    if (!symbol || typeof symbol !== "object") continue;
+    const file = compactIndex(symbol.file, fileIndexes, payload.files.length);
+    if (file === undefined) continue;
+    const index = symbols.length;
+    const id = typeof symbol.id === "string" ? symbol.id : (payload.symbolIdIndex?.[sourceIndex] ?? symbol.name);
+    symbols.push({ ...symbol, file });
+    symbolIdIndex.push(id);
+    if (typeof id === "string") symbolIndexes.set(id, index);
+  }
+
+  const symbolEdges = [];
+  for (const edge of sourceSymbolEdges) {
+    if (!edge || typeof edge !== "object") continue;
+    const from = compactIndex(edge.from, symbolIndexes, symbols.length);
+    const to = compactIndex(edge.to, symbolIndexes, symbols.length);
+    if (from !== undefined && to !== undefined) symbolEdges.push({ ...edge, from, to });
+  }
+
+  return { ...payload, fileEdges, symbols, symbolEdges, symbolIdIndex };
+}
+
+export function buildGraph(payload, options) {
+  payload = normalizeGraphPayload(payload);
+  const graph = new Graph({ multi: false, type: "directed" });
+
+  if (Array.isArray(payload.nodes) && Array.isArray(payload.edges)) {
+    for (const node of payload.nodes) {
+      if (typeof node !== "string") continue;
+      addNodeIfMissing(graph, node, {
+        label: shortLabel(node),
+        fullLabel: node,
+        size: 6,
+        color: FILE_NODE_COLOR,
+        kind: "file",
+      });
+    }
+
+    for (const edge of payload.edges) {
+      if (!edge || typeof edge !== "object" || typeof edge.from !== "string") continue;
+      const target = normalizeToKey(edge.to);
+      if (!target) continue;
+      const isExternalNode = target.type === "external";
+      if (isExternalNode && !options.showExternal) continue;
+
+      addNodeIfMissing(graph, edge.from, {
+        label: shortLabel(edge.from),
+        fullLabel: edge.from,
+        size: 6,
+        color: FILE_NODE_COLOR,
+        kind: "file",
+      });
+
+      addNodeIfMissing(graph, target.key, {
+        label: shortLabel(target.key),
+        fullLabel: target.key,
+        size: isExternalNode ? 4 : 6,
+        color: isExternalNode ? EXTERNAL_NODE_COLOR : FILE_NODE_COLOR,
+        kind: target.type,
+      });
+
+      const key = edgeKey(edge.from, target.key);
+      if (!graph.hasEdge(key)) {
+        graph.addDirectedEdgeWithKey(key, edge.from, target.key, {
+          label: typeof edge.raw === "string" ? edge.raw : "",
+        });
+      }
+    }
+  } else if (Array.isArray(payload.files) && Array.isArray(payload.fileEdges)) {
+    payload.files.forEach((file, index) => {
+      if (typeof file !== "string") return;
+      addNodeIfMissing(graph, `f:${index}`, {
+        label: shortLabel(file),
+        fullLabel: file,
+        size: 6,
+        color: FILE_NODE_COLOR,
+        kind: "file",
+      });
+    });
+
+    for (const fileEdge of payload.fileEdges) {
+      if (!fileEdge || typeof fileEdge !== "object" || typeof fileEdge.from !== "number") continue;
+      const fromKey = `f:${fileEdge.from}`;
+      if (!graph.hasNode(fromKey)) continue;
+      const to = fileEdge.to;
+      if (!to || typeof to !== "object") continue;
+
+      if (to.type === "file" && typeof to.path === "number") {
+        const toKey = `f:${to.path}`;
+        if (!graph.hasNode(toKey)) continue;
+        const key = edgeKey(fromKey, toKey);
+        if (!graph.hasEdge(key)) {
+          graph.addDirectedEdgeWithKey(key, fromKey, toKey, {
+            label: typeof fileEdge.raw === "string" ? fileEdge.raw : "",
+          });
+        }
+      }
+
+      if (to.type === "external" && typeof to.name === "string" && options.showExternal) {
+        const externalKey = `ext:${to.name}`;
+        addNodeIfMissing(graph, externalKey, {
+          label: shortLabel(to.name),
+          fullLabel: to.name,
+          size: 4,
+          color: EXTERNAL_NODE_COLOR,
+          kind: "external",
+        });
+        const key = edgeKey(fromKey, externalKey);
+        if (!graph.hasEdge(key)) {
+          graph.addDirectedEdgeWithKey(key, fromKey, externalKey, {
+            label: typeof fileEdge.raw === "string" ? fileEdge.raw : "",
+          });
+        }
+      }
+    }
+
+    const hasSymbols = Array.isArray(payload.symbols) && Array.isArray(payload.symbolEdges);
+    const symbolIdIndex = Array.isArray(payload.symbolIdIndex) ? payload.symbolIdIndex : null;
+
+    if (options.includeSymbols && hasSymbols) {
+      payload.symbols.forEach((symbol, index) => {
+        if (!symbol || typeof symbol !== "object" || typeof symbol.file !== "number") return;
+        const parentFileKey = `f:${symbol.file}`;
+        if (!graph.hasNode(parentFileKey)) return;
+        const symbolKey = `s:${index}`;
+        const rawName = typeof symbol.name === "string" ? symbol.name : (symbolIdIndex?.[index] ?? symbolKey);
+        const symbolLabel = shortLabel(rawName) || symbolKey;
+        addNodeIfMissing(graph, symbolKey, {
+          label: symbolLabel,
+          fullLabel: rawName,
+          size: 4,
+          color: SYMBOL_NODE_COLOR,
+          kind: "symbol",
+        });
+        const containsEdge = edgeKey(parentFileKey, symbolKey);
+        if (!graph.hasEdge(containsEdge)) {
+          graph.addDirectedEdgeWithKey(containsEdge, parentFileKey, symbolKey, { label: "contains" });
+        }
+      });
+
+      payload.symbolEdges.forEach((symbolEdge) => {
+        if (!symbolEdge || typeof symbolEdge !== "object") return;
+        if (typeof symbolEdge.from !== "number" || typeof symbolEdge.to !== "number") return;
+        const fromKey = `s:${symbolEdge.from}`;
+        const toKey = `s:${symbolEdge.to}`;
+        if (!graph.hasNode(fromKey) || !graph.hasNode(toKey)) return;
+        const key = edgeKey(fromKey, toKey);
+        if (!graph.hasEdge(key)) {
+          graph.addDirectedEdgeWithKey(key, fromKey, toKey, {
+            label: typeof symbolEdge.label === "string" ? symbolEdge.label : "uses",
+          });
+        }
+      });
+    }
+  } else {
+    throw new Error("Unsupported graph payload. Expected graph --json output.");
+  }
+
+  graph.forEachNode((node) => {
+    const degree = graph.degree(node);
+    const current = graph.getNodeAttribute(node, "size") ?? 6;
+    const size = Math.min(12, Math.max(current, 3 + Math.log2(degree + 1)));
+    graph.setNodeAttribute(node, "size", size);
+  });
+
+  applyLayout(graph);
+  return graph;
+}

package/docs/graph-visualization/index.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Codegraph Project Viewer</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="app-shell">
+      <aside class="sidebar">
+        <header>
+          <h1>Codegraph Project Viewer</h1>
+          <p>Explore the current project's dependencies and symbols.</p>
+        </header>
+
+        <section class="controls">
+          <label for="graph-file">Open exported graph JSON (optional)</label>
+          <input id="graph-file" type="file" accept="application/json" />
+
+          <div class="actions">
+            <button id="load-default" type="button">Reload project</button>
+            <button id="refresh" type="button">Apply filters</button>
+            <button id="reset-camera" type="button">Reset camera</button>
+          </div>
+
+          <label class="inline-control" for="show-external">
+            <input id="show-external" type="checkbox" />
+            Show external package nodes
+          </label>
+
+          <label class="inline-control" for="include-symbols">
+            <input id="include-symbols" type="checkbox" />
+            Include symbols when available (can be large)
+          </label>
+
+          <p id="status" role="status">Loading current project graph...</p>
+        </section>
+
+        <section class="tree-panel">
+          <div class="tree-toolbar">
+            <input id="tree-search" type="search" placeholder="Filter files and symbols..." autocomplete="off" />
+          </div>
+          <div id="file-tree" class="file-tree">
+            <p class="empty-state">Loading the project file tree...</p>
+          </div>
+        </section>
+
+        <section id="detail-panel" class="detail-panel hidden">
+          <div class="detail-header">
+            <span id="detail-title"></span>
+            <button id="detail-close" type="button" title="Close panel">&times;</button>
+          </div>
+          <div id="detail-content"></div>
+        </section>
+      </aside>
+
+      <section class="graph-panel">
+        <div id="graph-container" aria-label="Dependency graph visualization"></div>
+      </section>
+    </main>
+
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>