umberto 6.1.2 → 7.0.1

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 Changelog
 =========
 
+## [7.0.1](https://github.com/cksource/umberto/compare/v7.0.0...v7.0.1) (2025-05-14)
+
+### Other changes
+
+* Updated the project dependencies. Closes [#1253](https://github.com/cksource/umberto/issues/1253). ([commit](https://github.com/cksource/umberto/commit/28d74364207ab055ad76c2857d58cccb1866559b))
+* Removed dependencies that can be replaced with native APIs or other already used dependencies. ([commit](https://github.com/cksource/umberto/commit/28d74364207ab055ad76c2857d58cccb1866559b))
+* Sitemaps will be generated separately for each project. Closes [#1254](https://github.com/cksource/umberto/issues/1254). ([commit](https://github.com/cksource/umberto/commit/7968755b2a4b1c23768a9420292eb1d168b898b3))
+
+
+## [7.0.0](https://github.com/cksource/umberto/compare/v6.1.2...v7.0.0) (2025-05-05)
+
+### BREAKING CHANGES
+
+* Rendering TypeScript-based API pages requires an input file generated by Typedoc in version `0.28.0` or later.
+
+### Features
+
+* Support for rendering TypeScript API pages based on output from `typedoc@0.28`. Closes [#1188](https://github.com/cksource/umberto/issues/1188). ([commit](https://github.com/cksource/umberto/commit/561f94c6b025a0f1dbcc01c0c0e70ee5eeae387e))
+
+
 ## [6.1.2](https://github.com/cksource/umberto/compare/v6.1.1...v6.1.2) (2025-04-23)
 
 ### Bug fixes

package/hexo-config.json

@@ -15,16 +15,11 @@
 	"pug": {
 		"pretty": true
 	},
-  	"highlight": {
-	  	"enable": false
-	},
-	"prism": {
-		"enable": false
-	},
-  	"markdown_it_plus": {
-	  	"highlight": false,
-	  	"html": true,
-	  	"breaks": true,
+	"syntax_highlighter": "",
+	"markdown_it_plus": {
+		"highlight": false,
+		"html": true,
+		"breaks": true,
 		"linkify": false,
 		"plugins": [
 			{
@@ -42,19 +37,19 @@
 				"plugin": {
 					"name": "markdown-it-expand-tabs",
 					"enable": true,
-				  	"options": {
-					  	"tabWidth": 4
+					"options": {
+						"tabWidth": 4
 					}
 				}
 			}
 		]
 	},
-  	"skip_render": [
-	  	"**/*.css",
-	  	"**/*.scss",
-	  	"**/*.html",
-	  	"**/*.json",
-	  	"**/*.js",
-	  	"**/*.txt"
+	"skip_render": [
+		"**/*.css",
+		"**/*.scss",
+		"**/*.html",
+		"**/*.json",
+		"**/*.js",
+		"**/*.txt"
 	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "6.1.2",
+  "version": "7.0.1",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -15,42 +15,36 @@
   ],
   "dependencies": {
     "@babel/core": "^7.18.10",
-    "@babel/polyfill": "^7.12.1",
     "@babel/preset-env": "^7.18.10",
     "@ckeditor/jsdoc-plugins": "^43.0.0",
-    "babel-loader": "^8.2.5",
-    "chalk": "^4.1.0",
+    "babel-loader": "^10.0.0",
     "cheerio": "^1.0.0",
-    "cpx": "^1.5.0",
-    "del": "^6.1.1",
-    "element-closest": "^3.0.2",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^11.0.0",
-    "fuse.js": "^6.6.2",
-    "glob": "^7.2.3",
-    "hexo": "^6.2.0",
-    "hexo-generator-archive": "^1.0.0",
-    "hexo-generator-category": "^1.0.0",
-    "hexo-generator-index": "^1.0.0",
-    "hexo-generator-tag": "^1.0.0",
+    "fuse.js": "^7.1.0",
+    "glob": "^11.0.2",
+    "hexo": "^7.3.0",
+    "hexo-generator-archive": "^2.0.0",
+    "hexo-generator-category": "^2.0.0",
+    "hexo-generator-index": "^4.0.0",
+    "hexo-generator-tag": "^2.0.0",
     "hexo-render-pug": "^2.1.4",
     "hexo-renderer-markdown-it-plus": "^1.0.5",
     "htmlparser2": "^10.0.0",
     "javascript-stringify": "^2.1.0",
-    "jquery": "~3.6.0",
+    "jquery": "~3.7.1",
     "js-beautify": "^1.14.4",
     "lodash": "^4.17.21",
-    "markdown-it": "^13.0.1",
+    "markdown-it": "^14.1.0",
     "markdown-it-expand-tabs": "^1.0.13",
     "markdown-it-toc-and-anchor": "^4.2.0",
     "medium-zoom": "^1.0.6",
-    "minimatch": "^5.1.0",
-    "mkdirp": "^1.0.4",
+    "minimatch": "^10.0.1",
     "moment": "^2.29.4",
-    "nyc": "^15.1.0",
+    "nyc": "^17.1.0",
     "pug": "^3.0.2",
     "sass": "^1.54.0",
-    "sitemap": "^7.1.1",
+    "sitemap": "^8.0.0",
     "tippy.js": "^6.3.7",
     "tree-model": "^1.0.7",
     "upath": "^2.0.1",
@@ -79,6 +73,6 @@
     "packages/**"
   ],
   "hexo": {
-    "version": "6.3.0"
+    "version": "7.3.0"
   }
 }

package/scripts/filter/after-post-render/time-end.js

@@ -5,8 +5,7 @@
 
 'use strict';
 
-const util = require( 'util' );
-const chalk = require( 'chalk' );
+const { format, styleText } = require( 'util' );
 
 hexo.extend.filter.register( 'after_post_render', page => {
 	if ( !hexo.projectGlobals.common || !hexo.projectGlobals.common.verbose ) {
@@ -17,11 +16,11 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	// Log only pages, which generates for longer than 1 second.
 	if ( time[ 0 ] > 1 ) {
 		console.log(
-			util.format(
+			format(
 				'Page: %s was processed in: %s.%ss.',
-				chalk.cyanBright( page.source ),
-				chalk.yellow( time[ 0 ] ),
-				chalk.yellow( time[ 1 ] )
+				styleText( 'cyanBright', page.source ),
+				styleText( 'yellow', time[ 0 ] ),
+				styleText( 'yellow', time[ 1 ] )
 			)
 		);
 	}

package/scripts/utils/getreportissuewidgeturl.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const minimatch = require( 'minimatch' );
+const { minimatch } = require( 'minimatch' );
 
 /**
  * @param {Object} page A page object.

package/scripts/utils/logcrossprojectreference.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const chalk = require( 'chalk' );
+const { styleText } = require( 'util' );
 
 /**
  * Logs an error message about a cross-project reference found in the parsed expression.
@@ -19,8 +19,8 @@ const chalk = require( 'chalk' );
 module.exports = function logCrossProjectReference( { expression, source } ) {
 	process.exitCode = 1;
 
-	const message = `${ chalk.red( 'Error:' ) } Failed while convert ${ chalk.cyanBright( expression ) } tag`;
-	const messageLocation = source ? ` in ${ chalk.magentaBright( source ) }.` : '.';
+	const message = `${ styleText( 'red', 'Error:' ) } Failed while convert ${ styleText( 'cyanBright', expression ) } tag`;
+	const messageLocation = source ? ` in ${ styleText( 'magentaBright', source ) }.` : '.';
 	const messageDescription = ' Cross-project references are not supported.';
 
 	console.log( message + messageLocation + messageDescription );

package/scripts/utils/parselinks.js

@@ -5,9 +5,9 @@
 
 'use strict';
 
+const { styleText } = require( 'util' );
 const upath = require( 'upath' );
 const splitLongname = require( '../../src/helpers/split-longname' );
-const chalk = require( 'chalk' );
 
 const LINK_REGEXP = /\\?{(?:@linkapi|@link|@linksdk|@linkexample)\s+[^{]+?({[^}]+})?[^{}]*\\?}/g;
 
@@ -127,7 +127,7 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 			value: str,
 			source: data.source,
 			isSilent: isSilentError,
-			description: `Project ${ chalk.redBright( data.projectName ) } is not defined.`
+			description: `Project ${ styleText( 'redBright', data.projectName ) } is not defined.`
 		} );
 	}
 
@@ -343,10 +343,16 @@ function onError( { value, source, isSilent, description } ) {
 	if ( !isSilent ) {
 		process.exitCode = 1;
 
-		console.log(
-			`${ chalk.red( 'Error: ' ) }Failed while convert ${ chalk.cyanBright( value ) } tag in ` +
-			`${ chalk.magentaBright( source ) }.${ description ? chalk.italic( ' ' + description ) : '' }`
-		);
+		const message = [
+			styleText( 'red', 'Error:' ),
+			`Failed to convert ${ styleText( 'cyanBright', value ) } tag`,
+			source && `in ${ styleText( 'magentaBright', source ) }`,
+			description && `because ${ styleText( 'italic', description ) }`
+		]
+			.filter( Boolean )
+			.join( ' ' );
+
+		console.log( message );
 	}
 
 	return value;

package/src/api-builder/classes/description-parser.js

@@ -5,9 +5,9 @@
 
 'use strict';
 
+const { styleText } = require( 'util' );
 const cheerio = require( 'cheerio' );
 const splitLongname = require( '../../helpers/split-longname' );
-const chalk = require( 'chalk' );
 const macroReplacer = require( '../../tasks/macro-replacer' );
 const findTargetDoclet = require( '../utils/findtargetdoclet' );
 const { hasDedicatedApiPages, LONG_NAME_LABEL_REGEXP, LONG_NAME_MEMBER_SEPARATOR_REGEXP } = require( '../utils/utils' );
@@ -283,7 +283,7 @@ module.exports = class DescriptionParser {
 				replaceToPhrase = `<a href="${ href }">${ linkContent }</a>`;
 			} else {
 				console.log(
-					`${ chalk.yellow( 'Warning:' ) } Invalid link in API docs: ${ chalk.gray( fullMatch ) }.`,
+					`${ styleText( 'yellow', 'Warning:' ) } Invalid link in API docs: ${ styleText( 'gray', fullMatch ) }.`,
 					'There is no doclet of the link target.'
 				);
 

package/src/api-builder/utils/findtargetdoclet.js

@@ -79,9 +79,9 @@ module.exports = function findTargetDoclet( docletCollection, options ) {
 			return null;
 		}
 
-		const { properties = [] } = typedefItem;
+		const { properties } = typedefItem;
 
-		return properties.find( item => item.name === member ) ? typedefItem : null;
+		return ( properties || [] ).find( item => item.name === member ) ? typedefItem : null;
 	}
 
 	let targetDoclet;

package/src/data-converter/converters/typedoc/abstractparser.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const TypedocConverter = require( './typedocconverter' );
+const ReflectionKind = require( './reflectionkind' );
 
 /**
  * An abstract parser class providing basic utils for converting Typedoc reflection to JSDoc doclet.
@@ -14,14 +15,14 @@ module.exports = class AbstractParser {
 	/**
 	 * @abstract
 	 * @method canParse
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 
 	/**
 	 * @abstract
 	 * @method parse
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {Object}
 	 */
@@ -29,7 +30,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Coverts the item's comment from Markdown to HTML.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getComment( item ) {
@@ -41,33 +42,35 @@ module.exports = class AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {String}
 	 */
 	getLongName( item, parentName = null ) {
 		let separator;
 
-		switch ( item.kindString ) {
-			case 'Module':
+		if ( item.isCKEditor5Event ) {
+			separator = '#event:';
+		}
+
+		switch ( item.kind ) {
+			case ReflectionKind.Module:
 				separator = ':';
 				parentName = 'module';
 				break;
 
-			case 'Class':
-			case 'Function':
-			case 'Interface':
-			case 'Type alias':
+			case ReflectionKind.Variable:
+			case ReflectionKind.Function:
+			case ReflectionKind.Class:
+			case ReflectionKind.Interface:
+			case ReflectionKind.TypeAlias:
 				separator = '~';
 				break;
 
-			case 'Event':
-				separator = '#event:';
-				break;
-
 			default:
-				separator = this.getScope( item ) === 'static' ? '.' : '#';
-				break;
+				if ( !separator ) {
+					separator = this.getScope( item ) === 'static' ? '.' : '#';
+				}
 		}
 
 		return `${ parentName }${ separator }${ item.name }`;
@@ -76,7 +79,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Prepares the name for the computed property.
 	 *
-	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {ComputedPropertyReflection} item
 	 * @returns {String}
 	 */
 	getComputedName( item ) {
@@ -86,7 +89,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the access type for the item.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {'public'|'internal'|'protected'|'private'}
 	 */
 	getVisibility( item ) {
@@ -110,48 +113,49 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the item's kind.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getKind( item ) {
-		switch ( item.kindString ) {
-			case 'Module':
+		if ( item.isCKEditor5Event ) {
+			return 'event';
+		}
+		if ( item.isCKEditor5Error ) {
+			return 'error';
+		}
+
+		switch ( item.kind ) {
+			case ReflectionKind.Module:
 				return 'module';
 
-			case 'Class':
+			case ReflectionKind.Class:
 				return 'class';
 
-			case 'Function':
-			case 'Method':
-			case 'Constructor':
+			case ReflectionKind.Function:
+			case ReflectionKind.Method:
+			case ReflectionKind.Constructor:
 				return 'function';
 
-			case 'Interface':
+			case ReflectionKind.Interface:
 				return 'interface';
 
-			case 'Accessor':
-			case 'Property':
-			case 'Index signature':
+			case ReflectionKind.Accessor:
+			case ReflectionKind.Property:
+			case ReflectionKind.IndexSignature:
 				return 'member';
 
-			case 'Variable':
+			case ReflectionKind.Variable:
 				return 'constant';
 
-			case 'Type alias':
+			case ReflectionKind.TypeAlias:
 				return 'typedef';
-
-			case 'Event':
-				return 'event';
-
-			case 'Error':
-				return 'error';
 		}
 	}
 
 	/**
 	 * Returns the item's scope.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {'instance'|'static'}
 	 */
 	getScope( item ) {
@@ -167,7 +171,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the `extraId` combined from the item's scope, kind, name and optional variation.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getExtraId( item ) {
@@ -179,7 +183,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the long names of the events that are fired from the signature.
 	 *
-	 * @param {TypedocReflectionMeta} signature
+	 * @param {BaseReflection} signature
 	 * @param {String} parentName
 	 * @returns {Array.<String>|null}
 	 */
@@ -202,7 +206,7 @@ module.exports = class AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflectionMeta} signature
+	 * @param {BaseReflection} signature
 	 * @param {String} parentName
 	 * @returns {Array.<Object>|null}
 	 */
@@ -243,7 +247,7 @@ module.exports = class AbstractParser {
 	 * Returns the URL to GitHub with selected line, where the given doclet is defined.
 	 * The URL includes a commit hash which was used to build the API docs.
 	 *
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @param {Number} sourceIndex
 	 * @returns {Object|null}
 	 */
@@ -264,7 +268,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns links from the "@see" tags.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {Array.<String>}
 	 */
@@ -308,7 +312,7 @@ module.exports = class AbstractParser {
 	 *
 	 * The readonly state can be marked either by a TypeScript `readonly` keyword, or by the `@readonly` JSDoc keyword.
 	 *
-	 * @param {TypedocReflection} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isReadonly( item ) {
@@ -324,7 +328,7 @@ module.exports = class AbstractParser {
 	 *
 	 * The observable state can be marked by the `@observable` JSDoc keyword.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isObservable( item ) {
@@ -338,7 +342,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Checks if the item is marked as an optional.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isOptional( item ) {
@@ -355,7 +359,7 @@ module.exports = class AbstractParser {
 	 * The `internal` state means the same as `protected`, but with one exception: the `internal` member can be used from outside the class
 	 * in which it is defined (or its derivatives), as opposed to the `protected` state.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isInternal( item ) {
@@ -369,7 +373,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Checks if the member is marked by the `@deprecated` JSDoc tag.
 	 *
-	 * @param {TypedocReflectionMeta>} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isDeprecated( item ) {
@@ -387,7 +391,7 @@ module.exports = class AbstractParser {
 	 * It happens when the member has not specified `file` property. In such a case, Umberto does not know
 	 * where to point to a source and decides to skip generating the "See source" button.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	shouldSkipSource( item ) {
@@ -402,7 +406,7 @@ module.exports = class AbstractParser {
 	 * Returns a name specified in the `@label` annotation.
 	 *
 	 * @protected
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	_getLabelName( item ) {

package/src/data-converter/converters/typedoc/accessorparser.js

@@ -6,21 +6,22 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class AccessorParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Accessor';
+		return item.kind === ReflectionKind.Accessor;
 	}
 
 	/**
 	 * Checks if the accessor is readonly.
 	 *
 	 * @override
-	 * @param {TypedocReflection} item
+	 * @param {AccessorReflection} item
 	 * @returns {Boolean}
 	 */
 	isReadonly( item ) {
@@ -28,7 +29,7 @@ module.exports = class AccessorParser extends AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflection<'Accessor'>} item
+	 * @param {AccessorReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -41,6 +42,7 @@ module.exports = class AccessorParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: [ getSignature || {}, setSignature || {} ],
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),
@@ -65,7 +67,7 @@ module.exports = class AccessorParser extends AbstractParser {
 	/**
 	 * Returns the access type for the item based on its signatures.
 	 *
-	 * @param {TypedocReflection<Accessor>} item
+	 * @param {AccessorReflection} item
 	 * @returns {'public'|'internal'|'protected'|'private'}
 	 */
 	getVisibilityIncludingSignature( item ) {

package/src/data-converter/converters/typedoc/classparser.js

@@ -6,18 +6,19 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ClassParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Class';
+		return item.kind === ReflectionKind.Class;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Class'>} item
+	 * @param {ClassReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -26,6 +27,7 @@ module.exports = class ClassParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: item,
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),

package/src/data-converter/converters/typedoc/computedpropertyparser.js

@@ -6,18 +6,19 @@
 'use strict';
 
 const PropertyParser = require( './propertyparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ComputedPropertyParser extends PropertyParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Index signature';
+		return item.kind === ReflectionKind.IndexSignature;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {ComputedPropertyReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */