@ui5/webcomponents-tools 1.21.2 → 1.22.0-rc.1

package/lib/cem/utils.mjs

@@ -0,0 +1,355 @@
+import fs from "fs";
+import path from "path";
+
+let JSDocErrors = [];
+
+const getDeprecatedStatus = (jsdocComment) => {
+    const deprecatedTag = findTag(jsdocComment, "deprecated");
+    return deprecatedTag?.name
+        ? deprecatedTag.description
+            ? `${deprecatedTag.name} ${deprecatedTag.description}`
+            : deprecatedTag.name
+        : deprecatedTag
+            ? true
+            : undefined;
+};
+
+const normalizeDescription = (description) => {
+	return typeof description === 'string' ? description.replaceAll(/^-\s+|^(\n)+|(\n)+$/g, ""): description;
+}
+
+const getTypeRefs = (ts, classNodeMember, member) => {
+    const extractTypeRefs = (type) => {
+        if (type?.kind === ts.SyntaxKind.TypeReference) {
+            return type.typeArguments?.length
+                ? type.typeArguments.map((typeRef) => typeRef.typeName?.text)
+                : [type.typeName?.text];
+        } else if (type?.kind === ts.SyntaxKind.UnionType) {
+            return type.types
+                .map((type) => extractTypeRefs(type))
+                .flat(1);
+        } else if (type?.kind === ts.SyntaxKind.TemplateLiteralType) {
+            if (member.type) {
+                member.type.text = member.type.text.replaceAll?.(/`|\${|}/g, "");
+            }
+
+            return type.templateSpans?.length
+                ? type.templateSpans.map((typeRef) => typeRef.type?.typeName?.text)
+                : [type.typeName?.text];
+        }
+    };
+
+    let typeRefs = extractTypeRefs(classNodeMember.type);
+
+    if (typeRefs) {
+        typeRefs = typeRefs.filter((e) => !!e);
+    }
+
+    return typeRefs?.length ? typeRefs : undefined;
+};
+
+const getSinceStatus = (jsdocComment) => {
+    const sinceTag = findTag(jsdocComment, "since");
+    return sinceTag
+        ? sinceTag.description
+            ? `${sinceTag.name} ${sinceTag.description}`
+            : sinceTag.name
+        : undefined;
+};
+
+const getPrivacyStatus = (jsdocComment) => {
+    const privacyTag = findTag(jsdocComment, ["public", "private", "protected"]);
+    return privacyTag?.tag || "private";
+};
+
+const findPackageName = (ts, sourceFile, typeName, packageJSON) => {
+    const localStatements = [
+        ts.SyntaxKind.EnumDeclaration,
+        ts.SyntaxKind.InterfaceDeclaration,
+        ts.SyntaxKind.ClassDeclaration,
+        ts.SyntaxKind.TypeAliasDeclaration,
+    ];
+
+    const isLocalDeclared = sourceFile.statements.some(
+        (statement) =>
+            localStatements.includes(statement.kind) && statement?.name?.text === typeName
+    );
+
+    if (isLocalDeclared) {
+        return packageJSON?.name;
+    } else {
+        const importStatements = sourceFile.statements?.filter(
+            (statement) => statement.kind === ts.SyntaxKind.ImportDeclaration
+        );
+        const currentModuleSpecifier = importStatements.find((statement) => {
+            if (statement.importClause?.name?.text === typeName) {
+                return true;
+            }
+
+            return statement.importClause?.namedBindings?.elements?.some(
+                (element) => element.name?.text === typeName
+            );
+        })?.moduleSpecifier;
+
+        if (currentModuleSpecifier?.text?.startsWith(".")) {
+            return packageJSON?.name;
+        } else {
+            return Object.keys(packageJSON?.dependencies || {}).find(
+                (dependency) =>
+                    currentModuleSpecifier?.text?.startsWith(`${dependency}/`)
+            );
+        }
+    }
+};
+
+const findImportPath = (ts, sourceFile, typeName, packageJSON, modulePath) => {
+    const localStatements = [
+        ts.SyntaxKind.EnumDeclaration,
+        ts.SyntaxKind.InterfaceDeclaration,
+        ts.SyntaxKind.ClassDeclaration,
+        ts.SyntaxKind.TypeAliasDeclaration,
+    ];
+
+    const isLocalDeclared = sourceFile.statements.some(
+        (statement) =>
+            localStatements.includes(statement.kind) && statement?.name?.text === typeName
+    );
+
+    if (isLocalDeclared) {
+        return (
+            modulePath?.replace("src", "dist")?.replace(".ts", ".js") || undefined
+        );
+    } else {
+        const importStatements = sourceFile.statements?.filter(
+            (statement) => statement.kind === ts.SyntaxKind.ImportDeclaration
+        );
+        const currentModuleSpecifier = importStatements.find((statement) => {
+            if (statement.importClause?.name?.text === typeName) {
+                return true;
+            }
+
+            return statement.importClause?.namedBindings?.elements?.some(
+                (element) => element.name?.text === typeName
+            );
+        })?.moduleSpecifier;
+
+        if (currentModuleSpecifier?.text?.startsWith(".")) {
+            return (
+                path.join(path.dirname(modulePath), currentModuleSpecifier.text)
+                    ?.replace("src", "dist")?.replace(".ts", ".js") || undefined
+            );
+        } else {
+            const packageName = Object.keys(packageJSON?.dependencies || {}).find(
+                (dependency) =>
+                    currentModuleSpecifier?.text?.startsWith(dependency)
+            );
+            return currentModuleSpecifier?.text
+                ?.replace(`${packageName}/`, "") || undefined;
+        }
+    }
+};
+
+
+const isClass = text => {
+	return text.includes("@abstract") || text.includes("@class") || text.includes("@constructor");
+};
+
+const normalizeTagType = (type) => {
+	return type?.trim();
+}
+
+const getReference = (ts, type, classNode, modulePath) => {
+    let sourceFile = classNode.parent;
+
+    while (sourceFile && sourceFile.kind !== ts.SyntaxKind.SourceFile) {
+        sourceFile = sourceFile.parent;
+    }
+
+    const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+
+    const typeName =
+        typeof type === "string"
+            ? normalizeTagType(type)
+            : type.class?.expression?.text ||
+            type.typeExpression?.type?.getText() ||
+            type.typeExpression?.type?.elementType?.typeName?.text;
+    const packageName = findPackageName(ts, sourceFile, typeName, packageJSON);
+    const importPath = findImportPath(
+        ts,
+        sourceFile,
+        typeName,
+        packageJSON,
+        modulePath
+    );
+
+    return packageName && {
+        name: typeName,
+        package: packageName,
+        module: importPath,
+    };
+};
+
+const getType = (type) => {
+    const typeName = typeof type === "string" ? normalizeTagType(type) : type?.type;
+
+    const multiple =
+        typeName?.endsWith("[]") || typeName?.startsWith("Array<");
+    const name = multiple
+        ? typeName?.replace("[]", "")?.replace("Array<", "")?.replace(">", "")
+        : typeName;
+
+    return typeName ? { typeName: multiple ? `Array<${name}>` : typeName, name, multiple } : undefined;
+};
+
+const commonTags = ["public", "protected", "private", "since", "deprecated"];
+
+const allowedTags = {
+    field: [...commonTags, "formEvents", "formProperty", "default"],
+    slot: [...commonTags, "default"],
+    event: [...commonTags, "param", "allowPreventDefault", "native"],
+    eventParam: [...commonTags],
+    method: [...commonTags, "param", "returns", "override"],
+    class: [...commonTags, "constructor", "class", "abstract", "implements", "extends", "slot", "csspart"],
+    enum: [...commonTags],
+    enumMember: [...commonTags],
+    interface: [...commonTags],
+};
+allowedTags.getter = [...allowedTags.field, "override"]
+
+const tagMatchCallback = (tag, tagName) => {
+    const currentTagName = tag.tag;
+
+    return typeof tagName === "string"
+        ? currentTagName === tagName
+        : tagName.includes(currentTagName);
+};
+
+const findDecorator = (node, decoratorName) => {
+    return node?.decorators?.find(
+        (decorator) =>
+            decorator?.expression?.expression?.text === decoratorName
+    );
+};
+
+const findAllDecorators = (node, decoratorName) => {
+    return (
+        node?.decorators?.filter(
+            (decorator) =>
+                decorator?.expression?.expression?.text === decoratorName
+        ) || []
+    );
+};
+
+const hasTag = (jsDoc, tagName) => {
+    if (!jsDoc) {
+        return;
+    }
+
+    return jsDoc?.tags?.some((tag) => tagMatchCallback(tag, tagName));
+};
+
+const findTag = (jsDoc, tagName) => {
+    if (!jsDoc) {
+        return;
+    }
+
+    return jsDoc?.tags?.find((tag) => tagMatchCallback(tag, tagName));
+};
+
+const findAllTags = (jsDoc, tagName) => {
+    if (!jsDoc) {
+        return [];
+    }
+
+    const foundTags = jsDoc?.tags?.filter((tag) => tagMatchCallback(tag, tagName));
+
+    return foundTags || [];
+};
+
+const validateJSDocTag = (tag) => {
+    const booleanTags = ["private", "protected", "public", "abstract", "allowPreventDefault", "native", "formProperty", "constructor", "override"];
+    let tagName = tag.tag;
+
+    if (booleanTags.includes(tag.tag)) {
+        tagName = "boolean";
+    }
+
+    switch (tagName) {
+        case "boolean":
+            return !tag.name && !tag.type && !tag.description;
+        case "deprecated":
+            return !tag.type;
+        case "extends":
+            return !tag.type && tag.name && !tag.description;
+        case "implements":
+            return tag.type && !tag.name && !tag.description;
+        case "slot":
+            return tag.type && tag.name && tag.description;
+        case "csspart":
+            return !tag.type && tag.name && tag.description;
+        case "since":
+            return !tag.type && tag.name;
+        case "returns":
+            return !tag.type && tag.name;
+        case "default":
+            return !tag.type && !tag.description;
+        case "class":
+            return !tag.type;
+        case "param":
+            return !tag.type && tag.name;
+        case "eventparam":
+            return tag.type && tag.name;
+        case "formEvents":
+            return !tag.type && tag.name;
+        default:
+            return false;
+    }
+};
+
+const validateJSDocComment = (fieldType, jsdocComment, node, moduleDoc) => {
+    return !!jsdocComment?.tags?.every((tag) => {
+        let isValid = false
+
+        if (fieldType === "event" && tag?.tag === "param") {
+            isValid = allowedTags[fieldType]?.includes(tag.tag) && validateJSDocTag({...tag, tag: "eventparam"});
+        } else {
+            isValid = allowedTags[fieldType]?.includes(tag.tag) && validateJSDocTag(tag);
+        }
+
+        if (!isValid) {
+            JSDocErrors.push(
+                `=== ERROR: Problem found with ${node}'s JSDoc comment in ${moduleDoc.path}: \n\t- @${tag.tag} tag is being used wrong or it's not part of ${fieldType} JSDoc tags`
+            );
+        }
+
+        return !!isValid;
+    });
+};
+
+const getJSDocErrors = () => {
+    return JSDocErrors;
+};
+
+const formatArrays = (typeText) => {
+	return typeText.replaceAll(/(\S+)\[\]/g, "Array<$1>")
+}
+
+export {
+    getPrivacyStatus,
+    getSinceStatus,
+    getDeprecatedStatus,
+    getType,
+    getReference,
+    validateJSDocComment,
+    findDecorator,
+    findAllDecorators,
+    hasTag,
+    findTag,
+    findAllTags,
+    getJSDocErrors,
+    getTypeRefs,
+    normalizeDescription,
+    formatArrays,
+    isClass,
+    normalizeTagType
+};

package/lib/cem/validate.js

@@ -0,0 +1,63 @@
+const fs = require('fs');
+const Ajv = require('ajv');
+const path = require('path');
+
+// Load your JSON schema
+const extenalSchema = require('./schema.json');
+const internalSchema = require('./schema-internal.json');
+
+// Load your JSON data from the input file
+const inputFilePath = path.join(process.cwd(), "dist/custom-elements.json"); // Update with your file path
+const customManifest = fs.readFileSync(inputFilePath, 'utf8');
+const inputDataInternal = JSON.parse(customManifest);
+
+const clearProps = (data) => {
+    if (Array.isArray(data)) {
+        for (let i = 0; i < data.length; i++) {
+            if (typeof data[i] === "object") {
+                if (["enum", "interface"].includes(data[i].kind)) {
+                    data.splice(i, 1);
+                    i--;
+                } else {
+                    clearProps(data[i]);
+                }
+            }
+        }
+    } else if (typeof data === "object") {
+        Object.keys(data).forEach(prop => {
+            if (prop.startsWith("_ui5")) {
+                delete data[prop];
+            } else if (typeof data[prop] === "object") {
+                clearProps(data[prop]);
+            }
+        });
+    }
+
+    return data;
+}
+
+const inputDataExternal = clearProps(JSON.parse(JSON.stringify(inputDataInternal)));
+
+const ajv = new Ajv({ allowUnionTypes: true, allError: true })
+
+let validate = ajv.compile(internalSchema)
+
+// Validate the JSON data against the schema
+if (validate(inputDataInternal)) {
+    console.log('Validation internal custom-elements successful');
+} else {
+    console.error('Validation of internal custom-elements failed');
+    // console.error('Validation of internal custom-elements failed:', validate.errors);
+}
+
+validate = ajv.compile(extenalSchema)
+
+// Validate the JSON data against the schema
+if (validate(inputDataExternal)) {
+    console.log('Validation external custom-elements successful');
+    fs.writeFileSync(inputFilePath, JSON.stringify(inputDataExternal, null, 2), 'utf8');
+    fs.writeFileSync(inputFilePath.replace("custom-elements", "custom-elements-internal"), JSON.stringify(inputDataInternal, null, 2), 'utf8');
+} else {
+    console.error('Validation of external custom-elements failed:');
+    // console.error('Validation of external custom-elements failed:', ajv.errorsText(validate.errors));
+}

package/lib/create-illustrations/index.js

@@ -59,7 +59,7 @@ const generate = async () => {
 	const destPath = process.argv[6];
 	const collection = process.argv[7];
 	const fileNamePattern = new RegExp(`${illustrationsPrefix}-.+-(.+).svg`);
-// collect each illustration name because each one should have Sample.js file
+	// collect each illustration name because each one should have Sample.js file
 	const fileNames = new Set();
 
 	try {
@@ -75,7 +75,7 @@ const generate = async () => {
 		return `export default \`${svgContent}\`;`
 	};
 	const svgToJs = async fileName => {
-		const svg = await fs.readFile(path.join(srcPath, fileName), {encoding: "utf-8"});
+		const svg = await fs.readFile(path.join(srcPath, fileName), { encoding: "utf-8" });
 		const fileContent = svgImportTemplate(svg);
 		fileName = fileName.replace(/\.svg$/, ".js");
 
@@ -94,58 +94,47 @@ const generate = async () => {
 
 		const illustrationNameUpperCase = illustrationNameForTranslation.toUpperCase();
 
-		return defaultText ? `import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
+		return `import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
 import dialogSvg from "./${illustrationsPrefix}-Dialog-${illustrationName}.js";
 import sceneSvg from "./${illustrationsPrefix}-Scene-${illustrationName}.js";
-import spotSvg from "./${illustrationsPrefix}-Spot-${illustrationName}.js";
-import {
+import spotSvg from "./${illustrationsPrefix}-Spot-${illustrationName}.js";${
+	defaultText ? `import {
 	IM_TITLE_${illustrationNameUpperCase},
 	IM_SUBTITLE_${illustrationNameUpperCase},
-} from "../generated/i18n/i18n-defaults.js";
+} from "../generated/i18n/i18n-defaults.js";` : ``}
 
 const name = "${illustrationName}";
 const set = "${illustrationSet}";
-const collection = "${collection}";
+const collection = "${collection}";${defaultText ? `
 const title = IM_TITLE_${illustrationNameUpperCase};
-const subtitle = IM_SUBTITLE_${illustrationNameUpperCase};
+const subtitle = IM_SUBTITLE_${illustrationNameUpperCase};` : ``}
 
 registerIllustration(name, {
 	dialogSvg,
 	sceneSvg,
-	spotSvg,
+	spotSvg,${defaultText ? `
 	title,
-	subtitle,
+	subtitle,` : ``}
 	set,
 	collection,
 });
 
+export default "${illustrationSet === "fiori" ? "" : `${illustrationSet}/`}${illustrationName}";
 export {
 	dialogSvg,
 	sceneSvg,
 	spotSvg,
-};` :
-			`import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
-import dialogSvg from "./${illustrationsPrefix}-Dialog-${illustrationName}.js";
-import sceneSvg from "./${illustrationsPrefix}-Scene-${illustrationName}.js";
-import spotSvg from "./${illustrationsPrefix}-Spot-${illustrationName}.js";
-
-const name = "${illustrationName}";
-const set = "${illustrationSet}";
-const collection = "${collection}";
+};`
+	};
 
-registerIllustration(name, {
-	dialogSvg,
-	sceneSvg,
-	spotSvg,
-	set,
-	collection,
-});
+	const illustrationTypeDefinition = illustrationName => {
+		return `declare const dialogSvg: string;
+declare const sceneSvg: string;
+declare const spotSvg: string;
+declare const _default: "${illustrationSet === "fiori" ? "" : `${illustrationSet}/`}${illustrationName}";
 
-export {
-	dialogSvg,
-	sceneSvg,
-	spotSvg,
-};`
+export default _default;
+export { dialogSvg, sceneSvg, spotSvg };`
 	};
 
 	await fs.mkdir(destPath, { recursive: true });
@@ -165,6 +154,7 @@ export {
 
 	for (let illustrationName of fileNames) {
 		promises.push(fs.writeFile(path.join(destPath, `${illustrationName}.js`), illustrationImportTemplate(illustrationName)));
+		promises.push(fs.writeFile(path.join(destPath, `${illustrationName}.d.ts`), illustrationTypeDefinition(illustrationName)));
 	}
 
 	return Promise.all(promises);

package/lib/create-new-component/tsFileContentTemplate.js

@@ -25,10 +25,7 @@ import ${componentName}Css from "./generated/themes/${componentName}.css.js";
  * <code>import ${packageName}/dist/${componentName}.js";</code>
  *
  * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.${library}.${componentName}
- * @extends sap.ui.webc.base.UI5Element
- * @tagname ${tagName}
+ * @extends UI5Element
  * @public
  */
 @customElement({
@@ -43,7 +40,6 @@ import ${componentName}Css from "./generated/themes/${componentName}.css.js";
  * Example custom event.
  * Please keep in mind that all public events should be documented in the API Reference as shown below.
  *
- * @event sap.ui.webc.${library}.${componentName}#interact
  * @public
  */
 @event("interact", { detail: { /* event payload ( optional ) */ } })
@@ -51,9 +47,7 @@ class ${componentName} extends UI5Element {
 	/**
 	 * Defines the value of the component.
 	 *
-	 * @type {string}
-	 * @name sap.ui.webc.${library}.${componentName}.prototype.value
-	 * @defaultvalue ""
+	 * @default ""
 	 * @public
 	 */
 	@property()
@@ -62,9 +56,6 @@ class ${componentName} extends UI5Element {
 	/**
 	 * Defines the text of the component.
 	 *
-	 * @type {Node[]}
-	 * @name sap.ui.webc.${library}.${componentName}.prototype.default
-	 * @slot
 	 * @public
 	 */
 	@slot({ type: Node, "default": true })

package/lib/generate-js-imports/illustrations.js

@@ -21,12 +21,12 @@ const generateAvailableIllustrationsArray = (fileNames, exclusionPatterns = [])
   );
 };
 
-const generateDynamicImportsFileContent = (dynamicImports, availableIllustrations, collection, prefix = "") => {
+const generateDynamicImportsFileContent = (dynamicImports, availableIllustrations, collection, set, prefix = "") => {
   return `// @ts-nocheck
   import { registerIllustrationLoader } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
 
 export const loadIllustration = async (illustrationName) => {
-  const collectionAndPrefix = "${collection}/${prefix}";
+  const collectionAndPrefix = "${set}/${collection}/${prefix}";
   const cleanIllustrationName = illustrationName.startsWith(collectionAndPrefix) ? illustrationName.replace(collectionAndPrefix, "") : illustrationName;
   switch (cleanIllustrationName) {
 ${dynamicImports}
@@ -41,7 +41,7 @@ const loadAndCheck = async (illustrationName) => {
 };
 
 ${availableIllustrations}.forEach((illustrationName) =>
-  registerIllustrationLoader(\`${collection}/${prefix}\${illustrationName}\`, loadAndCheck)
+  registerIllustrationLoader(\`${set}/${collection}/${prefix}\${illustrationName}\`, loadAndCheck)
 );
 `;
 };
@@ -52,7 +52,7 @@ const getMatchingFiles = async (folder, pattern) => {
 };
 
 const generateIllustrations = async (config) => {
-  const { inputFolder, outputFile, collection, location, prefix, filterOut } = config;
+  const { inputFolder, outputFile, collection, location, prefix, filterOut, set } = config;
 
   const normalizedInputFolder = path.normalize(inputFolder);
   const normalizedOutputFile = path.normalize(outputFile);
@@ -62,7 +62,7 @@ const generateIllustrations = async (config) => {
   const dynamicImports = await generateDynamicImportLines(illustrations, location, filterOut);
   const availableIllustrations = generateAvailableIllustrationsArray(illustrations, filterOut);
 
-  const contentDynamic = generateDynamicImportsFileContent(dynamicImports, availableIllustrations, collection, prefix);
+  const contentDynamic = generateDynamicImportsFileContent(dynamicImports, availableIllustrations, collection, set, prefix);
 
   await fs.mkdir(path.dirname(normalizedOutputFile), { recursive: true });
   await fs.writeFile(normalizedOutputFile, contentDynamic);
@@ -74,10 +74,10 @@ const generateIllustrations = async (config) => {
 const config = {
   inputFolder: process.argv[2],
   outputFile: process.argv[3],
-  collection: process.argv[4],
-  location: process.argv[5],
-  prefix: process.argv[6],
-  filterOut: process.argv.slice(7),
+  set: process.argv[4],
+  collection: process.argv[5],
+  location: process.argv[6],
+  filterOut: process.argv.slice[7],
 };
 
 // Run the generation process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui5/webcomponents-tools",
-  "version": "1.21.2",
+  "version": "1.22.0-rc.1",
   "description": "UI5 Web Components: webcomponents.tools",
   "author": "SAP SE (https://www.sap.com)",
   "license": "Apache-2.0",
@@ -21,6 +21,7 @@
     "directory": "packages/tools"
   },
   "dependencies": {
+    "@custom-elements-manifest/analyzer": "^0.8.4",
     "@typescript-eslint/eslint-plugin": "^6.9.0",
     "@typescript-eslint/parser": "^6.9.0",
     "@wdio/cli": "^7.19.7",
@@ -29,11 +30,13 @@
     "@wdio/mocha-framework": "^7.19.7",
     "@wdio/spec-reporter": "^7.19.7",
     "@wdio/static-server-service": "^7.19.5",
+    "ajv": "^8.12.0",
     "chai": "^4.3.4",
     "child_process": "^1.0.2",
     "chokidar": "^3.5.1",
     "chokidar-cli": "^3.0.0",
     "command-line-args": "^5.1.1",
+    "comment-parser": "^1.4.0",
     "concurrently": "^6.0.0",
     "cross-env": "^7.0.3",
     "escodegen": "^2.0.0",
@@ -76,5 +79,5 @@
     "esbuild": "^0.19.9",
     "yargs": "^17.5.1"
   },
-  "gitHead": "1777f5289b1b23f96efd1389b6bb7ba0b3e1e580"
+  "gitHead": "1a4ba450e7d222535ddaf4f1d3b0ff91b020bb2a"
 }