fix(dts-generator): detect broken method names and throw error

Writing a method name like

MyModule[SomeEnum.EnumValue] = async function (param) {

in the UI5 source code led to a method name "undefined]" in api.json,
which led to a broken dts file and all kinds of unrelated tsc errors.
While it should have been detected earlier, it does not hurt to check
some names here.

Author: akudev

packages/dts-generator/docs/TECHNICAL.md

@@ -44,6 +44,7 @@ The generator works in several phases, which are reflected as modules in [`src/p
 Using `directives` as input and the information whether modules or globals should be generated, this phase does plenty of adjustments in the original api.json files:
 
 - `mergeOverlays` merges in the overlays from directives
+- `validateNames` does some rudimentary sanity checks for real-world issues which are otherwise hard to debug
 - `substituteSapClassInfoTypedef` adds the sap.ClassInfo typedef
 - `convertCoreAndConfigurationIntoANamespace` converts `sap.ui.core.Core` and `sap.ui.core.Configuration` from a class (needed as such in the SDK) into a namespace because the module export of both is an _instance_, not the class
 - `moveTypeParametersFromConstructorToClass` moves any type parameters from a class's constructor to the class itself. It is more common to build a generic class than building a constructor that has a generic parameter. Newer versions of UI5 (starting with 1.113) will already export the api.json like that, the code in `moveTypeParametersFromConstructorToClass` can handle this.

packages/dts-generator/src/phases/json-fixer.ts

@@ -134,6 +134,35 @@ function mergeOverlays(
   });
 }
 
+/**
+ * Does some rudimentary validation of method names.
+ * The method names are expected to be valid TypeScript identifiers.
+ * This is not a full validation, but catches errors that happened in real life and were hard to debug.
+ *
+ * @param symbols
+ */
+function validateNames(symbols: ConcreteSymbol[]) {
+  const invalid_characters = /[{}\[\]()<>]/;
+  symbols.forEach((symbol) => {
+    switch (symbol.kind) {
+      case "class":
+      case "namespace":
+        if (symbol.methods) {
+          symbol.methods.forEach((method) => {
+            if (invalid_characters.test(method.name)) {
+              throw new Error(
+                `Invalid method name "${method.name}" in ${symbol.name}: ` +
+                  "Method names must not contain square brackets. " +
+                  "This might be caused by using unsupported notation in the source code - check it! " +
+                  "Also check the generated api.json, which is used as input here, whether it also contains such a broken name.",
+              );
+            }
+          });
+        }
+    }
+  });
+}
+
 /**
  *
  * @param apijson
@@ -882,6 +911,7 @@ function _prepareApiJson(
   options = { mainLibrary: false, generateGlobals: false },
 ) {
   mergeOverlays(json, directives, { generateGlobals: options.generateGlobals });
+  validateNames(json.symbols);
   substituteSapClassInfoTypedef(json);
   convertCoreAndConfigurationIntoANamespace(json, directives);
   moveTypeParametersFromConstructorToClass(json);