From ac0078b046d9a19a197fdbaf282d840833b3c744 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 QUnit testsuites or
 annotated modules

QUnit testsuites using `QUnit.config.autostart = false` and `QUnit.start()`
are automatically detected to use `sap.ui.require` instead of `sap.ui.define`.
Modules can be also marked to use `sap.ui.require` by using the annotation
`/* @sapUiRequire */` in the program.
---
 README.md                                     |  56 ++++++-
 .../__test__/__snapshots__/test.js.snap       | 149 ++++++++++++++++++
 .../fixtures/sap-ui-require/othermodule.js    |   5 +
 .../testsuite-annotation.qunit.js             |   9 ++
 .../testsuite-autodetect.qunit.js             |   7 +
 .../testsuite-defect-1.qunit.js               |   7 +
 .../testsuite-defect-2.qunit.js               |   7 +
 .../sap-ui-require/testsuite.qunit.js         |   9 ++
 .../plugin/src/modules/helpers/wrapper.js     |  90 +++++++++--
 packages/plugin/src/utils/templates.js        |   6 +
 10 files changed, 333 insertions(+), 12 deletions(-)
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/othermodule.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-autodetect.qunit.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-1.qunit.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-2.qunit.js
 create mode 100644 packages/plugin/__test__/fixtures/sap-ui-require/testsuite.qunit.js

diff --git a/README.md b/README.md
index ea4b3b2..3786533 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,60 @@ 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 needed to include modules via script tags, such as for QUnit testsuites. Therefore, the Babel plugin supports converting modules into scripts using `sap.ui.require` instead of AMD-like modules using `sap.ui.define`. These modules then can be used as *top-level* scripts which can be included via `<script>` tags in HTML pages.
+
+To mark a module as being converted into such a `sap.ui.require` script, you can either annotate it via the comment: `/* @sapUiRequire */` or in case of QUnit testsuites the Babel plugin autodetects them when it finds the expression `QUnit.config.autostart = false` directly in the program body and `QUnit.start()` nested in the program code.
+
+Example for autodetection:
+
+```js
+// 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();
+  });
+});
+```
+
+Example using the annotation:
+
+```js
+/* @sapUiRequire */
+
+import Control from "sap/ui/core/Control";
+
+Control.extend("my.Control", {});
+```
+
+will be converted to:
+
+```js
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});
+```
+
+> :warning: Although, `sap.ui.define` and `sap.ui.require` look similar from API perspective both have a different behavior. To understand these differences please read the section *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..9e95e29 100644
--- a/packages/plugin/__test__/__snapshots__/test.js.snap
+++ b/packages/plugin/__test__/__snapshots__/test.js.snap
@@ -1604,6 +1604,154 @@ exports[`preset-env preset-env-usage.js 1`] = `
 });"
 `;
 
+exports[`sap-ui-require othermodule.js 1`] = `
+"sap.ui.require(["sap/ui/core/Control"], function (Control) {
+  "use strict";
+
+  Control.extend("my.Control", {});
+});"
+`;
+
+exports[`sap-ui-require testsuite.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-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-autodetect.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-defect-1.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[`sap-ui-require testsuite-defect-2.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 +1828,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.js b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule.js
new file mode 100644
index 0000000..8e4f7eb
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/othermodule.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/testsuite-annotation.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-annotation.qunit.js
new file mode 100644
index 0000000..da84a8c
--- /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-autodetect.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-autodetect.qunit.js
new file mode 100644
index 0000000..b806859
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-autodetect.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/__test__/fixtures/sap-ui-require/testsuite-defect-1.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-1.qunit.js
new file mode 100644
index 0000000..c1a08e0
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-1.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/__test__/fixtures/sap-ui-require/testsuite-defect-2.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-2.qunit.js
new file mode 100644
index 0000000..998e1bf
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite-defect-2.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/__test__/fixtures/sap-ui-require/testsuite.qunit.js b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite.qunit.js
new file mode 100644
index 0000000..9ec8ab9
--- /dev/null
+++ b/packages/plugin/__test__/fixtures/sap-ui-require/testsuite.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/src/modules/helpers/wrapper.js b/packages/plugin/src/modules/helpers/wrapper.js
index 38ea324..3aec49c 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,30 @@ 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(
+      [{ leadingComments: visitor.parent.comments }, ...body],
+      true
+    ) || hasQUnitAutostartBoilerplate(body);
+
+  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 +196,74 @@ function hasUseStrict(node) {
   );
 }
 
-function generateDefine(body, imports, exportGlobal) {
+function hasUseSapUiRequire(body, remove) {
+  // detect the @sapUiRequire comment
+  return body?.some((node) => {
+    return node.leadingComments?.some((comment, i) => {
+      const found = comment.value.includes("@sapUiRequire");
+      if (found && remove) {
+        node.leadingComments.slice(i, 1);
+      }
+      return found;
+    });
+  });
+}
+
+function hasQUnitAutostartBoilerplate(body) {
+  let autostartBoilerplate = body?.some((node) => {
+    // detect QUnit.config.autostart = false;
+    return (
+      t.isExpressionStatement(node) &&
+      t.isAssignmentExpression(node.expression) &&
+      t.isMemberExpression(node.expression.left) &&
+      t.isMemberExpression(node.expression.left.object) &&
+      t.isIdentifier(node.expression.left.object.object) &&
+      node.expression.left.object.object.name === "QUnit" &&
+      t.isIdentifier(node.expression.left.object.property) &&
+      node.expression.left.object.property.name === "config" &&
+      t.isIdentifier(node.expression.left.property) &&
+      node.expression.left.property.name === "autostart" &&
+      node.expression.operator === "=" &&
+      t.isBooleanLiteral(node.expression.right) &&
+      node.expression.right.value === false
+    );
+  });
+  // find QUnit.start() in the body using AST walk
+  if (autostartBoilerplate) {
+    autostartBoilerplate = body.some((child) => {
+      let found = false;
+      traverse(child, {
+        enter(path) {
+          const node = path.node;
+          if (
+            t.isExpressionStatement(node) &&
+            t.isCallExpression(node.expression) &&
+            t.isMemberExpression(node.expression.callee) &&
+            t.isIdentifier(node.expression.callee.object) &&
+            node.expression.callee.object.name === "QUnit" &&
+            t.isIdentifier(node.expression.callee.property) &&
+            node.expression.callee.property.name === "start"
+          ) {
+            found = true;
+          }
+        },
+        noScope: true,
+      });
+      return found;
+    });
+  }
+  return autostartBoilerplate;
+}
+
+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;