@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/parsers/context/ParseContext.d.ts

@@ -0,0 +1,314 @@
+/**
+ * ParseContext - Context object for markup parsing operations
+ *
+ * Provides access to page context, user information, engine managers,
+ * and parsing state throughout the processing pipeline.
+ *
+ * Related Issue: #55 - Core Infrastructure and Phase System
+ */
+import CacheDependencies from '../../cache/CacheDependencies.js';
+import { type PermissionSubject } from '../../managers/UserManager.js';
+/**
+ * User context interface
+ */
+export interface UserContext extends PermissionSubject {
+    /** Legacy alias some plugin code reads. */
+    userName?: string;
+    permissions?: string[];
+    /** A test account (#1805), from the account record; plugins enforce their own rules from it. */
+    isTest?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Request information
+ */
+export interface RequestInfo {
+    method?: string;
+    path?: string;
+    ip?: string;
+    userAgent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Minimal page frontmatter for parse context (uuid is the key consumer)
+ */
+export interface PageFrontmatter {
+    uuid?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+/**
+ * Page context interface
+ */
+export interface PageContext {
+    pageName?: string;
+    userName?: string;
+    userContext?: UserContext | null;
+    requestInfo?: RequestInfo | null;
+    pageMetadata?: PageFrontmatter | null;
+    [key: string]: unknown;
+}
+/**
+ * WikiEngine minimal interface (until WikiEngine.ts is fully typed)
+ * TODO: Replace with proper WikiEngine import once converted
+ */
+export interface WikiEngine {
+    getManager<T = unknown>(name: string): T | undefined;
+}
+/**
+ * Minimal WikiContext interface for the parser side (#629).
+ *
+ * ParseContext holds a reference to its parent WikiContext so user/page-data
+ * fields don't have to be copied. We define a structural interface here rather
+ * than importing the full WikiContext class to avoid coupling the parser
+ * package to context internals (and to side-step circular imports).
+ *
+ * Only the fields/methods ParseContext needs to delegate are listed.
+ */
+export interface WikiContextLike {
+    readonly engine: WikiEngine;
+    readonly pageName: string | null;
+    readonly userContext: UserContext | null;
+    readonly pageMetadata: PageFrontmatter | null;
+    hasPermission(action: string): Promise<boolean>;
+    canAccess(action: string): Promise<boolean>;
+    /** The non-recording affordance for display gates (#1668) — see WikiContext.mayShow. */
+    mayShow(action: string): Promise<boolean>;
+    getPrincipals(): string[];
+}
+/**
+ * Nested context structure (from WikiContext.toParseOptions())
+ */
+export interface NestedContextOptions {
+    pageContext: PageContext;
+    engine?: WikiEngine;
+    /**
+     * #629: optional reference to the parent WikiContext. When provided,
+     * ParseContext getters delegate user/page-data lookups to it instead of
+     * the constructor-time snapshot in `pageContext`. Lets the WikiContext
+     * stay the single source of truth across the parse run.
+     */
+    wikiContext?: WikiContextLike;
+}
+/**
+ * Direct context structure (legacy or alternative calling pattern)
+ */
+export type DirectContextOptions = PageContext;
+/**
+ * Combined context options
+ */
+export type ParseContextOptions = NestedContextOptions | DirectContextOptions;
+/**
+ * Context summary for logging
+ */
+export interface ContextSummary {
+    pageName: string;
+    userName: string;
+    authenticated: boolean;
+    roles: string[];
+    contentLength: number;
+    variableCount: number;
+    handlerResultCount: number;
+    processingTime: number;
+    phaseCount: number;
+}
+/**
+ * Error context for debugging
+ */
+export interface ParseErrorContext {
+    error: string;
+    phase: string;
+    pageName: string;
+    userName: string;
+    processingTime: number;
+    contentLength: number;
+    timestamp: string;
+}
+/**
+ * Exported user context for caching
+ */
+export interface ExportedUserContext {
+    isAuthenticated: boolean;
+    roles: string[];
+    permissions: string[];
+}
+/**
+ * Cached context data
+ */
+export interface CachedContextData {
+    pageName: string;
+    userName: string;
+    userContext: ExportedUserContext | null;
+    variables: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * ParseContext - Context object for markup parsing operations
+ *
+ * #629 Pass 2: holds a non-nullable reference to a WikiContextLike. For HTTP
+ * requests this is the actual WikiContext (passed through toParseOptions);
+ * for tests / direct construction it's a synthesized stub from the supplied
+ * PageContext. Consumers should always read user/page-data via
+ * `parseContext.wikiContext.X` — the duplicating getters from Pass 1
+ * (pageName / userContext / pageMetadata) have been removed.
+ *
+ * Helpers that derive (not duplicate) from wikiContext are still here:
+ * userName, isAuthenticated, getUserRoles.
+ */
+declare class ParseContext {
+    readonly originalContent: string;
+    readonly pageContext: PageContext;
+    readonly engine: WikiEngine;
+    /**
+     * Reference to the parent WikiContext (#629). Always non-null after
+     * construction — for callers without a real WikiContext, a stub is
+     * synthesized from the PageContext snapshot.
+     */
+    readonly wikiContext: WikiContextLike;
+    /**
+     * Request info. Built from request headers by toParseOptions; not
+     * duplicated from wikiContext (the stub lacks the headers anyway).
+     * Static after construction.
+     */
+    readonly requestInfo: RequestInfo | null;
+    /**
+     * The private titles this reader can see in the page owner's stores, by
+     * store id (#1457) — what a `[store/Title]` link on a PRIVATE page is
+     * resolved against, so the owner of a page that is not there gets a red
+     * link to its editor.
+     *
+     * `null` when the question does not arise: a public page, whose HTML is
+     * cached and shared by role and so has one appearance for everyone, or a
+     * page with no such link in it. A store that is ABSENT from the map is one
+     * this reader cannot open — not one without the page.
+     *
+     * Resolved once per parse by MarkupParser, never per link.
+     */
+    privateLinkTitles: Map<string, Set<string>> | null;
+    /**
+     * Hand finished HTML from a syntax handler to MarkupParser; write the
+     * returned placeholder into the content instead (#1623). The HTML is merged
+     * after markdown-it, so it is not mistaken for HTML the author typed and
+     * held to the author HTML policy. `null` outside a MarkupParser parse.
+     */
+    protectHtml: ((html: string) => string) | null;
+    protectedBlocks: unknown[];
+    syntaxTokens: unknown[];
+    variables: Map<string, unknown>;
+    handlerResults: Map<string, unknown>;
+    metadata: Record<string, unknown>;
+    /**
+     * #1751: the page cache's record of what this render reads. Plugins reach it
+     * through `context.dependsOn(topic)` (PluginManager.execute). Null when the
+     * page is not being cached.
+     */
+    readonly cacheDependencies: CacheDependencies | null;
+    private startTime;
+    private phaseTimings;
+    constructor(content: string, context: ParseContextOptions, engine: WikiEngine);
+    /**
+     * Caller's username — derivation helper over `wikiContext.userContext`.
+     * Returns 'anonymous' when no userContext is bound.
+     */
+    get userName(): string;
+    /**
+     * Get manager instance from engine
+     * @param managerName - Name of manager to retrieve
+     * @returns Manager instance or null
+     */
+    getManager(managerName: string): unknown;
+    /**
+     * Check if user is authenticated — derivation helper over `wikiContext.userContext`.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get user roles — derivation helper over `wikiContext.userContext`.
+     */
+    getUserRoles(): string[];
+    /**
+     * Set variable value
+     * @param name - Variable name
+     * @param value - Variable value
+     */
+    setVariable(name: string, value: unknown): void;
+    /**
+     * Get variable value
+     * @param name - Variable name
+     * @param defaultValue - Default value if not found
+     * @returns Variable value
+     */
+    getVariable(name: string, defaultValue?: unknown): unknown;
+    /**
+     * Store handler result
+     * @param handlerId - Handler identifier
+     * @param result - Handler result
+     */
+    setHandlerResult(handlerId: string, result: unknown): void;
+    /**
+     * Get handler result
+     * @param handlerId - Handler identifier
+     * @returns Handler result or null
+     */
+    getHandlerResult(handlerId: string): unknown;
+    /**
+     * Set metadata value
+     * @param key - Metadata key
+     * @param value - Metadata value
+     */
+    setMetadata(key: string, value: unknown): void;
+    /**
+     * Get metadata value
+     * @param key - Metadata key
+     * @param defaultValue - Default value if not found
+     * @returns Metadata value
+     */
+    getMetadata(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Record phase timing
+     * @param phaseName - Name of phase
+     * @param duration - Duration in milliseconds
+     */
+    recordPhaseTiming(phaseName: string, duration: number): void;
+    /**
+     * Get phase timing
+     * @param phaseName - Name of phase
+     * @returns Duration in milliseconds or 0
+     */
+    getPhaseTiming(phaseName: string): number;
+    /**
+     * Get total processing time
+     * @returns Total time in milliseconds
+     */
+    getTotalTime(): number;
+    /**
+     * Clone context for sub-processing
+     * @param overrides - Properties to override
+     * @returns New context instance
+     */
+    clone(overrides?: Partial<PageContext>): ParseContext;
+    /**
+     * Create error context for debugging
+     * @param error - Error that occurred
+     * @param phase - Phase where error occurred
+     * @returns Error context
+     */
+    createErrorContext(error: Error, phase: string): ParseErrorContext;
+    /**
+     * Get context summary for logging
+     * @returns Context summary
+     */
+    getSummary(): ContextSummary;
+    /**
+     * Export context data for caching
+     * @returns Serializable context data
+     */
+    exportForCache(): CachedContextData;
+    /**
+     * Import context data from cache
+     * @param data - Cached context data
+     */
+    importFromCache(data: CachedContextData): void;
+}
+export { ParseContext };
+export default ParseContext;

package/lib/src/parsers/data/emoji-map.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Emoji shortcode map for MarkupParser Step 0.7 (Issue #512)
+ *
+ * Keys are shortcode names (without colons).
+ * Values are Unicode emoji characters — no image assets needed.
+ * Shortcode names follow the de-facto standard used by GitHub, Slack, and Twemoji.
+ *
+ * To add emojis: extend EMOJI_MAP here AND add matching entries to
+ * EMOJI_CLIENT_DATA in public/js/emoji-autocomplete.js (client-side picker).
+ */
+export declare const EMOJI_MAP: Readonly<Record<string, string>>;
+/** Regex matching :shortcode: patterns — used by convertEmojiShortcodes */
+export declare const EMOJI_SHORTCODE_REGEX: RegExp;
+/**
+ * Replace all :shortcode: occurrences in text with their Unicode emoji.
+ * Unknown shortcodes are left unchanged.
+ */
+export declare function convertEmojiShortcodes(text: string): string;

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

@@ -0,0 +1,210 @@
+import { TokenType } from './Tokenizer.js';
+import WikiDocument from './WikiDocument.js';
+/**
+ * DOMBuilder - Converts tokens into a WikiDocument DOM tree
+ *
+ * ============================================================================
+ * ARCHITECTURE NOTE (Phase 4, Issue #118):
+ * ============================================================================
+ *
+ * **This DOMBuilder is a REFERENCE IMPLEMENTATION and is NOT actively used
+ * in the current rendering pipeline.**
+ *
+ * This builder converts tokens from the Tokenizer into a WikiDocument DOM.
+ * It was part of the Phase 0 tokenization-based parsing approach, which has
+ * been superseded by the extraction-based approach in Phases 1-3.
+ *
+ * CURRENT ACTIVE APPROACH:
+ * ------------------------
+ * DOM nodes are now created directly from extracted elements using:
+ * - DOMVariableHandler.createNodeFromExtract()
+ * - DOMPluginHandler.createNodeFromExtract()
+ * - DOMLinkHandler.createNodeFromExtract()
+ * - MarkupParser.createTextNodeForEscaped()
+ *
+ * These methods create DOM nodes directly without going through tokenization.
+ *
+ * WHY THIS DOMBUILDER IS KEPT:
+ * ----------------------------
+ * - Reference for token-to-DOM conversion patterns
+ * - Understanding of DOM tree construction
+ * - May be useful for future enhancements
+ * - Educational value
+ *
+ * SEE ALSO:
+ * - Tokenizer.js - Detailed architecture notes
+ * - DOMParser.js - Pipeline documentation
+ * - MarkupParser.parseWithDOMExtraction() - Current active pipeline
+ * - Issue #114 - WikiDocument DOM Solution
+ * - Issue #118 - Architecture documentation (this change)
+ *
+ * ============================================================================
+ *
+ * ORIGINAL DESCRIPTION:
+ * Takes an array of tokens from the Tokenizer and builds a structured
+ * DOM tree in a WikiDocument. Handles nesting, formatting, and all
+ * JSPWiki-compatible markup elements.
+ *
+ * Key Features:
+ * - Converts tokens to DOM nodes
+ * - Handles nested structures (lists, tables)
+ * - Manages formatting contexts (bold, italic)
+ * - Creates semantic HTML elements
+ *
+ * Part of Phase 2.4 of WikiDocument DOM Migration (GitHub Issue #93)
+ */
+/**
+ * Token metadata interface
+ */
+export interface TokenMetadata {
+    /** Heading level (for headings) */
+    level?: number;
+    /** Variable name (for variables) */
+    varName?: string;
+    /** Link target (for links) */
+    link?: string;
+    /** Link text (for links) */
+    text?: string;
+    /** Whether list is ordered (for lists) */
+    ordered?: boolean;
+    /** Additional metadata properties */
+    [key: string]: unknown;
+}
+/**
+ * Token interface
+ */
+export interface Token {
+    /** Token type - can be TokenType enum or string for extensibility */
+    type: TokenType | string;
+    /** Token value */
+    value: string;
+    /** Token metadata */
+    metadata?: TokenMetadata;
+    /** Line number */
+    line?: number;
+    /** Column number */
+    column?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * DOMBuilder class
+ */
+declare class DOMBuilder {
+    /** Target WikiDocument */
+    private wikiDocument;
+    /** Current parent element */
+    private currentParent;
+    /** Stack of nested lists */
+    private listStack;
+    /** Current table context */
+    private tableContext;
+    /** Current paragraph context */
+    private paragraphContext;
+    /**
+     * Creates a new DOMBuilder
+     *
+     * @param wikiDocument - Target WikiDocument
+     */
+    constructor(wikiDocument: WikiDocument);
+    /**
+     * Builds a DOM tree from an array of tokens
+     *
+     * @param tokens - Array of tokens from Tokenizer
+     * @returns The WikiDocument with built DOM
+     */
+    buildFromTokens(tokens: Token[]): WikiDocument;
+    /**
+     * Processes a single token
+     *
+     * @param token - Token to process
+     */
+    processToken(token: Token): void;
+    /**
+     * Handles plain text tokens
+     */
+    handleText(token: Token): void;
+    /**
+     * Handles escaped text [[...]]
+     * This is literal text that should not be parsed
+     */
+    handleEscaped(token: Token): void;
+    /**
+     * Handles variables {$varname}
+     */
+    handleVariable(token: Token): void;
+    /**
+     * Handles plugins [{PLUGIN ...}]
+     * Creates inline span element to allow plugins within paragraphs
+     */
+    handlePlugin(token: Token): void;
+    /**
+     * Handles wiki tags [tag]
+     */
+    handleWikiTag(token: Token): void;
+    /**
+     * Handles links [link|text]
+     */
+    handleLink(token: Token): void;
+    /**
+     * Handles interwiki links [Wiki:Page]
+     */
+    handleInterWiki(token: Token): void;
+    /**
+     * Handles headings !, !!, !!!
+     */
+    handleHeading(token: Token): void;
+    /**
+     * Handles list items *, #
+     */
+    handleListItem(token: Token): void;
+    /**
+     * Handles table cells | cell |
+     */
+    handleTableCell(token: Token): void;
+    /**
+     * Handles bold text __text__
+     */
+    handleBold(token: Token): void;
+    /**
+     * Handles italic text ''text''
+     */
+    handleItalic(token: Token): void;
+    /**
+     * Handles inline code {{text}}
+     */
+    handleCodeInline(token: Token): void;
+    /**
+     * Handles code blocks {{{code}}}
+     */
+    handleCodeBlock(token: Token): void;
+    /**
+     * Handles HTML comments <!-- comment -->
+     */
+    handleComment(token: Token): void;
+    /**
+     * Handles newlines
+     */
+    handleNewline(_token: Token): void;
+    /**
+     * Ensures a paragraph context exists for inline content
+     */
+    ensureParagraph(): void;
+    /**
+     * Closes the current paragraph context
+     */
+    closeCurrentParagraph(): void;
+    /**
+     * Adjusts the list stack to match the desired level
+     */
+    adjustListStack(targetLevel: number, isOrdered: boolean): void;
+    /**
+     * Closes all open lists
+     */
+    closeAllLists(): void;
+    /**
+     * Closes the current table context
+     */
+    closeCurrentTable(): void;
+}
+export default DOMBuilder;