@opensoftware/contracts 1.0.0 → 1.5.0

package/openapi/openapi.json

@@ -2,14 +2,127 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.0.0",
-    "description": "The shared formats as named models. No operations: module APIs are added per module. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+    "version": "1.5.0",
+    "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
       "identifier": "Apache-2.0"
     }
   },
-  "paths": {},
+  "paths": {
+    "/v1/gates": {
+      "post": {
+        "operationId": "GatekeeperApi_requestGate",
+        "description": "Ask the policy's approver groups for a decision. The same request again answers the gate it made before.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GateRequest"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/gates/{gateId}": {
+      "get": {
+        "operationId": "GatekeeperApi_getGate",
+        "description": "A gate: its state, and its record once it is decided.",
+        "parameters": [
+          {
+            "name": "gateId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GateView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "BearerAuth": []
+    }
+  ],
   "components": {
     "schemas": {
       "Actor": {
@@ -101,6 +214,31 @@
         ],
         "additionalProperties": false
       },
+      "ApiProblem": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A short summary, the same for every occurrence of the problem."
+          },
+          "status": {
+            "type": "integer",
+            "minimum": -2147483648,
+            "maximum": 2147483647,
+            "description": "The HTTP status code."
+          },
+          "detail": {
+            "type": "string",
+            "description": "What went wrong this time, for example the field that is missing."
+          }
+        },
+        "required": [
+          "title",
+          "status"
+        ],
+        "description": "An error of an HTTP API (RFC 9457)."
+      },
       "Artifact": {
         "type": "object",
         "properties": {
@@ -489,6 +627,127 @@
           "expired"
         ]
       },
+      "GateRecord": {
+        "type": "object",
+        "properties": {
+          "gate": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$"
+          },
+          "workItem": {
+            "type": "string"
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "request": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$",
+            "description": "SHA-256 of the canonical request: what was approved."
+          },
+          "policy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The policy file."
+          },
+          "policyDigest": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$",
+            "description": "SHA-256 of the policy's text: the rules that picked the approvers."
+          },
+          "risk": {
+            "type": "string"
+          },
+          "approvers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            }
+          },
+          "channel": {
+            "type": "string"
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "decision": {
+            "$ref": "#/components/schemas/GateDecision"
+          },
+          "decidedBy": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "Who decided. Absent only when the gate expired. A policy that names no group decides as a trigger."
+          },
+          "decidedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "reason": {
+            "type": "string",
+            "description": "The reason of a rejection."
+          },
+          "signature": {
+            "$ref": "#/components/schemas/RecordSignature",
+            "description": "Ed25519 over the canonical JSON of the rest of the record. Absent when the record is unsigned."
+          }
+        },
+        "required": [
+          "gate",
+          "workItem",
+          "stage",
+          "summary",
+          "request",
+          "policy",
+          "policyDigest",
+          "approvers",
+          "channel",
+          "requestedAt",
+          "decision",
+          "decidedAt"
+        ],
+        "description": "gatekeeper: who decided what and when, signed with Ed25519 (ADR 0047)."
+      },
+      "GateRequest": {
+        "type": "object",
+        "properties": {
+          "workItem": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "What waits: a work item ID or a URL."
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The stage that waits, for example \"merge\"."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the approvers decide, shown in the channel."
+          },
+          "links": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Link"
+            }
+          },
+          "change": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {},
+            "description": "Any facts the policy needs, such as changed paths, labels or the author."
+          }
+        },
+        "required": [
+          "workItem",
+          "stage",
+          "summary"
+        ],
+        "description": "gatekeeper: what a person is asked to approve, and the facts the policy decides on (ADR 0047)."
+      },
       "GateRequested": {
         "type": "object",
         "properties": {
@@ -597,6 +856,91 @@
           "summary"
         ]
       },
+      "GateState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "approved",
+          "rejected",
+          "expired"
+        ],
+        "description": "A gate's state: waiting, or how it was decided."
+      },
+      "GateView": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$",
+            "description": "\"g\" and 16 hex digits of the SHA-256 of the work item, the stage and the change."
+          },
+          "workItem": {
+            "type": "string"
+          },
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "risk": {
+            "type": "string",
+            "description": "The risk the policy named, for example \"high\"."
+          },
+          "approvers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups whose members may decide. Empty when the policy approved without a person."
+          },
+          "escalateTo": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups asked after the escalation time."
+          },
+          "channel": {
+            "type": "string",
+            "description": "Where people decide, for example \"slack:C0GATES\"."
+          },
+          "state": {
+            "$ref": "#/components/schemas/GateState"
+          },
+          "waitingFor": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The groups that may decide now. Only while the gate is pending."
+          },
+          "requestedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "expiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the gate expires without a decision."
+          },
+          "record": {
+            "$ref": "#/components/schemas/GateRecord",
+            "description": "The record, once the gate is decided."
+          }
+        },
+        "required": [
+          "id",
+          "workItem",
+          "stage",
+          "summary",
+          "approvers",
+          "channel",
+          "state",
+          "requestedAt"
+        ],
+        "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
+      },
       "Identifier": {
         "type": "string",
         "minLength": 1,
@@ -644,6 +988,81 @@
           "source"
         ]
       },
