[FEATURE] jsdoc: Support destructuring of enums for defaultValue (#775)

* ES6 destructuring of UI5 enums

- Use escope to go up through the chain
- Cover destructuring and build up a fully quantified name up to the imported module name
- Cover renaming
- Cover multiple destructuring

* Refactor plugin.js and reorder code

* Modify fixtres with destructuring cases

* Bugfix: Add arrow functions into the scope

* Tests: Modify expectations to cover destructuring cases

* Add copyright for the dependencies

* Tests: Align expectations w/ fixtures

* Bugfixing for destructuring

* Destructuring at function paramers

* Update documentation

* Cover cases where the var after destructuring does not look like an ENUM

* Enable the known test cases

* Test: Align expectations with fixtures

* Refactoring

* Refactor: Cover cases from MVN plugin + cleanup

* Refactor getEnclosingVariableScope to be more generic

* Fix typos

* Fix test cases

* Resolve destructuring in the parametter and consider var renaming

* Update samples to support destructuring w/ rename as func argument

* Add failing rename test case

* Var renaming while generating fully quantified name fixed

* Adjust tests

* Put renamed var as key in the localNames

* Remove optional chaining in plugin as we need to support node 12

* Adjust tests

* Fixe comments

* Replace regex with string comparisson function

* Cleanups

* Typo fixes

* Store expected api.json as beautified json

* Remove renaming

* Remove commented code

* Make tests closer to the real world naming and usage

* Modify tests to fit more likely on the real world scenarios

* Beautify api.json

* Make tests more production like

* Bugfix: Properly define dependencies

* Align with UI5 repo comments

* Align with OpenUI5 repo

* Align with UI5

* Refactor: checkVarRenaming

We cannot process variables with multiple definitions as we need to do
analysis which is far beoyund our capabilities. This limitiation on the other
side, gives us the opportunity to greatly simplify and reduce the code.

We could process eiter a destructure function argument or a
variable defintion

* Refactor fully qunitified name resolver

* Support aria.hasPopup case

* Refactor code and introducce isVarDestructuring()

* Align with OpenUI5

* Define new scenarios for destructuring

- Nested ObjectPattern destructuring
- ArrayPattern handling
- ArrayPattern + (nested) ObjectPattern

* Handle ObjectPattern nested destructuring in arguments

Basic handling of ArrayPattern in Arguments

* Additional test cases

* Refactor arguments handler to cover ObjectPattern, ArrayPattern & mixture of them

* Make ObjectPattern resolver reusable

* Adjust tests

* Include "path" to the resolved variables

* Refactor getFuncArgumentDestructNode() and include ArrayPattern in destructor detection

* Fix test cases

* Fix tests

* Fix for path resolving

* Enahnce with the new test cases

* Add FunctionDeclaration && FunctionExpression

* Revise ArrayPattern handling

* Include indices in the path for the ArrayPattern

* Fix test cases for ArrayPattern

* Refactor resolveFullyQuantifiedName()

* Refactor resolveObjectPatternChain()

* Remove names from ArrayPattern: makes no sense

* Fix tests

* Aquire proper scope (bugfix)

* Formatting fixes & minor refactoring

* Consistent returns

Co-authored-by: Matthias Osswald <mat.osswald@sap.com>

test/expected/build/library.j/dest/resources/library/j/SubControl.js

@@ -0,0 +1,45 @@
+/*!
+ * ${copyright}
+ */
+
+/**
+ * Covers:
+ * - ArrowFunctionExpression
+ */
+ window.someRandomModule ||
+ sap.ui.define(
+	 ["sap/ui/core/Control"],
+	 /**
+	  * Constructor for a new library.j.SubControl.
+	  *
+	  * @param {string} [sId] ID for the new control, generated automatically if no ID is given
+	  * @param {object} [mSettings] Initial settings for the new control
+	  *
+	  * @class
+	  *
+	  * @author SAP SE
+	  * @version ${version}
+	  *
+	  * @constructor
+	  * @extends sap.ui.core.Control
+	  * @public
+	  * @since 1.22
+	  * @alias library.j.SubControl
+	  */
+	 (Control) =>
+		 Control.extend(`library.j.SubControl`, {
+			 metadata: {
+				 properties: {
+					 /**
+					  * MyProp property
+					  * @since 1.46
+					  */
+					 MyProp: {
+						 type: "boolean",
+						 group: `Misc`,
+						 defaultValue: false,
+					 },
+				 },
+			 },
+		 })
+ );

test/expected/build/library.j/dest/resources/library/j/ValidPropertyDefaultValue.js

@@ -0,0 +1,184 @@
+/*!
+ * ${copyright}
+ */
+sap.ui.define(
+	[
+		"sap/ui/core/Control",
+		"./library",
+		"./core/library",
+		"sap/external/thirdparty/library",
+		"sap/external2/thirdparty/library",
+		"sap/external3/thirdparty/library",
+	],
+	(
+		Control,
+		{ MyValidEnum, ThisIsEnumToo: RenamedEnum },
+		coreLibrary,
+		[ {arrPattern}, {arrWith: {deep: arrPatternDeepDestruct}}],
+		{ objPattern: {deeply: {destructured: objPatternDeepDestruct}, objPattern1Lvl} },
+		libraryExt
+	) => {
+		const { AnotherValidEnum } = coreLibrary;
+		const { Buzz } = AnotherValidEnum;
+		const { AnotherValidEnum: {Buzz: BuzzRenamed} } = coreLibrary;
+		const { AnotherValidEnum: AnotherRenamedEnum } = coreLibrary;
+		const { H1 } = sap.ui.core.TitleLevel;
+		const { Value2: RenamedValue2 } = RenamedEnum;
+		const [ {arrPatternVarDef}, {nested: {arrPatternVarDef: arrPatternVarDefNestedAndRenamed}} ] = libraryExt;
+
+		/**
+		 * @class
+		 * My super documentation of this class
+		 *
+		 * @extends sap.ui.core.Control
+		 *
+		 * @author SAP SE
+		 * @version ${version}
+		 *
+		 * @public
+		 * @alias library.j.ValidPropertyDefaultValue
+		 * @ui5-metamodel text
+		 */
+		var ValidPropertyDefaultValue = Control.extend(
+			"library.j.ValidPropertyDefaultValue",
+			{
+				metadata: {
+					properties: {
+						/**
+						 * validPropertyDefaultValueEnumSimpleDestructuring
+						 */
+						validPropertyDefaultValueEnumSimpleDestructuring: {
+							type: "library.j.core.AnotherValidEnum",
+							group: "Misc",
+							defaultValue: AnotherValidEnum.Buzz
+						},
+
+						/**
+						 * validPropertyDefaultValueEnumChainedDestructuring
+						 */
+						 validPropertyDefaultValueEnumChainedDestructuring: {
+							type: "library.j.core.AnotherValidEnum",
+							group: "Misc",
+							defaultValue: Buzz
+						},
+
+						/**
+						 * validPropertyDefaultValueEnumNestedDestructuring
+						 */
+						 validPropertyDefaultValueEnumNestedDestructuring: {
+							type: "library.j.core.AnotherValidEnum",
+							group: "Misc",
+							defaultValue: BuzzRenamed
+						},
+
+						/**
+						 * validPropertyDefaultValueEnumDestructuringWithRename
+						 */
+						validPropertyDefaultValueEnumDestructuringWithRename: {
+							type: "library.j.core.AnotherValidEnum",
+							group: "Misc",
+							defaultValue: AnotherRenamedEnum.Fizz
+						},
+
+						/**
+						 * validPropertyDefaultValueEnumDestructuringWithRenameInArguments
+						 */
+						validPropertyDefaultValueEnumDestructuringWithRenameInArguments:
+							{
+								type: "library.j.ThisIsEnumToo",
+								group: "Misc",
+								defaultValue: RenamedEnum.Value1
+							},
+
+						/**
+						 * validPropertyDefaultValueEnumDestructuringWithRenameInArgumentsAndLocalVar
+						 */
+						validPropertyDefaultValueEnumDestructuringWithRenameInArgumentsAndLocalVar:
+							{
+								type: "library.j.ThisIsEnumToo",
+								group: "Misc",
+								defaultValue: RenamedValue2
+							},
+
+						/**
+						 * validPropertyDefaultValueEnumViaDestructuringInArrowFn
+						 */
+						validPropertyDefaultValueEnumViaDestructuringInArrowFn:
+							{
+								type: "library.j.MyValidEnum",
+								group: "Misc",
+								defaultValue: MyValidEnum.Foo
+							},
+
+						/**
+						 * validPropertyDefaultValueEnumViaDestructuringGlobal
+						 */
+						 validPropertyDefaultValueEnumViaDestructuringGlobal: {
+							type: "sap.ui.core.TitleLevel",
+							group: "Misc",
+							defaultValue: H1
+						},
+
+						/**
+						 * validPropertyDefaultValueArrPattern
+						 */
+						 validPropertyDefaultValueArrPattern: {
+							type: "sap.external.thirdparty.0",
+							group: "Misc",
+							defaultValue: arrPattern
+						},
+
+						/**
+						 * validPropertyDefaultValueArrPatternDeepDestruct
+						 */
+						 validPropertyDefaultValueArrPatternDeepDestruct: {
+							type: "sap.external.thirdparty.1.arrWith",
+							group: "Misc",
+							defaultValue: arrPatternDeepDestruct
+						},
+
+						/**
+						 * validPropertyDefaultValueArrPatternDeepDestruct
+						 */
+						 validPropertyDefaultValueObjPatternDeepDestruct: {
+							type: "sap.external2.thirdparty.objPattern.deeply",
+							group: "Misc",
+							defaultValue: objPatternDeepDestruct
+						},
+
+						/**
+						 * validPropertyDefaultValueObjPatternNested
+						 */
+						 validPropertyDefaultValueObjPatternNested: {
+							type: "sap.external2.thirdparty.objPattern",
+							group: "Misc",
+							defaultValue: objPattern1Lvl
+						},
+
+						/**
+						 * validPropertyDefaultValueArrPatternVarDef
+						 */
+						 validPropertyDefaultValueArrPatternVarDef: {
+							type: "sap.external3.thirdparty.0",
+							group: "Misc",
+							defaultValue: arrPatternVarDef
+						},
+
+						/**
+						 * validPropertyDefaultValueArrPatternVarDef
+						 */
+						 validPropertyDefaultValueArrPatternVarDefNestedAndRenamed: {
+							type: "sap.external3.thirdparty.1.nested",
+							group: "Misc",
+							defaultValue: arrPatternVarDefNestedAndRenamed
+						}
+					},
+				},
+				renderer: function () {},
+			}
+		);
+
+		return ValidPropertyDefaultValue;
+	},
+	/* bExport= */ true
+);

test/expected/build/library.j/dest/resources/library/j/core/library.js

@@ -0,0 +1,34 @@
+/*!
+ * ${copyright}
+ */
+sap.ui.define([], function () {
+	sap.ui.getCore().initLibrary({
+		name: "library.j.core",
+		version: "${version}",
+		dependencies: ["sap.ui.core"],
+		designtime: "library/j/core/designtime/library.designtime",
+		types: ["library.j.core.AnotherValidEnum"],
+	});
+
+	/**
+	 * AnotherValidEnum
+	 *
+	 * @enum {string}
+	 * @public
+	 * @ui5-metamodel This enumeration also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	library.j.core.AnotherValidEnum = {
+		/**
+		 * Fizz
+		 * @public
+		 */
+		Fizz: "Fizz",
+		/**
+		 * Buzz
+		 * @public
+		 */
+		Buzz: "Buzz",
+	};
+
+	return library.j.core;
+});

test/expected/build/library.j/dest/resources/library/j/library.js

@@ -0,0 +1,53 @@
+/*!
+ * ${copyright}
+ */
+sap.ui.define([], function () {
+	sap.ui.getCore().initLibrary({
+		name: "library.j",
+		version: "${version}",
+		dependencies: ["sap.ui.core"],
+		designtime: "library/j/designtime/library.designtime",
+		types: ["library.j.MyValidEnum"],
+	});
+
+	/**
+	 * MyValidEnum
+	 *
+	 * @enum {string}
+	 * @public
+	 * @ui5-metamodel This enumeration also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	library.j.MyValidEnum = {
+		/**
+		 * Foo
+		 * @public
+		 */
+		Foo: "Foo",
+		/**
+		 * Bar
+		 * @public
+		 */
+		Bar: "Bar",
+	};
+
+	/**
+	 * ThisIsEnumToo
+	 *
+	 * @enum {string}
+	 * @public
+	 */
+	library.j.ThisIsEnumToo = {
+		/**
+		 * Value1
+		 * @public
+		 */
+		Value1: "Value1",
+		/**
+		 * Value2
+		 * @public
+		 */
+		Value2: "Value2",
+	};
+
+	return library.j;
+});