@ui5/webcomponents-tools 0.0.0-bf8366eb6 → 0.0.0-c143e338b

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

@@ -0,0 +1,26 @@
+import { hasInitializer } from '../../utils/ast-helpers.js';
+import { isMixin } from '../../utils/mixins.js';
+import { createArrowFunction } from './creators/createArrowFunction.js';
+
+
+/**
+ * arrowFunctionPlugin
+ * 
+ * handles arrow functions
+ */
+export function arrowFunctionPlugin() {
+  return {
+    name: 'CORE - ARROW-FUNCTION',
+    analyzePhase({ts, node, moduleDoc}){
+      switch(node.kind) {
+        case ts.SyntaxKind.VariableStatement:
+          if(!isMixin(node) && hasInitializer(node)) {
+            const functionLike = createArrowFunction(node);
+            moduleDoc.declarations.push(functionLike);
+          }
+          break;
+      }
+    }
+  }
+}
+

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

@@ -0,0 +1,157 @@
+import { parse } from 'comment-parser';
+import { handleJsDocType, normalizeDescription } from '../../utils/jsdoc.js';
+import { has, safe } from '../../utils/index.js';
+
+/**
+ * CLASS-JSDOC
+ *
+ * Deals with any JSDoc above a class
+ */
+export function classJsDocPlugin() {
+  return {
+    name: 'CORE - CLASS-JSDOC',
+    analyzePhase({ts, node, moduleDoc}){
+      switch (node.kind) {
+        case ts.SyntaxKind.ClassDeclaration:
+          const className = node?.name?.getText();
+          const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+
+          /**
+           * Because we use a bunch of 'non-standard' JSDoc annotations, TS doesn't recognize most of them.
+           * Instead we use `comment-parser` to parse the JSDoc.
+           *
+           * Loops through each JSDoc (yes, there can be multiple) above a class, and parses every JSDoc annotation
+           *
+           * Checks to see if the item is already in the classDoc, and if so merge and overwrite (JSDoc takes precedence)
+           */
+          node?.jsDoc?.forEach(jsDoc => {
+            const parsed = parse(jsDoc?.getFullText());
+            parsed?.forEach(parsedJsDoc => {
+
+              /**
+               * If any of the tags is a `@typedef`, we ignore it; this JSDoc comment may be above a class,
+               * it probably doesnt _belong_ to the class, but something else in the file
+               */
+              if(parsedJsDoc?.tags?.some(tag => tag?.tag === 'typedef')) return;
+
+              parsedJsDoc?.tags?.forEach(jsDoc => {
+                switch(jsDoc.tag) {
+                  case 'attr':
+                  case 'attribute':
+                    const attributeAlreadyExists = classDoc?.attributes?.find(attr => attr.name === jsDoc.name);
+                    let attributeDoc = attributeAlreadyExists || {};
+                    attributeDoc = handleClassJsDoc(attributeDoc, jsDoc);
+                    if(!attributeAlreadyExists) {
+                      classDoc.attributes.push(attributeDoc);
+                    }
+                    break;
+                  case 'prop':
+                  case 'property':
+                    const fieldAlreadyExists = classDoc?.members?.find(member => member.name === jsDoc.name);
+                    let fieldDoc = fieldAlreadyExists || {};
+                    fieldDoc = handleClassJsDoc(fieldDoc, jsDoc);
+                    fieldDoc.kind = 'field';
+                    if(!fieldAlreadyExists) {
+                      classDoc.members.push(fieldDoc);
+                    }
+                    break;
+                  case 'fires':
+                  case 'event':
+                    const eventAlreadyExists = classDoc?.events?.find(event => event.name === jsDoc.name);
+                    let eventDoc = eventAlreadyExists || {};
+                    eventDoc = handleClassJsDoc(eventDoc, jsDoc);
+                    delete eventDoc.privacy;
+                    if(!eventAlreadyExists) {
+                      classDoc.events.push(eventDoc);
+                    }
+                    break;
+                  case 'csspart':
+                  case 'part':
+                    let cssPartDoc = {};
+                    cssPartDoc = handleClassJsDoc(cssPartDoc, jsDoc);
+                    classDoc.cssParts.push(cssPartDoc);
+                    break;
+                  case 'cssprop':
+                  case 'cssproperty':
+                    let cssPropertyDoc = {};
+                    cssPropertyDoc = handleClassJsDoc(cssPropertyDoc, jsDoc);
+                    classDoc.cssProperties.push(cssPropertyDoc);
+                    break;
+                  case 'slot':
+                    let slotDoc = {};
+                    slotDoc = handleClassJsDoc(slotDoc, jsDoc);
+                    classDoc.slots.push(slotDoc);
+                    break;
+                  case 'tag':
+                  case 'tagname':
+                  case 'element':
+                  case 'customElement':
+                  case 'customelement':
+                    classDoc.tagName = jsDoc?.name || '';
+                    classDoc.customElement = true;
+                    break;
+                  case 'cssState':
+                  case 'cssstate':
+                    let statePropertyDoc = {};
+                    statePropertyDoc = handleClassJsDoc(statePropertyDoc, jsDoc);
+                    classDoc.cssStates.push(statePropertyDoc);
+                    break;
+                  case 'deprecated':
+                    classDoc.deprecated = jsDoc?.name ? `${jsDoc.name} ${jsDoc?.description}`.trim() : "true";
+                    break;
+                }
+              })
+            });
+
+            /**
+             * Description
+             */
+            if(jsDoc?.comment) {
+              if(has(jsDoc?.comment)) {
+                classDoc.description = jsDoc.comment.map(com => `${safe(() => com?.name?.getText()) ?? ''}${com.text}`).join('');
+              } else {
+                classDoc.description = normalizeDescription(jsDoc.comment);
+              }
+            }
+
+            /**
+             * Comment-parse doesn't handle annotations with only a description correctly, for example:
+             * @summary foo bar
+             * will output only 'bar' as the description.
+             *
+             * Instead, we use TS for this JSDoc annotation.
+             */
+            jsDoc?.tags?.forEach(tag => {
+              switch(safe(() => tag?.tagName?.getText())) {
+                case 'summary':
+                  classDoc.summary = tag?.comment;
+                  break;
+              }
+            });
+          });
+
+          break;
+      }
+    }
+  }
+}
+
+function handleClassJsDoc(doc, tag) {
+  if(tag?.type) {
+    doc.type = { text: handleJsDocType(tag.type) }
+  }
+
+  if(tag?.description) {
+    doc.description = normalizeDescription(tag.description);
+  }
+
+  if(tag?.name) {
+    doc.name = tag.name === '-' ? '' : tag.name;
+  }
+
+  if(tag?.default) {
+    doc.default = tag.default;
+  }
+
+  return doc;
+}

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

