[INTERNAL] JSDoc: Add validation for since version

For experimental and deprecated tags the version
is indicated by certain tags
e.g. "as of version", "since version".

JIRA: CPOUI5FOUNDATION-329

Cherry picked from: SAP/openui5@f750709

lib/processors/jsdoc/lib/ui5/template/publish.js

@@ -27,6 +27,8 @@ const info = logger.info.bind(logger);
 const warning = logger.warn.bind(logger);
 const error = logger.error.bind(logger);
 
+const {extractVersion, extractSince} = require("./utils/versionUtil");
+
 /* errors that might fail the build in future */
 function future(msg) {
 	if ( logger.getLevel() >= logger.LEVELS.WARN ) {
@@ -1110,55 +1112,6 @@ function publishClasses(symbols, aRootNamespaces, hierarchyRoots) {
 
 // ---- helper functions for the templates ----
 
-const rSinceVersion = /^([0-9]+(?:\.[0-9]+(?:\.[0-9]+)?)?([-.][0-9A-Z]+)?)(?:\s|$)/i;
-
-function extractVersion(value) {
-
-	if ( !value ) {
-		return undefined;
-	}
-
-	if ( value === true ) {
-		value = '';
-	} else {
-		value = String(value);
-	}
-
-	const m = rSinceVersion.exec(value);
-	return m ? m[1] : undefined;
-
-}
-
-const rSince = /^(?:as\s+of|since)(?:\s+version)?\s*([0-9]+(?:\.[0-9]+(?:\.[0-9]+)?)?([-.][0-9A-Z]+)?)(?:\.$|\.\s+|[,:]\s*|\s-\s*|\s|$)/i;
-
-function extractSince(value) {
-
-	if ( !value ) {
-		return undefined;
-	}
-
-	if ( value === true ) {
-		value = '';
-	} else {
-		value = String(value);
-	}
-
-	const m = rSince.exec(value);
-	if ( m ) {
-		return {
-			since : m[1],
-			pos : m[0].length,
-			value : value.slice(m[0].length).trim()
-		};
-	}
-
-	return {
-		pos : 0,
-		value: value.trim()
-	};
-
-}
-
 function sortByAlias(a, b) {
 	const partsA = a.longname.split(/[.#]/);
 	const partsB = b.longname.split(/[.#]/);
@@ -2408,6 +2361,10 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 		if ( info.since ) {
 			attrib("since", info.since);
 		}
+		if (info.since === null) {
+			future(`**** Failed to parse version in string '${value}'. ` +
+				`Version might be missing or has an unexpected format.`)
+		}
 		if ( info.value ) {
 			curr["text"] = normalizeWS(info.value);
 		}

lib/processors/jsdoc/lib/ui5/template/utils/versionUtil.js

@@ -0,0 +1,118 @@
+
+
+const rSinceVersion = /^([0-9]+(?:\.[0-9]+(?:\.[0-9]+)?)?([-.][0-9A-Z]+)?)(\.$|\.\s+|[,:]\s*|\s-\s*|\s|$)/i;
+function _parseVersion(value) {
+	const m = rSinceVersion.exec(value);
+	if (m) {
+		// 3rd capture group contains additional characters such as ,: -
+		// version is either at its own or text is separated by space
+		var versionFollowedBySpace = m[3] === "" || /^\s/.test(m[3]);
+		return {
+			version: m[1],
+			versionFollowedBySpace: versionFollowedBySpace,
+			nextPosition: m[0].length
+		}
+	}
+}
+
+/**
+ * Extracts version
+ *
+ * @example valid versions
+ * "1.33.4 "
+ * "1.334"
+ */
+function extractVersion(value) {
+
+	if ( !value ) {
+		return undefined;
+	}
+
+	if ( value === true ) {
+		value = '';
+	} else {
+		value = String(value);
+	}
+
+	const parseResult = _parseVersion(value);
+	if (parseResult && parseResult.versionFollowedBySpace) {
+		return parseResult.version;
+	}
+}
+
+const rSinceIndicator = /^(?:as\s+of|since)(?:\s+version)?\s*/i
+
+/**
+ * Extracts since information from given value.
+ *
+ * <code>
+ * pos: position of additional text
+ * since: version information
+ * text: additional text
+ * </code>
+ *
+ * @example version indication with valid version
+ * Input: "Since version 1.3.4. mytext"
+ * Output:
+ * { pos: 21, since: '1.3.4', value: 'mytext' }
+ *
+ * @example version indication without valid version
+ * Input: "Since version mytext"
+ * Output:
+ * { pos: 0, since: null, value: 'Since version mytext.' }
+ *
+ * @example no indicator and no version present
+ * Input: "mytext"
+ * Output:
+ * { pos: 0, value: 'mytext.' }
+ *
+ *
+ *
+ * @param {string|boolean} value
+ * @returns {{pos: number, value: string, since: string|null|undefined}}
+ * undefined: value is falsy
+ */
+function extractSince(value) {
+
+	if ( !value ) {
+		return undefined;
+	}
+
+	if ( value === true ) {
+		value = '';
+	} else {
+		value = String(value);
+	}
+
+	const mSinceIndicator = rSinceIndicator.exec(value);
+	if (mSinceIndicator) {
+		const iSinceIndicatorLength = mSinceIndicator[0].length;
+		const versionAndText = value.substring(iSinceIndicatorLength);
+		const parseResult = _parseVersion(versionAndText);
+		if ( parseResult ) {
+			const textPosition = iSinceIndicatorLength + parseResult.nextPosition;
+			return {
+				since : parseResult.version,
+				pos : textPosition,
+				value : value.slice(textPosition).trim()
+			};
+		}
+		// since indicator present but version cannot be extracted
+		return {
+			since: null,
+			pos : 0,
+			value: value.trim()
+		};
+	}
+
+	return {
+		pos : 0,
+		value: value.trim()
+	};
+
+}
+
+module.exports = {
+	extractSince,
+	extractVersion
+}