From 7af2c055b151841ff509003971391e66430520d6 Mon Sep 17 00:00:00 2001 From: Dmitry Grand Date: Mon, 29 Jun 2026 13:28:48 -0700 Subject: [PATCH 1/2] comments --- .../src/model/firestore/presubmit_guard.dart | 2 + .../src/model/firestore/presubmit_job.dart | 2 + .../request_handlers/get_presubmit_guard.dart | 46 +++++++++++++++++-- .../get_presubmit_guard_summaries.dart | 23 +++++++++- .../request_handlers/get_presubmit_job.dart | 9 ++-- 5 files changed, 73 insertions(+), 9 deletions(-) diff --git a/app_dart/lib/src/model/firestore/presubmit_guard.dart b/app_dart/lib/src/model/firestore/presubmit_guard.dart index 8f260d4994..fbb62ffa83 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 0e50f10e9c..f549e3f53a 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 ecc482de87..fb4c21d3d2 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: +/// commit_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 16fc4a36ad..4de9181525 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 e2e42215ff..ec0f7b981d 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 /// [ From 211c392e3b6bdd35187ffc19c59ccb814c02df73 Mon Sep 17 00:00:00 2001 From: Dmitry Grand Date: Mon, 29 Jun 2026 13:36:09 -0700 Subject: [PATCH 2/2] fixes --- app_dart/lib/src/request_handlers/get_presubmit_guard.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fb4c21d3d2..c0817c853f 100644 --- a/app_dart/lib/src/request_handlers/get_presubmit_guard.dart +++ b/app_dart/lib/src/request_handlers/get_presubmit_guard.dart @@ -19,7 +19,7 @@ import '../service/firestore/unified_check_run.dart'; /// GET: /api/public/get-presubmit-guard /// /// Parameters: -/// commit_sha: (string in query) mandatory. The GitHub Commit SHA. +/// 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'. ///