/**
 * Plan 3b — Phase 1: Tree-sitter query wrapper.
 *
 * Adapters consume the helpers in this file — never the raw `web-tree-sitter`
 * API. This keeps the surface area minimal and testable.
 *
 * Design:
 *   - `compileQuery` caches compiled `Query` instances per (language, source)
 *     tuple. Compiling an S-expression is non-trivial; cache hit-rate is
 *     critical when the same query runs across N sampled files.
 *   - `runQuery` returns the captures as `{captures, file, line}` records so
 *     adapters never need to touch raw `Node` objects.
 *   - `InvalidQueryError` is the typed error thrown when an S-expression is
 *     malformed; never let a raw `Error` reach the adapter (per audit-iter-5
 *     fix HH test (b)).
 */
import { Query, type Language, type Parser } from 'web-tree-sitter';
/**
 * Thrown when an S-expression query string fails to compile against the
 * supplied grammar. Carries the original message and the offending source
 * so adapter authors can debug.
 */
export declare class InvalidQueryError extends Error {
    readonly queryName: string;
    readonly querySource: string;
    readonly cause?: unknown;
    constructor(queryName: string, querySource: string, cause: unknown);
}
/**
 * Compile (and cache) an S-expression query against `language`.
 *
 * Throws `InvalidQueryError` (NOT raw Error) on malformed S-expressions —
 * adapters can catch this without losing the typed boundary.
 *
 * Cache lookup is O(1) on the (Language, source) tuple via WeakMap+Map.
 */
export declare function compileQuery(language: Language, source: string, queryName: string): Query;
export interface RunQueryHit {
    /**
     * Capture name → captured text. If the same capture name appears multiple
     * times in a single match, the LAST occurrence wins (callers usually want
     * the most-specific one).
     */
    captures: Record<string, string>;
    /** Absolute path to the file being parsed. */
    file: string;
    /** 1-based line number of the FIRST capture in the match. */
    line: number;
    /** Name of the query (used for provenance). */
    queryName: string;
}
/**
 * Run a compiled query against a parsed tree. Returns a flat list of hits.
 *
 * Each match becomes one `RunQueryHit`. The `line` is computed from the
 * earliest-starting capture in the match (1-based). Note that this helper is
 * intentionally narrow — it is NOT a general node-walker. Adapters that need
 * tree traversal should compose multiple queries instead.
 */
export declare function runQuery(parser: Parser, source: string, queryText: string, queryName: string, filePath: string): RunQueryHit[];
