@ui5/webcomponents-tools 0.0.0-07d38e78e → 0.0.0-093de5dd1

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/utils/manifest-helpers.js

@@ -0,0 +1,194 @@
+/**
+ * UTILITIES RELATED TO GETTING INFORMATION OUT OF A MANIFEST OR DOC
+ */
+
+import { has } from "./index.js";
+
+/**
+ * @typedef {import('custom-elements-manifest/schema').Package} Package
+ */
+
+function loopThroughDeclarations(manifest, predicate) {
+  manifest?.modules?.forEach(_module => {
+    _module?.declarations?.forEach(predicate);
+  });
+}
+
+function loopThroughExports(manifest, predicate) {
+  manifest?.modules?.forEach(_module => {
+    _module?.exports?.forEach(predicate);
+  });
+}
+
+/**
+ * Loops through all modules' exports, and returns the kind provided by the users
+ *
+ * @example getKind('class');
+ * @example getKind('custom-element-definition');
+ */
+export function getAllExportsOfKind(manifest, kind) {
+  const result = [];
+  loopThroughExports(manifest, (_export) => {
+    if(_export.kind === kind) {
+      result.push(_export);
+    }
+  });
+  return result;
+}
+
+
+/**
+ * Loops through all modules' declarations, and returns the kind provided by the users
+ *
+ * @example getKind('class');
+ * @example getKind('custom-element-definition');
+ */
+export function getAllDeclarationsOfKind(manifest, kind) {
+  const result = [];
+  loopThroughDeclarations(manifest, (declaration) => {
+    if(declaration.kind === kind) {
+      result.push(declaration);
+    }
+  });
+  return result;
+}
+
+/**
+ * Gets the inheritance tree from a manifest given a className
+ * Returns an array of a classes mixins/superclasses all the way up the chain
+ *
+ * @param {Package[]} manifests
+ * @param {string} className
+ */
+export function getInheritanceTree(manifests, className) {
+  const tree = [];
+  const allClassLikes = new Map();
+  const _classes = [];
+  const _mixins = [];
+
+  manifests.forEach((cem) => {
+    _classes.push(...getAllDeclarationsOfKind(cem, 'class'));
+    _mixins.push(...getAllDeclarationsOfKind(cem, 'mixin'));
+  });
+
+  [..._mixins, ..._classes].forEach((klass) => {
+    allClassLikes.set(klass.name, klass);
+  });
+
+  let klass = allClassLikes.get(className)
+
+  if(klass) {
+    tree.push(klass)
+
+    klass?.mixins?.forEach(mixin => {
+      let foundMixin = _mixins.find(m => m.name === mixin.name);
+      if(foundMixin) {
+        tree.push(foundMixin);
+
+        while(has(foundMixin?.mixins)) {
+          foundMixin?.mixins?.forEach(mixin => {
+            foundMixin =  _mixins.find(m => m.name === mixin.name);
+            if(foundMixin) {
+              tree.push(foundMixin);
+            }
+          });
+        }
+      }
+    });
+
+    while(allClassLikes.has(klass.superclass?.name)) {
+      const newKlass = allClassLikes.get(klass.superclass.name);
+      let allMixins = [];
+      if (klass?.mixins) {
+        allMixins = [...klass.mixins];
+      }
+      if (newKlass?.mixins) {
+        allMixins = [...allMixins, ...newKlass.mixins];
+      }
+
+      allMixins.forEach(mixin => {
+        let foundMixin = _mixins.find(m => m.name === mixin.name);
+        if(foundMixin) {
+          tree.push(foundMixin);
+
+          while(has(foundMixin?.mixins)) {
+            foundMixin?.mixins?.forEach(mixin => {
+              foundMixin =  _mixins.find(m => m.name === mixin.name);
+              if(foundMixin) {
+                tree.push(foundMixin);
+              }
+            });
+          }
+        }
+      });
+
+      tree.push(newKlass);
+      klass = newKlass;
+    }
+    return tree;
+  }
+  return [];
+}
+
+/**
+ * @param {Package[]} manifests
+ * @param {string} modulePath
+ */
+ export function getModuleFromManifests(manifests, modulePath) {
+   let result = undefined;
+
+   manifests.forEach((cem) => {
+    cem?.modules?.forEach((_module) => {
+      if (_module.path === modulePath) {
+        result = _module;
+      }
+    });
+  });
+
+  return result;
+}
+
+/**
+ * @param {Package[]} manifests
+ * @param {string} className
+ */
+ export function getModuleForClassLike(manifests, className) {
+  let result = undefined;
+
+  manifests.forEach((cem) => {
+    cem?.modules?.forEach(_module => {
+      _module?.declarations?.forEach(declaration => {
+        if((declaration.kind === 'class' || declaration.kind === 'mixin') && declaration.name === className) {
+          result = _module.path;
+        }
+      });
+    });
+  });
+
+  return result;
+}
+
+/**
+ * Given a manifest module, a class name, and a class member name, gets the
+ * manifest doc for the module's class' member.
+ *
+ * @param  {Partial<import('custom-elements-manifest/schema').Module>} moduleDoc Manifest module
+ * @param  {string} className Class to get member of
+ * @param  {string} memberName Class member to get
+ * @param  {boolean} isStatic Is it a static member?
+ * @return {import('custom-elements-manifest/schema').ClassMember|void} the requested class member
+ */
+export function getClassMemberDoc(moduleDoc, className, memberName, isStatic = false) {
+  /** @type {import('custom-elements-manifest/schema').ClassDeclaration} */
+  const classDoc = (moduleDoc.declarations.find(x => x.name === className));
+
+  if (!classDoc || !has(classDoc.members))
+    return;
+
+  const memberDoc = classDoc.members.find(x =>
+    x.name === memberName &&
+    (x.static ?? false) === isStatic
+  );
+
+  return memberDoc;
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/utils/mixins.js

@@ -0,0 +1,112 @@
+import ts from 'typescript';
+
+import { getReturnValue } from '../utils/ast-helpers.js';
+
+export const isMixin = node => !!extractMixinNodes(node);
+
+export function extractMixinNodes(node) {
+  if (ts.isVariableStatement(node) || ts.isFunctionDeclaration(node)) {
+    if (ts.isVariableStatement(node)) {
+      /**
+       * @example const MyMixin = klass => class MyMixin extends klass {}
+       * @example export const MyMixin = klass => class MyMixin extends klass {}
+       */
+      const variableDeclaration = node.declarationList.declarations.find(declaration =>
+        ts.isVariableDeclaration(declaration),
+      );
+      if (variableDeclaration) {
+        const body = variableDeclaration?.initializer?.body;
+        if (body && ts.isClassExpression(body)) {
+          return { 
+            mixinFunction: node,
+            mixinClass: body,
+          };
+        }
+
+        /**
+         * @example const MyMixin = klass => { return class MyMixin extends Klass{} }
+         */
+        if (body && ts.isBlock(body)) {
+          const returnStatement = body.statements.find(statement => ts.isReturnStatement(statement));
+
+          if (returnStatement && returnStatement?.expression?.kind && ts.isClassExpression(returnStatement.expression)) {
+            return { 
+              mixinFunction: variableDeclaration.initializer,
+              mixinClass: returnStatement.expression
+            };
+          }
+        }
+
+        /**
+         * @example const MyMixin = klass => { class MyMixin extends klass {} return MyMixin;}
+         */
+        if (body && ts.isBlock(body)) {
+          const classDeclaration = body.statements.find(statement => ts.isClassDeclaration(statement));
+          const returnStatement = body.statements.find(statement => ts.isReturnStatement(statement));
+          /** Avoid undefined === undefined */
+          if(!(classDeclaration && returnStatement))
+            return;
+          const classDeclarationName = classDeclaration.name?.getText?.();
+          const returnValue = getReturnValue(returnStatement)
+          /**
+           * If the classDeclaration inside the function body has the same name as whats being
+           * returned from the function, consider it a mixin
+           */
+          if (classDeclarationName === returnValue) {
+            return {
+              mixinFunction: node,
+              mixinClass: classDeclaration
+            }
+          }
+        }
+      }
+    }
+
+    /**
+     *  @example function MyMixin(klass) { return class MyMixin extends Klass{} }
+     */
+    if (ts.isFunctionDeclaration(node)) {
+      if (node.body && ts.isBlock(node.body)) {
+
+        const returnStatement = node.body.statements.find(statement => ts.isReturnStatement(statement));
+
+        if (returnStatement?.expression && ts.isClassExpression(returnStatement.expression)) {
+          return { 
+            mixinFunction: node, 
+            mixinClass: returnStatement.expression
+          };
+        }
+      }
+    }
+
+    /**
+     * @example function MyMixin(klass) {class A extends klass {} return A;}
+     */
+    if (ts.isFunctionDeclaration(node)) {
+      if (node.body && ts.isBlock(node.body)) {
+        const classDeclaration = node.body.statements.find(statement => ts.isClassDeclaration(statement));
+        const returnStatement = node.body.statements.find(statement => ts.isReturnStatement(statement));
+
+        /** Avoid undefined === undefined */
+        if(!(classDeclaration && returnStatement))
+          return;
+
+        const classDeclarationName = classDeclaration.name?.getText?.();
+
+        const returnValue = getReturnValue(returnStatement)
+
+        /**
+         * If the classDeclaration inside the function body has the same name as whats being
+         * returned from the function, consider it a mixin
+         */
+        if (classDeclarationName === returnValue) {
+          return {
+            mixinFunction: node,
+            mixinClass: classDeclaration
+          }
+        }
+      }
+    }
+  }
+  return false;
+}

package/lib/cem/schema-internal.json

@@ -46,6 +46,12 @@
     "ClassDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -123,6 +129,12 @@
     "EnumDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -187,6 +199,12 @@
     "InterfaceDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -389,6 +407,9 @@
     "CssCustomProperty": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "default": {
           "type": "string"
         },
@@ -425,6 +446,9 @@
       "additionalProperties": false,
       "description": "The description of a CSS Part",
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "deprecated": {
           "description": "Whether the CSS shadow part is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
           "type": [
@@ -453,6 +477,12 @@
       "additionalProperties": false,
       "description": "A description of a custom element class.\n\nCustom elements are JavaScript classes, so this extends from\n`ClassDeclaration` and adds custom-element-specific features like\nattributes, events, and slots.\n\nNote that `tagName` in this interface is optional. Tag names are not\nneccessarily part of a custom element class, but belong to the definition\n(often called the \"registration\") or the `customElements.define()` call.\n\nBecause classes and tag names can only be registered once, there's a\none-to-one relationship between classes and tag names. For ease of use,\nwe allow the tag name here.\n\nSome packages define and register custom elements in separate modules. In\nthese cases one `Module` should contain the `CustomElement` without a\ntagName, and another `Module` should contain the\n`CustomElementExport`.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -618,6 +648,12 @@
       "additionalProperties": false,
       "description": "A class mixin that also adds custom element related properties.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -788,6 +824,14 @@
           "description": "Whether the parameter is optional. Undefined implies non-optional.",
           "type": "boolean"
         },
+        "_ui5Cancelable": {
+          "description": "Whether the event is cancelable or not.",
+          "type": "boolean"
+        },
+        "_ui5Bubbles": {
+          "description": "Whether the event bubbles or not.",
+          "type": "boolean"
+        },
         "_ui5since": {
           "description": "Marks when the field was introduced",
           "type": "string"
@@ -827,6 +871,12 @@
     "FunctionDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -1007,6 +1057,12 @@
       "additionalProperties": false,
       "description": "A description of a class mixin.\n\nMixins are functions which generate a new subclass of a given superclass.\nThis interfaces describes the class and custom element features that\nare added by the mixin. As such, it extends the CustomElement interface and\nClassLike interface.\n\nSince mixins are functions, it also extends the FunctionLike interface. This\nmeans a mixin is callable, and has parameters and a return type.\n\nThe return type is often hard or impossible to accurately describe in type\nsystems like TypeScript. It requires generics and an `extends` operator\nthat TypeScript lacks. Therefore it's recommended that the return type is\nleft empty. The most common form of a mixin function takes a single\nargument, so consumers of this interface should assume that the return type\nis the single argument subclassed by this declaration.\n\nA mixin should not have a superclass. If a mixins composes other mixins,\nthey should be listed in the `mixins` field.\n\nSee [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/}\nfor more information on the classmixin pattern in JavaScript.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -1172,6 +1228,9 @@
     "Slot": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "_ui5propertyName": {
           "type": "string"
         },
@@ -1275,6 +1334,12 @@
     "VariableDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },

package/lib/cem/types-internal.d.ts

@@ -319,9 +319,20 @@ export interface Event {
   _ui5parameters?: Parameter[]
   _ui5privacy?: Privacy
   /**
-   * Whether the parameter is optional. Undefined implies non-optional.
+   * Whether the event is preventable.
+   */
+  _ui5allowPreventDefault?: boolean;
+
+  /**
+   * Whether the event is cancelable.
    */
-  _ui5allowPreventDefault?: boolean
+  _ui5Cancelable?: boolean;
+
+  /**
+   * Whether the event is bubbles.
+   */
+  _ui5Bubbles?: boolean;
+
   /**
    * Marks when the field was introduced
    */
@@ -484,6 +495,7 @@ export interface TypeReference extends Reference {
  * The common interface of classes and mixins.
  */
 export interface ClassLike {
+  _ui5experimental?: boolean | string
   _ui5implements?: Reference[]
   _ui5privacy?: Privacy
   /**

package/lib/cem/utils.mjs

@@ -3,6 +3,8 @@ import path from "path";
 
 let documentationErrors = new Map();
 
+const packageRegex = /^((@([a-z0-9._-]+)\/)?([a-z0-9._-]+))/;
+
 const getDeprecatedStatus = (jsdocComment) => {
     const deprecatedTag = findTag(jsdocComment, "deprecated");
     return deprecatedTag?.name
@@ -14,12 +16,23 @@ const getDeprecatedStatus = (jsdocComment) => {
             : undefined;
 };
 
+const getExperimentalStatus = (jsdocComment) => {
+    const experimentalTag = findTag(jsdocComment, "experimental");
+    return experimentalTag?.name
+        ? experimentalTag.description
+            ? `${experimentalTag.name} ${experimentalTag.description}`
+            : experimentalTag.name
+        : experimentalTag
+            ? true
+            : undefined;
+};
+
 const toKebabCase = str => {
     return str.replaceAll(/[A-Z]+(?![a-z])|[A-Z]/g, ($, ofs) => (ofs ? "-" : "") + $.toLowerCase())
 }
 
 const normalizeDescription = (description) => {
-	return typeof description === 'string' ? description.replaceAll(/^-\s+|^(\n)+|(\n)+$/g, ""): description;
+    return typeof description === 'string' ? description.replaceAll(/^-\s+|^(\n)+|(\n)+$/g, "") : description;
 }
 
 const getTypeRefs = (ts, node, member) => {
@@ -100,10 +113,22 @@ const findPackageName = (ts, sourceFile, typeName) => {
         if (currentModuleSpecifier?.text?.startsWith(".")) {
             return packageJSON?.name;
         } else {
-            return Object.keys(packageJSON?.dependencies || {}).find(
-                (dependency) =>
-                    currentModuleSpecifier?.text?.startsWith(`${dependency}/`)
-            );
+            // my-package/test
+            // my-package
+            // @scope/my-package
+            // my.package
+            // _mypackage
+            // mypackage-
+            // scope/my-package/test
+            // @scope/my-package/test
+            const match = currentModuleSpecifier?.text.match(packageRegex);
+            let packageName;
+
+            if (match) {
+                packageName = match[1];
+            }
+
+            return packageName || undefined;
         }
     }
 };
@@ -145,23 +170,24 @@ const findImportPath = (ts, sourceFile, typeName, modulePath) => {
                     ?.replace("src", "dist")?.replace(".ts", ".js") || undefined
             );
         } else {
-            const packageName = Object.keys(packageJSON?.dependencies || {}).find(
-                (dependency) =>
-                    currentModuleSpecifier?.text?.startsWith(dependency)
-            );
-            return currentModuleSpecifier?.text
-                ?.replace(`${packageName}/`, "") || undefined;
+            let packageName = currentModuleSpecifier?.text?.replace(packageRegex, "") || undefined;
+
+            if (packageName?.startsWith("/")) {
+                packageName = packageName.replace("/", "");
+            }
+
+            return packageName;
         }
     }
 };
 
 
 const isClass = text => {
-	return text.includes("@abstract") || text.includes("@class") || text.includes("@constructor");
+    return text.includes("@abstract") || text.includes("@class") || text.includes("@constructor");
 };
 
 const normalizeTagType = (type) => {
-	return type?.trim();
+    return type?.trim();
 }
 
 const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
@@ -211,13 +237,13 @@ const commonTags = ["public", "protected", "private", "since", "deprecated"];
 const allowedTags = {
     field: [...commonTags, "formEvents", "formProperty", "default"],
     slot: [...commonTags, "default"],
-    event: [...commonTags, "param", "allowPreventDefault", "native"],
+    event: [...commonTags, "param", "native", "allowPreventDefault"],
     eventParam: [...commonTags],
     method: [...commonTags, "param", "returns", "override"],
-    class: [...commonTags, "constructor", "class", "abstract", "implements", "extends", "slot", "csspart"],
-    enum: [...commonTags],
-    enumMember: [...commonTags],
-    interface: [...commonTags],
+    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
+    enum: [...commonTags, "experimental",],
+    enumMember: [...commonTags, "experimental",],
+    interface: [...commonTags, "experimental",],
 };
 allowedTags.getter = [...allowedTags.field, "override"]
 
@@ -230,19 +256,29 @@ const tagMatchCallback = (tag, tagName) => {
 };
 
 const findDecorator = (node, decoratorName) => {
-    return node?.decorators?.find(
+    return (node?.modifiers || node?.decorators)?.find(
         (decorator) =>
             decorator?.expression?.expression?.text === decoratorName
     );
 };
 
 const findAllDecorators = (node, decoratorName) => {
-    return (
-        node?.decorators?.filter(
-            (decorator) =>
-                decorator?.expression?.expression?.text === decoratorName
-        ) || []
-    );
+    if (typeof decoratorName === "string") {
+        return (node?.modifiers || node?.decorators)?.filter(decorator => decorator?.expression?.expression?.text === decoratorName) || [];
+    }
+
+    if (Array.isArray(decoratorName)) {
+        return (node?.modifiers || node?.decorators)?.filter(decorator => {
+            if (decorator?.expression?.expression?.text) {
+                return decoratorName.includes(decorator.expression.expression.text);
+            }
+
+            return false;
+        }
+        ) || [];
+    }
+
+    return [];
 };
 
 const hasTag = (jsDoc, tagName) => {
@@ -272,7 +308,7 @@ const findAllTags = (jsDoc, tagName) => {
 };
 
 const validateJSDocTag = (tag) => {
-    const booleanTags = ["private", "protected", "public", "abstract", "allowPreventDefault", "native", "formProperty", "constructor", "override"];
+    const booleanTags = ["private", "protected", "public", "abstract", "native", "allowPreventDefault", "formProperty", "constructor", "override"];
     let tagName = tag.tag;
 
     if (booleanTags.includes(tag.tag)) {
@@ -284,6 +320,8 @@ const validateJSDocTag = (tag) => {
             return !tag.name && !tag.type && !tag.description;
         case "deprecated":
             return !tag.type;
+        case "experimental":
+            return !tag.type;
         case "extends":
             return !tag.type && tag.name && !tag.description;
         case "implements":
@@ -316,7 +354,7 @@ const validateJSDocComment = (fieldType, jsdocComment, node, moduleDoc) => {
         let isValid = false
 
         if (fieldType === "event" && tag?.tag === "param") {
-            isValid = allowedTags[fieldType]?.includes(tag.tag) && validateJSDocTag({...tag, tag: "eventparam"});
+            isValid = allowedTags[fieldType]?.includes(tag.tag) && validateJSDocTag({ ...tag, tag: "eventparam" });
         } else {
             isValid = allowedTags[fieldType]?.includes(tag.tag) && validateJSDocTag(tag);
         }
@@ -345,26 +383,27 @@ const displayDocumentationErrors = () => {
     [...documentationErrors.keys()].forEach(modulePath => {
         const moduleErrors = documentationErrors.get(modulePath);
 
-        console.log(`=== ERROR: ${moduleErrors.length > 1 ? `${moduleErrors.length} problems` :  "Problem"} found in file: ${modulePath}:`)
+        console.log(`=== ERROR: ${moduleErrors.length > 1 ? `${moduleErrors.length} problems` : "Problem"} found in file: ${modulePath}:`)
         moduleErrors.forEach(moduleError => {
             errorsCount++;
             console.log(`\t- ${moduleError}`)
         })
     })
 
-    if(errorsCount) {
+    if (errorsCount) {
         throw new Error(`Found ${errorsCount} errors in the description of the public API.`);
     }
 }
 
 const formatArrays = (typeText) => {
-	return typeText?.replaceAll(/(\S+)\[\]/g, "Array<$1>")
+    return typeText?.replaceAll(/(\S+)\[\]/g, "Array<$1>")
 }
 
 export {
     getPrivacyStatus,
     getSinceStatus,
     getDeprecatedStatus,
+    getExperimentalStatus,
     getType,
     getReference,
     validateJSDocComment,