feat(s2dm): add extended attributes metadata annotations

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.comt -c core.editor=true rebase --continue
t status --short
>

Author: jdacoello

docs/s2dm.md

@@ -46,6 +46,37 @@ Likewise, the `driverPosition` was derived from `Vehicle.Cabin.DriverPosition` a
 
 The `@vspec` directive is also used to annotate original names when they have been modified for GraphQL compliance (for example, see [Enum Value Sanitization](#enum-value-sanitization)).
 
+#### Extended Attributes
+
+If the VSpec model uses extended attributes (custom metadata), the exporter add them to `@vspec` metadata annotations.
+
+**Example VSS with extended attributes `source` and `quality`:**
+```yaml
+Vehicle.Speed:
+  datatype: float
+  type: sensor
+  unit: km/h
+  source: ecu0xAA        # Extended attribute
+  quality: 100           # Extended attribute
+```
+
+**Generated GraphQL:**
+```graphql
+type Vehicle {
+  speed(unit: VelocityUnitEnum = KILOMETERS_PER_HOUR): Float
+    @vspec(
+      element: SENSOR,
+      fqn: "Vehicle.Speed",
+      metadata: [
+        {key: "source", value: "ecu0xAA"},
+        {key: "quality", value: "100"}
+      ]
+    )
+}
+```
+
+Extended attributes work on all VSS elements: branches, sensors, actuators, attributes, and structs.
+
 ### VSS Data Types Support
 The exporter handles all `vspec` data types as follows:
 - **Strings** → GraphQL String

src/vss_tools/exporters/s2dm/schema_generator.py

@@ -100,7 +100,7 @@ def generate_s2dm_schema(
         for fqn in branches_df.index:
             if fqn not in types_registry:
                 types_registry[fqn] = create_object_type(
-                    fqn, branches_df, leaves_df, types_registry, unit_enums, vspec_comments
+                    fqn, branches_df, leaves_df, types_registry, unit_enums, vspec_comments, extended_attributes
                 )
 
         # Assemble complete schema

src/vss_tools/exporters/s2dm/type_builders.py

@@ -46,6 +46,24 @@
 from .metadata_tracker import build_field_path
 
 
+def _extract_extended_attributes(row: pd.Series, extended_attributes: tuple[str, ...]) -> dict[str, Any]:
+    """
+    Extract extended attributes from a DataFrame row.
+
+    Args:
+        row: pandas Series (DataFrame row) containing VSS node data
+        extended_attributes: Tuple of extended attribute names to extract
+
+    Returns:
+        Dictionary containing only the extended attributes that exist and are not NA
+    """
+    extracted = {}
+    for ext_attr in extended_attributes:
+        if ext_attr in row.index and pd.notna(row.get(ext_attr)):
+            extracted[ext_attr] = row[ext_attr]
+    return extracted
+
+
 def create_unit_enums() -> tuple[dict[str, GraphQLEnumType], dict[str, dict[str, dict[str, str]]]]:
     """
     Create GraphQL enum types for VSS units grouped by quantity.
@@ -307,7 +325,12 @@ def create_struct_types(
             fields[field_name] = GraphQLField(GraphQLNonNull(base_type), description=prop_row.get("description", ""))
 
             field_path = build_field_path(type_name, field_name)
-            vspec_comments["field_vss_types"][field_path] = {"element": "STRUCT_PROPERTY", "fqn": prop_fqn}
+            field_metadata = {"element": "STRUCT_PROPERTY", "fqn": prop_fqn}
+
+            # Capture extended attributes if present
+            field_metadata.update(_extract_extended_attributes(prop_row, extended_attributes))
+
+            vspec_comments["field_vss_types"][field_path] = field_metadata
 
             if pd.notna(prop_row.get("min")) or pd.notna(prop_row.get("max")):
                 vspec_comments["field_ranges"][field_path] = {
@@ -321,7 +344,11 @@ def create_struct_types(
         struct_types[type_name] = GraphQLObjectType(
             name=type_name, fields=fields, description=struct_row.get("description", "")
         )
-        vspec_comments["vss_types"][type_name] = {"element": "STRUCT", "fqn": fqn}
+
+        # Store type-level metadata including extended attributes
+        type_metadata = {"element": "STRUCT", "fqn": fqn}
+        type_metadata.update(_extract_extended_attributes(struct_row, extended_attributes))
+        vspec_comments["vss_types"][type_name] = type_metadata
 
     return struct_types
 
@@ -367,6 +394,7 @@ def create_object_type(
     types_registry: dict[str, Any],
     unit_enums: dict[str, GraphQLEnumType],
     vspec_comments: dict[str, dict[str, Any]],
+    extended_attributes: tuple[str, ...] = (),
 ) -> GraphQLObjectType:
     """
     Create GraphQL object type for a VSS branch.
@@ -381,6 +409,7 @@ def create_object_type(
         types_registry: Registry of already-created types
         unit_enums: Unit enum types
         vspec_comments: Metadata tracking dictionary
+        extended_attributes: Extended attribute names from CLI
 
     Returns:
         GraphQL object type for the branch
@@ -415,7 +444,12 @@ def get_fields() -> dict[str, GraphQLField]:
             field_path = build_field_path(type_name, field_name)
 
             if leaf_type := _get_vss_type_if_valid(leaf_row):
-                vspec_comments["field_vss_types"][field_path] = {"element": leaf_type, "fqn": child_fqn}
+                field_metadata = {"element": leaf_type, "fqn": child_fqn}
+
+                # Capture extended attributes if present
+                field_metadata.update(_extract_extended_attributes(leaf_row, extended_attributes))
+
+                vspec_comments["field_vss_types"][field_path] = field_metadata
 
             if pd.notna(leaf_row.get("min")) or pd.notna(leaf_row.get("max")):
                 vspec_comments["field_ranges"][field_path] = {
@@ -434,12 +468,12 @@ def get_fields() -> dict[str, GraphQLField]:
         for child_fqn, child_row in branches_df[branches_df["parent"] == fqn].iterrows():
             field_name = convert_name_for_graphql_schema(child_row["name"], GraphQLElementType.FIELD, S2DM_CONVERSIONS)
             child_type = types_registry.get(child_fqn) or create_object_type(
-                child_fqn, branches_df, leaves_df, types_registry, unit_enums, vspec_comments
+                child_fqn, branches_df, leaves_df, types_registry, unit_enums, vspec_comments, extended_attributes
             )
             types_registry[child_fqn] = child_type
 
             hoisted_fields = get_hoisted_fields(
-                child_fqn, child_row, leaves_df, types_registry, unit_enums, vspec_comments
+                child_fqn, child_row, leaves_df, types_registry, unit_enums, vspec_comments, extended_attributes
             )
             fields.update(hoisted_fields)
 
@@ -450,7 +484,10 @@ def get_fields() -> dict[str, GraphQLField]:
 
         return fields
 
-    vspec_comments["vss_types"][type_name] = {"element": "BRANCH", "fqn": fqn}
+    # Store type-level metadata including extended attributes
+    type_metadata = {"element": "BRANCH", "fqn": fqn}
+    type_metadata.update(_extract_extended_attributes(branch_row, extended_attributes))
+    vspec_comments["vss_types"][type_name] = type_metadata
 
     return GraphQLObjectType(name=type_name, fields=get_fields, description=branch_row.get("description", ""))
 
@@ -462,6 +499,7 @@ def get_hoisted_fields(
     types_registry: dict[str, Any],
     unit_enums: dict[str, GraphQLEnumType],
     vspec_comments: dict[str, dict[str, Any]],
+    extended_attributes: tuple[str, ...] = (),
 ) -> dict[str, GraphQLField]:
     """Get fields to hoist from instantiated child branch to parent."""
     hoisted: dict[str, GraphQLField] = {}
@@ -492,12 +530,17 @@ def get_hoisted_fields(
             field_path = build_field_path(parent_type_name, hoisted_field_name)
 
             if leaf_type := _get_vss_type_if_valid(leaf_row):
-                vspec_comments["field_vss_types"][field_path] = {
+                field_metadata = {
                     "element": leaf_type,
                     "fqn": leaf_fqn,
                     "instantiate": False,
                 }
 
+                # Capture extended attributes if present
+                field_metadata.update(_extract_extended_attributes(leaf_row, extended_attributes))
+
+                vspec_comments["field_vss_types"][field_path] = field_metadata
+
             if pd.notna(leaf_row.get("min")) or pd.notna(leaf_row.get("max")):
                 vspec_comments["field_ranges"][field_path] = {
                     "min": leaf_row.get("min") if pd.notna(leaf_row.get("min")) else None,

src/vss_tools/utils/graphql_directive_processor.py

@@ -237,13 +237,24 @@ def _process_field_directives(self, lines: list[str], vspec_comments: dict) -> l
                     continue
 
                 if in_type and line.strip().startswith(f"{field_name}") and "@vspec" not in line:
-                    # Build directive with element (mandatory), fqn, and optional metadata
+                    # Build metadata array from extended attributes
+                    metadata_entries = []
+
+                    # Add instantiate metadata if present
                     if instantiate is False:
-                        # Add metadata for hoisted non-instantiated fields
-                        directive = (
-                            f'@vspec(element: {element}, fqn: "{fqn}", '
-                            f'metadata: [{{key: "instantiate", value: "false"}}])'
-                        )
+                        metadata_entries.append('{key: "instantiate", value: "false"}')
+
+                    # Add extended attributes metadata
+                    for key, value in vss_info.items():
+                        if key not in ["element", "fqn", "instantiate"]:
+                            # Escape quotes in value
+                            escaped_value = str(value).replace('"', '\\\\"')
+                            metadata_entries.append(f'{{key: "{key}", value: "{escaped_value}"}}')
+
+                    # Build directive
+                    if metadata_entries:
+                        metadata_str = ", ".join(metadata_entries)
+                        directive = f'@vspec(element: {element}, fqn: "{fqn}", metadata: [{metadata_str}])'
                     else:
                         # Standard directive without metadata
                         directive = f'@vspec(element: {element}, fqn: "{fqn}")'
@@ -375,11 +386,25 @@ def _process_type_directives(self, lines: list[str], vspec_comments: dict) -> li
                         )
                         new_line += f" {directive}"
                     elif needs_vss_type and "@vspec" not in line:
-                        # Regular types get element + fqn only
+                        # Regular types get element + fqn + extended attributes metadata
                         vss_info = vspec_comments["vss_types"][type_name]
                         element = vss_info["element"]
                         fqn = vss_info["fqn"]
-                        directive = f'@vspec(element: {element}, fqn: "{fqn}")'
+
+                        # Build metadata array from extended attributes
+                        metadata_entries = []
+                        for key, value in vss_info.items():
+                            if key not in ["element", "fqn"]:
+                                # Escape quotes in value
+                                escaped_value = str(value).replace('"', '\\\\"')
+                                metadata_entries.append(f'{{key: "{key}", value: "{escaped_value}"}}')
+
+                        # Build directive
+                        if metadata_entries:
+                            metadata_str = ", ".join(metadata_entries)
+                            directive = f'@vspec(element: {element}, fqn: "{fqn}", metadata: [{metadata_str}])'
+                        else:
+                            directive = f'@vspec(element: {element}, fqn: "{fqn}")'
                         new_line += f" {directive}"
 
                     new_line += " {"

tests/test_s2dm_exporter.py

@@ -702,3 +702,42 @@ def test_instance_dimension_enum_sanitization(self):
         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
+
+    def test_extended_attributes_in_metadata(self):
+        """Test that extended attributes are captured and added to @vspec metadata."""
+        # Load the test vspec with extended attributes
+        tree, _ = get_trees(
+            vspec=Path("tests/vspec/test_s2dm/test_extended_attributes.vspec"),
+            include_dirs=(),
+            aborts=(),
+            strict=False,
+            extended_attributes=("source", "quality", "calibration", "customMetadata", "anotherAttribute"),
+            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, extended_attributes=("source", "quality", "calibration", "customMetadata", "anotherAttribute")
+        )
+        schema_str = print_schema_with_vspec_directives(schema, unit_metadata, allowed_metadata, vspec_comments)
+
+        # Check Vehicle.Speed has source and quality in metadata
+        assert "speed(unit: RelationUnitEnum = PERCENT): Float" in schema_str
+        assert '@vspec(element: SENSOR, fqn: "Vehicle.Speed"' in schema_str
+        assert '{key: "source", value: "ecu0xAA"}' in schema_str
+        assert '{key: "quality", value: "100"}' in schema_str
+
+        # Check Vehicle.Temperature has source, quality, and calibration
+        assert "temperature(unit: AngleUnitEnum = DEGREE): Int16" in schema_str
+        assert '@vspec(element: SENSOR, fqn: "Vehicle.Temperature"' in schema_str
+        assert '{key: "source", value: "ecu0xBB"}' in schema_str
+        assert '{key: "quality", value: "95"}' in schema_str
+        assert '{key: "calibration", value: "factory"}' in schema_str
+
+        # Check Vehicle.Info.Model has customMetadata and anotherAttribute
+        assert "model: String" in schema_str
+        assert '@vspec(element: ATTRIBUTE, fqn: "Vehicle.Info.Model"' in schema_str
+        assert '{key: "customMetadata", value: "test_value"}' in schema_str
+        assert '{key: "anotherAttribute", value: "42"}' in schema_str

tests/vspec/test_s2dm/test_extended_attributes.vspec

@@ -0,0 +1,33 @@
+# Test vspec for extended attributes in S2DM exporter
+
+Vehicle:
+  type: branch
+  description: High-level vehicle data.
+
+Vehicle.Speed:
+  datatype: float
+  type: sensor
+  unit: percent
+  description: Vehicle speed.
+  source: ecu0xAA
+  quality: 100
+
+Vehicle.Temperature:
+  datatype: int16
+  type: sensor
+  unit: degrees
+  description: Ambient temperature.
+  source: ecu0xBB
+  quality: 95
+  calibration: factory
+
+Vehicle.Info:
+  type: branch
+  description: Vehicle information.
+
+Vehicle.Info.Model:
+  datatype: string
+  type: attribute
+  description: Vehicle model.
+  customMetadata: test_value
+  anotherAttribute: 42