/**
 * 0.12.0+ — symbol-aware retrieval tools backed by ts-morph.
 *
 * These tools answer "what's already here?" — the question the
 * mandatory pre-write discovery requirement (Phase 1) makes the agent
 * ask before it adds new exported symbols. The bounded-attention
 * north star of the brownfield-retrieval plan: agent attention should
 * be bounded to the AREA the feature touches, never the project, and
 * within the area, look at existing entities BEFORE creating new ones.
 *
 * We deliberately don't use TypeScript's language service (no
 * type-checking) — that's an order of magnitude slower and we don't
 * need correctness here, we need speed. Syntax tree walks find ~95%
 * of what the agent needs and false positives (an identifier in a
 * comment, say) are recoverable: the agent reads the matched file
 * and decides.
 *
 * Each call loads a fresh ts-morph Project. That's ~200-500ms for a
 * mid-size codebase — the LLM round-trip dominates wall-clock so
 * caching across calls is a future optimization (and tricky because
 * brew's writes invalidate the project).
 */
export interface Reference {
    file: string;
    line: number;
    column: number;
    /** The line of code containing the reference, for context in the agent's prompt. */
    context: string;
    /** What kind of usage — "definition", "reference", "implements", "extends", "import". */
    kind: ReferenceKind;
}
export type ReferenceKind = "definition" | "reference" | "implements" | "extends" | "import";
/**
 * Find every place a symbol name is referenced in the source tree.
 *
 * Matches: identifier nodes with text === symbol. Includes the
 * symbol's own definition unless `excludeDefinitions` is set.
 *
 * Excludes:
 *   - Comments (text-search would catch them; AST walk doesn't)
 *   - String literals (same)
 *   - JSX text content
 *
 * Hits the import-statement specifier separately (kind: "import")
 * so the agent can distinguish "imported here" from "called here".
 */
export declare function findReferences(repoRoot: string, symbol: string, options?: {
    excludeDefinitions?: boolean;
    maxResults?: number;
}): Reference[];
/**
 * Find every class that implements an interface (or every interface that
 * extends another interface) by name. Returns the implementor's location.
 *
 * Catches:
 *   - `class Foo implements IBar { ... }` → implementations of `IBar`
 *   - `interface Foo extends IBar { ... }` → extensions of `IBar`
 *   - `class Foo extends Bar` → kind: "extends" (kept distinct from
 *     "implements" so the agent can tell hierarchy from interface
 *     conformance)
 */
export declare function findImplementations(repoRoot: string, interfaceName: string, options?: {
    maxResults?: number;
}): Reference[];
/**
 * Find the declaration site of a named symbol. Returns the FIRST match —
 * a symbol can be re-declared in multiple files (TS allows this for
 * augmenters / module declarations) but the common case is one
 * canonical home.
 *
 * Scans:
 *   - function declarations
 *   - class declarations
 *   - interface declarations
 *   - type alias declarations
 *   - enum declarations
 *   - exported variable declarations
 */
export declare function findDefinition(repoRoot: string, symbol: string): Reference | null;
/**
 * 0.12.0+ — render retrieval results as a compact markdown block for
 * the agent's tool output. Each result becomes a single line:
 * `kind | file:line:col | context`.
 *
 * Truncates at `max` to keep tool output under the agent's response
 * cap. Caller passes a sensible max; default 30 is enough for the
 * common case (most symbols have < 30 references in a focused codebase).
 */
export declare function renderReferences(refs: Reference[], max?: number): string;
//# sourceMappingURL=retrieval.d.ts.map