codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

package/dist/src/project-selector.d.ts

@@ -2,6 +2,12 @@ export interface Project {
     name: string;
     path: string;
 }
+/**
+ * One-off single-choice prompt for `--project` with no name — distinct from
+ * the multi-select `checkbox` flow: it reads/writes nothing persisted.
+ * Resolves to `undefined` if the user cancels (e.g. Ctrl+C).
+ */
+export declare function selectSingleProject(units: Project[]): Promise<string | undefined>;
 export declare class ProjectSelector {
     private readonly workspaceDir;
     private included;

package/dist/src/project-selector.js

@@ -34,9 +34,27 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProjectSelector = void 0;
+exports.selectSingleProject = selectSingleProject;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const prompts_1 = require("@inquirer/prompts");
+/**
+ * One-off single-choice prompt for `--project` with no name — distinct from
+ * the multi-select `checkbox` flow: it reads/writes nothing persisted.
+ * Resolves to `undefined` if the user cancels (e.g. Ctrl+C).
+ */
+async function selectSingleProject(units) {
+    try {
+        return await (0, prompts_1.select)({
+            message: 'Select a project to index',
+            choices: units.map(p => ({ name: p.name, value: p.name })),
+            pageSize: 15,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
 async function loadLines(filePath) {
     try {
         const content = await fs.promises.readFile(filePath, 'utf-8');

package/dist/src/retrieval-eval.d.ts

@@ -0,0 +1,16 @@
+import type { EvalSuite, SearchFn, IndexInspector, IRetrievalEvaluator, EvalRunResult, EvalResultFile, CompareResult } from './interfaces/IRetrievalEvaluator';
+/** Thrown by `parseSuite` before any search runs — names the offending case and field. */
+export declare class EvalSuiteError extends Error {
+    readonly caseId: string | null;
+    readonly field: string | null;
+    constructor(message: string, caseId: string | null, field: string | null);
+}
+/** Validates a loaded suite object against the schema; rejects before any search runs. */
+export declare function parseSuite(raw: unknown): EvalSuite;
+/** Merges several suites (already parsed) into one; case ids must be unique across all of them. */
+export declare function mergeSuites(suites: EvalSuite[]): EvalSuite;
+export declare class RetrievalEvaluator implements IRetrievalEvaluator {
+    evaluate(suite: EvalSuite, search: SearchFn, inspect: IndexInspector): Promise<EvalRunResult>;
+}
+/** Pure comparison of two result files; prints a warning (never refuses) on mismatched conditions. */
+export declare function compare(baseline: EvalResultFile, current: EvalResultFile): CompareResult;

package/dist/src/retrieval-eval.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetrievalEvaluator = exports.EvalSuiteError = void 0;
+exports.parseSuite = parseSuite;
+exports.mergeSuites = mergeSuites;
+exports.compare = compare;
+const zod_1 = require("zod");
+/** Thrown by `parseSuite` before any search runs — names the offending case and field. */
+class EvalSuiteError extends Error {
+    caseId;
+    field;
+    constructor(message, caseId, field) {
+        super(message);
+        this.caseId = caseId;
+        this.field = field;
+        this.name = 'EvalSuiteError';
+    }
+}
+exports.EvalSuiteError = EvalSuiteError;
+const ExpectedAnswerSchema = zod_1.z.object({
+    file: zod_1.z.string().min(1),
+    owner: zod_1.z.string().min(1).optional(),
+});
+const CaseSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    project: zod_1.z.string().min(1),
+    category: zod_1.z.enum(['identifier', 'behaviour', 'concept']),
+    query: zod_1.z.string().min(1),
+    expect: zod_1.z.array(ExpectedAnswerSchema).min(1),
+    threshold: zod_1.z.number().min(0).max(1).optional(),
+});
+const SuiteSchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    cases: zod_1.z.array(CaseSchema),
+});
+/** Best-effort id of the case at `cases[index]` in a raw (possibly invalid) object, for error messages. */
+function rawCaseId(raw, index) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const cases = raw.cases;
+    if (!Array.isArray(cases))
+        return null;
+    const entry = cases[index];
+    if (typeof entry !== 'object' || entry === null)
+        return null;
+    const id = entry.id;
+    return typeof id === 'string' ? id : null;
+}
+/** Validates a loaded suite object against the schema; rejects before any search runs. */
+function parseSuite(raw) {
+    const result = SuiteSchema.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const pathParts = issue.path;
+        const caseIndex = typeof pathParts[1] === 'number' ? pathParts[1] : null;
+        const caseId = caseIndex !== null ? rawCaseId(raw, caseIndex) ?? `#${caseIndex}` : null;
+        const field = pathParts.length > 2 ? String(pathParts[pathParts.length - 1]) : pathParts.length === 2 ? 'id' : String(pathParts[0] ?? '');
+        throw new EvalSuiteError(`${issue.message} (case ${caseId ?? '?'}, field ${field})`, caseId, field);
+    }
+    const seen = new Set();
+    for (const c of result.data.cases) {
+        if (seen.has(c.id)) {
+            throw new EvalSuiteError(`Duplicate case id (case ${c.id}, field id)`, c.id, 'id');
+        }
+        seen.add(c.id);
+    }
+    return result.data;
+}
+/** Merges several suites (already parsed) into one; case ids must be unique across all of them. */
+function mergeSuites(suites) {
+    const cases = [];
+    const seen = new Set();
+    for (const suite of suites) {
+        for (const c of suite.cases) {
+            if (seen.has(c.id))
+                throw new EvalSuiteError(`Duplicate case id across suites (case ${c.id}, field id)`, c.id, 'id');
+            seen.add(c.id);
+            cases.push(c);
+        }
+    }
+    return { version: 1, cases };
+}
+/** `owner` matches exactly, or as a prefix at a `.` boundary (`RepairsService` accepts any member of the class). */
+function ownerMatches(ownerPath, expectedOwner) {
+    return ownerPath === expectedOwner || ownerPath.startsWith(expectedOwner + '.');
+}
+async function validateCase(c, inspect) {
+    const valid = [];
+    const invalid = [];
+    for (const expected of c.expect) {
+        const indexed = await inspect.isFileIndexed(c.project, expected.file);
+        if (!indexed) {
+            invalid.push(expected);
+            continue;
+        }
+        if (expected.owner) {
+            const owners = await inspect.ownerPathsOfFile(c.project, expected.file);
+            const found = owners.some(o => ownerMatches(o, expected.owner));
+            if (!found) {
+                invalid.push(expected);
+                continue;
+            }
+        }
+        valid.push(expected);
+    }
+    return { valid, invalid };
+}
+function rankOf(hits, valid) {
+    for (let i = 0; i < hits.length; i++) {
+        const hit = hits[i];
+        const matches = valid.some(e => hit.filePath === e.file && (!e.owner || (hit.ownerPath !== null && ownerMatches(hit.ownerPath, e.owner))));
+        if (matches)
+            return { rank: i + 1, matched: hit };
+    }
+    return { rank: null, matched: null };
+}
+function emptyMetrics() {
+    return { count: 0, hit1: 0, hit5: 0, mrr10: 0 };
+}
+function accumulate(cases) {
+    const n = cases.length;
+    if (n === 0)
+        return emptyMetrics();
+    let hit1 = 0, hit5 = 0, mrrSum = 0;
+    for (const c of cases) {
+        if (c.rank === 1)
+            hit1++;
+        if (c.rank !== null && c.rank <= 5)
+            hit5++;
+        mrrSum += c.rank !== null ? 1 / c.rank : 0;
+    }
+    return { count: n, hit1: hit1 / n, hit5: hit5 / n, mrr10: mrrSum / n };
+}
+class RetrievalEvaluator {
+    async evaluate(suite, search, inspect) {
+        const cases = [];
+        const invalid = [];
+        const warnings = [];
+        for (const c of suite.cases) {
+            const { valid, invalid: invalidExpects } = await validateCase(c, inspect);
+            if (valid.length === 0) {
+                invalid.push({ id: c.id, reason: 'no valid expected answer', invalidExpects });
+                continue;
+            }
+            if (invalidExpects.length > 0) {
+                warnings.push({ id: c.id, droppedExpects: invalidExpects });
+            }
+            const hits = await search(c.query, 10, c.project, c.threshold);
+            const { rank, matched } = rankOf(hits, valid);
+            cases.push({ id: c.id, project: c.project, category: c.category, query: c.query, rank, matched });
+        }
+        const byCategory = {};
+        for (const category of ['identifier', 'behaviour', 'concept']) {
+            const subset = cases.filter(c => c.category === category);
+            if (subset.length > 0)
+                byCategory[category] = accumulate(subset);
+        }
+        return { cases, invalid, warnings, metrics: { overall: accumulate(cases), byCategory } };
+    }
+}
+exports.RetrievalEvaluator = RetrievalEvaluator;
+function metricDelta(baseline, current) {
+    return { baseline, current, delta: current - baseline };
+}
+function metricsDelta(baseline, current) {
+    return {
+        count: metricDelta(baseline.count, current.count),
+        hit1: metricDelta(baseline.hit1, current.hit1),
+        hit5: metricDelta(baseline.hit5, current.hit5),
+        mrr10: metricDelta(baseline.mrr10, current.mrr10),
+    };
+}
+/** Pure comparison of two result files; prints a warning (never refuses) on mismatched conditions. */
+function compare(baseline, current) {
+    const conditionWarnings = [];
+    if (baseline.metadata.suiteHash !== current.metadata.suiteHash) {
+        conditionWarnings.push(`suite differs: baseline ${baseline.metadata.suiteHash} vs current ${current.metadata.suiteHash}`);
+    }
+    if (baseline.metadata.embeddingModel !== current.metadata.embeddingModel) {
+        conditionWarnings.push(`embedding model differs: baseline ${baseline.metadata.embeddingModel} vs current ${current.metadata.embeddingModel}`);
+    }
+    if (baseline.metadata.rerankerModel !== current.metadata.rerankerModel) {
+        conditionWarnings.push(`reranker differs: baseline ${baseline.metadata.rerankerModel ?? 'none'} vs current ${current.metadata.rerankerModel ?? 'none'}`);
+    }
+    const byCategory = {};
+    for (const category of ['identifier', 'behaviour', 'concept']) {
+        const b = baseline.run.metrics.byCategory[category];
+        const cur = current.run.metrics.byCategory[category];
+        if (b && cur)
+            byCategory[category] = metricsDelta(b, cur);
+    }
+    const baselineRanked = new Map(baseline.run.cases.map(c => [c.id, c.rank]));
+    const currentRanked = new Map(current.run.cases.map(c => [c.id, c.rank]));
+    const hit5Gained = [];
+    const hit5Lost = [];
+    const allIds = new Set([...baselineRanked.keys(), ...currentRanked.keys()]);
+    for (const id of allIds) {
+        const b = baselineRanked.get(id) ?? null;
+        const cur = currentRanked.get(id) ?? null;
+        const bHit5 = b !== null && b <= 5;
+        const curHit5 = cur !== null && cur <= 5;
+        if (!bHit5 && curHit5)
+            hit5Gained.push(id);
+        if (bHit5 && !curHit5)
+            hit5Lost.push(id);
+    }
+    return {
+        overall: metricsDelta(baseline.run.metrics.overall, current.run.metrics.overall),
+        byCategory,
+        hit5Gained,
+        hit5Lost,
+        conditionWarnings,
+    };
+}

package/dist/src/services/AstParserService.d.ts

@@ -1,9 +1,16 @@
+import { Node } from 'ts-morph';
 import type { IAstParser, DepEdge, FileAnalysis, AnalyzeProjectOpts } from '../interfaces/IAstParser';
 import type { ILogger } from '../interfaces';
+/** Test seam for `graphql-symbols`' resolve-field parent-type resolution —
+ * defaults to the alias-following type-checker lookup `extractCalls` already uses. */
+export interface AstParserDeps {
+    resolveDeclaration?(identifier: Node): Node | undefined;
+}
 export declare class AstParserService implements IAstParser {
     private logger;
+    private deps;
     private morphProjects;
-    constructor(logger?: ILogger);
+    constructor(logger?: ILogger, deps?: AstParserDeps);
     analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;
     analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
@@ -12,6 +19,10 @@ export declare class AstParserService implements IAstParser {
     private createMorphProject;
     private getMorphProject;
     private extractEdges;
+    /** Manual fallback for a bindingless import specifier (design.md decision 2) —
+     * ts-morph's `getModuleSpecifierSourceFile()` is `null` for these even when
+     * the target is a real project file, since nothing is bound to resolve through. */
+    private resolveSideEffectModuleSpecifier;
     private resolveFromSymbol;
     private buildUsageMap;
     private getPos;
@@ -26,6 +37,60 @@ export declare class AstParserService implements IAstParser {
      * own first-to-last line — decorator-inclusive, comment-exclusive, and (for a
      * variable) the declarator alone, never the whole statement. */
     private buildOwnerRanges;
+    /** Local name → the name exported by `@nestjs/graphql`, for every named import
+     * of that module specifier (aliases followed). Recognition is import-based,
+     * not type-checker-based, so `skipFileDependencyResolution` batches agree. */
+    private buildGraphqlImportMap;
+    /** The identifier naming a decorator's expression (`@Foo` or the callee of `@Foo(...)`). */
+    private static decoratorIdentifier;
+    /** `dec` recognised against `importMap` — its exported `@nestjs/graphql` name and its call arguments (`[]` for a bare `@Foo`). */
+    private recognizedDecorator;
+    private static literalStringValue;
+    private static checkGraphqlGrammar;
+    /** `true` when any decorator argument is an (unwrapped) options object
+     * literal with `isAbstract: true` — an abstract base type (`PaginatedType`
+     * pattern) that NestJS never registers in the actual GraphQL schema. */
+    private static isAbstractGraphqlType;
+    /** `obj`'s own `name` property (`PropertyAssignment` or `ShorthandPropertyAssignment`), if any. */
+    private static findNameProperty;
+    /** Strips parens/`as`/`satisfies`/non-null wrappers (any nesting) to find the
+     * underlying node — used only to classify an argument's *shape* (type
+     * function vs. options object vs. literal vs. other), never to read a name
+     * value through the wrapper (decision 4 of `graphql-symbols` forbids that). */
+    private static peekThroughWrapper;
+    /**
+     * GraphQL name from a decorator's arguments (design decision 4 of
+     * `graphql-symbols`) — syntactic, no wrapper looked through at any step.
+     * `allowOptionsName` gates step 2 (the `name` option — `Query`/`Mutation`/
+     * `Subscription`/`ResolveField` only); `fallbackName` is the TS name used at
+     * step 3.
+     */
+    private deriveGraphqlName;
+    private logGraphqlSkip;
+    /** `declNode`'s qualified TypeScript name for diagnostics, independent of
+     * whether its own `code_symbol` row was actually written. */
+    private declarationNameFor;
+    /** The identifier named by a `@Resolver` argument: directly, or as an arrow
+     * function's expression body; or the sole identifier of a single-element
+     * array literal in either position (list-returning resolver). */
+    private static extractResolverIdentifier;
+    private defaultResolveDeclaration;
+    /** The GraphQL type name of a `@ResolveField`'s resolved parent class
+     * (design decision 5, second half): its recognised `@ObjectType` (else
+     * `@InterfaceType`) decorator, or its class name when it carries no
+     * decorator spelled `ObjectType`/`InterfaceType` at all, recognised or not. */
+    private classGraphqlTypeName;
+    /** The parent type of a `@ResolveField` — the enclosing class's recognised
+     * `@Resolver` argument (design decision 5, first half). */
+    private resolveResolverParentType;
+    private extractClassTypeRows;
+    private extractResolveFieldRow;
+    private extractMethodOperationRows;
+    /** GraphQL-named rows for every recognised `@nestjs/graphql` decorator in
+     * the file (`graphql-symbols`). `ownRows` is `symbols ∪ members` — the
+     * declarations' own `code_symbol` candidates, checked so a GraphQL row is
+     * never written without its decorated declaration's own row. */
+    private extractGraphqlNames;
     private static isValidSegment;
     private static memberName;
     private static unwrapExpr;