@willieee802/zigbee-herdsman 0.49.4 → 0.50.0

package/scripts/zap-update-types.ts

@@ -1,707 +0,0 @@
-/**
- * Script: Generate enums and interfaces from ZCL XML data type definitions.
- *
- * Goals:
- *  - Parse XML cluster definition files (library.xml and its includes).
- *  - Respect XSD-described structure (type.xsd).
- *  - For <type:type> with <restriction><type:enumeration>, create a TS enum.
- *  - For <type:type> with <bitmap><element>, create a TS enum (for flags).
- *  - For <type:type> with <restriction><sequence>, create a TS interface.
- *  - Parse inline type definitions within attributes and command fields.
- *  - Write the generated code to a new file.
- *
- * Requirements:
- *   pnpm i xml2js @types/xml2js
- *
- * Usage:
- *    tsx scripts/zap-update-types.ts ../zap/zcl-builtin/dotdot
- */
-
-import {promises as fs} from "node:fs";
-import path from "node:path";
-import process from "node:process";
-import ts from "typescript";
-import {parseStringPromise} from "xml2js";
-import type {XMLAttr, XMLBitmapDefinition, XMLClusterSide, XMLEnumeration, XMLRestriction, XMLRoot, XMLSequence, XMLTypeType} from "./zap-xml-types";
-
-// #region Type Definitions
-
-interface ParsedXMLTypeType extends XMLTypeType {
-    clusterName?: string;
-}
-
-interface ParsedType {
-    name: string;
-    node: ts.EnumDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.VariableStatement;
-}
-
-// #endregion
-
-// #region Helpers
-
-const NUMBER_TO_WORD: Record<string, string> = {
-    "0": "Zero",
-    "1": "One",
-    "2": "Two",
-    "3": "Three",
-    "4": "Four",
-    "5": "Five",
-    "6": "Six",
-    "7": "Seven",
-    "8": "Eight",
-    "9": "Nine",
-};
-
-const NAME_OVERRIDES: Record<string, string> = {
-    CCColorOptions: "ColorControlColorOptions",
-    CCDirection: "ColorControlDirection",
-    CCMoveMode: "ColorControlMoveMode",
-    CCStepMode: "ColorControlStepMode",
-    CCColorLoopDirection: "ColorControlColorLoopDirection",
-};
-
-/**
- * Converts a string to PascalCase.
- * Handles various delimiters like spaces, hyphens, and underscores.
- * Sanitizes names that start with a number.
- * @param str The input string.
- * @returns The PascalCased string.
- */
-function pascalCase(str: string): string {
-    if (!str) {
-        return "";
-    }
-
-    let sanitized = str.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[^0-9a-zA-Z]/g, " ");
-    const firstChar = sanitized.charAt(0);
-
-    if (NUMBER_TO_WORD[firstChar]) {
-        sanitized = `${NUMBER_TO_WORD[firstChar]}${sanitized.slice(1)}`;
-    }
-
-    return sanitized
-        .trim()
-        .split(" ")
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-        .join("");
-}
-
-/** Only uppercase first char after sanitized */
-function simplePascalCase(str: string): string {
-    if (!str) {
-        return "";
-    }
-
-    const override = NAME_OVERRIDES[str];
-
-    if (override) {
-        return override;
-    }
-
-    const sanitized = str.replace(/[^0-9a-zA-Z]/g, "");
-
-    return `${sanitized.charAt(0).toUpperCase()}${sanitized.slice(1)}`;
-}
-
-/**
- * Converts a string to camelCase.
- * @param str The input string.
- * @returns The camelCased string.
- */
-function camelCase(str: string): string {
-    if (!str) {
-        return "";
-    }
-
-    const pascal = simplePascalCase(str);
-
-    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
-}
-
-/**
- * Converts a hex or decimal string to a 0x-prefixed hex string.
- * @param value The input string (e.g., "01", "ff", "255").
- * @param pad4 If true pad to 4-digit instead of 2.
- * @returns The formatted hex string (e.g., "0x01", "0xFF").
- */
-function toHex(value: string, pad4 = false): string {
-    if (!value) {
-        return "0x00";
-    }
-
-    const num = Number.parseInt(value, 16);
-
-    if (Number.isNaN(num)) {
-        return "0x00";
-    }
-
-    return `0x${num.toString(16).padStart(pad4 ? 4 : 2, "0")}`;
-}
-
-// #endregion
-
-// #region XML Parsing and Type Collection
-
-const createSyntheticType = (
-    clusterName: string,
-    name: string,
-    parent: XMLAttr<{type: string}> & {restriction?: XMLRestriction[]; bitmap?: XMLBitmapDefinition[]},
-): ParsedXMLTypeType | undefined => {
-    if (parent.restriction || parent.bitmap) {
-        return {
-            // biome-ignore lint/style/useNamingConvention: API
-            $: {id: "", name: name, short: name, inheritsFrom: parent.$.type},
-            clusterName: clusterName,
-            restriction: parent.restriction,
-            bitmap: parent.bitmap,
-        };
-    }
-
-    return undefined;
-};
-
-async function collectAllTypes(startFile: string): Promise<ParsedXMLTypeType[]> {
-    const allTypes: ParsedXMLTypeType[] = [];
-    const visitedFiles = new Set<string>();
-    const filesToProcess: string[] = [startFile];
-
-    const processSide = (clusterName: string, side: XMLClusterSide | undefined) => {
-        if (!side) {
-            return;
-        }
-
-        if (side.attributes) {
-            for (const attr of side.attributes[0].attribute) {
-                const synthetic = createSyntheticType(clusterName, attr.$.name, attr);
-
-                if (synthetic) {
-                    allTypes.push(synthetic);
-                }
-            }
-        }
-
-        if (side.commands) {
-            for (const cmd of side.commands[0].command) {
-                if (cmd.fields) {
-                    for (const field of cmd.fields[0].field) {
-                        const synthetic = createSyntheticType(clusterName, field.$.name, field);
-
-                        if (synthetic) {
-                            allTypes.push(synthetic);
-                        }
-                    }
-                }
-            }
-        }
-    };
-
-    while (filesToProcess.length > 0) {
-        const currentFile = filesToProcess.shift();
-
-        if (!currentFile || visitedFiles.has(currentFile)) {
-            continue;
-        }
-
-        visitedFiles.add(currentFile);
-
-        try {
-            const xmlContent = await fs.readFile(currentFile, "utf-8");
-            const parsed = (await parseStringPromise(xmlContent, {
-                explicitArray: true,
-                mergeAttrs: false,
-                explicitRoot: true,
-            })) as XMLRoot;
-            const libraries = parsed["zcl:library"];
-            const global = parsed["zcl:global"];
-            const clusters = parsed["zcl:cluster"];
-
-            if (libraries) {
-                for (const lib of Array.isArray(libraries) ? libraries : [libraries]) {
-                    if (lib["type:type"]) {
-                        allTypes.push(...lib["type:type"]);
-                    }
-
-                    if (lib["xi:include"]) {
-                        const baseDir = path.dirname(currentFile);
-
-                        for (const include of lib["xi:include"]) {
-                            if (include.$.href && include.$.parse === "xml") {
-                                filesToProcess.push(path.resolve(baseDir, include.$.href));
-                            }
-                        }
-                    }
-                }
-            }
-
-            if (global) {
-                for (const lib of Array.isArray(global) ? global : [global]) {
-                    if (lib["type:type"]) {
-                        allTypes.push(...lib["type:type"]);
-                    }
-                }
-            }
-
-            if (clusters) {
-                for (const cluster of Array.isArray(clusters) ? clusters : [clusters]) {
-                    if (cluster["type:type"]) {
-                        for (const type of cluster["type:type"]) {
-                            allTypes.push({...type, clusterName: cluster.$.name});
-                        }
-                    }
-
-                    if (cluster.server) {
-                        processSide(cluster.$.name, cluster.server[0]);
-                    }
-
-                    if (cluster.client) {
-                        processSide(cluster.$.name, cluster.client[0]);
-                    }
-                }
-            }
-        } catch (error) {
-            console.error(`Error processing file ${currentFile}:`, error);
-        }
-    }
-
-    return allTypes;
-}
-
-class TypeResolver {
-    #typesByShort = new Map<string, ParsedXMLTypeType>();
-
-    add(types: ParsedXMLTypeType[]): void {
-        for (const type of types) {
-            const short = type.$.short.toLowerCase();
-
-            if (!this.#typesByShort.has(short)) {
-                this.#typesByShort.set(short, type);
-            }
-        }
-    }
-
-    resolve(short: string, factory: ts.NodeFactory): ts.TypeNode {
-        const type = this.#typesByShort.get(short.toLowerCase());
-
-        if (type?.$.inheritsFrom && !type.restriction?.some((r) => r["type:sequence"])) {
-            return this.resolve(type.$.inheritsFrom, factory);
-        }
-
-        switch (short.toLowerCase()) {
-            case "data8":
-            case "data16":
-            case "data24":
-            case "data32":
-            case "data40":
-            case "data48":
-            case "data56":
-            case "data64":
-            case "bool":
-            case "map8":
-            case "map16":
-            case "map24":
-            case "map32":
-            case "map40":
-            case "map48":
-            case "map56":
-            case "map64":
-            case "uint8":
-            case "uint16":
-            case "uint24":
-            case "uint32":
-            case "uint40":
-            case "uint48":
-            case "uint56":
-            case "uint64":
-            case "int8":
-            case "int16":
-            case "int24":
-            case "int32":
-            case "int40":
-            case "int48":
-            case "int56":
-            case "int64":
-            case "enum8":
-            case "enum16":
-            case "semi":
-            case "single":
-            case "double":
-            case "utc":
-            case "clusterid":
-            case "attribid":
-            case "bacoid":
-                return factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
-
-            case "octstr":
-            case "string":
-            case "octstr16":
-            case "string16":
-                return factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
-
-            case "array":
-            case "set":
-            case "bag":
-                return factory.createArrayTypeNode(factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword));
-
-            case "eui64":
-                return factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
-            case "key128":
-                return factory.createTypeReferenceNode("Buffer");
-
-            default:
-                if (type && type.$.short !== "unk") {
-                    return factory.createTypeReferenceNode(simplePascalCase(type.$.short));
-                }
-
-                return factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
-        }
-    }
-}
-
-// #endregion
-
-// #region AST Generation
-
-function addComments(_factory: ts.NodeFactory, node: ts.Node, type: ParsedXMLTypeType, noType = false): void {
-    const comments: string[] = [];
-
-    if (type.clusterName) {
-        comments.push(`@cluster ${type.clusterName}`);
-    }
-
-    if (type.$.inheritsFrom && !noType) {
-        comments.push(`@type ${type.$.inheritsFrom}`);
-    }
-
-    if (comments.length > 0) {
-        const commentText = `*\n * ${comments.join("\n * ")}\n `;
-
-        ts.addSyntheticLeadingComment(node, ts.SyntaxKind.MultiLineCommentTrivia, commentText, true);
-    }
-}
-
-function createEnumFromEnumeration(factory: ts.NodeFactory, type: ParsedXMLTypeType, enumerations: XMLEnumeration[]): ts.EnumDeclaration {
-    const memberNames = new Map<string, number>();
-    const members: ts.EnumMember[] = [];
-
-    for (const e of enumerations) {
-        let memberName = pascalCase(e.$.name);
-        const count = memberNames.get(memberName);
-
-        if (count !== undefined) {
-            memberNames.set(memberName, count + 1);
-
-            memberName = `${memberName}${count + 1}`;
-        } else {
-            memberNames.set(memberName, 1);
-        }
-
-        const memberValue = factory.createNumericLiteral(toHex(e.$.value, type.$.inheritsFrom?.endsWith("16")));
-
-        members.push(factory.createEnumMember(memberName, memberValue));
-    }
-
-    const enumDeclaration = factory.createEnumDeclaration(
-        [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-        simplePascalCase(type.$.short),
-        members,
-    );
-
-    addComments(factory, enumDeclaration, type);
-
-    return enumDeclaration;
-}
-
-function createEnumFromBitmap(factory: ts.NodeFactory, type: ParsedXMLTypeType, bitmap: XMLBitmapDefinition, shiftRight = false): ts.EnumDeclaration {
-    const memberNames = new Map<string, number>();
-    const members: ts.EnumMember[] = [];
-
-    for (const e of bitmap.element) {
-        if (shiftRight && !e.$.shiftRight) {
-            continue;
-        }
-
-        let memberName = pascalCase(e.$.name);
-        const count = memberNames.get(memberName);
-
-        if (count !== undefined) {
-            memberNames.set(memberName, count + 1);
-
-            memberName = `${memberName}${count + 1}`;
-        } else {
-            memberNames.set(memberName, 1);
-        }
-
-        const memberValue = factory.createNumericLiteral(
-            // biome-ignore lint/style/noNonNullAssertion: valid from top of loop
-            toHex(shiftRight ? e.$.shiftRight! : e.$.mask, !shiftRight && type.$.inheritsFrom?.endsWith("16")),
-        );
-
-        members.push(factory.createEnumMember(memberName, memberValue));
-    }
-
-    const enumDeclaration = factory.createEnumDeclaration(
-        [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-        simplePascalCase(
-            shiftRight
-                ? type.$.short.endsWith("ShiftRight")
-                    ? type.$.short
-                    : `${type.$.short.endsWith("Mask") ? type.$.short.slice(0, -4) : type.$.short}ShiftRight`
-                : type.$.short.endsWith("Mask")
-                  ? type.$.short
-                  : `${type.$.short}Mask`,
-        ),
-        members,
-    );
-
-    addComments(factory, enumDeclaration, type, shiftRight);
-
-    return enumDeclaration;
-}
-
-function createInterfaceFromSequence(
-    factory: ts.NodeFactory,
-    type: ParsedXMLTypeType,
-    sequence: XMLSequence,
-    resolver: TypeResolver,
-): ts.InterfaceDeclaration {
-    const memberNames = new Map<string, number>();
-    const members: ts.PropertySignature[] = [];
-
-    for (const f of sequence.field) {
-        let propertyName = camelCase(f.$.name);
-        const count = memberNames.get(propertyName);
-
-        if (count !== undefined) {
-            memberNames.set(propertyName, count + 1);
-
-            propertyName = `${propertyName}${count + 1}`;
-        } else {
-            memberNames.set(propertyName, 1);
-        }
-
-        const propertyType = resolver.resolve(f.$.type, factory);
-
-        members.push(
-            factory.createPropertySignature(
-                undefined,
-                propertyName,
-                f.$.presentIf ? factory.createToken(ts.SyntaxKind.QuestionToken) : undefined,
-                propertyType,
-            ),
-        );
-    }
-
-    const interfaceDeclaration = factory.createInterfaceDeclaration(
-        [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-        simplePascalCase(type.$.short),
-        undefined,
-        undefined,
-        members,
-    );
-
-    addComments(factory, interfaceDeclaration, type);
-
-    return interfaceDeclaration;
-}
-
-function createSafeNumericLiteral(value: string | number, bigInt: boolean, factory: ts.NodeFactory): ts.Expression {
-    if (bigInt) {
-        const num = BigInt(value);
-        const str = String(value);
-
-        return factory.createBigIntLiteral({base10Value: num < 0 ? str.slice(1) : str, negative: num < 0});
-    }
-
-    const num = Number(value);
-
-    if (num < 0) {
-        return factory.createPrefixUnaryExpression(ts.SyntaxKind.MinusToken, factory.createNumericLiteral(Math.abs(num)));
-    }
-
-    return factory.createNumericLiteral(num);
-}
-
-function createZclTypeInvalidConstants(
-    factory: ts.NodeFactory,
-    types: ParsedXMLTypeType[],
-): [byName: ts.VariableStatement, byType: ts.VariableStatement] | undefined {
-    const zclType = types.find((t) => t.$.short === "zclType");
-
-    if (!zclType?.restriction?.[0]?.["type:enumeration"]) {
-        return undefined;
-    }
-
-    const zclTypeEnumMap = new Map(zclType.restriction[0]["type:enumeration"].map((e) => [e.$.name, e.$.value]));
-    const byNameProperties: ts.PropertyAssignment[] = [];
-    const byTypeProperties: ts.PropertyAssignment[] = [];
-
-    for (const type of types) {
-        const invalidValue = type.restriction?.[0]?.["type:invalid"]?.[0]?.$?.value;
-        const typeId = zclTypeEnumMap.get(type.$.short);
-
-        if (invalidValue && typeId) {
-            const name = pascalCase(type.$.short);
-            const invalidValueLiteral = createSafeNumericLiteral(invalidValue, name.endsWith("56") || name.endsWith("64"), factory);
-
-            byNameProperties.push(factory.createPropertyAssignment(factory.createIdentifier(name), invalidValueLiteral));
-
-            const byTypeProp = factory.createPropertyAssignment(factory.createNumericLiteral(Number.parseInt(typeId, 16)), invalidValueLiteral);
-            const commentText = `* ${name} `;
-
-            ts.addSyntheticLeadingComment(byTypeProp, ts.SyntaxKind.MultiLineCommentTrivia, commentText, true);
-            byTypeProperties.push(byTypeProp);
-        }
-    }
-
-    const invalidVal = factory.createUnionTypeNode([
-        factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
-        factory.createKeywordTypeNode(ts.SyntaxKind.BigIntKeyword),
-    ]);
-    const byNameCommentText = "* ZCL non-values by type name (key of `ZclType`). ";
-    const byNameConst = factory.createVariableStatement(
-        [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-        factory.createVariableDeclarationList(
-            [
-                factory.createVariableDeclaration(
-                    "ZCL_TYPE_INVALID_BY_TYPE_NAME",
-                    undefined,
-                    factory.createTypeReferenceNode("Readonly", [
-                        factory.createTypeReferenceNode("Record", [factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword), invalidVal]),
-                    ]),
-                    factory.createObjectLiteralExpression(byNameProperties, true),
-                ),
-            ],
-            ts.NodeFlags.Const,
-        ),
-    );
-    const byTypeCommentText = "* ZCL non-values by type ID (value of `ZclType`). ";
-    const byTypeConst = factory.createVariableStatement(
-        [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-        factory.createVariableDeclarationList(
-            [
-                factory.createVariableDeclaration(
-                    "ZCL_TYPE_INVALID_BY_TYPE",
-                    undefined,
-                    factory.createTypeReferenceNode("Readonly", [
-                        factory.createTypeReferenceNode("Record", [factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), invalidVal]),
-                    ]),
-                    factory.createObjectLiteralExpression(byTypeProperties, true),
-                ),
-            ],
-            ts.NodeFlags.Const,
-        ),
-    );
-
-    ts.addSyntheticLeadingComment(byNameConst, ts.SyntaxKind.MultiLineCommentTrivia, byNameCommentText, true);
-    ts.addSyntheticLeadingComment(byTypeConst, ts.SyntaxKind.MultiLineCommentTrivia, byTypeCommentText, true);
-
-    return [byNameConst, byTypeConst];
-}
-
-function processTypes(factory: ts.NodeFactory, types: ParsedXMLTypeType[], resolver: TypeResolver): ParsedType[] {
-    const processed: ParsedType[] = [];
-    const processedNames = new Set<string>();
-
-    for (const type of types) {
-        const name = simplePascalCase(type.$.short);
-
-        if (processedNames.has(name)) {
-            continue;
-        }
-
-        const restriction = type.restriction?.[0];
-        const bitmap = type.bitmap?.[0];
-
-        if (restriction?.["type:enumeration"]) {
-            const createdNode = createEnumFromEnumeration(factory, type, restriction["type:enumeration"]);
-
-            if (createdNode.members.length > 0) {
-                processed.push({name, node: createdNode});
-                processedNames.add(name);
-            }
-        } else if (bitmap?.element) {
-            const createdNode = createEnumFromBitmap(factory, type, bitmap);
-
-            if (createdNode.members.length > 0) {
-                processed.push({name: `${name}Mask`, node: createdNode});
-                processedNames.add(name);
-            }
-
-            const createdNodeShiftRight = createEnumFromBitmap(factory, type, bitmap, true);
-
-            if (createdNodeShiftRight.members.length > 0) {
-                processed.push({name: `${name}ShiftRight`, node: createdNodeShiftRight});
-                processedNames.add(name);
-            }
-        } else if (restriction?.["type:sequence"]) {
-            const createdNode = createInterfaceFromSequence(factory, type, restriction["type:sequence"][0], resolver);
-
-            if (createdNode.members.length > 0) {
-                processed.push({name, node: createdNode});
-                processedNames.add(name);
-            }
-        }
-    }
-
-    const zclTypeInvalidConsts = createZclTypeInvalidConstants(factory, types);
-
-    if (zclTypeInvalidConsts) {
-        processed.push({name: "ZCL_TYPE_INVALID_BY_TYPE_NAME", node: zclTypeInvalidConsts[0]});
-        processed.push({name: "ZCL_TYPE_INVALID_BY_TYPE", node: zclTypeInvalidConsts[1]});
-    }
-
-    return processed;
-}
-
-// #endregion
-
-// #region Main
-
-async function main(): Promise<void> {
-    const args = process.argv.slice(2);
-
-    if (args.length !== 1) {
-        throw new Error("Usage: tsx scripts/zap-update-types.ts <path-to-xml-files>");
-    }
-
-    const xmlPath = args[0];
-    const libraryFile = path.join(xmlPath, "library.xml");
-    const outputFile = "src/zspec/zcl/definition/datatypes.ts";
-
-    console.log(`Starting type generation from ${libraryFile}...`);
-
-    const allTypes = await collectAllTypes(libraryFile);
-
-    if (allTypes.length === 0) {
-        console.log("No types found to process.");
-
-        return;
-    }
-
-    const resolver = new TypeResolver();
-
-    resolver.add(allTypes);
-
-    const factory = ts.factory;
-    const processedTypes = processTypes(factory, allTypes, resolver);
-    const nodesToPrint = processedTypes.map((p) => p.node);
-    const sourceFile = ts.createSourceFile(outputFile, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
-    const printer = ts.createPrinter({newLine: ts.NewLineKind.LineFeed, removeComments: false});
-    const content = nodesToPrint.map((node) => printer.printNode(ts.EmitHint.Unspecified, node, sourceFile)).join("\n\n");
-    const fileHeader = `/**
- * This file was automatically generated by scripts/zap-update-types.ts. Do NOT edit manually.
- *
- * ZCL data type definitions.
- */\n\n`;
-
-    await fs.writeFile(outputFile, `${fileHeader + content}\n`, "utf8");
-
-    console.log(`Successfully generated ${processedTypes.length} types to ${outputFile}.`);
-}
-
-main().catch((err) => {
-    console.error(err);
-    process.exit(1);
-});
-
-// #endregion