/**
 *
 * Resolves a doc-fragment set for a (intent, language) query via the
 * following priority chain:
 *   1. Context7 MCP  (priority 1; 30 s timeout)
 *   2. WebSearch    (priority 2 fallback; 200 ms simulated delay)
 *   3. Empty        (both sources exhausted)
 *
 * The Context7 + WebSearch calls are STUB implementations for v1:
 * they sleep for a fixed delay and return synthetic doc fragments so
 * the orchestrator's source-priority logic is testable end-to-end.
 * Real MCP wiring is a future slice — the stubs are clearly marked.
 *
 * Because a stub result is indistinguishable from a real one by shape,
 * every result carries `synthetic`: true when the fragments came from a
 * built-in stub rather than a caller-injected lookup (`context7Lookup` /
 * `webSearchLookup`). Callers MUST NOT present a synthetic result as a
 * scan result — `source` alone says which transport answered, not whether
 * anything real was consulted. The stub seam stays injectable so the real
 * wiring (and its tests) can replace it without touching this contract.
 *
 * The orchestrator emits structured log lines via the injected `io`
 * (stdout for progress, stderr for warnings) so a CLI caller can see
 * which fallback path was taken.
 */
import type { ProgramIO } from '../../cli/cli-helpers.js';
export type DocFragment = {
    readonly title: string;
    readonly url: string;
    readonly snippet: string;
};
export type ScanSource = 'context7' | 'websearch' | 'fallback';
export type ScanResult = {
    readonly results: readonly DocFragment[];
    readonly fragments: readonly DocFragment[];
    readonly source: ScanSource;
    readonly elapsedMs: number;
    /**
     * `true` when the fragments came from the built-in stub lookups instead
     * of a real documentation lookup. A synthetic result is not a scan
     * result: it must never be rendered as one or gated on.
     */
    readonly synthetic: boolean;
};
export type ScanOptions = {
    readonly intent: string;
    readonly language: string;
    readonly projectRoot: string;
    readonly io: ProgramIO;
    readonly context7TimeoutMs?: number;
    /** Test / real-wiring seam: replaces the priority-1 Context7 stub. */
    readonly context7Lookup?: LookupFn;
    /** Test / real-wiring seam: replaces the priority-2 WebSearch stub. */
    readonly webSearchLookup?: LookupFn;
};
export type LookupFn = (intent: string, language: string) => Promise<{
    readonly ok: boolean;
    readonly results: readonly DocFragment[];
}>;
export declare function scanBestPractice(opts: ScanOptions): Promise<ScanResult>;