Merge branch 'refactor/TG-1116-misc-cleanup' into 'enterprise'

ci bot · ci bot · commit 104ae70ad8e0 · 2026-06-04T18:06:06.000Z
Miscellaneous cleanup: MCP run-kind labels, shared run-status labels, API schema hygiene

See merge request dkinternal/testgen/dataops-testgen!537
diff --git a/testgen/api/deps.py b/testgen/api/deps.py
@@ -7,8 +7,9 @@
 from sqlalchemy import select
 
 from testgen.common.auth import authorize_token, decode_jwt_token
+from testgen.common.enums import PublicJobKey
 from testgen.common.models import Session, _current_session_wrapper, get_current_session
-from testgen.common.models.job_execution import PUBLIC_JOB_KEYS, JobExecution
+from testgen.common.models.job_execution import JobExecution
 from testgen.common.models.project_membership import ProjectMembership
 from testgen.common.models.table_group import TableGroup
 from testgen.common.models.test_suite import TestSuite
@@ -122,15 +123,15 @@ def dependency(test_suite_id: UUID, user: User = _require_user) -> TestSuite:
 def resolve_job(permission: str, *extra_filters):
     """Resolve a JobExecution by ``job_id`` path param and verify project permission.
 
-    Only jobs whose ``job_key`` is in ``PUBLIC_JOB_KEYS`` are exposed via the API.
+    Only externally-triggerable jobs (``PublicJobKey``) are exposed via the API.
     Internal kinds (score rollups, recalculations, monitor runs) are filtered out
     by construction. Extra ORM clauses are appended to the WHERE clause to further
     restrict by job_key when a caller wants a single kind.
     """
     def dependency(job_id: UUID, user: User = _require_user) -> JobExecution:
         query = select(JobExecution).where(
             JobExecution.id == job_id,
-            JobExecution.job_key.in_(PUBLIC_JOB_KEYS),
+            JobExecution.job_key.in_(list(PublicJobKey)),
             *extra_filters,
         )
         return _check_access(get_current_session().scalars(query).first(), user, permission)
diff --git a/testgen/api/jobs.py b/testgen/api/jobs.py
@@ -11,8 +11,8 @@
     resolve_test_suite,
 )
 from testgen.api.schemas import ErrorResponse, JobListResponse, JobResponse, JobSubmittedResponse
-from testgen.common.enums import JobKey, JobSource, JobStatus
-from testgen.common.models.job_execution import PUBLIC_JOB_KEYS, JobExecution
+from testgen.common.enums import JobKey, JobSource, JobStatus, PublicJobKey
+from testgen.common.models.job_execution import JobExecution
 from testgen.common.models.table_group import TableGroup
 from testgen.common.models.test_suite import TestSuite
 
