Handling struct items properly when we have a global and cluster specific struct with the same name (#1557)

- Fixed the zcl_struct_items_by_struct_and_cluster_name helper for this global vs cluster specific struct items
- Added tests for it
- Github: ZAP#1551

Author: brdandu

docs/sdk-integration.md

@@ -82,7 +82,7 @@ The `templates` key contained in the `gen-templates.json` file above, is an arra
 
 The _replacement pattern_ inside the output key, comes handy when iterator key is used and defines how each generated file will be named. Replacement patterns are in a format of `{key}` or `{key:modifier}`. The `key` can be any usual key that the iterated object provides. For example, if you iterate over cluster, these can be `code`, `name`, `description`, `define` and all the usual keys that a cluster supports. So if your output contains `{code}` then this pattern will be replaced by the actual cluster code.
 
-The modifier can be one of the following: `hexuppercase`, `hexlowercase`, `tolowercase`, `touppercase`, `tocamelcase`, `tosnakecase` aor `tosnakecaseallcaps`.
+The modifier can be one of the following: `hexuppercase`, `hexlowercase`, `tolowercase`, `touppercase`, `tocamelcase`, `tosnakecase` or `tosnakecaseallcaps`.
 
 ## Templates key: options
 

src-electron/db/db-mapping.js

@@ -357,6 +357,7 @@ exports.map = {
       isFabricScoped: dbApi.fromDbBool(x.IS_FABRIC_SCOPED),
       caption: `Struct, named ${x.NAME}`,
       structClusterCount: x.STRUCT_CLUSTER_COUNT,
+      structCount: x.STRUCT_COUNT,
       clusterName: x.CLUSTER_NAME,
       apiMaturity: x.API_MATURITY
     }

src-electron/db/query-struct.js

@@ -95,6 +95,7 @@ WHERE
  * @returns Promise of Struct
  */
 async function selectStructByName(db, name, packageIds) {
+  //STRUCT_COUNT counts the structs where there could be one global and one cluster specific with same name.
   return dbApi
     .dbGet(
       db,
@@ -105,6 +106,7 @@ SELECT
   STRUCT.API_MATURITY,
   DATA_TYPE.NAME,
   (SELECT COUNT(1) FROM DATA_TYPE_CLUSTER WHERE DATA_TYPE_CLUSTER.DATA_TYPE_REF = STRUCT.STRUCT_ID) AS STRUCT_CLUSTER_COUNT,
+  (SELECT COUNT(1) FROM STRUCT INNER JOIN DATA_TYPE ON STRUCT.STRUCT_ID = DATA_TYPE.DATA_TYPE_ID WHERE DATA_TYPE.NAME = "${name}" AND PACKAGE_REF IN (${dbApi.toInClause(packageIds)})) AS STRUCT_COUNT,
   DATA_TYPE.DISCRIMINATOR_REF
 FROM
   STRUCT

src-electron/db/query-zcl.js

@@ -498,66 +498,73 @@ async function selectAllStructItemsByStructName(
   packageIds,
   clusterName = null
 ) {
-  let clusterJoinQuery = ''
-  let clusterWhereQuery = ''
+  let clusterCondition = clusterName
+    ? `CLUSTER.NAME = "${clusterName}"`
+    : `CLUSTER.NAME IS NULL`
+
+  let structItemQuery = `
+  SELECT
+    SI.FIELD_IDENTIFIER,
+    SI.NAME,
+    (SELECT DATA_TYPE.NAME FROM DATA_TYPE WHERE DATA_TYPE.DATA_TYPE_ID = SI.DATA_TYPE_REF) AS TYPE,
+    DT.NAME AS DATA_TYPE_REF_NAME,
+    DISCRIMINATOR.NAME AS DISCRIMINATOR_NAME,
+    SI.STRUCT_REF,
+    SI.IS_ARRAY,
+    SI.IS_ENUM,
+    SI.MIN_LENGTH,
+    SI.MAX_LENGTH,
+    SI.IS_WRITABLE,
+    SI.IS_NULLABLE,
+    SI.IS_OPTIONAL,
+    SI.IS_FABRIC_SENSITIVE,
+    SI.DATA_TYPE_REF
+  FROM
+    STRUCT_ITEM AS SI
+  INNER JOIN
+    STRUCT
+  ON
+    STRUCT.STRUCT_ID = SI.STRUCT_REF
+  INNER JOIN
+    DATA_TYPE AS DT
+  ON
+    DT.DATA_TYPE_ID = STRUCT.STRUCT_ID
+  LEFT JOIN
+    DATA_TYPE_CLUSTER
+  ON
+    DATA_TYPE_CLUSTER.DATA_TYPE_REF = DT.DATA_TYPE_ID
+  LEFT JOIN
+    CLUSTER
+  ON
+    DATA_TYPE_CLUSTER.CLUSTER_REF = CLUSTER.CLUSTER_ID
+  INNER JOIN
+    DISCRIMINATOR
+  ON
+    DT.DISCRIMINATOR_REF = DISCRIMINATOR.DISCRIMINATOR_ID
+  WHERE
+    DT.NAME = ?
+  AND
+    DT.PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
+  AND
+    ${clusterCondition}
+  ORDER BY FIELD_IDENTIFIER`
+
+  let rows = []
+  // Attempt to retrieve struct items with given cluster name
   if (clusterName) {
-    clusterJoinQuery = `
-    INNER JOIN
-      DATA_TYPE_CLUSTER
-    ON
-      DATA_TYPE_CLUSTER.DATA_TYPE_REF = DT.DATA_TYPE_ID
-    INNER JOIN
-      CLUSTER
-    ON
-      DATA_TYPE_CLUSTER.CLUSTER_REF = CLUSTER.CLUSTER_ID
-      `
-    clusterWhereQuery = `
-    AND
-      CLUSTER.NAME = "${clusterName}"
-      `
+    rows = await dbApi.dbAll(db, structItemQuery, [name])
   }
-  return dbApi
-    .dbAll(
-      db,
-      `
-SELECT
-  SI.FIELD_IDENTIFIER,
-  SI.NAME,
-  (SELECT DATA_TYPE.NAME FROM DATA_TYPE WHERE DATA_TYPE.DATA_TYPE_ID = SI.DATA_TYPE_REF) AS TYPE,
-  DT.NAME AS DATA_TYPE_REF_NAME,
-  DISCRIMINATOR.NAME AS DISCRIMINATOR_NAME,
-  SI.STRUCT_REF,
-  SI.IS_ARRAY,
-  SI.IS_ENUM,
-  SI.MIN_LENGTH,
-  SI.MAX_LENGTH,
-  SI.IS_WRITABLE,
-  SI.IS_NULLABLE,
-  SI.IS_OPTIONAL,
-  SI.IS_FABRIC_SENSITIVE,
-  SI.DATA_TYPE_REF
-FROM
-  STRUCT_ITEM AS SI
-INNER JOIN
-  STRUCT
-ON
-  STRUCT.STRUCT_ID = SI.STRUCT_REF
-INNER JOIN
-  DATA_TYPE AS DT
-ON
-  DT.DATA_TYPE_ID = STRUCT.STRUCT_ID
-${clusterJoinQuery}
-INNER JOIN
-  DISCRIMINATOR
-ON
-  DT.DISCRIMINATOR_REF = DISCRIMINATOR.DISCRIMINATOR_ID
-WHERE DT.NAME = ?
-  AND DT.PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
-  ${clusterWhereQuery}
-ORDER BY FIELD_IDENTIFIER`,
-      [name]
+
+  // If no rows were found then find a global struct by turning cluster name to null
+  if (rows.length === 0) {
+    structItemQuery = structItemQuery.replace(
+      clusterCondition,
+      `CLUSTER.NAME IS NULL`
     )
-    .then((rows) => rows.map(dbMapping.map.structItem))
+    rows = await dbApi.dbAll(db, structItemQuery, [name])
+  }
+
+  return rows.map(dbMapping.map.structItem)
 }
 
 /**

src-electron/generator/helper-zcl.js

@@ -348,7 +348,8 @@ async function zcl_struct_items_by_struct_and_cluster_name(
     name,
     packageIds
   )
-  if (structObj.structClusterCount == 0) {
+
+  if (structObj.structClusterCount == 0 && structObj.structCount == 1) {
     // Just ignore the cluster name.
     return zcl_struct_items_by_struct_name.call(this, name, options)
   }

test/gen-matter-3-1.test.js

@@ -477,9 +477,50 @@ test(
     expect(ept).toContain(
       'TargetStruct item 4 from Binding cluster: FabricIndex'
     )
-
     expect(ept).toContain('Struct with array: NestedStructList')
     expect(ept).toContain('Struct with array: DoubleNestedStructList')
+
+    // Mode Select SemanticTagStruct items not giving global SemanticTagStruct struct items
+    expect(ept).toContain(
+      'SemanticTagStruct item 0 from Mode Select cluster: MfgCode'
+    )
+    expect(ept).toContain(
+      'SemanticTagStruct item 1 from Mode Select cluster: Value'
+    )
+    expect(ept).not.toContain(
+      'SemanticTagStruct item 2 from Mode Select cluster'
+    )
+    expect(ept).not.toContain('SemanticTagStruct item 2 from Mode Select')
+
+    // global SemanticTagStruct struct items not giving Mode Select SemanticTagStruct items
+    // In this case Descriptor cluster is using the global struct
+    expect(ept).toContain(
+      'SemanticTagStruct item 0 from Descriptor cluster: MfgCode'
+    )
+    expect(ept).toContain(
+      'SemanticTagStruct item 1 from Descriptor cluster: NamespaceID'
+    )
+    expect(ept).toContain(
+      'SemanticTagStruct item 2 from Descriptor cluster: Tag'
+    )
+    expect(ept).toContain(
+      'SemanticTagStruct item 3 from Descriptor cluster: Label'
+    )
+    expect(ept).not.toContain(
+      'SemanticTagStruct item 4 from Descriptor cluster'
+    )
+    // Checking with Identify cluster too
+    expect(ept).toContain(
+      'SemanticTagStruct item 0 from Identify cluster: MfgCode'
+    )
+    expect(ept).toContain(
+      'SemanticTagStruct item 1 from Identify cluster: NamespaceID'
+    )
+    expect(ept).toContain('SemanticTagStruct item 2 from Identify cluster: Tag')
+    expect(ept).toContain(
+      'SemanticTagStruct item 3 from Identify cluster: Label'
+    )
+    expect(ept).not.toContain('SemanticTagStruct item 4 from Identify cluster')
   },
   testUtil.timeout.long()
 )
@@ -706,7 +747,7 @@ test(
         commandNames.push(commandName['NAME'])
       }
     }
-    console.log('BHarat test commands: ' + JSON.stringify(commandNames))
+
     // Verify specific commands from the extension
     expect(commandNames).toContain('ReviewFabricRestrictions')
 

test/gen-template/matter3/miscellaneous_helper_tests.zapt

@@ -30,6 +30,18 @@ TargetStruct item {{index}} from Access Control cluster: {{name}}
 TargetStruct item {{index}} from Binding cluster: {{name}}
 {{/zcl_struct_items_by_struct_and_cluster_name}}
 
+{{#zcl_struct_items_by_struct_and_cluster_name "SemanticTagStruct" "Mode Select"}}
+SemanticTagStruct item {{index}} from Mode Select cluster: {{name}}
+{{/zcl_struct_items_by_struct_and_cluster_name}}
+
+{{#zcl_struct_items_by_struct_and_cluster_name "SemanticTagStruct" "Descriptor"}}
+SemanticTagStruct item {{index}} from Descriptor cluster: {{name}}
+{{/zcl_struct_items_by_struct_and_cluster_name}}
+
+{{#zcl_struct_items_by_struct_and_cluster_name "SemanticTagStruct" "Identify"}}
+SemanticTagStruct item {{index}} from Identify cluster: {{name}}
+{{/zcl_struct_items_by_struct_and_cluster_name}}
+
 {{#zcl_structs}}
   {{#if struct_contains_array}} Struct with array: {{name}}
   {{/if}}