fix: resolve PR #98 review blockers

Author: PatrickSys

CHANGELOG.md

@@ -2,37 +2,28 @@
 
 ## Unreleased
 
-## [2.1.0](https://github.com/PatrickSys/codebase-context/compare/v2.0.0...v2.1.0) (2026-04-13)
+## [2.1.0](https://github.com/PatrickSys/codebase-context/compare/v1.9.0...v2.1.0) (2026-04-13)
 
 ### Features
 
 - **search:** surface chunk intelligence directly in `search_codebase` results, including symbol identity, scope, signature preview, and compact/full response budgeting
 - **map:** upgrade the conventions map with structural skeleton sections and add `map --export` so the compact map can be written to `CODEBASE_MAP.md`
+- **mcp:** rework multi-project routing so one MCP server can serve multiple projects instead of one hardcoded server entry per repo
+- **mcp:** keep explicit `project` as the fallback when the client does not provide enough project context
+- **mcp:** accept repo paths, subproject paths, and file paths as `project` selectors when routing is ambiguous
 
 ### Bug Fixes
 
 - **metadata:** require real dependency evidence plus multiple framework indicators before labeling a repo as Next.js or another specialized framework
 - **reranker:** auto-heal corrupted cross-encoder cache entries and surface degraded reranker state in `searchQuality.rerankerStatus`
 - **benchmarks:** harden comparator lanes for cross-platform execution and keep setup failures explicit instead of silently turning them into claims
+- **search:** auto-heal on corrupted index now triggers a background rebuild instead of blocking the search response
 
 ### Documentation
 
 - publish the v2.1.0 discovery benchmark rerun with the current gate output: `pending_evidence`, `claimAllowed: false`, `24` frozen tasks, `0.75` average usefulness, and `1822.25` average estimated tokens
 - document the current comparator truth instead of stale assumptions: the public proof still has setup failures plus near-empty comparator outputs on this host, so benchmark win claims remain blocked
 - note the new `searchQuality.tokenEstimate` advisory contract: estimates are based on the final serialized response payload and warnings only appear above the 4K-token threshold
-
-### Features
-
-- **mcp:** rework multi-project routing so one MCP server can serve multiple projects instead of one hardcoded server entry per repo
-- **mcp:** keep explicit `project` as the fallback when the client does not provide enough project context
-- **mcp:** accept repo paths, subproject paths, and file paths as `project` selectors when routing is ambiguous
-
-### Bug Fixes
-
-- **search:** auto-heal on corrupted index now triggers a background rebuild instead of blocking the search response
-
-### Documentation
-
 - simplify the setup story around a roots-first contract: roots-capable multi-project sessions, single-project fallback, and explicit `project` retries
 - clarify that issue #63 fixed the architecture and workspace-aware workflow, but issue #2 is still only partially solved when the client does not provide roots or active-project context
 - remove the repo-local `init` / marker-file story from the public setup guidance

src/index.ts

@@ -50,6 +50,7 @@ import {
 } from './utils/project-discovery.js';
 import { readIndexMeta, validateIndexArtifacts } from './core/index-meta.js';
 import { TOOLS, dispatchTool, type ToolContext, type ToolResponse } from './tools/index.js';
