@ui5/webcomponents-tools 2.16.0-rc.0 → 2.16.0-rc.1

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/creators/createClass.js

@@ -0,0 +1,301 @@
+import ts from 'typescript';
+import { createFunctionLike } from './createFunctionLike.js';
+import { createAttribute, createAttributeFromField } from './createAttribute.js';
+import { createField } from './createClassField.js';
+import { handleHeritage, handleJsDoc, handleAttrJsDoc, handleTypeInference, handleDefaultValue } from './handlers.js';
+import { hasAttrAnnotation, hasIgnoreJSDoc, isDispatchEvent, isBindCall, isProperty, isReturnStatement } from '../../../utils/ast-helpers.js';
+import { resolveModuleOrPackageSpecifier } from '../../../utils/index.js';
+
+
+/**
+ * Creates a classDoc
+ */
+export function createClass(node, moduleDoc, context) {
+  let classTemplate = {
+    kind: 'class',
+    description: '',
+    /**
+     * In case of a class node?.name?.getText()
+     * In case of a mixin node?.parent?.parent?.name?.getText()
+     */
+    name: node?.name?.getText() || node?.parent?.parent?.name?.getText() || '',
+    cssProperties: [],
+    cssParts: [],
+    slots: [],
+    members: [],
+    events: [],
+    attributes: [],
+    cssStates: [],
+  };
+
+  node?.members?.forEach(member => {
+    /**
+     * Handle attributes
+     */
+    if (isProperty(member)) {
+      if (member?.name?.getText() === 'observedAttributes') {
+        /**
+         * @example static observedAttributes
+         */
+        if (ts.isPropertyDeclaration(member)) {
+          member?.initializer?.elements?.forEach((element) => {
+            if (ts.isStringLiteral(element)) {
+              const attribute = createAttribute(element);
+              classTemplate.attributes.push(attribute);
+            }
+          });
+        }
+
+        /**
+         * @example static get observedAttributes() {}
+         */
+        if (ts.isGetAccessor(member)) {
+          const returnStatement = member?.body?.statements?.find(isReturnStatement);
+
+          returnStatement?.expression?.elements?.forEach((element) => {
+            if (ts.isStringLiteral(element)) {
+              const attribute = createAttribute(element);
+              classTemplate.attributes.push(attribute);
+            }
+          });
+        }
+      }
+    }
+  });
+
+  /**
+   * Second pass through a class's members.
+   * We do this in two passes, because we need to know whether or not a class has any
+   * attributes, so we handle those first.
+   */
+  node?.members?.forEach(member => {
+    /**
+     * Handle class methods
+     */
+    if (ts.isMethodDeclaration(member) && !hasIgnoreJSDoc(member)) {
+      const method = createFunctionLike(member);
+      classTemplate.members.push(method);
+    }
+
+    /**
+     * Handle fields
+     */
+    if (isProperty(member) && !hasIgnoreJSDoc(member)) {
+      const field = createField(member);
+
+      /** If a member has only a getAccessor, it means it's readonly */
+      if(ts.isGetAccessor(member)) {
+        const hasSetter = node.members.some(m => ts.isSetAccessor(m) && m.name.getText() === field.name);
+        if(!hasSetter) {
+          field.readonly = true;
+        }
+      }
+
+      /** Flag class fields that get assigned a variable, so we can resolve it later (in the RESOLVE-INITIALIZERS plugin) */
+      if (member?.initializer?.kind === ts.SyntaxKind.Identifier) {
+        field.resolveInitializer = {
+          ...resolveModuleOrPackageSpecifier(moduleDoc, context, member?.initializer?.getText()),
+        }
+      }
+
+      /**
+       * Handle @attr
+       * If a field has a @attr annotation, also create an attribute for it
+       */
+      if (hasAttrAnnotation(member)) {
+        let attribute = createAttributeFromField(field);
+        attribute = handleAttrJsDoc(member, attribute);
+        field.attribute = attribute.name;
+
+        /**
+         * If the attribute already exists, merge it together with the extra
+         * information we got from the field (like type, summary, description, etc)
+         */
+        let attrAlreadyExists = classTemplate.attributes.find(attr => attr.name === attribute.name);
+
+        if (attrAlreadyExists) {
+          classTemplate.attributes = classTemplate.attributes.map(attr => {
+            return attr.name === attribute.name ? { ...attrAlreadyExists, ...attribute } : attr;
+          });
+        } else {
+          classTemplate.attributes.push(attribute);
+        }
+      }
+
+      /**
+       * A class can have a static prop and an instance prop with the same name,
+       * both should be output in the CEM
+       *
+       * If not a static prop, we merge getter and setter pairs here
+       */
+      if (field?.static) {
+        classTemplate.members.push(field);
+      } else {
+        const fieldExists = classTemplate.members
+          .filter(mem => !mem?.static)
+          .find(mem => mem?.name === member?.name?.getText());
+
+        if (fieldExists) {
+          classTemplate.members = classTemplate.members.map(mem => mem?.name === member?.name?.getText() && !mem?.static ? { ...mem, ...field } : mem);
+        } else {
+          classTemplate.members.push(field);
+        }
+      }
+    }
+
+    /**
+     * Handle events
+     *
+     * In order to find `this.dispatchEvent` calls, we have to traverse a method's AST
+     */
+    if (ts.isMethodDeclaration(member)) {
+      eventsVisitor(member, classTemplate);
+    }
+  });
+
+  getDefaultValuesFromConstructorVisitor(node, classTemplate, context);
+
+  classTemplate.members = classTemplate?.members?.filter(mem => !mem.ignore);
+
+  /**
+   * Inheritance
+   */
+  classTemplate = handleHeritage(classTemplate, moduleDoc, context, node);
+
+  return classTemplate;
+}
+
+function eventsVisitor(source, classTemplate) {
+  visitNode(source);
+
+  function visitNode(node) {
+    switch (node.kind) {
+      case ts.SyntaxKind.CallExpression:
+
+        /** If callexpression is `this.dispatchEvent` */
+        if (isDispatchEvent(node) && !hasIgnoreJSDoc(node.parent)) {
+          node?.arguments?.forEach((arg) => {
+            if (arg.kind === ts.SyntaxKind.NewExpression) {
+              /** e.g. `selected-changed` */
+              const eventName = arg?.arguments?.[0]?.text;
+              /**
+               * Check if event already exists
+               */
+              const eventExists = classTemplate?.events?.some(event => event.name === eventName);
+
+              if (!eventExists) {
+                let eventDoc = {
+                  ...(eventName ? { name: eventName } : {}),
+                  type: {
+                    text: arg.expression.text,
+                  },
+                };
+
+                eventDoc = handleJsDoc(eventDoc, node?.parent);
+                delete eventDoc.privacy;
+                classTemplate.events.push(eventDoc);
+              }
+            }
+          });
+
+        }
+    }
+
+    ts.forEachChild(node, visitNode);
+  }
+}
+
+export function getDefaultValuesFromConstructorVisitor(source, classTemplate, context) {
+  visitNode(source);
+
+  function visitNode(node) {
+    switch (node.kind) {
+      case ts.SyntaxKind.Constructor:
+        /**
+         * For every member that was added in the classDoc, we want to add a default value if we can
+         * To do this, we visit a class's constructor, and loop through the statements
+         */
+        node.body?.statements?.filter((statement) => statement.kind === ts.SyntaxKind.ExpressionStatement)
+          .filter((statement) => statement.expression.kind === ts.SyntaxKind.BinaryExpression)
+          .forEach((statement) => mapClassMember(source, classTemplate, context, node, statement, statement.expression));
+
+        break;
+    }
+
+    ts.forEachChild(node, visitNode);
+  }
+}
+
+function mapClassMember(source, classTemplate, context, node, statement, expression) {
+  let existingMember = classTemplate?.members?.find(member => expression?.left?.name?.getText() === member.name && member.kind === 'field');
+
+  // If the source is minified, or otherwise has a comma separated prop initialization
+  if (expression?.operatorToken?.kind === ts.SyntaxKind.CommaToken) {
+    if (expression.left.kind === ts.SyntaxKind.BinaryExpression) {
+      mapClassMember(source, classTemplate, context, node, statement, expression.left);
+    }
+    if (expression.right.kind === ts.SyntaxKind.BinaryExpression) {
+      mapClassMember(source, classTemplate, context, node, statement, expression.right);
+    }
+    return;
+  }
+
+  if (!existingMember) {
+    if (hasIgnoreJSDoc(statement)) return;
+    if (isBindCall(statement)) return;
+
+    existingMember = {
+      kind: 'field',
+      name: expression?.left?.name?.getText(),
+    }
+
+    if(!classTemplate.members){
+      classTemplate.members = [];
+    }
+
+    classTemplate.members.push(existingMember);
+  }
+
+  if (existingMember) {
+    if (hasIgnoreJSDoc(statement)) {
+      // schedule for deletion
+      existingMember.ignore = true;
+    }
+
+    if (!existingMember?.type) {
+      existingMember = handleTypeInference(existingMember, expression?.right);
+    }
+
+    existingMember = handleJsDoc(existingMember, statement);
+    existingMember = handleDefaultValue(existingMember, statement, expression);
+
+    /** Flag class fields that get assigned a variable, so we can resolve it later (in the RESOLVE-INITIALIZERS plugin) */
+    if (expression?.right?.kind === ts.SyntaxKind.Identifier) {
+      existingMember.resolveInitializer = {
+        ...resolveModuleOrPackageSpecifier({ path: source.getSourceFile().fileName }, context, expression?.right?.getText()),
+      }
+    }
+
+    if (hasAttrAnnotation(statement)) {
+      const field = existingMember
+      let attribute = createAttributeFromField(field);
+      attribute = handleAttrJsDoc(statement, attribute);
+
+      field.attribute = attribute.name;
+
+      /**
+        * If the attribute already exists, merge it together with the extra
+        * information we got from the field (like type, summary, description, etc)
+        */
+      let attrAlreadyExists = classTemplate.attributes.find(attr => attr.name === attribute.name);
+
+      if (attrAlreadyExists) {
+        classTemplate.attributes = classTemplate.attributes.map(attr => {
+          return attr.name === attribute.name ? { ...attrAlreadyExists, ...attribute } : attr;
+        });
+      } else {
+        classTemplate.attributes.push(attribute);
+      }
+    }
+  }
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/creators/createClassField.js

@@ -0,0 +1,26 @@
+import {
+  handleDefaultValue,
+  handleExplicitType,
+  handleJsDoc,
+  handleModifiers,
+  handlePrivateMember,
+  handleTypeInference,
+  handleWellKnownTypes
+} from './handlers.js';
+
+export function createField(node) {
+  let fieldTemplate = {
+    kind: 'field',
+    name: node?.name?.getText() || '',
+  }
+
+  fieldTemplate = handlePrivateMember(fieldTemplate, node);
+  fieldTemplate = handleTypeInference(fieldTemplate, node);
+  fieldTemplate = handleExplicitType(fieldTemplate, node);
+  fieldTemplate = handleModifiers(fieldTemplate, node);
+  fieldTemplate = handleDefaultValue(fieldTemplate, node);
+  fieldTemplate = handleWellKnownTypes(fieldTemplate, node);
+  fieldTemplate = handleJsDoc(fieldTemplate, node);
+
+  return fieldTemplate;
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/creators/createFunctionLike.js

@@ -0,0 +1,73 @@
+import ts from 'typescript';
+import { has } from '../../../utils/index.js';
+import { handleModifiers, handleJsDoc } from './handlers.js';
+
+/**
+ * Creates a functionLike, does _not_ handle arrow functions
+ */
+export function createFunctionLike(node) {
+  let functionLikeTemplate = {
+    kind: '',
+    name: node?.name?.getText() || ''
+  };
+  
+  functionLikeTemplate = handleKind(functionLikeTemplate, node);
+  functionLikeTemplate = handleModifiers(functionLikeTemplate, node);
+  functionLikeTemplate = handleParametersAndReturnType(functionLikeTemplate, node);
+  functionLikeTemplate = handleJsDoc(functionLikeTemplate, node);
+  
+  return functionLikeTemplate;
+}
+
+/**
+ * Determine the kind of the functionLike, either `'function'` or `'method'` 
+ */
+export function handleKind(functionLike, node) {
+  switch(node.kind) {
+    case ts.SyntaxKind.FunctionDeclaration:
+      functionLike.kind = 'function';
+      break;
+    case ts.SyntaxKind.MethodDeclaration:
+      functionLike.kind = 'method';
+      break;
+  }
+  return functionLike;
+}
+
+/**
+ * Handle a functionLikes return type and parameters/parameter types
+ */
+export function handleParametersAndReturnType(functionLike, node) {
+  if(node?.type) {
+    functionLike.return = {
+      type: { text: node.type.getText() }
+    }
+  }
+
+  const parameters = [];
+  node?.parameters?.forEach((param) => {  
+    const parameter = {
+      name: param.name.getText(),
+    }
+
+    if(param?.initializer) {
+      parameter.default = param.initializer.getText();
+    }
+
+    if(param?.questionToken) {
+      parameter.optional = true;
+    }
+
+    if(param?.type) {
+      parameter.type = {text: param.type.getText() }
+    }
+
+    parameters.push(parameter);
+  });
+
+  if(has(parameters)) {
+    functionLike.parameters = parameters;
+  }
+
+  return functionLike;
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/creators/createMixin.js

@@ -0,0 +1,33 @@
+import { createClass } from './createClass.js';
+import { handleParametersAndReturnType } from './createFunctionLike.js';
+import { handleJsDoc } from './handlers.js';
+
+/**
+ * Takes a mixinFunctionNode, which is the function/arrow function containing the mixin class
+ * and the actual class node returned by the mixin declaration
+ */
+export function createMixin(mixinFunctionNode, mixinClassNode, moduleDoc, context) {
+  let mixinTemplate = createClass(mixinClassNode, moduleDoc, context);
+
+  mixinTemplate = handleParametersAndReturnType(mixinTemplate, mixinFunctionNode?.declarationList?.declarations?.[0]?.initializer || mixinFunctionNode);
+  mixinTemplate = handleJsDoc(mixinTemplate, mixinFunctionNode);
+  mixinTemplate = handleName(mixinTemplate, mixinFunctionNode);
+  mixinTemplate = turnClassDocIntoMixin(mixinTemplate);
+
+  return mixinTemplate;
+}
+
+export function handleName(mixin, node) {
+  mixin.name = node?.name?.getText()  || node?.parent?.name?.getText() || node?.declarationList?.declarations?.[0]?.name?.getText() || '';
+  return mixin;
+}
+
+/**
+ * Turns a classDoc into a mixin
+ */
+function turnClassDocIntoMixin(mixin) {
+  mixin.kind = 'mixin';
+  delete mixin.superclass;
+  delete mixin.return;
+  return mixin;
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/creators/createVariable.js

@@ -0,0 +1,22 @@
+import {
+  handleDefaultValue,
+  handleExplicitType,
+  handleJsDoc,
+  handleTypeInference,
+  handleWellKnownTypes
+} from './handlers.js';
+
+export function createVariable(variableStatementNode, declarationNode) {
+  let variableTemplate = {
+    kind: 'variable',
+    name: declarationNode?.name?.getText() || ''
+  };
+
+  variableTemplate = handleTypeInference(variableTemplate, declarationNode);
+  variableTemplate = handleExplicitType(variableTemplate, declarationNode);
+  variableTemplate = handleWellKnownTypes(variableTemplate, declarationNode);
+  variableTemplate = handleDefaultValue(variableTemplate, declarationNode);
+  variableTemplate = handleJsDoc(variableTemplate, variableStatementNode);
+
+  return variableTemplate;
+}