depwire-cli 0.6.2 → 0.7.1

package/README.md

@@ -40,8 +40,8 @@ Depwire fixes this by giving AI tools a complete dependency graph of your codeba
 - **Live graph, always current** — edit a file and the dependency map updates in real-time. No re-indexing, no waiting.
 - **Works locally, stays private** — zero cloud accounts, zero data leaving your machine. Just `npm install` and go.
 
-### 13 MCP Tools, Not Just Visualization
-Depwire isn't just a pretty graph. It's a full context engine with 13 tools that AI assistants call autonomously — architecture summaries, dependency tracing, symbol search, file context, health scores, and more. The AI decides which tool to use based on your question.
+### 14 MCP Tools, Not Just Visualization
+Depwire isn't just a pretty graph. It's a full context engine with 14 tools that AI assistants call autonomously — architecture summaries, dependency tracing, symbol search, file context, health scores, temporal evolution, and more. The AI decides which tool to use based on your question.
 
 ## Installation
 
@@ -66,10 +66,15 @@ depwire viz
 depwire parse
 depwire docs
 depwire health
+depwire temporal
 
 # Or specify a directory explicitly
 npx depwire-cli viz ./my-project
 npx depwire-cli parse ./my-project
+npx depwire-cli temporal ./my-project
+
+# Temporal visualization options
+npx depwire-cli temporal --commits 20 --strategy monthly --verbose --stats
 
 # Exclude test files and node_modules
 npx depwire-cli parse --exclude "**/*.test.*" "**/node_modules/**"
@@ -134,6 +139,7 @@ Settings → Features → Experimental → Enable MCP → Add Server:
 | `get_project_docs` | Retrieve auto-generated codebase documentation |
 | `update_project_docs` | Regenerate documentation on demand |
 | `get_health_score` | Get 0-100 dependency health score with recommendations |
+| `get_temporal_graph` | Show how the graph evolved over git history |
 
 ## Supported Languages
 
@@ -179,6 +185,41 @@ Opens an interactive arc diagram in your browser:
 - Export as SVG or PNG
 - **Port collision handling** — Automatically finds an available port if default is in use
 
+## Temporal Graph
+
+Visualize how your codebase architecture evolved over git history. Scrub through time with an interactive timeline slider.
+
+```bash
+# Auto-detects project root
+depwire temporal
+
+# Sample 20 commits with monthly snapshots
+depwire temporal --commits 20 --strategy monthly
+
+# Verbose mode with detailed progress
+depwire temporal --verbose --stats
+
+# Custom port
+depwire temporal --port 3335
+```
+
+**Options:**
+- `--commits <number>` — Number of commits to sample (default: 20)
+- `--strategy <type>` — Sampling strategy: `even`, `weekly`, `monthly` (default: `even`)
+- `-p, --port <number>` — Server port (default: 3334)
+- `--output <path>` — Save snapshots to custom path (default: `.depwire/temporal/`)
+- `--verbose` — Show progress for each commit being parsed
+- `--stats` — Show summary statistics at end
+
+Opens an interactive temporal visualization in your browser:
+- Timeline slider showing all sampled commits
+- Arc diagram morphing between snapshots
+- Play/pause animation with speed controls (0.5×, 1×, 2×)
+- Statistics panel with growth deltas
+- Evolution chart tracking files/symbols/edges over time
+- Auto-zoom to fit all arcs on snapshot change
+- Search to highlight specific files across time
+
 ## How It Works
 
 1. **Parser** — tree-sitter extracts every symbol and reference
@@ -360,6 +401,44 @@ depwire health --json
 
 Health history is stored in `.depwire/health-history.json` (last 50 checks).
 
+### `depwire temporal [directory]`
+
+Visualize how the dependency graph evolved over git history.
+
+**Directory argument is optional** — Auto-detects project root.
+
+**Options:**
+- `--commits <number>` — Number of commits to sample (default: 20)
+- `--strategy <type>` — Sampling strategy: `even` (every Nth), `weekly`, `monthly` (default: `even`)
+- `-p, --port <number>` — Server port (default: 3334)
+- `--output <path>` — Save snapshots to custom path (default: `.depwire/temporal/`)
+- `--verbose` — Show progress for each commit being parsed
+- `--stats` — Show summary statistics at end
+
+**Examples:**
+```bash
+# Auto-detect and analyze 20 commits
+depwire temporal
+
+# Sample 50 commits with monthly snapshots
+depwire temporal --commits 50 --strategy monthly
+
+# Verbose mode with stats
+depwire temporal --verbose --stats
+
+# Custom output directory
+depwire temporal --output ./temp-snapshots
+```
+
+**Output:**
+- Interactive browser visualization at `http://127.0.0.1:3334`
+- Timeline slider to scrub through git history
+- Arc diagram morphing between snapshots
+- Growth statistics showing files/symbols/edges evolution
+- Auto-zoom to fit full diagram on each snapshot change
+
+Snapshots are cached in `.depwire/temporal/` for fast re-rendering.
+
 ### Error Handling
 
 Depwire gracefully handles parse errors:

