@liendev/lien 0.30.0 → 0.33.0

package/dist/index.js

@@ -8525,7 +8525,13 @@ var ListFunctionsSchema = external_exports.object({
   language: external_exports.string().optional().describe(
     "Filter by programming language.\n\nExamples: 'typescript', 'python', 'javascript', 'php'\n\nIf omitted, searches all languages."
   ),
-  symbolType: external_exports.enum(["function", "method", "class", "interface"]).optional().describe("Filter by symbol type. If omitted, returns all types.")
+  symbolType: external_exports.enum(["function", "method", "class", "interface"]).optional().describe("Filter by symbol type. If omitted, returns all types."),
+  limit: external_exports.number().int().min(1).max(200).default(50).describe(
+    "Number of results to return.\n\nDefault: 50\nIncrease to 200 for broad exploration."
+  ),
+  offset: external_exports.number().int().min(0).max(1e4).default(0).describe(
+    "Skip first N results before applying limit, equivalent to pagination offset.\n\nDefault: 0"
+  )
 });
 
 // src/mcp/schemas/dependents.schema.ts
@@ -8578,7 +8584,11 @@ IMPORTANT: Phrase queries as full questions starting with "How", "Where", "What"
 
 Use natural language describing what the code DOES, not function names. For exact string matching, use grep instead.
 
-Results include a relevance category (highly_relevant, relevant, loosely_related, not_relevant) for each match.`
+Returns:
+- results[]: { content, score, relevance, metadata: { file, startLine, endLine, language?, symbolName?, symbolType?, signature?, enclosingSymbol? } }
+- enclosingSymbol: "Class.method" for methods, "functionName" for standalone functions, absent for block chunks
+- relevance: "highly_relevant" | "relevant" | "loosely_related" (not_relevant auto-filtered)
+- groupedByRepo?: Record<repoId, results[]> (when crossRepo=true)`
   ),
   toMCPToolSchema(
     FindSimilarSchema,
@@ -8594,7 +8604,13 @@ Optional filters:
 - language: Filter by programming language (e.g., "typescript", "python")
 - pathHint: Filter by file path substring (e.g., "src/api", "components")
 
-Low-relevance results (not_relevant) are automatically pruned.`
+Low-relevance results (not_relevant) are automatically pruned.
+
+Returns:
+- results[]: { content, score, relevance, metadata: { file, startLine, endLine, language?, symbolName?, signature?, enclosingSymbol? } }
+- enclosingSymbol: "Class.method" for methods, "functionName" for standalone functions, absent for block chunks
+- relevance: "highly_relevant" | "relevant" | "loosely_related" (not_relevant auto-filtered)
+- filtersApplied?: { language?, pathHint?, prunedLowRelevance: number }`
   ),
   toMCPToolSchema(
     GetFilesContextSchema,
@@ -8653,7 +8669,16 @@ Examples:
 
 Filter by symbol type (function, method, class, interface) to narrow results.
 
-10x faster than semantic_search for structural/architectural queries. Use semantic_search instead when searching by what code DOES.`
+10x faster than semantic_search for structural/architectural queries. Use semantic_search instead when searching by what code DOES.
+
+Results are paginated (default: 50, max: 200). Use \`offset\` to page through large result sets.
+
+Returns:
+- results[]: { content, metadata: { file, startLine, endLine, language?, symbolName?, symbolType?, signature?, enclosingSymbol? } }
+- enclosingSymbol: "Class.method" for methods, "functionName" for standalone functions, absent for block chunks
+- method: "symbols" | "content" (query method used)
+- hasMore: boolean (more results available)
+- nextOffset?: number (offset for next page, when hasMore=true)`
   ),
   toMCPToolSchema(
     GetDependentsSchema,
@@ -8663,11 +8688,15 @@ Filter by symbol type (function, method, class, interface) to narrow results.
 - "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" })
 
