/**
 * parser.ts — Markdown link discovery, validation orchestration, and
 * condensing replacement.
 *
 * Workflow:
 *  1. Read the Markdown file.
 *  2. Regex-scan for `[text](url)` inline links and `[ref]: url` definitions
 *     (http/https only).
 *  3. For each unique URL, validate via `network.ts`.
 *  4. Update the lockfile with SHA-256 / ETag / token-savings metadata.
 *  5. Replace up-to-date inline link blocks with an HTML comment marker.
 *  6. Reference-style definitions are validated but never replaced (they are
 *     already token-cheap; removing them breaks Markdown rendering).
 *  7. Restore mode replaces `<!-- doc-lok:cached#hash -->` markers back with
 *     the original `[text](url)` links using the lockfile as the source of
 *     truth.
 */
import { COMPRESSED_MARKER_TOKENS, type Lockfile } from "./state.js";
import type { SsrfOptions } from "./ssrf.js";
import { type ConverterMode } from "./convert.js";
/** Options shared across the high-level markdown functions. */
export interface MarkdownOptions extends SsrfOptions {
    /**
     * Override the per-request timeout (ms). Default 15 000.
     * Currently informational — threaded through to `validateUrl`.
     */
    timeoutMs?: number;
}
/** Additional options for `inlineMarkdown`. */
export interface InlineOptions extends MarkdownOptions {
    /**
     * Override the default cache directory (`.doc-lok/cache` next to the
     * lockfile). Path is resolved relative to `process.cwd()`.
     */
    cacheDir?: string;
    /**
     * Refuse bodies larger than this. Default 1 MB.
     */
    maxBytes?: number;
    /**
     * Allowlist of Content-Type prefixes. Default: `text/html`, `text/plain`.
     * Pass an empty array to allow any content type.
     */
    allowedContentTypes?: readonly string[];
    /**
     * Section names to inline. Default `[]` — inline the table-of-contents
     * only. Special values: `"all"` / `"*"` for the full body, `"toc"` /
     * `"index"` for the TOC-only default. Otherwise, name(s) are matched
     * against detected headings via `matchSections`.
     */
    sections?: string[];
    /**
     * HTML→Markdown converter mode. Default `"minimal"` (built-in, zero deps).
     * Pass `"turndown"` to use the `turndown` peer dependency.
     */
    converter?: ConverterMode;
}
/** Per-link diagnostic emitted by `inlineMarkdown` (extends the base). */
export interface InlineDiagnostic extends LinkDiagnostic {
    /** Slugs of sections that were actually inlined (empty for TOC-only or error). */
    matchedSections?: string[];
    /** All section slugs available on the page (for agent discovery). */
    availableSections?: string[];
}
/** Result returned by `inlineMarkdown`. */
export interface InlineResult {
    /** Markdown with inline content blocks injected under unchanged links. */
    output: string;
    /** Per-link diagnostics. */
    diagnostics: InlineDiagnostic[];
    /** Total tokens saved this run (network + latency, not LLM tokens — see README). */
    tokensSaved: number;
    /** Path to the lockfile that was read/written. */
    lockfilePath: string;
    /** Full lockfile state after this run. */
    lockfile: Lockfile;
    /** Cache directory used for body storage. */
    cacheDir: string;
    /** Number of inline blocks written (vs. skipped due to error / oversized). */
    inlinedCount: number;
}
/**
 * Regex capturing reference-style link definitions:
 *   [ref]:  https://example.com  "optional title"
 *   [ref]: <https://example.com> "optional title"
 * Groups: 1=label, 2=url (may include angle brackets)
 */
