@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/dom/DOMParser.d.ts

@@ -0,0 +1,252 @@
+import WikiDocument from './WikiDocument.js';
+/**
+ * DOMParser - Complete DOM-based parsing pipeline for wiki markup
+ *
+ * ============================================================================
+ * ARCHITECTURE NOTE (Phase 4, Issue #118):
+ * ============================================================================
+ *
+ * **This DOMParser is a REFERENCE IMPLEMENTATION and is NOT actively used
+ * in the current rendering pipeline.**
+ *
+ * This parser uses the Tokenizer → DOMBuilder pipeline, which was the Phase 0
+ * approach to WikiDocument DOM parsing. However, it has been superseded by
+ * the extraction-based approach in Phases 1-3.
+ *
+ * CURRENT ACTIVE PIPELINE:
+ * ------------------------
+ * Use `MarkupParser.parseWithDOMExtraction()` instead of this DOMParser.
+ *
+ * The new pipeline:
+ * 1. MarkupParser.extractJSPWikiSyntax() - Extract JSPWiki syntax
+ * 2. MarkupParser.createDOMNode() - Create DOM nodes
+ * 3. markdown-it makeHtml() - Process markdown
+ * 4. MarkupParser.mergeDOMNodes() - Merge nodes into HTML
+ *
+ * WHY THIS DOMPARSER IS KEPT:
+ * ---------------------------
+ * - Reference implementation for token-based parsing
+ * - Useful for understanding the tokenization approach
+ * - May be enhanced for specific use cases in the future
+ * - Educational value for understanding different parsing strategies
+ *
+ * SEE ALSO:
+ * - Tokenizer.js - For detailed architecture notes
+ * - MarkupParser.parseWithDOMExtraction() - Current active pipeline
+ * - Issue #114 - WikiDocument DOM Solution
+ * - Issue #118 - Architecture documentation (this change)
+ *
+ * ============================================================================
+ *
+ * ORIGINAL DESCRIPTION:
+ * Integrates Tokenizer and DOMBuilder to convert wiki markup into
+ * a structured WikiDocument DOM tree. Provides error handling, recovery,
+ * and detailed error messages with position information.
+ *
+ * This follows JSPWiki's MarkupParser architecture.
+ *
+ * Key Features:
+ * - Complete parsing pipeline (Tokenizer → DOMBuilder)
+ * - Error handling with position tracking
+ * - Helpful error messages
+ * - Parse statistics and metadata
+ * - Graceful degradation on errors
+ *
+ * Part of Phase 2.5 of WikiDocument DOM Migration (GitHub Issue #93)
+ *
+ * JSPWiki Reference:
+ * https://github.com/apache/jspwiki/blob/master/jspwiki-main/src/main/java/org/apache/wiki/parser/MarkupParser.java
+ */
+/**
+ * DOMParser options
+ */
+export interface DOMParserOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Throw on parse errors instead of creating error document */
+    throwOnError?: boolean;
+    /** Error callback */
+    onError?: ((error: ParseError) => void) | null;
+    /** Warning callback */
+    onWarning?: ((warning: WarningInfo) => void) | null;
+}
+/**
+ * Parse statistics
+ */
+export interface ParseStatistics {
+    /** Total number of parses attempted */
+    totalParses: number;
+    /** Number of successful parses */
+    successfulParses: number;
+    /** Number of failed parses */
+    failedParses: number;
+    /** Total parse time in milliseconds */
+    totalParseTime: number;
+    /** Last parse time in milliseconds */
+    lastParseTime: number;
+}
+/**
+ * Extended statistics with computed values
+ */
+export interface ExtendedStatistics extends ParseStatistics {
+    /** Average parse time in milliseconds */
+    averageParseTime: number;
+    /** Success rate as percentage */
+    successRate: number;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    /** Whether the content is valid */
+    valid: boolean;
+    /** Parse errors */
+    errors: ErrorInfo[];
+    /** Parse warnings */
+    warnings: WarningInfo[];
+}
+/**
+ * Error information
+ */
+export interface ErrorInfo {
+    /** Error message */
+    message: string;
+    /** Character position */
+    position?: number;
+    /** Line number */
+    line?: number;
+    /** Column number */
+    column?: number;
+}
+/**
+ * Warning information
+ */
+export interface WarningInfo {
+    /** Warning message */
+    message: string;
+    /** Line number */
+    line?: number;
+    /** Column number */
+    column?: number;
+}
+/**
+ * Token interface (from Tokenizer)
+ */
+export interface Token {
+    /** Token type */
+    type: string;
+    /** Token value */
+    value: string;
+    /** Line number */
+    line?: number;
+    /** Column number */
+    column?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Rendering context
+ */
+export interface RenderContext {
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * DOMParser class
+ */
+declare class DOMParser {
+    /** Parser options */
+    protected options: Required<DOMParserOptions>;
+    /** Parse statistics */
+    private parseStats;
+    /**
+     * Creates a new DOMParser
+     *
+     * @param options - Parser options
+     */
+    constructor(options?: DOMParserOptions);
+    /**
+     * Parses wiki markup content into a WikiDocument
+     *
+     * Main entry point for DOM-based parsing. This is equivalent to
+     * JSPWiki's MarkupParser.parse() method.
+     *
+     * @param content - Wiki markup content to parse
+     * @param context - Rendering context (page info, user, etc.)
+     * @returns Parsed WikiDocument with DOM tree
+     * @throws ParseError if throwOnError is true and parsing fails
+     */
+    parse(content: string | null | undefined, context?: RenderContext | null): WikiDocument;
+    /**
+     * Creates an error document when parsing fails
+     *
+     * This allows graceful degradation - the page will still render
+     * but show the error to the user.
+     *
+     * @param content - Original content
+     * @param context - Rendering context
+     * @param error - The error that occurred
+     * @returns Error document
+     */
+    createErrorDocument(content: string, context: RenderContext | null, error: Error): WikiDocument;
+    /**
+     * Validates wiki markup without building full DOM
+     *
+     * Useful for syntax checking before saving.
+     *
+     * @param content - Wiki markup to validate
+     * @returns Validation result { valid: boolean, errors: [], warnings: [] }
+     */
+    validate(content: string): ValidationResult;
+    /**
+     * Checks tokens for common warnings
+     *
+     * @param tokens - Tokens to check
+     * @param result - Result object to add warnings to
+     */
+    checkForWarnings(tokens: Token[], result: ValidationResult): void;
+    /**
+     * Gets parser statistics
+     *
+     * @returns Parser statistics
+     */
+    getStatistics(): ExtendedStatistics;
+    /**
+     * Resets parser statistics
+     */
+    resetStatistics(): void;
+    /**
+     * Logs debug message if debug mode enabled
+     *
+     * @param message - Message to log
+     */
+    log(message: string): void;
+}
+/**
+ * Custom error class for parse errors
+ */
+export declare class ParseError extends Error {
+    /** Error type */
+    type: string;
+    /** Character position */
+    position: number;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column: number;
+    /** Underlying error */
+    cause?: Error;
+    /**
+     * Creates a parse error with position information
+     *
+     * @param type - Error type
+     * @param position - Character position
+     * @param line - Line number
+     * @param column - Column number
+     * @param message - Error message
+     * @param cause - Underlying error
+     */
+    constructor(type: string, position: number, line: number, column: number, message: string, cause?: Error);
+}
+export { DOMParser };
+export default DOMParser;

package/lib/src/parsers/dom/Tokenizer.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Tokenizer - Character-by-character parser for wiki markup
+ *
+ * ============================================================================
+ * ARCHITECTURE NOTE (Phase 4, Issue #118):
+ * ============================================================================
+ *
+ * **This Tokenizer is a REFERENCE IMPLEMENTATION and is NOT actively used
+ * in the current rendering pipeline.**
+ *
+ * HISTORY:
+ * --------
+ * Prior to Issue #114, this Tokenizer was part of the Phase 0 DOM parsing
+ * pipeline (Tokenizer → DOMBuilder → WikiDocument). However, this approach
+ * had conflicts when trying to parse both markdown AND JSPWiki syntax,
+ * resulting in bugs like ## headings becoming list items (Issue #110, #93).
+ *
+ * CURRENT ARCHITECTURE (Phases 1-3, Issue #114):
+ * -----------------------------------------------
+ * The rendering pipeline now uses a pre-extraction strategy inspired by
+ * JSPWiki's approach with FlexMark:
+ *
+ * 1. **Phase 1 - Extraction** (MarkupParser.extractJSPWikiSyntax())
+ *    - Extract ONLY JSPWiki syntax using regex
+ *    - Replace with HTML comment placeholders
+ *    - Result: Sanitized markdown + extracted elements
+ *
+ * 2. **Phase 2 - DOM Creation** (MarkupParser.createDOMNode())
+ *    - Create DOM nodes from extracted elements
+ *    - Uses DOMVariableHandler, DOMPluginHandler, DOMLinkHandler
+ *    - Result: Array of DOM nodes with data-jspwiki-id
+ *
+ * 3. **Phase 3 - markdown-it + Merge** (MarkupParser.parseWithDOMExtraction())
+ *    - markdown-it processes the sanitized markdown (handles ALL markdown)
+ *    - mergeDOMNodes() replaces placeholders with rendered nodes
+ *    - Result: Final HTML with both markdown and JSPWiki syntax
+ *
+ * WHY THIS TOKENIZER IS KEPT:
+ * ---------------------------
+ * - **Reference**: Documents JSPWiki syntax patterns clearly
+ * - **Testing**: Useful for unit testing syntax recognition
+ * - **Future**: May be enhanced for advanced use cases
+ * - **Educational**: Helps understand what we're parsing
+ *
+ * KEY DIFFERENCE:
+ * --------------
+ * - **Tokenizer**: Character-by-character, token-based parsing
+ * - **extractJSPWikiSyntax()**: Regex-based extraction (faster, simpler)
+ *
+ * The extraction approach is faster and avoids markdown conflicts because:
+ * 1. It extracts JSPWiki syntax BEFORE markdown parsing
+ * 2. markdown-it handles ALL markdown (no conflicts)
+ * 3. DOM nodes are merged back AFTER markdown conversion
+ *
+ * ============================================================================
+ *
+ * KEY FEATURES OF THIS TOKENIZER:
+ * - Character-by-character reading with position tracking
+ * - Lookahead support via peekChar()
+ * - Pushback support for complex token recognition
+ * - Line and column tracking for error reporting
+ * - Handles Unicode characters correctly
+ * - JSPWiki-only syntax (no markdown patterns)
+ *
+ * RELATED:
+ * - Issue #93: WikiDocument DOM Epic
+ * - Issue #110: Escaping bug
+ * - Issue #114: WikiDocument DOM Solution (heading bug fix)
+ * - Issue #118: Remove Markdown Tokenization (this change)
+ * - docs/planning/WikiDocument-DOM-Solution.md
+ *
+ * Part of Phase 2 of WikiDocument DOM Migration (GitHub Issue #93)
+ */
+/**
+ * Token types enum
+ */
+export declare enum TokenType {
+    TEXT = "TEXT",
+    ESCAPED = "ESCAPED",
+    VARIABLE = "VARIABLE",
+    PLUGIN = "PLUGIN",
+    METADATA = "METADATA",
+    WIKI_TAG = "WIKI_TAG",
+    LINK = "LINK",
+    INTERWIKI = "INTERWIKI",
+    HEADING = "HEADING",
+    LIST_ITEM = "LIST_ITEM",
+    TABLE_CELL = "TABLE_CELL",
+    BOLD = "BOLD",
+    ITALIC = "ITALIC",
+    CODE_INLINE = "CODE_INLINE",
+    CODE_BLOCK = "CODE_BLOCK",
+    COMMENT = "COMMENT",
+    NEWLINE = "NEWLINE",
+    EOF = "EOF"
+}
+/**
+ * Token metadata interface
+ */
+export interface TokenMetadata {
+    /** Variable name (for VARIABLE tokens) */
+    varName?: string;
+    /** Plugin content (for PLUGIN tokens) */
+    pluginContent?: string;
+    /** Metadata content (for METADATA tokens) */
+    metadataContent?: string;
+    /** Link target (for LINK tokens) */
+    link?: string;
+    /** Link text (for LINK tokens) */
+    text?: string;
+    /** Raw attribute string after the second pipe (for LINK tokens), e.g. `class='btn'` */
+    attrs?: string;
+    /** Heading level (for HEADING tokens) */
+    level?: number;
+    /** List marker (* or #) (for LIST_ITEM tokens) */
+    marker?: string;
+    /** Whether list is ordered (for LIST_ITEM tokens) */
+    ordered?: boolean;
+    /** Additional metadata properties */
+    [key: string]: unknown;
+}
+/**
+ * Position information
+ */
+export interface PositionInfo {
+    /** Character position in input */
+    position: number;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column: number;
+}
+/**
+ * Token structure
+ */
+export interface Token extends PositionInfo {
+    /** Token type from TokenType enum */
+    type: TokenType | string;
+    /** Token value/content */
+    value: string;
+    /** Additional token-specific data */
+    metadata?: TokenMetadata;
+    /** Index signature for additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Tokenizer class
+ */
+export declare class Tokenizer {
+    /** Input string */
+    protected input: string;
+    /** Length of input */
+    private length;
+    /** Current position in input */
+    position: number;
+    /** Current line number */
+    line: number;
+    /** Current column number */
+    column: number;
+    /** Pushback buffer for character lookahead */
+    private pushbackBuffer;
+    /**
+     * Create a new Tokenizer
+     * @param input - The wiki markup to tokenize
+     */
+    constructor(input: string | null | undefined);
+    /**
+     * Get the current character without advancing
+     * @returns Current character or null if at EOF
+     */
+    peekChar(): string | null;
+    /**
+     * Get the next character and advance position
+     * @returns Next character or null if at EOF
+     */
+    nextChar(): string | null;
+    /**
+     * Push a character back onto the input stream
+     * Allows the tokenizer to "undo" reading a character
+     * @param char - Character to push back
+     */
+    pushBack(char: string | null): void;
+    /**
+     * Peek ahead N characters without consuming them
+     * @param count - Number of characters to peek ahead
+     * @returns String of next N characters
+     */
+    peekAhead(count: number): string;
+    /**
+     * Skip whitespace characters (space, tab)
+     * Does NOT skip newlines
+     * @returns Number of whitespace characters skipped
+     */
+    skipWhitespace(): number;
+    /**
+     * Skip all whitespace including newlines
+     * @returns Number of whitespace characters skipped
+     */
+    skipAllWhitespace(): number;
+    /**
+     * Check if we're at the end of the input
+     * @returns True if at EOF
+     */
+    isEOF(): boolean;
+    /**
+     * Check if we're at the start of a line
+     * @returns True if at line start
+     */
+    isLineStart(): boolean;
+    /**
+     * Get current position information
+     * @returns Position information
+     */
+    getPosition(): PositionInfo;
+    /**
+     * Create a token with current position information
+     * @param type - Token type from TokenType enum
+     * @param value - Token value
+     * @param metadata - Additional token metadata
+     * @returns The created token
+     */
+    createToken(type: TokenType | string, value: string, metadata?: TokenMetadata): Token;
+    /**
+     * Read until a specific character or string is found
+     * @param delimiters - Character(s) to stop at
+     * @param consume - Whether to consume the delimiter
+     * @returns Text read until delimiter
+     */
+    readUntil(delimiters: string | string[], consume?: boolean): string;
+    /**
+     * Match a specific string at current position
+     * @param str - String to match
+     * @param consume - Whether to consume if matched
+     * @returns True if matched
+     */
+    match(str: string, consume?: boolean): boolean;
+    /**
+     * Expect a specific string at current position, throw if not found
+     * @param str - String to expect
+     * @throws Error if string not found
+     */
+    expect(str: string): void;
+    /**
+     * Get a substring of the input
+     * @param start - Start position
+     * @param end - End position
+     * @returns Substring
+     */
+    substring(start: number, end: number): string;
+    /**
+     * Reset tokenizer to beginning
+     */
+    reset(): void;
+    /**
+     * Tokenize the entire input into tokens
+     * @returns Array of tokens
+     */
+    tokenize(): Token[];
+    /**
+     * Get the next token from the input
+     * @returns Next token or null if EOF
+     */
+    nextToken(): Token | null;
+    /**
+     * Parse newline token
+     * @returns Newline token
+     */
+    parseNewlineToken(): Token;
+    /**
+     * Parse escaped text: [[text]
+     * Syntax: [[content] where [[ outputs literal [
+     * Everything between [[ and ] is treated as plain text
+     * Example: [[{$variable}] renders as literal [{$variable}]
+     * @returns Escaped token
+     */
+    parseEscapedToken(): Token;
+    /**
+     * Parse bracket directive [{...}]
+     * Determines type based on content:
+     * - [{$...}] → Variable
+     * - [{SET ...}] → Metadata
+     * - [{...}] → Plugin
+     * @returns Directive token
+     */
+    parseBracketDirective(): Token;
+    /**
+     * Parse variable: [{$varname}]
+     * Called after [{has been consumed
+     * @param pos - Position object
+     * @returns Variable token
+     */
+    parseVariableToken(pos: PositionInfo): Token;
+    /**
+     * Parse metadata: [{SET name=value}]
+     * Called after [{ has been consumed
+     * @param pos - Position object
+     * @returns Metadata token
+     */
+    parseMetadataToken(pos: PositionInfo): Token;
+    /**
+     * Parse plugin: [{PluginName param1=value1}]
+     * Called after [{ has been consumed
+     * @param pos - Position object
+     * @returns Plugin token
+     */
+    parsePluginToken(pos: PositionInfo): Token;
+    /**
+     * Parse wiki tag or link: [link], [link|text]
+     * @returns Wiki tag or link token
+     */
+    parseWikiTagToken(): Token;
+    /**
+     * Parse heading: !!!, !!, !
+     * @returns Heading token
+     */
+    parseHeadingToken(): Token;
+    /**
+     * Parse list item: *, #, **, ##, etc.
+     * @returns List item token
+     */
+    parseListItemToken(): Token;
+    /**
+     * Parse table cell: | cell
+     * @returns Table cell token
+     */
+    parseTableCellToken(): Token;
+    /**
+     * Parse bold: __text__
+     * @returns Bold token
+     */
+    parseBoldToken(): Token;
+    /**
+     * Parse italic: ''text''
+     * @returns Italic token
+     */
+    parseItalicToken(): Token;
+    /**
+     * Parse inline code: {{text}}
+     * @returns Code inline token
+     */
+    parseCodeInlineToken(): Token;
+    /**
+     * Parse code block: {{{code}}}
+     * @returns Code block token
+     */
+    parseCodeBlockToken(): Token;
+    /**
+     * Parse HTML comment: <!-- comment -->
+     * @returns Comment token
+     */
+    parseCommentToken(): Token;
+    /**
+     * Parse plain text until next special character
+     * @returns Text token
+     */
+    parseTextToken(): Token;
+}
+export { Tokenizer as default };