/**
 * Sources.ts
 *
 * Loads and validates documentation source configurations from config/sources.
 * Each source defines where to find documentation for evaluation — a Sanity
 * dataset, a branch deploy URL, a local dev server, etc.
 *
 * Every source carries all fields needed by both evaluation modes:
 *   - Baseline/Observed: uses projectId + dataset (GROQ queries to Sanity CMS)
 *   - Agentic: uses baseUrl (agent browses the live site, llms.txt derived automatically)
 *
 * Environment variables in config/sources are resolved via ${{ VAR | default }}
 * interpolation at load time.
 */
import type { Logger } from "./_vendor/ailf-core/index.d.ts";
/**
 * @deprecated Use {@link ResolvedSourceConfig} instead.
 * Kept as a type alias for backward compatibility during the transition.
 */
export type DocSource = ResolvedSourceConfig;
/**
 * Fully resolved documentation source configuration.
 *
 * After all CLI flags, environment variables, URL classifications, and
 * config/sources defaults are merged, the system produces a single
 * ResolvedSourceConfig that drives the entire pipeline.
 *
 * All ${{ }} expressions have been expanded by the time this is constructed.
 */
export interface ResolvedSourceConfig {
    /** Optional origin allowlist for agentic sandboxing */
    allowedOrigins?: string[];
    /** Base URL for documentation site (agentic mode + URL prefixes in context) */
    baseUrl: string;
    /** Sanity dataset name */
    dataset: string;
    /** Optional list of specific Sanity document IDs to fetch */
    documentIds?: string[];
    /** Custom HTTP headers to send with documentation requests (e.g., auth tokens) */
    headers?: Record<string, string>;
    /** URL to the llms.txt file — always derived as baseUrl + "/llms.txt" */
    llmsTxt: string;
    /** Source name (the key from config/sources, or "env-override") */
    name: string;
    /** Sanity release perspective ID (optional — for evaluating content releases) */
    perspective?: string;
    /** Hostname extracted from baseUrl — used for search result prioritization */
    priorityDomain: string;
    /** Sanity project ID */
    projectId: string;
    /** Sanity Studio base URL (for URL classification and Studio link generation) */
    studioOrigin: string;
    /** Direct documentation URLs (non-Sanity, from --url/--urls classification) */
    urls: string[];
}
/**
 * Check whether a URL is allowed by the given origin patterns.
 *
 * Returns `true` if:
 * - `origins` is empty (no sandboxing configured), or
 * - the URL's hostname matches at least one origin pattern.
 *
 * Returns `false` if the URL is invalid or doesn't match any pattern.
 */
export declare function isAllowedOrigin(url: string, origins: string[]): boolean;
/**
 * Overrides for source resolution. When provided, these values take
 * precedence over environment variables. This allows callers with
 * typed config (e.g., orchestration steps) to bypass the env var bridge.
 */
export interface SourceOverrides {
    allowedOrigins?: string[];
    baseUrl?: string;
    dataset?: string;
    directUrls?: string[];
    documentIds?: string[];
    headers?: Record<string, string>;
    perspective?: string;
    projectId?: string;
    studioOrigin?: string;
}
/**
 * Load a documentation source by name.
 *
 * Resolution order:
 *   1. If DOC_BASE_URL env var is set, build an ad-hoc source from env vars.
 *      When the resolved tuple (baseUrl, projectId, dataset) is value-equal
 *      to a registered named source and no override-only knob is set, the
 *      source resolves under its registered name instead of "env-override".
 *   2. If config/sources exists, load and interpolate the named source
 *   3. Otherwise the built-in default (sanity.io production). A requested name
 *      that can't be resolved throws — it does not fall back.
 *
 * @param name - Source name from config/sources. If omitted, uses DOC_SOURCE
 *               env var or the first source defined in config/sources.
 * @throws if an explicitly requested source (name / DOC_SOURCE) can't be
 *         resolved — a missing registry or unknown name fails loudly rather
 *         than silently defaulting to the wrong docs.
 */
export declare function loadSource(name?: string, overrides?: SourceOverrides, logger?: Logger): ResolvedSourceConfig;
/**
 * Match a hostname against an origin pattern that may contain `*` wildcards.
 *
 * The `*` wildcard matches any substring within a single hostname segment
 * (i.e., it does not cross dots). A bare `*` matches everything.
 *
 * @example
 * matchesOrigin("branch.sanity.build", "*.sanity.build")   // true
 * matchesOrigin("sanity.io", "*.sanity.build")              // false
 * matchesOrigin("anything.example.com", "*")                // true
 */
export declare function matchesOrigin(hostname: string, pattern: string): boolean;