@@ -98,15 +98,15 @@ def cancel_job(job: JobExecution = resolve_job("edit")):  # noqa: B008
 )
 def list_jobs(
     project_code: str = resolve_project_code("view"),
-    job_key: JobKey | None = Query(default=None),  # noqa: B008
+    job_key: PublicJobKey | None = Query(default=None),  # noqa: B008
     status: JobStatus | None = Query(default=None),  # noqa: B008
     page: int = Query(default=1, ge=1),
     limit: int = Query(default=20, ge=1, le=100),
 ):
     """List job executions for a project, with optional filters and pagination."""
     items, total = JobExecution.list_for_project(
         project_code,
-        JobExecution.job_key.in_(PUBLIC_JOB_KEYS),
+        JobExecution.job_key.in_(list(PublicJobKey)),
         job_key=job_key,
         status=status,
         page=page,
diff --git a/testgen/api/oauth/metadata.py b/testgen/api/oauth/metadata.py
@@ -12,7 +12,7 @@
 def authorization_server_metadata():
     """Return OAuth 2.1 Authorization Server Metadata per RFC 8414.
 
-    MCP clients use this for server discovery.
+    OAuth clients use this for server discovery.
     """
     base_url = settings.BASE_URL.rstrip("/")
 
diff --git a/testgen/api/runs.py b/testgen/api/runs.py
@@ -7,13 +7,13 @@
 from testgen.api.schemas import (
     ErrorResponse,
     IssueBreakdown,
-    JobKey,
     ProfilingRunResponse,
     ProfilingRunResult,
     TestBreakdown,
     TestRunResponse,
     TestRunResult,
 )
+from testgen.common.enums import JobKey
 from testgen.common.models import get_current_session
 from testgen.common.models.hygiene_issue import HygieneIssue
 from testgen.common.models.job_execution import JobExecution
diff --git a/testgen/api/schemas.py b/testgen/api/schemas.py
@@ -6,7 +6,7 @@
 
 from pydantic import BaseModel, field_validator
 
-from testgen.common.enums import JobKey, JobSource, JobStatus
+from testgen.common.enums import JobSource, JobStatus, PublicJobKey
 
 # --- Jobs ---
 
@@ -24,7 +24,7 @@ class JobResponse(BaseModel):
     """Full job execution record returned by status and cancel endpoints."""
 
     id: UUID
-    job_key: JobKey
+    job_key: PublicJobKey
     status: JobStatus
     source: JobSource
     created_at: datetime
diff --git a/testgen/common/enums.py b/testgen/common/enums.py
@@ -40,14 +40,21 @@ class JobKey(StrEnum):
     run_data_cleanup = "run-data-cleanup"
 
 
+class PublicJobKey(StrEnum):
+    """``job_key`` values exposed through the public API — the externally-triggerable
+    subset of ``JobKey``. Internal maintenance kinds are intentionally absent."""
+    run_profile = JobKey.run_profile.value
+    run_tests = JobKey.run_tests.value
+    run_test_generation = JobKey.run_test_generation.value
+
+
 class JobSource(StrEnum):
     """``source`` column values for ``job_executions``."""
     api = "api"
     ui = "ui"
     scheduler = "scheduler"
     mcp = "mcp"
     cli = "cli"
-    backfill = "backfill"
     system = "system"
 
 
@@ -63,6 +70,18 @@ class JobStatus(StrEnum):
     CANCELED = "canceled"
 
 
+# User-facing display labels for JobStatus values.
+JOB_STATUS_LABEL: dict[str, str] = {
+    JobStatus.COMPLETED: "Completed",
+    JobStatus.CANCELED: "Canceled",
+    JobStatus.CANCEL_REQUESTED: "Canceling",
+    JobStatus.PENDING: "Pending",
+    JobStatus.CLAIMED: "Starting",
+    JobStatus.RUNNING: "Running",
+    JobStatus.ERROR: "Error",
+}
+
+
 class Disposition(StrEnum):
     """Stored disposition values for ``profile_anomaly_results.disposition`` and
     ``test_results.disposition``. The user-facing label for ``INACTIVE`` is "Muted"."""
diff --git a/testgen/common/models/job_execution.py b/testgen/common/models/job_execution.py
@@ -6,21 +6,12 @@
 from sqlalchemy import Column, String, Text, case, delete, func, select, text, update
 from sqlalchemy.dialects import postgresql
 
-from testgen.common.enums import JobKey, JobSource, JobStatus
+from testgen.common.enums import JobSource, JobStatus
 from testgen.common.models import Base, database_session, get_current_session
 
 LOG = logging.getLogger("testgen")
 
 
-# Job kinds that are externally triggerable. Internal kinds (run-score-update,
-# recalculate-project-scores, ...) are absent and filtered out by construction.
-PUBLIC_JOB_KEYS: frozenset[JobKey] = frozenset({
-    JobKey.run_profile,
-    JobKey.run_tests,
-    JobKey.run_test_generation,
-})
-
-
 _VALID_TRANSITIONS: dict[JobStatus, frozenset[JobStatus]] = {
     JobStatus.PENDING: frozenset({JobStatus.CLAIMED, JobStatus.CANCEL_REQUESTED}),
     JobStatus.CLAIMED: frozenset({JobStatus.RUNNING, JobStatus.ERROR, JobStatus.CANCEL_REQUESTED}),
diff --git a/testgen/common/models/profiling_run.py b/testgen/common/models/profiling_run.py
@@ -10,7 +10,7 @@
 from sqlalchemy.orm.attributes import flag_modified
 from sqlalchemy.sql.expression import case
 
-from testgen.common.enums import Disposition, JobStatus
+from testgen.common.enums import JOB_STATUS_LABEL, Disposition, JobStatus
 from testgen.common.models import database_session, get_current_session
 from testgen.common.models.connection import Connection
 from testgen.common.models.entity import Entity, EntityMinimal
@@ -71,15 +71,7 @@ class ProfilingRunSummary(EntityMinimal):
     dq_score_profiling: float | None
     total_count: int
 
-    STATUS_LABEL: ClassVar[dict[str, str]] = {
-        JobStatus.COMPLETED: "Completed",
-        JobStatus.CANCELED: "Canceled",
-        JobStatus.CANCEL_REQUESTED: "Canceling",
-        JobStatus.PENDING: "Pending",
-        JobStatus.CLAIMED: "Starting",
-        JobStatus.RUNNING: "Running",
-        JobStatus.ERROR: "Error",
-    }
+    STATUS_LABEL: ClassVar[dict[str, str]] = JOB_STATUS_LABEL
 
     @property
     def status_label(self) -> str:
diff --git a/testgen/common/models/test_run.py b/testgen/common/models/test_run.py
@@ -8,7 +8,7 @@
 from sqlalchemy.orm.attributes import flag_modified
 from sqlalchemy.sql.expression import case
 
-from testgen.common.enums import JobStatus
+from testgen.common.enums import JOB_STATUS_LABEL, JobStatus
 from testgen.common.models import database_session, get_current_session
 from testgen.common.models.connection import Connection
 from testgen.common.models.entity import Entity, EntityMinimal
@@ -70,15 +70,7 @@ class TestRunSummary(EntityMinimal):
     dq_score_testing: float | None
     total_count: int
 
-    STATUS_LABEL: ClassVar[dict[str, str]] = {
-        JobStatus.COMPLETED: "Completed",
-        JobStatus.CANCELED: "Canceled",
-        JobStatus.CANCEL_REQUESTED: "Canceling",
-        JobStatus.PENDING: "Pending",
-        JobStatus.CLAIMED: "Starting",
-        JobStatus.RUNNING: "Running",
-        JobStatus.ERROR: "Error",
-    }
+    STATUS_LABEL: ClassVar[dict[str, str]] = JOB_STATUS_LABEL
 
     @property
     def status_label(self) -> str:
diff --git a/testgen/mcp/tools/execution.py b/testgen/mcp/tools/execution.py
@@ -133,7 +133,7 @@ def _render_submission(
 ) -> str:
     doc = MdDoc()
     doc.heading(1, f"{kind} submitted for `{scope_name}`")
-    doc.field("Job ID", job.id, code=True)
+    doc.field(kind.title(), job.id, code=True)
     doc.field(scope_label, scope_name)
     doc.field("Status", "Pending")
     doc.text(f"Use `{poll_tool}` {poll_hint}.")
@@ -147,7 +147,7 @@ def _render_cancel(job: JobExecution, kind: str, poll_tool: str) -> str:
         )
     doc = MdDoc()
     doc.heading(1, f"{kind} cancellation requested")
-    doc.field("Job ID", job.id, code=True)
+    doc.field(kind.title(), job.id, code=True)
     doc.field("Status", job.status)
     doc.text(f"Use `{poll_tool}` to confirm cancellation.")
     return doc.render()
diff --git a/testgen/mcp/tools/profiling.py b/testgen/mcp/tools/profiling.py
@@ -509,7 +509,7 @@ def get_profiling_run(job_execution_id: str) -> str:
     doc = MdDoc()
     tg_label = summary.table_groups_name or "—"
     doc.heading(1, f"Profiling run: {tg_label}")
-    doc.field("Job ID", summary.job_execution_id, code=True)
+    doc.field("Profiling Run", summary.job_execution_id, code=True)
     if summary.table_groups_name:
         doc.field("Table group", summary.table_groups_name)
     if summary.table_group_schema:
@@ -561,7 +561,7 @@ def get_profiling_run(job_execution_id: str) -> str:
 def _render_pending_profiling_je(doc: MdDoc, je: JobExecution, label: str) -> None:
     status_label = ProfilingRunSummary.STATUS_LABEL.get(je.status, je.status)
     doc.heading(3, f"{label} — {status_label}")
-    doc.field("Job ID", je.id, code=True)
+    doc.field("Profiling Run", je.id, code=True)
     if je.job_schedule_id is not None:
         doc.field("Schedule", je.job_schedule_id, code=True)
     doc.field("Submitted", je.created_at)
@@ -572,7 +572,7 @@ def _render_pending_profiling_je(doc: MdDoc, je: JobExecution, label: str) -> No
 def _render_profiling_run_section(doc: MdDoc, run: ProfilingRunSummary) -> None:
     title = run.table_groups_name or run.profiling_run_id or run.job_execution_id
     doc.heading(2, f"{title} — {run.status_label}")
-    doc.field("Job ID", run.job_execution_id, code=True)
+    doc.field("Profiling Run", run.job_execution_id, code=True)
     if run.job_schedule_id is not None:
         doc.field("Schedule", run.job_schedule_id, code=True)
     doc.field("Submitted", run.created_at)
diff --git a/testgen/mcp/tools/schedules.py b/testgen/mcp/tools/schedules.py
@@ -6,12 +6,11 @@
 from sqlalchemy import select
 
 from testgen.common.cron_service import describe_cron, get_cron_sample
-from testgen.common.enums import JobKey
+from testgen.common.enums import JOB_STATUS_LABEL, JobKey
 from testgen.common.models import get_current_session, with_database_session
 from testgen.common.models.job_execution import JobExecution
 from testgen.common.models.scheduler import JobSchedule
 from testgen.common.models.table_group import TableGroup
-from testgen.common.models.test_run import TestRunSummary  # STATUS_LABEL is shared with ProfilingRunSummary
 from testgen.common.models.test_suite import TestSuite
 from testgen.mcp.exceptions import MCPResourceNotAccessible, MCPUserError
 from testgen.mcp.permissions import get_project_permissions, mcp_permission
@@ -421,13 +420,13 @@ def get_schedule(schedule_id: str) -> str:
     for je in history:
         rows.append([
             je.id,
-            TestRunSummary.STATUS_LABEL.get(je.status, je.status),
+            JOB_STATUS_LABEL.get(je.status, je.status),
             je.started_at,
             je.completed_at,
             format_run_duration(je.started_at, je.completed_at),
         ])
     doc.table(
-        ["Job ID", "Status", "Started", "Completed", "Duration"],
+        [_kind_display(sched.key), "Status", "Started", "Completed", "Duration"],
         rows,
         code=[0],
     )
diff --git a/testgen/mcp/tools/test_runs.py b/testgen/mcp/tools/test_runs.py
@@ -160,7 +160,7 @@ def get_test_run(job_execution_id: str) -> str:
     doc = MdDoc()
     suite_label = summary.test_suite or "—"
     doc.heading(1, f"Test run: {suite_label}")
-    doc.field("Job ID", summary.job_execution_id, code=True)
+    doc.field("Test Run", summary.job_execution_id, code=True)
     doc.field("Test suite", suite_label)
     if summary.table_groups_name:
         doc.field("Table group", summary.table_groups_name)
@@ -278,7 +278,7 @@ def _select_pending_test_jes(
 def _render_pending_je(doc: MdDoc, je: JobExecution, label: str) -> None:
     status_label = TestRunSummary.STATUS_LABEL.get(je.status, je.status)
     doc.heading(3, f"{label} — {status_label}")
-    doc.field("Job ID", je.id, code=True)
+    doc.field("Test Run", je.id, code=True)
     if je.job_schedule_id is not None:
         doc.field("Schedule", je.job_schedule_id, code=True)
     doc.field("Submitted", je.created_at)
@@ -289,7 +289,7 @@ def _render_pending_je(doc: MdDoc, je: JobExecution, label: str) -> None:
 def _render_test_run_section(doc: MdDoc, run: TestRunSummary) -> None:
     title = run.test_suite or run.project_code
     doc.heading(2, f"{title} — {run.status_label}")
-    doc.field("Job ID", run.job_execution_id, code=True)
+    doc.field("Test Run", run.job_execution_id, code=True)
     if run.job_schedule_id is not None:
         doc.field("Schedule", run.job_schedule_id, code=True)
     if run.test_suite:
diff --git a/testgen/server/__init__.py b/testgen/server/__init__.py
@@ -44,6 +44,11 @@ def _patch_openapi_schema(app: FastAPI) -> None:
     - Top-level component schema titles (shown in Redoc sidebar)
     - Path/query parameter schemas
 
+    It also strips ``description`` from enum component schemas. A ``StrEnum`` used
+    as a field type surfaces its class docstring as the schema description; enums
+    are internal primitives free to carry technical docstrings, so the public
+    schema must not echo them. Per-field API text comes from ``Field(description=...)``.
+
     FastAPI caches the schema after the first call, so the patching runs once.
     """
     _original = app.openapi
@@ -56,6 +61,8 @@ def patched_openapi() -> dict:
                 for branch in prop.get("anyOf", []):
                     branch.pop("title", None)
             model_schema.pop("title", None)
+            if "enum" in model_schema:
+                model_schema.pop("description", None)
         for methods in schema.get("paths", {}).values():
             for details in methods.values():
                 if isinstance(details, dict):
diff --git a/tests/unit/api/test_jobs.py b/tests/unit/api/test_jobs.py