+      "PrClosed": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "pr.closed@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/PrClosedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "forge adapters: a pull request was merged or closed without a merge."
+      },
+      "PrClosedData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The pull request."
+          },
+          "merged": {
+            "type": "boolean",
+            "description": "True when the pull request was merged, false when it was closed without a merge."
+          },
+          "mergeCommit": {
+            "$ref": "#/components/schemas/CommitHash"
+          }
+        },
+        "required": [
+          "url",
+          "merged"
+        ]
+      },
       "PrOpened": {
         "type": "object",
         "properties": {
@@ -747,6 +1166,85 @@
           "author"
         ]
       },
+      "PrReviewed": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "pr.reviewed@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/PrReviewedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "forge adapters: a person, an agent or a bot reviewed or commented on a pull request."
+      },
+      "PrReviewedData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The pull request."
+          },
+          "reviewer": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "automated": {
+            "type": "boolean",
+            "description": "True when an agent or a bot wrote the review, not a person."
+          },
+          "state": {
+            "$ref": "#/components/schemas/ReviewState"
+          }
+        },
+        "required": [
+          "url",
+          "reviewer",
+          "state"
+        ]
+      },
       "Priority": {
         "type": "string",
         "enum": [
@@ -843,6 +1341,38 @@
         "description": "The adapters a factory uses, per port (docs/architecture/internals.md). Keys are adapter names.",
         "additionalProperties": false
       },
+      "RecordSignature": {
+        "type": "object",
+        "properties": {
+          "algorithm": {
+            "type": "string",
+            "const": "Ed25519"
+          },
+          "key": {
+            "type": "string",
+            "pattern": "^sha256:",
+            "description": "SHA-256 of the public key in DER, like \"sha256:…\"."
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The signature in base64."
+          }
+        },
+        "required": [
+          "algorithm",
+          "key",
+          "value"
+        ]
+      },
+      "ReviewState": {
+        "type": "string",
+        "enum": [
+          "approved",
+          "changes_requested",
+          "commented"
+        ]
+      },
       "RunCompleted": {
         "type": "object",
         "properties": {
@@ -1548,6 +2078,12 @@
         ],
         "description": "intake: a work item was accepted."
       }
+    },
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "Bearer"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.0.0",
+  "version": "1.5.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -39,9 +39,12 @@
   "devDependencies": {
     "@asyncapi/parser": "3.6.6",
     "@typespec/compiler": "1.17.0",
+    "@typespec/http": "1.17.0",
     "@typespec/json-schema": "1.17.0",
+    "@typespec/openapi": "1.17.0",
+    "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.0.0"
+    "@opensoftware/testkit": "0.12.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/events.tsp

@@ -54,6 +54,12 @@ model ScoreRecorded is CloudEvent<"score.recorded@v1", Score>;
 /** forge adapters: the factory opened a pull request. */
 model PrOpened is CloudEvent<"pr.opened@v1", PrOpenedData>;
 
+/** forge adapters: a person, an agent or a bot reviewed or commented on a pull request. */
+model PrReviewed is CloudEvent<"pr.reviewed@v1", PrReviewedData>;
+
+/** forge adapters: a pull request was merged or closed without a merge. */
+model PrClosed is CloudEvent<"pr.closed@v1", PrClosedData>;
+
 model RunCompletedData {
   runId: Identifier;
   workItemId: Identifier;
@@ -132,3 +138,31 @@ model PrOpenedData {
   workItemId?: Identifier;
   runId?: Identifier;
 }
+
+enum ReviewState {
+  approved,
+  changes_requested,
+  commented,
+}
+
+model PrReviewedData {
+  /** The pull request. */
+  url: url;
+
+  reviewer: Actor;
+
+  /** True when an agent or a bot wrote the review, not a person. */
+  automated?: boolean;
+
+  state: ReviewState;
+}
+
+model PrClosedData {
+  /** The pull request. */
+  url: url;
+
+  /** True when the pull request was merged, false when it was closed without a merge. */
+  merged: boolean;
+
+  mergeCommit?: CommitHash;
+}