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

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

@@ -0,0 +1,338 @@
+import ts from 'typescript';
+import { parse } from 'comment-parser';
+
+import { has, resolveModuleOrPackageSpecifier, safe } from '../../../utils/index.js';
+import { handleJsDocType, normalizeDescription } from '../../../utils/jsdoc.js';
+import { isWellKnownType } from '../../../utils/ast-helpers.js';
+
+/**
+ * @example static foo;
+ * @example public foo;
+ * @example private foo;
+ * @example protected foo;
+ */
+export function handleModifiers(doc, node) {
+  node?.modifiers?.forEach(modifier => {
+    if(modifier?.kind === ts.SyntaxKind.StaticKeyword) {
+      doc.static = true;
+    }
+
+    if (modifier?.kind === ts.SyntaxKind.ReadonlyKeyword) {
+      doc.readonly = true;
+    }
+
+    switch (modifier.kind) {
+      case ts.SyntaxKind.PublicKeyword:
+        doc.privacy = 'public';
+        break;
+      case ts.SyntaxKind.PrivateKeyword:
+        doc.privacy = 'private';
+        break;
+      case ts.SyntaxKind.ProtectedKeyword:
+        doc.privacy = 'protected';
+        break;
+    }
+  });
+
+  if (node.name?.text?.startsWith('#')) {
+    doc.privacy = 'private';
+  }
+
+  return doc;
+}
+
+/**
+ * Handles JsDoc
+ */
+export function handleJsDoc(doc, node) {
+  node?.jsDoc?.forEach(jsDocComment => {
+    if(jsDocComment?.comment) {
+      if(has(jsDocComment?.comment)) {
+        doc.description = jsDocComment.comment.map(com => `${safe(() => com?.name?.getText()) ?? ''}${com.text}`).join('');
+      } else {
+        doc.description = normalizeDescription(jsDocComment.comment);
+      }
+    }
+
+    jsDocComment?.tags?.forEach(tag => {
+      /** @readonly */
+      if(tag.kind === ts.SyntaxKind.JSDocReadonlyTag) {
+        doc.readonly = true;
+      }
+
+      /** @param */
+      if(tag.kind === ts.SyntaxKind.JSDocParameterTag) {
+        const parameter = doc?.parameters?.find(parameter => parameter.name === tag.name.text);
+        const parameterAlreadyExists = !!parameter;
+        const parameterTemplate = parameter || {};
+
+        if(tag?.comment) {
+          parameterTemplate.description = normalizeDescription(tag.comment);
+        }
+
+        if(tag?.name) {
+          parameterTemplate.name = tag.name.getText();
+        }
+
+        /**
+         * If its bracketed, that means its optional
+         * @example [foo]
+         */
+        if(tag?.isBracketed) {
+          parameterTemplate.optional = true;
+        }
+
+        if(tag?.typeExpression) {
+          parameterTemplate.type = {
+            text: handleJsDocType(tag.typeExpression.type.getText())
+          }
+        }
+
+        if(!parameterAlreadyExists) {
+          doc.parameters = [...(doc?.parameters || []), parameterTemplate];
+        }
+      }
+
+      /** @returns */
+      if(tag.kind === ts.SyntaxKind.JSDocReturnTag) {
+        doc.return = {
+          type: {
+            text: handleJsDocType(tag?.typeExpression?.type?.getText())
+          }
+        }
+      }
+
+      /** @type */
+      if(tag.kind === ts.SyntaxKind.JSDocTypeTag) {
+        if(tag?.comment) {
+          doc.description = normalizeDescription(tag.comment);
+        }
+
+        doc.type = {
+          text: handleJsDocType(tag.typeExpression.type.getText())
+        }
+      }
+
+      /** @reflect */
+      if(safe(() => tag?.tagName?.getText()) === 'reflect' && doc?.kind === 'field') {
+        doc.reflects = true;
+      }
+
+      /** @summary */
+      if(safe(() => tag?.tagName?.getText()) === 'summary') {
+        doc.summary = tag.comment;
+      }
+
+      /** @deprecated */
+      if(safe(() => tag?.tagName?.getText()) === 'deprecated') {
+        doc.deprecated = tag.comment || "true";
+      }
+
+      /** @default */
+      if (safe(() => tag?.tagName?.getText()) === 'default' && doc?.kind === 'field') {
+        doc.default ??= tag.comment;
+      }
+
+      /**
+       * Overwrite privacy
+       * @public
+       * @private
+       * @protected
+       */
+      switch(tag.kind) {
+        case ts.SyntaxKind.JSDocPublicTag:
+          doc.privacy = 'public';
+          break;
+        case ts.SyntaxKind.JSDocPrivateTag:
+          doc.privacy = 'private';
+          break;
+        case ts.SyntaxKind.JSDocProtectedTag:
+          doc.privacy = 'protected';
+          break;
+      }
+    });
+  });
+
+  return doc;
+}
+
+
+
+/**
+ * Creates a mixin for inside a classDoc
+ */
+export function createClassDeclarationMixin(name, moduleDoc, context) {
+  const mixin = {
+    name,
+    ...resolveModuleOrPackageSpecifier(moduleDoc, context, name)
+  };
+  return mixin;
+}
+
+/**
+ * Handles mixins and superclass
+ */
+export function handleHeritage(classTemplate, moduleDoc, context, node) {
+  node?.heritageClauses?.forEach((clause) => {
+    /* Ignoring `ImplementsKeyword` for now, future revisions may retrieve docs per-field for the implemented methods. */
+    if (clause.token !== ts.SyntaxKind.ExtendsKeyword) return;
+
+    clause?.types?.forEach((type) => {
+      const mixins = [];
+      let node = type.expression;
+      let superClass;
+
+      /* gather mixin calls */
+      if (ts.isCallExpression(node)) {
+        const mixinName = node.expression.getText();
+        mixins.push(createClassDeclarationMixin(mixinName, moduleDoc, context))
+        while (ts.isCallExpression(node.arguments[0])) {
+          node = node.arguments[0];
+          const mixinName = node.expression.getText();
+          mixins.push(createClassDeclarationMixin(mixinName, moduleDoc, context));
+        }
+        superClass = node.arguments[0].text;
+      } else {
+        superClass = node.text;
+      }
+
+      if (has(mixins)) {
+        classTemplate.mixins = mixins;
+      }
+
+      classTemplate.superclass = {
+        name: superClass,
+        ...resolveModuleOrPackageSpecifier(moduleDoc, context, superClass)
+      };
+
+      if(superClass === 'HTMLElement') {
+        delete classTemplate.superclass.module;
+      }
+    });
+  });
+
+  return classTemplate;
+}
+
+/**
+ * Handles fields that have an @attr jsdoc annotation and gets the attribute name (if specified) and the description
+ * @example @attr my-attr this is the attr description
+ */
+export function handleAttrJsDoc(node, doc) {
+  node?.jsDoc?.forEach(jsDoc => {
+    const docs = parse(jsDoc?.getFullText())?.find(doc => doc?.tags?.some(({tag}) => ["attribute", "attr"].includes(tag)));
+    const attrTag = docs?.tags?.find(({tag}) => ["attribute", "attr"].includes(tag));
+
+    if(attrTag?.name) {
+      doc.name = attrTag.name;
+    }
+
+    if(attrTag?.description) {
+      doc.description = normalizeDescription(attrTag.description);
+    }
+  });
+
+  return doc;
+}
+
+export function handleTypeInference(doc, node) {
+  const n = node?.initializer || node;
+  switch(n?.kind) {
+    case ts.SyntaxKind.TrueKeyword:
+    case ts.SyntaxKind.FalseKeyword:
+      doc.type = { text: "boolean" }
+      break;
+    case ts.SyntaxKind.StringLiteral:
+      doc.type = { text: "string" }
+      break;
+    case ts.SyntaxKind.PrefixUnaryExpression:
+      doc.type = n?.operator === ts.SyntaxKind.ExclamationToken ? { text: "boolean" } : { text: "number" };
+      break;
+    case ts.SyntaxKind.NumericLiteral:
+      doc.type = { text: "number" }
+      break;
+    case ts.SyntaxKind.NullKeyword:
+      doc.type = { text: "null" }
+      break;
+    case ts.SyntaxKind.ArrayLiteralExpression:
+      doc.type = { text: "array" }
+      break;
+    case ts.SyntaxKind.ObjectLiteralExpression:
+      doc.type = { text: "object" }
+      break;
+  }
+  return doc;
+}
+
+/**
+ * For `as const` and namespace/enum types
+ * @example class A { b = 'b' as const }
+ * @example class A { b = B.b }
+ */
+export function handleWellKnownTypes(doc, node) {
+  if (!!node.initializer?.expression) {
+    const text = node?.initializer?.expression?.getText();
+    if (isWellKnownType(node)) {
+      doc.type = { text };
+    }
+  }
+  return doc;
+}
+
+export function handleDefaultValue(doc, node, expression) {
+  /**
+   * In case of a class field node?.initializer
+   * In case of a property assignment in constructor node?.expression?.right
+   */
+  const initializer = node?.initializer || expression?.right;
+
+  /** Ignore the following */
+  if(initializer?.kind === ts.SyntaxKind.BinaryExpression) return doc;
+  if(initializer?.kind === ts.SyntaxKind.ConditionalExpression) return doc;
+  if(initializer?.kind === ts.SyntaxKind.PropertyAccessExpression) return doc;
+  if(initializer?.kind === ts.SyntaxKind.CallExpression) return doc;
+  if(initializer?.kind === ts.SyntaxKind.ArrowFunction) return doc;
+
+  let defaultValue;
+  /**
+   * Check if value has `as const`
+   * @example const foo = 'foo' as const;
+   */
+  if(initializer?.kind === ts.SyntaxKind.AsExpression) {
+    defaultValue = initializer?.expression?.getText()
+  } else {
+    defaultValue = initializer?.getText()
+  }
+
+  if(defaultValue) {
+    doc.default = defaultValue.replace(/\s+/g, ' ').trim();
+  }
+  return doc;
+}
+
+/**
+ * Add TS type
+ * @example class Foo { bar: string = ''; }
+ */
+export function handleExplicitType(doc, node) {
+  if(node.type) {
+    doc.type = { text: node.type.getText() }
+
+    if(node?.questionToken) {
+      doc.type.text += ' | undefined';
+    }
+  }
+
+  return doc;
+}
+
+/**
+ * if is private field
+ * @example class Foo { #bar = ''; }
+ */
+export function handlePrivateMember(doc, node) {
+  if (ts.isPrivateIdentifier(node.name)) {
+    doc.privacy = 'private';
+  }
+  return doc;
+}

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

