@liendev/lien 0.16.0 → 0.17.0

package/CURSOR_RULES_TEMPLATE.md

@@ -17,6 +17,7 @@ You have access to Lien semantic search tools. USE THEM INSTEAD OF grep/ripgrep/
 | "Find all Controllers" | `list_functions` | grep |
 | Edit a file | `get_files_context` FIRST | direct edit |
 | Find similar code | `find_similar` | manual search |
+| "What depends on this file?" | `get_dependents` | manual grep |
 
 ## Before ANY Code Change
 
@@ -35,9 +36,11 @@ REQUIRED sequence:
 
 **`get_files_context({ filepaths: "path/to/file.ts" })`** or **`get_files_context({ filepaths: ["file1.ts", "file2.ts"] })`**
 - MANDATORY before editing any file
-- Returns `testAssociations`: which tests cover this file
+- Returns `testAssociations`: which tests import/cover this file (reverse dependency lookup)
 - Shows file dependencies and relationships
 - Accepts single filepath or array of filepaths for batch operations
+- Single file returns: `{ file: string, chunks: [], testAssociations: [] }`
+- Multiple files returns: `{ files: { [path]: { chunks: [], testAssociations: [] } } }`
 
 **`list_functions({ pattern: ".*Controller.*" })`**
 - Fast symbol lookup by naming pattern
@@ -48,11 +51,30 @@ REQUIRED sequence:
 - Find similar implementations for consistency
 - Use when refactoring or detecting duplication
 
+**`get_dependents({ filepath: "path/to/file.ts", depth: 1 })`**
+- Find all files that import/depend on a target file
+- Use for impact analysis: "What breaks if I change this?"
+- Returns risk level (low/medium/high/critical) based on:
+  - Dependency count (how many files import it)
+  - Complexity metrics (how complex the dependent code is)
+- Highlights top 5 most complex dependents when complexity data available
+
 ## Test Associations
 
-`get_files_context` returns `testAssociations` showing which tests cover the file.
-ALWAYS check this before modifying source code.
-After changes, remind the user: "This file is covered by [test files] - run these to verify."
+`get_files_context` returns `testAssociations` showing which tests import/cover the file.
+- Uses reverse dependency lookup to find test files that import the source file
+- Returns array of test file paths for each requested file
+- ALWAYS check this before modifying source code
+- After changes, remind the user: "This file is covered by [test files] - run these to verify."
+
+Example:
+```typescript
+get_files_context({ filepaths: "src/auth.ts" })
+// Returns: { file: "src/auth.ts", chunks: [...], testAssociations: ["src/__tests__/auth.test.ts"] }
+
+get_files_context({ filepaths: ["src/auth.ts", "src/user.ts"] })
+// Returns: { files: { "src/auth.ts": { chunks: [...], testAssociations: [...] }, ... } }
+```
 
 ## Workflow Patterns
 
