Render provisionality for commands and other elements (#72332)

* Update jinja and add test

* Apply suggestion

* Support parsing comments for elements with prefixes like "provisional"

Author: AryaHassanli

scripts/py_matter_idl/matter/idl/generators/idl/MatterIdl.jinja

@@ -7,6 +7,7 @@
  optional ExtensionFieldSet extensionFieldSets[] = 5;
 #}
 
+{{- field.api_maturity | idltxt -}}
 {%- if field.qualities %}{{field.qualities | idltxt}} {% endif -%}
 {{field.data_type.name}}
 {%- if field.data_type.max_length -%} <{{field.data_type.max_length}}> {%- endif -%}
@@ -18,6 +19,7 @@
 {% macro render_struct(s) -%}{#
  Macro for the output of a complete struct
 #}
+{{- s.api_maturity | idltxt -}}
 {%- if s.is_shared%}shared {% endif -%}
 {%- if s.tag %}{{s.tag | idltxt}} {% endif -%}
 {% if s.qualities %}{{s.qualities | idltxt}} {% endif -%}
@@ -42,18 +44,18 @@ struct {{s.name}} {##}
 // This IDL was auto-generated from a parsed data structure
 
 {% for enum in idl.global_enums %}
-enum {{enum.name}} : {{ enum.base_type}} {
+{{enum.api_maturity | idltxt}}enum {{enum.name}} : {{ enum.base_type}} {
   {% for entry in enum.entries %}
-  {{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
+  {{entry.api_maturity | idltxt}}{{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
   {% endfor %}
 }
 
 {% endfor %}
 
 {%- for bitmap in idl.global_bitmaps %}
-bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
+{{bitmap.api_maturity | idltxt}}bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
   {% for entry in bitmap.entries %}
-  {{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
+  {{entry.api_maturity | idltxt}}{{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
   {% endfor %}
 }
 
@@ -72,9 +74,9 @@ bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
 
   {% for enum in cluster.enums | selectattr("is_global")%}
   /* GLOBAL:
-  enum {{enum.name}} : {{ enum.base_type}} {
+  {{enum.api_maturity | idltxt}}enum {{enum.name}} : {{ enum.base_type}} {
     {% for entry in enum.entries %}
-    {{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
+    {{entry.api_maturity | idltxt}}{{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
     {% endfor %}
   }
   */
@@ -83,9 +85,9 @@ bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
 
   {%- for bitmap in cluster.bitmaps | selectattr("is_global")%}
   /* GLOBAL:
-  bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
+  {{bitmap.api_maturity | idltxt}}bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
     {% for entry in bitmap.entries %}
-    {{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
+    {{entry.api_maturity | idltxt}}{{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
     {% endfor %}
   }
   */
@@ -100,20 +102,22 @@ bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
   {% endfor %}
 
   {%- for enum in cluster.enums | rejectattr("is_global")%}
-  {%+ if enum.is_shared%}shared {% endif -%}
+  {%+ if enum.api_maturity %}{{enum.api_maturity | idltxt}}{% endif -%}
+  {%- if enum.is_shared%}shared {% endif -%}
   enum {{enum.name}} : {{ enum.base_type}} {
     {% for entry in enum.entries %}
-    {{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
+    {{entry.api_maturity | idltxt}}{{entry.name}} = {{entry.code}} {{-specification_name_clarification(entry)}};
     {% endfor %}
   }
 
   {% endfor %}
 
   {%- for bitmap in cluster.bitmaps | rejectattr("is_global")%}
-  {%+ if bitmap.is_shared%}shared {% endif -%}
+  {%+ if bitmap.api_maturity %}{{bitmap.api_maturity | idltxt}}{% endif -%}
+  {%- if bitmap.is_shared%}shared {% endif -%}
   bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
     {% for entry in bitmap.entries %}
-    {{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
+    {{entry.api_maturity | idltxt}}{{entry.name}} = 0x{{"%X" | format(entry.code)}} {{-specification_name_clarification(entry)}};
     {% endfor %}
   }
 
@@ -152,7 +156,7 @@ bitmap {{bitmap.name}} : {{ bitmap.base_type}} {
   {% if c.description %}
   /** {{c.description}} */
   {% endif %}
-  {{c.qualities | idltxt}}command {{c | command_access}}{{c.name}}(
+  {{c.api_maturity | idltxt}}{{c.qualities | idltxt}}command {{c | command_access}}{{c.name}}(
      {%- if c.input_param %}{{c.input_param}}{% endif -%}
   ): {{c.output_param}} = {{c.code}};
   {% endfor %}

scripts/py_matter_idl/matter/idl/matter_idl_parser.py

@@ -50,7 +50,7 @@ def apply_to_idl(self, idl: Idl, content: str):
             return
 
         actual_pos = self.start_pos + self.value_len
-        while content[actual_pos] in ' \t\n\r':
+        while actual_pos < len(content) and content[actual_pos] in ' \t\n\r':
             actual_pos += 1
 
         # A doc comment will apply to any supported element assuming it immediately
@@ -505,10 +505,16 @@ def endpoint_server_cluster(self, meta, cluster_id, *content):
         return AddServerClusterToEndpointTransform(
             ServerClusterInstantiation(parse_meta=meta, name=cluster_id, attributes=attributes, events_emitted=events, commands=commands))
 
-    @v_args(inline=True)
-    def cluster_content(self, api_maturity, element):
+    @v_args(meta=True)
+    def cluster_content(self, meta, args):
+        api_maturity, element = args[0], args[1]
         if api_maturity is not None:
             element.api_maturity = api_maturity
+        if not self.skip_meta:
+            if isinstance(element, Attribute):
+                element.definition.parse_meta = ParseMetaData(meta)
+            elif hasattr(element, 'parse_meta'):
+                element.parse_meta = ParseMetaData(meta)
         return element
 
     @v_args(inline=True, meta=True)

scripts/py_matter_idl/matter/idl/test_idl_generator.py

@@ -134,6 +134,46 @@ def test_app_rendering(self):
             # checks that data types and content is the same
             self.assertEqual(idl, idl2)
 
+    def test_maturity_rendering(self):
+        idl_content = """
+            client cluster ProvisionalCluster = 1 {
+                provisional struct ProvisionalStruct {
+                    provisional int16u provisionalField = 1;
+                }
+
+                provisional enum ProvisionalEnum : ENUM16 {
+                    provisional kProvisionalValue = 0;
+                }
+
+                provisional bitmap ProvisionalBitmap : BITMAP32 {
+                    provisional kProvisionalBit = 0x1;
+                }
+
+                /** Test command description */
+                provisional command ProvisionalCommand(): DefaultSuccess = 0;
+            }
+        """
+        # Parse and render (skip_meta must be False for comment parsing to work)
+        parser = CreateParser(skip_meta=False, merge_globals=False)
+        idl = parser.parse(idl_content)
+        rendered = RenderAsIdlTxt(idl)
+
+        # Verify that maturity words are preserved in the rendered IDL
+        self.assertIn("provisional struct ProvisionalStruct", rendered)
+        self.assertIn("provisional int16u provisionalField = 1;", rendered)
+        self.assertIn("provisional enum ProvisionalEnum", rendered)
+        self.assertIn("provisional kProvisionalValue = 0;", rendered)
+        self.assertIn("provisional bitmap ProvisionalBitmap", rendered)
+        self.assertIn("provisional kProvisionalBit = 0x1;", rendered)
+        self.assertIn("provisional command ProvisionalCommand(): DefaultSuccess = 0;", rendered)
+
+        # Verify that doc comment is matched and rendered correctly on the provisional command
+        self.assertIn("/** Test command description */", rendered)
+
+        # Also ensure roundtrip parses back to the exact same IDL
+        idl2 = parser.parse(rendered)
+        self.assertEqual(idl, idl2)
+
 
 if __name__ == '__main__':
     unittest.main()