package/dist/{chunk-VNUOE5VC.js → chunk-65H7HCM4.js}

@@ -7272,8 +7272,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/tools.ts
-import { dirname as dirname14, join as join14 } from "path";
-import { existsSync as existsSync11, readFileSync as readFileSync7 } from "fs";
+import { dirname as dirname14, join as join15 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
 
 // src/mcp/connect.ts
 import simpleGit from "simple-git";
@@ -7467,6 +7467,268 @@ async function connectToRepo(source, subdirectory, state) {
   }
 }
 
+// src/temporal/git.ts
+import { execSync as execSync2 } from "child_process";
+async function getCommitLog(dir, limit) {
+  try {
+    const limitArg = limit ? `-n ${limit}` : "";
+    const output = execSync2(
+      `git log ${limitArg} --pretty=format:"%H|%aI|%s|%an"`,
+      { cwd: dir, encoding: "utf-8" }
+    );
+    if (!output.trim()) {
+      return [];
+    }
+    return output.trim().split("\n").map((line) => {
+      const [hash, date, message, author] = line.split("|");
+      return { hash, date, message, author };
+    });
+  } catch (error) {
+    throw new Error(`Failed to get git log: ${error}`);
+  }
+}
+async function getCurrentBranch(dir) {
+  try {
+    return execSync2("git rev-parse --abbrev-ref HEAD", {
+      cwd: dir,
+      encoding: "utf-8"
+    }).trim();
+  } catch (error) {
+    throw new Error(`Failed to get current branch: ${error}`);
+  }
+}
+async function checkoutCommit(dir, hash) {
+  try {
+    execSync2(`git checkout -q ${hash}`, { cwd: dir, stdio: "ignore" });
+  } catch (error) {
+    throw new Error(`Failed to checkout commit ${hash}: ${error}`);
+  }
+}
+async function restoreOriginal(dir, originalBranch) {
+  try {
+    execSync2(`git checkout -q ${originalBranch}`, {
+      cwd: dir,
+      stdio: "ignore"
+    });
+  } catch (error) {
+    throw new Error(`Failed to restore branch ${originalBranch}: ${error}`);
+  }
+}
+async function stashChanges(dir) {
+  try {
+    const status = execSync2("git status --porcelain", {
+      cwd: dir,
+      encoding: "utf-8"
+    }).trim();
+    if (status) {
+      execSync2('git stash push -q -m "depwire temporal analysis"', {
+        cwd: dir,
+        stdio: "ignore"
+      });
+      return true;
+    }
+    return false;
+  } catch (error) {
+    throw new Error(`Failed to stash changes: ${error}`);
+  }
+}
+async function popStash(dir) {
+  try {
+    execSync2("git stash pop -q", { cwd: dir, stdio: "ignore" });
+  } catch (error) {
+    console.warn("Warning: Failed to restore stashed changes:", error);
+  }
+}
+function isGitRepo(dir) {
+  try {
+    execSync2("git rev-parse --git-dir", { cwd: dir, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/temporal/sampler.ts
+function sampleCommits(commits, targetCount, strategy) {
+  if (commits.length === 0) {
+    return [];
+  }
+  if (commits.length <= targetCount) {
+    return commits;
+  }
+  switch (strategy) {
+    case "even":
+      return sampleEvenly(commits, targetCount);
+    case "weekly":
+      return sampleWeekly(commits, targetCount);
+    case "monthly":
+      return sampleMonthly(commits, targetCount);
+    default:
+      return sampleEvenly(commits, targetCount);
+  }
+}
+function sampleEvenly(commits, targetCount) {
+  if (targetCount >= commits.length) {
+    return commits;
+  }
+  const result = [];
+  const step = (commits.length - 1) / (targetCount - 1);
+  for (let i = 0; i < targetCount; i++) {
+    const index = Math.round(i * step);
+    result.push(commits[index]);
+  }
+  return result;
+}
+function sampleWeekly(commits, targetCount) {
+  const result = [];
+  const first = commits[0];
+  const last = commits[commits.length - 1];
+  result.push(first);
+  const weekMap = /* @__PURE__ */ new Map();
+  for (const commit of commits) {
+    const date = new Date(commit.date);
+    const year = date.getFullYear();
+    const week = getWeekNumber(date);
+    const key = `${year}-W${week}`;
+    weekMap.set(key, commit);
+  }
+  const weeklyCommits = Array.from(weekMap.values());
+  if (weeklyCommits.length <= targetCount) {
+    return weeklyCommits;
+  }
+  const step = Math.floor((weeklyCommits.length - 2) / (targetCount - 2));
+  for (let i = 1; i < targetCount - 1; i++) {
+    const index = Math.min(i * step, weeklyCommits.length - 2);
+    if (weeklyCommits[index] !== first && weeklyCommits[index] !== last) {
+      result.push(weeklyCommits[index]);
+    }
+  }
+  if (result[result.length - 1] !== last) {
+    result.push(last);
+  }
+  return result;
+}
+function sampleMonthly(commits, targetCount) {
+  const result = [];
+  const first = commits[0];
+  const last = commits[commits.length - 1];
+  result.push(first);
+  const monthMap = /* @__PURE__ */ new Map();
+  for (const commit of commits) {
+    const date = new Date(commit.date);
+    const key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+    monthMap.set(key, commit);
+  }
+  const monthlyCommits = Array.from(monthMap.values());
+  if (monthlyCommits.length <= targetCount) {
+    return monthlyCommits;
+  }
+  const step = Math.floor((monthlyCommits.length - 2) / (targetCount - 2));
+  for (let i = 1; i < targetCount - 1; i++) {
+    const index = Math.min(i * step, monthlyCommits.length - 2);
+    if (monthlyCommits[index] !== first && monthlyCommits[index] !== last) {
+      result.push(monthlyCommits[index]);
+    }
+  }
+  if (result[result.length - 1] !== last) {
+    result.push(last);
+  }
+  return result;
+}
+function getWeekNumber(date) {
+  const d = new Date(
+    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+  );
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  return Math.ceil(((d.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+}
+
+// src/temporal/snapshots.ts
+import { writeFileSync as writeFileSync4, readFileSync as readFileSync7, mkdirSync as mkdirSync3, existsSync as existsSync11, readdirSync as readdirSync3 } from "fs";
+import { join as join14 } from "path";
+function saveSnapshot(snapshot, outputDir) {
+  if (!existsSync11(outputDir)) {
+    mkdirSync3(outputDir, { recursive: true });
+  }
+  const filename = `${snapshot.commitHash.substring(0, 8)}.json`;
+  const filepath = join14(outputDir, filename);
+  writeFileSync4(filepath, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+function loadSnapshot(commitHash, outputDir) {
+  const shortHash = commitHash.substring(0, 8);
+  const filepath = join14(outputDir, `${shortHash}.json`);
+  if (!existsSync11(filepath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync7(filepath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function createSnapshot(graph, commitHash, commitDate, commitMessage, commitAuthor) {
+  const fileMap = /* @__PURE__ */ new Map();
+  for (const node of graph.nodes) {
+    if (!fileMap.has(node.filePath)) {
+      fileMap.set(node.filePath, { symbols: 0, inbound: 0, outbound: 0 });
+    }
+    fileMap.get(node.filePath).symbols++;
+  }
+  for (const edge of graph.edges) {
+    const sourceNode = graph.nodes.find((n) => n.id === edge.source);
+    const targetNode = graph.nodes.find((n) => n.id === edge.target);
+    if (sourceNode && targetNode && sourceNode.filePath !== targetNode.filePath) {
+      if (fileMap.has(sourceNode.filePath)) {
+        fileMap.get(sourceNode.filePath).outbound++;
+      }
+      if (fileMap.has(targetNode.filePath)) {
+        fileMap.get(targetNode.filePath).inbound++;
+      }
+    }
+  }
+  const files = Array.from(fileMap.entries()).map(([path2, data]) => ({
+    path: path2,
+    symbols: data.symbols,
+    connections: data.inbound + data.outbound
+  }));
+  const edgeMap = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    const sourceNode = graph.nodes.find((n) => n.id === edge.source);
+    const targetNode = graph.nodes.find((n) => n.id === edge.target);
+    if (sourceNode && targetNode && sourceNode.filePath !== targetNode.filePath) {
+      const key = sourceNode.filePath < targetNode.filePath ? `${sourceNode.filePath}|${targetNode.filePath}` : `${targetNode.filePath}|${sourceNode.filePath}`;
+      edgeMap.set(key, (edgeMap.get(key) || 0) + 1);
+    }
+  }
+  const edges = Array.from(edgeMap.entries()).map(([key, weight]) => {
+    const [source, target] = key.split("|");
+    return { source, target, weight };
+  });
+  const languages2 = {};
+  for (const file of graph.files) {
+    const ext = file.split(".").pop() || "unknown";
+    const lang = ext === "ts" || ext === "tsx" ? "typescript" : ext === "js" || ext === "jsx" || ext === "mjs" || ext === "cjs" ? "javascript" : ext === "py" ? "python" : ext === "go" ? "go" : "other";
+    languages2[lang] = (languages2[lang] || 0) + 1;
+  }
+  return {
+    commitHash,
+    commitDate,
+    commitMessage,
+    commitAuthor,
+    stats: {
+      totalFiles: graph.files.length,
+      totalSymbols: graph.nodes.length,
+      totalEdges: edges.length,
+      languages: languages2
+    },
+    files,
+    edges
+  };
+}
+
 // src/mcp/tools.ts
 function getToolsList() {
   return [
@@ -7647,6 +7909,24 @@ function getToolsList() {
         type: "object",
         properties: {}
       }
+    },
+    {
+      name: "get_temporal_graph",
+      description: "Show how the dependency graph evolved over git history. Returns snapshots at sampled commits showing file counts, symbol counts, edge counts, and structural changes over time.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          commits: {
+            type: "number",
+            description: "Number of commits to sample (default: 10)"
+          },
+          strategy: {
+            type: "string",
+            enum: ["even", "weekly", "monthly"],
+            description: "Sampling strategy (default: even)"
+          }
+        }
+      }
     }
   ];
 }
@@ -7700,6 +7980,15 @@ async function handleToolCall(name, args, state) {
       } else {
         result = handleGetHealthScore(state);
       }
+    } else if (name === "get_temporal_graph") {
+      if (!isProjectLoaded(state)) {
+        result = {
+          error: "No project loaded",
+          message: "Use connect_repo to connect to a codebase first"
+        };
+      } else {
+        result = await handleGetTemporalGraph(state, args.commits || 10, args.strategy || "even");
+      }
     } else {
       if (!isProjectLoaded(state)) {
         result = {
@@ -8124,8 +8413,8 @@ The server will keep running until you end the MCP session or press Ctrl+C.`;
   };
 }
 async function handleGetProjectDocs(docType, state) {
-  const docsDir = join14(state.projectRoot, ".depwire");
-  if (!existsSync11(docsDir)) {
+  const docsDir = join15(state.projectRoot, ".depwire");
+  if (!existsSync12(docsDir)) {
     const errorMessage = `Project documentation has not been generated yet.
 
 Run \`depwire docs ${state.projectRoot}\` to generate codebase documentation.
@@ -8155,12 +8444,12 @@ Available document types:
       missing.push(doc);
       continue;
     }
-    const filePath = join14(docsDir, metadata.documents[doc].file);
-    if (!existsSync11(filePath)) {
+    const filePath = join15(docsDir, metadata.documents[doc].file);
+    if (!existsSync12(filePath)) {
       missing.push(doc);
       continue;
     }
-    const content = readFileSync7(filePath, "utf-8");
+    const content = readFileSync8(filePath, "utf-8");
     if (docsToReturn.length > 1) {
       output += `
 
@@ -8185,16 +8474,16 @@ Available document types:
 }
 async function handleUpdateProjectDocs(docType, state) {
   const startTime = Date.now();
-  const docsDir = join14(state.projectRoot, ".depwire");
+  const docsDir = join15(state.projectRoot, ".depwire");
   console.error("Regenerating project documentation...");
   const parsedFiles = await parseProject(state.projectRoot);
   const graph = buildGraph(parsedFiles);
   const parseTime = (Date.now() - startTime) / 1e3;
   state.graph = graph;
-  const packageJsonPath = join14(__dirname, "../../package.json");
-  const packageJson = JSON.parse(readFileSync7(packageJsonPath, "utf-8"));
+  const packageJsonPath = join15(__dirname, "../../package.json");
+  const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf-8"));
   const docsToGenerate = docType === "all" ? ["architecture", "conventions", "dependencies", "onboarding"] : [docType];
-  const docsExist = existsSync11(docsDir);
+  const docsExist = existsSync12(docsDir);
   const result = await generateDocs(graph, state.projectRoot, packageJson.version, parseTime, {
     outputDir: docsDir,
     format: "markdown",
@@ -8235,6 +8524,86 @@ function handleGetHealthScore(state) {
   const report = calculateHealthScore(graph, projectRoot);
   return report;
 }
+async function handleGetTemporalGraph(state, commits, strategy) {
+  const projectRoot = state.projectRoot;
+  if (!isGitRepo(projectRoot)) {
+    return {
+      error: "Not a git repository",
+      message: "Temporal analysis requires git history"
+    };
+  }
+  try {
+    const allCommits = await getCommitLog(projectRoot);
+    if (allCommits.length === 0) {
+      return {
+        error: "No commits found",
+        message: "Repository has no commit history"
+      };
+    }
+    const sampledCommits = sampleCommits(allCommits, commits, strategy);
+    const snapshots = [];
+    const outputDir = join15(projectRoot, ".depwire", "temporal");
+    for (const commit of sampledCommits) {
+      const existing = loadSnapshot(commit.hash, outputDir);
+      if (existing) {
+        snapshots.push(existing);
+      }
+    }
+    if (snapshots.length === 0) {
+      return {
+        status: "no_snapshots",
+        message: "No temporal snapshots found. Run `depwire temporal` to generate them.",
+        commits_found: allCommits.length,
+        commits_to_sample: sampledCommits.length
+      };
+    }
+    const first = snapshots[0];
+    const last = snapshots[snapshots.length - 1];
+    const growth = {
+      files: last.stats.totalFiles - first.stats.totalFiles,
+      symbols: last.stats.totalSymbols - first.stats.totalSymbols,
+      edges: last.stats.totalEdges - first.stats.totalEdges
+    };
+    const trend = growth.files > 0 ? "Growing" : growth.files < 0 ? "Shrinking" : "Stable";
+    let biggestGrowth = { index: 0, files: 0, date: "", message: "" };
+    for (let i = 1; i < snapshots.length; i++) {
+      const delta = snapshots[i].stats.totalFiles - snapshots[i - 1].stats.totalFiles;
+      if (delta > biggestGrowth.files) {
+        biggestGrowth = {
+          index: i,
+          files: delta,
+          date: snapshots[i].commitDate,
+          message: snapshots[i].commitMessage
+        };
+      }
+    }
+    return {
+      status: "success",
+      time_range: {
+        from: first.commitDate,
+        to: last.commitDate
+      },
+      snapshots: snapshots.map((s) => ({
+        commit: s.commitHash.substring(0, 8),
+        date: s.commitDate,
+        message: s.commitMessage,
+        author: s.commitAuthor,
+        files: s.stats.totalFiles,
+        symbols: s.stats.totalSymbols,
+        edges: s.stats.totalEdges
+      })),
+      growth,
+      trend,
+      biggest_growth_period: biggestGrowth.files > 0 ? biggestGrowth : null,
+      summary: `Analyzed ${snapshots.length} snapshots from ${new Date(first.commitDate).toLocaleDateString()} to ${new Date(last.commitDate).toLocaleDateString()}. Overall trend: ${trend}.`
+    };
+  } catch (error) {
+    return {
+      error: "Failed to analyze temporal graph",
+      message: String(error)
+    };
+  }
+}
 
 // src/mcp/server.ts
 async function startMcpServer(state) {
@@ -8284,5 +8653,16 @@ export {
   calculateHealthScore,
   getHealthTrend,
   generateDocs,
+  getCommitLog,
+  getCurrentBranch,
+  checkoutCommit,
+  restoreOriginal,
+  stashChanges,
+  popStash,
+  isGitRepo,
+  sampleCommits,
+  saveSnapshot,
+  loadSnapshot,
+  createSnapshot,
   startMcpServer
 };