codecortex-ai 0.4.2 → 0.4.4

package/README.md

@@ -1,6 +1,9 @@
 # CodeCortex
 
-> Persistent codebase knowledge layer for AI agents. Your AI shouldn't re-learn your codebase every session.
+Persistent codebase knowledge layer for AI agents. Your AI shouldn't re-learn your codebase every session.
+
+> **⚠️ If you're on v0.4.3 or earlier, update now:** `npm install -g codecortex-ai@latest`
+> v0.4.4 adds freshness flags on all MCP responses and `get_edit_briefing` — a pre-edit risk briefing tool.
 
 [Website](https://codecortex-ai.vercel.app) · [npm](https://www.npmjs.com/package/codecortex-ai) · [GitHub](https://github.com/rushikeshmore/CodeCortex)
 
@@ -13,7 +16,7 @@
 Every AI coding session starts from scratch. When context compacts or a new session begins, the AI re-scans the entire codebase. Same files, same tokens, same wasted time. It's like hiring a new developer every session who has to re-learn everything before writing a single line.
 
 **The data backs this up:**
-- AI agents increase defect risk by 30% on unfamiliar code ([CodeScene + Lund University, 2025](https://codescene.com/hubfs/whitepapers/AI-Coding-Assistants-and-Code-Quality.pdf))
+- AI agents increase defect risk by 30% on unfamiliar code ([CodeScene + Lund University, 2025](https://codescene.com/hubfs/whitepapers/AI-Ready-Code-How-Code-Health-Determines-AI-Performance.pdf))
 - Code churn grew 2.5x in the AI era ([GitClear, 211M lines analyzed](https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality))
 - Nobody combines structural + semantic + temporal + decision knowledge in one portable tool
 
@@ -25,9 +28,11 @@ CodeCortex pre-digests codebases into layered knowledge files and serves them to
 
 ## Quick Start
 
+> **Requires Node 20 or 22.** Node 24 is not yet supported (tree-sitter native bindings need an upstream update).
+
 ```bash
-# Install
-npm install -g codecortex-ai
+# Install (--legacy-peer-deps needed for tree-sitter peer dep mismatches)
+npm install -g codecortex-ai --legacy-peer-deps
 
 # Initialize knowledge for your project
 cd /path/to/your-project
@@ -93,9 +98,9 @@ Example from a real codebase:
 - `routes.ts` and `worker.ts` co-changed in 9/12 commits (75%) with **zero imports between them**
 - Without this knowledge, an AI editing one file would produce a bug 75% of the time
 
-## MCP Tools (14)
+## MCP Tools (15)
 
-### Read Tools (9)
+### Read Tools (10)
 
 | Tool | Description |
 |------|-------------|
@@ -108,6 +113,9 @@ Example from a real codebase:
 | `lookup_symbol` | Symbol by name/file/kind |
 | `get_change_coupling` | What files must I also edit if I touch X? |
 | `get_hotspots` | Files ranked by risk (churn x coupling) |
+| `get_edit_briefing` | **NEW** — Pre-edit risk briefing: co-change warnings, hidden deps, bug history, importers |
+
+All read tools include `_freshness` metadata indicating how up-to-date the knowledge is.
 
 ### Write Tools (5)
 
@@ -148,7 +156,7 @@ vs. raw scan of entire codebase:    ~37,800 tokens
 
 85-90% token reduction. 7-10x efficiency gain.
 
-## Supported Languages (28)
+## Supported Languages (27)
 
 | Category | Languages |
 |----------|-----------|
@@ -172,4 +180,4 @@ vs. raw scan of entire codebase:    ~37,800 tokens
 
 ## License
 
-MIT
+MIT

package/dist/{chunk-PBYRGMCK.js → chunk-4N3T43UG.js}

@@ -197,6 +197,9 @@ function getModuleDependencies(graph, moduleName) {
     calls: graph.calls.filter((e) => moduleFiles.has(e.file))
   };
 }
+function getFileImporters(graph, file) {
+  return graph.imports.filter((e) => e.target.includes(file)).map((e) => e.source);
+}
 function getMostImportedFiles(graph, limit = 10) {
   const counts = /* @__PURE__ */ new Map();
   for (const edge of graph.imports) {
@@ -212,6 +215,9 @@ function enrichCouplingWithImports(graph, coupling) {
   for (const pair of coupling) {
     const key = [pair.fileA, pair.fileB].sort().join("|");
     pair.hasImport = importPairs.has(key);
+    if (pair.strength >= 0.7 && !pair.hasImport) {
+      pair.warning = `HIDDEN DEPENDENCY \u2014 ${Math.round(pair.strength * 100)}% co-change rate`;
+    }
   }
 }
 
@@ -456,11 +462,159 @@ async function getAllCortexFiles(dir) {
   return files;
 }
 
+// src/git/diff.ts
+import simpleGit from "simple-git";
+async function getUncommittedDiff(root) {
+  const git = simpleGit(root);
+  const diff = await git.diffSummary();
+  return {
+    filesChanged: diff.files.map((f) => f.file),
+    insertions: diff.insertions,
+    deletions: diff.deletions,
+    summary: `${diff.files.length} files changed, +${diff.insertions} -${diff.deletions}`
+  };
+}
+async function getChangedFilesSinceDate(root, sinceDate) {
+  const git = simpleGit(root);
+  const log = await git.log({ "--since": sinceDate, "--name-only": null });
+  const files = /* @__PURE__ */ new Set();
+  for (const commit of log.all) {
+    const diff = commit.diff;
+    if (diff) {
+      for (const file of diff.files) {
+        files.add(file.file);
+      }
+    }
+  }
+  return [...files];
+}
+function mapFilesToModules(files) {
+  const moduleMap = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const parts = file.split("/");
+    let module = "root";
+    if (parts[0] === "src" && parts.length >= 3 && parts[1]) {
+      module = parts[1];
+    } else if (parts[0] === "lib" && parts.length >= 3 && parts[1]) {
+      module = parts[1];
+    }
+    const existing = moduleMap.get(module) || [];
+    existing.push(file);
+    moduleMap.set(module, existing);
+  }
+  return moduleMap;
+}
+
+// src/git/history.ts
+import simpleGit2 from "simple-git";
+async function getCommitHistory(root, days = 90) {
+  const git = simpleGit2(root);
+  const since = new Date(Date.now() - days * 24 * 60 * 60 * 1e3).toISOString().split("T")[0];
+  const log = await git.log({
+    "--since": since,
+    "--stat": null,
+    maxCount: 500
+  });
+  return log.all.map((commit) => ({
+    hash: commit.hash,
+    date: commit.date,
+    message: commit.message,
+    author: commit.author_name,
+    filesChanged: parseStatFiles(commit.diff)
+  }));
+}
+function parseStatFiles(diff) {
+  if (!diff || !diff.files) return [];
+  return diff.files.map((f) => f.file);
+}
+async function isGitRepo(root) {
+  const git = simpleGit2(root);
+  try {
+    await git.status();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getHeadCommit(root) {
+  const git = simpleGit2(root);
+  try {
+    const log = await git.log({ maxCount: 1 });
+    return log.latest?.hash || null;
+  } catch {
+    return null;
+  }
+}
+
+// src/core/freshness.ts
+async function computeFreshness(projectRoot) {
+  const manifest = await readManifest(projectRoot);
+  if (!manifest) return null;
+  const lastUpdated = manifest.lastUpdated;
+  if (!lastUpdated) return null;
+  const isRepo = await isGitRepo(projectRoot);
+  let changedFiles = [];
+  if (isRepo) {
+    try {
+      changedFiles = await getChangedFilesSinceDate(projectRoot, lastUpdated);
+      changedFiles = changedFiles.filter((f) => {
+        const base = f.split("/").pop() ?? "";
+        return !base.endsWith(".lock") && base !== "package-lock.json" && base !== "yarn.lock" && base !== "pnpm-lock.yaml" && base !== "CHANGELOG.md" && !f.startsWith(".codecortex/");
+      });
+    } catch {
+      changedFiles = [];
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  const analyzed = new Date(lastUpdated);
+  const daysSinceAnalysis = Math.floor((now.getTime() - analyzed.getTime()) / (1e3 * 60 * 60 * 24));
+  const count = changedFiles.length;
+  let status;
+  let message;
+  if (count === 0 && daysSinceAnalysis <= 7) {
+    status = "fresh";
+    message = "Knowledge is up to date.";
+  } else if (count <= 2 && daysSinceAnalysis <= 7) {
+    status = "slightly_stale";
+    message = `${count} file${count === 1 ? "" : "s"} changed since last analysis. Minor drift.`;
+  } else if (count <= 5 || daysSinceAnalysis <= 14) {
+    status = "stale";
+    message = `${count} file${count === 1 ? "" : "s"} changed since last analysis. Consider running \`codecortex update\`.`;
+  } else {
+    status = "very_stale";
+    message = `${count} files changed over ${daysSinceAnalysis} days since last analysis. Run \`codecortex update\` before trusting this knowledge.`;
+  }
+  return {
+    status,
+    lastAnalyzed: lastUpdated,
+    daysSinceAnalysis,
+    filesChangedSince: count,
+    changedFiles: changedFiles.slice(0, 20),
+    // Cap to avoid bloating response
+    message
+  };
+}
+
 // src/mcp/tools/read.ts
 function textResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function withFreshness(data, freshness) {
+  if (!freshness) return data;
+  return { ...data, _freshness: freshness };
+}
 function registerReadTools(server, projectRoot) {
+  let cachedFreshness = null;
+  const FRESHNESS_TTL_MS = 6e4;
+  async function getFreshness() {
+    const now = Date.now();
+    if (cachedFreshness && now - cachedFreshness.timestamp < FRESHNESS_TTL_MS) {
+      return cachedFreshness.info;
+    }
+    const info = await computeFreshness(projectRoot);
+    cachedFreshness = { info, timestamp: now };
+    return info;
+  }
   server.registerTool(
     "get_project_overview",
     {
@@ -481,12 +635,13 @@ function registerReadTools(server, projectRoot) {
           mostImported: getMostImportedFiles(graph, 5)
         };
       }
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         constitution,
         overview,
         manifest,
         graphSummary
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -508,7 +663,8 @@ function registerReadTools(server, projectRoot) {
       if (graph) {
         deps = getModuleDependencies(graph, name);
       }
-      return textResult({ found: true, name, doc, dependencies: deps });
+      const freshness = await getFreshness();
+      return textResult(withFreshness({ found: true, name, doc, dependencies: deps }, freshness));
     }
   );
   server.registerTool(
@@ -524,12 +680,13 @@ function registerReadTools(server, projectRoot) {
       }
       const session = await readSession(projectRoot, latestId);
       const allSessions = await listSessions(projectRoot);
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         hasSession: true,
         latest: session,
         totalSessions: allSessions.length,
         recentSessionIds: allSessions.slice(0, 5)
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -542,11 +699,12 @@ function registerReadTools(server, projectRoot) {
     },
     async ({ query }) => {
       const results = await searchKnowledge(projectRoot, query);
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         query,
         totalResults: results.length,
         results: results.slice(0, 20)
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -568,11 +726,12 @@ function registerReadTools(server, projectRoot) {
           }
         }
       }
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         total: decisions.length,
         topic: topic || "all",
         decisions
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -587,16 +746,17 @@ function registerReadTools(server, projectRoot) {
     async ({ file, module }) => {
       const graph = await readGraph(projectRoot);
       if (!graph) return textResult({ found: false, message: "No graph data. Run codecortex init first." });
+      const freshness = await getFreshness();
       if (module) {
         const deps = getModuleDependencies(graph, module);
-        return textResult({ module, ...deps });
+        return textResult(withFreshness({ module, ...deps }, freshness));
       }
       if (file) {
         const imports = graph.imports.filter((e) => e.source.includes(file) || e.target.includes(file));
         const calls = graph.calls.filter((e) => e.file.includes(file));
-        return textResult({ file, imports, calls });
+        return textResult(withFreshness({ file, imports, calls }, freshness));
       }
-      return textResult(graph);
+      return textResult(withFreshness(graph, freshness));
     }
   );
   server.registerTool(
@@ -618,11 +778,12 @@ function registerReadTools(server, projectRoot) {
       );
       if (kind) matches = matches.filter((s) => s.kind === kind);
       if (file) matches = matches.filter((s) => s.file.includes(file));
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         query: { name, kind, file },
         totalMatches: matches.length,
         symbols: matches.slice(0, 30)
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -644,12 +805,13 @@ function registerReadTools(server, projectRoot) {
           (c) => c.fileA.includes(file) || c.fileB.includes(file)
         );
       }
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         file: file || "all",
         minStrength,
         couplings: coupling,
         warning: coupling.filter((c) => !c.hasImport).length > 0 ? "HIDDEN DEPENDENCIES FOUND \u2014 some coupled files have NO import between them" : null
-      });
+      }, freshness));
     }
   );
   server.registerTool(
@@ -683,14 +845,104 @@ function registerReadTools(server, projectRoot) {
         riskMap.set(b.file, entry);
       }
       const ranked = [...riskMap.entries()].sort((a, b) => b[1].risk - a[1].risk).slice(0, limit).map(([file, data]) => ({ file, ...data, risk: Math.round(data.risk * 100) / 100 }));
-      return textResult({
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
         period: `${temporal.periodDays} days`,
         totalCommits: temporal.totalCommits,
         hotspots: ranked
+      }, freshness));
+    }
+  );
+  server.registerTool(
+    "get_edit_briefing",
+    {
+      description: "CALL THIS BEFORE EDITING FILES. Takes a list of files you plan to edit and returns everything you need to know: co-change warnings (files you must also update), risk assessment, who imports these files, relevant patterns, and recent change history. Prevents bugs from hidden dependencies.",
+      inputSchema: {
+        files: z.array(z.string()).min(1).describe("File paths you plan to edit (relative to project root)")
+      }
+    },
+    async ({ files }) => {
+      const temporalContent = await readFile(cortexPath(projectRoot, "temporal.json"));
+      if (!temporalContent) return textResult({ found: false, message: "No temporal data. Run codecortex init first." });
+      const temporal = JSON.parse(temporalContent);
+      const graph = await readGraph(projectRoot);
+      const patternsContent = await readFile(cortexPath(projectRoot, "patterns.md"));
+      const briefings = files.map((file) => {
+        const couplings = temporal.coupling.filter((c) => c.fileA.includes(file) || c.fileB.includes(file)).map((c) => {
+          const other = c.fileA.includes(file) ? c.fileB : c.fileA;
+          return {
+            file: other,
+            cochanges: c.cochanges,
+            strength: c.strength,
+            hasImport: c.hasImport,
+            warning: c.warning || null
+          };
+        }).sort((a, b) => b.strength - a.strength);
+        const hotspot = temporal.hotspots.find((h) => h.file.includes(file));
+        const bugs = temporal.bugHistory.find((b) => b.file.includes(file));
+        const couplingCount = couplings.length;
+        const hiddenDeps = couplings.filter((c) => !c.hasImport).length;
+        let riskLevel = "LOW";
+        const riskScore = (hotspot?.changes || 0) + couplingCount * 2 + (bugs?.fixCommits || 0) * 3 + hiddenDeps * 4;
+        if (riskScore >= 20) riskLevel = "CRITICAL";
+        else if (riskScore >= 12) riskLevel = "HIGH";
+        else if (riskScore >= 6) riskLevel = "MEDIUM";
+        let importedBy = [];
+        if (graph) {
+          importedBy = getFileImporters(graph, file);
+        }
+        const recentChange = hotspot ? {
+          lastChanged: hotspot.lastChanged,
+          daysSinceChange: hotspot.daysSinceChange,
+          totalChanges: hotspot.changes,
+          stability: hotspot.stability
+        } : null;
+        const bugHistory = bugs ? {
+          fixCommits: bugs.fixCommits,
+          lessons: bugs.lessons
+        } : null;
+        return {
+          file,
+          risk: {
+            level: riskLevel,
+            score: Math.round(riskScore * 100) / 100,
+            reason: buildRiskReason(riskLevel, hotspot, couplingCount, hiddenDeps, bugs)
+          },
+          cochangeWarnings: couplings,
+          importedBy,
+          recentChange,
+          bugHistory
+        };
       });
+      const inputSet = new Set(files);
+      const alsoConsider = /* @__PURE__ */ new Set();
+      for (const b of briefings) {
+        for (const c of b.cochangeWarnings) {
+          const coupledFile = c.file;
+          const isInInput = files.some((f) => coupledFile.includes(f) || f.includes(coupledFile));
+          if (!isInInput && c.strength >= 0.5) {
+            alsoConsider.add(`${coupledFile} (${Math.round(c.strength * 100)}% co-change with ${b.file}${c.hasImport ? "" : ", NO import \u2014 hidden dep"})`);
+          }
+        }
+      }
+      const freshness = await getFreshness();
+      return textResult(withFreshness({
+        briefings,
+        alsoConsiderEditing: [...alsoConsider],
+        patterns: patternsContent || null
+      }, freshness));
     }
   );
 }