-Example: get_dependents({ filepath: "src/utils/validate.ts" })`
+Returns:
+- dependentCount / productionDependentCount / testDependentCount
+- riskLevel: "low" | "medium" | "high" | "critical"
+- dependents[]: { filepath, isTestFile, usages[]? }
+- complexityMetrics: { averageComplexity, maxComplexity, highComplexityDependents[] }
+- totalUsageCount?: number (when symbol parameter provided)
+- groupedByRepo?: Record<repoId, dependents[]> (when crossRepo=true)`
   ),
   toMCPToolSchema(
     GetComplexitySchema,
@@ -8690,19 +8719,108 @@ Examples:
   get_complexity({ files: ["src/auth.ts", "src/api/user.ts"] })
   get_complexity({ threshold: 15 })
 
-Returns violations with metricType ('cyclomatic', 'cognitive', 'halstead_effort',
-or 'halstead_bugs'), risk levels, and dependent counts.
-Human-readable output: "23 (needs ~23 tests)", "\u{1F9E0} 45", "~2h 30m", "2.27 bugs".`
+Returns:
+- summary: { filesAnalyzed, avgComplexity, maxComplexity, violationCount, bySeverity: { error, warning } }
+- violations[]: { filepath, symbolName, symbolType, complexity, metricType, threshold, severity, riskLevel, dependentCount }
+- metricType: "cyclomatic" | "cognitive" | "halstead_effort" | "halstead_bugs"
+- severity: "error" | "warning"
+- groupedByRepo?: Record<repoId, violations[]> (when crossRepo=true)`
   )
 ];
 
 // src/mcp/utils/tool-wrapper.ts
 import { LienError, LienErrorCode } from "@liendev/core";
+
+// src/mcp/utils/response-budget.ts
+var MAX_RESPONSE_CHARS = 12e3;
+function applyResponseBudget(result, maxChars = MAX_RESPONSE_CHARS) {
+  const serialized = JSON.stringify(result);
+  if (serialized.length <= maxChars) {
+    return { result };
+  }
+  const originalChars = serialized.length;
+  const cloned = JSON.parse(serialized);
+  const arrays = findContentArrays(cloned);
+  if (arrays.length === 0) {
+    return { result };
+  }
+  for (const arr of arrays) {
+    for (const item of arr) {
+      item.content = truncateContent(item.content, 10);
+    }
+  }
+  if (measureSize(cloned) <= maxChars) {
+    return buildResult(cloned, originalChars, 1);
+  }
+  let currentSize = measureSize(cloned);
+  for (const arr of arrays) {
+    while (arr.length > 1 && currentSize > maxChars) {
+      arr.pop();
+      currentSize = measureSize(cloned);
+    }
+  }
+  if (currentSize <= maxChars) {
+    return buildResult(cloned, originalChars, 2);
+  }
+  for (const arr of arrays) {
+    for (const item of arr) {
+      item.content = truncateContent(item.content, 3);
+    }
+  }
+  return buildResult(cloned, originalChars, 3);
+}
+function truncateContent(content, maxLines) {
+  const lines = content.split("\n");
+  if (lines.length <= maxLines) return content;
+  return lines.slice(0, maxLines).join("\n") + "\n... (truncated)";
+}
+function measureSize(obj) {
+  return JSON.stringify(obj).length;
+}
+function findContentArrays(obj) {
+  const found = [];
+  walk(obj, found);
+  return found;
+}
+function walk(node, found) {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    if (node.length > 0 && node.every(
+      (elem) => typeof elem === "object" && elem !== null && typeof elem.content === "string"
+    )) {
+      found.push(node);
+    }
+    return;
+  }
+  for (const value of Object.values(node)) {
+    walk(value, found);
+  }
+}
+function buildResult(cloned, originalChars, phase) {
+  const finalChars = measureSize(cloned);
+  return {
+    result: cloned,
+    truncation: {
+      originalChars,
+      finalChars,
+      phase,
+      message: `Response truncated from ${originalChars} to ${finalChars} chars (phase ${phase}/3). Use narrower filters or smaller limit for complete results.`
+    }
+  };
+}
+
+// src/mcp/utils/tool-wrapper.ts
 function wrapToolHandler(schema, handler) {
   return async (args) => {
     try {
       const validated = schema.parse(args);
-      const result = await handler(validated);
+      const rawResult = await handler(validated);
+      const { result, truncation } = applyResponseBudget(rawResult);
+      if (truncation && typeof result === "object" && result !== null) {
+        const obj = result;
+        obj.note = obj.note ? `${obj.note}
+${truncation.message}` : truncation.message;
+      }
       return {
         content: [{
           type: "text",
@@ -8710,45 +8828,48 @@ function wrapToolHandler(schema, handler) {
         }]
       };
     } catch (error) {
-      if (error instanceof ZodError) {
-        return {
-          isError: true,
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              error: "Invalid parameters",
-              code: LienErrorCode.INVALID_INPUT,
-              details: error.errors.map((e) => ({
-                field: e.path.join("."),
-                message: e.message
-              }))
-            }, null, 2)
-          }]
-        };
-      }
-      if (error instanceof LienError) {
-        return {
-          isError: true,
-          content: [{
-            type: "text",
-            text: JSON.stringify(error.toJSON(), null, 2)
-          }]
-        };
-      }
-      console.error("Unexpected error in tool handler:", error);
-      return {
-        isError: true,
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            error: error instanceof Error ? error.message : "Unknown error",
-            code: LienErrorCode.INTERNAL_ERROR
-          }, null, 2)
-        }]
-      };
+      return formatErrorResponse(error);
     }
   };
 }
