archtracker-mcp 0.6.0 → 0.7.0

package/dist/mcp/index.js

@@ -1562,6 +1562,8 @@ var en = {
   "diff.reasonRemoved": 'Dependency "{file}" was removed',
   "diff.reasonModified": 'Dependency "{file}" had its dependencies changed',
   "diff.reasonAdded": 'New dependency "{file}" was added',
+  "diff.testSummary": "  ... and {count} test/fixture file(s)",
+  "diff.testAffectedSummary": "  ... and {count} test/fixture-related review(s)",
   // Search
   "search.pathMatch": 'Path matches "{pattern}"',
   "search.affected": 'May be affected by changes to "{file}" (via: {via})',
@@ -1623,6 +1625,12 @@ var en = {
   "web.watching": "Watching {dir}/ for changes...",
   "web.reloading": "File change detected, reloading...",
   "web.reloaded": "Graph reloaded",
+  // History
+  "history.title": "# Snapshot History\n",
+  "history.empty": "No snapshots found. Run `archtracker init` to create one.",
+  "history.entry": "  {ts}  |  {files} files, {edges} edges, {circular} circular{layers}",
+  "history.count": "{count} snapshot(s) recorded",
+  "history.snapshotNotFound": "Snapshot not found for timestamp: {ts}",
   // Errors
   "error.analyzer": "[Analysis Error] {message}",
   "error.storage": "[Storage Error] {message}",
@@ -1655,6 +1663,8 @@ var ja = {
   "diff.reasonRemoved": '\u4F9D\u5B58\u5148 "{file}" \u304C\u524A\u9664\u3055\u308C\u307E\u3057\u305F',
   "diff.reasonModified": '\u4F9D\u5B58\u5148 "{file}" \u306E\u4F9D\u5B58\u95A2\u4FC2\u304C\u5909\u66F4\u3055\u308C\u307E\u3057\u305F',
   "diff.reasonAdded": '\u65B0\u3057\u3044\u4F9D\u5B58\u5148 "{file}" \u304C\u8FFD\u52A0\u3055\u308C\u307E\u3057\u305F',
+  "diff.testSummary": "  ... \u4ED6 {count}\u4EF6\u306E\u30C6\u30B9\u30C8/\u30D5\u30A3\u30AF\u30B9\u30C1\u30E3\u30D5\u30A1\u30A4\u30EB",
+  "diff.testAffectedSummary": "  ... \u4ED6 {count}\u4EF6\u306E\u30C6\u30B9\u30C8/\u30D5\u30A3\u30AF\u30B9\u30C1\u30E3\u95A2\u9023\u306E\u78BA\u8A8D\u9805\u76EE",
   // Search
   "search.pathMatch": '\u30D1\u30B9\u304C "{pattern}" \u306B\u30DE\u30C3\u30C1',
   "search.affected": '"{file}" \u306E\u5909\u66F4\u306B\u3088\u308A\u5F71\u97FF\u3092\u53D7\u3051\u308B\u53EF\u80FD\u6027\uFF08\u7D4C\u7531: {via}\uFF09',
@@ -1716,6 +1726,12 @@ var ja = {
   "web.watching": "{dir}/ \u3092\u76E3\u8996\u4E2D...",
   "web.reloading": "\u30D5\u30A1\u30A4\u30EB\u5909\u66F4\u3092\u691C\u51FA\u3001\u30EA\u30ED\u30FC\u30C9\u4E2D...",
   "web.reloaded": "\u30B0\u30E9\u30D5\u3092\u66F4\u65B0\u3057\u307E\u3057\u305F",
+  // History
+  "history.title": "# \u30B9\u30CA\u30C3\u30D7\u30B7\u30E7\u30C3\u30C8\u5C65\u6B74\n",
+  "history.empty": "\u30B9\u30CA\u30C3\u30D7\u30B7\u30E7\u30C3\u30C8\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002`archtracker init` \u3067\u4F5C\u6210\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "history.entry": "  {ts}  |  {files}\u30D5\u30A1\u30A4\u30EB, {edges}\u30A8\u30C3\u30B8, \u5FAA\u74B0{circular}\u4EF6{layers}",
+  "history.count": "{count}\u4EF6\u306E\u30B9\u30CA\u30C3\u30D7\u30B7\u30E7\u30C3\u30C8\u3092\u8A18\u9332",
+  "history.snapshotNotFound": "\u6307\u5B9A\u306E\u30BF\u30A4\u30E0\u30B9\u30BF\u30F3\u30D7\u306E\u30B9\u30CA\u30C3\u30D7\u30B7\u30E7\u30C3\u30C8\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093: {ts}",
   // Errors
   "error.analyzer": "[\u89E3\u6790\u30A8\u30E9\u30FC] {message}",
   "error.storage": "[\u30B9\u30C8\u30EC\u30FC\u30B8\u30A8\u30E9\u30FC] {message}",
@@ -1858,14 +1874,14 @@ var LAYER_COLORS = [
   "#ffa657",
   "#7ee787"
 ];
-async function analyzeMultiLayer(projectRoot, layerDefs) {
+async function analyzeMultiLayer(projectRoot, layerDefs, globalExclude) {
   const layers = {};
   const layerMetadata = [];
   for (let idx = 0; idx < layerDefs.length; idx++) {
     const def = layerDefs[idx];
     const targetDir = resolve4(projectRoot, def.targetDir);
     const graph = await analyzeProject(targetDir, {
-      exclude: def.exclude,
+      exclude: def.exclude ?? globalExclude,
       language: def.language
     });
     const language = def.language ?? await detectLanguage(targetDir) ?? "javascript";
@@ -2291,11 +2307,240 @@ function isNodeError(error) {
   return error instanceof Error && "code" in error;
 }
 
+// src/storage/graph-cache.ts
+import { readFile as readFile3, writeFile as writeFile2, mkdir as mkdir2, stat as stat4 } from "fs/promises";
+import { join as join6, resolve as resolve5 } from "path";
+import { readdir as readdir3 } from "fs/promises";
+import { createHash } from "crypto";
+var CACHE_FILE = "graph.json";
+var ARCHTRACKER_DIR2 = ".archtracker";
+async function hashFile(filePath) {
+  const content = await readFile3(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+async function collectFileFingerprints(dir, exclude = []) {
+  const fingerprints = {};
+  const excludeRegexes = exclude.map((p) => new RegExp(p));
+  async function walk(currentDir) {
+    let entries;
+    try {
+      entries = await readdir3(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join6(currentDir, entry.name);
+      const relativePath = fullPath.slice(dir.length + 1);
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      if (excludeRegexes.some((r) => r.test(relativePath))) continue;
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        try {
+          const s = await stat4(fullPath);
+          const hash = await hashFile(fullPath);
+          fingerprints[relativePath] = { mtime: s.mtimeMs, hash };
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(dir);
+  return fingerprints;
+}
+async function saveGraphCache(projectRoot, graph, options, extra) {
+  const absRoot = resolve5(projectRoot);
+  const dir = join6(absRoot, ARCHTRACKER_DIR2);
+  await mkdir2(dir, { recursive: true });
+  let fingerprints;
+  if (extra?.layerDirs?.length) {
+    fingerprints = {};
+    for (const layerDir of extra.layerDirs) {
+      const layerPath = resolve5(absRoot, layerDir);
+      const layerFp = await collectFileFingerprints(layerPath, options.exclude);
+      for (const [key, value] of Object.entries(layerFp)) {
+        fingerprints[`${layerDir}/${key}`] = value;
+      }
+    }
+  } else {
+    fingerprints = await collectFingerprintsForGraph(absRoot, options);
+  }
+  let layersJsonHash;
+  try {
+    layersJsonHash = await hashFile(join6(dir, "layers.json"));
+  } catch {
+  }
+  const mtimes = {};
+  for (const [k, v] of Object.entries(fingerprints)) {
+    mtimes[k] = v.mtime;
+  }
+  const cache = {
+    version: "1.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    options: {
+      targetDir: options.targetDir,
+      projectRoot: options.projectRoot,
+      language: options.language,
+      exclude: options.exclude
+    },
+    fileMtimes: mtimes,
+    fileHashes: Object.fromEntries(
+      Object.entries(fingerprints).map(([k, v]) => [k, v.hash])
+    ),
+    graph,
+    multiLayer: extra?.multiLayer,
+    layerMetadata: extra?.layerMetadata,
+    layerDirs: extra?.layerDirs,
+    layersJsonHash
+  };
+  await writeFile2(join6(dir, CACHE_FILE), JSON.stringify(cache), "utf-8");
+}
+async function loadGraphCache(projectRoot) {
+  const absRoot = resolve5(projectRoot);
+  const filePath = join6(absRoot, ARCHTRACKER_DIR2, CACHE_FILE);
+  try {
+    const raw = await readFile3(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    if (data?.version !== "1.0" || !data?.graph || !data?.fileMtimes) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+async function isGraphCacheValid(cache, projectRoot, options) {
+  if (cache.options.targetDir !== options.targetDir || cache.options.projectRoot !== options.projectRoot || (cache.options.language ?? "") !== (options.language ?? "") || JSON.stringify(cache.options.exclude ?? []) !== JSON.stringify(options.exclude ?? [])) {
+    return false;
+  }
+  const absRoot = resolve5(projectRoot);
+  const targetPath = resolve5(absRoot, options.targetDir);
+  const isMultiLayer = (cache.layerDirs?.length ?? 0) > 0;
+  let currentLayersHash;
+  try {
+    currentLayersHash = await hashFile(join6(absRoot, ARCHTRACKER_DIR2, "layers.json"));
+  } catch {
+  }
+  if ((cache.layersJsonHash ?? "") !== (currentLayersHash ?? "")) return false;
+  let currentMtimes;
+  if (isMultiLayer) {
+    currentMtimes = {};
+    for (const layerDir of cache.layerDirs) {
+      const layerPath = resolve5(absRoot, layerDir);
+      const dirMtimes = await collectFileMtimes(layerPath, options.exclude);
+      for (const [key, value] of Object.entries(dirMtimes)) {
+        currentMtimes[`${layerDir}/${key}`] = value;
+      }
+    }
+  } else {
+    currentMtimes = await collectFileMtimes(targetPath, options.exclude);
+  }
+  const cachedKeys = new Set(Object.keys(cache.fileMtimes));
+  const currentKeys = new Set(Object.keys(currentMtimes));
+  if (cachedKeys.size !== currentKeys.size) return false;
+  for (const key of cachedKeys) {
+    if (!currentKeys.has(key)) return false;
+  }
+  const mtimeChanged = [];
+  for (const key of cachedKeys) {
+    if (Math.abs(cache.fileMtimes[key] - currentMtimes[key]) > 1) {
+      mtimeChanged.push(key);
+    }
+  }
+  if (mtimeChanged.length === 0) return true;
+  if (!cache.fileHashes) return false;
+  for (const key of mtimeChanged) {
+    const cachedHash = cache.fileHashes[key];
+    if (!cachedHash) return false;
+    try {
+      const fullPath = isMultiLayer ? join6(absRoot, key) : join6(targetPath, key);
+      const currentHash = await hashFile(fullPath);
+      if (currentHash !== cachedHash) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+async function collectFileMtimes(dir, exclude) {
+  const mtimes = {};
+  const excludeRegexes = (exclude ?? []).map((p) => new RegExp(p));
+  async function walk(currentDir) {
+    let entries;
+    try {
+      entries = await readdir3(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join6(currentDir, entry.name);
+      const relativePath = fullPath.slice(dir.length + 1);
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      if (excludeRegexes.some((r) => r.test(relativePath))) continue;
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        try {
+          const s = await stat4(fullPath);
+          mtimes[relativePath] = s.mtimeMs;
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(dir);
+  return mtimes;
+}
+async function collectFingerprintsForGraph(absRoot, options) {
+  const targetPath = resolve5(absRoot, options.targetDir);
+  return collectFileFingerprints(targetPath, options.exclude);
+}
+
 // src/analyzer/resolve.ts
 async function resolveGraph(opts) {
+  if (!opts.noCache) {
+    const cache = await loadGraphCache(opts.projectRoot);
+    if (cache) {
+      const valid = await isGraphCacheValid(cache, opts.projectRoot, {
+        targetDir: opts.targetDir,
+        projectRoot: opts.projectRoot,
+        language: opts.language,
+        exclude: opts.exclude
+      });
+      if (valid) {
+        const result2 = {
+          graph: cache.graph,
+          multiLayer: cache.multiLayer,
+          layerMetadata: cache.layerMetadata,
+          fromCache: true
+        };
+        if (cache.multiLayer) {
+          const layerConfig2 = await loadLayerConfig(opts.projectRoot);
+          if (layerConfig2) {
+            const autoConnections = detectCrossLayerConnections(
+              cache.multiLayer.layers,
+              layerConfig2.layers
+            );
+            const manualConnections = layerConfig2.connections ?? [];
+            const manualKeys = new Set(manualConnections.map(
+              (c) => `${c.fromLayer}/${c.fromFile}\u2192${c.toLayer}/${c.toFile}`
+            ));
+            result2.crossLayerEdges = [
+              ...manualConnections,
+              ...autoConnections.filter(
+                (c) => !manualKeys.has(`${c.fromLayer}/${c.fromFile}\u2192${c.toLayer}/${c.toFile}`)
+              )
+            ];
+          }
+        }
+        return result2;
+      }
+    }
+  }
   const layerConfig = await loadLayerConfig(opts.projectRoot);
+  let result;
   if (layerConfig) {
-    const multi = await analyzeMultiLayer(opts.projectRoot, layerConfig.layers);
+    const multi = await analyzeMultiLayer(opts.projectRoot, layerConfig.layers, opts.exclude);
     const autoConnections = detectCrossLayerConnections(multi.layers, layerConfig.layers);
     const manualConnections = layerConfig.connections ?? [];
     const manualKeys = new Set(manualConnections.map(
@@ -2307,31 +2552,52 @@ async function resolveGraph(opts) {
         (c) => !manualKeys.has(`${c.fromLayer}/${c.fromFile}\u2192${c.toLayer}/${c.toFile}`)
       )
     ];
-    return {
+    result = {
       graph: multi.merged,
       multiLayer: multi,
       layerMetadata: multi.layerMetadata,
       crossLayerEdges: merged
     };
+  } else {
+    const graph = await analyzeProject(opts.targetDir, {
+      exclude: opts.exclude,
+      language: opts.language
+    });
+    result = { graph };
   }
-  const graph = await analyzeProject(opts.targetDir, {
-    exclude: opts.exclude,
-    language: opts.language
-  });
-  return { graph };
+  try {
+    await saveGraphCache(
+      opts.projectRoot,
+      result.graph,
+      {
+        targetDir: opts.targetDir,
+        projectRoot: opts.projectRoot,
+        language: opts.language,
+        exclude: opts.exclude
+      },
+      {
+        multiLayer: result.multiLayer,
+        layerMetadata: result.layerMetadata,
+        layerDirs: layerConfig?.layers.map((l) => l.targetDir)
+      }
+    );
+  } catch {
+  }
+  return result;
 }
 
 // src/storage/snapshot.ts
-import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile3, access } from "fs/promises";
-import { join as join6 } from "path";
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile4, readdir as readdir4, access } from "fs/promises";
+import { join as join7 } from "path";
 import { z as z2 } from "zod";
 
 // src/types/schema.ts
 var SCHEMA_VERSION = "1.1";
 
 // src/storage/snapshot.ts
-var ARCHTRACKER_DIR2 = ".archtracker";
+var ARCHTRACKER_DIR3 = ".archtracker";
 var SNAPSHOT_FILE = "snapshot.json";
+var HISTORY_DIR = "history";
 var FileNodeSchema = z2.object({
   path: z2.string(),
   exists: z2.boolean(),
@@ -2356,25 +2622,34 @@ var SnapshotSchema = z2.object({
   rootDir: z2.string(),
   graph: DependencyGraphSchema
 });
-async function saveSnapshot(projectRoot, graph, multiLayer) {
-  const dirPath = join6(projectRoot, ARCHTRACKER_DIR2);
-  const filePath = join6(dirPath, SNAPSHOT_FILE);
+async function saveSnapshot(projectRoot, graph, multiLayer, analysisOptions) {
+  const dirPath = join7(projectRoot, ARCHTRACKER_DIR3);
+  const filePath = join7(dirPath, SNAPSHOT_FILE);
   const snapshot = {
     version: SCHEMA_VERSION,
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     rootDir: graph.rootDir,
     graph,
-    ...multiLayer ? { multiLayer } : {}
+    ...multiLayer ? { multiLayer } : {},
+    ...analysisOptions ? { analysisOptions } : {}
   };
-  await mkdir2(dirPath, { recursive: true });
-  await writeFile2(filePath, JSON.stringify(snapshot, null, 2), "utf-8");
+  await mkdir3(dirPath, { recursive: true });
+  const json = JSON.stringify(snapshot, null, 2);
+  await writeFile3(filePath, json, "utf-8");
+  try {
+    const historyPath = join7(dirPath, HISTORY_DIR);
+    await mkdir3(historyPath, { recursive: true });
+    const safeTs = snapshot.timestamp.replace(/[:.]/g, "-");
+    await writeFile3(join7(historyPath, `${safeTs}.json`), json, "utf-8");
+  } catch {
+  }
   return snapshot;
 }
 async function loadSnapshot(projectRoot) {
-  const filePath = join6(projectRoot, ARCHTRACKER_DIR2, SNAPSHOT_FILE);
+  const filePath = join7(projectRoot, ARCHTRACKER_DIR3, SNAPSHOT_FILE);
   let raw;
   try {
-    raw = await readFile3(filePath, "utf-8");
+    raw = await readFile4(filePath, "utf-8");
   } catch (error) {
     if (isNodeError2(error) && error.code === "ENOENT") {
       return null;
@@ -2401,6 +2676,67 @@ async function loadSnapshot(projectRoot) {
   }
   return result.data;
 }
+async function listSnapshots(projectRoot) {
+  const historyPath = join7(projectRoot, ARCHTRACKER_DIR3, HISTORY_DIR);
+  let entries;
+  try {
+    entries = await readdir4(historyPath);
+  } catch {
+    return [];
+  }
+  const jsonFiles = entries.filter((e) => e.endsWith(".json")).sort().reverse();
+  const summaries = [];
+  for (const file of jsonFiles) {
+    try {
+      const raw = await readFile4(join7(historyPath, file), "utf-8");
+      const parsed = JSON.parse(raw);
+      const result = SnapshotSchema.safeParse(parsed);
+      if (result.success) {
+        const snap = result.data;
+        summaries.push({
+          timestamp: snap.timestamp,
+          totalFiles: snap.graph.totalFiles,
+          totalEdges: snap.graph.totalEdges,
+          circularDeps: snap.graph.circularDependencies.length,
+          hasMultiLayer: "multiLayer" in parsed && parsed.multiLayer != null
+        });
+      }
+    } catch {
+    }
+  }
+  return summaries;
+}
+async function loadSnapshotByTimestamp(projectRoot, timestamp) {
+  const historyPath = join7(projectRoot, ARCHTRACKER_DIR3, HISTORY_DIR);
+  let entries;
+  try {
+    entries = await readdir4(historyPath);
+  } catch {
+    return null;
+  }
+  const jsonFiles = entries.filter((e) => e.endsWith(".json")).sort();
+  const safeTs = timestamp.replace(/[:.]/g, "-");
+  const exactMatch = jsonFiles.find((f) => f === `${safeTs}.json`);
+  if (exactMatch) {
+    return loadHistoryFile(join7(historyPath, exactMatch));
+  }
+  const prefixMatch = jsonFiles.find((f) => f.startsWith(safeTs.slice(0, 10)));
+  if (prefixMatch) {
+    return loadHistoryFile(join7(historyPath, prefixMatch));
+  }
+  return null;
+}
+async function loadHistoryFile(filePath) {
+  try {
+    const raw = await readFile4(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const result = SnapshotSchema.safeParse(parsed);
+    if (result.success) return result.data;
+    return null;
+  } catch {
+    return null;
+  }
+}
 var StorageError = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -2462,6 +2798,17 @@ function computeDiff(oldGraph, newGraph) {
   }
   return { added, removed, modified, affectedDependents };
 }
+function isTestOrFixture(path) {
+  return /(__fixtures__|__tests__|__mocks__|\.test\.|\.spec\.|\.e2e\.)/.test(path);
+}
+function partition(arr, pred) {
+  const yes = [];
+  const no = [];
+  for (const item of arr) {
+    (pred(item) ? yes : no).push(item);
+  }
+  return [yes, no];
+}
 function formatDiffReport(diff) {
   const lines = [];
   lines.push(t("diff.title"));
@@ -2470,32 +2817,51 @@ function formatDiffReport(diff) {
     return lines.join("\n");
   }
   if (diff.added.length > 0) {
+    const [testFiles, srcFiles] = partition(diff.added, isTestOrFixture);
     lines.push(t("diff.added", { count: diff.added.length }));
-    for (const f of diff.added) {
+    for (const f of srcFiles) {
       lines.push(`  + ${f}`);
     }
+    if (testFiles.length > 0) {
+      lines.push(t("diff.testSummary", { count: testFiles.length }));
+    }
     lines.push("");
   }
   if (diff.removed.length > 0) {
+    const [testFiles, srcFiles] = partition(diff.removed, isTestOrFixture);
     lines.push(t("diff.removed", { count: diff.removed.length }));
-    for (const f of diff.removed) {
+    for (const f of srcFiles) {
       lines.push(`  - ${f}`);
     }
+    if (testFiles.length > 0) {
+      lines.push(t("diff.testSummary", { count: testFiles.length }));
+    }
     lines.push("");
   }
   if (diff.modified.length > 0) {
+    const [testFiles, srcFiles] = partition(diff.modified, isTestOrFixture);
     lines.push(t("diff.modified", { count: diff.modified.length }));
-    for (const f of diff.modified) {
+    for (const f of srcFiles) {
       lines.push(`  ~ ${f}`);
     }
+    if (testFiles.length > 0) {
+      lines.push(t("diff.testSummary", { count: testFiles.length }));
+    }
     lines.push("");
   }
   if (diff.affectedDependents.length > 0) {
+    const [testEntries, srcEntries] = partition(
+      diff.affectedDependents,
+      (a) => isTestOrFixture(a.file) || isTestOrFixture(a.dependsOn)
+    );
     lines.push(t("diff.affected", { count: diff.affectedDependents.length }));
-    for (const a of diff.affectedDependents) {
+    for (const a of srcEntries) {
       lines.push(`  ! ${a.file}`);
       lines.push(`    ${a.reason}`);
     }
+    if (testEntries.length > 0) {
+      lines.push(t("diff.testAffectedSummary", { count: testEntries.length }));
+    }
     lines.push("");
   }
   return lines.join("\n");
@@ -2509,10 +2875,10 @@ function arraysEqual(a, b) {
 }
 
 // src/utils/path-guard.ts
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 function validatePath(inputPath, boundary) {
-  const resolved = resolve5(inputPath);
-  const root = boundary ? resolve5(boundary) : process.cwd();
+  const root = boundary ? resolve6(boundary) : process.cwd();
+  const resolved = boundary ? resolve6(root, inputPath) : resolve6(inputPath);
   if (!resolved.startsWith(root)) {
     throw new PathTraversalError(
       t("pathGuard.traversal", { input: inputPath, resolved, boundary: root })
@@ -2520,6 +2886,9 @@ function validatePath(inputPath, boundary) {
   }
   return resolved;
 }
+function resolveProjectRoot(inputPath) {
+  return resolve6(inputPath);
+}
 var PathTraversalError = class extends Error {
   constructor(message) {
     super(message);
@@ -2529,13 +2898,13 @@ var PathTraversalError = class extends Error {
 
 // src/utils/version.ts
 import { readFileSync as readFileSync3 } from "fs";
-import { join as join7, dirname as dirname2 } from "path";
+import { join as join8, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 function loadVersion() {
   let dir = dirname2(fileURLToPath(import.meta.url));
   for (let i = 0; i < 5; i++) {
     try {
-      const pkg = JSON.parse(readFileSync3(join7(dir, "package.json"), "utf-8"));
+      const pkg = JSON.parse(readFileSync3(join8(dir, "package.json"), "utf-8"));
       return pkg.version;
     } catch {
       dir = dirname2(dir);
@@ -2557,13 +2926,45 @@ var LANG_DISPLAY = {
   "c-sharp": "C#"
 };
 var languageList = LANGUAGE_IDS.map((id) => LANG_DISPLAY[id] ?? id.charAt(0).toUpperCase() + id.slice(1)).join(", ");
+var MCP_DEFAULT_EXCLUDES = [
+  "__fixtures__",
+  "__tests__",
+  "__mocks__",
+  "\\.test\\.",
+  "\\.spec\\.",
+  "\\.e2e\\."
+];
+var memoryCache = null;
+function cacheKey(opts) {
+  return JSON.stringify([opts.targetDir, opts.projectRoot, opts.language ?? "", opts.exclude ?? []]);
+}
 async function resolveGraphMcp(opts) {
-  return resolveGraph({
-    targetDir: opts.targetDir,
-    projectRoot: opts.projectRoot,
-    exclude: opts.exclude,
-    language: opts.language
+  const effectiveOpts = {
+    ...opts,
+    exclude: opts.exclude ?? MCP_DEFAULT_EXCLUDES
+  };
+  const key = cacheKey(effectiveOpts);
+  if (memoryCache && memoryCache.key === key) {
+    const result2 = await resolveGraph({
+      targetDir: effectiveOpts.targetDir,
+      projectRoot: effectiveOpts.projectRoot,
+      exclude: effectiveOpts.exclude,
+      language: effectiveOpts.language
+    });
+    if (result2.fromCache) {
+      return memoryCache.result;
+    }
+    memoryCache = { key, result: result2, timestamp: Date.now() };
+    return result2;
+  }
+  const result = await resolveGraph({
+    targetDir: effectiveOpts.targetDir,
+    projectRoot: effectiveOpts.projectRoot,
+    exclude: effectiveOpts.exclude,
+    language: effectiveOpts.language
   });
+  memoryCache = { key, result, timestamp: Date.now() };
+  return result;
 }
 function formatLayerSummary(metadata) {
   return metadata.map(
@@ -2581,11 +2982,11 @@ server.tool(
   },
   async ({ targetDir, projectRoot, exclude, language }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
       const { graph, layerMetadata, crossLayerEdges } = await resolveGraphMcp({
         targetDir,
-        projectRoot,
+        projectRoot: root,
         exclude,
         language
       });
@@ -2622,11 +3023,11 @@ server.tool(
   },
   async ({ targetDir, exclude, topN, saveSnapshot: doSave, projectRoot, language }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
       const { graph, multiLayer, layerMetadata, crossLayerEdges } = await resolveGraphMcp({
         targetDir,
-        projectRoot,
+        projectRoot: root,
         exclude,
         language
       });
@@ -2646,7 +3047,7 @@ Cross-layer connections (${crossLayerEdges.length}):
 ${crossSummary}` });
       }
       if (doSave) {
-        await saveSnapshot(projectRoot, graph, multiLayer);
+        await saveSnapshot(root, graph, multiLayer, { targetDir, language, exclude });
         content.push({ type: "text", text: t("analyze.snapshotSaved") });
       }
       return { content };
@@ -2665,14 +3066,14 @@ server.tool(
   },
   async ({ targetDir, projectRoot, language }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
       const { graph, multiLayer, layerMetadata } = await resolveGraphMcp({
         targetDir,
-        projectRoot,
+        projectRoot: root,
         language
       });
-      const snapshot = await saveSnapshot(projectRoot, graph, multiLayer);
+      const snapshot = await saveSnapshot(root, graph, multiLayer, { targetDir, language });
       const keyComponents = Object.values(graph.files).sort((a, b) => b.dependents.length - a.dependents.length).slice(0, 5).map((f) => `  ${t("cli.dependedBy", { path: f.path, count: f.dependents.length })}`);
       const report = [
         t("mcp.snapshotSaved"),
@@ -2692,24 +3093,58 @@ server.tool(
 );
 server.tool(
   "check_architecture_diff",
-  "Compare saved snapshot with current code dependencies and warn about files that may need updates",
+  "Compare saved snapshot with current code dependencies and warn about files that may need updates. Use fromTimestamp to diff against a historical snapshot, or listHistory=true to list all snapshots.",
   {
     targetDir: z3.string().default("src").describe("Target directory path"),
     projectRoot: z3.string().default(".").describe("Project root (where .archtracker is placed)"),
-    language: languageEnum.optional().describe("Target language (auto-detected if omitted)")
+    language: languageEnum.optional().describe("Target language (auto-detected if omitted)"),
+    fromTimestamp: z3.string().optional().describe("Compare from a specific historical snapshot timestamp"),
+    listHistory: z3.boolean().optional().describe("If true, list all available snapshots instead of diffing")
   },
-  async ({ targetDir, projectRoot, language }) => {
+  async ({ targetDir, projectRoot, language, fromTimestamp, listHistory }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
-      const existingSnapshot = await loadSnapshot(projectRoot);
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
+      if (listHistory) {
+        const snapshots = await listSnapshots(root);
+        if (snapshots.length === 0) {
+          return { content: [{ type: "text", text: t("history.empty") }] };
+        }
+        const lines = [
+          t("history.count", { count: snapshots.length }),
+          "",
+          ...snapshots.map((s) => {
+            const layers = s.hasMultiLayer ? " [multi-layer]" : "";
+            return t("history.entry", {
+              ts: s.timestamp,
+              files: s.totalFiles,
+              edges: s.totalEdges,
+              circular: s.circularDeps,
+              layers
+            });
+          })
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+      let existingSnapshot;
+      if (fromTimestamp) {
+        existingSnapshot = await loadSnapshotByTimestamp(root, fromTimestamp);
+        if (!existingSnapshot) {
+          return {
+            content: [{ type: "text", text: t("history.snapshotNotFound", { ts: fromTimestamp }) }],
+            isError: true
+          };
+        }
+      } else {
+        existingSnapshot = await loadSnapshot(root);
+      }
       if (!existingSnapshot) {
         const { graph, multiLayer } = await resolveGraphMcp({
           targetDir,
-          projectRoot,
+          projectRoot: root,
           language
         });
-        await saveSnapshot(projectRoot, graph, multiLayer);
+        await saveSnapshot(root, graph, multiLayer, { targetDir, language });
         return {
           content: [
             {
@@ -2725,7 +3160,7 @@ server.tool(
       }
       const { graph: currentGraph } = await resolveGraphMcp({
         targetDir,
-        projectRoot,
+        projectRoot: root,
         language
       });
       const diff = computeDiff(existingSnapshot.graph, currentGraph);
@@ -2746,18 +3181,14 @@ server.tool(
   },
   async ({ targetDir, projectRoot, language }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
-      let snapshot = await loadSnapshot(projectRoot);
-      if (!snapshot) {
-        const { graph: graph2, multiLayer } = await resolveGraphMcp({
-          targetDir,
-          projectRoot,
-          language
-        });
-        snapshot = await saveSnapshot(projectRoot, graph2, multiLayer);
-      }
-      const graph = snapshot.graph;
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
+      const { graph } = await resolveGraphMcp({
+        targetDir,
+        projectRoot: root,
+        language
+      });
+      const existingSnapshot = await loadSnapshot(root);
       const keyComponents = Object.values(graph.files).filter((f) => f.dependents.length > 0 || f.dependencies.length > 0).sort((a, b) => b.dependents.length - a.dependents.length).slice(0, 20).map((f) => ({
         path: f.path,
         dependentCount: f.dependents.length,
@@ -2769,7 +3200,7 @@ server.tool(
         t("cli.fileCount", { count: graph.totalFiles }),
         t("cli.edgeCount", { count: graph.totalEdges }),
         t("cli.circularCount", { count: graph.circularDependencies.length }),
-        t("cli.snapshot", { ts: snapshot.timestamp }),
+        ...existingSnapshot ? [t("cli.snapshot", { ts: existingSnapshot.timestamp })] : [],
         "",
         t("cli.keyComponents"),
         ...keyComponents.map(
@@ -2779,8 +3210,8 @@ server.tool(
       const context = {
         validPaths,
         summary,
-        snapshotExists: true,
-        snapshotTimestamp: snapshot.timestamp,
+        snapshotExists: existingSnapshot !== null,
+        snapshotTimestamp: existingSnapshot?.timestamp,
         keyComponents
       };
       return {
@@ -2812,18 +3243,13 @@ server.tool(
   },
   async ({ query, mode, targetDir, projectRoot, limit, language }) => {
     try {
-      validatePath(targetDir);
-      validatePath(projectRoot);
-      let snapshot = await loadSnapshot(projectRoot);
-      if (!snapshot) {
-        const { graph: graph2, multiLayer } = await resolveGraphMcp({
-          targetDir,
-          projectRoot,
-          language
-        });
-        snapshot = await saveSnapshot(projectRoot, graph2, multiLayer);
-      }
-      const graph = snapshot.graph;
+      const root = resolveProjectRoot(projectRoot);
+      validatePath(targetDir, root);
+      const { graph } = await resolveGraphMcp({
+        targetDir,
+        projectRoot: root,
+        language
+      });
       const maxResults = limit ?? 10;
       let results;
       if ((mode === "path" || mode === "affected") && !query) {