Sync the revision scan public contract

openapi.public.json

@@ -5991,6 +5991,68 @@
         ],
         "type": "object"
       },
+      "ScanRequestBody": {
+        "additionalProperties": false,
+        "description": "One request to scan a ref or an exact commit of the repository.",
+        "properties": {
+          "budget_credits": {
+            "description": "The credits the whole scan may spend, at most the organization's\n on-demand ceiling.",
+            "format": "int64",
+            "type": "integer"
+          },
+          "commit_sha": {
+            "description": "An exact commit. Name it or `ref`.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "ref": {
+            "description": "A ref, resolved once when the request arrives. Name it or `commit_sha`.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "request_id": {
+            "description": "The caller's identity for this request. Sending it again returns the\n first resolution instead of scanning again.",
+            "format": "uuid",
+            "type": "string"
+          }
+        },
+        "required": [
+          "request_id",
+          "budget_credits"
+        ],
+        "type": "object"
+      },
+      "ScanResponse": {
+        "description": "What a scan request resolved to.",
+        "properties": {
+          "outcome": {
+            "description": "`CREATED`, `EXISTING` when this request id was already resolved, or\n `REPOSITORY_UNAVAILABLE` when GitHub could not resolve it.",
+            "type": "string"
+          },
+          "resolution_id": {
+            "description": "The request's one resolution receipt.",
+            "format": "uuid",
+            "type": "string"
+          },
+          "review_id": {
+            "description": "The scan review, readable through the review routes. Absent when\n GitHub could not resolve the request.",
+            "format": "uuid",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "resolution_id",
+          "outcome"
+        ],
+        "type": "object"
+      },
       "SpecialistAssessmentExecution": {
         "properties": {
           "assessment_id": {
@@ -7596,6 +7658,84 @@
         "x-proofline-token-scope": "guidance:read"
       }
     },
+    "/api/v1/organizations/{org_id}/repositories/{repo_id}/scans": {
+      "post": {
+        "description": "Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and records that resolution. Requires live GitHub write access, and `budget_credits` at most the organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same `request_id` again returns the first resolution. Results remain in Proofline and are never posted to GitHub.",
+        "operationId": "request_scan",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "org_id",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "style": "simple"
+          },
+          {
+            "in": "path",
+            "name": "repo_id",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "style": "simple"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScanRequestBody"
+              }
+            }
+          },
+          "description": "One request to scan a ref or an exact commit of the repository.",
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ScanResponse"
+                }
+              }
+            },
+            "description": "What a scan request resolved to."
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunNowRefused"
+                }
+              }
+            },
+            "description": "A run-now request that created nothing, as the 400 it is answered with.\n\n The refusal is a configuration fact, not a failure, and it is still sent\n as an RFC 9457 problem: `title`, `status` and `detail` are what a client\n that knows only problems shows, and `repository_name` and `refusal` are\n the extension members a client that knows refusals links from. During a\n rollout a page loaded from the previous bundle keeps working against\n this server, because a refusal was a 400 with a `detail` before too."
+          },
+          "default": {
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Problem"
+                }
+              }
+            },
+            "description": "An RFC 9457 problem; the HTTP status remains authoritative."
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "summary": "Scan a repository revision",
+        "x-proofline-token-scope": "scans:request"
+      }
+    },
     "/api/v1/organizations/{org_id}/repository-names": {
       "get": {
         "description": "Returns the ID and full name of each connected repository inside the token's repository restriction, including repositories with no review, so a client can resolve `owner/name` to an ID.",

proofline/__init__.py

@@ -25,6 +25,8 @@
     RunNowMode,
     RunNowRequest,
     RunNowResponse,
+    ScanRequestBody,
+    ScanResponse,
     StartSession,
     StopResponse,
     UploadedReport,
@@ -67,6 +69,8 @@
     "RunNowMode",
     "RunNowRequest",
     "RunNowResponse",
+    "ScanRequestBody",
+    "ScanResponse",
     "SecretStr",
     "StartSession",
     "StopResponse",

proofline/_generated/api/default/request_scan.py

@@ -0,0 +1,220 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from ...client import AuthenticatedClient, Client
+from ...models.problem import Problem
+from ...models.run_now_refused import RunNowRefused
+from ...models.scan_request_body import ScanRequestBody
+from ...models.scan_response import ScanResponse
+from ...types import Response
+
+
+def _get_kwargs(
+    org_id: UUID,
+    repo_id: UUID,
+    *,
+    body: ScanRequestBody,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/api/v1/organizations/{org_id}/repositories/{repo_id}/scans".format(
+            org_id=quote(str(org_id), safe=""),
+            repo_id=quote(str(repo_id), safe=""),
+        ),
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Problem | RunNowRefused | ScanResponse:
+    if response.status_code == 200:
+        response_200 = ScanResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = RunNowRefused.from_dict(response.json())
+
+        return response_400
+
+    response_default = Problem.from_dict(response.json())
+
+    return response_default
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Problem | RunNowRefused | ScanResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    org_id: UUID,
+    repo_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: ScanRequestBody,
+) -> Response[Problem | RunNowRefused | ScanResponse]:
+    """Scan a repository revision
+
+     Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and
+    records that resolution. Requires live GitHub write access, and `budget_credits` at most the
+    organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same
+    `request_id` again returns the first resolution. Results remain in Proofline and are never posted to
+    GitHub.
+
+    Args:
+        org_id (UUID):
+        repo_id (UUID):
+        body (ScanRequestBody): One request to scan a ref or an exact commit of the repository.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Problem | RunNowRefused | ScanResponse]
+    """
+
+    kwargs = _get_kwargs(
+        org_id=org_id,
+        repo_id=repo_id,
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    org_id: UUID,
+    repo_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: ScanRequestBody,
+) -> Problem | RunNowRefused | ScanResponse | None:
+    """Scan a repository revision
+
+     Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and
+    records that resolution. Requires live GitHub write access, and `budget_credits` at most the
+    organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same
+    `request_id` again returns the first resolution. Results remain in Proofline and are never posted to
+    GitHub.
+
+    Args:
+        org_id (UUID):
+        repo_id (UUID):
+        body (ScanRequestBody): One request to scan a ref or an exact commit of the repository.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Problem | RunNowRefused | ScanResponse
+    """
+
+    return sync_detailed(
+        org_id=org_id,
+        repo_id=repo_id,
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    org_id: UUID,
+    repo_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: ScanRequestBody,
+) -> Response[Problem | RunNowRefused | ScanResponse]:
+    """Scan a repository revision
+
+     Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and
+    records that resolution. Requires live GitHub write access, and `budget_credits` at most the
+    organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same
+    `request_id` again returns the first resolution. Results remain in Proofline and are never posted to
+    GitHub.
+
+    Args:
+        org_id (UUID):
+        repo_id (UUID):
+        body (ScanRequestBody): One request to scan a ref or an exact commit of the repository.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Problem | RunNowRefused | ScanResponse]
+    """
+
+    kwargs = _get_kwargs(
+        org_id=org_id,
+        repo_id=repo_id,
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    org_id: UUID,
+    repo_id: UUID,
+    *,
+    client: AuthenticatedClient,
+    body: ScanRequestBody,
+) -> Problem | RunNowRefused | ScanResponse | None:
+    """Scan a repository revision
+
+     Scans the whole repository at one commit, resolved once from `ref` or named by `commit_sha`, and
+    records that resolution. Requires live GitHub write access, and `budget_credits` at most the
+    organization's on-demand scan limit; a limit of 0 turns on-demand scans off. Sending the same
+    `request_id` again returns the first resolution. Results remain in Proofline and are never posted to
+    GitHub.
+
+    Args:
+        org_id (UUID):
+        repo_id (UUID):
+        body (ScanRequestBody): One request to scan a ref or an exact commit of the repository.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Problem | RunNowRefused | ScanResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            org_id=org_id,
+            repo_id=repo_id,
+            client=client,
+            body=body,
+        )
+    ).parsed