@bernierllc/markdown-parser 1.0.0

package/src/MarkdownParser.ts

@@ -0,0 +1,517 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { Logger } from '@bernierllc/logger';
+import { MarkdownParserConfig, ParseResult, ASTNode, Position } from './types';
+import { CacheManager } from './utils/cache';
+import { countNodes } from './utils/ast-utils';
+
+/**
+ * High-performance markdown parser with caching and plugin support
+ */
+export class MarkdownParser {
+  private config: Required<MarkdownParserConfig>;
+  private cacheManager: CacheManager | null;
+  private logger: Logger;
+
+  constructor(config?: MarkdownParserConfig) {
+    this.config = {
+      gfm: config?.gfm ?? true,
+      commonmark: config?.commonmark ?? true,
+      plugins: config?.plugins ?? [],
+      cache: {
+        enabled: config?.cache?.enabled ?? false,
+        maxSize: config?.cache?.maxSize ?? 1000,
+        ttl: config?.cache?.ttl ?? 3600,
+      },
+      logger: config?.logger ?? (console as unknown as Logger),
+    };
+
+    this.cacheManager = this.config.cache.enabled
+      ? new CacheManager(this.config.cache.maxSize, this.config.cache.ttl)
+      : null;
+
+    this.logger = this.config.logger as Logger;
+  }
+
+  /**
+   * Parse markdown string to AST
+   */
+  async parse(markdown: string): Promise<ParseResult> {
+    const startTime = Date.now();
+
+    // Check cache
+    if (this.cacheManager) {
+      const cacheKey = this.cacheManager.generateKey(markdown);
+      const cached = this.cacheManager.get(cacheKey);
+
+      if (cached) {
+        this.logger.debug('Markdown parse cache hit', { cacheKey });
+        return {
+          success: true,
+          ast: cached,
+          metadata: {
+            parseTime: Date.now() - startTime,
+            nodeCount: countNodes(cached),
+            cached: true,
+          },
+        };
+      }
+    }
+
+    try {
+      // Parse markdown to AST
+      let ast = await this.parseToAST(markdown);
+
+      // Apply plugins
+      for (const plugin of this.config.plugins) {
+        ast = plugin.transform(ast);
+      }
+
+      // Cache result
+      if (this.cacheManager) {
+        const cacheKey = this.cacheManager.generateKey(markdown);
+        this.cacheManager.set(cacheKey, ast);
+      }
+
+      const parseTime = Date.now() - startTime;
+      this.logger.debug('Markdown parsed successfully', {
+        parseTime,
+        nodeCount: countNodes(ast),
+      });
+
+      return {
+        success: true,
+        ast,
+        metadata: {
+          parseTime,
+          nodeCount: countNodes(ast),
+          cached: false,
+        },
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Unknown parse error');
+      this.logger.error('Markdown parse failed', error);
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+
+  /**
+   * Core parsing logic (CommonMark + GFM)
+   */
+  private async parseToAST(markdown: string): Promise<ASTNode> {
+    const lines = markdown.split('\n');
+    const root: ASTNode = { type: 'root', children: [] };
+
+    let lineNumber = 0;
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      lineNumber = i + 1;
+
+      // Skip empty lines
+      if (!line.trim()) {
+        i++;
+        continue;
+      }
+
+      // Heading
+      const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+      if (headingMatch) {
+        const level = headingMatch[1].length;
+        const text = headingMatch[2].trim();
+        root.children!.push({
+          type: 'heading',
+          attributes: { level },
+          children: this.parseInline(text),
+          position: this.createPosition(lineNumber, 0, line.length),
+        });
+        i++;
+        continue;
+      }
+
+      // Horizontal rule
+      if (line.match(/^(\*{3,}|-{3,}|_{3,})$/)) {
+        root.children!.push({
+          type: 'horizontalRule',
+          position: this.createPosition(lineNumber, 0, line.length),
+        });
+        i++;
+        continue;
+      }
+
+      // Code block (fenced)
+      if (line.match(/^```/)) {
+        const language = line.slice(3).trim();
+        const codeLines: string[] = [];
+        const startLine = lineNumber;
+        i++;
+
+        while (i < lines.length && !lines[i].match(/^```/)) {
+          codeLines.push(lines[i]);
+          i++;
+        }
+
+        root.children!.push({
+          type: 'codeBlock',
+          value: codeLines.join('\n'),
+          attributes: { language: language || 'plaintext' },
+          position: this.createPosition(startLine, 0, i - startLine),
+        });
+        i++; // Skip closing ```
+        continue;
+      }
+
+      // Blockquote
+      if (line.match(/^>\s/)) {
+        const quoteLines: string[] = [];
+        const startLine = lineNumber;
+
+        while (i < lines.length && lines[i].match(/^>\s/)) {
+          quoteLines.push(lines[i].replace(/^>\s/, ''));
+          i++;
+        }
+
+        const quoteContent = quoteLines.join('\n');
+        const quotedAst = await this.parseToAST(quoteContent);
+
+        root.children!.push({
+          type: 'blockquote',
+          children: quotedAst.children,
+          position: this.createPosition(startLine, 0, i - startLine),
+        });
+        continue;
+      }
+
+      // Task list (GFM) - Check BEFORE unordered list since "- [ ]" matches "- " pattern
+      if (this.config.gfm && line.match(/^[\s]*-\s\[\s*[ xX]\s*\]/)) {
+        const checked = line.includes('[x]') || line.includes('[X]');
+        const text = line.replace(/^[\s]*-\s\[\s*[ xX]\s*\]\s*/, '');
+        root.children!.push({
+          type: 'taskListItem',
+          attributes: { checked },
+          children: this.parseInline(text),
+          position: this.createPosition(lineNumber, 0, line.length),
+        });
+        i++;
+        continue;
+      }
+
+      // Unordered list
+      if (line.match(/^[\s]*[-*+]\s/)) {
+        const listItems: ASTNode[] = [];
+        const startLine = lineNumber;
+
+        while (i < lines.length && lines[i].match(/^[\s]*[-*+]\s/)) {
+          const itemText = lines[i].replace(/^[\s]*[-*+]\s/, '');
+          listItems.push({
+            type: 'listItem',
+            children: this.parseInline(itemText),
+          });
+          i++;
+        }
+
+        root.children!.push({
+          type: 'list',
+          attributes: { ordered: false },
+          children: listItems,
+          position: this.createPosition(startLine, 0, i - startLine),
+        });
+        continue;
+      }
+
+      // Ordered list
+      if (line.match(/^[\s]*\d+\.\s/)) {
+        const listItems: ASTNode[] = [];
+        const startLine = lineNumber;
+
+        while (i < lines.length && lines[i].match(/^[\s]*\d+\.\s/)) {
+          const itemText = lines[i].replace(/^[\s]*\d+\.\s/, '');
+          listItems.push({
+            type: 'listItem',
+            children: this.parseInline(itemText),
+          });
+          i++;
+        }
+
+        root.children!.push({
+          type: 'list',
+          attributes: { ordered: true },
+          children: listItems,
+          position: this.createPosition(startLine, 0, i - startLine),
+        });
+        continue;
+      }
+
+      // Table (GFM)
+      if (this.config.gfm && i + 1 < lines.length && lines[i + 1].match(/^\|?[\s]*:?-+:?[\s]*\|/)) {
+        const table = this.parseTable(lines, i);
+        root.children!.push(table.node);
+        i = table.nextIndex;
+        continue;
+      }
+
+      // Paragraph (default)
+      const paragraphLines: string[] = [line];
+      const startLine = lineNumber;
+      i++;
+
+      // Collect continuation lines
+      while (
+        i < lines.length &&
+        lines[i].trim() &&
+        !lines[i].match(/^(#{1,6}\s|```|>\s|[-*+]\s|\d+\.\s|\*{3,}|-{3,}|_{3,})/)
+      ) {
+        paragraphLines.push(lines[i]);
+        i++;
+      }
+
+      const paragraphText = paragraphLines.join(' ');
+      root.children!.push({
+        type: 'paragraph',
+        children: this.parseInline(paragraphText),
+        position: this.createPosition(startLine, 0, paragraphLines.length),
+      });
+    }
+
+    return root;
+  }
+
+  /**
+   * Parse inline formatting (bold, italic, code, links, images)
+   */
+  private parseInline(text: string): ASTNode[] {
+    const nodes: ASTNode[] = [];
+    let remaining = text;
+
+    while (remaining.length > 0) {
+      // Bold (**text** or __text__)
+      const boldMatch = remaining.match(/^(\*\*|__)(.+?)\1/);
+      if (boldMatch) {
+        nodes.push({
+          type: 'strong',
+          children: [{ type: 'text', value: boldMatch[2] }],
+        });
+        remaining = remaining.slice(boldMatch[0].length);
+        continue;
+      }
+
+      // Italic (*text* or _text_)
+      const italicMatch = remaining.match(/^(\*|_)(.+?)\1/);
+      if (italicMatch) {
+        nodes.push({
+          type: 'emphasis',
+          children: [{ type: 'text', value: italicMatch[2] }],
+        });
+        remaining = remaining.slice(italicMatch[0].length);
+        continue;
+      }
+
+      // Inline code (`code`)
+      const codeMatch = remaining.match(/^`([^`]+)`/);
+      if (codeMatch) {
+        nodes.push({
+          type: 'code',
+          value: codeMatch[1],
+        });
+        remaining = remaining.slice(codeMatch[0].length);
+        continue;
+      }
+
+      // Strikethrough (GFM: ~~text~~)
+      if (this.config.gfm) {
+        const strikeMatch = remaining.match(/^~~(.+?)~~/);
+        if (strikeMatch) {
+          nodes.push({
+            type: 'strikethrough',
+            children: [{ type: 'text', value: strikeMatch[1] }],
+          });
+          remaining = remaining.slice(strikeMatch[0].length);
+          continue;
+        }
+      }
+
+      // Image (![alt](url))
+      const imageMatch = remaining.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
+      if (imageMatch) {
+        nodes.push({
+          type: 'image',
+          attributes: {
+            alt: imageMatch[1],
+            src: imageMatch[2],
+          },
+        });
+        remaining = remaining.slice(imageMatch[0].length);
+        continue;
+      }
+
+      // Link ([text](url))
+      const linkMatch = remaining.match(/^\[([^\]]+)\]\(([^)]+)\)/);
+      if (linkMatch) {
+        nodes.push({
+          type: 'link',
+          attributes: {
+            href: linkMatch[2],
+          },
+          children: [{ type: 'text', value: linkMatch[1] }],
+        });
+        remaining = remaining.slice(linkMatch[0].length);
+        continue;
+      }
+
+      // Autolink (GFM: https://example.com)
+      if (this.config.gfm) {
+        const autolinkMatch = remaining.match(/^(https?:\/\/[^\s]+)/);
+        if (autolinkMatch) {
+          nodes.push({
+            type: 'autolink',
+            attributes: {
+              href: autolinkMatch[1],
+            },
+            children: [{ type: 'text', value: autolinkMatch[1] }],
+          });
+          remaining = remaining.slice(autolinkMatch[0].length);
+          continue;
+        }
+      }
+
+      // Line break (two spaces + newline or backslash + newline)
+      if (remaining.match(/^(  \n|\\\n)/)) {
+        nodes.push({ type: 'lineBreak' });
+        remaining = remaining.slice(remaining.match(/^(  \n|\\\n)/)![0].length);
+        continue;
+      }
+
+      // Plain text (consume until next special character or URL)
+      const textMatch = remaining.match(/^((?:(?!https?:\/\/)[^*_`~!\[\n])+)/);
+      if (textMatch) {
+        nodes.push({
+          type: 'text',
+          value: textMatch[1],
+        });
+        remaining = remaining.slice(textMatch[1].length);
+        continue;
+      }
+
+      // Single character fallback
+      nodes.push({
+        type: 'text',
+        value: remaining[0],
+      });
+      remaining = remaining.slice(1);
+    }
+
+    return nodes;
+  }
+
+  /**
+   * Parse GFM table
+   */
+  private parseTable(lines: string[], startIndex: number): { node: ASTNode; nextIndex: number } {
+    const headerLine = lines[startIndex];
+    const separatorLine = lines[startIndex + 1];
+
+    // Parse header
+    const headerCells = headerLine.split('|').filter((cell) => cell.trim());
+    const headerRow: ASTNode = {
+      type: 'tableRow',
+      children: headerCells.map((cell) => ({
+        type: 'tableCell',
+        attributes: { header: true },
+        children: this.parseInline(cell.trim()),
+      })),
+    };
+
+    // Parse alignment from separator
+    const alignments = separatorLine
+      .split('|')
+      .filter((cell) => cell.trim())
+      .map((cell) => {
+        const trimmed = cell.trim();
+        if (trimmed.startsWith(':') && trimmed.endsWith(':')) return 'center';
+        if (trimmed.endsWith(':')) return 'right';
+        if (trimmed.startsWith(':')) return 'left';
+        return 'left';
+      });
+
+    // Parse body rows
+    const bodyRows: ASTNode[] = [];
+    let i = startIndex + 2;
+
+    while (i < lines.length && lines[i].includes('|')) {
+      const cells = lines[i].split('|').filter((cell) => cell.trim());
+      bodyRows.push({
+        type: 'tableRow',
+        children: cells.map((cell, index) => ({
+          type: 'tableCell',
+          attributes: {
+            header: false,
+            align: alignments[index] || 'left',
+          },
+          children: this.parseInline(cell.trim()),
+        })),
+      });
+      i++;
+    }
+
+    return {
+      node: {
+        type: 'table',
+        children: [headerRow, ...bodyRows],
+        position: this.createPosition(startIndex + 1, 0, i - startIndex),
+      },
+      nextIndex: i,
+    };
+  }
+
+  /**
+   * Create position information
+   */
+  private createPosition(line: number, column: number, length: number): Position {
+    return {
+      start: { line, column, offset: 0 },
+      end: { line: line + length - 1, column: column + length, offset: 0 },
+    };
+  }
+
+  /**
+   * Clear the parse cache
+   */
+  clearCache(): void {
+    if (this.cacheManager) {
+      this.cacheManager.clear();
+      this.logger.debug('Markdown parse cache cleared');
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): { size: number; enabled: boolean } {
+    return {
+      size: this.cacheManager?.size() ?? 0,
+      enabled: this.config.cache.enabled,
+    };
+  }
+
+  /**
+   * Prune expired cache entries
+   */
+  pruneCache(): number {
+    if (this.cacheManager) {
+      const removed = this.cacheManager.prune();
+      this.logger.debug('Pruned expired cache entries', { removed });
+      return removed;
+    }
+    return 0;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+export { MarkdownParser } from './MarkdownParser';
+export * from './types';
+export * from './plugins';
+export * from './utils/ast-utils';
+export { CacheManager } from './utils/cache';

package/src/plugins/commonmark.ts

@@ -0,0 +1,23 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { MarkdownPlugin, ASTNode } from '../types';
+
+/**
+ * CommonMark specification plugin
+ */
+export const commonmarkPlugin: MarkdownPlugin = {
+  name: 'commonmark',
+  version: '1.0.0',
+  transform: (ast: ASTNode): ASTNode => {
+    // This is a placeholder - CommonMark features are built into the main parser
+    // when commonmark config is enabled. This plugin can be used for additional
+    // post-processing transformations specific to CommonMark.
+    return ast;
+  },
+};

package/src/plugins/gfm.ts

@@ -0,0 +1,23 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { MarkdownPlugin, ASTNode } from '../types';
+
+/**
+ * GitHub-Flavored Markdown extensions plugin
+ */
+export const gfmPlugin: MarkdownPlugin = {
+  name: 'gfm',
+  version: '1.0.0',
+  transform: (ast: ASTNode): ASTNode => {
+    // This is a placeholder - GFM features are built into the main parser
+    // when gfm config is enabled. This plugin can be used for additional
+    // post-processing transformations specific to GFM.
+    return ast;
+  },
+};

package/src/plugins/index.ts

@@ -0,0 +1,10 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+export * from './gfm';
+export * from './commonmark';

package/src/types.ts

@@ -0,0 +1,114 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { Logger } from '@bernierllc/logger';
+
+/**
+ * Markdown Parser Configuration
+ */
+export interface MarkdownParserConfig {
+  /** Enable GitHub-Flavored Markdown extensions */
+  gfm?: boolean;
+
+  /** Enable CommonMark strict mode */
+  commonmark?: boolean;
+
+  /** Custom plugins to apply */
+  plugins?: MarkdownPlugin[];
+
+  /** Enable caching of parsed AST */
+  cache?: {
+    enabled: boolean;
+    maxSize?: number; // Maximum cache entries
+    ttl?: number; // Time to live in seconds
+  };
+
+  /** Logger instance */
+  logger?: Logger;
+}
+
+/**
+ * Position information in source document
+ */
+export interface Position {
+  start: { line: number; column: number; offset: number };
+  end: { line: number; column: number; offset: number };
+}
+
+/**
+ * Markdown Abstract Syntax Tree Node
+ */
+export interface ASTNode {
+  type: NodeType;
+  value?: string;
+  children?: ASTNode[];
+  attributes?: Record<string, unknown>;
+  position?: Position;
+}
+
+/**
+ * Node types supported by the parser
+ */
+export type NodeType =
+  | 'root'
+  | 'heading'
+  | 'paragraph'
+  | 'text'
+  | 'emphasis'
+  | 'strong'
+  | 'link'
+  | 'image'
+  | 'code'
+  | 'codeBlock'
+  | 'blockquote'
+  | 'list'
+  | 'listItem'
+  | 'table'
+  | 'tableRow'
+  | 'tableCell'
+  | 'html'
+  | 'horizontalRule'
+  | 'lineBreak'
+  // GFM extensions
+  | 'strikethrough'
+  | 'taskList'
+  | 'taskListItem'
+  | 'autolink'
+  | 'footnote'
+  | 'footnoteReference';
+
+/**
+ * Parse result with metadata
+ */
+export interface ParseResult {
+  success: boolean;
+  ast?: ASTNode;
+  error?: string;
+  metadata?: {
+    parseTime: number; // Milliseconds
+    nodeCount: number;
+    cached: boolean;
+  };
+}
+
+/**
+ * Plugin interface for custom extensions
+ */
+export interface MarkdownPlugin {
+  name: string;
+  version: string;
+  transform: (ast: ASTNode) => ASTNode;
+}
+
+/**
+ * Cache entry structure
+ */
+export interface CacheEntry {
+  ast: ASTNode;
+  timestamp: number;
+}