hx-8da6f798 Migrate QualityCheckExecutor fallback

Author: easel

.helix/issues.jsonl

@@ -8,6 +8,11 @@
 {"id":"hx-4db4f06e","title":"Deprecate gx_wrapper.py; migrate consumers to GXSuiteExecutor","type":"task","status":"closed","priority":2,"labels":["helix","blocked"],"deps":[],"parent":"","spec-id":"docs/helix/01-frame/features/FEAT-024-validator-consolidation.md","description":"","design":"","acceptance":"gx_wrapper.py has deprecation warning; validator.py no longer imports gx_wrapper; all GX execution uses GXSuiteExecutor","assignee":"helix","notes":"BLOCKED [2026-04-01T23:12:15-04:00]: failed to complete after 4 attempts with exponential backoff","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:01Z","updated":"2026-04-02T03:15:05Z"}
 {"id":"hx-6a1e485c","title":"ADR-005 Phase C: migrate consumers from quality_checks to ExpectationSuite","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:refactor","area:validation"],"deps":["hx-4db4f06e"],"parent":"","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"All 10 source files updated to read from umf.expectations instead of quality_checks; backward-compatible fallback for old YAML files","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:03Z","updated":"2026-04-02T03:29:43Z"}
 {"id":"hx-bae407fe","title":"Implement GXTestHarness fixture for agentic iteration","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:build","area:testing"],"deps":[],"parent":"","spec-id":"docs/helix/01-frame/features/FEAT-016-testing-infrastructure.md","description":"","design":"","acceptance":"GXTestHarness fixture in tests/conftest.py with harness.run(expectations) API; documented usage example","assignee":"helix","notes":"BLOCKED [2026-04-01T23:12:15-04:00]: failed to complete after 4 attempts with exponential backoff","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:05Z","updated":"2026-04-02T03:37:59Z"}
-{"id":"hx-96d0725a","title":"Resolve preview --against parameter (implement or remove)","type":"task","status":"open","priority":2,"labels":["helix","blocked"],"deps":[],"parent":"","spec-id":"docs/helix/01-frame/features/FEAT-023-authoring-tools.md","description":"","design":"","acceptance":"Either --against triggers CSV validation execution, or parameter is removed from CLI and spec updated","assignee":"","notes":"BLOCKED [2026-04-01T23:12:15-04:00]: failed to complete after 4 attempts with exponential backoff","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:07Z","updated":"2026-04-02T03:12:15Z"}
+{"id":"hx-96d0725a","title":"Resolve preview --against parameter (implement or remove)","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:build","area:authoring"],"deps":[],"parent":"","spec-id":"docs/helix/01-frame/features/FEAT-023-authoring-tools.md","description":"","design":"","acceptance":"Either --against triggers CSV validation execution, or parameter is removed from CLI and spec updated","assignee":"","notes":"BLOCKED [2026-04-01T23:12:15-04:00]: failed to complete after 4 attempts with exponential backoff","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:07Z","updated":"2026-04-02T03:39:28Z"}
 {"id":"hx-ac83f094","title":"Add profiling pipeline end-to-end test","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:test","area:profiling"],"deps":[],"parent":"","spec-id":"docs/helix/01-frame/features/FEAT-005-profiling.md","description":"","design":"","acceptance":"Integration test exercises SparkToUmfMapper -> DeequToUmfMapper -> BaselineExpectationGenerator flow end-to-end","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:09Z","updated":"2026-04-02T03:08:12Z"}
 {"id":"hx-807a8731","title":"Publish tablespec to PyPI","type":"task","status":"closed","priority":2,"labels":["helix","phase:deploy","kind:deploy","area:distribution"],"deps":[],"parent":"","spec-id":"docs/helix/05-deploy/deployment-checklist.md","description":"","design":"","acceptance":"tablespec package available on PyPI; pip install tablespec works","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:00:10Z","updated":"2026-04-02T03:09:52Z"}
