@ui5/webcomponents-tools 0.0.0-9261ac932 → 0.0.0-95afb1087

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

@@ -407,6 +407,9 @@
     "CssCustomProperty": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "default": {
           "type": "string"
         },
@@ -443,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": [
@@ -1222,6 +1228,9 @@
     "Slot": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "_ui5propertyName": {
           "type": "string"
         },

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
@@ -30,7 +32,7 @@ const toKebabCase = str => {
 }
 
 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) => {
@@ -111,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;
         }
     }
 };
@@ -156,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"));
@@ -226,7 +241,7 @@ const allowedTags = {
     eventParam: [...commonTags],
     method: [...commonTags, "param", "returns", "override"],
     class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
-    enum: [...commonTags],
+    enum: [...commonTags, "experimental",],
     enumMember: [...commonTags, "experimental",],
     interface: [...commonTags, "experimental",],
 };
@@ -241,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) => {
@@ -329,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);
         }
@@ -358,20 +383,20 @@ 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 {

package/lib/cem/validate.js

@@ -1,70 +1,76 @@
 const fs = require('fs');
 const Ajv = require('ajv');
 const path = require('path');
-const yargs = require('yargs/yargs')
-const { hideBin } = require('yargs/helpers')
-const argv = yargs(hideBin(process.argv))
-	.argv;
-
 // Load your JSON schema
 const extenalSchema = require('./schema.json');
 const internalSchema = require('./schema-internal.json');
 
-// Load your JSON data from the input file
-const inputFilePath = path.join(process.cwd(), "dist/custom-elements.json"); // Update with your file path
-const customManifest = fs.readFileSync(inputFilePath, 'utf8');
-const inputDataInternal = JSON.parse(customManifest);
 
-inputDataInternal.modules.forEach(moduleDoc => {
-    moduleDoc.exports = moduleDoc.exports.
-    filter(e => moduleDoc.declarations.find(d => d.name === e.declaration.name && ["class", "function", "variable", "enum"].includes(d.kind)) || e.name === "default");
-})
+const validateFn = async () => {
+	// Load your JSON data from the input file
+	const inputFilePath = path.join(process.cwd(), "dist/custom-elements.json"); // Update with your file path
+	const customManifest = fs.readFileSync(inputFilePath, 'utf8');
+	const inputDataInternal = JSON.parse(customManifest);
+	const devMode = process.env.UI5_CEM_MODE === "dev";
 
-const clearProps = (data) => {
-    if (Array.isArray(data)) {
-        for (let i = 0; i < data.length; i++) {
-            if (typeof data[i] === "object") {
-                if (["enum", "interface"].includes(data[i].kind)) {
-                    data.splice(i, 1);
-                    i--;
-                } else {
-                    clearProps(data[i]);
-                }
-            }
-        }
-    } else if (typeof data === "object") {
-        Object.keys(data).forEach(prop => {
-            if (prop.startsWith("_ui5")) {
-                delete data[prop];
-            } else if (typeof data[prop] === "object") {
-                clearProps(data[prop]);
-            }
-        });
-    }
+	inputDataInternal.modules.forEach(moduleDoc => {
+		moduleDoc.exports = moduleDoc.exports.
+			filter(e => moduleDoc.declarations.find(d => d.name === e.declaration.name && ["class", "function", "variable", "enum"].includes(d.kind)) || e.name === "default");
+	})
 
-    return data;
-}
+	const clearProps = (data) => {
+		if (Array.isArray(data)) {
+			for (let i = 0; i < data.length; i++) {
+				if (typeof data[i] === "object") {
+					if (["enum", "interface"].includes(data[i].kind)) {
+						data.splice(i, 1);
+						i--;
+					} else {
+						clearProps(data[i]);
+					}
+				}
+			}
+		} else if (typeof data === "object") {
+			Object.keys(data).forEach(prop => {
+				if (prop.startsWith("_ui5")) {
+					delete data[prop];
+				} else if (typeof data[prop] === "object") {
+					clearProps(data[prop]);
+				}
+			});
+		}
+
+		return data;
+	}
 
-const ajv = new Ajv({ allowUnionTypes: true, allError: true })
-let validate = ajv.compile(internalSchema)
+	const ajv = new Ajv({ allowUnionTypes: true, allError: true })
+	let validate = ajv.compile(internalSchema)
 
-// Validate the JSON data against the schema
-if (argv.dev) {
-    if (validate(inputDataInternal)) {
-        console.log('Internal custom  element manifest is validated successfully');
-    } else {
-        throw new Error(`Validation of internal custom elements manifest failed: ${validate.errors}`);
-    }
+	// Validate the JSON data against the schema
+	if (devMode) {
+		if (validate(inputDataInternal)) {
+			console.log('Internal custom  element manifest is validated successfully');
+		} else {
+			console.log(validate.errors)
+			throw new Error(`Validation of internal custom elements manifest failed: ${validate.errors}`);
+		}
+	}
+
+	const inputDataExternal = clearProps(JSON.parse(JSON.stringify(inputDataInternal)));
+	validate = ajv.compile(extenalSchema)
+
+	// Validate the JSON data against the schema
+	if (validate(inputDataExternal)) {
+		console.log('Custom element manifest is validated successfully');
+		fs.writeFileSync(inputFilePath, JSON.stringify(inputDataExternal, null, 2), 'utf8');
+		fs.writeFileSync(inputFilePath.replace("custom-elements", "custom-elements-internal"), JSON.stringify(inputDataInternal, null, 2), 'utf8');
+	} else if (devMode) {
+		throw new Error(`Validation of public custom elements manifest failed: ${validate.errors}`);
+	}
 }
 
-const inputDataExternal = clearProps(JSON.parse(JSON.stringify(inputDataInternal)));
-validate = ajv.compile(extenalSchema)
+if (require.main === module) {
+	validateFn()
+}
 
-// Validate the JSON data against the schema
-if (validate(inputDataExternal)) {
-    console.log('Custom element manifest is validated successfully');
-    fs.writeFileSync(inputFilePath, JSON.stringify(inputDataExternal, null, 2), 'utf8');
-    fs.writeFileSync(inputFilePath.replace("custom-elements", "custom-elements-internal"), JSON.stringify(inputDataInternal, null, 2), 'utf8');
-} else if (argv.dev) {
-    throw new Error(`Validation of public custom elements manifest failed: ${validate.errors}`);
-    }
+exports._ui5mainFn = validateFn;

package/lib/chokidar/chokidar.js

@@ -0,0 +1,29 @@
+const chokidar = require('chokidar');
+const { exec } = require("child_process");
+
+
+const main = async (argv) => {
+	if (argv.length < 4) {
+		console.error("Please provide a file pattern to watch and a command to execute on changes.");
+		console.error("<file-pattern> <command>");
+		process.exit(1);
+	}
+	console.log(argv);
+	const filePattern = argv[2];
+	const command = argv.slice(3).join(' ');
+
+	const watcher = new chokidar.FSWatcher();
+
+	watcher.add(filePattern);
+	watcher.unwatch("src/generated");
+
+	watcher.on('change', async () => {
+		exec(command);
+	});
+};
+
+if (require.main === module) {
+	main(process.argv)
+}
+
+exports._ui5mainFn = main;