/**
 * Public graph/read views for declaration facts and cross-file references
 * (P2 MCP audit Phase 3 Task 3.6).
 *
 * Callable-only {@link searchSymbolOccurrences} is unchanged. These views
 * project the optional semantic plane with independent coverage facets and
 * explicit present-empty vs absent (unsupported) semantics.
 */
import { type Result } from '@opensip-cli/core';
import { type ReadGroupSummary } from './bounded-view.js';
import { type EffectiveGraphSourceFilter, type GraphReadFacetCoverage, type GraphSourceFilter } from './query-contracts.js';
import { type SourceRoleMatcher } from './source-filter.js';
import type { GraphReadError } from './types.js';
import type { Catalog, CrossFileReferenceFact, DeclarationFact, DeclarationKind, ReferenceKind } from '../types.js';
/** Match semantics for declaration search (mirrors symbol search). */
export type DeclarationSearchMatch = 'substring' | 'exact' | 'qualified';
export interface DeclarationSearchQuery {
    readonly query: string;
    readonly match: DeclarationSearchMatch;
    readonly filter: GraphSourceFilter;
    readonly kinds?: readonly DeclarationKind[];
    readonly limit: number;
    readonly afterKey?: string;
    readonly groupBy?: 'none' | 'package' | 'file';
}
export interface DeclarationRef {
    readonly declarationId: string;
    readonly name: string;
    readonly qualifiedName: string;
    readonly kind: DeclarationKind;
    readonly package: string;
    readonly filePath: string;
    readonly line: number;
    readonly column: number;
    readonly endLine: number;
    readonly endColumn: number;
    readonly visibility: DeclarationFact['visibility'];
    readonly exportRole: DeclarationFact['exportRole'];
    readonly inTestFile: boolean;
    readonly definedInGenerated: boolean;
}
export interface DeclarationSearchView {
    readonly referenceScope: 'cross-file';
    readonly declarations: readonly DeclarationRef[];
    readonly hasMore: boolean;
    readonly totalMatches: number;
    readonly effectiveFilter: EffectiveGraphSourceFilter;
    readonly coverage: GraphReadFacetCoverage;
    readonly groups?: readonly ReadGroupSummary[];
    /** True when the catalog plane is absent (unsupported). */
    readonly unsupported: boolean;
}
export interface ReferencesToQuery {
    readonly declarationId: string;
    readonly filter: GraphSourceFilter;
    readonly kinds?: readonly ReferenceKind[];
    readonly limit: number;
    readonly afterKey?: string;
    readonly groupBy?: 'none' | 'package' | 'file';
}
export interface ReferenceSiteRef {
    readonly referenceId: string;
    readonly kind: ReferenceKind;
    readonly filePath: string;
    readonly line: number;
    readonly column: number;
    readonly endLine: number;
    readonly endColumn: number;
    readonly package: string;
    readonly targetDeclarationId?: string;
    readonly targetPackage?: string;
    readonly targetName?: string;
    readonly targetKind?: DeclarationKind;
    readonly basis: CrossFileReferenceFact['basis'];
    readonly confidence: CrossFileReferenceFact['confidence'];
    readonly importSpecifier?: string;
    readonly reason?: string;
    readonly inTestFile: boolean;
    readonly definedInGenerated: boolean;
}
export interface ReferencesToView {
    readonly referenceScope: 'cross-file';
    readonly declarationId: string;
    readonly references: readonly ReferenceSiteRef[];
    readonly hasMore: boolean;
    readonly totalMatches: number;
    readonly effectiveFilter: EffectiveGraphSourceFilter;
    readonly coverage: GraphReadFacetCoverage;
    readonly groups?: readonly ReadGroupSummary[];
    readonly unsupported: boolean;
    /** True when the declaration id is not present in the retained inventory. */
    readonly declarationMissing: boolean;
}
export declare function declarationStableKey(ref: DeclarationRef): string;
export declare function referenceStableKey(ref: ReferenceSiteRef): string;
export declare function compareDeclarationRefs(a: DeclarationRef, b: DeclarationRef): number;
export declare function compareReferenceSites(a: ReferenceSiteRef, b: ReferenceSiteRef): number;
/**
 * Search declaration facts with filter-first semantics and a bounded top-K
 * window. Absent plane → empty declarations + incomplete inventory facet.
 */
export declare function searchDeclarationFacts(catalog: Catalog, query: DeclarationSearchQuery, matcher: SourceRoleMatcher): Result<DeclarationSearchView, GraphReadError>;
/**
 * Cross-file references to a declaration id. Missing id is reported via
 * `declarationMissing` (caller maps to a typed MCP read error).
 */
export declare function referencesToDeclaration(catalog: Catalog, query: ReferencesToQuery, matcher: SourceRoleMatcher): Result<ReferencesToView, GraphReadError>;
//# sourceMappingURL=declaration-reference-view.d.ts.map