comments

app_dart/lib/src/model/firestore/presubmit_guard.dart

@@ -44,6 +44,8 @@ final class PresubmitGuardId extends AppDocumentId<PresubmitGuard> {
       PresubmitGuard.metadata;
 }
 
+/// For the Unified Check Run flow, this represents execution details of a
+/// 'Dashboard Checks' GitHub check.
 final class PresubmitGuard extends AppDocument<PresubmitGuard> {
   static const collectionId = 'presubmit_guards';
   static const fieldCheckRun = 'check_run';

app_dart/lib/src/model/firestore/presubmit_job.dart

@@ -163,6 +163,8 @@ final class PresubmitJob extends AppDocument<PresubmitJob> {
     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,

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.

app_dart/lib/src/request_handlers/get_presubmit_guard_summaries.dart

@@ -14,14 +14,35 @@ 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
 ///
 /// Parameters:
 ///   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.

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
 /// [