+{"id":"hx-2c3c331f","title":"ADR-005 Phase C: migrate consumers to ExpectationSuite","type":"epic","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:validation"],"deps":[],"parent":"","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"All runtime consumers read from ExpectationSuite; quality_checks retained for backward-compatible loading only","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:39:59Z","updated":"2026-04-02T03:39:59Z"}
+{"id":"hx-bdb8fff2","title":"Migrate UMFLoader to populate ExpectationSuite on read","type":"task","status":"in_progress","priority":2,"labels":["helix","phase:build","kind:refactor","area:loader"],"deps":[],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"UMFLoader.load() populates umf.expectations from validation_rules + quality_checks via expectation_migration; split-format saver writes expectations.yaml","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:07Z","updated":"2026-04-02T03:44:10Z"}
+{"id":"hx-8da6f798","title":"Migrate QualityCheckExecutor to read from ExpectationSuite","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:refactor","area:validation"],"deps":["hx-bdb8fff2"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"QualityCheckExecutor reads from umf.expectations; falls back to quality_checks if expectations is empty","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:13Z","updated":"2026-04-02T03:48:32Z"}
+{"id":"hx-9ed0389d","title":"Migrate authoring commands to use ExpectationSuite","type":"task","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:authoring"],"deps":["hx-bdb8fff2"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"mutations.py, preview.py, apply_response.py, and cli.py search/mutate umf.expectations instead of quality_checks","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:19Z","updated":"2026-04-02T03:40:19Z"}
+{"id":"hx-f3261259","title":"Add deprecation warnings to quality_checks and validation_rules fields","type":"task","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:models"],"deps":["hx-8da6f798","hx-9ed0389d"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"Pydantic model emits DeprecationWarning when quality_checks or validation_rules are populated directly; ADR-005 status updated to Phase C","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:24Z","updated":"2026-04-02T03:40:24Z"}

src/tablespec/quality/executor.py

@@ -201,24 +201,7 @@ def execute_quality_checks(
                 )
 
         # Extract ingested-stage checks from the unified expectation suite.
-        suite = umf.expectations or migrate_to_expectation_suite(umf.model_dump(exclude_none=True))
-        configured_checks: list[QualityCheck] = []
-        thresholds_dict: dict[str, Any] | None = None
-
-        if suite:
-            from tablespec.models.umf import QualityCheck as QualityCheckModel
-
-            configured_checks = [
-                QualityCheckModel(
-                    expectation=exp.model_dump(),
-                    severity=exp.meta.severity,
-                    blocking=exp.meta.blocking,
-                    description=exp.meta.description,
-                    tags=list(exp.meta.tags),
-                )
-                for exp in suite.ingested
-            ]
-            thresholds_dict = suite.thresholds
+        configured_checks, thresholds_dict = self._get_configured_checks(umf)
 
         # Add default checks (row count change) unless already configured
         checks = self._merge_with_defaults(configured_checks)
@@ -320,6 +303,33 @@ def execute_quality_checks(
             validated_records=validated_records,
         )
 
