@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/parsers/LinkParser.d.ts

@@ -0,0 +1,457 @@
+/**
+ * LinkParser - Centralized link parsing for ngdpbase
+ *
+ * Inspired by JSPWiki's link parsing implementation, this class provides
+ * a centralized, flexible, and maintainable approach to parsing various
+ * types of links in wiki content.
+ *
+ * Supports the following link formats:
+ * - [PageName] - Simple internal wiki links
+ * - [DisplayText|Target] - Links with custom display text
+ * - [DisplayText|Target|attributes] - Links with custom attributes
+ *
+ * Features:
+ * - Centralized parsing logic to reduce brittle code
+ * - Security-focused attribute validation
+ * - Support for internal wiki links, external links, and InterWiki links
+ * - Extensible architecture for future link types
+ * - Comprehensive error handling and validation
+ *
+ * @class LinkParser
+ *
+ * @property {LinkParserOptions} options - Parser configuration options
+ * @property {Set<string>} pageNames - Cache of available page names
+ * @property {PageNameMatcher|null} pageNameMatcher - Page name matching utility
+ * @property {Map<string, InterWikiSiteConfig>} interWikiSites - InterWiki site configurations
+ * @property {RegExp} linkPattern - Regular expression for link matching
+ *
+ * @see {@link PageNameMatcher} for fuzzy page matching
+ * @see {@link RenderingManager} for usage
+ *
+ * @example
+ * const linkParser = new LinkParser();
+ * linkParser.setPageNames(['Main', 'Help', 'About']);
+ * const html = linkParser.parseLinks('[Main] and [Help|Documentation]');
+ *
+ * @author ngdpbase
+ * @version 1.0.0
+ * @see https://github.com/jwilleke/ngdpbase/issues/75
+ */
+import PageNameMatcher from '../utils/PageNameMatcher.js';
+/**
+ * A bracket that is not escaped: preceded by an even number of backslashes,
+ * none included (#1480). CommonMark's `\[` is a literal `[`, so it is not
+ * a link, a variable or a plugin, for the renderer, the link graph or the
+ * rename rewriter alike. `\\[` — an escaped backslash — still opens one.
+ * A lookbehind, so it consumes nothing and match offsets are unchanged.
+ */
+export declare const UNESCAPED_BRACKET = "(?<=(?:^|[^\\\\])(?:\\\\\\\\)*)";
+/**
+ * Not a task-list checkbox (#1476, operator: task lists are supported): a
+ * `[ ]`, `[x]` or `[X]` right after a list marker (`-`, `*`, `+`, `1.`,
+ * `1)`) at the start of a line, followed by a space. GitHub's task lists —
+ * markdown-it-task-lists renders them — and never a link to a page named
+ * "x". A lookahead, so it consumes nothing. Needs the `m` flag for `^`, so it
+ * spells the line start as `(?:^|\n)` instead.
+ */
+export declare const NOT_TASK_MARKER = "(?!(?<=(?:^|\\n)[ \\t]*(?:[-*+]|\\d+[.)])[ \\t]+)\\[[ xX]\\][ \\t])";
+/**
+ * Not a GitHub alert marker (#1493): `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`,
+ * `[!WARNING]` or `[!CAUTION]` alone on a blockquote's line, which the page
+ * profile renders as an alert box — never a link to a page named "!NOTE". A
+ * lookahead, so it consumes nothing; spells the line start as `(?:^|\n)`.
+ */
+export declare const NOT_ALERT_MARKER = "(?!(?<=(?:^|\\n)[ \\t]*(?:>[ \\t]?)+[ \\t]*)\\[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\\][ \\t]*(?:\\n|$))";
+/**
+ * The wiki link syntax, as a source string: `[text]`, `[text|target]` or
+ * `[text|target|attributes]`. The trailing `(?!\()` skips `[text](url)` —
+ * that is a markdown link, and its bracket text is not a wiki link target.
+ *
+ * Exported as a source string rather than a RegExp because the compiled form
+ * needs the `g` flag, and a shared global RegExp carries `lastIndex` between
+ * callers. Use {@link wikiLinkPattern} to get a fresh one.
+ *
+ * Shared so that anything reasoning about link targets — rendering, the
+ * link graph, the rename rewriter (#1094) — agrees with the parser about what
+ * a link *is*. A second copy of this pattern is a second answer waiting to
+ * drift from this one.
+ */
+export declare const WIKI_LINK_PATTERN_SOURCE = "(?<=(?:^|[^\\\\])(?:\\\\\\\\)*)(?!(?<=(?:^|\\n)[ \\t]*(?:[-*+]|\\d+[.)])[ \\t]+)\\[[ xX]\\][ \\t])(?!(?<=(?:^|\\n)[ \\t]*(?:>[ \\t]?)+[ \\t]*)\\[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\\][ \\t]*(?:\\n|$))\\[([^|\\]]+)(?:\\|([^|\\]]+))?(?:\\|([^\\]]+))?\\](?!\\()";
+/** A reference label as CommonMark matches it: case-insensitive, inner whitespace collapsed. */
+export declare function referenceLabel(raw: string): string;
+/**
+ * Where the page's reference links are (#1491): each definition's `[label]`,
+ * and each use of a defined label — `[text][label]` (no space between),
+ * `[label][]` and `[label]`. markdown-it renders them and hides the
+ * definitions; every other `[…]` stays a wiki link. A page that defines
+ * nothing has no ranges, so it renders exactly as before.
+ */
+export declare function referenceLinkRanges(content: string): Array<[number, number]>;
+/**
+ * The link text of every Markdown link whose text holds brackets of its own
+ * (#1708): `[a [b] c](url)`. CommonMark allows balanced brackets there, and
+ * markdown-it renders them, but the wiki link syntax took the inner `[b`
+ * first and split the link. Each range runs from the opening `[` to its
+ * matching `]`, which is followed by `(`.
+ *
+ * Every reader of wiki links skips a match that starts inside one of these
+ * ranges, so the renderer, the link graph and the rename rewriter agree that
+ * the brackets are link text. An escaped bracket (#1480) is not counted, and
+ * link text that starts with NCM's `[[` escape is left to it. One
+ * pass with a stack, so a long page costs no more than its length.
+ *
+ * Reference links (#1491) are Markdown link text too: `[text][label]`,
+ * `[label][]` and `[label]` when the page defines `label`, and the
+ * definition line's `[label]` itself. See {@link referenceLinkRanges}.
+ */
+export declare function markdownLinkTextRanges(content: string): Array<[number, number]>;
+/** Whether `offset` falls inside one of `ranges`, its opening bracket included. */
+export declare function insideMarkdownLinkText(ranges: ReadonlyArray<[number, number]>, offset: number): boolean;
+/** A fresh global RegExp for the wiki link syntax. Never share one. */
+export declare function wikiLinkPattern(): RegExp;
+/**
+ * Target shapes that are NOT internal wiki page names. Non-global, so these
+ * are stateless and safe to share.
+ */
+export declare const LINK_URL_PATTERNS: {
+    readonly external: RegExp;
+    readonly email: RegExp;
+    readonly anchor: RegExp;
+    readonly absolute: RegExp;
+};
+/** `Site:path` — an InterWiki reference, not a local page. */
+export declare const INTERWIKI_PATTERN: RegExp;
+/**
+ * Default CSS classes for different link types
+ */
+export interface DefaultClasses {
+    /** Class for internal wiki links */
+    internal: string;
+    /** Class for external links */
+    external: string;
+    /** Class for InterWiki links */
+    interwiki: string;
+    /** Class for red links (non-existent pages) */
+    redlink: string;
+}
+/**
+ * URL pattern definitions for link type detection
+ */
+export interface UrlPatterns {
+    /** Pattern for external HTTP/HTTPS URLs */
+    external: RegExp;
+    /** Pattern for email links */
+    email: RegExp;
+    /** Pattern for anchor links */
+    anchor: RegExp;
+    /** Pattern for absolute paths */
+    absolute: RegExp;
+}
+/**
+ * Security configuration options
+ */
+export interface SecurityOptions {
+    /** Validate URLs for safety */
+    validateUrls: boolean;
+    /** Sanitize HTML attributes */
+    sanitizeAttributes: boolean;
+    /** Prevent XSS attacks */
+    preventXSS: boolean;
+}
+/**
+ * LinkParser configuration options
+ */
+export interface LinkParserOptions {
+    /** Allowed HTML attributes for links */
+    allowedAttributes: string[];
+    /** Default CSS classes for link types */
+    defaultClasses: DefaultClasses;
+    /** URL patterns for validation */
+    urlPatterns: UrlPatterns;
+    /** InterWiki site pattern */
+    interWikiPattern: RegExp;
+    /** Security settings */
+    security: SecurityOptions;
+}
+/**
+ * InterWiki site configuration
+ */
+export interface InterWikiSiteConfig {
+    /** URL template with %s placeholder for page name */
+    url: string;
+    /** Description of the InterWiki site */
+    description?: string;
+    /** Whether to open links in new window */
+    openInNewWindow?: boolean;
+}
+/**
+ * HTML attributes for links
+ */
+export interface LinkAttributes {
+    [key: string]: string;
+}
+/**
+ * Parsing context for link generation
+ */
+export interface ParserContext {
+    /** Current page name */
+    pageName?: string;
+    /** Additional context data */
+    [key: string]: unknown;
+}
+/**
+ * Parser statistics
+ */
+export interface ParserStats {
+    /** Number of page names in cache */
+    pageNamesCount: number;
+    /** Number of InterWiki sites configured */
+    interWikiSitesCount: number;
+    /** Number of allowed attributes */
+    allowedAttributes: number;
+    /** Whether security features are enabled */
+    securityEnabled: boolean;
+}
+/**
+ * Link data structure for Link constructor
+ */
+export interface LinkData {
+    /** Original text from content */
+    originalText?: string;
+    /** Display text for the link */
+    text?: string;
+    /** Target page or URL */
+    target?: string | null;
+    /** Raw attributes string */
+    attributesString?: string | null;
+    /** Parsed attributes object */
+    attributes?: LinkAttributes;
+    /** Start index in content */
+    startIndex?: number;
+    /** End index in content */
+    endIndex?: number;
+}
+/**
+ * Link information object returned by toObject()
+ */
+export interface LinkInfo {
+    /** Original text from content */
+    originalText: string;
+    /** Display text for the link */
+    text: string;
+    /** Target page or URL */
+    target: string | null;
+    /** Parsed attributes */
+    attributes: LinkAttributes;
+    /** Whether this is a simple link */
+    isSimple: boolean;
+    /** Whether the link has attributes */
+    hasAttributes: boolean;
+}
+/**
+ * Link type enumeration
+ */
+export type LinkType = 'internal' | 'external' | 'interwiki' | 'email' | 'anchor';
+/**
+ * Main LinkParser class
+ */
+export declare class LinkParser {
+    /** Parser configuration options */
+    options: LinkParserOptions;
+    /** Cache of available page names */
+    pageNames: Set<string>;
+    /** Page name matcher for fuzzy matching */
+    pageNameMatcher: PageNameMatcher | null;
+    /** InterWiki sites configuration */
+    interWikiSites: Map<string, InterWikiSiteConfig>;
+    /** Link pattern regex */
+    linkPattern: RegExp;
+    /**
+     * Create a new LinkParser instance
+     *
+     * @constructor
+     * @param {Partial<LinkParserOptions>} [options={}] - Configuration options
+     */
+    constructor(options?: Partial<LinkParserOptions>);
+    /**
+     * Set the list of existing wiki page names for link validation
+     * @param {string[]} pageNames - Array of page names
+     * @param {boolean} matchEnglishPlurals - Enable plural matching (default: true)
+     * @param {boolean} matchCamelCase - Enable CamelCase matching (default: false)
+     */
+    setPageNames(pageNames: string[], matchEnglishPlurals?: boolean, matchCamelCase?: boolean): void;
+    /**
+     * Add a page name to the known pages
+     * @param {string} pageName - Page name to add
+     */
+    addPageName(pageName: string): void;
+    /**
+     * Set InterWiki sites configuration
+     * @param {Map<string, InterWikiSiteConfig> | Record<string, InterWikiSiteConfig>} sites - InterWiki sites configuration
+     */
+    setInterWikiSites(sites: Map<string, InterWikiSiteConfig> | Record<string, InterWikiSiteConfig>): void;
+    /**
+     * Parse all links in the given content
+     * @param {string} content - Content containing wiki links
+     * @param {ParserContext} context - Parsing context (pageName, etc.)
+     * @returns {string} Content with links converted to HTML
+     */
+    parseLinks(content: string, context?: ParserContext): string;
+    /**
+     * Find all links in the content
+     * @param {string} content - Content to search
+     * @returns {Link[]} Array of Link objects
+     */
+    findLinks(content: string): Link[];
+    /**
+     * Parse link attributes from attribute string
+     * @param {string} attributeString - String containing attributes
+     * @returns {LinkAttributes} Parsed attributes object
+     */
+    parseAttributes(attributeString: string): LinkAttributes;
+    /**
+     * Generate HTML for a link
+     * @param {Link} link - Link object to process
+     * @param {ParserContext} context - Parsing context
+     * @returns {string} HTML link
+     */
+    generateLinkHtml(link: Link, context: ParserContext): string;
+    /**
+     * Determine the type of link
+     * @param {Link} link - Link object
+     * @returns {LinkType} Link type
+     */
+    determineLinkType(link: Link): LinkType;
+    /**
+     * Generate HTML for internal wiki links
+     * @param {Link} link - Link object
+     * @param {ParserContext} _context - Parsing context (unused)
+     * @returns {string} HTML link
+     */
+    generateInternalLink(link: Link, _context: ParserContext): string;
+    /**
+     * Generate HTML for external links
+     * @param {Link} link - Link object
+     * @param {ParserContext} _context - Parsing context (unused)
+     * @returns {string} HTML link
+     */
+    generateExternalLink(link: Link, _context: ParserContext): string;
+    /**
+     * Generate HTML for InterWiki links
+     * @param {Link} link - Link object
+     * @param {ParserContext} _context - Parsing context (unused)
+     * @returns {string} HTML link
+     */
+    generateInterWikiLink(link: Link, _context: ParserContext): string;
+    /**
+     * Generate HTML for email links
+     * @param {Link} link - Link object
+     * @param {ParserContext} _context - Parsing context (unused)
+     * @returns {string} HTML link
+     */
+    generateEmailLink(link: Link, _context: ParserContext): string;
+    /**
+     * Generate HTML for anchor links
+     * @param {Link} link - Link object
+     * @param {ParserContext} _context - Parsing context (unused)
+     * @returns {string} HTML link
+     */
+    generateAnchorLink(link: Link, _context: ParserContext): string;
+    /**
+     * Build HTML attribute string
+     * @param {LinkAttributes} customAttributes - Custom attributes from link
+     * @param {Record<string, string | undefined>} defaultAttributes - Default attributes
+     * @returns {string} HTML attribute string
+     */
+    buildAttributeString(customAttributes?: LinkAttributes, defaultAttributes?: Record<string, string | undefined>): string;
+    /**
+     * Validate URL safety
+     * @param {string} url - URL to validate
+     * @returns {boolean} True if URL is safe
+     */
+    isUrlSafe(url: string): boolean;
+    /**
+     * Sanitize style attribute value
+     * @param {string} style - Style value
+     * @returns {string} Sanitized style
+     */
+    sanitizeStyleAttribute(style: string): string;
+    /**
+     * Sanitize attribute value to prevent XSS
+     * @param {string} value - Attribute value
+     * @returns {string} Sanitized value
+     */
+    sanitizeAttributeValue(value: string): string;
+    /**
+     * Escape HTML characters
+     * @param {string} text - Text to escape
+     * @returns {string} Escaped text
+     */
+    escapeHtml(text: string): string;
+    /**
+     * Get parser statistics
+     * @returns {ParserStats} Parser statistics
+     */
+    getStats(): ParserStats;
+}
+/**
+ * Link class representing a parsed link
+ */
+export declare class Link {
+    /** Original text from content */
+    originalText: string;
+    /** Display text for the link */
+    text: string;
+    /** Target page or URL */
+    target: string | null;
+    /** Raw attributes string */
+    attributesString: string | null;
+    /** Parsed attributes object */
+    attributes: LinkAttributes;
+    /** Start index in content */
+    startIndex: number;
+    /** End index in content */
+    endIndex: number;
+    /**
+     * Create a new Link instance
+     * @param {LinkData} data - Link data
+     */
+    constructor(data?: LinkData);
+    /**
+     * Check if this is a simple link (no target specified)
+     * @returns {boolean} True if simple link
+     */
+    isSimple(): boolean;
+    /**
+     * Get the effective target (target or text if no target)
+     * @returns {string} Effective target
+     */
+    getEffectiveTarget(): string;
+    /**
+     * Check if link has attributes
+     * @returns {boolean} True if has attributes
+     */
+    hasAttributes(): boolean;
+    /**
+     * Get attribute value by name
+     * @param {string} name - Attribute name
+     * @returns {string | undefined} Attribute value
+     */
+    getAttribute(name: string): string | undefined;
+    /**
+     * Set attribute value
+     * @param {string} name - Attribute name
+     * @param {string} value - Attribute value
+     */
+    setAttribute(name: string, value: string): void;
+    /**
+     * Get link information as object
+     * @returns {LinkInfo} Link information
+     */
+    toObject(): LinkInfo;
+}
+declare const _default: {
+    LinkParser: typeof LinkParser;
+    Link: typeof Link;
+};
+export default _default;