feat: Implement instance dimension enum sanitization and metadata annotation

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

Author: jdacoello

src/vss_tools/exporters/s2dm/type_builders.py

@@ -110,6 +110,8 @@ def create_instance_types(
         Mapping of type names to GraphQL enum or object types
     """
     types: dict[str, GraphQLEnumType | GraphQLObjectType] = {}
+    vspec_comments.setdefault("instance_dimension_enums", {})
+
     for fqn, row in branches_df[branches_df["instances"].notna()].iterrows():
         if instances := row.get("instances"):
             base_name = convert_name_for_graphql_schema(fqn, GraphQLElementType.TYPE, S2DM_CONVERSIONS)
@@ -119,11 +121,28 @@ def create_instance_types(
             fields = {}
             for i, values in enumerate(dimensions, 1):
                 enum_name = f"{tag_name}_Dimension{i}"
+
+                # Sanitize enum values and track modifications
+                enum_values = {}
+                modified_values = {}
+
+                for v in values:
+                    sanitized, was_modified = _sanitize_enum_value_for_graphql(str(v))
+                    enum_values[sanitized] = GraphQLEnumValue(v)
+
+                    if was_modified:
+                        modified_values[sanitized] = str(v)
+
                 types[enum_name] = GraphQLEnumType(
                     enum_name,
-                    {v: GraphQLEnumValue(v) for v in values},
+                    enum_values,
                     description=f"Dimensional enum for VSS instance dimension {i}.",
                 )
+
+                # Store metadata for directive processor
+                if modified_values:
+                    vspec_comments["instance_dimension_enums"][enum_name] = {"modified_values": modified_values}
+
                 fields[f"dimension{i}"] = GraphQLField(types[enum_name])
 
             types[tag_name] = GraphQLObjectType(tag_name, fields)

src/vss_tools/utils/graphql_directive_processor.py

@@ -54,6 +54,9 @@ def process_schema(
 
         lines = self._process_unit_enum_directives(lines, unit_enums_metadata, processed_enum_values)
         lines = self._process_allowed_enum_directives(lines, allowed_enums_metadata, processed_enum_values)
+        lines = self._process_instance_dimension_enum_directives(
+            lines, vspec_comments.get("instance_dimension_enums", {}), processed_enum_values
+        )
         lines = self._process_field_directives(lines, vspec_comments)
         lines = self._process_deprecated_directives(lines, vspec_comments.get("field_deprecated", {}))
         lines = self._process_range_directives(lines, vspec_comments.get("field_ranges", {}))
@@ -167,6 +170,51 @@ def _process_allowed_enum_directives(
 
         return lines
 
+    def _process_instance_dimension_enum_directives(
+        self, lines: list[str], instance_dimension_enums: dict, processed_values: set
+    ) -> list[str]:
+        """
+        Process instance dimension enum directives.
+
+        Annotates enum values that were modified during sanitization with their original names.
+        """
+        for enum_name, enum_data in instance_dimension_enums.items():
+            modified_values = enum_data.get("modified_values", {})
+            if not modified_values:
+                continue
+
+            in_target_enum = False
+
+            for i, line in enumerate(lines):
+                # Detect enum start
+                if line.strip().startswith(f"enum {enum_name}"):
+                    in_target_enum = True
+                    continue
+                elif line.strip().startswith("enum ") and in_target_enum:
+                    in_target_enum = False
+                    continue
+                elif line.strip() == "}" and in_target_enum:
+                    in_target_enum = False
+                    continue
+
+                # Process enum values within target enum
+                if in_target_enum and line.strip() and not line.strip().startswith('"'):
+                    stripped_line = line.strip()
+
+                    for enum_value_name, original_value in modified_values.items():
+                        enum_value_key = f"{enum_name}.{enum_value_name}"
+
+                        if stripped_line.startswith(enum_value_name) and enum_value_key not in processed_values:
+                            if "@vspec" not in line:
+                                indent = line[: len(line) - len(line.lstrip())]
+                                directive = f'@vspec(metadata: [{{key: "originalName", value: "{original_value}"}}])'
+                                lines[i] = f"{indent}{enum_value_name} {directive}"
+
+                            processed_values.add(enum_value_key)
+                            break
+
+        return lines
+
     def _process_field_directives(self, lines: list[str], vspec_comments: dict) -> list[str]:
         """Process consolidated field @vspec directives (element + fqn + optional metadata)."""
         # Process VSS type information (element + fqn + metadata)

tests/test_s2dm_exporter.py

@@ -667,3 +667,38 @@ def test_camelcase_enums_schema_generation(self):
         assert 'IO_ERROR @vspec(metadata: [{key: "originalName", value: "IOError"}])' in schema_str
         assert 'XML_PARSER @vspec(metadata: [{key: "originalName", value: "XMLParser"}])' in schema_str
         assert 'SOME_API_KEY @vspec(metadata: [{key: "originalName", value: "someAPIKey"}])' in schema_str
+
+    def test_instance_dimension_enum_sanitization(self):
+        """Test that instance dimension enum values are properly sanitized and annotated."""
+        # Load the test vspec with instances that need sanitization
+        tree, _ = get_trees(
+            vspec=Path("tests/vspec/test_s2dm/test_instance_sanitization.vspec"),
+            include_dirs=(),
+            aborts=(),
+            strict=False,
+            extended_attributes=(),
+            quantities=(Path("tests/vspec/test_s2dm/test_quantities.yaml"),),
+            units=(Path("tests/vspec/test_s2dm/test_units.yaml"),),
+            overlays=(),
+            expand=False,
+        )
+
+        schema, unit_metadata, allowed_metadata, vspec_comments = generate_s2dm_schema(tree)
+        schema_str = print_schema_with_vspec_directives(schema, unit_metadata, allowed_metadata, vspec_comments)
+
+        # Check that Row instance enum is created and values are sanitized
+        assert "enum Vehicle_Cabin_InstanceTag_Dimension1" in schema_str
+        assert 'ROW1 @vspec(metadata: [{key: "originalName", value: "Row1"}])' in schema_str
+        assert 'ROW2 @vspec(metadata: [{key: "originalName", value: "Row2"}])' in schema_str
+
+        # Check that DriverSide/PassengerSide instance enum is created and values are sanitized
+        assert "enum Vehicle_Cabin_Seat_InstanceTag_Dimension1" in schema_str
+        assert 'DRIVER_SIDE @vspec(metadata: [{key: "originalName", value: "DriverSide"}])' in schema_str
+        assert 'PASSENGER_SIDE @vspec(metadata: [{key: "originalName", value: "PassengerSide"}])' in schema_str
+
+        # Check that FrontLeft/FrontRight/RearLeft/RearRight instance enum is created and values are sanitized
+        assert "enum Vehicle_Cabin_Seat_Position_InstanceTag_Dimension1" in schema_str
+        assert 'FRONT_LEFT @vspec(metadata: [{key: "originalName", value: "FrontLeft"}])' in schema_str
+        assert 'FRONT_RIGHT @vspec(metadata: [{key: "originalName", value: "FrontRight"}])' in schema_str
+        assert 'REAR_LEFT @vspec(metadata: [{key: "originalName", value: "RearLeft"}])' in schema_str
+        assert 'REAR_RIGHT @vspec(metadata: [{key: "originalName", value: "RearRight"}])' in schema_str

tests/vspec/test_s2dm/test_instance_sanitization.vspec

@@ -0,0 +1,28 @@
+# Test vspec for instance dimension enum sanitization
+
+Vehicle:
+  type: branch
+  description: High-level vehicle data.
+
+Vehicle.Cabin:
+  type: branch
+  description: Cabin information.
+  instances:
+    - Row[1,2]
+
+Vehicle.Cabin.Seat:
+  type: branch
+  description: Seat information.
+  instances:
+    - ["DriverSide", "PassengerSide"]
+
+Vehicle.Cabin.Seat.Position:
+  type: branch
+  description: Seat position.
+  instances:
+    - ["FrontLeft", "FrontRight", "RearLeft", "RearRight"]
+
+Vehicle.Cabin.Seat.Position.IsOccupied:
+  datatype: boolean
+  type: actuator
+  description: Is the seat position occupied.