+function formatErrorResponse(error) {
+  if (error instanceof ZodError) {
+    return {
+      isError: true,
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          error: "Invalid parameters",
+          code: LienErrorCode.INVALID_INPUT,
+          details: error.errors.map((e) => ({
+            field: e.path.join("."),
+            message: e.message
+          }))
+        }, null, 2)
+      }]
+    };
+  }
+  if (error instanceof LienError) {
+    return {
+      isError: true,
+      content: [{
+        type: "text",
+        text: JSON.stringify(error.toJSON(), null, 2)
+      }]
+    };
+  }
+  console.error("Unexpected error in tool handler:", error);
+  return {
+    isError: true,
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        error: error instanceof Error ? error.message : "Unknown error",
+        code: LienErrorCode.INTERNAL_ERROR
+      }, null, 2)
+    }]
+  };
+}
 
 // src/mcp/utils/metadata-shaper.ts
 var FIELD_ALLOWLISTS = {
@@ -8841,6 +8962,9 @@ function pickMetadata(metadata, allowlist) {
       out[key] = cleaned;
     }
   }
+  if (metadata.symbolName) {
+    out["enclosingSymbol"] = metadata.parentClass ? `${metadata.parentClass}.${metadata.symbolName}` : metadata.symbolName;
+  }
   return result;
 }
 function shapeResultMetadata(result, tool) {
@@ -8868,6 +8992,33 @@ function groupResultsByRepo(results) {
   }
   return grouped;
 }