@@ -73,6 +95,15 @@ After changes, remind the user: "This file is covered by [test files] - run thes
 5. Tell user which tests to run
 ```
 
+### Pattern 3: Impact Analysis Before Refactoring
+```
+1. get_dependents({ filepath: "target/file.ts" })
+2. Review risk level and dependent count
+3. Check highComplexityDependents (if any)
+4. Use get_files_context on high-risk dependents
+5. Plan refactoring strategy based on impact
+```
+
 ## Query Construction
 
 ### Good Queries (DO THIS)

package/dist/index.js

@@ -5688,6 +5688,17 @@ var ListFunctionsSchema = z4.object({
   )
 });
 
+// src/mcp/schemas/dependents.schema.ts
+import { z as z5 } from "zod";
+var GetDependentsSchema = z5.object({
+  filepath: z5.string().min(1, "Filepath cannot be empty").describe(
+    "Path to file to find dependents for (relative to workspace root).\n\nExample: 'src/utils/validate.ts'\n\nReturns all files that import or depend on this file.\n\nNote: Scans up to 10,000 code chunks. For very large codebases,\nresults may be incomplete (a warning will be included if truncated)."
+  ),
+  depth: z5.number().int().min(1).max(1).default(1).describe(
+    "Depth of transitive dependencies. Only depth=1 (direct dependents) is currently supported.\n\n1 = Direct dependents only"
+  )
+});
+
 // src/mcp/tools.ts
 var tools = [
   toMCPToolSchema(
@@ -5722,15 +5733,39 @@ MANDATORY: Call this BEFORE editing any file. Accepts single path or array of pa
 
 Single file:
   get_files_context({ filepaths: "src/auth.ts" })
+  
+  Returns:
+  {
+    file: "src/auth.ts",
+    chunks: [...],
+    testAssociations: ["src/__tests__/auth.test.ts"]
+  }
 
 Multiple files (batch):
   get_files_context({ filepaths: ["src/auth.ts", "src/user.ts"] })
+  
+  Returns:
+  {
+    files: {
+      "src/auth.ts": {
+        chunks: [...],
+        testAssociations: ["src/__tests__/auth.test.ts"]
+      },
+      "src/user.ts": {
+        chunks: [...],
+        testAssociations: ["src/__tests__/user.test.ts"]
+      }
+    }
+  }
 
 Returns for each file:
 - All chunks and related code
-- testAssociations (which tests cover this file)
+- testAssociations: Array of test files that import this file (reverse dependency lookup)
 - Relevance scoring
 
+ALWAYS check testAssociations before modifying source code.
+After changes, remind the user to run the associated tests.
+
 Batch calls are more efficient than multiple single-file calls.`
   ),
   toMCPToolSchema(
@@ -5743,6 +5778,20 @@ Examples:
 - "Find service classes" \u2192 list_functions({ pattern: ".*Service$" })
 
 10x faster than semantic_search for structural/architectural queries. Use semantic_search instead when searching by what code DOES.`
+  ),
+  toMCPToolSchema(
+    GetDependentsSchema,
+    "get_dependents",
+    `Find all code that depends on a file (reverse dependency lookup). Use for impact analysis:
+- "What breaks if I change this?"
+- "Is this safe to delete?"
+- "What imports this module?"
+
+Returns:
+- List of files that import the target
+- Risk level (low/medium/high/critical) based on dependent count and complexity
+
+Example: get_dependents({ filepath: "src/utils/validate.ts" })`
   )
 ];
 
@@ -5942,6 +5991,50 @@ function wrapToolHandler(schema, handler) {
   };
 }
 
+// src/mcp/utils/path-matching.ts
+function normalizePath(path18, workspaceRoot) {
+  let normalized = path18.replace(/['"]/g, "").trim().replace(/\\/g, "/");
+  normalized = normalized.replace(/\.(ts|tsx|js|jsx)$/, "");
+  if (normalized.startsWith(workspaceRoot + "/")) {
+    normalized = normalized.substring(workspaceRoot.length + 1);
+  }
+  return normalized;
+}
+function matchesAtBoundary(str, pattern) {
+  const index = str.indexOf(pattern);
+  if (index === -1) return false;
+  const charBefore = index > 0 ? str[index - 1] : "/";
+  if (charBefore !== "/" && index !== 0) return false;
+  const endIndex = index + pattern.length;
+  if (endIndex === str.length) return true;
+  const charAfter = str[endIndex];
+  return charAfter === "/";
+}
+function matchesFile(normalizedImport, normalizedTarget) {
+  if (normalizedImport === normalizedTarget) return true;
+  if (matchesAtBoundary(normalizedImport, normalizedTarget)) {
+    return true;
+  }
+  if (matchesAtBoundary(normalizedTarget, normalizedImport)) {
+    return true;
+  }
+  const cleanedImport = normalizedImport.replace(/^(\.\.?\/)+/, "");
+  if (matchesAtBoundary(cleanedImport, normalizedTarget) || matchesAtBoundary(normalizedTarget, cleanedImport)) {
+    return true;
+  }
+  return false;
+}
+function getCanonicalPath(filepath, workspaceRoot) {
+  let canonical = filepath.replace(/\\/g, "/");
+  if (canonical.startsWith(workspaceRoot + "/")) {
+    canonical = canonical.substring(workspaceRoot.length + 1);
+  }
+  return canonical;
+}
+function isTestFile2(filepath) {
+  return /\.(test|spec)\.[^/]+$/.test(filepath) || /(^|[/\\])(test|tests|__tests__)[/\\]/.test(filepath);
+}
+
 // src/mcp/server.ts
 init_errors();
 var __filename4 = fileURLToPath4(import.meta.url);
@@ -5953,6 +6046,31 @@ try {
 } catch {
   packageJson3 = require4(join3(__dirname4, "../../package.json"));
 }
+var DEPENDENT_COUNT_THRESHOLDS = {
+  LOW: 5,
+  // Few dependents, safe to change
+  MEDIUM: 15,
+  // Moderate impact, review dependents
+  HIGH: 30
+  // High impact, careful planning needed
+};
+var COMPLEXITY_THRESHOLDS = {
+  HIGH_COMPLEXITY_DEPENDENT: 10,
+  // Individual file is complex
+  CRITICAL_AVG: 15,
+  // Average complexity indicates systemic complexity
+  CRITICAL_MAX: 25,
+  // Peak complexity indicates hotspot
+  HIGH_AVG: 10,
+  // Moderately complex on average
+  HIGH_MAX: 20,
+  // Some complex functions exist
+  MEDIUM_AVG: 6,
+  // Slightly above simple code
+  MEDIUM_MAX: 15
+  // Occasional branching
+};
+var SCAN_LIMIT = 1e4;
 async function startMCPServer(options) {
   const { rootDir, verbose, watch } = options;
   const log = (message) => {
@@ -6049,6 +6167,7 @@ async function startMCPServer(options) {
               const isSingleFile = !Array.isArray(validatedArgs.filepaths);
               log(`Getting context for: ${filepaths.join(", ")}`);
               await checkAndReconnect();
+              const workspaceRoot = process.cwd().replace(/\\/g, "/");
               const fileEmbeddings = await Promise.all(filepaths.map((fp) => embeddings.embed(fp)));
               const allFileSearches = await Promise.all(
                 fileEmbeddings.map(
@@ -6057,9 +6176,11 @@ async function startMCPServer(options) {
               );
               const fileChunksMap = filepaths.map((filepath, i) => {
                 const allResults = allFileSearches[i];
-                return allResults.filter(
-                  (r) => r.metadata.file.includes(filepath) || filepath.includes(r.metadata.file)
-                );
+                const targetCanonical = getCanonicalPath(filepath, workspaceRoot);
+                return allResults.filter((r) => {
+                  const chunkCanonical = getCanonicalPath(r.metadata.file, workspaceRoot);
+                  return chunkCanonical === targetCanonical;
+                });
               });
               let relatedChunksMap = [];
               if (validatedArgs.includeRelated) {
@@ -6076,18 +6197,57 @@ async function startMCPServer(options) {
                   relatedChunksMap = Array.from({ length: filepaths.length }, () => []);
                   filesWithChunks.forEach(({ filepath, index }, i) => {
                     const related = relatedSearches[i];
-                    relatedChunksMap[index] = related.filter(
-                      (r) => !r.metadata.file.includes(filepath) && !filepath.includes(r.metadata.file)
-                    );
+                    const targetCanonical = getCanonicalPath(filepath, workspaceRoot);
+                    relatedChunksMap[index] = related.filter((r) => {
+                      const chunkCanonical = getCanonicalPath(r.metadata.file, workspaceRoot);
+                      return chunkCanonical !== targetCanonical;
+                    });
                   });
                 }
               }
+              const allChunks = await vectorDB.scanWithFilter({ limit: SCAN_LIMIT });
+              if (allChunks.length === SCAN_LIMIT) {
+                log(`WARNING: Scanned ${SCAN_LIMIT} chunks (limit reached). Test associations may be incomplete for large codebases.`);
+              }
+              const pathCache = /* @__PURE__ */ new Map();
+              const normalizePathCached = (path18) => {
+                if (pathCache.has(path18)) return pathCache.get(path18);
+                const normalized = normalizePath(path18, workspaceRoot);
+                pathCache.set(path18, normalized);
+                return normalized;
+              };
+              const testAssociationsMap = filepaths.map((filepath) => {
+                const normalizedTarget = normalizePathCached(filepath);
+                const testFiles = /* @__PURE__ */ new Set();
+                for (const chunk of allChunks) {
+                  const chunkFile2 = getCanonicalPath(chunk.metadata.file, workspaceRoot);
+                  if (!isTestFile2(chunkFile2)) continue;
+                  const imports = chunk.metadata.imports || [];
+                  for (const imp of imports) {
+                    const normalizedImport = normalizePathCached(imp);
+                    if (matchesFile(normalizedImport, normalizedTarget)) {
+                      testFiles.add(chunkFile2);
+                      break;
+                    }
+                  }
+                }
+                return Array.from(testFiles);
+              });
               const filesData = {};
               filepaths.forEach((filepath, i) => {
                 const fileChunks = fileChunksMap[i];
                 const relatedChunks = relatedChunksMap[i] || [];
+                const seenChunks = /* @__PURE__ */ new Set();
+                const dedupedChunks = [...fileChunks, ...relatedChunks].filter((chunk) => {
+                  const canonicalFile = getCanonicalPath(chunk.metadata.file, workspaceRoot);
+                  const chunkId = `${canonicalFile}:${chunk.metadata.startLine}-${chunk.metadata.endLine}`;
+                  if (seenChunks.has(chunkId)) return false;
+                  seenChunks.add(chunkId);
+                  return true;
+                });
                 filesData[filepath] = {
-                  chunks: [...fileChunks, ...relatedChunks]
+                  chunks: dedupedChunks,
+                  testAssociations: testAssociationsMap[i]
                 };
               });
               log(`Found ${Object.values(filesData).reduce((sum, f) => sum + f.chunks.length, 0)} total chunks`);
@@ -6096,7 +6256,8 @@ async function startMCPServer(options) {
                 return {
                   indexInfo: getIndexMetadata(),
                   file: filepath,
-                  chunks: filesData[filepath].chunks
+                  chunks: filesData[filepath].chunks,
+                  testAssociations: filesData[filepath].testAssociations
                 };
               } else {
                 return {
@@ -6147,6 +6308,144 @@ async function startMCPServer(options) {
               };
             }
           )(args);
+        case "get_dependents":
+          return await wrapToolHandler(
+            GetDependentsSchema,
+            async (validatedArgs) => {
+              log(`Finding dependents of: ${validatedArgs.filepath}`);
+              await checkAndReconnect();
+              const allChunks = await vectorDB.scanWithFilter({ limit: SCAN_LIMIT });
+              if (allChunks.length === SCAN_LIMIT) {
+                log(`WARNING: Scanned ${SCAN_LIMIT} chunks (limit reached). Results may be incomplete for large codebases.`);
+              }
+              log(`Scanning ${allChunks.length} chunks for imports...`);
+              const workspaceRoot = process.cwd().replace(/\\/g, "/");
+              const pathCache = /* @__PURE__ */ new Map();
+              const normalizePathCached = (path18) => {
+                if (pathCache.has(path18)) return pathCache.get(path18);
+                const normalized = normalizePath(path18, workspaceRoot);
+                pathCache.set(path18, normalized);
+                return normalized;
+              };
+              const importIndex = /* @__PURE__ */ new Map();
+              for (const chunk of allChunks) {
+                const imports = chunk.metadata.imports || [];
+                for (const imp of imports) {
+                  const normalizedImport = normalizePathCached(imp);
+                  if (!importIndex.has(normalizedImport)) {
+                    importIndex.set(normalizedImport, []);
+                  }
+                  importIndex.get(normalizedImport).push(chunk);
+                }
+              }
+              const normalizedTarget = normalizePathCached(validatedArgs.filepath);
+              const dependentChunks = [];
+              const seenChunkIds = /* @__PURE__ */ new Set();
+              if (importIndex.has(normalizedTarget)) {
+                for (const chunk of importIndex.get(normalizedTarget)) {
+                  const chunkId = `${chunk.metadata.file}:${chunk.metadata.startLine}-${chunk.metadata.endLine}`;
+                  if (!seenChunkIds.has(chunkId)) {
+                    dependentChunks.push(chunk);
+                    seenChunkIds.add(chunkId);
+                  }
+                }
+              }
+              for (const [normalizedImport, chunks] of importIndex.entries()) {
+                if (normalizedImport !== normalizedTarget && matchesFile(normalizedImport, normalizedTarget)) {
+                  for (const chunk of chunks) {
+                    const chunkId = `${chunk.metadata.file}:${chunk.metadata.startLine}-${chunk.metadata.endLine}`;
+                    if (!seenChunkIds.has(chunkId)) {
+                      dependentChunks.push(chunk);
+                      seenChunkIds.add(chunkId);
+                    }
+                  }
+                }
+              }
+              const chunksByFile = /* @__PURE__ */ new Map();
+              for (const chunk of dependentChunks) {
+                const canonical = getCanonicalPath(chunk.metadata.file, workspaceRoot);
+                const existing = chunksByFile.get(canonical) || [];
+                existing.push(chunk);
+                chunksByFile.set(canonical, existing);
+              }
+              const fileComplexities = [];
+              for (const [filepath, chunks] of chunksByFile.entries()) {
+                const complexities = chunks.map((c) => c.metadata.complexity).filter((c) => typeof c === "number" && c > 0);
+                if (complexities.length > 0) {
+                  const sum = complexities.reduce((a, b) => a + b, 0);
+                  const avg = sum / complexities.length;
+                  const max = Math.max(...complexities);
+                  fileComplexities.push({
+                    filepath,
+                    avgComplexity: Math.round(avg * 10) / 10,
+                    // Round to 1 decimal
+                    maxComplexity: max,
+                    complexityScore: sum,
+                    chunksWithComplexity: complexities.length
+                  });
+                }
+              }
+              let complexityMetrics;
+              if (fileComplexities.length > 0) {
+                const allAvgs = fileComplexities.map((f) => f.avgComplexity);
+                const allMaxes = fileComplexities.map((f) => f.maxComplexity);
+                const totalAvg = allAvgs.reduce((a, b) => a + b, 0) / allAvgs.length;
+                const globalMax = Math.max(...allMaxes);
+                const highComplexityDependents = fileComplexities.filter((f) => f.maxComplexity > COMPLEXITY_THRESHOLDS.HIGH_COMPLEXITY_DEPENDENT).sort((a, b) => b.maxComplexity - a.maxComplexity).slice(0, 5).map((f) => ({
+                  filepath: f.filepath,
+                  maxComplexity: f.maxComplexity,
+                  avgComplexity: f.avgComplexity
+                }));
+                let complexityRiskBoost = "low";
+                if (totalAvg > COMPLEXITY_THRESHOLDS.CRITICAL_AVG || globalMax > COMPLEXITY_THRESHOLDS.CRITICAL_MAX) {
+                  complexityRiskBoost = "critical";
+                } else if (totalAvg > COMPLEXITY_THRESHOLDS.HIGH_AVG || globalMax > COMPLEXITY_THRESHOLDS.HIGH_MAX) {
+                  complexityRiskBoost = "high";
+                } else if (totalAvg > COMPLEXITY_THRESHOLDS.MEDIUM_AVG || globalMax > COMPLEXITY_THRESHOLDS.MEDIUM_MAX) {
+                  complexityRiskBoost = "medium";
+                }
+                complexityMetrics = {
+                  averageComplexity: Math.round(totalAvg * 10) / 10,
+                  maxComplexity: globalMax,
+                  filesWithComplexityData: fileComplexities.length,
+                  highComplexityDependents,
+                  complexityRiskBoost
+                };
+              } else {
+                complexityMetrics = {
+                  averageComplexity: 0,
+                  maxComplexity: 0,
+                  filesWithComplexityData: 0,
+                  highComplexityDependents: [],
+                  complexityRiskBoost: "low"
+                };
+              }
+              const uniqueFiles = Array.from(chunksByFile.keys()).map((filepath) => ({
+                filepath,
+                isTestFile: isTestFile2(filepath)
+              }));
+              const count = uniqueFiles.length;
+              let riskLevel = count === 0 ? "low" : count <= DEPENDENT_COUNT_THRESHOLDS.LOW ? "low" : count <= DEPENDENT_COUNT_THRESHOLDS.MEDIUM ? "medium" : count <= DEPENDENT_COUNT_THRESHOLDS.HIGH ? "high" : "critical";
+              const RISK_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
+              if (RISK_ORDER[complexityMetrics.complexityRiskBoost] > RISK_ORDER[riskLevel]) {
+                riskLevel = complexityMetrics.complexityRiskBoost;
+              }
+              log(`Found ${count} dependent files (risk: ${riskLevel}${complexityMetrics.filesWithComplexityData > 0 ? ", complexity-boosted" : ""})`);
+              let note;
+              if (allChunks.length === SCAN_LIMIT) {
+                note = `Warning: Scanned ${SCAN_LIMIT} chunks (limit reached). Results may be incomplete for large codebases. Some dependents might not be listed.`;
+              }
+              return {
+                indexInfo: getIndexMetadata(),
+                filepath: validatedArgs.filepath,
+                dependentCount: count,
+                riskLevel,
+                dependents: uniqueFiles,
+                complexityMetrics,
+                note
+              };
+            }
+          )(args);
         default:
           throw new LienError(
             `Unknown tool: ${name}`,