@@ -0,0 +1,90 @@
+import { getDeclarationInFile, hasIgnoreJSDoc, isCustomElementsDefineCall } from '../../utils/ast-helpers.js';
+import { resolveModuleOrPackageSpecifier } from '../../utils/index.js';
+import { createClass } from './creators/createClass.js';
+
+/**
+ * CUSTOM-ELEMENTS-DEFINE-CALLS
+ * 
+ * Analyzes calls for:
+ * @example customElements.define()
+ * @example window.customElements.define()
+ */
+export function customElementsDefineCallsPlugin() {
+  let counter;
+  return {
+    name: 'CORE - CUSTOM-ELEMENTS-DEFINE-CALLS',
+    analyzePhase({ts, node, moduleDoc, context}){    
+      if(node?.kind === ts.SyntaxKind.SourceFile) {
+        counter = 0;
+      }
+
+      if (hasIgnoreJSDoc(node))
+        return;
+
+      /** 
+       * @example customElements.define('my-el', MyEl); 
+       * @example window.customElements.define('my-el', MyEl);
+       */
+      if(isCustomElementsDefineCall(node)) {
+        const classArg = node.parent.arguments[1];
+        let isAnonymousClass = classArg?.kind === ts.SyntaxKind.ClassExpression;
+        let isUnnamed = classArg?.name === undefined;
+
+        if(isAnonymousClass) {
+          const klass = createClass(classArg, moduleDoc, context);
+
+          if(isUnnamed) {
+            klass.name = `anonymous_${counter}`;
+          }
+          moduleDoc.declarations.push(klass);
+        }
+
+        let elementClass;
+
+        /** 
+         * @example customElements.define('m-e', class extends HTMLElement{}) 
+         *                                            ^
+         */
+        if(isUnnamed) {
+          elementClass = `anonymous_${counter}`;
+          counter = counter + 1;
+        }
+
+        /** 
+         * @example customElements.define('m-e', MyElement) 
+         *                                       ^^^^^^^^^
+         */
+        if(node?.parent?.arguments?.[1]?.text) {
+          elementClass = node.parent.arguments[1].text;
+        }
+
+        /** 
+         * @example customElements.define('m-e', class MyElement extends HTMLElement{}) 
+         *                                             ^^^^^^^^^
+         */
+        if(classArg?.name) {
+          elementClass = classArg?.name?.getText();
+        }
+
+        const elementTag = node.parent.arguments[0].text;
+
+        const klass = getDeclarationInFile(elementClass, node?.getSourceFile());
+
+        if (hasIgnoreJSDoc(klass))
+          return;
+
+        const definitionDoc = {
+          kind: 'custom-element-definition',
+          name: elementTag,
+          declaration: {
+            name: elementClass,
+            ...resolveModuleOrPackageSpecifier(moduleDoc, context, elementClass)
+          },
+        };
+    
+        moduleDoc.exports = [...(moduleDoc.exports || []), definitionDoc];
+      }
+    }
+  }
+}
+

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

