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

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

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