@ckeditor/ckeditor5-dev-docs 47.1.1 → 49.0.0

package/lib/build.js

@@ -4,10 +4,9 @@
  */
 
 import { glob } from 'glob';
-import TypeDoc from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-import validators from './validators/index.js';
+import upath from 'upath';
+import { Application, OptionDefaults } from 'typedoc';
+import * as plugins from '@ckeditor/typedoc-plugins';
 
 /**
  * Builds CKEditor 5 documentation using `typedoc`.
@@ -16,78 +15,76 @@ import validators from './validators/index.js';
  * @returns {Promise}
  */
 export default async function build( config ) {
-	const { plugins } = typedocPlugins;
 	const sourceFilePatterns = config.sourceFiles.filter( Boolean );
-	const strictMode = config.strict || false;
 	const extraPlugins = config.extraPlugins || [];
 	const ignoreFiles = config.ignoreFiles || [];
-	const validatorOptions = config.validatorOptions || {};
+	const validatorOptions = config.validatorOptions || {
+		strict: false
+	};
+	const verbose = config.verbose || false;
 
-	const files = await glob( sourceFilePatterns, {
+	const files = ( await glob( sourceFilePatterns, {
 		ignore: ignoreFiles
-	} );
-	const typeDoc = new TypeDoc.Application();
+	} ) ).map( upath.normalize );
 
-	typeDoc.options.addReader( new TypeDoc.TSConfigReader() );
-	typeDoc.options.addReader( new TypeDoc.TypeDocReader() );
-
-	typeDoc.bootstrap( {
+	const app = await Application.bootstrapWithPlugins( {
 		tsconfig: config.tsconfig,
 		excludeExternals: true,
+		excludePrivate: false,
 		entryPoints: files,
-		logLevel: 'Warn',
+		logLevel: verbose ? 'Info' : 'Warn',
 		basePath: config.cwd,
+		readme: 'none',
+
 		blockTags: [
+			...OptionDefaults.blockTags,
 			'@eventName',
-			'@default'
+			'@export',
+			'@fires',
+			'@label',
+			'@observable',
+			'@error'
 		],
 		inlineTags: [
-			'@link',
+			...OptionDefaults.inlineTags,
 			'@glink'
 		],
 		modifierTags: [
+			...OptionDefaults.modifierTags,
 			'@publicApi',
-			'@skipSource',
-			'@internal'
+			'@skipSource'
 		],
 		plugin: [
 			// Fixes `"name": 'default" in the output project.
 			'typedoc-plugin-rename-defaults',
-
-			plugins[ 'typedoc-plugin-module-fixer' ],
-			plugins[ 'typedoc-plugin-symbol-fixer' ],
-			plugins[ 'typedoc-plugin-interface-augmentation-fixer' ],
-			plugins[ 'typedoc-plugin-tag-error' ],
-			plugins[ 'typedoc-plugin-tag-event' ],
-			plugins[ 'typedoc-plugin-tag-observable' ],
-			plugins[ 'typedoc-plugin-purge-private-api-docs' ],
-
-			// The `event-inheritance-fixer` plugin must be loaded after `tag-event` plugin, as it depends on its output.
-			plugins[ 'typedoc-plugin-event-inheritance-fixer' ],
-
-			// The `event-param-fixer` plugin must be loaded after `tag-event` and `tag-observable` plugins, as it depends on their output.
-			plugins[ 'typedoc-plugin-event-param-fixer' ],
-
 			...extraPlugins
 		]
 	} );
 
+	plugins.typeDocRestoreProgramAfterConversion( app );
+	plugins.typeDocModuleFixer( app );
+	plugins.typeDocSymbolFixer( app );
+	plugins.typeDocTagError( app );
+	plugins.typeDocTagEvent( app );
+	plugins.typeDocTagObservable( app );
+	plugins.typeDocEventParamFixer( app );
+	plugins.typeDocEventInheritanceFixer( app );
+	plugins.typeDocInterfaceAugmentationFixer( app );
+	plugins.typeDocPurgePrivateApiDocs( app );
+	plugins.typeDocReferenceFixer( app );
+	plugins.typeDocOutputCleanUp( app );
+	plugins.validate( app, validatorOptions );
+
 	console.log( 'Typedoc started...' );
 
-	const conversionResult = typeDoc.convert();
+	const conversionResult = await app.convert();
 
 	if ( !conversionResult ) {
 		throw 'Something went wrong with TypeDoc.';
 	}
 
-	const validationResult = validators.validate( conversionResult, typeDoc, validatorOptions );
-
-	if ( !validationResult && strictMode ) {
-		throw 'Something went wrong with TypeDoc.';
-	}
-
 	if ( config.outputPath ) {
-		await typeDoc.generateJson( conversionResult, config.outputPath );
+		await app.generateJson( conversionResult, config.outputPath );
 	}
 
 	console.log( `Documented ${ files.length } files!` );
@@ -108,6 +105,9 @@ export default async function build( config ) {
  *
  * @property {boolean} [strict=false] If `true`, errors found during the validation will finish the process
  * and exit code will be changed to `1`.
+ *
+ * @property {boolean} [verbose=false] If `true`, the output will be verbose.
+ *
  * @property {string} [outputPath] A path to the place where extracted doclets will be saved. Is an optional value due to tests.
  *
  * @property {string} [extraPlugins=[]] An array of path to extra plugins that will be added to Typedoc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-dev-docs",
-  "version": "47.1.1",
+  "version": "49.0.0",
   "description": "Tasks used to build and verify the documentation for CKEditor 5.",
   "keywords": [],
   "author": "CKSource (http://cksource.com/)",
@@ -22,12 +22,10 @@
     "lib"
   ],
   "dependencies": {
-    "@ckeditor/ckeditor5-dev-utils": "^47.1.1",
-    "@ckeditor/typedoc-plugins": "^47.1.1",
-    "glob": "^10.0.0",
-    "fs-extra": "^11.0.0",
-    "tmp": "^0.2.1",
-    "typedoc": "^0.23.15",
-    "typedoc-plugin-rename-defaults": "0.6.6"
+    "@ckeditor/typedoc-plugins": "^49.0.0",
+    "glob": "^11.0.1",
+    "typedoc": "0.28.4",
+    "typedoc-plugin-rename-defaults": "^0.7.3",
+    "upath": "^2.0.1"
   }
 }

package/lib/validators/fires-validator/index.js

@@ -1,58 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import { ReflectionKind } from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-/**
- * Validates the output produced by TypeDoc.
- *
- * It checks if the event in the "@fires" tag exists.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {function} onError A callback that is executed when a validation error is detected.
- */
-export default function validate( project, onError ) {
-	const { utils } = typedocPlugins;
-	const reflections = project
-		.getReflectionsByKind( ReflectionKind.Class | ReflectionKind.CallSignature )
-		.filter( utils.isReflectionValid );
-
-	for ( const reflection of reflections ) {
-		const identifiers = getIdentifiersFromFiresTag( reflection );
-
-		if ( !identifiers.length ) {
-			continue;
-		}
-
-		for ( const identifier of identifiers ) {
-			const isValid = utils.isIdentifierValid( reflection, identifier );
-
-			if ( !isValid ) {
-				const eventName = identifier.replace( /^#event:/, '' );
-
-				onError( `Incorrect event name: "${ eventName }" in the @fires tag`, reflection );
-			}
-		}
-	}
-}
-
-function getIdentifiersFromFiresTag( reflection ) {
-	const { utils } = typedocPlugins;
-
-	if ( !reflection.comment ) {
-		return [];
-	}
-
-	return reflection.comment.getTags( '@fires' )
-		.flatMap( tag => tag.content.map( item => item.text.trim() ) )
-		.map( identifier => {
-			if ( utils.isAbsoluteIdentifier( identifier ) ) {
-				return identifier;
-			}
-
-			return '#event:' + identifier;
-		} );
-}

package/lib/validators/index.js

@@ -1,57 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-import seeValidator from './see-validator/index.js';
-import linkValidator from './link-validator/index.js';
-import firesValidator from './fires-validator/index.js';
-import moduleValidator from './module-validator/index.js';
-import overloadsValidator from './overloads-validator/index.js';
-
-/**
- * Validates the CKEditor 5 documentation.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {object} typeDoc A TypeDoc application instance.
- * @param {TypedocValidator} [options={}] A configuration object.
- * @returns {boolean}
- */
-export default {
-	validate( project, typeDoc, options = {} ) {
-		const { utils } = typedocPlugins;
-		const validators = [
-			seeValidator,
-			linkValidator,
-			firesValidator,
-			moduleValidator
-		];
-
-		if ( options.enableOverloadValidator ) {
-			validators.push( overloadsValidator );
-		}
-
-		typeDoc.logger.info( 'Starting validation...' );
-
-		// The same error can be reported twice:
-		//
-		// 1. When processing types and events (comments are copied from a type to an event).
-		// 2. When a parent class defines an invalid link, inherited members link to the invalid link too.
-		const errors = new Map();
-
-		for ( const validator of validators ) {
-			validator( project, ( error, reflection ) => {
-				const node = utils.getNode( reflection );
-
-				errors.set( node, { error, node } );
-			} );
-		}
-
-		errors.forEach( ( { error, node } ) => typeDoc.logger.warn( error, node ) );
-
-		typeDoc.logger.info( 'Validation completed.' );
-
-		return !errors.size;
-	}
-};

package/lib/validators/link-validator/index.js

@@ -1,58 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import { ReflectionKind } from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-/**
- * Validates the output produced by TypeDoc.
- *
- * It checks if the identifier in the "@link" tag points to an existing doclet.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {function} onError A callback that is executed when a validation error is detected.
- */
-export default function validate( project, onError ) {
-	const { utils } = typedocPlugins;
-	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
-
-	for ( const reflection of reflections ) {
-		const identifiers = getIdentifiersFromLinkTag( reflection );
-
-		if ( !identifiers.length ) {
-			continue;
-		}
-
-		for ( const identifier of identifiers ) {
-			const isValid = utils.isIdentifierValid( reflection, identifier );
-
-			if ( !isValid ) {
-				onError( `Incorrect link: "${ identifier }"`, reflection );
-			}
-		}
-	}
-}
-
-function getIdentifiersFromLinkTag( reflection ) {
-	if ( !reflection.comment ) {
-		return [];
-	}
-
-	// The "@link" tag can be located in the comment summary or it can be nested in other block tags.
-	const parts = [
-		...reflection.comment.summary,
-		...reflection.comment.blockTags.flatMap( tag => tag.content )
-	];
-
-	return parts
-		.filter( part => part.kind === 'inline-tag' && part.tag === '@link' )
-		.map( part => {
-			// The "@link" tag may contain the actual identifier and the display name after a space.
-			// Split by space to extract only the identifier from the whole tag.
-			const [ identifier ] = part.text.split( ' ' );
-
-			return identifier;
-		} );
-}

package/lib/validators/module-validator/index.js

@@ -1,55 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import { ReflectionKind } from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-const AUGMENTATION_MODULE_REGEXP = /[^\\/]+[\\/]src[\\/]augmentation/;
-
-/**
- * Validates the output produced by TypeDoc.
- *
- * It checks if the module name matches the path to the file where the module is defined.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {function} onError A callback that is executed when a validation error is detected.
- */
-export default function validate( project, onError ) {
-	const { utils } = typedocPlugins;
-	const reflections = project.getReflectionsByKind( ReflectionKind.Module );
-
-	for ( const reflection of reflections ) {
-		// The augmentation module does not contain the `@module` annotation. We need to skip it.
-		if ( reflection.name.match( AUGMENTATION_MODULE_REGEXP ) ) {
-			continue;
-		}
-
-		const [ packageName, ...moduleName ] = reflection.name.split( '/' );
-
-		// If there is no module name after the package name, skip it.
-		if ( !moduleName.length ) {
-			continue;
-		}
-
-		const node = utils.getNode( reflection );
-
-		// Not a ES6 module.
-		if ( !node ) {
-			continue;
-		}
-
-		const filePath = node.fileName;
-
-		if ( filePath.endsWith( 'src/augmentation.ts' ) ) {
-			continue;
-		}
-
-		const expectedFilePath = `ckeditor5-${ packageName }/src/${ moduleName.join( '/' ) }.ts`;
-
-		if ( !filePath.endsWith( expectedFilePath ) ) {
-			onError( `Invalid module name: "${ reflection.name }"`, reflection );
-		}
-	}
-}

package/lib/validators/overloads-validator/index.js

@@ -1,54 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import { ReflectionKind } from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-// The `@label` validator is currently not used.
-// See: https://github.com/ckeditor/ckeditor5/issues/13591.
-
-/**
- * Validates the output produced by TypeDoc.
- *
- * It checks if overloaded methods and functions are described with the mandatory "@label" tag.
- *
- * Also, it prevents using the same name twice for overloaded structures.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {function} onError A callback that is executed when a validation error is detected.
- */
-export default function validate( project, onError ) {
-	const { utils } = typedocPlugins;
-	const kinds = ReflectionKind.Method | ReflectionKind.Constructor | ReflectionKind.Function;
-	const reflections = project.getReflectionsByKind( kinds ).filter( utils.isReflectionValid );
-
-	for ( const reflection of reflections ) {
-		// Omit non-overloaded structures.
-		if ( reflection.signatures.length === 1 ) {
-			continue;
-		}
-
-		const uniqueValues = new Set();
-
-		const isInherited = !!reflection.inheritedFrom;
-		const errorMessageSuffix = isInherited ? ' due the inherited structure' : '';
-
-		for ( const signature of reflection.signatures ) {
-			// Check if a signature has a label...
-			if ( signature.comment && signature.comment.getTag( '@label' ) ) {
-				const [ { text: label } ] = signature.comment.getTag( '@label' ).content;
-
-				// ...and whether it is a unique value.
-				if ( uniqueValues.has( label ) ) {
-					onError( `Duplicated name: "${ label }" in the @label tag` + errorMessageSuffix, signature );
-				} else {
-					uniqueValues.add( label );
-				}
-			} else {
-				onError( 'Overloaded signature misses the @label tag' + errorMessageSuffix, signature );
-			}
-		}
-	}
-}

package/lib/validators/see-validator/index.js

@@ -1,58 +0,0 @@
-/**
- * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-import { ReflectionKind } from 'typedoc';
-import typedocPlugins from '@ckeditor/typedoc-plugins';
-
-/**
- * Validates the output produced by TypeDoc.
- *
- * It checks if the identifier in the "@see" tag points to an existing doclet.
- *
- * @param {object} project Generated output from TypeDoc to validate.
- * @param {function} onError A callback that is executed when a validation error is detected.
- */
-export default function validate( project, onError ) {
-	const { utils } = typedocPlugins;
-	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
-
-	for ( const reflection of reflections ) {
-		const identifiers = getIdentifiersFromSeeTag( reflection );
-
-		if ( !identifiers.length ) {
-			continue;
-		}
-
-		for ( const identifier of identifiers ) {
-			const isValid = utils.isIdentifierValid( reflection, identifier );
-
-			if ( !isValid ) {
-				onError( `Incorrect link: "${ identifier }"`, reflection );
-			}
-		}
-	}
-}
-
-function getIdentifiersFromSeeTag( reflection ) {
-	if ( !reflection.comment ) {
-		return [];
-	}
-
-	return reflection.comment.getTags( '@see' )
-		.flatMap( tag => tag.content.map( item => item.text.trim() ) )
-		.filter( text => {
-			// Remove list markers (e.g. "-").
-			if ( text.length <= 1 ) {
-				return false;
-			}
-
-			// Remove external links.
-			if ( /^https?:\/\//.test( text ) ) {
-				return false;
-			}
-
-			return true;
-		} );
-}