@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/dom/handlers/DOMPluginHandler.d.ts

@@ -0,0 +1,212 @@
+/**
+ * DOMPluginHandler - DOM-based plugin execution handler
+ *
+ * Replaces string-based regex plugin processing with DOM queries.
+ * Processes wiki plugins by querying WikiDocument for .wiki-plugin elements
+ * and executing them through PluginManager.
+ *
+ * Part of Phase 4 of WikiDocument DOM Migration (GitHub Issue #107)
+ *
+ * Usage:
+ *   In wiki markup: [{PluginName param=value}]
+ *   These are tokenized as PLUGIN tokens and become .wiki-plugin elements
+ *   This handler executes them and replaces with rendered output
+ */
+import type WikiDocument from '../WikiDocument.js';
+import type { LinkedomElement } from '../WikiDocument.js';
+/**
+ * Plugin execution context
+ */
+export interface PluginContext {
+    /** Page name */
+    pageName: string;
+    /** User name */
+    userName: string;
+    /** User context information */
+    userContext?: {
+        username?: string;
+        email?: string;
+        fullName?: string;
+        roles?: string[];
+        [key: string]: unknown;
+    };
+    /** Request information */
+    requestInfo?: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    /** Page front matter metadata (uuid, title, etc.) */
+    pageMetadata?: unknown;
+    /** WikiEngine reference */
+    engine: unknown;
+    /** WikiContext reference */
+    wikiContext?: unknown;
+    /** Plugin parameters */
+    parameters: Record<string, string>;
+    /** Plugin body content (for body plugins) */
+    bodyContent: string | null;
+    /** Plugin name */
+    pluginName: string;
+    /** WikiDocument reference */
+    wikiDocument?: WikiDocument;
+    /** Plugin DOM element */
+    pluginElement?: LinkedomElement | null;
+    /** Link graph for plugins like ReferringPagesPlugin */
+    linkGraph?: Record<string, unknown>;
+    /** Page context (nested structure) */
+    pageContext?: {
+        pageName?: string;
+        [key: string]: unknown;
+    };
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Parsed plugin information
+ */
+export interface PluginInfo {
+    /** Plugin name */
+    pluginName: string;
+    /** Plugin parameters */
+    parameters: Record<string, string>;
+}
+/**
+ * Plugin manager interface
+ */
+interface PluginManager {
+    /** Execute a plugin */
+    execute(pluginName: string, pageName: string, parameters: Record<string, string>, context: PluginContext): Promise<string | null>;
+    /** Additional manager methods */
+    [key: string]: unknown;
+}
+/**
+ * WikiEngine interface (minimal)
+ */
+interface WikiEngine {
+    /** Get a manager by name */
+    getManager(name: string): unknown;
+    /** Additional engine properties */
+    [key: string]: unknown;
+}
+/**
+ * Extracted element from JSPWiki syntax extraction
+ */
+export interface ExtractedPluginElement {
+    /** Element type */
+    type: string;
+    /** Plugin inner content (e.g., "TableOfContents" or "Search query='wiki'") */
+    inner: string;
+    /** Unique ID for tracking */
+    id: number;
+    /** Original text */
+    originalText?: string;
+    /** Start index in content */
+    startIndex?: number;
+    /** End index in content */
+    endIndex?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Information about a single plugin
+ */
+export interface PluginInstanceInfo {
+    /** Plugin name */
+    name: string;
+    /** Plugin parameters */
+    parameters: Record<string, string>;
+}
+/**
+ * Statistics about plugin processing
+ */
+export interface PluginStatistics {
+    /** Total number of plugins in document */
+    totalPlugins: number;
+    /** Number of unique plugins */
+    uniqueCount: number;
+    /** Array of unique plugin names */
+    uniquePlugins: string[];
+    /** Array of plugin instances */
+    plugins: PluginInstanceInfo[];
+}
+/**
+ * DOMPluginHandler class
+ */
+declare class DOMPluginHandler {
+    /** WikiEngine instance */
+    private engine;
+    /** PluginManager instance (loaded dynamically) */
+    protected pluginManager: PluginManager | null;
+    /**
+     * Creates a new DOMPluginHandler
+     *
+     * @param {WikiEngine} engine - WikiEngine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initializes the handler
+     */
+    initialize(): Promise<void>;
+    /**
+     * Processes plugins in a WikiDocument
+     *
+     * Queries for .wiki-plugin elements and executes them.
+     * This is the DOM-based equivalent of PluginSyntaxHandler.process()
+     *
+     * @param {WikiDocument} wikiDocument - The WikiDocument to process
+     * @param {PluginContext} context - Rendering context
+     * @returns {Promise<WikiDocument>} Updated WikiDocument
+     */
+    processPlugins(wikiDocument: WikiDocument, context: PluginContext): Promise<WikiDocument>;
+    /**
+     * Parses plugin content string into name and parameters
+     *
+     * @param {string} pluginContent - Plugin content (e.g., "TableOfContents max=3")
+     * @returns {PluginInfo | null} { pluginName, parameters } or null if invalid
+     */
+    parsePluginContent(pluginContent: string): PluginInfo | null;
+    /**
+     * Parses parameter string into object
+     *
+     * @param {string} paramString - Parameter string (e.g., "max=3 show=true")
+     * @returns {Record<string, string>} Parsed parameters
+     */
+    parseParameters(paramString: string): Record<string, string>;
+    /**
+     * Executes a plugin through PluginManager
+     *
+     * @param {string} pluginName - Name of the plugin
+     * @param {Record<string, string>} parameters - Plugin parameters
+     * @param {PluginContext} context - Rendering context
+     * @param {unknown} pluginElement - The plugin DOM element
+     * @returns {Promise<string | null>} Plugin output HTML or null
+     */
+    executePlugin(pluginName: string, parameters: Record<string, string>, context: PluginContext, pluginElement: unknown): Promise<string | null>;
+    /**
+     * Creates a DOM node from an extracted plugin element
+     *
+     * This method is part of the Phase 2 extraction-based parsing (Issue #114).
+     * It creates a plugin node from a pre-extracted element and executes the plugin.
+     *
+     * @param {ExtractedPluginElement} element - Extracted element from extractJSPWikiSyntax()
+     * @param {PluginContext} context - Rendering context
+     * @param {WikiDocument} wikiDocument - WikiDocument to create node in
+     * @returns {Promise<Element>} DOM node for the plugin
+     *
+     * @example
+     * const element = { type: 'plugin', inner: 'TableOfContents', id: 1, ... };
+     * const node = await handler.createNodeFromExtract(element, context, wikiDoc);
+     * // Returns: <span class="wiki-plugin" data-plugin="TableOfContents">...plugin output...</span>
+     */
+    createNodeFromExtract(element: ExtractedPluginElement, context: PluginContext, wikiDocument: WikiDocument): Promise<LinkedomElement>;
+    /**
+     * Gets statistics about plugin processing
+     *
+     * @param {WikiDocument} wikiDocument - Document to analyze
+     * @returns {PluginStatistics} Statistics
+     */
+    getStatistics(wikiDocument: WikiDocument): PluginStatistics;
+}
+export default DOMPluginHandler;

package/lib/src/parsers/dom/handlers/DOMVariableHandler.d.ts

@@ -0,0 +1,171 @@
+/**
+ * DOMVariableHandler - DOM-based variable expansion handler
+ *
+ * Replaces string-based regex variable expansion with DOM queries.
+ * Processes wiki variables by querying WikiDocument for .wiki-variable elements
+ * and resolving their values through VariableManager.
+ *
+ * Part of Phase 3 of WikiDocument DOM Migration (GitHub Issue #93)
+ *
+ * Usage:
+ *   In wiki markup: {$username}, {$pagename}, {$date}, etc.
+ *   These are tokenized as VARIABLE tokens and become .wiki-variable elements
+ *   This handler resolves them to actual values
+ */
+import type WikiDocument from '../WikiDocument.js';
+import type { LinkedomElement } from '../WikiDocument.js';
+/**
+ * Context for variable resolution
+ */
+export interface VariableContext {
+    /** Page name */
+    pageName?: string;
+    /** User context information */
+    userContext?: {
+        username?: string;
+        email?: string;
+        fullName?: string;
+        roles?: string[];
+        [key: string]: unknown;
+    };
+    /** Request information */
+    requestInfo?: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    /** Page context (nested structure from WikiContext) */
+    pageContext?: VariableContext;
+    /** WikiEngine reference */
+    engine?: unknown;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Variable handler function type
+ */
+export type VariableHandler = (context: VariableContext) => string | number | Promise<string | number>;
+/**
+ * Variable manager interface
+ */
+interface VariableManager {
+    /** Map of variable handlers */
+    variableHandlers: Map<string, VariableHandler>;
+    /** Additional manager methods */
+    [key: string]: unknown;
+}
+/**
+ * WikiEngine interface (minimal)
+ */
+interface WikiEngine {
+    /** Get a manager by name */
+    getManager(name: string): unknown;
+    /** Additional engine properties */
+    [key: string]: unknown;
+}
+/**
+ * Extracted element from JSPWiki syntax extraction
+ */
+export interface ExtractedElement {
+    /** Element type */
+    type: string;
+    /** Variable name (may include $ prefix) */
+    varName: string;
+    /** Unique ID for tracking */
+    id: number;
+    /** Original text */
+    originalText?: string;
+    /** Start index in content */
+    startIndex?: number;
+    /** End index in content */
+    endIndex?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Information about a single variable
+ */
+export interface VariableInfo {
+    /** Variable name */
+    name: string;
+    /** Whether the variable was successfully resolved */
+    resolved: boolean;
+}
+/**
+ * Statistics about variable processing
+ */
+export interface VariableStatistics {
+    /** Total number of variables in document */
+    totalVariables: number;
+    /** Number of unique variables */
+    uniqueCount: number;
+    /** Array of unique variable names */
+    uniqueVariables: string[];
+    /** Array of variable information */
+    variables: VariableInfo[];
+}
+/**
+ * DOMVariableHandler class
+ */
+declare class DOMVariableHandler {
+    /** WikiEngine instance */
+    private engine;
+    /** VariableManager instance (loaded dynamically) */
+    protected variableManager: VariableManager | null;
+    /**
+     * Creates a new DOMVariableHandler
+     *
+     * @param {WikiEngine} engine - WikiEngine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initializes the handler
+     */
+    initialize(): Promise<void>;
+    /**
+     * Processes variables in a WikiDocument
+     *
+     * Queries for .wiki-variable elements and resolves their values.
+     * This is the DOM-based equivalent of VariableManager.expandVariables()
+     *
+     * @param {WikiDocument} wikiDocument - The WikiDocument to process
+     * @param {VariableContext} context - Rendering context
+     * @returns {Promise<WikiDocument>} Updated WikiDocument
+     */
+    processVariables(wikiDocument: WikiDocument, context: VariableContext): Promise<WikiDocument>;
+    /**
+     * Resolves a variable name to its value
+     *
+     * @param {string} varName - Variable name (without {$ })
+     * @param {VariableContext} context - Rendering context
+     * @returns {string | number | null} Variable value or null if not found
+     */
+    resolveVariable(varName: string, context: VariableContext): string | number | null;
+    /**
+     * Creates a DOM node from an extracted variable element
+     *
+     * This method is part of the Phase 2 extraction-based parsing (Issue #114).
+     * It creates a variable node from a pre-extracted element instead of
+     * parsing it from tokens.
+     *
+     * @param {ExtractedElement} element - Extracted element from extractJSPWikiSyntax()
+     * @param {VariableContext} context - Rendering context
+     * @param {WikiDocument} wikiDocument - WikiDocument to create node in
+     * @returns {Promise<Element>} DOM node for the variable
+     *
+     * @example
+     * const element = { type: 'variable', varName: '$username', id: 0, ... };
+     * const node = await handler.createNodeFromExtract(element, context, wikiDoc);
+     * // Returns: <span class="wiki-variable" data-variable="username">JohnDoe</span>
+     */
+    createNodeFromExtract(element: ExtractedElement, context: VariableContext, wikiDocument: WikiDocument): Promise<LinkedomElement>;
+    /**
+     * Gets statistics about variable processing
+     *
+     * @param {WikiDocument} wikiDocument - Document to analyze
+     * @returns {VariableStatistics} Statistics
+     */
+    getStatistics(wikiDocument: WikiDocument): VariableStatistics;
+}
+export default DOMVariableHandler;

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

@@ -0,0 +1,269 @@
+import type ParseContext from '../context/ParseContext.js';
+import type { FilterValidationError } from './FilterChain.js';
+/**
+ * BaseFilter - Abstract base class for all content filters with modular configuration
+ *
+ * Provides the foundation for content filtering with complete modularity through
+ * app-default-config.json and app-custom-config.json configuration support.
+ *
+ * Design Principles:
+ * - Complete configuration modularity and reusability
+ * - Zero hardcoded values - everything configurable
+ * - Consistent interface across all filter types
+ * - Performance monitoring and error handling
+ * - Security-first design with configurable validation
+ *
+ * Related Issue: Phase 4 - Filter Pipeline Core
+ * Epic: #41 - Implement JSPWikiMarkupParser for Complete Enhancement Support
+ */
+/**
+ * Pipeline phase a filter operates in (#614).
+ *
+ * - `'markup'` (default) — runs on raw markdown/JSPWiki content before
+ *   markdown rendering. ValidationFilter, SpamFilter operate here.
+ * - `'html'` — runs on rendered HTML after markdown-it. SecurityFilter
+ *   (XSS prevention, dangerous-tag stripping, attribute allow-listing)
+ *   operates here, since its rules target HTML constructs that don't
+ *   exist in raw markdown.
+ */
+export type FilterPhase = 'markup' | 'html';
+/**
+ * Filter configuration options
+ */
+export interface FilterOptions {
+    enabled?: boolean;
+    timeout?: number;
+    cacheResults?: boolean;
+    cacheTTL?: number;
+    version?: string;
+    description?: string;
+    category?: string;
+    phase?: FilterPhase;
+}
+/**
+ * Filter performance statistics
+ */
+export interface FilterStats {
+    executionCount: number;
+    totalTime: number;
+    errorCount: number;
+    lastExecuted: Date | null;
+    averageTime: number;
+}
+/**
+ * Filter configuration (from config files)
+ */
+export interface FilterConfig {
+    enabled: boolean;
+    priority: number;
+    timeout: number;
+    cacheResults: boolean;
+    cacheTTL: number;
+    reportErrors: boolean;
+    logLevel: string;
+}
+/**
+ * Filter metadata
+ */
+export interface FilterMetadata {
+    id: string;
+    version: string;
+    description: string;
+    category: string;
+    priority: number;
+    enabled: boolean;
+    options: Required<FilterOptions>;
+    stats: FilterStats & {
+        filterId: string;
+        priority: number;
+        enabled: boolean;
+        initialized: boolean;
+        category: string;
+    };
+    configuration: FilterConfig | null;
+}
+/**
+ * Filter error context
+ */
+export interface FilterErrorContext {
+    filterId: string;
+    error: string;
+    stack?: string;
+    contentLength: number;
+    contentPreview: string;
+    context: {
+        pageName?: string;
+        userName?: string;
+    };
+    stats: FilterStats;
+    timestamp: string;
+}
+/**
+ * Configuration summary
+ */
+export interface ConfigurationSummary {
+    filterId: string;
+    enabled: boolean;
+    priority: number;
+    configuration: FilterConfig | null;
+    configurationSource: 'loaded' | 'defaults';
+    options: Required<FilterOptions>;
+}
+/**
+ * Initialization context (minimal interface for unconverted dependencies)
+ */
+export interface FilterInitializationContext {
+    engine?: {
+        getManager(name: string): unknown;
+    };
+}
+/**
+ * ParseContext re-export — the real class from `../context/ParseContext.js`.
+ * Kept as a re-export so existing filters can keep their
+ * `import { ParseContext }` paths unchanged. (#629 Pass 2)
+ */
+export type { ParseContext };
+/**
+ * BaseFilter - Abstract base class for all content filters
+ */
+declare abstract class BaseFilter {
+    priority: number;
+    readonly filterId: string;
+    readonly version: string;
+    readonly description: string;
+    readonly category: string;
+    readonly phase: FilterPhase;
+    protected options: Required<FilterOptions>;
+    protected stats: FilterStats;
+    protected enabled: boolean;
+    protected initialized: boolean;
+    protected config: FilterConfig | null;
+    /**
+     * Create a content filter
+     * @param priority - Filter priority (0-1000, higher = executed first)
+     * @param options - Filter configuration options
+     */
+    constructor(priority?: number, options?: FilterOptions);
+    /**
+     * Initialize filter with modular configuration
+     * @param context - Initialization context
+     */
+    initialize(context?: FilterInitializationContext): Promise<void>;
+    /**
+     * Load configuration from app-default-config.json and app-custom-config.json
+     * @param context - Initialization context
+     */
+    protected loadModularConfiguration(context: FilterInitializationContext): void;
+    /**
+     * Get filter type for configuration lookup (override in subclasses)
+     * @returns Filter type for configuration
+     */
+    protected getFilterType(): string | null;
+    /**
+     * Custom initialization logic (override in subclasses)
+     * @param _context - Initialization context
+     */
+    protected onInitialize(_context: FilterInitializationContext): Promise<void>;
+    /**
+     * Main filter processing method - MUST be implemented by subclasses
+     * @param content - Content to filter
+     * @param context - Parse context
+     * @returns Filtered content
+     */
+    abstract process(content: string, context: ParseContext): Promise<string>;
+    /**
+     * Rule violations that must BLOCK a page save — MUST be implemented by
+     * subclasses (#1037).
+     *
+     * Abstract on purpose. `FilterChain.collectErrors()` calls this on every
+     * enabled filter, but skipped any filter that did not define it, so a filter
+     * could opt out of save-time enforcement by simply not having the method —
+     * invisibly, with nothing to grep for. SecurityFilter and SpamFilter both
+     * did exactly that, which is why a page containing `<script>` saved cleanly
+     * while a filter that would have caught it was enabled and running.
+     *
+     * Declaring it here turns that silence into a compile error. A filter that
+     * genuinely blocks nothing returns `[]` — one explicit line stating a
+     * position, rather than an absence nobody notices.
+     *
+     * Note the input: at save time this receives the page SOURCE, not rendered
+     * HTML, regardless of the filter's `phase`. A filter whose `process()` works
+     * on rendered output must not reuse that logic here — assuming otherwise is
+     * what made SecurityFilter's `preventXSS()` entity-encode whole documents.
+     *
+     * Only `severity: 'error'` belongs here. Warnings are surfaced at render
+     * time and must never stop a save.
+     *
+     * @param content - The page source about to be written
+     * @param context - Parse context (pageName, userName, engine)
+     * @returns Blocking violations; empty when the content is acceptable
+     */
+    abstract collectErrors(content: string, context: ParseContext): Promise<FilterValidationError[]>;
+    /**
+     * Execute filter 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 error context for debugging (modular error handling)
+     * @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): FilterErrorContext;
+    /**
+     * Enable the filter
+     */
+    enable(): void;
+    /**
+     * Disable the filter
+     */
+    disable(): void;
+    /**
+     * Check if filter is enabled
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get filter statistics
+     * @returns Filter statistics
+     */
+    getStats(): FilterStats & {
+        filterId: string;
+        priority: number;
+        enabled: boolean;
+        initialized: boolean;
+        category: string;
+    };
+    /**
+     * Reset filter statistics
+     */
+    resetStats(): void;
+    /**
+     * Get filter metadata
+     * @returns Filter metadata
+     */
+    getMetadata(): FilterMetadata;
+    /**
+     * Get configuration summary for debugging (modular introspection)
+     * @returns Configuration summary
+     */
+    getConfigurationSummary(): ConfigurationSummary;
+    /**
+     * Clean up filter resources (optional override)
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Custom shutdown logic (override in subclasses)
+     */
+    protected onShutdown(): Promise<void>;
+    /**
+     * String representation of filter
+     * @returns String representation
+     */
+    toString(): string;
+}
+export default BaseFilter;