codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/interfaces/IAstParser.d.ts

@@ -1,3 +1,4 @@
+import type { DeclarationTree } from '../declarations/DeclarationTree';
 export interface DepEdge {
     project: string;
     fromFile: string;
@@ -6,7 +7,7 @@ export interface DepEdge {
     toSymbol: string | null;
     depType: string;
 }
-export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature';
+export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'graphql_query' | 'graphql_mutation' | 'graphql_subscription' | 'graphql_field' | 'graphql_type';
 export interface SymbolEntry {
     project: string;
     filePath: string;
@@ -16,14 +17,9 @@ export interface SymbolEntry {
     line: number | null;
     endLine: number | null;
     col: number | null;
-    /** Dotted path of enclosing named scopes, outermost first; null for top-level declarations. */
     container: string | null;
     isStatic: boolean;
-    /**
-     * Whether this declaration node has a body (vs. an overload signature).
-     * Internal — used only to pick an overload set's representative row before
-     * writing to `code_symbol`; never persisted.
-     */
+    target?: string | null;
     hasBody?: boolean;
 }
 export interface CallEdge {
@@ -36,40 +32,19 @@ export interface CallEdge {
     line: number | null;
     col: number | null;
 }
-/**
- * Line range of a named scope used only to compute a chunk's owning declaration
- * (`ownerPath`). Method/constructor/accessor ranges carry their enclosing class
- * as `container`; top-level declarations use `container: null`. These are NOT
- * persisted to `code_symbol` — they exist only for chunk ownership.
- */
-export interface OwnerRange {
-    name: string;
-    container: string | null;
-    line: number;
-    endLine: number;
-}
 export interface FileAnalysis {
     edges: DepEdge[];
-    /** Top-level declarations only — feeds the chunker and the embedding prompt. */
     symbols: SymbolEntry[];
-    /** Members, namespace-level declarations and classes collected from the whole
-     * file. Written to `code_symbol` alongside `symbols`; never fed to the
-     * chunker or the prompt (see the `symbol-index-members` retrieval-invariance
-     * requirement). */
     members: SymbolEntry[];
     calls: CallEdge[];
-    /** Ownership ranges (decorator-inclusive) for every indexed declaration except `method_signature`. */
-    ownerRanges?: OwnerRange[];
+    declarations?: DeclarationTree;
+    graphqlNames: SymbolEntry[];
 }
 export interface AnalyzeProjectOpts {
     skipDependencyResolution?: boolean;
-    /** Path to root tsconfig (e.g. tsconfig.base.json) for workspace-wide path aliases */
     rootTsConfigPath?: string;
 }
 export interface IAstParser {
-    /**
-     * @deprecated Use analyzeProject instead for project-wide context.
-     */
     analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
     analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;

package/dist/src/interfaces/IChunker.d.ts

@@ -1,24 +1,15 @@
-import type { SymbolEntry } from './IAstParser';
-/** One embeddable unit of source with its 1-based inclusive line range. */
+import type { DeclarationTree } from '../declarations/DeclarationTree';
 export interface ChunkPiece {
     content: string;
     startLine: number;
     endLine: number;
 }
 export interface ChunkOpts {
-    /** 'ast' = symbol-aligned boundaries; 'character' = fixed-size recursive splitter. */
     strategy: 'ast' | 'character';
-    /** Schema files (.prisma/.graphql/.gql) always use the schema separator splitter. */
     isSchemaFile: boolean;
-    /** Top-level symbol ranges for the file; may be empty (no analysis available). */
-    symbols: SymbolEntry[];
+    declarations?: DeclarationTree;
+    jsx?: boolean;
 }
 export interface IChunker {
-    /**
-     * Split source into embeddable pieces. AST strategy aligns boundaries to
-     * top-level declaration ranges and never emits a piece longer than the
-     * configured chunk size; falls back to the character splitter for schema
-     * files, empty-symbol files, or when strategy is 'character'.
-     */
     chunk(code: string, opts: ChunkOpts): Promise<ChunkPiece[]>;
 }

package/dist/src/interfaces/ICorpusInspector.d.ts

@@ -0,0 +1,7 @@
+export interface ICorpusInspector {
+    headCommit(root: string): Promise<string>;
+    trackedChanges(root: string): Promise<string[]>;
+    untrackedFiles(root: string, skipDirs: readonly string[]): Promise<string[]>;
+    listFiles(dir: string): Promise<string[]>;
+    readFile(absPath: string): Promise<Buffer | null>;
+}

package/dist/src/interfaces/ICorpusInspector.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/IDatabase.d.ts

@@ -1,58 +1,24 @@
 import type { DrizzleDb, DrizzleTx } from '../services/DatabaseService';
-/** Single-row record of which embedding model built the current index. */
 export interface IndexMeta {
     provider: string;
     model: string;
     dimensions: number;
 }
-/**
- * Database abstraction — services depend on this interface
- * rather than the concrete DatabaseService.
- */
 export interface IDatabase {
     readonly orm: DrizzleDb;
     query<T = any>(sql: string, params?: any[]): Promise<T>;
+    queryWithLocalSettings<T = any>(settings: Record<string, string | number>, sql: string, params?: any[]): Promise<T>;
+    pgvectorVersion(): Promise<string | null>;
     transaction<T>(fn: (tx: DrizzleTx) => Promise<T>): Promise<T>;
     initDb(): Promise<void>;
     initDbWithSchema(): Promise<void>;
     destroy(): Promise<void>;
-    /** Read the single `index_meta` row, or null when absent (table missing → null). */
     readIndexMeta(): Promise<IndexMeta | null>;
-    /** Upsert the single `index_meta` row. */
     writeIndexMeta(meta: IndexMeta): Promise<void>;
-    /** Create `code_chunk` (+ HNSW/service indexes) at `dimensions` if absent. */
     ensureChunkTable(dimensions: number): Promise<void>;
-    /** Drop and recreate `code_chunk` at `dimensions` (dimension change). */
     recreateChunkTable(dimensions: number): Promise<void>;
-    /**
-     * Return all file paths referenced in any of the four index tables for `project`.
-     * Union of code_chunk.filePath, code_symbol.filePath, code_call.fromFile,
-     * code_dependency.fromFile. calleeFile and toFile are excluded (may belong to other projects).
-     */
     listKnownFiles(project: string): Promise<string[]>;
-    /**
-     * Delete rows for `filePaths` from all four index tables in one transaction.
-     * code_call rows where the file is either fromFile OR calleeFile are removed.
-     * code_dependency rows where the file is either fromFile OR toFile are removed.
-     * No-op when `filePaths` is empty.
-     */
     deleteFiles(project: string, filePaths: string[]): Promise<void>;
-    /** Return all project names referenced in any of the four index tables. */
     listIndexedProjects(): Promise<string[]>;
-    /** Delete all rows for `name` from the four index tables in one transaction. */
     deleteProject(name: string): Promise<void>;
-    /** Every project with at least one row in `code_chunk` or `code_symbol` — the
-     * symbol/call-graph lookup scope (distinct from `listIndexedProjects`, which
-     * also covers `code_call`/`code_dependency`). */
-    listProjectsWithIndexRows(): Promise<string[]>;
-    /**
-     * Among `projectNames` (or every project with rows when null), those that
-     * are outdated: at least one row in `code_chunk`/`code_symbol` and a
-     * `symbol_index_version` below the current format version (missing row = 1).
-     * A missing `symbol_index_version` table counts as "no marker rows" for every
-     * project. Any other database error propagates.
-     */
-    listOutdatedProjects(projectNames: string[] | null): Promise<string[]>;
-    /** Upsert a project's `symbol_index_version` marker to the current format version. */
-    upsertSymbolIndexVersion(project: string): Promise<void>;
 }

package/dist/src/interfaces/IEmbedder.d.ts

@@ -1,16 +1,7 @@
 export type InputType = 'query' | 'document';
 export interface IEmbedder {
-    /**
-     * The vector width this embedder produces, when known without a probe:
-     * `embedding.dimensions` override → model registry, else `0` for models whose
-     * width is only knowable by embedding once (see `resolveDimension`). Read by
-     * `SearcherService.assertIndexMatches` to catch a dimension change on the
-     * search side (skipped when `0`). Indexing resolves the true width via
-     * `resolveDimension` (which probes when needed), not this field.
-     */
     readonly dimensions: number;
     embed(text: string, inputType?: InputType): Promise<number[]>;
-    /** One vector per input, in input order. The indexing path. */
     embedBatch(texts: string[], inputType?: InputType): Promise<number[][]>;
     rerank?(query: string, documents: string[], topN: number): Promise<number[]>;
     listModels?(): Promise<string[]>;

package/dist/src/interfaces/ILogger.d.ts

@@ -1,17 +1,7 @@
-/**
- * Logger abstraction — allows services to depend on a contract
- * rather than the concrete pino-based LoggerService.
- */
 export interface ILogger {
     debug(msg: string, data?: Record<string, unknown>): void;
     info(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
-    /**
-     * Structured telemetry emitted at `info` **independent of the configured log
-     * level** — so an operator can collect it in production without the full
-     * `debug` firehose. No-op when file logging is disabled (never writes to
-     * stdout, which the MCP transport owns).
-     */
-    metric(msg: string, data?: Record<string, unknown>): void;
+    withContext<T>(context: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;
 }

package/dist/src/interfaces/IMcpToolHandler.d.ts

@@ -1,8 +1,3 @@
-/**
- * MCP Tool Handler interface — each tool implements this contract.
- * Follows the Open/Closed Principle: new tools are added by implementing
- * this interface and registering them, not by modifying McpServer.
- */
 export interface ToolDefinition {
     name: string;
     description: string;

package/dist/src/interfaces/IMonorepoResolver.d.ts

@@ -1,33 +1,11 @@
-/**
- * Represents a discovered project within a monorepo workspace.
- */
 export interface MonorepoProject {
-    /** Project name (e.g. "my-app", "shared-utils") */
     name: string;
-    /** Absolute path to the project root */
     path: string;
-    /** npm scope + package name (e.g. "@scope/my-app") — null if no package.json or no name */
     packageName: string | null;
-    /** "app" | "lib" — derived from project.json or directory convention */
     type: 'app' | 'lib';
 }
-/**
- * Monorepo resolver — detects and resolves workspace structure.
- * Implementations handle specific monorepo tooling (Nx, Turborepo, etc.)
- */
 export interface IMonorepoResolver {
-    /**
-     * Detect whether the given root directory is a monorepo workspace.
-     */
     isMonorepo(rootDir: string): boolean;
-    /**
-     * Discover all projects (apps + libs) in the monorepo.
-     */
     discoverProjects(rootDir: string): MonorepoProject[];
-    /**
-     * Get the root tsconfig path that contains workspace-wide path aliases.
-     * For Nx this is typically tsconfig.base.json at the workspace root.
-     * The AST parser uses this to resolve cross-project imports (@scope/*).
-     */
     getRootTsConfigPath(rootDir: string): string | null;
 }

package/dist/src/interfaces/IProjectDiscovery.d.ts

@@ -1,28 +1,11 @@
 export interface DiscoveredProject {
     name: string;
     path: string;
-    /** npm scope + package name (e.g. "@scope/my-app") — only set for monorepo projects */
     packageName?: string | null;
-    /** "app" | "lib" — only set for monorepo projects */
     type?: 'app' | 'lib';
-    /**
-     * Path to the workspace-wide tsconfig (e.g. tsconfig.base.json) that holds
-     * cross-project path aliases. Set for monorepo projects; undefined for flat
-     * workspaces (where each project uses its own local tsconfig.json).
-     */
     rootTsConfigPath?: string | null;
-    /**
-     * When a top-level directory is itself a nested monorepo (e.g. an Nx repo
-     * under a flat workspaceRoot), this holds its expanded sub-projects. The
-     * repo stays a single selectable unit; `toLeafProjects` expands `children`
-     * into the actual projects to index. Absent/undefined for ordinary projects.
-     */
     children?: DiscoveredProject[];
 }
-/**
- * Project discovery abstraction — decouples project enumeration
- * from the indexing service (Single Responsibility Principle).
- */
 export interface IProjectDiscovery {
     discover(rootDir: string): DiscoveredProject[];
 }

package/dist/src/interfaces/IRetrievalEvaluator.d.ts

@@ -0,0 +1,216 @@
+import type { StageName } from './ISearcher';
+export type { StageName };
+export type EvalCategory = 'identifier' | 'behaviour' | 'concept';
+export interface ExpectedAnswer {
+    file: string;
+    owner?: string;
+}
+export interface EvalCase {
+    id: string;
+    project: string;
+    category: EvalCategory;
+    query: string;
+    expect: ExpectedAnswer[];
+    threshold?: number;
+    corpus?: string | null;
+}
+export interface CorpusRef {
+    root: string;
+    commit: string;
+}
+export interface EvalSuite {
+    version: 1;
+    corpus?: CorpusRef;
+    cases: EvalCase[];
+}
+export interface SearchHit {
+    filePath: string;
+    ownerPath: string | null;
+}
+export interface StagedHits {
+    pool: SearchHit[];
+    stages: {
+        vector: SearchHit[];
+    } & Partial<Record<StageName, SearchHit[]>>;
+    rerankFailed: boolean;
+    fetchLimit: number;
+    indexParams: {
+        efSearch: number | null;
+        iterativeScan: string;
+    };
+}
+export type SearchFn = (query: string, limit: number, project: string | null, threshold?: number) => Promise<StagedHits>;
+export interface IndexInspector {
+    isFileIndexed(project: string, file: string): Promise<boolean>;
+    ownerPathsOfFile(project: string, file: string): Promise<string[]>;
+    projectDir(project: string): Promise<string | null>;
+}
+export interface Metrics {
+    count: number;
+    hit1: number;
+    hit5: number;
+    mrr10: number;
+}
+export interface StageRank {
+    rank: number | null;
+    matched: SearchHit | null;
+}
+export interface CaseResult {
+    id: string;
+    project: string;
+    category: EvalCategory;
+    query: string;
+    stages: Partial<Record<StageName, StageRank>>;
+    poolRank: number | null;
+    poolSize: number;
+    rerankFailed: boolean;
+    corpus: string | null;
+}
+export interface InvalidCase {
+    id: string;
+    reason: string;
+    invalidExpects: ExpectedAnswer[];
+}
+export interface PartialWarning {
+    id: string;
+    droppedExpects: ExpectedAnswer[];
+}
+export interface StageMetrics {
+    overall: Metrics;
+    byCategory: Partial<Record<EvalCategory, Metrics>>;
+}
+export interface PoolMetrics {
+    count: number;
+    recall: number;
+    short: number;
+}
+export interface PairCounts {
+    improved: number;
+    worsened: number;
+    unchanged: number;
+    signTestP: number;
+}
+export interface PairedChange {
+    overall: PairCounts;
+    byCategory: Partial<Record<EvalCategory, PairCounts>>;
+    hit5Gained: string[];
+    hit5Lost: string[];
+}
+export interface StageChange {
+    from: StageName;
+    to: StageName;
+    change: PairedChange;
+}
+export interface EvalRunResult {
+    cases: CaseResult[];
+    invalid: InvalidCase[];
+    warnings: PartialWarning[];
+    stages: StageName[];
+    metrics: Partial<Record<StageName, StageMetrics>>;
+    pool: {
+        overall: PoolMetrics;
+        byCategory: Partial<Record<EvalCategory, PoolMetrics>>;
+    };
+    stageChanges: StageChange[];
+    rerankFailures: number;
+    byCorpus: Record<string, CorpusRunMetrics>;
+}
+export interface CorpusRunMetrics {
+    cases: number;
+    metrics: Partial<Record<StageName, StageMetrics>>;
+    pool: {
+        overall: PoolMetrics;
+        byCategory: Partial<Record<EvalCategory, PoolMetrics>>;
+    };
+    stageChanges: StageChange[];
+}
+export interface ObservedSearchParams {
+    fetchLimit: number[];
+    efSearch: (number | null)[];
+    iterativeScan: string[];
+}
+export interface EvalOutcome {
+    run: EvalRunResult;
+    observed: ObservedSearchParams;
+}
+export interface CaseProgress {
+    index: number;
+    total: number;
+    id: string;
+    result: CaseResult | null;
+    invalid: InvalidCase | null;
+    ms: number;
+}
+export interface IRetrievalEvaluator {
+    evaluate(suite: EvalSuite, search: SearchFn, inspect: IndexInspector, onCase?: (p: CaseProgress) => void): Promise<EvalOutcome>;
+}
+export interface SearchConditions {
+    similarityThreshold: number;
+    overfetch: number;
+    candidateFloor: number;
+    fetchLimit: number[];
+    efSearch: (number | null)[];
+    iterativeScan: string[];
+}
+export interface ResultMetadata {
+    suitePath: string;
+    suiteHash: string;
+    embeddingProvider: string;
+    embeddingModel: string;
+    rerankerModel: string | null;
+    indexMeta: {
+        provider: string;
+        model: string;
+        dimensions: number;
+    } | null;
+    gitCommit: string;
+    timestamp: string;
+    conditions: SearchConditions | null;
+    corpora: CorpusRecord[];
+    liveCases: number;
+}
+export interface CorpusRecord {
+    root: string;
+    commit: string;
+    projects: string[];
+    chunks: number;
+    fingerprint: string;
+}
+export interface EvalResultFile {
+    metadata: ResultMetadata;
+    run: EvalRunResult;
+    legacy?: true;
+}
+export interface MetricDelta {
+    baseline: number;
+    current: number;
+    delta: number;
+}
+export type MetricsDelta = Record<keyof Metrics, MetricDelta>;
+export interface StageComparison {
+    stage: StageName;
+    overall: MetricsDelta;
+    byCategory: Partial<Record<EvalCategory, MetricsDelta>>;
+    change: PairedChange;
+}
+export interface PoolValueDelta {
+    baseline: number | null;
+    current: number;
+    delta: number | null;
+}
+export interface PoolDelta {
+    recall: PoolValueDelta;
+    short: PoolValueDelta;
+}
+export interface CompareResult {
+    stages: StageComparison[];
+    unmatchedStages: {
+        stage: StageName;
+        side: 'baseline' | 'current';
+    }[];
+    pool: {
+        overall: PoolDelta;
+        byCategory: Partial<Record<EvalCategory, PoolDelta>>;
+    };
+    conditionWarnings: string[];
+}

package/dist/src/interfaces/IRetrievalEvaluator.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/ISearcher.d.ts

@@ -1,8 +1,18 @@
-import type { SearchResult, NeighborResult, GraphContext, DependencyRow, ProjectRow, GrepMatch, SymbolKind, SymbolHit, CallerRow, FileRangeResult } from '../services/SearcherService';
-/**
- * Searcher abstraction — McpServer depends on this interface
- * rather than the concrete SearcherService.
- */
+import type { SearchResult, NeighborResult, GraphContext, DependencyRow, ProjectRow, SymbolKind, SymbolHit, CallerRow, FileRangeResult, ListFilesResult, GrepSymbolResult, ResolvedToolPath, PathFailure } from '../services/SearcherService';
+export type StageName = 'vector' | 'reranked';
+export interface StagedSearchResult {
+    pool: SearchResult[];
+    stages: {
+        vector: SearchResult[];
+        reranked?: SearchResult[];
+    };
+    rerankFailed: boolean;
+    fetchLimit: number;
+    indexParams: {
+        efSearch: number | null;
+        iterativeScan: string;
+    };
+}
 export interface ISearcher {
     prepareQuery(raw: string): Promise<{
         query: string;
@@ -14,27 +24,23 @@ export interface ISearcher {
         from: string;
         to: string;
     }[]>;
-    searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<SearchResult[]>;
+    searchChunksWithStages(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<StagedSearchResult>;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
     fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
-    getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
-    getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
-    grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
-        matches: GrepMatch[];
-        truncated: boolean;
-    }>;
+    grepSymbol(symbol: string, rootDir: string, excludeFile: string): Promise<GrepSymbolResult>;
     findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
         hits: SymbolHit[];
         truncated: boolean;
         grepFailed: boolean;
     }>;
-    /** One-line warning when a project in scope is outdated (see `SearcherService.outdatedNotice`), else null. */
-    outdatedNotice(project: string | null): Promise<string | null>;
-    listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
-        tree: string;
-        error?: string;
-    };
-    readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
-    readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    listFiles(relPath: string, depth: number, pattern: string | null): Promise<ListFilesResult>;
+    readFile(relPath: string, maxLines: number): Promise<FileRangeResult>;
+    readFileRange(relPath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    resolveToolPath(input: string | null | undefined): Promise<ResolvedToolPath>;
+    checkGraphPath(relPath: string): Promise<PathFailure | null>;
+    fallbackRoot(relPath: string): string | null;
 }

package/dist/src/interfaces/index.d.ts

@@ -6,3 +6,4 @@ export type { IDatabase } from './IDatabase';
 export type { ISearcher } from './ISearcher';
 export type { IProjectDiscovery, DiscoveredProject } from './IProjectDiscovery';
 export type { IMcpToolHandler, ToolDefinition, ToolResponse } from './IMcpToolHandler';
+export type { EvalCategory, ExpectedAnswer, EvalCase, EvalSuite, SearchHit, SearchFn, IndexInspector, Metrics, CaseResult, InvalidCase, PartialWarning, EvalRunResult, IRetrievalEvaluator, ResultMetadata, EvalResultFile, MetricDelta, MetricsDelta, CompareResult, } from './IRetrievalEvaluator';

package/dist/src/interrupt.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupInterrupt = setupInterrupt;
-// Graceful interruption for long-running CLI operations.
-// Caller creates the AbortController; this function wires stdin and returns a cleanup function.
 function setupInterrupt(controller) {
     if (!process.stdin.isTTY)
         return () => { };

package/dist/src/owner-path.d.ts

@@ -1,10 +1,9 @@
-import type { OwnerRange } from './interfaces/IAstParser';
-/**
- * Resolve the owning declaration for a chunk given its 1-based start line and a
- * flat list of candidate ranges (top-level symbols + method ranges). The
- * deepest range containing the start line wins (smallest `endLine - line` span),
- * so a method beats its enclosing class. Returns `Container.name` for methods
- * (via `container`) or `name` for top-level declarations, and `null` when the
- * start line lies outside every range (imports / module-scope gaps).
- */
-export declare function resolveOwnerPath(startLine: number, ranges: OwnerRange[]): string | null;
+import type { DeclarationTree } from './declarations/DeclarationTree';
+import type { SourceLines } from './declarations/SourceLines';
+interface LineSpan {
+    startLine: number;
+    endLine: number;
+}
+export declare function ownedLines(piece: LineSpan, declarations: DeclarationTree, lines: SourceLines): number[];
+export declare function ownerOf(piece: LineSpan, declarations: DeclarationTree, lines: SourceLines): string | null;
+export {};

package/dist/src/owner-path.js

@@ -1,27 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveOwnerPath = resolveOwnerPath;
-/**
- * Resolve the owning declaration for a chunk given its 1-based start line and a
- * flat list of candidate ranges (top-level symbols + method ranges). The
- * deepest range containing the start line wins (smallest `endLine - line` span),
- * so a method beats its enclosing class. Returns `Container.name` for methods
- * (via `container`) or `name` for top-level declarations, and `null` when the
- * start line lies outside every range (imports / module-scope gaps).
- */
-function resolveOwnerPath(startLine, ranges) {
-    let best = null;
-    let bestSpan = Infinity;
-    for (const r of ranges) {
-        if (r.line <= startLine && startLine <= r.endLine) {
-            const span = r.endLine - r.line;
-            if (span < bestSpan) {
-                bestSpan = span;
-                best = r;
-            }
-        }
+exports.ownedLines = ownedLines;
+exports.ownerOf = ownerOf;
+function ownedLines(piece, declarations, lines) {
+    const owned = [];
+    for (let n = piece.startLine; n <= piece.endLine; n++) {
+        if (lines.isSignificant(n) && declarations.contains(n))
+            owned.push(n);
     }
-    if (!best)
-        return null;
-    return best.container ? `${best.container}.${best.name}` : best.name;
+    return owned;
+}
+function ownerOf(piece, declarations, lines) {
+    return declarations.smallestContaining(ownedLines(piece, declarations, lines))?.qualifiedName ?? null;
 }

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

@@ -0,0 +1,7 @@
+import type { DiscoveredProject } from './interfaces';
+export interface ResolveProjectNamesResult {
+    targets: DiscoveredProject[];
+    notFound: string[];
+}
+export declare function resolveProjectNames(names: string[], units: DiscoveredProject[]): ResolveProjectNamesResult;
+export declare function listAvailableNames(units: DiscoveredProject[]): string[];