import { PackageAPI, ExportedFunction, ExportedType, ReadmeContent, PackageInfo, ReadmeSection, SyncError, MDXFrontmatter, MDXDocument } from '../types.js';
import { Result } from '@bfra.me/es/result';
import 'zod';

/**
 * @bfra.me/doc-sync/generators/api-reference-generator - API documentation table generation
 */

declare function generateAPIReference(api: PackageAPI): string;
declare function generateAPICompact(api: PackageAPI): string;
declare function generateCategoryReference(functions: readonly ExportedFunction[], types: readonly ExportedType[], categoryName: string): string;

/**
 * @bfra.me/doc-sync/generators/code-example-formatter - Syntax-highlighted code blocks from JSDoc examples
 */

/**
 * Options for code example formatting
 */
interface CodeExampleOptions {
    /** Default language for code blocks */
    readonly defaultLanguage?: string;
    /** Whether to add function name as title */
    readonly includeTitle?: boolean;
    /** Maximum number of examples per function */
    readonly maxExamplesPerFunction?: number;
    /** Whether to wrap examples in collapsible sections */
    readonly collapsible?: boolean;
}
declare function formatCodeExamples(api: PackageAPI, options?: CodeExampleOptions): string;
declare function formatFunctionExamples(fn: ExportedFunction, options?: CodeExampleOptions): string;
declare function formatTypeExamples(type: ExportedType, options?: CodeExampleOptions): string;
declare function formatCodeBlock(code: string, language?: string): string;
declare function cleanCodeExample(code: string): string;
declare function detectLanguage(code: string): string | undefined;
declare function formatUsageExample(fn: ExportedFunction): string;
declare function groupExamplesByCategory(api: PackageAPI): Map<string, {
    functions: ExportedFunction[];
    types: ExportedType[];
}>;
declare function formatGroupedExamples(api: PackageAPI, options?: CodeExampleOptions): string;

/**
 * @bfra.me/doc-sync/generators/component-mapper - Map content sections to Starlight components
 */

/**
 * Configuration for Starlight component mapping
 */
interface ComponentMapperConfig {
    /** Section titles that should use CardGrid for features */
    readonly featureSections?: readonly string[];
    /** Section titles that should use Tabs for installation */
    readonly tabSections?: readonly string[];
    /** Section titles to exclude from output */
    readonly excludeSections?: readonly string[];
    /** Custom component mappings by section title */
    readonly customMappings?: Record<string, SectionMapper>;
}
/**
 * A function that maps section content to MDX output
 */
type SectionMapper = (section: ReadmeSection, info: PackageInfo) => string;
declare function mapToStarlightComponents(readme: ReadmeContent, packageInfo: PackageInfo, config?: ComponentMapperConfig): string;
declare function generateInstallTabs(packageName: string): string;
declare function createBadge(text: string, variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default'): string;
declare function createCard(title: string, content: string, icon?: string): string;
declare function createCardGrid(cards: {
    title: string;
    content: string;
    icon?: string;
}[]): string;
declare function createTabs(items: {
    label: string;
    content: string;
}[]): string;

/**
 * @bfra.me/doc-sync/generators/content-merger - Preserve manual sections using sentinel markers
 */

/**
 * A section of content extracted from MDX
 */
interface ContentSection {
    /** Section type */
    readonly type: 'auto' | 'manual' | 'unchanged';
    /** Section content */
    readonly content: string;
    /** Start position in source */
    readonly startIndex: number;
    /** End position in source */
    readonly endIndex: number;
}
/**
 * Merge options
 */
interface MergeOptions {
    /** Strategy for handling conflicts */
    readonly conflictStrategy?: 'keep-manual' | 'keep-auto' | 'merge';
    /** Preserve empty manual sections */
    readonly preserveEmptyManual?: boolean;
}
/**
 * Result of a merge operation
 */
interface MergeResult {
    /** Merged content */
    readonly content: string;
    /** Number of manual sections preserved */
    readonly preservedCount: number;
    /** Number of auto-generated sections updated */
    readonly updatedCount: number;
    /** Whether content changed */
    readonly hasChanges: boolean;
}
declare function mergeContent(existingContent: string, newContent: string, options?: MergeOptions): Result<MergeResult, SyncError>;
declare function extractManualSections(content: string): ContentSection[];
declare function extractAutoSections(content: string): ContentSection[];
declare function hasManualContent(content: string): boolean;
declare function hasAutoContent(content: string): boolean;
declare function wrapManualSection(content: string): string;
declare function wrapAutoSection(content: string): string;
declare function stripSentinelMarkers(content: string): string;
declare function validateMarkerPairing(content: string): Result<true, SyncError>;
declare function createDiffSummary(oldContent: string, newContent: string): string;

/**
 * @bfra.me/doc-sync/generators/frontmatter-generator - Starlight-compatible frontmatter generation
 */

declare function generateFrontmatter(packageInfo: PackageInfo, readme: ReadmeContent | undefined, overrides?: Partial<MDXFrontmatter>): MDXFrontmatter;
declare function stringifyFrontmatter(frontmatter: MDXFrontmatter): string;
declare function parseFrontmatter(yaml: string): Partial<MDXFrontmatter>;

/**
 * @bfra.me/doc-sync/generators/mdx-generator - MDX document structure generation for Starlight
 */

/**
 * Options for MDX generation
 */
interface MDXGeneratorOptions {
    /** Include API reference section */
    readonly includeAPI?: boolean;
    /** Include examples from JSDoc */
    readonly includeExamples?: boolean;
    /** Custom frontmatter overrides */
    readonly frontmatterOverrides?: Partial<MDXFrontmatter>;
    /** Preserve manual content sections */
    readonly preserveManualContent?: boolean;
    /** Existing MDX content for merging */
    readonly existingContent?: string;
}
declare function generateMDXDocument(packageInfo: PackageInfo, readme: ReadmeContent | undefined, api: PackageAPI | undefined, options?: MDXGeneratorOptions): Result<MDXDocument, SyncError>;
/**
 * Sanitizes content for safe MDX rendering
 * Prevents XSS by escaping potentially dangerous content
 */
declare function sanitizeContent(content: string): string;
/**
 * Sanitizes content within MDX while preserving JSX components
 * Sanitizes JSX component attributes to prevent XSS while leaving closing tags unchanged
 */
declare function sanitizeTextContent(content: string): string;
declare function validateMDXSyntax(mdx: string): Result<true, SyncError>;

export { type CodeExampleOptions, type ComponentMapperConfig, type ContentSection, type MDXGeneratorOptions, type MergeOptions, type MergeResult, type SectionMapper, cleanCodeExample, createBadge, createCard, createCardGrid, createDiffSummary, createTabs, detectLanguage, extractAutoSections, extractManualSections, formatCodeBlock, formatCodeExamples, formatFunctionExamples, formatGroupedExamples, formatTypeExamples, formatUsageExample, generateAPICompact, generateAPIReference, generateCategoryReference, generateFrontmatter, generateInstallTabs, generateMDXDocument, groupExamplesByCategory, hasAutoContent, hasManualContent, mapToStarlightComponents, mergeContent, parseFrontmatter, sanitizeContent, sanitizeTextContent, stringifyFrontmatter, stripSentinelMarkers, validateMDXSyntax, validateMarkerPairing, wrapAutoSection, wrapManualSection };