@@ -0,0 +1,20 @@
+import { createClass } from './creators/createClass.js';
+
+/**
+ * classPlugin
+ * 
+ * handles classes
+ */
+export function classPlugin() {
+  return {
+    name: 'CORE - CLASSES',
+    analyzePhase({ts, node, moduleDoc, context}){
+      switch(node.kind) {
+        case ts.SyntaxKind.ClassDeclaration:
+          const klass = createClass(node, moduleDoc, context);
+          moduleDoc.declarations.push(klass);
+          break;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+import ts from 'typescript';
+import { handleParametersAndReturnType } from './createFunctionLike.js';
+import { handleJsDoc } from './handlers.js';
+
+export function createArrowFunction(node) {
+  const arrowFunction = node?.declarationList?.declarations?.find(declaration => ts.SyntaxKind.ArrowFunction === declaration?.initializer?.kind);
+
+  let functionLikeTemplate = {
+    kind: 'function',
+    name: arrowFunction?.name?.getText() || '',
+  };
+  
+  functionLikeTemplate = handleParametersAndReturnType(functionLikeTemplate, arrowFunction?.initializer);
+  functionLikeTemplate = handleJsDoc(functionLikeTemplate, node);
+
+  return functionLikeTemplate;
+}

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

@@ -0,0 +1,24 @@
+export function createAttribute(node) {
+  const attributeTemplate = {
+    name: node?.text || ''
+  }
+  return attributeTemplate;
+}
+
+export function createAttributeFromField(field) {
+  const attribute = {
+    ...field,
+    fieldName: field.name
+  }
+
+  /** 
+   * Delete the following properties because they don't exist on a attributeDoc 
+   */
+  delete attribute.kind;
+  delete attribute.static;
+  delete attribute.privacy;
+  delete attribute.reflects;
+  delete attribute.resolveInitializer;
+
+  return attribute;
+}

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;
+}