legal-markdown-js
Version:
Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version
111 lines • 4.04 kB
TypeScript
/**
* Pipeline Builder
*
* Single source of truth for remark plugin ordering. Uses phase-based
* architecture to ensure deterministic execution order and prevent
* subtle bugs like variables evaluating after conditionals (Issue #120).
*
* @module pipeline-builder
*/
import type { ProcessingPhase, PluginMetadata, PluginOrderValidationResult } from '../../plugins/remark/types.js';
/**
* Ordered pipeline result from builder
*
* Contains the final plugin execution order, grouped by phase,
* with validation results and capabilities tracking.
*/
interface OrderedPipeline {
/** Plugin names in execution order */
names: string[];
/** Plugins grouped by phase for visualization and debugging */
byPhase: Map<ProcessingPhase, string[]>;
/** Validation result (errors, warnings) */
validation: PluginOrderValidationResult;
/** Capabilities provided by this pipeline */
capabilities: Set<string>;
/** Timestamp when pipeline was built */
builtAt: Date;
/** Configuration used to build this pipeline */
config: PipelineConfig;
}
/**
* Pipeline configuration
*
* Defines which plugins to enable, metadata, processing options,
* and validation behavior.
*/
interface PipelineConfig {
/** Plugins to enable (by name) */
enabledPlugins: string[];
/** Metadata for plugin configuration */
metadata: Record<string, unknown>;
/** Processing options (debug, field tracking, etc.) */
options: Record<string, unknown>;
/**
* Validation mode:
* - 'strict': Throw errors on validation failures (dev/CI)
* - 'warn': Log warnings but continue (production default)
* - 'silent': No validation output
*/
validationMode?: 'strict' | 'warn' | 'silent';
/** Enable debug logging */
debug?: boolean;
}
/**
* Detect appropriate validation mode based on environment
*
* Returns 'strict' in development/CI, 'warn' in production
*/
export declare function detectValidationMode(): 'strict' | 'warn' | 'silent';
/**
* Group plugins by their assigned processing phase
*
* @param pluginNames - Array of plugin names to group
* @param registry - Plugin metadata registry
* @returns Map of phase → plugin names
*/
export declare function groupPluginsByPhase(pluginNames: string[], registry: Map<string, PluginMetadata>): Map<ProcessingPhase, string[]>;
/**
* Validate that required capabilities are provided by the pipeline
*
* Throws an error if any plugin requires a capability that is not
* provided by any earlier plugin in the pipeline.
*
* @param orderedPlugins - Plugin names in execution order
* @param registry - Plugin metadata registry
* @param debug - Enable debug logging
*/
export declare function validateCapabilities(orderedPlugins: string[], registry: Map<string, PluginMetadata>, debug?: boolean): void;
/**
* Build a remark plugin pipeline with phase-based ordering
*
* This is the single source of truth for plugin ordering. It uses the
* phase-based architecture to ensure deterministic execution order and
* prevent subtle bugs like variables evaluating after conditionals (Issue #120).
*
* @param config - Pipeline configuration
* @param registry - Plugin metadata registry
* @returns Ordered pipeline with validation results
*
* @example
* ```typescript
* import { buildRemarkPipeline } from './pipeline-builder.js';
* import { GLOBAL_PLUGIN_REGISTRY } from '../../plugins/remark/plugin-metadata-registry.js';
*
* const pipeline = buildRemarkPipeline(
* {
* enabledPlugins: ['remarkImports', 'remarkTemplateFields', 'remarkHeaders'],
* metadata: { author: 'John Doe' },
* options: { debug: true },
* validationMode: 'strict'
* },
* GLOBAL_PLUGIN_REGISTRY
* );
*
* console.log('Plugin order:', pipeline.names);
* console.log('By phase:', pipeline.byPhase);
* ```
*/
export declare function buildRemarkPipeline(config: PipelineConfig, registry: Map<string, PluginMetadata>): OrderedPipeline;
export {};
//# sourceMappingURL=pipeline-builder.d.ts.map