From c610305e8fb869461a8dd5ba876270c7f7b71a22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matthias=20O=C3=9Fwald?=
 <1410947+matz3@users.noreply.github.com>
Date: Tue, 14 Jul 2020 13:59:33 +0200
Subject: [PATCH] [FIX] Node.js API: TypeScript type definition support (#335)

Lazy-loading in the index.js breaks the automatic type definition detection from TypeScript when using the module via require. Therefore we need to manually declare the exported types.

Adds a small jsdoc-plugin to remove the import() comments as JSDoc is unable to parse them.
---
 index.js        |  28 +++++++++++-
 jsdoc-plugin.js |  13 ++++++
 jsdoc.json      | 118 ++++++++++++++++++++++++------------------------
 3 files changed, 99 insertions(+), 60 deletions(-)
 create mode 100644 jsdoc-plugin.js

diff --git a/index.js b/index.js
index 19140fb97..e21fbfee6 100644
--- a/index.js
+++ b/index.js
@@ -2,8 +2,14 @@
  * @module module:@ui5/project
  * @public
  */
-const modules = {
+module.exports = {
+	/**
+	 * @type {import('./lib/normalizer')}
+	 */
 	normalizer: "./lib/normalizer",
+	/**
+	 * @type {import('./lib/projectPreprocessor')}
+	 */
 	projectPreprocessor: "./lib/projectPreprocessor",
 	/**
 	 * @public
@@ -11,7 +17,13 @@ const modules = {
 	 * @namespace
 	 */
 	ui5Framework: {
+		/**
+		 * @type {typeof import('./lib/ui5Framework/Openui5Resolver')}
+		 */
 		Openui5Resolver: "./lib/ui5Framework/Openui5Resolver",
+		/**
+		 * @type {typeof import('./lib/ui5Framework/Sapui5Resolver')}
+		 */
 		Sapui5Resolver: "./lib/ui5Framework/Sapui5Resolver"
 	},
 	/**
@@ -20,7 +32,13 @@ const modules = {
 	 * @namespace
 	 */
 	validation: {
+		/**
+		 * @type {import('./lib/validation/validator')}
+		 */
 		validator: "./lib/validation/validator",
+		/**
+		 * @type {typeof import('./lib/validation/ValidationError')}
+		 */
 		ValidationError: "./lib/validation/ValidationError"
 	},
 	/**
@@ -29,7 +47,13 @@ const modules = {
 	 * @namespace
 	 */
 	translators: {
+		/**
+		 * @type {import('./lib/translators/npm')}
+		 */
 		npm: "./lib/translators/npm",
+		/**
+		 * @type {import('./lib/translators/static')}
+		 */
 		static: "./lib/translators/static"
 	}
 };
@@ -49,4 +73,4 @@ function exportModules(exportRoot, modulePaths) {
 	}
 }
 
-exportModules(module.exports, modules);
+exportModules(module.exports, JSON.parse(JSON.stringify(module.exports)));
diff --git a/jsdoc-plugin.js b/jsdoc-plugin.js
new file mode 100644
index 000000000..bf94fbc6e
--- /dev/null
+++ b/jsdoc-plugin.js
@@ -0,0 +1,13 @@
+/*
+ * Removes JSDoc comments with TypeScript import() declarations (used in index.js)
+ */
+
+const IMPORT_PATTERN = /{(?:typeof )?import\(["'][^"']*["']\)[ .|}><,)=#\n]/;
+
+exports.handlers = {
+	jsdocCommentFound: function(e) {
+		if (IMPORT_PATTERN.test(e.comment)) {
+			e.comment = "";
+		}
+	}
+};
diff --git a/jsdoc.json b/jsdoc.json
index 81925e93c..bce77a4bd 100644
--- a/jsdoc.json
+++ b/jsdoc.json
@@ -1,60 +1,62 @@
 {
-    "tags": {
-        "allowUnknownTags": false
-    },
-    "source": {
-        "include": ["README.md", "index.js"],
-        "includePattern": ".+\\.js$",
-        "excludePattern": "(node_modules(\\\\|/))"
-    },
-    "plugins": [],
-    "opts": {
-        "template": "node_modules/docdash/",
-        "encoding": "utf8",
-        "destination": "jsdocs/",
-        "recurse": true,
-        "verbose": true,
-        "access": "public"
-    },
-    "templates": {
-        "cleverLinks": false,
-        "monospaceLinks": false,
-        "default": {
-            "useLongnameInNav": true
-        }
-    },
-    "openGraph": {
-        "title": "UI5 Tooling - API Reference",
-        "type": "website",
-        "image": "https://sap.github.io/ui5-tooling/docs/images/UI5_logo_wide.png",
-        "site_name": "UI5 Tooling - API Reference",
-        "url": "https://sap.github.io/ui5-tooling/"
-    },
-    "docdash": {
-        "sectionOrder": [
-            "Modules",
-            "Namespaces",
-            "Classes",
-            "Externals",
-            "Events",
-            "Mixins",
-            "Tutorials",
-            "Interfaces"
-        ],
-        "meta": {
-            "title": "UI5 Tooling - API Reference - UI5 Project",
-            "description": "UI5 Tooling - API Reference - UI5 Project",
-            "keyword": "openui5 sapui5 ui5 build development tool api reference"
-        },
-        "search": true,
-        "wrap": true,
-        "menu": {
-            "GitHub": {
-                "href": "https://github.com/SAP/ui5-project",
-                "target": "_blank",
-                "class": "menu-item",
-                "id": "github_link"
-            }
-        }
-    }
+	"tags": {
+		"allowUnknownTags": false
+	},
+	"source": {
+		"include": ["README.md", "index.js"],
+		"includePattern": ".+\\.js$",
+		"excludePattern": "(node_modules(\\\\|/))"
+	},
+	"plugins": [
+		"./jsdoc-plugin"
+	],
+	"opts": {
+		"template": "node_modules/docdash/",
+		"encoding": "utf8",
+		"destination": "jsdocs/",
+		"recurse": true,
+		"verbose": true,
+		"access": "public"
+	},
+	"templates": {
+		"cleverLinks": false,
+		"monospaceLinks": false,
+		"default": {
+			"useLongnameInNav": true
+		}
+	},
+	"openGraph": {
+		"title": "UI5 Tooling - API Reference",
+		"type": "website",
+		"image": "https://sap.github.io/ui5-tooling/docs/images/UI5_logo_wide.png",
+		"site_name": "UI5 Tooling - API Reference",
+		"url": "https://sap.github.io/ui5-tooling/"
+	},
+	"docdash": {
+		"sectionOrder": [
+			"Modules",
+			"Namespaces",
+			"Classes",
+			"Externals",
+			"Events",
+			"Mixins",
+			"Tutorials",
+			"Interfaces"
+		],
+		"meta": {
+			"title": "UI5 Tooling - API Reference - UI5 Project",
+			"description": "UI5 Tooling - API Reference - UI5 Project",
+			"keyword": "openui5 sapui5 ui5 build development tool api reference"
+		},
+		"search": true,
+		"wrap": true,
+		"menu": {
+			"GitHub": {
+				"href": "https://github.com/SAP/ui5-project",
+				"target": "_blank",
+				"class": "menu-item",
+				"id": "github_link"
+			}
+		}
+	}
 }