From 4d7e0c7c926015d52ab97ad7044b0848204be264 Mon Sep 17 00:00:00 2001
From: Peter Muessig <peter.muessig@sap.com>
Date: Sat, 13 Jul 2024 12:34:06 +0200
Subject: [PATCH] feat: support sap.ui.require for @sapUiRequire annotated
 modules

QUnit testsuites using `QUnit.config.autostart = false` and `QUnit.start()`
loaded via <script> tags must be loaded using `sap.ui.require`. With this
change modules can be marked using `sap.ui.require` by using the annotation
`/* @sapUiRequire */` in the program code.
---
 README.md                                     | 36 ++++++-
 .../__test__/__snapshots__/test.js.snap       | 99 +++++++++++++++++++
 .../othermodule-annotation-end.js             |  5 +
 .../othermodule-annotation-middle.js          |  5 +
 .../othermodule-annotation-nested.js          |  7 ++
 .../sap-ui-require/othermodule-annotation.js  |  5 +
 .../othermodule-noannotation.js               |  3 +
 .../testsuite-annotation.qunit.js             |  9 ++
 .../testsuite-noannotation.qunit.js           |  7 ++
 .../plugin/src/modules/helpers/wrapper.js     | 55 ++++++++---
 packages/plugin/src/utils/templates.js        |  6 ++
 11 files changed, 225 insertions(+), 12 deletions(-)
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-end.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-middle.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-nested.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule-noannotation.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/testsuite-annotation.qunit.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/testsuite-noannotation.qunit.js

diff --git a/README.md b/README.md
index ea4b3b2..ca2b514 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,7 @@ A more detailed feature list includes:
 
 ### Converting ES modules (import/export) into sap.ui.define or sap.ui.require
 
-The plugin will wrap any code having import/export statements in an sap.ui.define. If there is no import/export, it won't be wrapped.
+The plugin will wrap any code having import/export statements in `sap.ui.define`. If there is no import/export, it won't be wrapped.
 
 #### Static Import
 
