Add apiMaturity for attributes (#1169)

andy31415 · web-flow · commit 1642f1be2892 · 2023-10-23T12:50:24.000-04:00
diff --git a/docs/make-schema-diagram b/docs/make-schema-diagram
@@ -10,7 +10,11 @@
 # It also has only ever been tested on Linux.
 #
 
-SC_HOME=~/schemacrawler/latest
+# You can set env variables such as:
+#   SC_HOME=/opt/schemacrawler
+if [ -z "$SC_HOME" ]; then
+  SC_HOME=~/schemacrawler/latest
+fi
 SC_BIN=${SC_HOME}/_schemacrawler/bin/schemacrawler.sh
 
 SQLITE=~/.zap/self-check.sqlite
diff --git a/docs/zap-schema.svg b/docs/zap-schema.svg
diff --git a/src-electron/db/db-mapping.js b/src-electron/db/db-mapping.js
@@ -124,6 +124,7 @@ exports.map = {
       entryType: x.ARRAY_TYPE,
       isArray: x.ARRAY_TYPE ? 1 : 0,
       mustUseTimedWrite: dbApi.fromDbBool(x.MUST_USE_TIMED_WRITE),
+      apiMaturity: x.API_MATURITY,
     }
   },
 
@@ -519,6 +520,7 @@ exports.map = {
       minInterval: x.MIN_INTERVAL,
       maxInterval: x.MAX_INTERVAL,
       reportableChange: x.REPORTABLE_CHANGE,
+      apiMaturity: x.API_MATURITY,
     }
   },
 
@@ -580,6 +582,7 @@ exports.map = {
       storageOption: x.STORAGE_OPTION,
       tokenId: x.TOKEN_ID, // Endpoint type attribute's token id
       type: x.TYPE != 'array' ? x.TYPE : x.ARRAY_TYPE, // Attribute type
+      apiMaturity: x.API_MATURITY,
     }
   },
 
diff --git a/src-electron/db/query-attribute.js b/src-electron/db/query-attribute.js
@@ -54,7 +54,8 @@ async function selectEndpointTypeAttributesByEndpointTypeRefAndClusterRef(
       INCLUDED_REPORTABLE,
       MIN_INTERVAL,
       MAX_INTERVAL,
-      REPORTABLE_CHANGE
+      REPORTABLE_CHANGE,
+      API_MATURITY
     from 
       ENDPOINT_TYPE_ATTRIBUTE
     where
@@ -197,7 +198,8 @@ async function selectAllAttributeDetailsFromEnabledClusters(
      ENDPOINT_TYPE_ATTRIBUTE.DEFAULT_VALUE,
      ENDPOINT_TYPE_ATTRIBUTE.MIN_INTERVAL,
      ENDPOINT_TYPE_ATTRIBUTE.MAX_INTERVAL,
-     ENDPOINT_TYPE_ATTRIBUTE.REPORTABLE_CHANGE
+     ENDPOINT_TYPE_ATTRIBUTE.REPORTABLE_CHANGE,
+     ATTRIBUTE.API_MATURITY
   FROM ATTRIBUTE
   INNER JOIN ENDPOINT_TYPE_ATTRIBUTE
   ON ATTRIBUTE.ATTRIBUTE_ID = ENDPOINT_TYPE_ATTRIBUTE.ATTRIBUTE_REF
@@ -254,7 +256,8 @@ async function selectAttributeDetailsFromAllEndpointTypesAndClustersUtil(
     ATTRIBUTE.MANUFACTURER_CODE,
     ENDPOINT_TYPE_CLUSTER.SIDE,
     CLUSTER.NAME AS CLUSTER_NAME,
-    ENDPOINT_TYPE_CLUSTER.ENABLED
+    ENDPOINT_TYPE_CLUSTER.ENABLED,
+    ATTRIBUTE.API_MATURITY
   FROM
     ATTRIBUTE
   INNER JOIN
@@ -857,7 +860,8 @@ SELECT
   A.IS_NULLABLE,
   A.IS_SCENE_REQUIRED,
   A.ARRAY_TYPE,
-  A.MUST_USE_TIMED_WRITE
+  A.MUST_USE_TIMED_WRITE,
+  A.API_MATURITY
 FROM ATTRIBUTE AS A
 INNER JOIN CLUSTER AS C
 ON C.CLUSTER_ID = A.CLUSTER_REF
@@ -913,7 +917,8 @@ SELECT
   A.IS_NULLABLE,
   A.IS_SCENE_REQUIRED,
   A.ARRAY_TYPE,
-  A.MUST_USE_TIMED_WRITE
+  A.MUST_USE_TIMED_WRITE,
+  A.API_MATURITY
 FROM ATTRIBUTE AS A
 WHERE A.PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
   AND A.CODE = ?
@@ -1005,7 +1010,8 @@ async function selectTokenAttributesForEndpoint(
     CLUSTER.NAME AS CLUSTER_NAME,
     CLUSTER.DEFINE AS CLUSTER_DEFINE,
     ENDPOINT_TYPE_ATTRIBUTE.SINGLETON,
-    ENDPOINT_TYPE_ATTRIBUTE.STORAGE_OPTION
+    ENDPOINT_TYPE_ATTRIBUTE.STORAGE_OPTION,
+    ATTRIBUTE.API_MATURITY
   FROM
     ATTRIBUTE
   INNER JOIN
diff --git a/src-electron/db/query-endpoint.js b/src-electron/db/query-endpoint.js
@@ -135,6 +135,7 @@ SELECT
   A.IS_SCENE_REQUIRED,
   A.IS_OPTIONAL,
   A.DEFINE,
+  A.API_MATURITY,
   EA.STORAGE_OPTION,
   EA.SINGLETON,
   EA.BOUNDED,
@@ -192,6 +193,7 @@ ORDER BY A.MANUFACTURER_CODE, A.CODE
       maxInterval: row.MAX_INTERVAL,
       reportableChange: row.REPORTABLE_CHANGE,
       define: row.DEFINE,
+      apiMaturity: row.API_MATURITY,
     }
   })
 }
