diff --git a/app_dart/lib/src/model/firestore/presubmit_guard.dart b/app_dart/lib/src/model/firestore/presubmit_guard.dart index 8f260d499..fbb62ffa8 100644 --- a/app_dart/lib/src/model/firestore/presubmit_guard.dart +++ b/app_dart/lib/src/model/firestore/presubmit_guard.dart @@ -44,6 +44,8 @@ final class PresubmitGuardId extends AppDocumentId { PresubmitGuard.metadata; } +/// For the Unified Check Run flow, this represents execution details of a +/// 'Dashboard Checks' GitHub check. final class PresubmitGuard extends AppDocument { static const collectionId = 'presubmit_guards'; static const fieldCheckRun = 'check_run'; diff --git a/app_dart/lib/src/model/firestore/presubmit_job.dart b/app_dart/lib/src/model/firestore/presubmit_job.dart index 0e50f10e9..f549e3f53 100644 --- a/app_dart/lib/src/model/firestore/presubmit_job.dart +++ b/app_dart/lib/src/model/firestore/presubmit_job.dart @@ -163,6 +163,8 @@ final class PresubmitJob extends AppDocument { return PresubmitJob.fromDocument(document); } + /// For the Unified Check Run flow, this represents information about + /// individual LUCI build execution. factory PresubmitJob({ required RepositorySlug slug, required int checkRunId, diff --git a/app_dart/lib/src/request_handlers/get_presubmit_guard.dart b/app_dart/lib/src/request_handlers/get_presubmit_guard.dart index ecc482de8..c0817c853 100644 --- a/app_dart/lib/src/request_handlers/get_presubmit_guard.dart +++ b/app_dart/lib/src/request_handlers/get_presubmit_guard.dart @@ -13,11 +13,49 @@ import '../../cocoon_service.dart'; import '../request_handling/public_api_request_handler.dart'; import '../service/firestore/unified_check_run.dart'; -/// Request handler for retrieving the aggregated presubmit guard status. +/// For the Unified Check Run flow, this handler returns aggregated execution +/// details of the 'Dashboard Checks' GitHub check for a commit. /// -/// This handler queries the presubmit guards for a specific commit SHA and -/// returns an aggregated response including the overall guard status and -/// individual stage statuses. +/// GET: /api/public/get-presubmit-guard +/// +/// Parameters: +/// sha: (string in query) mandatory. The GitHub Commit SHA. +/// repo: (string in query) optional. The repository name. Defaults to 'flutter'. +/// owner: (string in query) optional. The repository owner. Defaults to 'flutter'. +/// +/// Response: Status 200 OK +/// { +/// "pr_num": 181051, +/// "check_run_id": 82814077799, +/// "author": "ievdokdm", +/// "stages": [ +/// { +/// "name": "fusion", +/// "created_at": 1782162074809, +/// "jobs": { +/// "Linux web_canvaskit_tests_0": "Succeeded", +/// "Mac_arm64 build_tests_2_5": "Failed", +/// "Windows tool_integration_tests_5_10": "In progress", +/// "Linux web_canvaskit_tests_1": "Pending", +/// "Mac_arm64 build_tests_3_5": "Infra failure", +/// "Windows tool_integration_tests_7_10": "Cancelled", +/// "Windows tool_integration_tests_6_10": "New", +/// "Windows tool_integration_tests_9_10": "Skipped", +/// "Windows tool_integration_tests_8_10": "Neutral", +/// } +/// }, +/// { +/// "name": "engine", +/// "created_at": 1782160242084, +/// "jobs": { +/// "Linux windows_host_engine": "Succeeded", +/// "Linux web_host_engine": "Succeeded", +/// } +/// } +/// ], +/// "guard_status": "Failed", +/// "enable_gemini_log_analysis": true +/// } @immutable final class GetPresubmitGuard extends PublicApiRequestHandler { /// Defines the [GetPresubmitGuard] handler. diff --git a/app_dart/lib/src/request_handlers/get_presubmit_guard_summaries.dart b/app_dart/lib/src/request_handlers/get_presubmit_guard_summaries.dart index 16fc4a36a..4de918152 100644 --- a/app_dart/lib/src/request_handlers/get_presubmit_guard_summaries.dart +++ b/app_dart/lib/src/request_handlers/get_presubmit_guard_summaries.dart @@ -14,7 +14,8 @@ import '../../cocoon_service.dart'; import '../request_handling/public_api_request_handler.dart'; import '../service/firestore/unified_check_run.dart'; -/// Request handler for retrieving all presubmit guards for a specific pull request. +/// For the Unified Check Run flow, this handler retrieves aggregated execution +/// details about all 'Dashboard Checks' for a specific pull request. /// /// GET: /api/public/get-presubmit-guard-summaries /// @@ -22,6 +23,26 @@ import '../service/firestore/unified_check_run.dart'; /// repo: (string in query) required. The repository name (e.g., 'flutter'). /// pr: (int in query) required. The pull request number. /// owner: (string in query) optional. The repository owner (e.g., 'flutter'). +/// +/// Response: Status 200 OK +/// [ +/// { +/// "head_sha": "a2ef4ae497e588a4c6a1db741ed1b4602b77d084", +/// "creation_time": 1782160242084, +/// "guard_status": "Succeeded" +/// }, +/// { +/// "head_sha": "b1314384fe741a4a334792b5a520bb8d55077487", +/// "creation_time": 1781822988802, +/// "guard_status": "Failed" +/// } +/// ] +/// +/// Response: Status 400 Bad Request +/// { +/// "error": "No guards found for PR 123456 in flutter/flutter" +/// } +/// @immutable final class GetPresubmitGuardSummaries extends PublicApiRequestHandler { /// Defines the [GetPresubmitGuardSummaries] handler. diff --git a/app_dart/lib/src/request_handlers/get_presubmit_job.dart b/app_dart/lib/src/request_handlers/get_presubmit_job.dart index e2e42215f..ec0f7b981 100644 --- a/app_dart/lib/src/request_handlers/get_presubmit_job.dart +++ b/app_dart/lib/src/request_handlers/get_presubmit_job.dart @@ -11,15 +11,16 @@ import '../../cocoon_service.dart'; import '../request_handling/public_api_request_handler.dart'; import '../service/firestore/unified_check_run.dart'; -/// Returns all attempts for a specific presubmit job. +/// For the Unified Check Run flow, this API returns information about all +/// LUCI build executions for a specific ci.yaml recipe. /// /// GET: /api/public/get-presubmit-job /// /// Parameters: /// check_run_id: (int in query) mandatory. The GitHub Check Run ID. -/// job_name: (string in query) mandatory. The name of the job. -/// repo: (string in query) optional. The repository name. -/// owner: (string in query) optional. The repository owner. +/// job_name: (string in query) mandatory. The name of the ci.yaml recipe. +/// repo: (string in query) optional. The repository name. Defaults to 'flutter'. +/// owner: (string in query) optional. The repository owner. Defaults to 'flutter'. /// /// Response: Status 200 OK /// [