codesearch-mcp 0.2.3-alpha → 0.3.0-alpha

package/dist/src/retrieval-eval.js

@@ -1,11 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RetrievalEvaluator = exports.EvalSuiteError = void 0;
+exports.RetrievalEvaluator = exports.LIVE_GROUP = exports.EvalSuiteError = exports.STAGE_ORDER = void 0;
 exports.parseSuite = parseSuite;
+exports.corporaOf = corporaOf;
+exports.isUnderRoot = isUnderRoot;
+exports.checkCaseCorpora = checkCaseCorpora;
 exports.mergeSuites = mergeSuites;
+exports.signTest = signTest;
+exports.pairedChange = pairedChange;
 exports.compare = compare;
 const zod_1 = require("zod");
-/** Thrown by `parseSuite` before any search runs — names the offending case and field. */
+const CATEGORIES = ['identifier', 'behaviour', 'concept'];
+exports.STAGE_ORDER = ['vector', 'reranked'];
+const STAGE_SOURCE = { reranked: 'vector' };
+const UNRANKED = 11;
 class EvalSuiteError extends Error {
     caseId;
     field;
@@ -29,11 +37,15 @@ const CaseSchema = zod_1.z.object({
     expect: zod_1.z.array(ExpectedAnswerSchema).min(1),
     threshold: zod_1.z.number().min(0).max(1).optional(),
 });
+const CorpusSchema = zod_1.z.object({
+    root: zod_1.z.string().min(1).refine(r => !r.startsWith('/') && !r.split('/').includes('..') && !r.endsWith('/'), 'must be a workspace-relative directory'),
+    commit: zod_1.z.string().regex(/^[0-9a-f]{40}$/, 'must be a full 40-hex commit SHA'),
+}).strict();
 const SuiteSchema = zod_1.z.object({
     version: zod_1.z.literal(1),
+    corpus: CorpusSchema.optional(),
     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;
@@ -46,7 +58,6 @@ function rawCaseId(raw, index) {
     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) {
@@ -64,10 +75,40 @@ function parseSuite(raw) {
         }
         seen.add(c.id);
     }
-    return result.data;
+    const corpus = result.data.corpus?.root ?? null;
+    return { ...result.data, cases: result.data.cases.map(c => ({ ...c, corpus })) };
+}
+function corporaOf(suites) {
+    const byRoot = new Map();
+    for (const suite of suites) {
+        if (!suite.corpus)
+            continue;
+        const prev = byRoot.get(suite.corpus.root);
+        if (prev && prev.commit !== suite.corpus.commit) {
+            throw new EvalSuiteError(`Corpus ${suite.corpus.root} is declared at two commits: ${prev.commit} and ${suite.corpus.commit}`, null, 'corpus');
+        }
+        byRoot.set(suite.corpus.root, { root: suite.corpus.root, commit: suite.corpus.commit });
+    }
+    return [...byRoot.values()].sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0));
+}
+function isUnderRoot(dir, root) {
+    return dir === root || dir.startsWith(root + '/');
+}
+async function checkCaseCorpora(cases, projectDir) {
+    for (const c of cases) {
+        if (!c.corpus)
+            continue;
+        const dir = await projectDir(c.project);
+        if (dir === null) {
+            throw new EvalSuiteError(`Project ${c.project} is not indexed, so it cannot be checked against corpus ${c.corpus} (case ${c.id}, field project)`, c.id, 'project');
+        }
+        if (!isUnderRoot(dir, c.corpus)) {
+            throw new EvalSuiteError(`Project ${c.project} (${dir}) is outside corpus ${c.corpus} (case ${c.id}, field project)`, c.id, 'project');
+        }
+    }
 }
-/** Merges several suites (already parsed) into one; case ids must be unique across all of them. */
 function mergeSuites(suites) {
+    corporaOf(suites);
     const cases = [];
     const seen = new Set();
     for (const suite of suites) {
@@ -80,7 +121,6 @@ function mergeSuites(suites) {
     }
     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 + '.');
 }