@@ -0,0 +1,156 @@
+import { getDeclarationInFile, hasIgnoreJSDoc } from '../../utils/ast-helpers.js';
+import {
+  hasExportModifier,
+  hasDefaultModifier,
+  hasNamedExports,
+  isReexport,
+} from '../../utils/exports.js';
+import { isBareModuleSpecifier } from '../../utils/index.js';
+
+/**
+ * EXPORTS
+ * 
+ * Analyzes a modules exports and adds them to the moduleDoc
+ */
+export function exportsPlugin() {
+  return {
+    name: 'CORE - EXPORTS',
+    analyzePhase({ts, node, moduleDoc}){
+      if(hasIgnoreJSDoc(node)) return;
+
+      /**
+       * @example export const foo = '';
+       */
+      if(hasExportModifier(node) && ts.isVariableStatement(node)) {
+        node?.declarationList?.declarations?.forEach(declaration => {
+          const _export = {          
+            kind: 'js',
+            name: declaration.name.getText(),
+            declaration: {
+              name: declaration.name.getText(),
+              module: moduleDoc.path,
+            },
+          };
+
+          moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+        });
+      }
+
+      /**
+       * @example export default var1;
+       */
+      if (node.kind === ts.SyntaxKind.ExportAssignment) {
+        const _export = {
+          kind: 'js',
+          name: 'default',
+          declaration: {
+            name: node.expression.text,
+            module: moduleDoc.path,
+          },
+        };
+        moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+      }
+
+      if (node.kind === ts.SyntaxKind.ExportDeclaration) {
+
+        /**
+         * @example export { var1, var2 };
+         */
+        if (hasNamedExports(node) && !isReexport(node)) {
+          node.exportClause?.elements?.forEach((element) => {
+            if (hasIgnoreJSDoc(element) || hasIgnoreJSDoc(getDeclarationInFile(element, node.getSourceFile())))
+              return;
+
+            const _export = {
+              kind: 'js',
+              name: element.name.getText(),
+              declaration: {
+                name: element.propertyName?.getText() || element.name.getText(),
+                module: moduleDoc.path,
+              },
+            };
+
+            moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+          });
+        }
+
+        /**
+         * @example export * from 'foo';
+         * @example export * from './my-module.js';
+         */
+        if (isReexport(node) && !hasNamedExports(node)) {
+          const _export = {
+            kind: 'js',
+            name: '*',
+            declaration: {
+              name: '*',
+              package: node.moduleSpecifier.getText().replace(/'/g, ''),
+            },
+          };
+          moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+        }
+
+        /**
+         * @example export { var1, var2 } from 'foo';
+         * @example export { var1, var2 } from './my-module.js';
+         */
+        if (isReexport(node) && hasNamedExports(node)) {
+          node.exportClause?.elements?.forEach((element) => {
+            const _export = {
+              kind: 'js',
+              name: element.name.getText(),
+              declaration: {
+                name: element.propertyName?.getText() || element.name.getText(),
+              },
+            };
+
+            if (isBareModuleSpecifier(node.moduleSpecifier.getText())) {
+              _export.declaration.package = node.moduleSpecifier.getText().replace(/'/g, '');
+            } else {
+              _export.declaration.module = node.moduleSpecifier.getText().replace(/'/g, '');
+            }
+
+            moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+          });
+        }
+      }
+
+      /**
+       * @example export function foo() {}
+       */
+      if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
+        if (hasExportModifier(node)) {
+          const isDefault = hasDefaultModifier(node);
+          const _export = {
+            kind: 'js',
+            name: isDefault ? 'default' : node.name?.getText() || '',
+            declaration: {
+              name: node.name?.getText() || '',
+              module: moduleDoc.path,
+            },
+          };
+
+          moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+        }
+      }
+
+      /**
+       * @example export class Class1 {}
+       */
+      if (node.kind === ts.SyntaxKind.ClassDeclaration) {
+        if (hasExportModifier(node)) {
+          const isDefault = hasDefaultModifier(node);
+          const _export = {
+            kind: 'js',
+            name: isDefault ? 'default' : node?.name?.text || '',
+            declaration: {
+              name: node?.name?.text || '',
+              module: moduleDoc.path,
+            },
+          };
+          moduleDoc.exports = [...(moduleDoc.exports || []), _export];
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,24 @@
+import { createFunctionLike } from './creators/createFunctionLike.js';
+import { isMixin } from '../../utils/mixins.js';
+
+/**
+ * functionLikePlugin
+ * 
+ * handles functionLikes such as class methods and functions
+ * does NOT handle arrow functions
+ */
+export function functionLikePlugin() {
+  return {
+    name: 'CORE - FUNCTION-LIKE',
+    analyzePhase({ts, node, moduleDoc}){
+      switch(node.kind) {
+        case ts.SyntaxKind.FunctionDeclaration:
+          if(!isMixin(node)) {
+            const functionLike = createFunctionLike(node);
+            moduleDoc.declarations.push(functionLike);
+          }
+          break;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+import { extractMixinNodes, isMixin } from '../../utils/mixins.js';
+import { createMixin } from './creators/createMixin.js';
+
+/**
+ * mixinPlugin
+ * 
+ * handles mixins
+ */
+export function mixinPlugin() {
+  return {
+    name: 'CORE - MIXINS',
+    analyzePhase({ts, node, moduleDoc, context}){
+      switch(node.kind) {
+        case ts.SyntaxKind.VariableStatement:
+        case ts.SyntaxKind.FunctionDeclaration:
+          /**
+           * Try to extract mixin nodes, if its a mixin
+           */
+          if(isMixin(node)) {
+            const { mixinFunction, mixinClass } = extractMixinNodes(node);
+            let mixin = createMixin(mixinFunction, mixinClass, moduleDoc, context);
+            moduleDoc.declarations.push(mixin);
+          }
+          break;
+      }
+    }
+  }
+}
+