forges 0.0.0 → 0.1.0

package/dist/schema/Thread.json

@@ -0,0 +1,653 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/ThreadRef"
+    },
+    "kind": {
+      "$ref": "#/definitions/ThreadKind"
+    },
+    "title": {
+      "type": "string"
+    },
+    "body": {
+      "type": "string"
+    },
+    "state": {
+      "$ref": "#/definitions/ThreadState"
+    },
+    "stateRaw": {
+      "type": "string",
+      "description": "Forge-native state string the normalised `state` was derived from."
+    },
+    "stateReason": {
+      "type": "string",
+      "description": "Forge-native state qualifier, for example `completed` or `not_planned`."
+    },
+    "isDraft": {
+      "type": "boolean"
+    },
+    "author": {
+      "$ref": "#/definitions/Actor"
+    },
+    "assignees": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Actor"
+      }
+    },
+    "reviewers": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Reviewer"
+      },
+      "description": "Reviewers the thread read reports. Some forges report outstanding requests only, others each reviewer's verdict; `threads.reviews()` has every submitted review."
+    },
+    "labels": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Label"
+      }
+    },
+    "url": {
+      "type": "string"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "closedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "lastActivityAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Latest activity the forge reports for the thread."
+    },
+    "locked": {
+      "type": "boolean"
+    },
+    "commentCount": {
+      "type": "number"
+    },
+    "participants": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Actor"
+      },
+      "description": "Everyone who authored or commented on the thread, where the forge reports them."
+    },
+    "readState": {
+      "type": "string",
+      "enum": [
+        "read",
+        "unread"
+      ],
+      "description": "Whether the authenticated account has read the thread, where the forge tracks it per thread."
+    },
+    "subscription": {
+      "$ref": "#/definitions/SubscriptionState",
+      "description": "The authenticated account's subscription, where the thread read already carries it."
+    },
+    "milestone": {
+      "$ref": "#/definitions/Milestone"
+    },
+    "reactions": {
+      "$ref": "#/definitions/ReactionSummary"
+    },
+    "branches": {
+      "$ref": "#/definitions/PullBranches",
+      "description": "Pull requests only."
+    },
+    "checks": {
+      "$ref": "#/definitions/ChecksSummary",
+      "description": "Pull requests only."
+    },
+    "stack": {
+      "$ref": "#/definitions/ThreadStack",
+      "description": "Pull requests in a stack: a chain of dependent pull requests, each based on the one before."
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ForgeWarning"
+      },
+      "description": "Non-fatal problems hit while reading the thread, for example an unreachable record."
+    },
+    "raw": {
+      "description": "Unnormalised forge payload, retained for fidelity."
+    }
+  },
+  "required": [
+    "ref",
+    "kind",
+    "title",
+    "state",
+    "isDraft",
+    "assignees",
+    "reviewers",
+    "labels",
+    "raw"
+  ],
+  "description": "An issue, pull request, discussion or commit conversation.",
+  "x-forges-type": "Thread",
+  "definitions": {
+    "Actor": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "login": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "avatarUrl": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "typeRaw": {
+          "type": "string",
+          "description": "Forge-reported account type, retained verbatim for callers that classify further."
+        },
+        "isBotHint": {
+          "type": "boolean",
+          "description": "Hint derived from forge metadata that the actor is automation. Callers own the classification policy."
+        },
+        "app": {
+          "type": "object",
+          "properties": {
+            "slug": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "slug"
+          ],
+          "description": "The app behind a bot account, where the forge ties one to it (GitHub Apps' `slug[bot]` users)."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "isBotHint",
+        "login"
+      ],
+      "description": "An account: a user, an organisation or a bot.",
+      "x-forges-type": "Actor"
+    },
+    "ChecksSummary": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "success",
+            "failure",
+            "unknown"
+          ]
+        },
+        "stateRaw": {
+          "type": "string"
+        },
+        "total": {
+          "type": "number",
+          "description": "Absent when the forge reports only a combined state."
+        },
+        "failed": {
+          "type": "number"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "state"
+      ],
+      "description": "Combined state of the checks on a pull request's head commit. `failure` when any check failed, else `pending` while any runs, else `success`.",
+      "x-forges-type": "ChecksSummary"
+    },
+    "ForgeInstance": {
+      "type": "string",
+      "description": "Host of a single forge deployment, for example `github.com` or `codeberg.org`.",
+      "x-forges-type": "ForgeInstance"
+    },
+    "ForgeKind": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/KnownForgeKind"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Identifier of a forge implementation. Unknown forges are permitted so that third-party providers can be registered without a core release.",
+      "x-forges-type": "ForgeKind"
+    },
+    "ForgeWarning": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "$ref": "#/definitions/ForgeWarningCode",
+          "description": "Stable machine-readable code."
+        },
+        "message": {
+          "type": "string",
+          "description": "A description of the problem, for a person."
+        },
+        "subject": {
+          "type": "string",
+          "description": "Key or URI of the item the warning concerns, when it concerns one."
+        },
+        "cause": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "status": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "name",
+            "message"
+          ]
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "description": "A non-fatal problem encountered while producing a result.",
+      "x-forges-type": "ForgeWarning"
+    },
+    "ForgeWarningCode": {
+      "type": "string",
+      "description": "The warning codes providers emit; providers may add codes in a minor release.",
+      "x-forges-type": "ForgeWarningCode"
+    },
+    "KnownForgeKind": {
+      "type": "string",
+      "enum": [
+        "github",
+        "gitlab",
+        "bitbucket",
+        "forgejo",
+        "gitea",
+        "tangled",
+        "gitee",
+        "azure-devops",
+        "cursor-origin",
+        "pushin"
+      ],
+      "description": "The forges this package ships providers for.",
+      "x-forges-type": "KnownForgeKind"
+    },
+    "Label": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "colour": {
+          "type": "string",
+          "description": "The colour as hex digits, without a leading `#`."
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "description": "A label that a repository defines.",
+      "x-forges-type": "Label"
+    },
+    "Milestone": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Forge-native milestone id, as `threads.setMilestone` takes it."
+        },
+        "title": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "open",
+            "closed"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "dueOn": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "url": {
+          "type": "string"
+        },
+        "raw": {}
+      },
+      "required": [
+        "id",
+        "title",
+        "state",
+        "raw"
+      ],
+      "description": "A milestone that groups threads.",
+      "x-forges-type": "Milestone"
+    },
+    "PullBranches": {
+      "type": "object",
+      "properties": {
+        "head": {
+          "type": "object",
+          "properties": {
+            "ref": {
+              "type": "string"
+            },
+            "sha": {
+              "type": "string"
+            },
+            "repo": {
+              "$ref": "#/definitions/RepoRef",
+              "description": "The repository that holds the head branch, which differs for a fork."
+            }
+          },
+          "required": [
+            "ref"
+          ],
+          "description": "`sha` is absent on forges where a pull is a patch rather than a branch (Tangled)."
+        },
+        "base": {
+          "type": "object",
+          "properties": {
+            "ref": {
+              "type": "string"
+            },
+            "sha": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "ref"
+          ]
+        },
+        "mergeCommitSha": {
+          "type": "string",
+          "description": "The merge commit, once the pull request is merged."
+        }
+      },
+      "required": [
+        "head",
+        "base"
+      ],
+      "description": "The branches of a pull request.",
+      "x-forges-type": "PullBranches"
+    },
+    "ReactionContent": {
+      "type": "string",
+      "enum": [
+        "+1",
+        "-1",
+        "laugh",
+        "confused",
+        "heart",
+        "hooray",
+        "rocket",
+        "eyes"
+      ],
+      "description": "The reactions every forge with reactions has in common, named as GitHub names them. A {@link Reaction} whose forge-native name has no entry here has `content: 'other'`, with the forge-native name in `contentRaw`.",
+      "x-forges-type": "ReactionContent"
+    },
+    "ReactionSummary": {
+      "type": "object",
+      "properties": {
+        "total": {
+          "type": "number",
+          "description": "The number of reactions of every kind."
+        },
+        "counts": {
+          "type": "object",
+          "properties": {
+            "+1": {
+              "type": "number"
+            },
+            "-1": {
+              "type": "number"
+            },
+            "laugh": {
+              "type": "number"
+            },
+            "confused": {
+              "type": "number"
+            },
+            "heart": {
+              "type": "number"
+            },
+            "hooray": {
+              "type": "number"
+            },
+            "rocket": {
+              "type": "number"
+            },
+            "eyes": {
+              "type": "number"
+            }
+          },
+          "description": "The number of reactions of each kind. A reaction with no {@link ReactionContent} entry has no key here."
+        },
+        "viewerReacted": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ReactionContent"
+          },
+          "description": "Reactions the authenticated account has left. Absent when the forge does not report them."
+        }
+      },
+      "required": [
+        "total",
+        "counts"
+      ],
+      "description": "The reactions on a thread or comment, counted.",
+      "x-forges-type": "ReactionSummary"
+    },
+    "RepoRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "owner": {
+          "type": "string",
+          "description": "Full namespace path. On forges with nested groups (GitLab) this contains slashes, for example `acme/platform`; `name` never does."
+        },
+        "name": {
+          "type": "string",
+          "description": "Repository name. Empty for namespace-scoped refs."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "repo",
+            "namespace"
+          ],
+          "description": "`'namespace'` for subjects that belong to a group rather than a repository (GitLab epics). Absent means a repository."
+        },
+        "externalId": {
+          "type": "string",
+          "description": "Stable forge-native identifier that survives renames and transfers: a GitHub, Forgejo or Gitea numeric id, a GitLab project or group id, a Bitbucket UUID or a Tangled repo DID. {@link repoKey} prefers it over `owner` and `name`."
+        }
+      },
+      "required": [
+        "forge",
+        "instance",
+        "name",
+        "owner"
+      ],
+      "description": "Addresses a repository by its forge, instance, owner and name.",
+      "x-forges-type": "RepoRef"
+    },
+    "ReviewState": {
+      "type": "string",
+      "enum": [
+        "approved",
+        "changes_requested",
+        "commented",
+        "pending",
+        "dismissed",
+        "unknown"
+      ],
+      "description": "What a review or a reviewer says about a pull request. `unknown` is a state that the model does not name.",
+      "x-forges-type": "ReviewState"
+    },
+    "Reviewer": {
+      "type": "object",
+      "properties": {
+        "actor": {
+          "$ref": "#/definitions/Actor"
+        },
+        "state": {
+          "$ref": "#/definitions/ReviewState"
+        },
+        "stateRaw": {
+          "type": "string"
+        },
+        "isTeam": {
+          "type": "boolean",
+          "description": "True when the reviewer is a team rather than an account."
+        }
+      },
+      "required": [
+        "actor",
+        "state"
+      ],
+      "description": "A reviewer who was asked to review a pull request, and what they said.",
+      "x-forges-type": "Reviewer"
+    },
+    "SubscriptionState": {
+      "type": "string",
+      "enum": [
+        "subscribed",
+        "ignored",
+        "none"
+      ],
+      "description": "Whether the account gets notifications for a thread.",
+      "x-forges-type": "SubscriptionState"
+    },
+    "ThreadKind": {
+      "type": "string",
+      "enum": [
+        "issue",
+        "pull_request",
+        "discussion",
+        "commit",
+        "other"
+      ],
+      "description": "Kind of thread. `'other'` holds forge-specific subjects with no shared kind (check suites, epics); `ThreadRef.typeRaw` names them.",
+      "x-forges-type": "ThreadKind"
+    },
+    "ThreadRef": {
+      "type": "object",
+      "properties": {
+        "forge": {
+          "$ref": "#/definitions/ForgeKind"
+        },
+        "instance": {
+          "$ref": "#/definitions/ForgeInstance",
+          "description": "The host of the instance, such as `github.com` or `git.example.com`."
+        },
+        "repo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "kind": {
+          "$ref": "#/definitions/ThreadKind"
+        },
+        "typeRaw": {
+          "type": "string",
+          "description": "Forge-native subject type, for example `PullRequest` or `MergeRequest`."
+        },
+        "number": {
+          "type": "string",
+          "description": "Per-repo thread number, the commit sha for `kind: 'commit'`, or the forge-native id for `kind: 'other'`. Absent when the forge did not identify the thread; such a ref cannot be fetched or keyed until enriched."
+        },
+        "displayNumber": {
+          "type": "string",
+          "description": "Human-facing per-repo number, when it differs from `number`. Tangled identifies threads by AT-URI but shows numbers in its UI and webhooks."
+        },
+        "externalId": {
+          "type": "string",
+          "description": "Globally unique forge-native identifier, where one exists: a GitHub `node_id`, a GitLab global id, or an atproto record URI."
+        }
+      },
+      "required": [
+        "forge",
+        "instance",
+        "kind",
+        "repo"
+      ],
+      "description": "Reference to a thread. A thread `number` is unique only within its repo, so the repo is always carried alongside it.",
+      "x-forges-type": "ThreadRef"
+    },
+    "ThreadStack": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Forge-native stack id, where the forge names stacks."
+        },
+        "parent": {
+          "$ref": "#/definitions/ThreadRef",
+          "description": "The pull request this one is stacked on. Absent for the root of the stack."
+        }
+      },
+      "description": "Where a pull request sits in a stack of pull requests.",
+      "x-forges-type": "ThreadStack"
+    },
+    "ThreadState": {
+      "type": "string",
+      "enum": [
+        "open",
+        "closed",
+        "merged",
+        "unknown"
+      ],
+      "description": "Thread state. `'unknown'` is distinct from any real state and signals that the value was not present in the payload, so the caller may enrich it with `threads.get()`. Draft status is orthogonal; see `Thread.isDraft`.",
+      "x-forges-type": "ThreadState"
+    }
+  }
+}

package/dist/schema/ThreadKind.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "enum": [
+    "issue",
+    "pull_request",
+    "discussion",
+    "commit",
+    "other"
+  ],
+  "description": "Kind of thread. `'other'` holds forge-specific subjects with no shared kind (check suites, epics); `ThreadRef.typeRaw` names them.",
+  "x-forges-type": "ThreadKind",
+  "definitions": {}
+}