@@ -117,45 +157,209 @@ function rankOf(hits, valid) {
 function emptyMetrics() {
     return { count: 0, hit1: 0, hit5: 0, mrr10: 0 };
 }
-function accumulate(cases) {
-    const n = cases.length;
+function accumulate(ranks) {
+    const n = ranks.length;
     if (n === 0)
         return emptyMetrics();
     let hit1 = 0, hit5 = 0, mrrSum = 0;
-    for (const c of cases) {
-        if (c.rank === 1)
+    for (const rank of ranks) {
+        if (rank === 1)
             hit1++;
-        if (c.rank !== null && c.rank <= 5)
+        if (rank !== null && rank <= 5)
             hit5++;
-        mrrSum += c.rank !== null ? 1 / c.rank : 0;
+        mrrSum += rank !== null ? 1 / rank : 0;
     }
     return { count: n, hit1: hit1 / n, hit5: hit5 / n, mrr10: mrrSum / n };
 }
+function stageRank(c, stage) {
+    return c.stages[stage]?.rank ?? null;
+}
+function stageMetrics(cases, stage) {
+    const byCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = cases.filter(c => c.category === category);
+        if (subset.length > 0)
+            byCategory[category] = accumulate(subset.map(c => stageRank(c, stage)));
+    }
+    return { overall: accumulate(cases.map(c => stageRank(c, stage))), byCategory };
+}
+function poolMetricsOf(cases) {
+    const count = cases.length;
+    return {
+        count,
+        recall: count === 0 ? 0 : cases.filter(c => c.poolRank !== null).length / count,
+        short: cases.filter(c => c.short).length,
+    };
+}
+function binomialCdfHalf(k, n) {
+    let pmf = Math.pow(0.5, n);
+    let cdf = pmf;
+    for (let i = 1; i <= k; i++) {
+        pmf = pmf * (n - i + 1) / i;
+        cdf += pmf;
+    }
+    return cdf;
+}
+function signTest(improved, worsened) {
+    const n = improved + worsened;
+    if (n === 0)
+        return 1;
+    return Math.min(1, 2 * binomialCdfHalf(Math.min(improved, worsened), n));
+}
+function pairCounts(pairs) {
+    let improved = 0, worsened = 0, unchanged = 0;
+    for (const p of pairs) {
+        if (p.to < p.from)
+            improved++;
+        else if (p.to > p.from)
+            worsened++;
+        else
+            unchanged++;
+    }
+    return { improved, worsened, unchanged, signTestP: signTest(improved, worsened) };
+}
+function pairedChange(from, to) {
+    const fromById = new Map(from.map(c => [c.id, c.rank]));
+    const pairs = [];
+    for (const c of to) {
+        if (!fromById.has(c.id))
+            continue;
+        pairs.push({ id: c.id, category: c.category, from: fromById.get(c.id) ?? UNRANKED, to: c.rank ?? UNRANKED });
+    }
+    const byCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = pairs.filter(p => p.category === category);
+        if (subset.length > 0)
+            byCategory[category] = pairCounts(subset);
+    }
+    return {
+        overall: pairCounts(pairs),
+        byCategory,
+        hit5Gained: pairs.filter(p => p.from > 5 && p.to <= 5).map(p => p.id),
+        hit5Lost: pairs.filter(p => p.from <= 5 && p.to > 5).map(p => p.id),
+    };
+}
+function rankedCases(cases, stage) {
+    return cases.map(c => ({ id: c.id, category: c.category, rank: stageRank(c, stage) }));
+}
+function stageChangesOf(cases, stages) {
+    const changes = [];
+    for (const to of stages) {
+        const from = STAGE_SOURCE[to];
+        if (from && stages.includes(from)) {
+            changes.push({ from, to, change: pairedChange(rankedCases(cases, from), rankedCases(cases, to)) });
+        }
+    }
+    return changes;
+}
+function reportedStages(stages) {
+    return exports.STAGE_ORDER.filter(s => stages[s] !== undefined);
+}
+function sortedDistinct(values) {
+    return [...new Set(values)].sort((a, b) => {
+        if (a === b)
+            return 0;
+        if (a === null)
+            return -1;
+        if (b === null)
+            return 1;
+        return a < b ? -1 : 1;
+    });
+}
+exports.LIVE_GROUP = 'live';
+function runFigures(cases, stages, shortPool) {
+    const metrics = {};
+    for (const stage of stages)
+        metrics[stage] = stageMetrics(cases, stage);
+    const poolInput = (subset) => subset.map(c => ({ poolRank: c.poolRank, short: shortPool.get(c.id) }));
+    const poolByCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = cases.filter(c => c.category === category);
+        if (subset.length > 0)
+            poolByCategory[category] = poolMetricsOf(poolInput(subset));
+    }
+    return {
+        cases: cases.length,
+        metrics,
+        pool: { overall: poolMetricsOf(poolInput(cases)), byCategory: poolByCategory },
+        stageChanges: stageChangesOf(cases, stages),
+    };
+}
 class RetrievalEvaluator {
-    async evaluate(suite, search, inspect) {
+    async evaluate(suite, search, inspect, onCase) {
+        await checkCaseCorpora(suite.cases, p => inspect.projectDir(p));
         const cases = [];
+        const shortPool = new Map();
         const invalid = [];
         const warnings = [];
-        for (const c of suite.cases) {
+        const fetchLimits = [];
+        const efSearches = [];
+        const iterativeScans = [];
+        let stages = null;
+        const total = suite.cases.length;
+        for (const [i, c] of suite.cases.entries()) {
+            const started = Date.now();
+            const report = (result, inv) => onCase?.({ index: i + 1, total, id: c.id, result, invalid: inv, ms: Date.now() - started });
             const { valid, invalid: invalidExpects } = await validateCase(c, inspect);
             if (valid.length === 0) {
-                invalid.push({ id: c.id, reason: 'no valid expected answer', invalidExpects });
+                const inv = { id: c.id, reason: 'no valid expected answer', invalidExpects };
+                invalid.push(inv);
+                report(null, inv);
                 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 caseStages = reportedStages(hits.stages);
+            if (stages === null) {
+                stages = caseStages;
+            }
+            else if (caseStages.join(',') !== stages.join(',')) {
+                throw new Error(`Case ${c.id} reported stages [${caseStages.join(', ')}], but the run's stages are [${stages.join(', ')}]`);
+            }
+            const ranks = {};
+            for (const stage of caseStages)
+                ranks[stage] = rankOf(hits.stages[stage], valid);
+            const result = {
+                id: c.id, project: c.project, category: c.category, query: c.query,
+                stages: ranks,
+                poolRank: rankOf(hits.pool, valid).rank,
+                poolSize: hits.pool.length,
+                rerankFailed: hits.rerankFailed,
+                corpus: c.corpus ?? null,
+            };
+            cases.push(result);
+            shortPool.set(c.id, hits.pool.length < hits.fetchLimit);
+            fetchLimits.push(hits.fetchLimit);
+            efSearches.push(hits.indexParams.efSearch);
+            iterativeScans.push(hits.indexParams.iterativeScan);
+            report(result, null);
         }
-        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);
+        const runStages = stages ?? ['vector'];
+        const figures = (subset) => runFigures(subset, runStages, shortPool);
+        const byCorpus = {};
+        for (const key of [...new Set(cases.map(c => c.corpus ?? exports.LIVE_GROUP))].sort()) {
+            byCorpus[key] = figures(cases.filter(c => (c.corpus ?? exports.LIVE_GROUP) === key));
         }
-        return { cases, invalid, warnings, metrics: { overall: accumulate(cases), byCategory } };
+        const all = figures(cases);
+        const observed = {
+            fetchLimit: sortedDistinct(fetchLimits),
+            efSearch: sortedDistinct(efSearches),
+            iterativeScan: sortedDistinct(iterativeScans),
+        };
+        return {
+            run: {
+                cases, invalid, warnings,
+                stages: runStages,
+                metrics: all.metrics,
+                pool: all.pool,
+                stageChanges: all.stageChanges,
+                rerankFailures: cases.filter(c => c.rerankFailed).length,
+                byCorpus,
+            },
+            observed,
+        };
     }
 }
 exports.RetrievalEvaluator = RetrievalEvaluator;
@@ -170,45 +374,127 @@ function metricsDelta(baseline, current) {
         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}`);
+function metricsDeltaByCategory(baseline, current) {
+    const out = {};
+    for (const category of CATEGORIES) {
+        const b = baseline[category];
+        const cur = current[category];
+        if (b && cur)
+            out[category] = metricsDelta(b, cur);
     }
-    if (baseline.metadata.embeddingModel !== current.metadata.embeddingModel) {
-        conditionWarnings.push(`embedding model differs: baseline ${baseline.metadata.embeddingModel} vs current ${current.metadata.embeddingModel}`);
+    return out;
+}
+function poolValueDelta(baseline, current) {
+    return { baseline, current, delta: baseline === null ? null : current - baseline };
+}
+function poolDelta(baseline, current) {
+    return {
+        recall: poolValueDelta(baseline?.recall ?? null, current.recall),
+        short: poolValueDelta(baseline?.short ?? null, current.short),
+    };
+}
+function formatCondition(value) {
+    return Array.isArray(value) ? `[${value.map(v => (v === null ? 'not sent' : String(v))).join(', ')}]` : String(value);
+}
+function corpusWarningsOf(b, cur) {
+    const warnings = [];
+    if (b.corpora.length === 0)
+        warnings.push('baseline records no corpus');
+    const baseByRoot = new Map(b.corpora.map(c => [c.root, c]));
+    const curByRoot = new Map(cur.corpora.map(c => [c.root, c]));
+    for (const root of [...new Set([...baseByRoot.keys(), ...curByRoot.keys()])].sort()) {
+        const bc = baseByRoot.get(root), cc = curByRoot.get(root);
+        if (!bc) {
+            warnings.push(`corpus ${root} only in the current run`);
+            continue;
+        }
+        if (!cc) {
+            warnings.push(`corpus ${root} only in the baseline`);
+            continue;
+        }
+        if (bc.commit !== cc.commit) {
+            warnings.push(`corpus ${root} commit differs: baseline ${bc.commit} vs current ${cc.commit}`);
+        }
+        else if (bc.fingerprint !== cc.fingerprint) {
+            warnings.push(`corpus ${root} was searched on a different index build: fingerprint ${bc.fingerprint} (${bc.chunks} chunks) vs ${cc.fingerprint} (${cc.chunks} chunks)`);
+        }
     }
-    if (baseline.metadata.rerankerModel !== current.metadata.rerankerModel) {
-        conditionWarnings.push(`reranker differs: baseline ${baseline.metadata.rerankerModel ?? 'none'} vs current ${current.metadata.rerankerModel ?? 'none'}`);
+    const live = (side, n) => `${side} includes ${n} live-corpus case(s); differences may come from code changes`;
+    if (b.liveCases > 0)
+        warnings.push(live('baseline', b.liveCases));
+    if (cur.liveCases > 0)
+        warnings.push(live('current run', cur.liveCases));
+    return warnings;
+}
+function conditionWarningsOf(baseline, current) {
+    const warnings = [];
+    const b = baseline.metadata, cur = current.metadata;
+    if (b.suiteHash !== cur.suiteHash) {
+        warnings.push(`suite differs: baseline ${b.suiteHash} vs current ${cur.suiteHash}`);
     }
-    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);
+    if (b.embeddingModel !== cur.embeddingModel) {
+        warnings.push(`embedding model differs: baseline ${b.embeddingModel} vs current ${cur.embeddingModel}`);
+    }
+    if (b.rerankerModel !== cur.rerankerModel) {
+        warnings.push(`reranker differs: baseline ${b.rerankerModel ?? 'none'} vs current ${cur.rerankerModel ?? 'none'}`);
+    }
+    if (!b.conditions)
+        warnings.push('baseline records no search conditions');
+    if (!cur.conditions)
+        warnings.push('current run records no search conditions');
+    if (b.conditions && cur.conditions) {
+        const bc = b.conditions;
+        const cc = cur.conditions;
+        for (const key of [...new Set([...Object.keys(bc), ...Object.keys(cc)])]) {
+            if (!(key in bc))
+                warnings.push(`search condition ${key} recorded only by the current run (${formatCondition(cc[key])})`);
+            else if (!(key in cc))
+                warnings.push(`search condition ${key} recorded only by the baseline (${formatCondition(bc[key])})`);
+            else if (JSON.stringify(bc[key]) !== JSON.stringify(cc[key])) {
+                warnings.push(`${key} differs: baseline ${formatCondition(bc[key])} vs current ${formatCondition(cc[key])}`);
+            }
+        }
+    }
+    warnings.push(...corpusWarningsOf(b, cur));
+    if (baseline.run.rerankFailures > 0)
+        warnings.push(`baseline has ${baseline.run.rerankFailures} rerank failure(s)`);
+    if (current.run.rerankFailures > 0)
+        warnings.push(`current run has ${current.run.rerankFailures} rerank failure(s)`);
+    return warnings;
+}
+function compare(baseline, current) {
+    const stages = [];
+    for (const stage of current.run.stages) {
+        const b = baseline.run.metrics[stage];
+        const cur = current.run.metrics[stage];
+        if (!baseline.run.stages.includes(stage) || !b || !cur)
+            continue;
+        stages.push({
+            stage,
+            overall: metricsDelta(b.overall, cur.overall),
+            byCategory: metricsDeltaByCategory(b.byCategory, cur.byCategory),
+            change: pairedChange(rankedCases(baseline.run.cases, stage), rankedCases(current.run.cases, stage)),
+        });
+    }
+    const unmatchedStages = [
+        ...baseline.run.stages.filter(s => !current.run.stages.includes(s)).map(stage => ({ stage, side: 'baseline' })),
+        ...current.run.stages.filter(s => !baseline.run.stages.includes(s)).map(stage => ({ stage, side: 'current' })),
+    ];
+    const basePool = baseline.legacy ? null : baseline.run.pool;
+    const poolByCategory = {};
+    for (const category of CATEGORIES) {
+        const cur = current.run.pool.byCategory[category];
+        if (!cur)
+            continue;
+        if (basePool === null)
+            poolByCategory[category] = poolDelta(null, cur);
+        else if (basePool.byCategory[category])
+            poolByCategory[category] = poolDelta(basePool.byCategory[category], cur);
     }
     return {
-        overall: metricsDelta(baseline.run.metrics.overall, current.run.metrics.overall),
-        byCategory,
-        hit5Gained,
-        hit5Lost,
-        conditionWarnings,
+        stages,
+        unmatchedStages,
+        pool: { overall: poolDelta(basePool?.overall ?? null, current.run.pool.overall), byCategory: poolByCategory },
+        conditionWarnings: conditionWarningsOf(baseline, current),
     };
 }

package/dist/src/search/result-shaping.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_PER_FILE = 2;
+export declare function limitPerFile<T extends {
+    filePath: string;
+}>(ranked: T[], limit: number, perFile: number): T[];

package/dist/src/search/result-shaping.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PER_FILE = void 0;
+exports.limitPerFile = limitPerFile;
+exports.DEFAULT_PER_FILE = 2;
+function limitPerFile(ranked, limit, perFile) {
+    const taken = [];
+    const perFileCount = new Map();
+    for (const entry of ranked) {
+        if (taken.length >= limit)
+            break;
+        const count = perFileCount.get(entry.filePath) ?? 0;
+        if (count >= perFile)
+            continue;
+        perFileCount.set(entry.filePath, count + 1);
+        taken.push(entry);
+    }
+    return taken;
+}

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

@@ -1,8 +1,6 @@
 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;
 }
@@ -10,6 +8,7 @@ export declare class AstParserService implements IAstParser {
     private logger;
     private deps;
     private morphProjects;
+    private readonly declarationBuilder;
     constructor(logger?: ILogger, deps?: AstParserDeps);
     analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;
@@ -19,77 +18,32 @@ 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;
-    /** Trimmed text of the source line containing `node`'s start — the signature
-     * rule for every kind (name node for members, the position node for
-     * constructors/anonymous default classes). */
     private lineTextAt;
     private extractSymbols;
     private extractMembers;
-    /** Chunk-ownership ranges from every indexed declaration (top-level symbols +
-     * members) except `method_signature`. Each range spans the declaration node's
-     * 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 buildDeclarations;
     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;
@@ -99,24 +53,10 @@ export declare class AstParserService implements IAstParser {
     private classExpressionRoot;
     private objectLiteralRootValid;
     private isTopLevelOrNamespaceDirect;
-    /** One step of the ancestor walk used by `containerSegments`: does `node`
-     * contribute a named segment, pass through transparently, or disqualify
-     * (exclude) everything nested inside it? */
     private walkStep;
-    /** The dotted container path of `node`'s enclosing named scopes, outermost
-     * first, or null when any contributing ancestor is invalid (a computed /
-     * string-literal segment, a string-named module, `declare global`, or an
-     * unrooted class expression / object literal). */
     private containerSegments;
-    /** If `node` is a declaration this service indexes (top-level symbol, member,
-     * or collected class), its own name + container. Otherwise null. Shared by
-     * member extraction, ownership ranges and the call graph so all three name a
-     * declaration identically. */
     private describeIndexedNode;
     private qualifiedName;
-    /** The qualified name of the nearest ancestor of `node` that is itself an
-     * indexed declaration (method, accessor, constructor, function property,
-     * namespace/top-level function, or module-/namespace-level variable). */
     private findFromSymbol;
     private extractCalls;
 }