umberto 7.0.2 → 8.0.0

package/scripts/utils/parser-cursor.js

@@ -0,0 +1,280 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * A cursor class that enables creating a left recursion recursive descent parser.
+ * It maintains position state and provides backtracking capabilities for parsing operations.
+ */
+class ParserCursor {
+	#_stack = [];
+
+	/**
+	 * Creates a new cursor instance for parsing text.
+	 *
+	 * @param text - The text to parse.
+	 * @param [index=0] - The initial position in the text.
+	 */
+	constructor( text, index = 0 ) {
+		this.index = index;
+		this.text = text;
+	}
+
+	/**
+	 * Executes a callback with automatic cursor position management.
+	 * If the callback returns undefined, the cursor position is restored to the state before the call.
+	 * This enables backtracking in the parser.
+	 *
+	 * @param callback - The callback function to execute.
+	 * @returns The result of the callback function.
+	 */
+	try( callback ) {
+		this.#push();
+
+		const result = callback( this );
+
+		if ( result === undefined ) {
+			this.index = this.#pop();
+		} else {
+			this.#pop( false );
+		}
+
+		return result;
+	}
+
+	/**
+	 * Attempts to consume a single terminal character at the current position.
+	 *
+	 * @param ch - The character to match and consume.
+	 * @returns True if the character was consumed, false otherwise.
+	 */
+	eatTerminal( ch ) {
+		if ( this.text[ this.index ] !== ch ) {
+			return false;
+		}
+
+		this.index++;
+		return true;
+	}
+
+	/**
+	 * Attempts to consume a sequence of terminal characters.
+	 * All characters must match in order for the operation to succeed.
+	 *
+	 * @param chars - The sequence of characters to match and consume.
+	 * @returns True if all characters were consumed, false otherwise.
+	 */
+	eatTerminals( chars ) {
+		this.#push();
+
+		for ( const ch of chars ) {
+			if ( !this.eatTerminal( ch ) ) {
+				this.#pop();
+				return false;
+			}
+		}
+
+		this.#pop( false );
+		return true;
+	}
+
+	/**
+	 * Consumes all terminal characters from the current position until a non-terminal character is encountered.
+	 *
+	 * @param chars - The characters to consume. If not provided, defaults to whitespace characters.
+	 */
+	eatAllNextTerminals( chars ) {
+		while ( this.index < this.text.length && chars.includes( this.text[ this.index ] ) ) {
+			this.index++;
+		}
+	}
+
+	/**
+	 * Consumes all whitespace characters (spaces and tabs) from the current position.
+	 */
+	eatIndent() {
+		this.eatAllNextTerminals( ' \t' );
+	}
+
+	/**
+	 * Consumes characters from the current position until a character matches the provided matcher function.
+	 * It consumes terminal character but does not include it in the result.
+	 *
+	 * @param matcher - A function that takes a character and returns true if it matches the condition to stop consuming.
+	 */
+	eatAllNextUntil( matcher ) {
+		let acc = '';
+
+		while ( this.index < this.text.length ) {
+			const ch = this.text[ this.index++ ];
+
+			if ( matcher( ch ) ) {
+				return acc;
+			}
+
+			acc += ch;
+		}
+
+		return acc;
+	}
+
+	/**
+	 * Consumes characters from the current position until a specific character is encountered.
+	 * It consumes terminal character but does not include it in the result.
+	 *
+	 * @param char - The character to stop consuming at.
+	 * @returns The consumed characters up to the specified character.
+	 */
+	eatUntilTerminal( char ) {
+		return this.eatAllNextUntil( c => c === char );
+	}
+
+	/**
+	 * Consumes characters from the current position until a newline character is encountered.
+	 * It consumes terminal character but does not include it in the result.
+	 */
+	eatUntilEOL() {
+		return this.eatAllNextUntil( c => c === '\n' );
+	}
+
+	/**
+	 * Attempts to consume a quoted string (single or double quotes).
+	 * Returns the content between the quotes without the quote characters.
+	 * Supports escaped quotes using backslash.
+	 *
+	 * @returns The quoted content or null if no valid quote was found.
+	 */
+	eatQuote() {
+		const quoteChar = this.text[ this.index ];
+
+		let started = false;
+		let acc = '';
+		let escaped = false;
+
+		this.#push();
+
+		for ( ; this.index < this.text.length; ++this.index ) {
+			const ch = this.text[ this.index ];
+
+			if ( escaped ) {
+				// Handle escaped characters
+				if ( ch === quoteChar || ch === '\\' ) {
+					acc += ch;
+				} else {
+					acc += '\\' + ch;
+				}
+
+				escaped = false;
+			} else if ( ch === '\\' ) {
+				escaped = true;
+			} else if ( ch !== quoteChar ) {
+				acc += ch;
+			} else if ( !started ) {
+				started = true;
+			} else {
+				// eat the closing quote
+				this.index++;
+				break;
+			}
+		}
+
+		if ( started ) {
+			this.#pop( false );
+			return acc;
+		}
+
+		this.#pop();
+		return null;
+	}
+
+	/**
+	 * Consumes a word (alphanumeric characters, underscore, and optionally other allowed characters).
+	 *
+	 * @param [whitelist=':-'] - Additional characters to allow in the word.
+	 * @returns The consumed word, or empty string if no word was found.
+	 */
+	eatWord( whitelist = ':-' ) {
+		let acc = '';
+
+		this.#push();
+
+		for ( ; this.index < this.text.length; ++this.index ) {
+			const ch = this.text[ this.index ];
+
+			if ( !isWordChar( ch ) && !whitelist.includes( ch ) ) {
+				break;
+			}
+
+			acc += ch;
+		}
+
+		this.#pop( !acc );
+
+		return acc;
+	}
+
+	/**
+	 * Attempts to consume Nth productions until a production is not matched.
+	 */
+	accumulateEaters( production ) {
+		const results = [];
+
+		for ( let watchdog = 0; watchdog < 1000; watchdog++ ) {
+			const result = this.try( production );
+
+			if ( result !== undefined ) {
+				results.push( result );
+			} else {
+				break;
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Saves the current cursor position to the internal stack.
+	 * This enables backtracking by restoring to this position later.
+	 */
+	#push() {
+		this.#_stack.push( this.index );
+	}
+
+	/**
+	 * Removes and optionally restores the last saved cursor position from the stack.
+	 *
+	 * @param [assign=true] - If true, restores the cursor to the popped position.
+	 * @returns The popped position value.
+	 */
+	#pop( assign = true ) {
+		const value = this.#_stack.pop();
+
+		if ( assign ) {
+			this.index = value;
+		}
+
+		return value;
+	}
+};
+
+/**
+ * Checks if a character is a word character (alphanumeric or underscore).
+ *
+ * @param c - The character to check.
+ * @returns True if the character is a word character.
+ */
+function isWordChar( c ) {
+	const code = c.charCodeAt( 0 );
+
+	return (
+		( code >= 65 && code <= 90 ) || // A-Z
+		( code >= 97 && code <= 122 ) || // a-z
+		( code >= 48 && code <= 57 ) || // 0-9
+		code === 95 // _
+	);
+}
+
+module.exports = ParserCursor;

package/scripts/utils/pipe.js

@@ -0,0 +1,17 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Applies a series of functions to an input value, passing the result of each function
+ * as the input to the next function.
+ *
+ * @param {*} value - The initial value to be processed by the functions.
+ * @returns {*} The final result after all functions have been applied.
+ */
+module.exports = function pipe( ...fns ) {
+	return value => fns.reduce( ( acc, fn ) => fn( acc ), value );
+};

package/scripts/utils/pug-renderer/create-prerender-pug-template.js

@@ -0,0 +1,172 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { randomId, regenerateRandomIds } = require( '../random-id' );
+const renderPugComponent = require( './render-pug-component' );
+
+/**
+ * Creates a template function for a Pug component with a built-in caching mechanism.
+ *
+ * This function is useful for optimizing the rendering of components that are used multiple times
+ * with minor changes in attributes. It divides attributes into three categories: `static`, `dynamic`, and `mask`,
+ * to efficiently manage caching.
+ *
+ * - `static`: Attributes that are the same for all instances of the component.
+ *   They are passed to the Pug component during the first render.
+ *
+ * - `dynamic`: Attributes whose values can change and affect the component's appearance or structure.
+ *   A cache key is generated based on the combination of these attribute values.
+ *   A new version of the component is rendered and cached for each unique combination of these attribute values.
+ *
+ * - `mask`: Attributes whose values are unique for each call and should not be part of the cached HTML.
+ *   Instead, unique identifiers (masks) are inserted into the cached template, which are replaced
+ *   with the actual values after retrieving the template from the cache. This is ideal for content
+ *   such as code in a code block.
+ *
+ * @example
+ * const createPrerenderPugTemplate = require( './create-prerender-pug-template' );
+ *
+ * // Creates a template for the 'code-block' component.
+ * const codeBlockTemplate = createPrerenderPugTemplate( {
+ *   // Attributes for `renderPugComponent`.
+ *   includes: [ '_components/code-block/index' ],
+ *   component: 'code-block',
+ *
+ *   // Attributes for the component itself.
+ *   componentAttrs: {
+ *     // Static attributes are the same for every render.
+ *     static: {
+ *       copyable: true
+ *     },
+ *     // Dynamic attributes are used for caching.
+ *     // A new version of the component will be rendered and cached
+ *     // for each unique combination of these attribute values.
+ *     dynamic: [ 'language' ],
+ *     // Masked attributes are replaced after rendering (even from the cache).
+ *     // They are used for unique content that should not be cached.
+ *     mask: [ 'code' ]
+ *   }
+ * } );
+ *
+ * // Using the template.
+ * // The first call will render the component for the 'javascript' language and cache it.
+ * const html1 = codeBlockTemplate( { language: 'javascript', code: 'console.log( "Hello" );' } );
+ *
+ * // This call will use the cached version for 'javascript'.
+ * // Only 'code' will be replaced.
+ * const html2 = codeBlockTemplate( { language: 'javascript', code: 'console.log( "World" );' } );
+ *
+ * // This will render a new version for 'html' and cache it.
+ * const html3 = codeBlockTemplate( { language: 'html', code: '<h1>Hello</h1>' } );
+ */
+module.exports = function createPrerenderPugTemplate( { componentAttrs, skipCacheIf, ...renderAttrs } ) {
+	const cacheStorage = new Map();
+	const maskAttrsMap = assignMaskAttrsIds( componentAttrs.mask || [] );
+
+	const allKnownAttributes = [
+		...componentAttrs.dynamic || [],
+		...Object.keys( componentAttrs.static || {} ),
+		...componentAttrs.mask || []
+	];
+
+	return dynamicAttrs => {
+		// Check if we should skip caching based on the provided condition.
+		const skipCache = skipCacheIf?.( dynamicAttrs );
+
+		if ( skipCache ) {
+			return renderPugComponent( {
+				...renderAttrs,
+				componentAttrs: {
+					...componentAttrs.static,
+					...dynamicAttrs
+				}
+			} );
+		}
+
+		// Check if component is already pre-rendered, if so, return cached HTML.
+		const _hasUnknownAttributes = hasUnknownAttributes( allKnownAttributes, dynamicAttrs );
+		const cacheKey = createCacheKey( componentAttrs.dynamic, dynamicAttrs );
+
+		let renderedHtml;
+
+		if ( !_hasUnknownAttributes && cacheStorage.has( cacheKey ) ) {
+			renderedHtml = cacheStorage.get( cacheKey );
+		} else {
+			renderedHtml = renderPugComponent( {
+				...renderAttrs,
+				componentAttrs: {
+					...componentAttrs.static,
+					...dynamicAttrs,
+					...maskAttrsMap
+				}
+			} );
+
+			if ( !_hasUnknownAttributes ) {
+				cacheStorage.set( cacheKey, renderedHtml );
+			}
+		}
+
+		// Regenerate random IDs in the rendered HTML to ensure uniqueness.
+		renderedHtml = regenerateRandomIds( renderedHtml );
+
+		for ( const maskKey in maskAttrsMap ) {
+			const dynamicValue = dynamicAttrs[ maskKey ] || '';
+
+			renderedHtml = renderedHtml.replace(
+				maskAttrsMap[ maskKey ],
+				dynamicValue
+			);
+		}
+
+		return renderedHtml;
+	};
+};
+
+/**
+ * Checks if the provided component attributes contain any unknown attributes.
+ */
+function hasUnknownAttributes( knownAttributes, componentAttrs ) {
+	return Object.keys( componentAttrs ).some( attr => !knownAttributes.includes( attr ) );
+}
+
+/**
+ * Creates a cache key based on the specified attributes and their values.
+ *
+ * @param cacheByAttributes An array of attribute names to be included in the cache key.
+ * @param componentAttrs An object containing component attributes and their values.
+ * @returns The generated cache key.
+ */
+function createCacheKey( cacheByAttributes, componentAttrs ) {
+	if ( !cacheByAttributes?.length ) {
+		return 'default';
+	}
+
+	let acc = '';
+
+	for ( const attr of cacheByAttributes ) {
+		acc += `${ attr }-${ componentAttrs[ attr ] || 'undefined' }-`;
+	}
+
+	return acc;
+}
+
+/**
+ * Creates an object that maps mask attribute names to unique random IDs.
+ *
+ * @param maskAttributes An array of attribute names that should be masked.
+ * @returns An object where keys are attribute names and values are unique mask IDs.
+ */
+function assignMaskAttrsIds( maskAttributes ) {
+	return maskAttributes.reduce(
+		( acc, attr ) => {
+			acc[ attr ] = randomId( 'mask', false );
+
+			return acc;
+		},
+		Object.create( {} )
+	);
+}

package/scripts/utils/pug-renderer/render-pug-component.js

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const path = require( 'path' );
+const hexoManager = require( '../../../src/hexo-manager' );
+
+/**
+ * Renders a Pug component with specified includes and parameters.
+ *
+ * @param options - The rendering options.
+ * @param options.hexo - The Hexo instance.
+ * @param options.mixinContextVars - Context variables to be passed to the Pug mixin.
+ * @param [options.requires=[]] - Array of Pug includes to be added at the top of the template.
+ * @param options.component - The name of the component to render (without the + prefix).
+ * @param [options.componentAttrs={}] - Attributes to pass to the component.
+ * @param [options.basePath] - Base path for the component. Defaults to theme components directory.
+ * @returns The rendered HTML.
+ */
+module.exports = function renderPugComponent(
+	{
+		hexo,
+		mixinContextVars = {},
+		requires = [],
+		component,
+		componentAttrs = {},
+		basePath
+	}
+) {
+	const { children, ...restComponentAttrs } = componentAttrs || {};
+
+	// Default base path is the components directory in the theme
+	// Handle case where hexo.theme_dir might be undefined
+	const resolvedHexo = hexo || hexoManager.hexo;
+	const themeDir = resolvedHexo && resolvedHexo.theme_dir || path.join( __dirname, '../../themes/umberto' );
+	const componentsPath = basePath || path.join( themeDir, 'layout', 'gloria', '_components' );
+
+	// Prepare includes statements
+	const includeStatements = requires.map( include => `include ${ include }` );
+
+	// Prepare the component call with its attributes
+	const componentCall = `+${ component }(${ JSON.stringify( restComponentAttrs ) })`;
+
+	// Complete content to be rendered
+	const content = [
+		...includeStatements,
+		componentCall,
+		children
+	]
+		.filter( Boolean )
+		.join( '\n' );
+
+	// Prepare locals for rendering
+	const locals = Object.assign(
+		{},
+		resolvedHexo.locals.toObject(),
+		resolvedHexo.extend.helper.list(),
+		{
+			...mixinContextVars,
+			config: resolvedHexo.config
+		}
+	);
+
+	// Render and return the component
+	return resolvedHexo.render.renderSync( {
+		text: content,
+		engine: 'pug',
+		path: componentsPath
+	}, locals );
+};

package/scripts/utils/pug-to-xml-binding/parser/walk-xml-tree.js

@@ -0,0 +1,150 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Symbols used to control tree walking behavior in leave callbacks
+ */
+const TREE_WALK_SYMBOLS = {
+	REMOVE: Symbol( 'REMOVE' ),
+	REPLACE: Symbol( 'REPLACE' ),
+	KEEP: Symbol( 'KEEP' ),
+	ABORT: Symbol( 'ABORT' )
+};
+
+/**
+ * Walks through a tree structure, calling enter and leave callbacks for each node.
+ * The leave callback can return an object with a symbol to control the node's fate:
+ * - { symbol: TREE_WALK_SYMBOLS.REMOVE } - removes the node
+ * - { symbol: TREE_WALK_SYMBOLS.REPLACE, value: newNode } - replaces the node
+ * - { symbol: TREE_WALK_SYMBOLS.KEEP } or undefined - keeps the node unchanged
+ *
+ * @param tree - The tree or node to walk through
+ * @param options - Walking options
+ * @param [options.enter] - Callback called when entering a node (node, depth, parents)
+ * @param [options.leave] - Callback called when leaving a node (node, depth, parents)
+ * @param [depth=0] - Current depth (used internally for recursion)
+ * @param [parents=[]] - Array of parent nodes (used internally for recursion)
+ * @returns The potentially modified tree
+ */
+function walkXMLTree( tree, options = {}, depth = 0, parents = [] ) {
+	const { enter, leave } = options;
+
+	// Handle array of nodes
+	if ( Array.isArray( tree ) ) {
+		const result = [];
+
+		for ( let i = 0; i < tree.length; i++ ) {
+			const processedNode = walkXMLTree( tree[ i ], options, depth, parents );
+
+			if ( Array.isArray( processedNode ) ) {
+				result.push( ...processedNode );
+			} else if ( processedNode !== undefined ) {
+				result.push( processedNode );
+			}
+		}
+
+		return result;
+	}
+
+	if ( enter ) {
+		const enterResult = enter( tree, depth, parents );
+		const processedResult = processCallbackResult( enterResult, tree );
+
+		if ( processedResult === Symbol.for( 'ABORT_WALK' ) ) {
+			return;
+		}
+
+		if ( processedResult !== tree ) {
+			return processedResult;
+		}
+	}
+
+	// Create a working copy of the node to potentially modify
+	let workingNode = tree;
+
+	// Recursively walk children if they exist
+	if ( tree.children && Array.isArray( tree.children ) ) {
+		const modifiedChildren = walkXMLTree( tree.children, options, depth + 1, [ ...parents, tree ] );
+
+		// Only create a new node if children were actually modified
+		if ( modifiedChildren !== tree.children ) {
+			workingNode = { ...tree, children: modifiedChildren };
+		}
+	}
+
+	// Call leave callback
+	if ( leave ) {
+		const leaveResult = leave( workingNode, depth, parents );
+
+		return processCallbackResult( leaveResult, workingNode );
+	}
+
+	return workingNode;
+};
+
+/**
+ * Processes a callback result and returns the appropriate action.
+ *
+ * @param result - The result from enter/leave callback
+ * @param defaultValue - Value to return if no action is taken
+ * @returns The processed result
+ */
+function processCallbackResult( result, defaultValue ) {
+	if ( result && typeof result === 'object' && result.symbol ) {
+		switch ( result.symbol ) {
+			case TREE_WALK_SYMBOLS.KEEP:
+				return defaultValue;
+
+			case TREE_WALK_SYMBOLS.REMOVE:
+				return undefined;
+
+			case TREE_WALK_SYMBOLS.REPLACE:
+				return result.value;
+
+			case TREE_WALK_SYMBOLS.ABORT:
+				return Symbol.for( 'ABORT_WALK' );
+		}
+	}
+
+	return defaultValue;
+}
+
+/**
+ * Helper functions for tree walking control
+ */
+const TreeWalkActions = {
+	/**
+	 * Creates an action to remove the current node.
+	 *
+	 * @returns Control object for node removal
+	 */
+	remove() {
+		return { symbol: TREE_WALK_SYMBOLS.REMOVE };
+	},
+
+	/**
+	 * Creates an action to replace the current node with a new value.
+	 *
+	 * @param value - The new value to replace the node with
+	 * @returns Control object for node replacement
+	 */
+	replace( value ) {
+		return { symbol: TREE_WALK_SYMBOLS.REPLACE, value };
+	},
+
+	/**
+	 * Creates an action to keep the current node unchanged.
+	 *
+	 * @returns Control object for keeping the node
+	 */
+	keep() {
+		return { symbol: TREE_WALK_SYMBOLS.KEEP };
+	}
+};
+
+exports.walkXMLTree = walkXMLTree;
+exports.TreeWalkActions = TreeWalkActions;