@ui5/webcomponents-tools 0.0.0-07460127d → 0.0.0-093de5dd1

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

@@ -0,0 +1,117 @@
+import ts from 'typescript';
+import { FEATURES } from './features/index.js';
+import { withErrorHandling } from './utils/index.js';
+
+/**
+ * CORE
+ *
+ * This function is the core of the analyzer. It takes an array of ts sourceFiles, and creates a
+ * custom elements manifest.
+ */
+export function create({modules, plugins = [], context = {dev:false}}) {
+  const customElementsManifest = {
+    schemaVersion: '1.0.0',
+    readme: '',
+    modules: [],
+  };
+
+  const { dev } = context;
+
+  const mergedPlugins = [
+    ...FEATURES,
+    ...plugins,
+  ];
+
+  if(dev) console.log('[INITIALIZE PLUGINS]');
+  mergedPlugins.forEach(({name, initialize}) => {
+    withErrorHandling(name, () => {
+      initialize?.({ts, customElementsManifest, context});
+    });
+  });
+
+  modules.forEach(currModule => {
+    if(dev) console.log('[COLLECT PHASE]: ', currModule.fileName);
+    /**
+     * COLLECT PHASE
+     * First pass through all modules. Can be used to gather imports, exports, types, default values,
+     * which you may need to know the existence of in a later phase.
+     */
+    collect(currModule, context, mergedPlugins);
+  });
+
+  modules.forEach(currModule => {
+    if(dev) console.log('[ANALYZE PHASE]: ', currModule.fileName);
+    const moduleDoc = {
+      kind: "javascript-module",
+      path: currModule.fileName,
+      declarations: [],
+      exports: []
+    };
+
+    /**
+     * ANALYZE PHASE
+     * Go through the AST of every separate module, and gather as much as information as we can
+     * This includes a modules imports, which are not specified in custom-elements.json, but are
+     * required for the LINK PHASE, and deleted when processed
+     */
+    analyze(currModule, moduleDoc, context, mergedPlugins);
+    customElementsManifest.modules.push(moduleDoc);
+
+    if(dev) console.log('[MODULE LINK PHASE]: ', currModule.fileName);
+    /**
+     * LINK PHASE
+     * All information for a module has been gathered, now we can link information together. Like:
+     * - Finding a CustomElement's tagname by finding its customElements.define() call (or 'export')
+     * - Applying inheritance to classes (adding `inheritedFrom` properties/attrs/events/methods)
+     */
+    mergedPlugins.forEach(({name, moduleLinkPhase}) => {
+      withErrorHandling(name, () => {
+        moduleLinkPhase?.({ts, moduleDoc, context});
+      });
+    });
+  });
+
+  if(dev) console.log('[PACKAGE LINK PHASE]');
+  /**
+   * PACKAGE LINK PHASE
+   * All modules have now been parsed, we can now link information from across modules together
+   * - Link classes to their definitions etc
+   * - Match tagNames for classDocs
+   * - Apply inheritance
+   */
+  mergedPlugins.forEach(({name, packageLinkPhase}) => {
+    withErrorHandling(name, () => {
+      packageLinkPhase?.({customElementsManifest, context});
+    });
+  });
+
+  return customElementsManifest;
+}
+
+function collect(source, context, mergedPlugins) {
+  visitNode(source);
+
+  function visitNode(node) {
+    mergedPlugins.forEach(({name, collectPhase}) => {
+      withErrorHandling(name, () => {
+        collectPhase?.({ts, node, context});
+      });
+    });
+
+    ts.forEachChild(node, visitNode);
+  }
+}
+
+function analyze(source, moduleDoc, context, mergedPlugins) {
+  visitNode(source);
+
+  function visitNode(node) {
+    mergedPlugins.forEach(({name, analyzePhase}) => {
+      withErrorHandling(name, () => {
+        analyzePhase?.({ts, node, moduleDoc, context});
+      });
+    });
+
+    ts.forEachChild(node, visitNode);
+  }
+}

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