Add apiMaturity for attributes

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

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,
     }
   },
 

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

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,
     }
   })
 }

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(

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,
   ])
 }
 

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)})

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),

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) {

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()
 )

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,

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}}
+
+

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>

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">