umberto 6.1.2 → 7.0.0

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

@@ -6,33 +6,28 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class PropertyParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Property' && item.name !== 'constructor';
+		return item.kind === ReflectionKind.Property;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Property'>} item
+	 * @param {PropertyReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
 	parse( item, parentName ) {
-		// By default, a comment that is associated in the source code with the property, is bound to the item itself, as anyone would
-		// expect. TypeDoc works differently for a callable property, for which the comment is moved down to the property signature.
-		// Hence, we must extract it back from the property signature to be able to display it correctly in the API docs.
-		const description = isCallableProperty( item ) ?
-			this.getComment( item.type.declaration.signatures[ 0 ] ) :
-			this.getComment( item );
-
 		return {
 			// 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 ),
@@ -44,7 +39,7 @@ module.exports = class PropertyParser extends AbstractParser {
 			optional: this.isOptional( item ),
 			kind: this.getKind( item ),
 			extraId: this.getExtraId( item ),
-			description,
+			description: this.getComment( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
 			deprecated: this.isDeprecated( item ),
@@ -60,7 +55,7 @@ module.exports = class PropertyParser extends AbstractParser {
 	/**
 	 * Returns the default value of an item defined by the `@defaultValue` or `@default` tags.
 	 *
-	 * @param {TypedocReflection} item
+	 * @param {PropertyReflection} item
 	 * @returns {String}
 	 */
 	getDefault( item ) {
@@ -77,19 +72,3 @@ module.exports = class PropertyParser extends AbstractParser {
 		return defaultTag.content[ 0 ].text;
 	}
 };
-
-/**
- * @param {TypedocReflectionType} item
- * @returns {Boolean}
- */
-function isCallableProperty( item ) {
-	if ( item.type.type !== 'reflection' ) {
-		return false;
-	}
-
-	if ( !Array.isArray( item.type.declaration.signatures ) ) {
-		return false;
-	}
-
-	return true;
-}

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

@@ -0,0 +1,41 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
+
+module.exports = class ReferenceParser extends AbstractParser {
+	/**
+	 * @param {BaseReflection} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kind === ReflectionKind.Reference;
+	}
+
+	/**
+	 * @param {ReferenceReflection} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		return {
+			// 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 ),
+			file: this.getFile( item ),
+
+			_isReference: true,
+
+			targetDoclet: null
+		};
+	}
+};

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

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+// To avoid linking Umberto and Typedoc, let's keep this file in sync with the `ReflectionKind` enum.
+// See: https://typedoc.org/api/enums/Models.ReflectionKind.html
+
+module.exports.Accessor = 262144;
+module.exports.CallSignature = 4096;
+module.exports.Class = 128;
+module.exports.Constructor = 512;
+module.exports.ConstructorSignature = 16384;
+module.exports.Document = 8388608;
+module.exports.Enum = 8;
+module.exports.EnumMember = 16;
+module.exports.Function = 64;
+module.exports.GetSignature = 524288;
+module.exports.IndexSignature = 8192;
+module.exports.Interface = 256;
+module.exports.Method = 2048;
+module.exports.Module = 2;
+module.exports.Namespace = 4;
+module.exports.Parameter = 32768;
+module.exports.Project = 1;
+module.exports.Property = 1024;
+module.exports.Reference = 4194304;
+module.exports.SetSignature = 1048576;
+module.exports.TypeAlias = 2097152;
+module.exports.TypeLiteral = 65536;
+module.exports.TypeParameter = 131072;
+module.exports.Variable = 32;

package/src/data-converter/converters/typedoc/typedoc.ts

@@ -6,286 +6,287 @@
 // This file contains several types and definitions used in the Typedoc converter mechanism.
 // It is not loaded anywhere in Umberto, and should not cause any errors.
 
-/**
- * @typeParameter V Kind string.
- */
-export type TypedocReflectionMeta<V extends string> = {
+import type * as ReflectionKind from './reflectionkind.js';
 
-	/**
-	 * A name of a parser that should process given structure.
-	 */
-	kindString: V;
+export type TypedocCommentItem = {
+	kind: 'text' | 'code' | 'inline-tag';
+	text: string;
 
 	/**
-	 * An internal (Typedoc) kind identifier.
+	 * Available when `kind === 'inline-tag'`.
 	 */
-	kind: number;
+	tag?: string;
 
 	/**
-	 * An identifier used to map reference reflections.
+	 * Available if `tag === '@link'` and it points to an existing reflection.
 	 */
-	id: number;
+	target?: number;
+};
 
-	/**
-	 * A name of a member.
-	 */
+export type BaseReflection<T> = {
+	id: number;
+	kind: T;
 	name: string;
-
+	variant: 'declaration' | 'reference' | 'signature';
 	flags: Record<
 		'isReadonly' | 'isPrivate' | 'isProtected' | 'isPublic' | 'isStatic' | 'isOptional' | 'isRest' | 'isExternal',
 		true | undefined
 	>;
-
 	comment?: {
-
-		/**
-		 * A description of the code. It contains all text found before processing annotations.
-		 */
 		summary: Array<TypedocCommentItem>;
-
-		/**
-		 * Annotations that require additional description, e.g. `@param`.
-		 */
 		blockTags: Array<{
 			tag: `@${ string }`;
 			name: string;
 			content: Array<TypedocCommentItem>;
 		}>;
-
-		/**
-		 * Annotation without descriptions, e.g. `@internal`.
-		 */
 		modifierTags: Array<`@${ string }`>;
 	};
+	sources?: Array<{
+		fileName: string;
+		line: number;
+		character: number;
+		url: string;
+	}>;
+};
+
+export type ProjectReflection = BaseReflection<typeof ReflectionKind.Project> & {
+	children: Array<ModuleReflection>;
+};
+
+export type ModuleReflection = BaseReflection<typeof ReflectionKind.Module> & {
+	children: Array<
+		VariableReflection |
+		FunctionReflection |
+		CKEditor5ErrorReflection |
+		ClassReflection |
+		InterfaceReflection |
+		ReferenceReflection |
+		LiteralObjectReflection
+	>;
+};
+
+export type VariableReflection = BaseReflection<typeof ReflectionKind.Variable> & {
+	type: AvailableTypes;
+	defaultValue: string;
+};
+
+export type ReferenceReflection = BaseReflection<typeof ReflectionKind.Reference> & {
+	variant: 'reference';
+	target: number;
+};
+
+export type LiteralObjectReflection = BaseReflection<typeof ReflectionKind.TypeLiteral> & {
+	type?: LiteralTypeReflection;
 };
 
 /**
- * @typeParam T A name of a parser that should process given structure.
+ * CKEditor 5 structures.
  */
-export type TypedocReflection<T extends TypedocParsers> = TypedocReflectionMeta<T> & {
 
-	/**
-	 * An array of reflections children if the given structure can be a parent. Otherwise, `undefined`.
-	 */
-	children: ChildrenMap[T] extends null ? undefined : Array<ChildrenMap[T]>;
+export type CKEditor5ErrorReflection = BaseReflection<typeof ReflectionKind.Document> & {
+	isCKEditor5Error: true;
+	parameters: Array<ParameterReflection>;
+};
 
-	/**
-	 * An array of parent classes or interfaces that given structure extends.
-	 */
-	extendedTypes: T extends ClassOrInterface ? Array<TypedocReflectionMeta<TypedocParsers>> : undefined;
+export type CKEditor5EventReflection = BaseReflection<typeof ReflectionKind.Document> & {
+	parameters: Array<ParameterReflection>;
+};
 
-	/**
-	 * An array of interfaces that given class implements.
-	 */
-	implementedTypes: T extends 'Class' ? Array<TypedocReflectionMeta<TypedocParsers>> : undefined;
+export type Eventable = {
+	ckeditor5Events: Array<CKEditor5EventReflection>;
+};
 
-	/**
-	 * Type parameters for an interface or a class.
-	 *
-	 * Also, due to lack of knowledge how to create parameters for a custom structure, we keep event arguments here.
-	 */
-	typeParameters: T extends ClassOrInterface | 'Event' ? Array<TypedocReflectionTypeParameter> : undefined;
+/**
+ * OOP.
+ */
 
-	/**
-	 * Type parameters for a constant or a callable expression.
-	 */
-	typeParameter: T extends 'Variable' | 'Method' | 'Function' ? Array<TypedocReflectionTypeParameter> : undefined;
+export type TypeParameterReflection = BaseReflection<typeof ReflectionKind.TypeParameter> & {
+	type?: AvailableTypes;
+	default?: LiteralOrIntrinsic | ReferenceType;
+};
 
-	/**
-	 * For inherited properties, the property contains a parent reflection.
-	 */
-	inheritedFrom: T extends 'Method' | 'Function' ? Record<string, any> : undefined;
+export type Inheritable = {
+	extendedTypes: Array<ReferenceType>;
+	implementedTypes: Array<ReferenceType>;
+	typeParameters: Array<TypeParameterReflection>;
+	inheritedFrom: ReferenceType;
+};
 
-	/**
-	 * The `signatures` property exists only for callable doclets.
-	 */
-	signatures: T extends ConstructorOrMethod | 'Function' ? Array<TypedocCallSignature> : undefined;
+export type ClassReflection = BaseReflection<typeof ReflectionKind.Class> & Inheritable & Eventable & {
+	children: Array<AccessorReflection | ConstructorReflection | MethodReflection | PropertyReflection>;
+};
 
-	/**
-	 * A value defined by an exported constant (`export const ...`).
-	 */
-	defaultValue: T extends 'Variable' ? TypedocReflectionType : undefined;
+export type InterfaceReflection = BaseReflection<typeof ReflectionKind.Interface> & Inheritable & Eventable & {
+	children: Array<AccessorReflection | MethodReflection | PropertyReflection>;
+};
 
-	/**
-	 * The `setSignature` and `getSignature` exist only when processing a getter or/and setter.
-	 *
-	 * However, the getter does not allow setting a value. The `set*` property does not exist in such a case.
-	 * The same applies to setters and their `get*` properties.
-	 */
-	setSignature?: T extends 'Accessor' ? TypedocCallSignature : undefined;
-	getSignature?: T extends 'Accessor' ? TypedocCallSignature : undefined;
+export type AccessorReflection = BaseReflection<typeof ReflectionKind.Accessor> & {
+	getSignature: Omit<
+		CallSignatureReflection<typeof ReflectionKind.GetSignature>,
+		'typeParameters' | 'parameters'
+	>;
+	setSignature: Omit<
+		CallSignatureReflection<typeof ReflectionKind.SetSignature>,
+		'typeParameters'
+	>;
+};
 
-	/**
-	 * An array of sources that defines given structure.
-	 */
-	sources?: Array<TypedocSource>;
-	originalName?: string;
+export type PropertyReflection = BaseReflection<typeof ReflectionKind.Property> & {
+	type: AvailableTypes;
 };
 
-export type TypedocReflectionType = TypedocReflectionMeta<'Parameter'> & {
-	type: TypedocTypeDetails;
-	elementType?: TypedocTypeDetails;
-	declaration?: {
-		signatures?: Array<TypedocCallSignature>;
-		children?: Array<TypedocReflection<TypedocParsers>>;
-	};
-	types?: Array<TypedocReflectionType>;
-	defaultValue?: string;
+export type ComputedPropertyReflection = BaseReflection<typeof ReflectionKind.IndexSignature>;
+
+/**
+ * Callables.
+ */
+
+export type TypedocCallable<T> = {
+	signatures: Array<CallSignatureReflection<T>>;
 };
 
-export type TypedocReflectionTypeParameter = TypedocReflectionMeta<'Type parameter'> & TypedocTypeDetails & {
-	default?: TypedocTypeDetails;
-	type?: TypedocReflectionType;
+export type ParameterReflection = BaseReflection<typeof ReflectionKind.Parameter> & {
+	type: AvailableTypes;
 };
 
-export type TypedocCallSignature = TypedocReflectionMeta<'Call signature'> & {
-	type: TypedocReflectionType;
-	parameters?: Array<TypedocReflectionType>;
-	inheritedFrom?: Record<string, any>;
+export type CallSignatureReflection<T> = BaseReflection<T> & {
+	type: AvailableTypes;
+	parameters?: Array<ParameterReflection>;
+	typeParameters?: Array<TypeParameterReflection>;
+	inheritedFrom?: ReferenceType;
+	children?: Array<PropertyReflection>;
+	indexSignatures?: Array<IndexSignatureType>;
 };
 
-export type TypedocTypeDetails = string | LiteralOrIntrinsic | Reference | TypeOperator |
-	{
-		type: 'union';
-		types: Array<TypedocReflectionType>;
-	} |
-	{
-		type: 'array';
-		elementType: TypedocTypeDetails;
-	} |
-	{
-		type: 'indexedAccess';
-		objectType: TypedocTypeDetails;
-		indexType: TypedocTypeDetails;
-	} |
-	{
-		type: 'reflection';
-		declaration: {
-			signatures?: Array<TypedocCallSignature>;
-		};
-	} |
-	{
-		type: 'tuple';
-		elements: Array<TypedocTypeDetails>;
-	} |
-	{
-		type: 'named-tuple-member';
-		element: TypedocTypeDetails;
-	} |
-	{
-		type: 'intersection';
-		types: Array<TypedocReflectionType>;
-	} |
-	{
-		type: 'query';
-		queryType: {
-			name: string;
-		};
-	} |
-	{
-		type: 'mapped';
-		parameter: string;
-		parameterType?: TypeOperator | string;
-		templateType: LiteralOrIntrinsic;
-		optionalModifier?: string;
-	} |
-	{
-		type: 'conditional';
-		checkType: Reference;
-		extendsType: TypedocTypeDetails;
-		trueType: TypedocTypeDetails;
-		falseType: TypedocTypeDetails;
-	} |
-	{
-		type: 'template-literal';
-		tail: Array<{
-			type: TypedocTypeDetails;
-			suffix: string;
-		}>;
-		head: string;
-	} |
-	{
-		type: 'predicate';
-		targetType: TypedocTypeDetails;
+export type ConstructorReflection =
+	BaseReflection<typeof ReflectionKind.Constructor> & TypedocCallable<typeof ReflectionKind.ConstructorSignature>;
+
+export type MethodReflection =
+	BaseReflection<typeof ReflectionKind.Method> & TypedocCallable<typeof ReflectionKind.CallSignature>;
+
+export type FunctionReflection =
+	BaseReflection<typeof ReflectionKind.Function> & TypedocCallable<typeof ReflectionKind.CallSignature>;
+
+/**
+ * Types.
+ */
+
+export type AvailableTypes = string |
+	LiteralOrIntrinsic |
+	ReferenceType |
+	TypeOperator |
+	LiteralTypeReflection |
+	UnionType |
+	ArrayType |
+	IndexAccessType |
+	TupleType |
+	NamedTupleMemberType |
+	IntersectionType |
+	QueryType |
+	MappedType |
+	ConditionalType |
+	TemplateLiteralType |
+	PredicateType;
+
+export type LiteralTypeReflection = BaseReflection<typeof ReflectionKind.TypeLiteral> & {
+	type: 'reflection';
+	declaration?: {
+		name: '__type';
+		children?: Array<PropertyReflection>;
+		signatures?: TypedocCallable<typeof ReflectionKind.CallSignature>;
+		indexSignatures?: Array<IndexSignatureType>;
 	};
+};
 
-export type TypedocCommentItem = {
-	kind: 'text' | 'code' | 'inline-tag';
-	text: string;
+export type IndexSignatureType = BaseReflection<typeof ReflectionKind.IndexSignature> & {
+	name: '__index';
+	variant: 'signature';
+	parameters: Array<ParameterReflection>;
+	type: AvailableTypes;
+};
 
-	/**
-	 * Available when `kind === 'inline-tag'`.
-	 */
-	tag?: string;
+export type UnionType = {
+	type: 'union';
+	types: Array<LiteralTypeReflection>;
+};
 
-	/**
-	 * Available if `tag === '@link'` and it points to an existing reflection.
-	 */
-	target?: number;
+export type ArrayType = {
+	type: 'array';
+	elementType: AvailableTypes;
 };
 
-/**
- * Available parsers for processing reflections.
- */
-export type TypedocParsers = keyof ChildrenMap;
+export type IndexAccessType = {
+	type: 'indexedAccess';
+	objectType: AvailableTypes;
+	indexType: AvailableTypes;
+};
 
-/**
- * An alias for callable properties from a class or an interface.
- */
-export type ConstructorOrMethod = 'Constructor' | 'Method';
+export type TupleType = {
+	type: 'tuple';
+	elements: Array<AvailableTypes>;
+};
 
-/**
- * An alias for types that contains children.
- */
-type ClassOrInterface = 'Class' | 'Interface';
+export type NamedTupleMemberType = {
+	type: 'namedTupleMember';
+	element: AvailableTypes;
+};
 
-/**
- * A map containing the possible types of children for a given parent type.
- */
-type ChildrenMap = {
-	// Root.
-	Module: TypedocReflection<ClassOrInterface | 'Function' | 'Type alias' | 'Error' | 'Variable'>;
+export type IntersectionType = {
+	type: 'intersection';
+	types: Array<LiteralTypeReflection>;
+};
 
-	// Module children.
-	Class: TypedocReflection<ConstructorOrMethod | 'Event' | 'Accessor' | 'Property'>;
-	Interface: TypedocReflection<ConstructorOrMethod | 'Event' | 'Accessor' | 'Property'>;
-	Function: null;
-	'Type alias': null;
-	Error: null;
-	Variable: null;
+export type QueryType = {
+	type: 'query';
+	queryType: {
+		name: string;
+	};
+};
 
-	// Class/interface children.
-	Constructor: null;
-	Method: null;
-	Property: null;
-	Accessor: null;
-	Event: null;
+export type MappedType = {
+	type: 'mapped';
+	parameter: string;
+	parameterType?: TypeOperator | string;
+	templateType: LiteralOrIntrinsic;
+	optionalModifier?: string;
+};
 
-	// A special "parser" that points to an existing doclet that most probably has been already converted.
-	Reference: null;
+export type ConditionalType = {
+	type: 'conditional';
+	checkType: ReferenceType;
+	extendsType: AvailableTypes;
+	trueType: AvailableTypes;
+	falseType: AvailableTypes;
+};
 
-	// To detect if a specified argument is a class instance or a function.
-	'Constructor signature': null;
+export type TemplateLiteralType = {
+	type: 'templateLiteral';
+	tail: Array<{
+		type: AvailableTypes;
+		suffix: string;
+	}>;
+	head: string;
 };
 
-type TypedocSource = {
-	fileName: string;
-	line: number;
-	character: number;
-	url: string;
+export type PredicateType = {
+	type: 'predicate';
+	targetType: AvailableTypes;
 };
 
-type Reference = {
+export type ReferenceType = {
 	type: 'reference';
-	name: string;
-	id?: number;
-	typeArguments?: Array<TypedocReflectionTypeParameter>;
+	target: number | {
+		packageName: 'typescript';
+		packagePath: string;
+		qualifiedName: string;
+	};
+	typeArguments?: Array<TypeParameterReflection>;
 };
 
-type TypeOperator = {
+export type TypeOperator = {
 	type: 'typeOperator';
 	operator: string;
-	target: Reference;
+	target: ReferenceType;
 };
 
 type LiteralOrIntrinsic =