+function buildRiskReason(level, hotspot, couplings, hiddenDeps, bugs) {
+  if (level === "LOW") return "Low change frequency, few couplings.";
+  const parts = [];
+  if (hotspot && hotspot.changes >= 5) parts.push(`${hotspot.changes} changes (${hotspot.stability})`);
+  if (couplings > 0) parts.push(`${couplings} coupled file${couplings === 1 ? "" : "s"}`);
+  if (hiddenDeps > 0) parts.push(`${hiddenDeps} hidden dep${hiddenDeps === 1 ? "" : "s"}`);
+  if (bugs && bugs.fixCommits > 0) parts.push(`${bugs.fixCommits} bug-fix commit${bugs.fixCommits === 1 ? "" : "s"}`);
+  return parts.join(", ") + ".";
+}
 
 // src/mcp/tools/write.ts
 import { z as z3 } from "zod";
@@ -916,7 +1168,7 @@ function registerWriteTools(server, projectRoot) {
 function createServer(projectRoot) {
   const server = new McpServer({
     name: "codecortex",
-    version: "0.4.2",
+    version: "0.4.4",
     description: "Persistent codebase knowledge layer. Pre-digested architecture, symbols, coupling, and patterns served to AI agents."
   });
   registerReadTools(server, projectRoot);
@@ -956,12 +1208,17 @@ export {
   writeModuleDoc,
   listModuleDocs,
   listDecisions,
+  getCommitHistory,
+  isGitRepo,
+  getHeadCommit,
   writeSession,
   listSessions,
   getLatestSession,
   createSession,
   searchKnowledge,
+  getUncommittedDiff,
+  mapFilesToModules,
   createServer,
   startServer
 };
-//# sourceMappingURL=chunk-PBYRGMCK.js.map
+//# sourceMappingURL=chunk-4N3T43UG.js.map