/** HTML comment marker injected in place of unchanged inline links. */
declare const MARKER = "<!-- doc-lok:cached";
/** HTML comment marker prefix used by `inlineMarkdown` to wrap fetched bodies. */
declare const INLINE_MARKER = "<!-- doc-lok:inline";
/** Per-link diagnostic emitted to the CLI. */
export interface LinkDiagnostic {
    url: string;
    status: "cached" | "updated" | "error";
    tokensSaved: number;
    message?: string;
}
/** Aggregate result returned by `condenseMarkdown`. */
export interface CondenseResult {
    /** The condensed Markdown text. */
    output: string;
    /** Per-link diagnostics. */
    diagnostics: LinkDiagnostic[];
    /** Total tokens saved in this run. */
    tokensSaved: number;
    /** Path to the lockfile that was read/written. */
    lockfilePath: string;
    /** Full lockfile state after this run (for agent / --json consumption). */
    lockfile: Lockfile;
}
/**
 * Condense a Markdown file by replacing unchanged remote inline links with a
 * tiny HTML comment marker.  Reference-style definitions are validated (so
 * the lockfile stays current) but are left in place.
 *
 * @param mdFilePath  Absolute or relative path to the `.md` file.
 * @param lockfilePath  Optional explicit lockfile path.
 */
export declare function condenseMarkdown(mdFilePath: string, lockfilePath?: string, opts?: MarkdownOptions): Promise<CondenseResult>;
/**
 * Inline mode (`--inline`): fetch the body of each linked URL, cache it,
 * and inject a fenced HTML-comment block into the Markdown so the LLM
 * sees the linked content directly. Unchanged URLs on re-runs skip the
 * body re-fetch entirely (HEAD only) — saves network + latency, and
 * makes the prompt byte-identical across runs (which unlocks provider-
 * side prompt caching on Anthropic / OpenAI).
 *
 * **Does not save LLM tokens on its own** — the inlined body is still
 * sent and tokenized every run. See ROADMAP P2 (`--summary`) for the
 * feature that actually shrinks LLM token cost.
 *
 * @param mdFilePath  Absolute or relative path to the `.md` file.
 * @param lockfilePath  Optional explicit lockfile path.
 * @param opts  Optional: `cacheDir`, `maxBytes`, `allowedContentTypes`,
 *              `allowPrivate`, `timeoutMs`.
 */
export declare function inlineMarkdown(mdFilePath: string, lockfilePath?: string, opts?: InlineOptions): Promise<InlineResult>;
/**
 * Restore a condensed Markdown file by replacing `<!-- doc-lok:cached#hash -->`
 * markers back with the original `[text](url)` links.
 *
 * Uses the lockfile as the source of truth — every URL whose hash appears in
 * a marker must have a corresponding entry in the lockfile.
 *
 * @param mdFilePath  Absolute or relative path to the condensed `.md` file.
 * @param lockfilePath  Optional explicit lockfile path.
 */
export declare function restoreMarkdown(mdFilePath: string, lockfilePath?: string): Promise<{
    output: string;
    restoredCount: number;
    lockfilePath: string;
}>;
/** Result returned by `checkMarkdown` — validation only, no file modification. */
export interface CheckResult {
    /** Per-link diagnostics with freshness status. */
    diagnostics: LinkDiagnostic[];
    /** Total tokens that *would* be saved if condensed. */
    tokensSaved: number;
    /** Path to the lockfile that was read/written. */
    lockfilePath: string;
    /** Full lockfile state (so agents can inspect SHAs without a separate read). */
    lockfile: Lockfile;
}
/**
 * Check URL freshness in a Markdown file without modifying it.
 *
 * Validates every http(s) URL (inline + reference), updates the lockfile with
 * current SHA-256 / ETag metadata, and returns diagnostics.  The Markdown file
 * itself is never rewritten — this is a read-only probe designed for agents
 * that need to know whether links are stale before deciding to condense.
 *
 * @param mdFilePath  Absolute or relative path to the `.md` file.
 * @param lockfilePath  Optional explicit lockfile path.
 */
export declare function checkMarkdown(mdFilePath: string, lockfilePath?: string, opts?: MarkdownOptions): Promise<CheckResult>;
/** Re-export the marker prefix for consumers that want to detect it. */
export { MARKER, INLINE_MARKER, COMPRESSED_MARKER_TOKENS };
export type { Lockfile };
//# sourceMappingURL=parser.d.ts.map