+    def _get_configured_checks(
+        self,
+        umf: Any,
+    ) -> tuple[list[QualityCheck], dict[str, Any] | None]:
+        """Return configured ingested checks and thresholds for a loaded UMF.
+
+        Prefer the unified ExpectationSuite when it contains expectations.
+        Fall back to migrating legacy quality_checks when the suite is absent or empty.
+        """
+        suite = umf.expectations
+        if suite is None or not suite.expectations:
+            suite = migrate_to_expectation_suite(umf.model_dump(exclude_none=True))
+
+        from tablespec.models.umf import QualityCheck as QualityCheckModel
+
+        configured_checks = [
+            QualityCheckModel(
+                expectation=exp.model_dump(),
+                severity=exp.meta.severity,
+                blocking=exp.meta.blocking,
+                description=exp.meta.description,
+                tags=list(exp.meta.tags),
+            )
+            for exp in suite.ingested
+        ]
+        return configured_checks, suite.thresholds
+
     def _execute_batch(
         self,
         spark_df: DataFrame,

tests/unit/test_quality_executor_selection.py

@@ -0,0 +1,110 @@
+"""Tests for QualityCheckExecutor expectation source selection."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from tablespec.models.umf import Expectation, ExpectationMeta, ExpectationSuite
+from tablespec.quality.executor import QualityCheckExecutor
+
+pytestmark = [pytest.mark.fast, pytest.mark.no_spark]
+
+
+def _make_executor() -> QualityCheckExecutor:
+    return object.__new__(QualityCheckExecutor)
+
+
+class TestConfiguredCheckSelection:
+    def test_prefers_expectation_suite_when_populated(self) -> None:
+        executor = _make_executor()
+        suite = ExpectationSuite(
+            expectations=[
+                Expectation(
+                    type="expect_column_values_to_be_between",
+                    kwargs={"column": "amount", "min_value": 0},
+                    meta=ExpectationMeta(
+                        stage="ingested",
+                        severity="critical",
+                        blocking=True,
+                        description="amount must be non-negative",
+                        tags=["finance"],
+                    ),
+                ),
+                Expectation(
+                    type="expect_column_values_to_match_regex",
+                    kwargs={"column": "code", "regex": r"^[A-Z]+$"},
+                    meta=ExpectationMeta(stage="raw"),
+                ),
+            ],
+            thresholds={"max_failures": 2},
+        )
+        umf = SimpleNamespace(
+            expectations=suite,
+            model_dump=lambda **_: {"quality_checks": {"checks": ["legacy"]}},
+        )
+
+        with patch("tablespec.quality.executor.migrate_to_expectation_suite") as migrate:
+            checks, thresholds = executor._get_configured_checks(umf)
+
+        migrate.assert_not_called()
+        assert thresholds == {"max_failures": 2}
+        assert len(checks) == 1
+        assert checks[0].expectation["type"] == "expect_column_values_to_be_between"
+        assert checks[0].severity == "critical"
+        assert checks[0].blocking is True
+        assert checks[0].description == "amount must be non-negative"
+        assert checks[0].tags == ["finance"]
+
+    def test_falls_back_to_legacy_checks_when_suite_is_empty(self) -> None:
+        executor = _make_executor()
+        umf = SimpleNamespace(
+            expectations=ExpectationSuite(expectations=[]),
+            model_dump=lambda **_: {"quality_checks": {"checks": ["legacy"]}},
+        )
+        migrated_suite = ExpectationSuite(
+            expectations=[
+                Expectation(
+                    type="expect_column_values_to_be_in_set",
+                    kwargs={"column": "status", "value_set": ["A", "B"]},
+                    meta=ExpectationMeta(stage="ingested", severity="warning"),
+                )
+            ],
+            thresholds={"min_success_rate": 95.0},
+        )
+
+        with patch(
+            "tablespec.quality.executor.migrate_to_expectation_suite",
+            return_value=migrated_suite,
+        ) as migrate:
+            checks, thresholds = executor._get_configured_checks(umf)
+
+        migrate.assert_called_once_with({"quality_checks": {"checks": ["legacy"]}})
+        assert thresholds == {"min_success_rate": 95.0}
+        assert len(checks) == 1
+        assert checks[0].expectation["type"] == "expect_column_values_to_be_in_set"
+        assert checks[0].severity == "warning"
+
+    def test_does_not_fall_back_when_suite_has_only_raw_expectations(self) -> None:
+        executor = _make_executor()
+        umf = SimpleNamespace(
+            expectations=ExpectationSuite(
+                expectations=[
+                    Expectation(
+                        type="expect_column_values_to_match_regex",
+                        kwargs={"column": "id", "regex": r"^\d+$"},
+                        meta=ExpectationMeta(stage="raw"),
+                    )
+                ]
+            ),
+            model_dump=lambda **_: {"quality_checks": {"checks": ["legacy"]}},
+        )
+
+        with patch("tablespec.quality.executor.migrate_to_expectation_suite") as migrate:
+            checks, thresholds = executor._get_configured_checks(umf)
+
+        migrate.assert_not_called()
+        assert checks == []
+        assert thresholds is None