@ui5/webcomponents-tools 0.0.0-e818f286e → 0.0.0-ebd9a4db3

package/lib/cem/utils.mjs

@@ -0,0 +1,423 @@
+import fs from "fs";
+import path from "path";
+
+let documentationErrors = new Map();
+
+const packageRegex = /^((@([a-z0-9._-]+)\/)?([a-z0-9._-]+))/;
+
+const getDeprecatedStatus = (jsdocComment) => {
+    const deprecatedTag = findTag(jsdocComment, "deprecated");
+    return deprecatedTag?.name
+        ? deprecatedTag.description
+            ? `${deprecatedTag.name} ${deprecatedTag.description}`
+            : deprecatedTag.name
+        : deprecatedTag
+            ? true
+            : undefined;
+};
+
+const getExperimentalStatus = (jsdocComment) => {
+    const experimentalTag = findTag(jsdocComment, "experimental");
+    return experimentalTag?.name
+        ? experimentalTag.description
+            ? `${experimentalTag.name} ${experimentalTag.description}`
+            : experimentalTag.name
+        : experimentalTag
+            ? true
+            : undefined;
+};
+
+const toKebabCase = str => {
+    return str.replaceAll(/[A-Z]+(?![a-z])|[A-Z]/g, ($, ofs) => (ofs ? "-" : "") + $.toLowerCase())
+}
+
+const normalizeDescription = (description) => {
+    return typeof description === 'string' ? description.replaceAll(/^-\s+|^(\n)+|(\n)+$/g, "") : description;
+}
+
+const getTypeRefs = (ts, node, 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.ArrayType) {
+            return [type.elementType?.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(node.type) || node?.typeArguments?.map(n => extractTypeRefs(n)).flat(2);
+
+    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) => {
+    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 {
+            // my-package/test
+            // my-package
+            // @scope/my-package
+            // my.package
+            // _mypackage
+            // mypackage-
+            // scope/my-package/test
+            // @scope/my-package/test
+            const match = currentModuleSpecifier?.text.match(packageRegex);
+            let packageName;
+
+            if (match) {
+                packageName = match[1];
+            }
+
+            return packageName || undefined;
+        }
+    }
+};
+
+const findImportPath = (ts, sourceFile, typeName, 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 {
+            let packageName = currentModuleSpecifier?.text?.replace(packageRegex, "") || undefined;
+
+            if (packageName?.startsWith("/")) {
+                packageName = packageName.replace("/", "");
+            }
+
+            return packageName;
+        }
+    }
+};
+
+
+const isClass = text => {
+    return text.includes("@abstract") || text.includes("@class") || text.includes("@constructor");
+};
+
+const normalizeTagType = (type) => {
+    return type?.trim();
+}
+
+const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+
+const getReference = (ts, type, classNode, modulePath) => {
+    let sourceFile = classNode.parent;
+
+    while (sourceFile && sourceFile.kind !== ts.SyntaxKind.SourceFile) {
+        sourceFile = sourceFile.parent;
+    }
+
+    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);
+    const importPath = findImportPath(
+        ts,
+        sourceFile,
+        typeName,
+        modulePath
+    )?.replace(`${packageName}/`, "");
+
+    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", "native", "allowPreventDefault"],
+    eventParam: [...commonTags],
+    method: [...commonTags, "param", "returns", "override"],
+    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
+    enum: [...commonTags, "experimental",],
+    enumMember: [...commonTags, "experimental",],
+    interface: [...commonTags, "experimental",],
+};
+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?.modifiers || node?.decorators)?.find(
+        (decorator) =>
+            decorator?.expression?.expression?.text === decoratorName
+    );
+};
+
+const findAllDecorators = (node, decoratorName) => {
+    if (typeof decoratorName === "string") {
+        return (node?.modifiers || node?.decorators)?.filter(decorator => decorator?.expression?.expression?.text === decoratorName) || [];
+    }
+
+    if (Array.isArray(decoratorName)) {
+        return (node?.modifiers || node?.decorators)?.filter(decorator => {
+            if (decorator?.expression?.expression?.text) {
+                return decoratorName.includes(decorator.expression.expression.text);
+            }
+
+            return false;
+        }
+        ) || [];
+    }
+
+    return [];
+};
+
+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", "native", "allowPreventDefault", "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 "experimental":
+            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) {
+            logDocumentationError(moduleDoc.path, `Incorrect use of @${tag.tag}. Ensure it is part of ${fieldType} JSDoc tags.`)
+        }
+
+        return !!isValid;
+    });
+};
+
+const logDocumentationError = (modulePath, message) => {
+    let moduleErrors = documentationErrors.get(modulePath);
+
+    if (!moduleErrors) {
+        documentationErrors.set(modulePath, []);
+        moduleErrors = documentationErrors.get(modulePath);
+    }
+
+    moduleErrors.push(message);
+}
+
+const displayDocumentationErrors = () => {
+    let errorsCount = 0;
+    [...documentationErrors.keys()].forEach(modulePath => {
+        const moduleErrors = documentationErrors.get(modulePath);
+
+        console.log(`=== ERROR: ${moduleErrors.length > 1 ? `${moduleErrors.length} problems` : "Problem"} found in file: ${modulePath}:`)
+        moduleErrors.forEach(moduleError => {
+            errorsCount++;
+            console.log(`\t- ${moduleError}`)
+        })
+    })
+
+    if (errorsCount) {
+        throw new Error(`Found ${errorsCount} errors in the description of the public API.`);
+    }
+}
+
+const formatArrays = (typeText) => {
+    return typeText?.replaceAll(/(\S+)\[\]/g, "Array<$1>")
+}
+
+export {
+    getPrivacyStatus,
+    getSinceStatus,
+    getDeprecatedStatus,
+    getExperimentalStatus,
+    getType,
+    getReference,
+    validateJSDocComment,
+    findDecorator,
+    findAllDecorators,
+    hasTag,
+    findTag,
+    findAllTags,
+    getTypeRefs,
+    normalizeDescription,
+    formatArrays,
+    isClass,
+    normalizeTagType,
+    displayDocumentationErrors,
+    logDocumentationError,
+    toKebabCase
+};