+async function executeSearch(vectorDB, queryEmbedding, params, log) {
+  const { query, limit, crossRepo, repoIds } = params;
+  if (crossRepo && vectorDB instanceof QdrantDB) {
+    const results2 = await vectorDB.searchCrossRepo(queryEmbedding, limit, { repoIds });
+    log(`Found ${results2.length} results across ${Object.keys(groupResultsByRepo(results2)).length} repos`);
+    return { results: results2, crossRepoFallback: false };
+  }
+  if (crossRepo) {
+    log("Warning: crossRepo=true requires Qdrant backend. Falling back to single-repo search.", "warning");
+  }
+  const results = await vectorDB.search(queryEmbedding, limit, query);
+  log(`Found ${results.length} results`);
+  return { results, crossRepoFallback: !!crossRepo };
+}
+function processResults(rawResults, crossRepoFallback, log) {
+  const notes = [];
+  if (crossRepoFallback) {
+    notes.push("Cross-repo search requires Qdrant backend. Fell back to single-repo search.");
+  }
+  const results = deduplicateResults(rawResults);
+  if (results.length > 0 && results.every((r) => r.relevance === "not_relevant")) {
+    notes.push("No relevant matches found.");
+    log("Returning 0 results (all not_relevant)");
+    return { results: [], notes };
+  }
+  return { results, notes };
+}
 async function handleSemanticSearch(args, ctx) {
   const { vectorDB, embeddings, log, checkAndReconnect, getIndexMetadata } = ctx;
   return await wrapToolHandler(
@@ -8877,35 +9028,18 @@ async function handleSemanticSearch(args, ctx) {
       log(`Searching for: "${query}"${crossRepo ? " (cross-repo)" : ""}`);
       await checkAndReconnect();
       const queryEmbedding = await embeddings.embed(query);
-      let results;
-      let crossRepoFallback = false;
-      if (crossRepo && vectorDB instanceof QdrantDB) {
-        results = await vectorDB.searchCrossRepo(queryEmbedding, limit, { repoIds });
-        log(`Found ${results.length} results across ${Object.keys(groupResultsByRepo(results)).length} repos`);
-      } else {
-        if (crossRepo) {
-          log("Warning: crossRepo=true requires Qdrant backend. Falling back to single-repo search.");
-          crossRepoFallback = true;
-        }
-        results = await vectorDB.search(queryEmbedding, limit, query);
-        log(`Found ${results.length} results`);
-      }
-      results = deduplicateResults(results);
-      const notes = [];
-      if (crossRepoFallback) {
-        notes.push("Cross-repo search requires Qdrant backend. Fell back to single-repo search.");
-      }
-      if (results.length > 0 && results.every((r) => r.relevance === "not_relevant")) {
-        notes.push("No relevant matches found.");
-        log("Returning 0 results (all not_relevant)");
-        return {
-          indexInfo: getIndexMetadata(),
-          results: [],
-          note: notes.join(" ")
-        };
-      }
+      const { results: rawResults, crossRepoFallback } = await executeSearch(
+        vectorDB,
+        queryEmbedding,
+        { query, limit: limit ?? 5, crossRepo, repoIds },
+        log
+      );
+      const { results, notes } = processResults(rawResults, crossRepoFallback, log);
       log(`Returning ${results.length} results`);
       const shaped = shapeResults(results, "semantic_search");
+      if (shaped.length === 0) {
+        notes.push('0 results. Try rephrasing as a full question (e.g. "How does X work?"), or use grep for exact string matches. If the codebase was recently updated, run "lien reindex".');
+      }
       return {
         indexInfo: getIndexMetadata(),
         results: shaped,
@@ -8964,7 +9098,8 @@ async function handleFindSimilar(args, ctx) {
       return {
         indexInfo: getIndexMetadata(),
         results: shapeResults(finalResults, "find_similar"),
-        ...hasFilters && { filtersApplied }
+        ...hasFilters && { filtersApplied },
+        ...finalResults.length === 0 && { note: "0 results. Ensure the code snippet is at least 24 characters and representative of the pattern. Try grep for exact string matches." }
       };
     }
   )(args);
@@ -9063,19 +9198,15 @@ function isTestFile(filepath) {
 }
 
 // src/mcp/handlers/get-files-context.ts
+import { MAX_CHUNKS_PER_FILE } from "@liendev/core";
 var SCAN_LIMIT = 1e4;
 async function searchFileChunks(filepaths, ctx) {
-  const { vectorDB, embeddings, workspaceRoot } = ctx;
-  const fileEmbeddings = await Promise.all(
-    filepaths.map((fp) => embeddings.embed(fp))
-  );
-  const allFileSearches = await Promise.all(
-    fileEmbeddings.map(
-      (embedding, i) => vectorDB.search(embedding, 50, filepaths[i])
-    )
-  );
-  return filepaths.map((filepath, i) => {
-    const allResults = allFileSearches[i];
+  const { vectorDB, workspaceRoot } = ctx;
+  const allResults = await vectorDB.scanWithFilter({
+    file: filepaths,
+    limit: filepaths.length * MAX_CHUNKS_PER_FILE
+  });
+  return filepaths.map((filepath) => {
     const targetCanonical = getCanonicalPath(filepath, workspaceRoot);
     return allResults.filter((r) => {
       const chunkCanonical = getCanonicalPath(r.metadata.file, workspaceRoot);
@@ -9245,13 +9376,12 @@ async function handleGetFilesContext(args, ctx) {
 }
 
 // src/mcp/handlers/list-functions.ts
-import { SYMBOL_TYPE_MATCHES } from "@liendev/core";
-async function performContentScan(vectorDB, args, log) {
+async function performContentScan(vectorDB, args, fetchLimit, log) {
   log("Falling back to content scan...");
   let results = await vectorDB.scanWithFilter({
     language: args.language,
-    limit: 200
-    // Fetch more, we'll filter by symbolName
+    symbolType: args.symbolType,
+    limit: fetchLimit
   });
   if (args.pattern) {
     const regex = new RegExp(args.pattern, "i");
@@ -9260,16 +9390,37 @@ async function performContentScan(vectorDB, args, log) {
       return symbolName && regex.test(symbolName);
     });
   }
-  if (args.symbolType) {
-    const allowedTypes = SYMBOL_TYPE_MATCHES[args.symbolType];
-    results = results.filter((r) => {
-      const recordType2 = r.metadata?.symbolType;
-      return recordType2 && allowedTypes?.has(recordType2);
+  return {
+    results,
+    method: "content"
+  };
+}
+async function queryWithFallback(vectorDB, args, fetchLimit, log) {
+  try {
+    const results = await vectorDB.querySymbols({
+      language: args.language,
+      pattern: args.pattern,
+      symbolType: args.symbolType,
+      limit: fetchLimit
     });
+    if (results.length === 0 && (args.language || args.pattern || args.symbolType)) {
+      log("No symbol results, falling back to content scan...");
+      return await performContentScan(vectorDB, args, fetchLimit, log);
+    }
+    return { results, method: "symbols" };
+  } catch (error) {
+    log(`Symbol query failed: ${error}`);
+    return await performContentScan(vectorDB, args, fetchLimit, log);
   }
+}
+function paginateResults(results, offset, limit) {
+  const dedupedResults = deduplicateResults(results);
+  const hasMore = dedupedResults.length > offset + limit;
+  const paginatedResults = dedupedResults.slice(offset, offset + limit);
   return {
-    results: results.slice(0, 50),
-    method: "content"
+    paginatedResults,
+    hasMore,
+    ...hasMore ? { nextOffset: offset + limit } : {}
   };
 }
 async function handleListFunctions(args, ctx) {
@@ -9279,31 +9430,28 @@ async function handleListFunctions(args, ctx) {
     async (validatedArgs) => {
       log("Listing functions with symbol metadata...");
       await checkAndReconnect();
-      let queryResult;
-      try {
-        const results = await vectorDB.querySymbols({
-          language: validatedArgs.language,
-          pattern: validatedArgs.pattern,
-          symbolType: validatedArgs.symbolType,
-          limit: 50
-        });
-        if (results.length === 0 && (validatedArgs.language || validatedArgs.pattern || validatedArgs.symbolType)) {
-          log("No symbol results, falling back to content scan...");
-          queryResult = await performContentScan(vectorDB, validatedArgs, log);
-        } else {
-          queryResult = { results, method: "symbols" };
-        }
-      } catch (error) {
-        log(`Symbol query failed: ${error}`);
-        queryResult = await performContentScan(vectorDB, validatedArgs, log);
+      const limit = validatedArgs.limit ?? 50;
+      const offset = validatedArgs.offset ?? 0;
+      const fetchLimit = limit + offset + 1;
+      const queryResult = await queryWithFallback(vectorDB, validatedArgs, fetchLimit, log);
+      const { paginatedResults, hasMore, nextOffset } = paginateResults(queryResult.results, offset, limit);
+      log(`Found ${paginatedResults.length} matches using ${queryResult.method} method`);
+      const notes = [];
+      if (queryResult.results.length === 0) {
+        notes.push('0 results. Try a broader regex pattern (e.g. ".*") or omit the symbolType filter. Use semantic_search for behavior-based queries.');
+      } else if (paginatedResults.length === 0 && offset > 0) {
+        notes.push("No results for this page. The offset is beyond the available results; try reducing or resetting the offset to 0.");
+      }
+      if (queryResult.method === "content") {
+        notes.push('Using content search. Run "lien reindex" to enable faster symbol-based queries.');
       }
-      const dedupedResults = deduplicateResults(queryResult.results);
-      log(`Found ${dedupedResults.length} matches using ${queryResult.method} method`);
       return {
         indexInfo: getIndexMetadata(),
         method: queryResult.method,
-        results: shapeResults(dedupedResults, "list_functions"),
-        note: queryResult.method === "content" ? 'Using content search. Run "lien reindex" to enable faster symbol-based queries.' : void 0
+        hasMore,
+        ...nextOffset !== void 0 ? { nextOffset } : {},
+        results: shapeResults(paginatedResults, "list_functions"),
+        ...notes.length > 0 && { note: notes.join(" ") }
       };
     }
   )(args);