legal-markdown-js/dist/plugins/remark/imports.d.ts

Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version

/**
 * Remark Plugin for Import Processing
 *
 * This plugin processes import directives in legal documents using AST processing.
 * Imports allow including content from external files, with support for partial
 * content inclusion, metadata merging, and circular import detection.
 *
 * Features:
 * - File-based imports with @import directive
 * - Partial content imports from files
 * - YAML frontmatter merging from imported files
 * - Circular import detection and prevention
 * - Relative and absolute path resolution
 * - Import caching for performance
 *
 * @example
 * ```typescript
 * import { unified } from 'unified';
 * import remarkParse from 'remark-parse';
 * import remarkStringify from 'remark-stringify';
 * import { remarkImports } from './imports.js';
 *
 * const processor = unified()
 *   .use(remarkParse)
 *   .use(remarkImports, {
 *     basePath: './documents',
 *     mergeMetadata: true
 *   })
 *   .use(remarkStringify);
 * ```
 *
 * @module
 */
import { Plugin } from 'unified';
import { Root } from 'mdast';
import type { YamlValue } from '../../types/index.js';
/**
 * Options for the remark imports plugin
 * @interface RemarkImportsOptions
 */
export interface RemarkImportsOptions {
    /** Base path for resolving import files */
    basePath?: string;
    /** Whether to merge metadata from imported files */
    mergeMetadata?: boolean;
    /** Enable debug logging */
    debug?: boolean;
    /** Maximum import depth for circular import prevention */
    maxDepth?: number;
    /** Maximum execution time in milliseconds for import processing */
    timeoutMs?: number;
    /** Whether to filter reserved fields from imported metadata */
    filterReserved?: boolean;
    /** Whether to validate type compatibility before merging */
    validateTypes?: boolean;
    /** Whether to log import operations for debugging */
    logImportOperations?: boolean;
    /** Whether to add HTML comments showing import boundaries in output */
    importTracing?: boolean;
    /** Callback for handling imported metadata */
    onMetadataMerged?: (mergedMetadata: Record<string, YamlValue>, fromFile: string) => void;
    /** List of files currently being processed (for circular import detection) */
    importStack?: string[];
}
/**
 * Import directive information
 */
interface ImportDirective {
    /** Path to the file to import */
    filePath: string;
    /** Optional section to import from the file */
    section?: string;
    /** Start and end positions in the text */
    start: number;
    end: number;
    /** Full match text */
    fullMatch: string;
}
/**
 * Import processing context
 */
interface ImportContext {
    /** Current import depth */
    depth: number;
    /** Maximum allowed depth */
    maxDepth: number;
    /** Base path for file resolution */
    basePath: string;
    /** Whether to merge metadata */
    mergeMetadata: boolean;
    /** Debug mode flag */
    debug: boolean;
    /** Processing start time for timeout management */
    startTime: number;
    /** Maximum execution time in milliseconds */
    timeoutMs: number;
    /** Whether to filter reserved fields */
    filterReserved: boolean;
    /** Whether to validate type compatibility */
    validateTypes: boolean;
    /** Whether to log import operations */
    logImportOperations: boolean;
    /** Whether to add HTML comment boundaries around imported content */
    importTracing: boolean;
    /** Callback for metadata merging */
    onMetadataMerged?: (mergedMetadata: Record<string, YamlValue>, fromFile: string) => void;
    /** Stack of files being imported (for circular detection) */
    importStack: string[];
    /** Cache of imported file contents */
    contentCache: Map<string, string>;
    /** List of all imported metadata for sequential merging */
    importedMetadataList: Array<{
        metadata: Record<string, YamlValue>;
        source: string;
    }>;
    /** List of successfully imported files */
    importedFiles: string[];
    /** Accumulated metadata from all imports (for mixin expansion) */
    accumulatedMetadata: Record<string, YamlValue>;
}
/**
 * Result of import processing
 */
export interface ImportResult {
    /** The processed content */
    content: string;
    /** Merged metadata from all imports */
    mergedMetadata: Record<string, YamlValue>;
    /** List of successfully imported files */
    importedFiles: string[];
    /** Detailed merge statistics */
    mergeStats?: {
        totalImports: number;
        propertiesAdded: number;
        conflictsResolved: number;
        reservedFieldsFiltered: number;
        addedFields: string[];
        conflictedFields: string[];
        filteredFields: string[];
    };
}
/**
 * Remark plugin for processing imports
 *
 * This plugin identifies and processes import directives in markdown text,
 * loading content from external files and optionally merging their metadata.
 *
 * @param options - Configuration options for import processing
 * @returns Remark plugin transformer function
 */
export declare const remarkImports: Plugin<[RemarkImportsOptions], Root>;
/**
 * Extract import directives from text
 */
declare function extractImportDirectives(text: string): ImportDirective[];
/**
 * Load file content with caching
 */
declare function loadFileContent(filePath: string, context: ImportContext): string | null;
declare function getCanonicalImportPath(filePath: string): string;
/**
 * Extract a specific section from content
 */
declare function extractSection(content: string, sectionName: string, debug: boolean): string;
/**
 * Metadata for remarkImports plugin
 *
 * Dependencies:
 * - Must run BEFORE remarkTemplateFields (fields in imported content need processing)
 * - Must run BEFORE remarkLegalHeadersParser (legal headers in imported content need parsing)
 * - Must run BEFORE remarkFieldTracking (imported fields need tracking)
 */
export { extractImportDirectives as _extractImportDirectives, loadFileContent as _loadFileContent, getCanonicalImportPath as _getCanonicalImportPath, extractSection as _extractSection, };
//# sourceMappingURL=imports.d.ts.map