@@ -341,6 +341,40 @@ sap.ui.define(["./a"], A => {
 
 Also refer to the `neverUseStrict` option below.
 
+### Top-Level Scripts (e.g. QUnit Testsuites)
+
+By default, modules are converted to UI5 AMD-like modules using `sap.ui.define`. In some cases, it is necessary to include modules via script tags, such as for QUnit testsuites. Therefore, this Babel plugin supports converting modules into scripts using `sap.ui.require` instead of AMD-like modules using `sap.ui.define`. These modules can then be used as *top-level* scripts, which can be included via `<script>` tags in HTML pages. To mark a module as being converted into a `sap.ui.require` script, you need to add the comment `/* @sapUiRequire */` at the top of the file.
+
+Example:
+
+```js
+/* @sapUiRequire */
+
+// https://api.qunitjs.com/config/autostart/
+QUnit.config.autostart = false;
+
+// import all your QUnit tests here
+void Promise.all([import("unit/controller/App.qunit")]).then(() => {
+  QUnit.start();
+});
+```
+
+will be converted to:
+
+```js
+"sap.ui.require([], function () {
+  "use strict";
+
+  function __ui5_require_async(path) { /* ... */ }
+  QUnit.config.autostart = false;
+  void Promise.all([__ui5_require_async("unit/controller/App.qunit")]).then(() => {
+    QUnit.start();
+  });
+});
+```
+
+> :warning: Although `sap.ui.define` and `sap.ui.require` may appear similar from an API perspective, they have different behaviors. To understand these differences, please read the section titled "Using sap.ui.require instead of sap.ui.define on the top level" in the [Troubleshooting for Loading Modules](https://ui5.sap.com/#/topic/4363b3fe3561414ca1b030afc8cd30ce).
+
 ### Converting ES classes into Control.extend(..) syntax
 
 By default, the plugin converts ES classes to `Control.extend(..)` syntax if the class extends from a class which has been imported.
diff --git a/packages/plugin/__test__/__snapshots__/test.js.snap b/packages/plugin/__test__/__snapshots__/test.js.snap
index a343536..4aadd7b 100644
--- a/packages/plugin/__test__/__snapshots__/test.js.snap
+++ b/packages/plugin/__test__/__snapshots__/test.js.snap
@@ -1604,6 +1604,104 @@ exports[`preset-env preset-env-usage.js 1`] = `
 });"
 `;
 
+exports[`sap-ui-require othermodule-annotation.js 1`] = `
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});"
+`;
+
+exports[`sap-ui-require othermodule-annotation-end.js 1`] = `
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});"
+`;
+
+exports[`sap-ui-require othermodule-annotation-middle.js 1`] = `
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});"
+`;
+
+exports[`sap-ui-require othermodule-annotation-nested.js 1`] = `
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {
+    onInit: function () {}
+  });
+});"
+`;
+
+exports[`sap-ui-require othermodule-noannotation.js 1`] = `
+"sap.ui.define(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});"
+`;
+
+exports[`sap-ui-require testsuite-annotation.qunit.js 1`] = `
+"sap.ui.require([], function () {
+  "use strict";
+
+  function __ui5_require_async(path) {
+    return new Promise(function (resolve, reject) {
+      sap.ui.require([path], function (module) {
+        if (!(module && module.__esModule)) {
+          module = module === null || !(typeof module === "object" && path.endsWith("/library")) ? {
+            default: module
+          } : module;
+          Object.defineProperty(module, "__esModule", {
+            value: true
+          });
+        }
+        resolve(module);
+      }, function (err) {
+        reject(err);
+      });
+    });
+  }
+  QUnit.config.autostart = false;
+  void Promise.all([__ui5_require_async("unit/controller/App.qunit")]).then(() => {
+    QUnit.start();
+  });
+});"
+`;
+
+exports[`sap-ui-require testsuite-noannotation.qunit.js 1`] = `
+"sap.ui.define([], function () {
+  "use strict";
+
+  function __ui5_require_async(path) {
+    return new Promise(function (resolve, reject) {
+      sap.ui.require([path], function (module) {
+        if (!(module && module.__esModule)) {
+          module = module === null || !(typeof module === "object" && path.endsWith("/library")) ? {
+            default: module
+          } : module;
+          Object.defineProperty(module, "__esModule", {
+            value: true
+          });
+        }
+        resolve(module);
+      }, function (err) {
+        reject(err);
+      });
+    });
+  }
+  QUnit.config.autostart = false;
+  void Promise.all([__ui5_require_async("unit/controller/App.qunit")]).then(() => {
+    QUnit.start();
+  });
+});"
+`;
+
 exports[`typescript ts-class-anonymous.ts 1`] = `
 "sap.ui.define(["sap/Class"], function (SAPClass) {
   "use strict";
@@ -1680,6 +1778,7 @@ exports[`typescript ts-class-controller-extension-extended.ts 1`] = `
   return MyExtendedController;
 });"
 `;
+
 exports[`typescript ts-class-controller-extension-extended-error-1.ts 1`] = `
 "ControllerExtension.use() must be called with exactly one argument but has 0
    7 |  */
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-end.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-end.js
new file mode 100644
index 0000000..216cf03
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-end.js
@@ -0,0 +1,5 @@
+import Control from "sap/ui/core/Control";
+
+Control.extend("my.Control", {});
+
+/* @sapUiRequire */
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-middle.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-middle.js
new file mode 100644
index 0000000..d99951d
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-middle.js
@@ -0,0 +1,5 @@
+import Control from "sap/ui/core/Control";
+
+/* @sapUiRequire */
+
+Control.extend("my.Control", {});
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-nested.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-nested.js
new file mode 100644
index 0000000..cc637bf
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation-nested.js
@@ -0,0 +1,7 @@
+import Control from "sap/ui/core/Control";
+
+Control.extend("my.Control", {
+  onInit: function () {
+    /* @sapUiRequire */
+  },
+});
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation.js
new file mode 100644
index 0000000..8e4f7eb
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-annotation.js
@@ -0,0 +1,5 @@
+/* @sapUiRequire */
+
+import Control from "sap/ui/core/Control";
+
+Control.extend("my.Control", {});
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-noannotation.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-noannotation.js
new file mode 100644
index 0000000..901ef46
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule-noannotation.js
@@ -0,0 +1,3 @@
+import Control from "sap/ui/core/Control";
+
+Control.extend("my.Control", {});
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-annotation.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-annotation.qunit.js
new file mode 100644
index 0000000..9ec8ab9
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-annotation.qunit.js
@@ -0,0 +1,9 @@
+/* @sapUiRequire */
+
+// https://api.qunitjs.com/config/autostart/
+QUnit.config.autostart = false;
+
+// import all your QUnit tests here
+void Promise.all([import("unit/controller/App.qunit")]).then(() => {
+  QUnit.start();
+});
diff --git a/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-noannotation.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-noannotation.qunit.js
new file mode 100644
index 0000000..b806859
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-noannotation.qunit.js
@@ -0,0 +1,7 @@
+// https://api.qunitjs.com/config/autostart/
+QUnit.config.autostart = false;
+
+// import all your QUnit tests here
+void Promise.all([import("unit/controller/App.qunit")]).then(() => {
+  QUnit.start();
+});
diff --git a/packages/plugin/src/modules/helpers/wrapper.js b/packages/plugin/src/modules/helpers/wrapper.js
index 38ea324..8cd0a8b 100644
--- a/packages/plugin/src/modules/helpers/wrapper.js
+++ b/packages/plugin/src/modules/helpers/wrapper.js
@@ -1,4 +1,4 @@
-import { types as t } from "@babel/core";
+import { types as t, traverse } from "@babel/core";
 import * as eh from "./exports";
 import * as th from "../../utils/templates";
 import * as ast from "../../utils/ast";
@@ -158,23 +158,27 @@ export function wrap(visitor, programNode, opts) {
     body.unshift(th.buildDefaultImportInterop());
   }
 
-  const define = generateDefine(
+  // should we use sap.ui.require instead of sap.ui.define?
+  let useSapUiRequire = hasUseSapUiRequire(visitor.parent.comments, body, true);
+
+  // generate the sap.ui.define or sap.ui.require
+  const defineOrRequire = generateDefineOrRequire(
     body,
     imports,
     exportGlobal || opts.exportAllGlobal,
-    hasUseStrict(programNode)
+    useSapUiRequire
   );
 
   // add the "use strict" directive if not on program node
   if (!opts.neverUseStrict && !hasUseStrict(programNode)) {
-    const defineFnBody = define.expression.arguments[1].body;
-    defineFnBody.directives = [
+    const defineOrRequireFnBody = defineOrRequire.expression.arguments[1].body;
+    defineOrRequireFnBody.directives = [
       t.directive(t.directiveLiteral("use strict")),
-      ...(defineFnBody.directives || []),
+      ...(defineOrRequireFnBody.directives || []),
     ];
   }
 
-  programNode.body = [...preDefine, define];
+  programNode.body = [...preDefine, defineOrRequire];
 
   // if a copyright comment is present we append it to the new program node
   if (copyright && visitor.parent) {
@@ -189,13 +193,42 @@ function hasUseStrict(node) {
   );
 }
 
-function generateDefine(body, imports, exportGlobal) {
+function hasUseSapUiRequire(comments, body, remove) {
+  // detect the @sapUiRequire comment
+  return comments.some((comment) => {
+    let found = false;
+    // check for existing comment block
+    if (comment.type === "CommentBlock") {
+      found = comment.value.trim() === "@sapUiRequire";
+    }
+    // remove the comment (if it is somewhere in the body)
+    if (found && remove) {
+      body?.forEach((node) => {
+        traverse(node, {
+          enter(path) {
+            ["leadingComments", "trailingComments", "innerComments"].forEach(
+              (key) => {
+                path.node[key] = path.node[key]?.filter((c) => c !== comment);
+              }
+            );
+          },
+          noScope: true,
+        });
+      });
+    }
+    return found;
+  });
+}
+
+function generateDefineOrRequire(body, imports, exportGlobal, useRequire) {
   const defineOpts = {
     SOURCES: t.arrayExpression(imports.map((i) => t.stringLiteral(i.src))),
     PARAMS: imports.map((i) => t.identifier(i.tmpName)),
     BODY: body,
   };
-  return exportGlobal
-    ? th.buildDefineGlobal(defineOpts)
-    : th.buildDefine(defineOpts);
+  return useRequire
+    ? th.buildRequire(defineOpts)
+    : exportGlobal
+      ? th.buildDefineGlobal(defineOpts)
+      : th.buildDefine(defineOpts);
 }
diff --git a/packages/plugin/src/utils/templates.js b/packages/plugin/src/utils/templates.js
index e9eb38a..01c936c 100644
--- a/packages/plugin/src/utils/templates.js
+++ b/packages/plugin/src/utils/templates.js
@@ -8,6 +8,12 @@ export const buildAssign = template(`
   OBJECT.NAME = VALUE;
 `);
 
+export const buildRequire = template(`
+  sap.ui.require(SOURCES, function (PARAMS) {
+    BODY;
+  });
+`);
+
 export const buildDefine = template(`
   sap.ui.define(SOURCES, function (PARAMS) {
     BODY;