@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/filters/FilterChain.d.ts

@@ -0,0 +1,320 @@
+/**
+ * FilterChain - Modular content filtering pipeline with complete configuration support
+ *
+ * Provides a sophisticated, configurable filter system that processes content through
+ * multiple stages with priority-based execution, performance monitoring, and error handling.
+ *
+ * Design Principles:
+ * - Complete modularity through app-default-config.json and app-custom-config.json
+ * - Zero hardcoded values - everything configurable
+ * - Reusable architecture for any content filtering needs
+ * - Performance monitoring and caching integration
+ *
+ * Related Issue: Phase 4 - Filter Pipeline Core
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+import BaseFilter from './BaseFilter.js';
+import type { FilterPhase } from './BaseFilter.js';
+import type { ParseContext } from '../context/ParseContext.js';
+/**
+ * Structured error returned by FilterChain.collectErrors() (#596).
+ * Filters that opt in implement their own collectErrors() returning rule
+ * violations of `severity: 'error'`. The chain accumulates them across all
+ * enabled filters; the save path (WikiRoutes.savePage) uses the array to
+ * decide whether to block the save and what to surface to the editor.
+ */
+export interface FilterValidationError {
+    filterId: string;
+    rule: string;
+    severity: 'error';
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Filter chain configuration
+ */
+export interface FilterChainConfig {
+    enabled: boolean;
+    maxFilters: number;
+    timeout: number;
+    enableProfiling: boolean;
+    failOnError: boolean;
+    cacheResults: boolean;
+    cacheTTL: number;
+    preventXSS: boolean;
+    sanitizeHTML: boolean;
+    stripDangerousContent: boolean;
+    enableParallelExecution: boolean;
+    maxConcurrentFilters: number;
+}
+/**
+ * Filter execution statistics
+ */
+export interface FilterExecutionStats {
+    executionCount: number;
+    totalTime: number;
+    errorCount: number;
+    lastExecuted: Date | null;
+}
+/**
+ * Filter chain statistics
+ */
+export interface FilterChainStats {
+    executionCount: number;
+    totalTime: number;
+    filterExecutions: Map<string, FilterExecutionStats>;
+    errorCount: number;
+    lastExecution: Date | null;
+}
+/**
+ * Performance execution record
+ */
+export interface PerformanceExecution {
+    executionTime: number;
+    success: boolean;
+    timestamp: number;
+}
+/**
+ * Alert thresholds
+ */
+export interface AlertThresholds {
+    executionTime: number;
+    errorRate: number;
+}
+/**
+ * Performance monitor
+ */
+export interface PerformanceMonitor {
+    enabled: boolean;
+    recentExecutions: PerformanceExecution[];
+    maxRecentEntries: number;
+    alertThresholds: AlertThresholds;
+}
+/**
+ * Initialization context
+ */
+export interface FilterChainInitContext {
+    engine?: WikiEngine;
+}
+/**
+ * WikiEngine minimal interface
+ */
+export interface WikiEngine {
+    getManager(name: string): unknown;
+}
+/**
+ * Chain statistics summary
+ */
+export interface ChainStatsSummary {
+    executionCount: number;
+    totalTime: number;
+    averageTime: number;
+    errorCount: number;
+    lastExecution: Date | null;
+    filterCount: number;
+    enabledFilterCount: number;
+}
+/**
+ * Extended filter chain statistics
+ */
+export interface ExtendedFilterChainStats {
+    chain: ChainStatsSummary;
+    filters: Record<string, FilterExecutionStats & {
+        averageTime: number;
+    }>;
+    configuration: {
+        enabled: boolean;
+        maxFilters: number;
+        timeout: number;
+        enableProfiling: boolean;
+        failOnError: boolean;
+    };
+    performance: {
+        recentExecutionCount: number;
+        alertThresholds: AlertThresholds;
+    } | null;
+}
+/**
+ * Exported filter info
+ */
+export interface ExportedFilterInfo {
+    filterId: string;
+    priority: number;
+    enabled: boolean;
+    description: string;
+}
+/**
+ * Exported chain state
+ */
+export interface ExportedChainState {
+    config: FilterChainConfig;
+    stats: Omit<FilterChainStats, 'filterExecutions'> & {
+        filterExecutions: Record<string, FilterExecutionStats>;
+    };
+    filters: ExportedFilterInfo[];
+}
+/**
+ * Configuration summary
+ */
+export interface ConfigurationSummary extends FilterChainConfig {
+    filterCount: number;
+    enabledFilterCount: number;
+    configurationSource: string;
+}
+/**
+ * FilterChain - Modular content filtering pipeline
+ */
+declare class FilterChain {
+    private engine;
+    private filters;
+    private filtersByPriority;
+    private filterMap;
+    private config;
+    private stats;
+    private performanceMonitor;
+    constructor(engine?: WikiEngine | null);
+    /**
+     * Initialize FilterChain with complete modular configuration
+     * @param context - Initialization context
+     */
+    initialize(context?: FilterChainInitContext): Promise<void>;
+    /**
+     * Load modular configuration from app-default-config.json and app-custom-config.json
+     * Demonstrates complete configuration modularity and reusability
+     */
+    loadModularConfiguration(): void;
+    /**
+     * Initialize performance monitoring for filter execution
+     */
+    private initializePerformanceMonitoring;
+    /**
+     * Add filter to the chain with modular configuration
+     * @param filter - Filter to add
+     * @param _options - Registration options
+     * @returns True if added successfully
+     */
+    addFilter(filter: BaseFilter, _options?: Record<string, unknown>): boolean;
+    /**
+     * Remove filter from the chain
+     * @param filterId - Filter ID to remove
+     * @returns True if removed successfully
+     */
+    removeFilter(filterId: string): boolean;
+    /**
+     * Rebuild priority-sorted filter list (modular ordering)
+     */
+    private rebuildPriorityList;
+    /**
+     * Process content through the filter chain with modular execution
+     * @param content - Content to filter
+     * @param context - Parse context
+     * @returns Filtered content
+     */
+    process(content: string, context: ParseContext, phase?: FilterPhase): Promise<string>;
+    /**
+     * Collect error-severity rule violations across all enabled filters without
+     * mutating content. Used by the save path to decide whether to block a save
+     * and what structured errors to surface to the editor (#596).
+     *
+     * Each filter that opts in exposes its own async `collectErrors(content,
+     * context)` returning a `FilterValidationError[]`. Filters without that
+     * method are skipped silently — they participate in render-time `process()`
+     * only.
+     *
+     * @param content - Content to validate
+     * @param context - Parse context
+     * @returns Aggregated error-severity violations from all enabled filters
+     */
+    collectErrors(content: string, context: ParseContext, phase?: FilterPhase): Promise<FilterValidationError[]>;
+    /**
+     * Execute filters sequentially (default, safe mode)
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Processed content
+     */
+    private executeFiltersSequential;
+    /**
+     * Execute filters in parallel (advanced mode - configurable)
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Processed content
+     */
+    private executeFiltersParallel;
+    /**
+     * Execute a single filter with error handling
+     * @param filter - Filter to execute
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Processed content
+     */
+    private executeFilter;
+    /**
+     * Track filter execution for performance monitoring (modular monitoring)
+     * @param executionTime - Execution time in milliseconds
+     * @param success - Whether execution was successful
+     */
+    private trackFilterExecution;
+    /**
+     * Check performance thresholds and generate alerts (modular alerting)
+     */
+    private checkPerformanceThresholds;
+    /**
+     * Generate performance alert (modular alerting)
+     * @param type - Alert type
+     * @param message - Alert message
+     */
+    private generateAlert;
+    /**
+     * Get filter by ID
+     * @param filterId - Filter ID
+     * @returns Filter or null if not found
+     */
+    getFilter(filterId: string): BaseFilter | null;
+    /**
+     * Get all filters sorted by priority
+     * @param enabledOnly - Only return enabled filters
+     * @returns Filters sorted by priority
+     */
+    getFilters(enabledOnly?: boolean): BaseFilter[];
+    /**
+     * Enable filter by ID
+     * @param filterId - Filter ID
+     * @returns True if successful
+     */
+    enableFilter(filterId: string): boolean;
+    /**
+     * Disable filter by ID
+     * @param filterId - Filter ID
+     * @returns True if successful
+     */
+    disableFilter(filterId: string): boolean;
+    /**
+     * Get comprehensive filter chain statistics (modular monitoring)
+     * @returns Filter chain statistics
+     */
+    getStats(): ExtendedFilterChainStats;
+    /**
+     * Reset all filter statistics
+     */
+    resetStats(): void;
+    /**
+     * Get configuration summary for debugging (modular introspection)
+     * @returns Configuration summary
+     */
+    getConfiguration(): ConfigurationSummary;
+    /**
+     * Export filter chain state for persistence or debugging
+     * @returns Serializable state
+     */
+    exportState(): ExportedChainState;
+    /**
+     * Clear all filters and reset state
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Shutdown filter chain
+     */
+    shutdown(): Promise<void>;
+}
+export default FilterChain;

package/lib/src/parsers/handlers/BaseSyntaxHandler.d.ts

@@ -0,0 +1,331 @@
+import type ParseContext from '../context/ParseContext.js';
+/**
+ * BaseSyntaxHandler - Abstract base class for all markup syntax handlers
+ *
+ * Defines the contract that all syntax handlers must implement and provides
+ * common utilities for pattern matching, parameter parsing, and error handling.
+ *
+ * Related Issue: #56 - Handler Registration and Priority System
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+/**
+ * Handler configuration options
+ */
+export interface HandlerOptions {
+    enabled?: boolean;
+    timeout?: number;
+    caseSensitive?: boolean;
+    multiline?: boolean;
+    global?: boolean;
+    version?: string;
+    description?: string;
+    dependencies?: Array<string | DependencySpec>;
+    throwOnError?: boolean;
+}
+/**
+ * Specific dependency specification
+ */
+export interface DependencySpec {
+    type: 'manager' | 'handler';
+    name: string;
+    version?: string;
+    optional?: boolean;
+}
+/**
+ * Handler performance statistics
+ */
+export interface HandlerStats {
+    executionCount: number;
+    totalTime: number;
+    errorCount: number;
+    lastExecuted: Date | null;
+    averageTime: number;
+}
+/**
+ * Dependency validation error
+ */
+export interface DependencyError {
+    type: 'manager' | 'handler' | 'validation_error';
+    name?: string;
+    dependency?: unknown;
+    message: string;
+    dependencySpec?: DependencySpec;
+}
+/**
+ * Parameter validation rule
+ */
+export interface ValidationRule {
+    type?: 'string' | 'number' | 'boolean' | 'object';
+    required?: boolean;
+    default?: unknown;
+    min?: number;
+    max?: number;
+    pattern?: string;
+}
+/**
+ * Parameter validation result
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    params: Record<string, unknown>;
+}
+/**
+ * Single parameter validation result
+ */
+export interface ParameterValidationResult {
+    error?: string;
+    value?: unknown;
+}
+/**
+ * Error context for debugging
+ */
+export interface ErrorContext {
+    handlerId: string;
+    error: string;
+    stack?: string;
+    contentLength: number;
+    contentPreview: string;
+    context: {
+        pageName?: string;
+        userName?: string;
+        processingTime?: number;
+    };
+    stats: HandlerStats;
+    timestamp: string;
+}
+/**
+ * Handler metadata
+ */
+export interface HandlerMetadata {
+    id: string;
+    version: string;
+    description: string;
+    priority: number;
+    pattern: string;
+    dependencies: Array<string | DependencySpec>;
+    options: Required<HandlerOptions>;
+    stats: HandlerStats & {
+        handlerId: string;
+        priority: number;
+        enabled: boolean;
+        initialized: boolean;
+    };
+}
+/**
+ * Handler clone configuration
+ */
+export interface HandlerCloneConfig {
+    handlerId?: string;
+    pattern: RegExp;
+    priority: number;
+    options: Required<HandlerOptions>;
+    version: string;
+    description: string;
+    dependencies: Array<string | DependencySpec>;
+}
+/**
+ * Initialization context (minimal interface for unconverted dependencies)
+ */
+export interface InitializationContext {
+    engine?: {
+        getManager(name: string): unknown;
+    };
+    handlerRegistry?: {
+        getHandler(name: string): unknown;
+    };
+}
+/**
+ * ParseContext re-export — the real class from `../context/ParseContext.js`.
+ * Kept as a re-export so existing handlers can keep their
+ * `import { ParseContext }` paths unchanged. (#629 Pass 2 resolved the
+ * long-standing TODO of using the proper ParseContext type.)
+ */
+export type { ParseContext };
+/**
+ * BaseSyntaxHandler - Abstract base class for all markup syntax handlers
+ */
+declare abstract class BaseSyntaxHandler {
+    priority: number;
+    readonly pattern: RegExp;
+    readonly handlerId: string;
+    readonly version: string;
+    readonly description: string;
+    readonly dependencies: Array<string | DependencySpec>;
+    protected options: Required<HandlerOptions>;
+    protected stats: HandlerStats;
+    protected initialized: boolean;
+    protected enabled: boolean;
+    protected initContext?: InitializationContext;
+    protected dependencyErrors?: DependencyError[];
+    /**
+     * Create a syntax handler
+     * @param pattern - Pattern to match (regex or string)
+     * @param priority - Handler priority (0-1000, higher = executed first)
+     * @param options - Handler configuration options
+     */
+    constructor(pattern: RegExp | string, priority?: number, options?: HandlerOptions);
+    /**
+     * Compile pattern into RegExp if it's a string
+     * @param pattern - Pattern to compile
+     * @returns Compiled regular expression
+     */
+    protected compilePattern(pattern: RegExp | string): RegExp;
+    /**
+     * Build regex flags based on options
+     * @returns Regex flags string
+     */
+    protected buildRegexFlags(): string;
+    /**
+     * Initialize the handler (optional override)
+     * Called when handler is registered
+     * @param context - Initialization context
+     */
+    initialize(context?: InitializationContext): Promise<void>;
+    /**
+     * Custom initialization logic (override in subclasses)
+     * @param _context - Initialization context
+     */
+    protected onInitialize(_context: InitializationContext): Promise<void>;
+    /**
+     * Validate handler dependencies
+     * @param context - Initialization context
+     */
+    protected validateDependencies(context: InitializationContext): void;
+    /**
+     * Validate specific dependency requirement
+     * @param dependency - Dependency specification
+     * @param context - Initialization context
+     */
+    protected validateSpecificDependency(dependency: DependencySpec, context: InitializationContext): void;
+    /**
+     * Get dependency validation errors
+     * @returns Array of dependency errors
+     */
+    getDependencyErrors(): DependencyError[];
+    /**
+     * Check if handler has unresolved dependencies
+     * @returns True if there are dependency errors
+     */
+    hasDependencyErrors(): boolean;
+    /**
+     * Main processing method - MUST be implemented by subclasses
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Processed content
+     */
+    abstract process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Handle a specific match - called for each pattern match
+     * @param match - Regex match result
+     * @param context - Parse context
+     * @returns Replacement content
+     */
+    handle(_match: RegExpMatchArray, _context: ParseContext): Promise<string>;
+    /**
+     * Execute the handler with performance tracking and error handling
+     * @param content - Content to process
+     * @param context - Parse context
+     * @returns Processed content
+     */
+    execute(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Create timeout promise for handler execution
+     * @returns Promise that rejects after timeout
+     */
+    protected createTimeoutPromise(): Promise<string>;
+    /**
+     * Create error context for debugging
+     * @param error - The error that occurred
+     * @param content - Content being processed
+     * @param context - Parse context
+     * @returns Error context
+     */
+    protected createErrorContext(error: Error, content: string, context: ParseContext): ErrorContext;
+    /**
+     * Parse parameters from parameter string
+     * Handles various formats: key=value, key='value', key="value"
+     * @param paramString - Parameter string to parse
+     * @returns Parsed parameters
+     */
+    parseParameters(paramString: string | null | undefined): Record<string, unknown>;
+    /**
+     * Validate parameters against schema
+     * @param params - Parameters to validate
+     * @param schema - Validation schema
+     * @returns Validation result
+     */
+    validateParameters(params: Record<string, unknown>, schema?: Record<string, ValidationRule>): ValidationResult;
+    /**
+     * Validate a single parameter
+     * @param key - Parameter key
+     * @param value - Parameter value
+     * @param rule - Validation rule
+     * @returns Validation result
+     */
+    protected validateParameter(key: string, value: unknown, rule: ValidationRule): ParameterValidationResult;
+    /**
+     * Enable the handler
+     */
+    enable(): void;
+    /**
+     * Disable the handler
+     */
+    disable(): void;
+    /**
+     * Check if handler is enabled
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get handler statistics
+     * @returns Handler statistics
+     */
+    getStats(): HandlerStats & {
+        handlerId: string;
+        priority: number;
+        enabled: boolean;
+        initialized: boolean;
+    };
+    /**
+     * Reset handler statistics
+     */
+    resetStats(): void;
+    /**
+     * Get handler metadata
+     * @returns Handler metadata
+     */
+    getMetadata(): HandlerMetadata;
+    /**
+     * Clean up handler resources (optional override)
+     * Called when handler is unregistered
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Custom shutdown logic (override in subclasses)
+     */
+    protected onShutdown(): Promise<void>;
+    /**
+     * Create a clone of this handler with different options
+     * @param overrides - Option overrides
+     * @returns Handler configuration for creating new instance
+     */
+    clone(overrides?: Partial<HandlerOptions> & {
+        handlerId?: string;
+        priority?: number;
+    }): HandlerCloneConfig;
+    /**
+     * String representation of handler
+     * @returns String representation
+     */
+    toString(): string;
+}
+/**
+ * Custom error class for handler execution errors
+ */
+export declare class HandlerExecutionError extends Error {
+    readonly handlerId: string;
+    readonly context: ErrorContext;
+    constructor(message: string, handlerId: string, context: ErrorContext);
+}
+export default BaseSyntaxHandler;