diff --git a/src-electron/db/query-impexp.js b/src-electron/db/query-impexp.js
@@ -566,7 +566,7 @@ async function exportAttributesFromEndpointTypeCluster(
   endpointClusterId
 ) {
   let mapFunction = (x) => {
-    return {
+    let result = {
       name: x.NAME,
       code: x.CODE,
       mfgCode: x.MANUFACTURER_CODE,
@@ -582,6 +582,11 @@ async function exportAttributesFromEndpointTypeCluster(
       maxInterval: x.MAX_INTERVAL,
       reportableChange: x.REPORTABLE_CHANGE,
     }
+    if (x.API_MATURITY) {
+      result.apiMaturity = x.API_MATURITY
+    }
+
+    return result
   }
   return dbApi
     .dbAll(
diff --git a/src-electron/db/query-loader.js b/src-electron/db/query-loader.js
@@ -159,11 +159,13 @@ INSERT INTO ATTRIBUTE (
   MUST_USE_TIMED_WRITE,
   MANUFACTURER_CODE,
   INTRODUCED_IN_REF,
-  REMOVED_IN_REF
+  REMOVED_IN_REF,
+  API_MATURITY
 ) VALUES (
   ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
   (SELECT SPEC_ID FROM SPEC WHERE CODE = ? AND PACKAGE_REF = ?),
-  (SELECT SPEC_ID FROM SPEC WHERE CODE = ? AND PACKAGE_REF = ?)
+  (SELECT SPEC_ID FROM SPEC WHERE CODE = ? AND PACKAGE_REF = ?),
+  ?
 )`
 
 const SELECT_CLUSTER_SPECIFIC_DATA_TYPE = `
@@ -224,6 +226,7 @@ function attributeMap(clusterId, packageId, attributes) {
     packageId,
     attribute.removedIn,
     packageId,
+    attribute.apiMaturity,
   ])
 }
 
diff --git a/src-electron/db/query-zcl.js b/src-electron/db/query-zcl.js
@@ -670,7 +670,8 @@ SELECT
   IS_NULLABLE,
   IS_SCENE_REQUIRED,
   ARRAY_TYPE,
-  MUST_USE_TIMED_WRITE
+  MUST_USE_TIMED_WRITE,
+  API_MATURITY
 FROM ATTRIBUTE
 WHERE (CLUSTER_REF = ? OR CLUSTER_REF IS NULL)
   AND PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
@@ -715,7 +716,8 @@ SELECT
   IS_NULLABLE,
   IS_SCENE_REQUIRED,
   ARRAY_TYPE,
-  MUST_USE_TIMED_WRITE
+  MUST_USE_TIMED_WRITE,
+  API_MATURITY
 FROM ATTRIBUTE
 WHERE
   SIDE = ?
@@ -779,7 +781,8 @@ SELECT
   A.IS_NULLABLE,
   A.IS_SCENE_REQUIRED,
   A.ARRAY_TYPE,
-  A.MUST_USE_TIMED_WRITE
+  A.MUST_USE_TIMED_WRITE,
+  A.API_MATURITY
 FROM
   ATTRIBUTE AS A,
   CLUSTER AS C
@@ -823,7 +826,8 @@ SELECT
   IS_NULLABLE,
   IS_SCENE_REQUIRED,
   ARRAY_TYPE,
-  MUST_USE_TIMED_WRITE
+  MUST_USE_TIMED_WRITE,
+  API_MATURITY
 FROM ATTRIBUTE
 WHERE ATTRIBUTE_ID = ?`,
       [id]
@@ -886,7 +890,8 @@ SELECT
   A.IS_NULLABLE,
   A.IS_SCENE_REQUIRED,
   A.ARRAY_TYPE,
-  A.MUST_USE_TIMED_WRITE
+  A.MUST_USE_TIMED_WRITE,
+  A.API_MATURITY
 FROM ATTRIBUTE AS A
 WHERE ATTRIBUTE_ID = ?`,
       [clusterRef, clusterRef, attributeId]
@@ -925,6 +930,7 @@ SELECT
   A.IS_SCENE_REQUIRED,
   A.ARRAY_TYPE,
   A.MUST_USE_TIMED_WRITE,
+  A.API_MATURITY,
   C.CODE AS CLUSTER_CODE
 FROM
   ATTRIBUTE AS A
@@ -978,7 +984,8 @@ SELECT
   IS_NULLABLE,
   IS_SCENE_REQUIRED,
   ARRAY_TYPE,
-  MUST_USE_TIMED_WRITE
+  MUST_USE_TIMED_WRITE,
+  API_MATURITY
 FROM ATTRIBUTE
    WHERE SIDE = ?
    AND PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
diff --git a/src-electron/db/zap-schema.sql b/src-electron/db/zap-schema.sql
@@ -279,6 +279,7 @@ CREATE TABLE IF NOT EXISTS "ATTRIBUTE" (
   "MUST_USE_TIMED_WRITE" integer,
   "INTRODUCED_IN_REF" integer,
   "REMOVED_IN_REF" integer,
+  "API_MATURITY" text,
   foreign key (INTRODUCED_IN_REF) references SPEC(SPEC_ID),
   foreign key (REMOVED_IN_REF) references SPEC(SPEC_ID),
   foreign key (CLUSTER_REF) references CLUSTER(CLUSTER_ID),
diff --git a/src-electron/zcl/zcl-loader-silabs.js b/src-electron/zcl/zcl-loader-silabs.js
@@ -598,6 +598,7 @@ function prepareCluster(cluster, context, isExtension = false) {
         isNullable: attribute.$.isNullable == 'true' ? true : false,
         entryType: attribute.$.entryType,
         mustUseTimedWrite: attribute.$.mustUseTimedWrite == 'true',
+        apiMaturity: attribute.$.apiMaturity,
       }
       att.access = extractAccessIntoArray(attribute)
       if (att.manufacturerCode == null) {
diff --git a/test/gen-matter-api-maturity.test.js b/test/gen-matter-api-maturity.test.js
@@ -96,6 +96,12 @@ test(
     // Expect that the maturity test cluster is tagged as internal
     expect(ept).toContain('client cluster ApiMaturityTest = 4386 (internal) {')
     expect(ept).toContain('server cluster ApiMaturityTest = 4386 (internal) {')
+
+    // attribute tagging
+    expect(ept).toContain('optional int8u attribute stableAttribute = 0;')
+    expect(ept).toContain(
+      'optional int8u attribute provisionalAttribute = 1 (provisional);'
+    )
   },
   testUtil.timeout.long()
 )
diff --git a/test/gen-meta.test.js b/test/gen-meta.test.js
@@ -71,21 +71,33 @@ test(
     const attributes = await queryZcl.selectAllAttributes(db, [
       zclContext.packageId,
     ])
-    expect(attributes.length).toBe(4)
-    expect(attributes[0].name).toBe('at1')
-    expect(attributes[1].name).toBe('at2')
+    expect(attributes.length).toBeGreaterThanOrEqual(4)
 
-    let access
-    access = await queryAccess.selectAttributeAccess(db, attributes[0].id)
-    expect(access.length).toBe(1)
-    expect(access[0].operation).toBe('write')
-    expect(access[0].role).toBe('manage')
-    expect(access[0].accessModifier).toBe('fabric-scoped')
-    access = await queryAccess.selectAttributeAccess(db, attributes[1].id)
-    expect(access.length).toBe(1)
-    expect(access[0].operation).toBeNull()
-    expect(access[0].role).toBeNull()
-    expect(access[0].accessModifier).toBe('fabric-sensitive')
+    // Expect attributes at1 and at2 to be found
+    let hasAt1 = false
+    let hasAt2 = false
+
+    for (const attr of attributes) {
+      if (attr.name == 'at1') {
+        hasAt1 = true
+
+        let access = await queryAccess.selectAttributeAccess(db, attr.id)
+        expect(access.length).toBe(1)
+        expect(access[0].operation).toBe('write')
+        expect(access[0].role).toBe('manage')
+        expect(access[0].accessModifier).toBe('fabric-scoped')
+      } else if (attr.name == 'at2') {
+        hasAt2 = true
+
+        let access = await queryAccess.selectAttributeAccess(db, attr.id)
+        expect(access.length).toBe(1)
+        expect(access[0].operation).toBeNull()
+        expect(access[0].role).toBeNull()
+        expect(access[0].accessModifier).toBe('fabric-sensitive')
+      }
+    }
+    expect(hasAt1).toBeTruthy()
+    expect(hasAt2).toBeTruthy()
 
     const structs = await queryZcl.selectAllStructsWithItemCount(db, [
       zclContext.packageId,
diff --git a/test/gen-template/matter-api-maturity/codegen_test.zapt b/test/gen-template/matter-api-maturity/codegen_test.zapt
@@ -7,7 +7,65 @@ Here are all clusters:
 cluster {{asUpperCamelCase name}} = {{code}}
   {{~#if apiMaturity}} ({{apiMaturity}}){{/if}} {{!~}}
 {
-   // TODO: add attributes, structures and any other things needed here
+  {{#zcl_enums}}
+  enum {{asUpperCamelCase name preserveAcronyms=true}} : ENUM{{multiply size 8}};
+
+  {{/zcl_enums}}
+  {{#zcl_bitmaps}}
+  bitmap {{asUpperCamelCase name preserveAcronyms=true}} : BITMAP{{multiply size 8}};
+
+  {{/zcl_bitmaps}}
+  {{#zcl_events}}
+  {{priority}} event {{asUpperCamelCase name preserveAcronyms=true}} = {{code}} {
+    {{#zcl_event_fields}}
+    {{#if isOptional~}}optional {{/if~}}
+    {{~#if isNullable~}}nullable {{/if~}}
+    {{~#if isFabricSensitive~}}fabric_sensitive {{/if~}}
+    {{type}} {{asLowerCamelCase name~}}
+    {{~#if isArray~}} [] {{~/if}} = {{fieldIdentifier}};
+    {{/zcl_event_fields}}
+  }
+
+  {{/zcl_events}}
+  {{#zcl_structs}}
+  struct {{name}} {
+    {{#zcl_struct_items}}
+    {{#if isOptional~}}optional {{/if~}}
+    {{~#if isNullable~}}nullable {{/if~}}
+    {{~#if isFabricSensitive~}}fabric_sensitive {{/if~}}
+    {{type}} {{asLowerCamelCase label~}}
+    {{~#if isArray~}} [] {{~/if}} = {{fieldIdentifier}};
+    {{/zcl_struct_items}}
+  }
+
+  {{/zcl_structs}}
+
+  {{#zcl_attributes_server}}
+      {{#unless isGlobalAttribute}}
+  {{! ensure indent ~}}
+      {{#if isOptional~}} optional {{/if~}}
+      {{~#unless isWritableAttribute~}} readonly {{/unless~}}
+      {{~#if isNullable~}} nullable {{/if~}} 
+      {{type}} attribute {{asLowerCamelCase name~}} {{~#if isArray~}} [] {{~/if}} = {{code~}}
+      {{~#if apiMaturity}} ({{apiMaturity}}) {{~/if~}};
+      {{/unless}}
+
+  {{/zcl_attributes_server}}
+
+  {{#zcl_commands}}
+  command {{asUpperCamelCase commandName}} = {{code}} {
+  {{#zcl_command_arguments}}
+    {{#if isOptional~}}optional {{/if~}}
+    {{~#if isNullable~}}nullable {{/if~}}
+    {{~#if isFabricSensitive~}}fabric_sensitive {{/if~}}
+    {{type}} {{asLowerCamelCase label~}}
+    {{~#if isArray~}} [] {{~/if}} = {{fieldIdentifier}};
+  {{/zcl_command_arguments}}
+  }
+
+  {{/zcl_commands}}
 }
 
 {{~/all_user_clusters}}
+
+
diff --git a/test/resource/meta/api_maturity.xml b/test/resource/meta/api_maturity.xml
@@ -30,6 +30,9 @@ limitations under the License.
        <item fieldId="0" name="Cluster" type="cluster_id" isNullable="true"/>
        <item fieldId="1" name="Endpoint" type="endpoint_no" isNullable="true"/>
     </struct>
+    <attribute side="server" code="0x0000" define="STABLE_ATTRIBUTE" type="INT8U" writable="true" optional="true">StableAttribute</attribute>
+    <attribute apiMaturity="provisional" side="server" code="0x0001" define="PROVISIONAL_ATTRIBUTE" type="INT8U" writable="true" optional="true">ProvisionalAttribute</attribute>
+    <attribute side="server" code="0x0000" define="STABLE_ATTRIBUTE" type="INT8U" writable="true" optional="true">StableAttribute</attribute>
 
     <command source="client" code="0x00" name="StableCommand" response="StableCommandResponse" optional="false" >
       <description>A Test command</description>
diff --git a/zcl-builtin/shared/schema/zcl.xsd b/zcl-builtin/shared/schema/zcl.xsd
@@ -479,6 +479,7 @@ This schema describes the format of the XML files, that describe the ZCL specifi
       <xs:attribute name="array" type="xs:boolean"/>
       <xs:attribute name="isNullable" type="xs:boolean"/>
       <xs:attribute name="mustUseTimedWrite" type="xs:boolean"/>
+      <xs:attribute name="apiMaturity" type="zclApiMaturity"/>
     </xs:complexType>
   </xs:element>
   <xs:element name="description">

Original file line number	Diff line number	Diff line change
`@@ -124,6 +124,7 @@ exports.map = {`
`124`	`124`	`entryType: x.ARRAY_TYPE,`
`125`	`125`	`isArray: x.ARRAY_TYPE ? 1 : 0,`
`126`	`126`	`mustUseTimedWrite: dbApi.fromDbBool(x.MUST_USE_TIMED_WRITE),`
	`127`	`+ apiMaturity: x.API_MATURITY,`
`127`	`128`	`}`
`128`	`129`	`},`
`129`	`130`
`@@ -519,6 +520,7 @@ exports.map = {`
`519`	`520`	`minInterval: x.MIN_INTERVAL,`
`520`	`521`	`maxInterval: x.MAX_INTERVAL,`
`521`	`522`	`reportableChange: x.REPORTABLE_CHANGE,`
	`523`	`+ apiMaturity: x.API_MATURITY,`
`522`	`524`	`}`
`523`	`525`	`},`
`524`	`526`
`@@ -580,6 +582,7 @@ exports.map = {`
`580`	`582`	`storageOption: x.STORAGE_OPTION,`
`581`	`583`	`tokenId: x.TOKEN_ID, // Endpoint type attribute's token id`
`582`	`584`	`type: x.TYPE != 'array' ? x.TYPE : x.ARRAY_TYPE, // Attribute type`
	`585`	`+ apiMaturity: x.API_MATURITY,`
`583`	`586`	`}`
`584`	`587`	`},`
`585`	`588`
Original file line number	Diff line number	Diff line change
`@@ -598,6 +598,7 @@ function prepareCluster(cluster, context, isExtension = false) {`
`598`	`598`	`isNullable: attribute.$.isNullable == 'true' ? true : false,`
`599`	`599`	`entryType: attribute.$.entryType,`
`600`	`600`	`mustUseTimedWrite: attribute.$.mustUseTimedWrite == 'true',`
	`601`	`+ apiMaturity: attribute.$.apiMaturity,`
`601`	`602`	`}`
`602`	`603`	`att.access = extractAccessIntoArray(attribute)`
`603`	`604`	`if (att.manufacturerCode == null) {`