import type { Code, Definition as MdastDefinition, Heading as MdastHeading, Image as MdastImage, ImageReference as MdastImageReference, Link as MdastLink, LinkReference as MdastLinkReference, Nodes, Parents, Root } from "mdast";
import type { Position } from "unist";
import type { ParsedDocument } from "./types/metadata.js";
/** One-based, inclusive range in the original Markdown file. */
export interface MarkdownSourceRange {
    startLine: number;
    endLine: number;
}
/** One-based, inclusive line range with one-based mdast columns. */
export interface MarkdownSourceColumnRange extends MarkdownSourceRange {
    startColumn: number;
    endColumn: number;
}
/** One node plus its structural context, retained in source traversal order. */
export interface MarkdownNodeRecord {
    node: Nodes;
    parent: Parents;
    index: number;
    ancestors: Parents[];
}
export interface MarkdownHeadingRecord extends MarkdownSourceRange {
    node: MdastHeading;
    depth: number;
    text: string;
}
interface MarkdownResolvedDestinationBase extends MarkdownSourceColumnRange {
    text: string;
    target: string;
    source: string;
    definitionStartLine?: number;
    definitionEndLine?: number;
}
export interface MarkdownLinkRecord extends MarkdownResolvedDestinationBase {
    kind: "link";
    node: MdastLink | MdastLinkReference;
}
export interface MarkdownImageRecord extends MarkdownResolvedDestinationBase {
    kind: "image";
    node: MdastImage | MdastImageReference;
}
export type MarkdownLinkTargetRecord = MarkdownLinkRecord | MarkdownImageRecord;
/** One parser-recognized link/image use, including unresolved references. */
export interface MarkdownLinkSyntaxRecord extends MarkdownSourceColumnRange {
    node: MdastLink | MdastLinkReference | MdastImage | MdastImageReference;
    source: string;
}
/** One parser-recognized definition. Definitions identify targets but are not uses. */
export interface MarkdownDefinitionRecord extends MarkdownSourceColumnRange {
    node: MdastDefinition;
    identifier: string;
    target: string;
    source: string;
}
export interface MarkdownCodeBlockRecord extends MarkdownSourceRange {
    node: Code;
    kind: "fenced" | "indented";
    language: string;
    content: string;
    contentStartLine: number;
    contentEndLine: number;
    closed: boolean;
}
/**
 * Shared syntax representation for one eligible Markdown artifact.
 *
 * `bodyStartLine` is the one-based original-file line parsed as Markdown.
 * mdast positions are converted back to original-file lines by this module.
 */
export interface MarkdownSyntax {
    sourceLines: string[];
    bodyStartLine: number;
    root: Root;
    records: MarkdownNodeRecord[];
    headings: MarkdownHeadingRecord[];
    links: MarkdownLinkRecord[];
    images: MarkdownImageRecord[];
    linkTargets: MarkdownLinkTargetRecord[];
    linkSyntax: MarkdownLinkSyntaxRecord[];
    definitions: MarkdownDefinitionRecord[];
    codeBlocks: MarkdownCodeBlockRecord[];
}
/** Find the body line under the exact general Renma frontmatter contract. */
export declare function markdownBodyStartLine(sourceLines: string[]): number;
/**
 * Parse one Markdown body while retaining original-file source provenance.
 * Artifact-aware callers pass their selected body start explicitly; the
 * default is the exact general Renma contract.
 */
export declare function parseMarkdownSyntax(content: string, bodyStartLine?: number): MarkdownSyntax;
/** Retain syntax as non-public working state associated with a parsed document. */
export declare function attachMarkdownSyntax(document: ParsedDocument, syntax: MarkdownSyntax): void;
/** Return the primary syntax parse retained for an eligible parsed document. */
export declare function markdownSyntaxForDocument(document: ParsedDocument): MarkdownSyntax | undefined;
/**
 * Return cached syntax or recover it for an independently constructed copy.
 * Normal repository snapshots take the cached branch because `parseDocument`
 * attaches their primary parse before any syntax consumer runs.
 */
export declare function ensureMarkdownSyntaxForDocument(document: ParsedDocument): MarkdownSyntax | undefined;
/** Require an mdast source position so parser failures remain fail-closed. */
export declare function requiredMarkdownPosition(node: {
    position?: Position | undefined;
}): Position;
/** Convert an mdast position to a one-based original-file line range. */
export declare function markdownSourceRange(node: {
    position?: Position | undefined;
}, bodyStartLine: number): MarkdownSourceRange;
/** Convert an mdast position while retaining its one-based source columns. */
export declare function markdownSourceColumnRange(node: {
    position?: Position | undefined;
}, bodyStartLine: number): MarkdownSourceColumnRange;
/** Collect descendant text without exposing mdast details to ordinary callers. */
export declare function markdownNodeText(node: Nodes | Parents): string;
/** Return every original-file line occupied by matching structural code nodes. */
export declare function markdownCodeLineNumbers(syntax: MarkdownSyntax, kind?: MarkdownCodeBlockRecord["kind"]): Set<number>;
export {};