+import { finalizeSearchPayloadText } from './tools/search-payload-budget.js';
 import type { ProjectDescriptor, ToolPaths } from './tools/types.js';
 import {
   getOrCreateProject,
@@ -119,48 +120,20 @@ type ProjectResolution =
   | { ok: true; project: ProjectState }
   | { ok: false; response: ToolResponse };
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function finalizeJsonTextPayload(payload: Record<string, unknown>): string {
-  if (!isPlainRecord(payload.searchQuality)) {
+  const mode =
+    typeof payload.budget === 'object' &&
+    payload.budget !== null &&
+    'mode' in payload.budget &&
+    (payload.budget.mode === 'compact' || payload.budget.mode === 'full')
+      ? payload.budget.mode
+      : undefined;
+
+  if (!mode) {
     return JSON.stringify(payload);
   }
 
-  let tokenEstimate =
-    typeof payload.searchQuality.tokenEstimate === 'number'
-      ? payload.searchQuality.tokenEstimate
-      : 0;
-  let warning =
-    typeof payload.searchQuality.warning === 'string' ? payload.searchQuality.warning : undefined;
-  let renderedPayload = '';
-
-  for (let attempt = 0; attempt < 5; attempt += 1) {
-    renderedPayload = JSON.stringify({
-      ...payload,
-      searchQuality: {
-        ...payload.searchQuality,
-        ...(warning ? { warning } : {}),
-        tokenEstimate
-      }
-    });
-
-    const nextTokenEstimate = Math.ceil(renderedPayload.length / 4);
-    const nextWarning =
-      nextTokenEstimate > 4000
-        ? `Large search payload: estimated ${nextTokenEstimate} tokens. Prefer compact mode or tighter filters before pasting into an agent.`
-        : undefined;
-
-    if (nextTokenEstimate === tokenEstimate && nextWarning === warning) {
-      return renderedPayload;
-    }
-
-    tokenEstimate = nextTokenEstimate;
-    warning = nextWarning;
-  }
-
-  return renderedPayload;
+  return finalizeSearchPayloadText(payload, { mode });
 }
 
 function registerKnownRoot(rootPath: string): string {

src/tools/search-codebase.ts

@@ -26,6 +26,7 @@ import type { MemoryWithConfidence } from '../memory/store.js';
 import { InternalFileGraph } from '../utils/usage-tracker.js';
 import type { FileExport } from '../utils/usage-tracker.js';
 import { RELATIONSHIPS_FILENAME } from '../constants/codebase-context.js';
+import { finalizeSearchPayloadText } from './search-payload-budget.js';
 
 // Stop words for compact-mode memory relevance filter (mirrors QUERY_STOP_WORDS in search.ts)
 const COMPACT_STOP_WORDS = new Set([
@@ -1061,44 +1062,6 @@ export async function handle(
     relatedMemories?: string[];
   };
 
-  function renderSearchPayloadText(payload: SearchResponsePayload): string {
-    let tokenEstimate = 0;
-    let warning: string | undefined;
-    let renderedPayload = '';
-
-    for (let attempt = 0; attempt < 5; attempt += 1) {
-      renderedPayload = JSON.stringify(
-        {
-          ...payload,
-          searchQuality: {
-            ...searchQualityBlock,
-            ...(warning && { warning }),
-            tokenEstimate
-          }
-        },
-        null,
-        2
-      );
-
-      const estimatedTransportPayload =
-        process.platform === 'win32' ? renderedPayload.replace(/\n/g, '\r\n') : renderedPayload;
-      const nextTokenEstimate = Math.ceil(estimatedTransportPayload.length / 4);
-      const nextWarning =
-        nextTokenEstimate > 4000
-          ? `Large search payload: estimated ${nextTokenEstimate} tokens. Prefer compact mode or tighter filters before pasting into an agent.`
-          : undefined;
-
-      if (nextTokenEstimate === tokenEstimate && nextWarning === warning) {
-        return renderedPayload;
-      }
-
-      tokenEstimate = nextTokenEstimate;
-      warning = nextWarning;
-    }
-
-    return renderedPayload;
-  }
-
   // Compact mode (default): bounded response with light graph context
   const isCompact = mode !== 'full';
 
@@ -1108,7 +1071,8 @@ export async function handle(
     const patternSummary = buildPatternSummary();
     const bestExample = getBestExample(compactResults);
     const nextHops = buildNextHops(compactResults, searchQuality);
-    const payloadText = renderSearchPayloadText({
+    const payloadText = finalizeSearchPayloadText(
+      {
       status: 'success',
       searchQuality: searchQualityBlock,
       budget: { mode: 'compact', resultCount: compactResults.length },
@@ -1152,7 +1116,9 @@ export async function handle(
       ...(strongMemories.length > 0 && {
         relatedMemories: strongMemories.map((m) => `${m.memory} (${m.effectiveConfidence})`)
       })
-    });
+      },
+      { mode: 'compact', pretty: true, transportAware: true }
+    );
 
     return {
       content: [
@@ -1165,7 +1131,8 @@ export async function handle(
   }
 
   // Full mode: today's response shape + budget + relevanceReason; consumers removed
-  const payloadText = renderSearchPayloadText({
+  const payloadText = finalizeSearchPayloadText(
+    {
     status: 'success',
     searchQuality: searchQualityBlock,
     budget: { mode: 'full', resultCount: results.length },
@@ -1212,7 +1179,9 @@ export async function handle(
         .slice(0, 3)
         .map((m) => `${m.memory} (${m.effectiveConfidence})`)
     })
-  });
+    },
+    { mode: 'full', pretty: true, transportAware: true }
+  );
 
   return {
     content: [

src/tools/search-payload-budget.ts

@@ -0,0 +1,69 @@
+type SearchPayloadMode = 'compact' | 'full';
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function buildWarning(tokenEstimate: number, mode: SearchPayloadMode): string | undefined {
+  if (tokenEstimate <= 4000) {
+    return undefined;
+  }
+
+  if (mode === 'compact') {
+    return `Large search payload: estimated ${tokenEstimate} tokens. Try tighter filters (e.g. layer=, language=) to reduce payload size.`;
+  }
+
+  return `Large search payload: estimated ${tokenEstimate} tokens. Prefer compact mode or tighter filters before pasting into an agent.`;
+}
+
+export function finalizeSearchPayloadText(
+  payload: Record<string, unknown>,
+  options: {
+    mode: SearchPayloadMode;
+    pretty?: boolean;
+    transportAware?: boolean;
+  }
+): string {
+  if (!isPlainRecord(payload.searchQuality)) {
+    return JSON.stringify(payload, null, options.pretty ? 2 : undefined);
+  }
+
+  let tokenEstimate =
+    typeof payload.searchQuality.tokenEstimate === 'number'
+      ? payload.searchQuality.tokenEstimate
+      : 0;
+  let warning =
+    typeof payload.searchQuality.warning === 'string' ? payload.searchQuality.warning : undefined;
+  let renderedPayload = '';
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    renderedPayload = JSON.stringify(
+      {
+        ...payload,
+        searchQuality: {
+          ...payload.searchQuality,
+          ...(warning ? { warning } : {}),
+          tokenEstimate
+        }
+      },
+      null,
+      options.pretty ? 2 : undefined
+    );
+
+    const estimatedTransportPayload =
+      options.transportAware && process.platform === 'win32'
+        ? renderedPayload.replace(/\n/g, '\r\n')
+        : renderedPayload;
+    const nextTokenEstimate = Math.ceil(estimatedTransportPayload.length / 4);
+    const nextWarning = buildWarning(nextTokenEstimate, options.mode);
+
+    if (nextTokenEstimate === tokenEstimate && nextWarning === warning) {
+      return renderedPayload;
+    }
+
+    tokenEstimate = nextTokenEstimate;
+    warning = nextWarning;
+  }
+
+  return renderedPayload;
+}

tests/search-compact-mode.test.ts

@@ -363,6 +363,46 @@ describe('search_codebase compact/full mode', () => {
     expect(payload.searchQuality.warning).toBeUndefined();
   });
 
+  it('uses filter-only guidance when a final compact payload exceeds the token threshold', async () => {
+    const oversizedSummary = 'Token-heavy compact summary '.repeat(1200);
+    searchMocks.search.mockResolvedValueOnce([
+      makeResult({
+        summary: oversizedSummary
+      })
+    ]);
+
+    const { server } = await import('../src/index.js');
+    const handler = (
+      server as {
+        _requestHandlers?: Map<
+          string,
+          (r: unknown) => Promise<{ content: Array<{ type: string; text: string }> }>
+        >;
+      }
+    )._requestHandlers?.get('tools/call');
+    if (!handler) throw new Error('Expected tools/call handler');
+
+    const response = await handler({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: { name: 'search_codebase', arguments: { query: 'auth service' } }
+    });
+
+    const payload = JSON.parse(response.content[0].text) as {
+      searchQuality: {
+        tokenEstimate: number;
+        warning?: string;
+      };
+    };
+
+    expect(payload.searchQuality.tokenEstimate).toBe(Math.ceil(response.content[0].text.length / 4));
+    expect(payload.searchQuality.tokenEstimate).toBeGreaterThan(4000);
+    expect(payload.searchQuality.warning).toBe(
+      `Large search payload: estimated ${payload.searchQuality.tokenEstimate} tokens. Try tighter filters (e.g. layer=, language=) to reduce payload size.`
+    );
+  });
+
   // Test 5: Full mode returns hints arrays and all memories + budget
   it('full mode returns hints object with callers/tests and budget metadata', async () => {
     searchMocks.search.mockResolvedValueOnce([makeResult()]);
@@ -444,8 +484,8 @@ describe('search_codebase compact/full mode', () => {
 
     expect(payload.searchQuality.tokenEstimate).toBe(Math.ceil(response.content[0].text.length / 4));
     expect(payload.searchQuality.tokenEstimate).toBeGreaterThan(4000);
-    expect(payload.searchQuality.warning).toContain(
-      `estimated ${payload.searchQuality.tokenEstimate} tokens`
+    expect(payload.searchQuality.warning).toBe(
+      `Large search payload: estimated ${payload.searchQuality.tokenEstimate} tokens. Prefer compact mode or tighter filters before pasting into an agent.`
     );
   });