package/lib/cem/validate.js

@@ -0,0 +1,67 @@
+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 devMode = process.env.UI5_CEM_MODE === "dev";
+
+inputDataInternal.modules.forEach(moduleDoc => {
+	moduleDoc.exports = moduleDoc.exports.
+		filter(e => moduleDoc.declarations.find(d => d.name === e.declaration.name && ["class", "function", "variable", "enum"].includes(d.kind)) || e.name === "default");
+})
+
+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 ajv = new Ajv({ allowUnionTypes: true, allError: true })
+let validate = ajv.compile(internalSchema)
+
+// Validate the JSON data against the schema
+if (devMode) {
+	if (validate(inputDataInternal)) {
+		console.log('Internal custom  element manifest is validated successfully');
+	} else {
+		console.log(validate.errors)
+		throw new Error(`Validation of internal custom elements manifest failed: ${validate.errors}`);
+	}
+}
+
+const inputDataExternal = clearProps(JSON.parse(JSON.stringify(inputDataInternal)));
+validate = ajv.compile(extenalSchema)
+
+// Validate the JSON data against the schema
+if (validate(inputDataExternal)) {
+	console.log('Custom element manifest is validated successfully');
+	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 if (devMode) {
+	throw new Error(`Validation of public custom elements manifest failed: ${validate.errors}`);
+}

package/lib/copy-list/index.js

@@ -3,7 +3,7 @@ const path = require("path");
 
 const fileList = process.argv[2];
 const dest = process.argv[3];
-const src = "../../node_modules/@openui5/sap.ui.core/src/";
+const src = "@openui5/sap.ui.core/src/";
 
 const generate = async () => {
 	const filesToCopy = (await fs.readFile(fileList)).toString();
@@ -15,7 +15,7 @@ const generate = async () => {
 	const trimFile = file => file.trim();
 
 	return filesToCopy.split("\n").map(trimFile).filter(shouldCopy).map(async moduleName => {
-		const srcPath = path.join(src, moduleName);
+		const srcPath = require.resolve(path.join(src, moduleName), {paths: [process.cwd()]});
 		const destPath = path.join(dest, moduleName);
 
 		await fs.mkdir(path.dirname(destPath), { recursive: true });

package/lib/create-icons/index.js

@@ -1,7 +1,7 @@
 const fs = require("fs").promises;
 const path = require("path");
 
-const collectionName = process.argv[2] || "SAP-icons";
+const collectionName = process.argv[2] || "SAP-icons-v4";
 const collectionVersion = process.argv[3];
 const srcFile = collectionVersion ? path.normalize(`src/${collectionVersion}/${collectionName}.json`) : path.normalize(`src/${collectionName}.json`);
 const destDir = collectionVersion ? path.normalize(`dist/${collectionVersion}/`) : path.normalize("dist/");
@@ -17,12 +17,12 @@ const packageName = "${packageName}";
 
 registerIcon(name, { pathData, ltr, collection, packageName });
 
-export default "${name}";
+export default "${collection}/${name}";
 export { pathData, ltr, accData };`;
 
 
-const iconAccTemplate = (name, pathData, ltr, accData, collection, packageName) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
-import { ${accData.key} } from "../generated/i18n/i18n-defaults.js";
+const iconAccTemplate = (name, pathData, ltr, accData, collection, packageName, versioned) => `import { registerIcon } from "@ui5/webcomponents-base/dist/asset-registries/Icons.js";
+import { ${accData.key} } from "${versioned ? "../" : "./"}generated/i18n/i18n-defaults.js";
 
 const name = "${name}";
 const pathData = "${pathData}";
@@ -33,19 +33,38 @@ const packageName = "${packageName}";
 
 registerIcon(name, { pathData, ltr, accData, collection, packageName });
 
-export default "${name}";
+export default "${collection}/${name}";
 export { pathData, ltr, accData };`;
 
 
 
-const collectionTemplate = (name) => `import { isThemeFamily } from "@ui5/webcomponents-base/dist/config/Theme.js";
-import {pathData as pathDataV5, ltr, accData} from "./v5/${name}.js";
-import {pathData as pathDataV4} from "./v4/${name}.js";
+const collectionTemplate = (name, versions, fullName) => `import { isLegacyThemeFamilyAsync } from "@ui5/webcomponents-base/dist/config/Theme.js";
+import { pathData as pathData${versions[0]}, ltr, accData } from "./${versions[0]}/${name}.js";
+import { pathData as pathData${versions[1]} } from "./${versions[1]}/${name}.js";
 
-const pathData = isThemeFamily("sap_horizon") ? pathDataV5 : pathDataV4;
+const getPathData = async() => {
+	return await isLegacyThemeFamilyAsync() ? pathDatav4 : pathDatav5;
+};
 
-export default "${name}";
-export { pathData, ltr, accData };`;
+export default "${fullName}";
+export { getPathData, ltr, accData };`;
+
+
+const typeDefinitionTemplate = (name, accData, collection) => `declare const pathData: string;
+declare const ltr: boolean;
+declare const accData: ${accData ? '{ key: string; defaultText: string; }' : null}
+declare const _default: "${collection}/${name}";
+
+export default _default;
+export { pathData, ltr, accData };`
+
+const collectionTypeDefinitionTemplate = (name, accData) => `declare const getPathData: () => Promise<string>;
+declare const ltr: boolean;
+declare const accData: ${accData ? '{ key: string; defaultText: string; }' : null}
+declare const _default: "${name}";
+
+export default _default;
+export { getPathData, ltr, accData };`
 
 
 const svgTemplate = (pathData) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
@@ -63,20 +82,46 @@ const createIcons = async (file) => {
 		const pathData = iconData.path;
 		const ltr = !!iconData.ltr;
 		const acc = iconData.acc;
+		const packageName =  json.packageName;
+		const collection =  json.collection;
+		const versioned = json.version;
 
-		const content = acc ? iconAccTemplate(name, pathData, ltr, acc, json.collection, json.packageName) : iconTemplate(name, pathData, ltr, json.collection, json.packageName);
+		const content = acc ? iconAccTemplate(name, pathData, ltr, acc, collection, packageName, versioned) : iconTemplate(name, pathData, ltr, collection, packageName);
 
 		promises.push(fs.writeFile(path.join(destDir, `${name}.js`), content));
 		promises.push(fs.writeFile(path.join(destDir, `${name}.svg`), svgTemplate(pathData)));
-
-		if (json.version) {
-			promises.push(fs.writeFile(path.join(path.normalize("dist/"), `${name}.js`), collectionTemplate(name)));
+		promises.push(fs.writeFile(path.join(destDir, `${name}.d.ts`), typeDefinitionTemplate(name, acc, collection)));
+
+		// For versioned icons collections, the script creates top level (unversioned) module that internally imports the versioned ones.
+		// For example, the top level "@ui5/ui5-webcomponents-icons/dist/accept.js" imports:
+		// - "@ui5/ui5-webcomponents-icons/dist/v5/accept.js"
+		// - "@ui5/ui5-webcomponents-icons/dist/v4/accept.js"
+
+		if (versioned) {
+			// The exported value from the top level (unversioned) icon module depends on whether the collection is the default,
+			// to add or not the collection name to the exported value:
+			// For the default collection (SAPIcons) we export just the icon name - "export default { 'accept' }"
+			// For non-default collections (SAPTNTIcons and SAPBSIcons) we export the full name - "export default { 'tnt/actor' }"
+			const effectiveName = isDefaultCollection(collection) ? name : getUnversionedFullIconName(name, collection);
+			promises.push(fs.writeFile(path.join(path.normalize("dist/"), `${name}.js`), collectionTemplate(name, json.versions, effectiveName)));
+            promises.push(fs.writeFile(path.join(path.normalize("dist/"), `${name}.d.ts`), collectionTypeDefinitionTemplate(effectiveName, acc)));
 		}
 	}
 
 	return Promise.all(promises);
 };
 
+const isDefaultCollection = collectionName => collectionName === "SAP-icons-v4"  || collectionName === "SAP-icons-v5";
+const getUnversionedFullIconName = (name, collection) => `${getUnversionedCollectionName(collection)}/${name}`;
+const getUnversionedCollectionName = collectionName => CollectionVersionedToUnversionedMap[collectionName] || collectionName;
+
+const CollectionVersionedToUnversionedMap = {
+	"tnt-v2": "tnt",
+	"tnt-v3": "tnt",
+	"business-suite-v1": "business-suite",
+	"business-suite-v2": "business-suite",
+};
+
 createIcons(srcFile).then(() => {
 	console.log("Icons created.");
 });