umberto 6.1.1 → 7.0.0

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 =