Normalize YAML export formatting for repo-backed namespaces (#1947)

* Make sure that the generated YAML has consistent ordering to prevent spurious changes

* Add tests for consistency of node YAML export

* Fix

Author: shangyian

datajunction-server/datajunction_server/internal/namespaces.py

@@ -18,6 +18,8 @@
 from ruamel.yaml.comments import CommentedSeq
 from ruamel.yaml.comments import CommentedMap
 from ruamel.yaml.comments import Comment
+from yamlfix import fix_code
+from yamlfix.model import YamlfixConfig
 
 from datajunction_server.database.deployment import Deployment
 from datajunction_server.models.deployment import (
@@ -1450,6 +1452,16 @@ def _node_spec_to_yaml_dict(node_spec, include_all_columns=False) -> dict:
         # If columns is explicitly None, remove it
         del data["columns"]
 
+    # Sort list fields for deterministic output
+    if "owners" in data and isinstance(data["owners"], list):  # pragma: no branch
+        data["owners"] = sorted(data["owners"])
+    if "tags" in data and isinstance(data["tags"], list):  # pragma: no branch
+        data["tags"] = sorted(data["tags"])
+    if "columns" in data and isinstance(data["columns"], list):
+        for col in data["columns"]:
+            if "attributes" in col and isinstance(col["attributes"], list):
+                col["attributes"] = sorted(col["attributes"])
+
     # Remove empty lists/dicts for cleaner YAML
     data = {k: v for k, v in data.items() if v or v == 0 or v is False}
 
@@ -1529,7 +1541,13 @@ def node_spec_to_yaml(node_spec, existing_yaml: str | None = None) -> str:
     # Export to YAML
     stream = StringIO()
     yaml_handler.dump(yaml_dict, stream)
-    return stream.getvalue()
+    raw = stream.getvalue()
+
+    # Apply yamlfix for consistent formatting (matches repo pre-commit hooks)
+    yamlfix_config = YamlfixConfig()
+    yamlfix_config.explicit_start = False
+    yamlfix_config.line_length = 120
+    return fix_code(raw, yamlfix_config)
 
 
 # Git configuration validation helpers

datajunction-server/tests/internal/namespaces_test.py

@@ -8,7 +8,10 @@
 from datajunction_server.internal.namespaces import (
     _merge_list_with_key,
     _merge_yaml_preserving_comments,
+    node_spec_to_yaml,
 )
+from datajunction_server.models.deployment import MetricSpec, TransformSpec
+from datajunction_server.models.node_type import NodeType
 
 
 class TestMergeListWithKey:
@@ -301,3 +304,123 @@ def test_merge_yaml_cube_removes_deleted_metrics(self):
         # Should only include items that are in new data, in original order
         assert result["metrics"] == ["metric_a", "metric_c"]
         assert result["dimensions"] == ["dim_x"]
+
+
+class TestNodeSpecToYaml:
+    """Tests for node_spec_to_yaml formatting and determinism"""
+
+    def test_owners_are_sorted(self):
+        """owners list is sorted alphabetically regardless of input order"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            owners=["zara@netflix.com", "alice@netflix.com", "bob@netflix.com"],
+            query="SELECT SUM(rev) FROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.metrics.revenue",
+            "node_type: metric",
+            "owners: [alice@netflix.com, bob@netflix.com, zara@netflix.com]",
+            "mode: published",
+            "query: SELECT SUM(rev) FROM ns.transforms.t",
+        ]
+
+    def test_tags_are_sorted(self):
+        """tags list is sorted alphabetically regardless of input order"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            tags=["ratio_metric", "core", "finance"],
+            query="SELECT SUM(rev) FROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.metrics.revenue",
+            "node_type: metric",
+            "tags: [core, finance, ratio_metric]",
+            "mode: published",
+            "query: SELECT SUM(rev) FROM ns.transforms.t",
+        ]
+
+    def test_column_attributes_are_sorted(self):
+        """column attributes are sorted alphabetically regardless of input order"""
+        spec = TransformSpec(
+            name="ns.transforms.t",
+            node_type=NodeType.TRANSFORM,
+            query="SELECT id FROM ns.source.s",
+            columns=[
+                {
+                    "name": "id",
+                    "display_name": "ID",
+                    "attributes": ["dimension", "primary_key"],
+                },
+            ],
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.transforms.t",
+            "node_type: transform",
+            "mode: published",
+            "columns:",
+            "  - name: id",
+            "    display_name: ID",
+            "    attributes: [dimension, primary_key]",
+            "query: SELECT id FROM ns.source.s",
+        ]
+
+    def test_output_is_deterministic(self):
+        """calling node_spec_to_yaml twice with the same spec gives identical output"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            owners=["zara@netflix.com", "alice@netflix.com"],
+            tags=["ratio_metric", "core"],
+            query="SELECT SUM(rev) FROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec) == node_spec_to_yaml(spec)
+
+    def test_no_yaml_document_start_marker(self):
+        """output does not start with --- (explicit_start=False)"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            query="SELECT SUM(rev) FROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.metrics.revenue",
+            "node_type: metric",
+            "mode: published",
+            "query: SELECT SUM(rev) FROM ns.transforms.t",
+        ]
+
+    def test_multiline_query_uses_literal_block_style(self):
+        """multiline queries are serialized with |- literal block style"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            query="SELECT SUM(rev)\nFROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.metrics.revenue",
+            "node_type: metric",
+            "mode: published",
+            "query: |-",
+            "  SELECT SUM(rev)",
+            "  FROM ns.transforms.t",
+        ]
+
+    def test_short_lists_use_inline_style(self):
+        """short lists (owners, tags) use inline [a, b] style after yamlfix"""
+        spec = MetricSpec(
+            name="ns.metrics.revenue",
+            node_type=NodeType.METRIC,
+            owners=["alice@netflix.com"],
+            tags=["core"],
+            query="SELECT SUM(rev) FROM ns.transforms.t",
+        )
+        assert node_spec_to_yaml(spec).splitlines() == [
+            "name: ns.metrics.revenue",
+            "node_type: metric",
+            "owners: [alice@netflix.com]",
+            "tags: [core]",
+            "mode: published",
+            "query: SELECT SUM(rev) FROM ns.transforms.t",
+        ]