forges 0.0.0 → 0.1.0

package/dist/schema/ForgeCapabilities.json

@@ -0,0 +1,737 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Instance version the capabilities were computed for, when known."
+    },
+    "experimental": {
+      "type": "boolean",
+      "const": true,
+      "description": "The forge's API as a whole is unstable, so the provider can change with it."
+    },
+    "sources": {
+      "type": "object",
+      "properties": {
+        "poll": {
+          "$ref": "#/definitions/Support"
+        },
+        "webhook": {
+          "$ref": "#/definitions/Support"
+        },
+        "subscribe": {
+          "$ref": "#/definitions/Support"
+        }
+      },
+      "required": [
+        "poll",
+        "webhook",
+        "subscribe"
+      ],
+      "description": "`subscribe` is a long-lived push stream; see {@link SourcesApi}."
+    },
+    "repos": {
+      "type": "object",
+      "properties": {
+        "get": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.get()`."
+        },
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.list()` and `repos.listPage()`."
+        },
+        "labels": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.labels()` and `repos.labelsPage()`."
+        },
+        "createLabel": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.createLabel()`."
+        },
+        "milestones": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.milestones()` and `repos.milestonesPage()`."
+        },
+        "collaborators": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.collaborators()` and `repos.collaboratorsPage()`."
+        },
+        "permissionFor": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.permissionFor()`."
+        },
+        "addCollaborator": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.addCollaborator()`."
+        },
+        "assignableUsers": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.assignableUsers()` and `repos.assignableUsersPage()`."
+        },
+        "reviewerCandidates": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `repos.reviewerCandidates()` and `repos.reviewerCandidatesPage()`."
+        }
+      },
+      "required": [
+        "get",
+        "list",
+        "labels",
+        "createLabel",
+        "milestones",
+        "collaborators",
+        "permissionFor",
+        "addCollaborator",
+        "assignableUsers",
+        "reviewerCandidates"
+      ]
+    },
+    "users": {
+      "type": "object",
+      "properties": {
+        "get": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `users.get()`."
+        },
+        "me": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `users.me()`."
+        }
+      },
+      "required": [
+        "get",
+        "me"
+      ]
+    },
+    "threads": {
+      "type": "object",
+      "properties": {
+        "get": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.get()`, per thread kind."
+        },
+        "list": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.list()` and `threads.listPage()`, per thread kind."
+        },
+        "getMany": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.getMany()`."
+        },
+        "events": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.events()` and `threads.eventsPage()`, per thread kind."
+        }
+      },
+      "required": [
+        "get",
+        "list",
+        "getMany",
+        "events"
+      ]
+    },
+    "comments": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.comments()` and `threads.commentsPage()`, per thread kind."
+        },
+        "edit": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.editComment()`, per thread kind."
+        },
+        "delete": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.deleteComment()`, per thread kind."
+        }
+      },
+      "required": [
+        "list",
+        "edit",
+        "delete"
+      ]
+    },
+    "reactions": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.reactions()` and `threads.reactionsPage()`, per thread kind."
+        }
+      },
+      "required": [
+        "list"
+      ],
+      "description": "Listing the reactions on a thread or one of its comments, per thread kind."
+    },
+    "notifications": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.list()` and `notifications.listPage()`."
+        },
+        "markRead": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.markRead()`."
+        },
+        "markDone": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.markDone()`."
+        },
+        "unsubscribe": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.unsubscribe()`."
+        },
+        "markAllRead": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.markAllRead()`."
+        },
+        "markAllDone": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.markAllDone()`."
+        },
+        "unreadCount": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `notifications.unreadCount()`."
+        }
+      },
+      "required": [
+        "list",
+        "markRead",
+        "markDone",
+        "unsubscribe",
+        "markAllRead",
+        "markAllDone",
+        "unreadCount"
+      ]
+    },
+    "writes": {
+      "type": "object",
+      "properties": {
+        "comment": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.comment()`, per thread kind."
+        },
+        "upsertComment": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Composed from `comment`, `comments.list` and `comments.edit`, so `'emulated'` where it works at all, or `'unverified'` where a part is."
+        },
+        "close": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.close()`, per thread kind."
+        },
+        "reopen": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.reopen()`, per thread kind."
+        },
+        "create": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.create()`, per thread kind."
+        },
+        "update": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.update()`, per thread kind."
+        },
+        "setLabels": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.setLabels()`, per thread kind."
+        },
+        "addLabels": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.addLabels()`, per thread kind."
+        },
+        "removeLabels": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.removeLabels()`, per thread kind."
+        },
+        "setMilestone": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.setMilestone()`, per thread kind."
+        },
+        "react": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.react()` and `threads.unreact()`, per thread kind."
+        },
+        "setAssignees": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.setAssignees()`, per thread kind."
+        },
+        "requestReview": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.requestReview()`, per thread kind."
+        },
+        "merge": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.merge()`."
+        },
+        "approveAndMerge": {
+          "$ref": "#/definitions/Support",
+          "description": "Composed from `merge` and `reviews.approve`."
+        },
+        "transfer": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.transfer()`."
+        },
+        "markDuplicate": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.markDuplicate()`."
+        }
+      },
+      "required": [
+        "comment",
+        "upsertComment",
+        "close",
+        "reopen",
+        "create",
+        "update",
+        "setLabels",
+        "addLabels",
+        "removeLabels",
+        "setMilestone",
+        "react",
+        "setAssignees",
+        "requestReview",
+        "merge",
+        "approveAndMerge",
+        "transfer",
+        "markDuplicate"
+      ],
+      "description": "Write verbs, per thread kind except `merge`, `approveAndMerge`, `transfer` and `markDuplicate`."
+    },
+    "subscriptions": {
+      "type": "object",
+      "properties": {
+        "get": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.subscription()`, per thread kind."
+        },
+        "set": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.subscribe()` and `threads.unsubscribe()`, per thread kind."
+        }
+      },
+      "required": [
+        "get",
+        "set"
+      ],
+      "description": "Reading a thread subscription (`get`) and changing it (`set`), per kind. Distinct from notification unsubscribe."
+    },
+    "checks": {
+      "type": "object",
+      "properties": {
+        "thread": {
+          "$ref": "#/definitions/PerKind",
+          "description": "Support for `threads.checks()`, per thread kind."
+        },
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `checks.list()`."
+        },
+        "report": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `checks.report()`."
+        },
+        "rerun": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `checks.rerun()`."
+        }
+      },
+      "required": [
+        "thread",
+        "list",
+        "report",
+        "rerun"
+      ],
+      "description": "`thread` covers `Thread.checks` and `threads.checks()` (pull requests only); the rest are the commit-level surface. `report` is a commit status unless the credential can write check runs."
+    },
+    "ci": {
+      "type": "object",
+      "properties": {
+        "runs": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `ci.runs()` and `ci.runsPage()`."
+        },
+        "run": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `ci.run()`."
+        },
+        "jobs": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `ci.jobs()` and `ci.jobsPage()`."
+        },
+        "log": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `ci.log()`."
+        }
+      },
+      "required": [
+        "runs",
+        "run",
+        "jobs",
+        "log"
+      ],
+      "description": "Read-only CI surface. `log` is `false` where job logs are not reachable over the API."
+    },
+    "reviews": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.reviews()` and `threads.reviewsPage()`."
+        },
+        "create": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.createReview()`."
+        },
+        "submit": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.submitReview()`."
+        },
+        "approve": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.approve()`."
+        },
+        "resolveThread": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.resolveReviewThread()` and `threads.unresolveReviewThread()`."
+        }
+      },
+      "required": [
+        "list",
+        "create",
+        "submit",
+        "approve",
+        "resolveThread"
+      ],
+      "description": "Reviews on a pull request. `list` is `'emulated'` where reviews are synthesised from approvals or votes; `create` then covers only the events the forge's approval endpoint can express."
+    },
+    "contents": {
+      "type": "object",
+      "properties": {
+        "file": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.file()`."
+        },
+        "tree": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.tree()` and `contents.treePage()`."
+        },
+        "branches": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.branches()` and `contents.branchesPage()`."
+        },
+        "tags": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.tags()` and `contents.tagsPage()`."
+        },
+        "resolveRef": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.resolveRef()`."
+        },
+        "commits": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.commits()` and `contents.commitsPage()`."
+        },
+        "commit": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.commit()`."
+        },
+        "compare": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `contents.compare()`."
+        },
+        "threadFiles": {
+          "$ref": "#/definitions/Support",
+          "description": "`threads.files` and `threads.commits` on a pull request."
+        },
+        "threadCommits": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `threads.commits()` and `threads.commitsPage()`."
+        }
+      },
+      "required": [
+        "file",
+        "tree",
+        "branches",
+        "tags",
+        "resolveRef",
+        "commits",
+        "commit",
+        "compare",
+        "threadFiles",
+        "threadCommits"
+      ],
+      "description": "Repository contents. `tree` is `'emulated'` where recursion is walked level by level rather than by the forge."
+    },
+    "webhooks": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.list()` and `webhooks.listPage()`."
+        },
+        "create": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.create()`."
+        },
+        "update": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.update()`."
+        },
+        "delete": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.delete()`."
+        },
+        "rotateSecret": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.rotateSecret()`."
+        },
+        "deliveries": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.deliveries()` and `webhooks.deliveriesPage()`."
+        },
+        "redeliver": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `webhooks.redeliver()`."
+        }
+      },
+      "required": [
+        "list",
+        "create",
+        "update",
+        "delete",
+        "rotateSecret",
+        "deliveries",
+        "redeliver"
+      ],
+      "description": "Managing registered webhooks, beside receiving deliveries."
+    },
+    "releases": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.list()` and `releases.listPage()`."
+        },
+        "get": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.get()`."
+        },
+        "latest": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.latest()`."
+        },
+        "getByTag": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.getByTag()`."
+        },
+        "downloadAsset": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.downloadAsset()`."
+        },
+        "create": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.create()`."
+        },
+        "update": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `releases.update()`."
+        }
+      },
+      "required": [
+        "list",
+        "get",
+        "latest",
+        "getByTag",
+        "downloadAsset",
+        "create",
+        "update"
+      ]
+    },
+    "search": {
+      "type": "object",
+      "properties": {
+        "threads": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `search.threads()` and `search.threadsPage()`."
+        },
+        "repos": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `search.repos()` and `search.reposPage()`."
+        },
+        "commits": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `search.commits()` and `search.commitsPage()`."
+        },
+        "code": {
+          "$ref": "#/definitions/Support",
+          "description": "Support for `search.code()` and `search.codePage()`."
+        }
+      },
+      "required": [
+        "threads",
+        "repos",
+        "commits",
+        "code"
+      ],
+      "description": "Cross-repository search of issues and pull requests, repositories, commits and code."
+    },
+    "securityAlerts": {
+      "$ref": "#/definitions/AlertSupport",
+      "description": "Per alert kind, since each needs its own token scope on GitHub."
+    },
+    "installations": {
+      "$ref": "#/definitions/Support",
+      "description": "Enumerating app installations and deriving one provider per installation."
+    },
+    "eventKinds": {
+      "type": "string",
+      "enum": [
+        "native",
+        "heuristic"
+      ],
+      "description": "`'heuristic'` when event kinds are inferred from free text (GitLab system notes) rather than reported by the forge, so `kind` may be `'other'` or wrong for unrecognised wording; `kindRaw` and `payload` stay exact."
+    },
+    "authKinds": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/AuthKind"
+      },
+      "description": "Auth types the provider accepts. The type this provider was created with is `ForgeProvider.authKind`."
+    },
+    "limits": {
+      "$ref": "#/definitions/TextLimits",
+      "description": "Maximum text lengths the forge accepts."
+    }
+  },
+  "required": [
+    "sources",
+    "repos",
+    "users",
+    "threads",
+    "comments",
+    "reactions",
+    "notifications",
+    "writes",
+    "subscriptions",
+    "checks",
+    "ci",
+    "reviews",
+    "contents",
+    "webhooks",
+    "releases",
+    "search",
+    "securityAlerts",
+    "installations",
+    "eventKinds",
+    "authKinds"
+  ],
+  "description": "What a provider supports, operation by operation. It is computed without a request, and `refreshCapabilities()` refines it with the instance version. Each group holds one entry per capability, and the [capability matrix](/reference/capability-matrix) lists them for every forge.",
+  "x-forges-type": "ForgeCapabilities",
+  "definitions": {
+    "AlertSupport": {
+      "type": "object",
+      "properties": {
+        "dependency": {
+          "$ref": "#/definitions/Support"
+        },
+        "code_scanning": {
+          "$ref": "#/definitions/Support"
+        },
+        "secret": {
+          "$ref": "#/definitions/Support"
+        },
+        "advisory": {
+          "$ref": "#/definitions/Support"
+        }
+      },
+      "required": [
+        "dependency",
+        "code_scanning",
+        "secret",
+        "advisory"
+      ],
+      "description": "Support per security alert kind.",
+      "x-forges-type": "AlertSupport"
+    },
+    "AuthKind": {
+      "type": "string",
+      "enum": [
+        "token",
+        "basic",
+        "app",
+        "app_password",
+        "oauth",
+        "anonymous"
+      ],
+      "description": "The credential types that a provider can accept.",
+      "x-forges-type": "AuthKind"
+    },
+    "PerKind": {
+      "type": "object",
+      "properties": {
+        "issue": {
+          "$ref": "#/definitions/Support"
+        },
+        "pull_request": {
+          "$ref": "#/definitions/Support"
+        },
+        "discussion": {
+          "$ref": "#/definitions/Support"
+        },
+        "commit": {
+          "$ref": "#/definitions/Support"
+        }
+      },
+      "required": [
+        "issue",
+        "pull_request",
+        "discussion",
+        "commit"
+      ],
+      "description": "Per-thread-kind support. `'other'` subjects have no verbs, so they have no entry.",
+      "x-forges-type": "PerKind"
+    },
+    "Support": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "const": "emulated"
+        },
+        {
+          "type": "string",
+          "const": "experimental"
+        },
+        {
+          "type": "string",
+          "const": "unverified"
+        }
+      ],
+      "description": "Capability flag. Every value other than `false` means the operation is available:\n\n- `true`: native, and verified against the forge's responses.\n- `'experimental'`: native and verified, but built on an API the forge marks unstable, so it can change.\n- `'emulated'`: composed from other calls, so the result is approximate.\n- `'unverified'`: implemented, but not yet verified against the forge's responses, so it may not work.",
+      "x-forges-type": "Support"
+    },
+    "TextLimits": {
+      "type": "object",
+      "properties": {
+        "bodyLength": {
+          "type": "number"
+        },
+        "commentLength": {
+          "type": "number"
+        },
+        "labelLength": {
+          "type": "number"
+        }
+      },
+      "description": "Maximum lengths the forge accepts, in characters.",
+      "x-forges-type": "TextLimits"
+    }
+  }
+}